Skip to content

SSH Keys

SSH keys are one of the most secure ways to access a web server, since it requires authentication beyond a simple password. While each new Equinix Metal™ server has a root password assigned, it is removed from the customer portal after 24 hours. You can either add a new root password to the server, or you can use SSH to log in.

SSH keys are generated on your local machine, generating a public key and a private key. When you place your public key on your Equinix Metal server, you can connect to it from the local machine containing the private key.

Generating SSH Keys

Linux, Mac, and the more recent versions of Windows 10 have can generate SSH keys using ssh-keygen. Open a command line and type:

ssh-keygen -t rsa

The -t rsa flag will generate an RSA key-pair.

You will get a series of prompts through the creation process.

Enter file in which to save the key (/home/<name>/.ssh/id_rsa):

for Linux and Mac, or

Enter file in which to save the key (C:\Users\<name>/.ssh/id_rsa)

on Windows.

Press enter to accept the default location, which you can use if this is your first SSH key. The next prompt is:

Enter passphrase (empty for no passphrase):

A passphrase is not required and you can press enter to leave it empty, but it will provide an extra layer of security. If you set a passphrase, it will be required every time you use SSH to access your server.

Once you have finished, two files are generated at the location you specified (or the default location). If you selected the default, your public key is located at /home/<name>/.ssh/<key-name>.pub on Linux or Mac, or C:\Users\<name>/.ssh/<key_name>.pub on Windows. The public key is the one that you need to upload to Equinix Metal.

The other key file is the private key, located at /home/<name>/.ssh/<key-name> on Linux or Mac, or C:\Users\<name>/.ssh/<key_name> on Windows, if you selected the default location. Do not share your private key.

The PuTTY Way (Windows)

If you are running an older version of Windows, you may need to use PuTTY to generate SSH keys. First, download PuTTY. The two binaries you will need are:

  • PuTTY (the SSH and Telnet client itself)
  • PuTTYgen (an RSA and DSA key generation utility)

Next, open PuTTYgen.exe which will look like this:

PuTTY key Generator 1

You can change the parameters for your key, even though the default ones are just fine. When you’re ready, click Generate.

In order to create a random key, you will be asked to move the cursor around a small empty area on the window. This randomness is called entropy and is used to create keys in a secure way that cannot be reproduced by others.

After a few seconds, once the keys are ready, you will be presented with this view:

PuTTY key Generator 2

Click the Save private key button, name it whatever you like and choose a secure location to save the key with the extension ".ppk".

Repeat the same thing after clicking on Save public key. This time, make sure to give it an extension like ".txt", so you can open it later in a regular text editor.

Note! If you open the public key text file you just saved, you will probably see that it contains something that looks like the following:


Comment: "rsa-key-xxxxxx"



Why PuTTY saves it in this format is unclear, but it is not an accepted form of the public key.

So, for that reason, you might want to copy whatever the Putty Generator shows on the Public key window and paste it on the document, after deleting everything that was there before.

It should look like: ssh-rsa AAAA............== rsa-key-xxxxxxx

Connecting with SSH

To SSH into your server from Mac, Linux, and newer versions of Windows 10, run the command:

ssh root@<your_Public IPv4>

If you are using PuTTY on Windows, run the PuTTY.exe binary downloaded earlier go to "Data" under "Connection", and add root in the field of the username.

Go to Authentication, under SSH, and click the Browse button, to add the private SSH key created earlier.

PuTTy login 1

Now go to Session, enter the public IP address of your server, give a name to the session, and click Open.

PuTTy login 2

Personal Keys vs Project Keys

Equinix Metal has two types of SSH Keys, personal keys and project keys.

A personal key will be included on all new servers in the projects that you own, or of which you are a collaborator.

You can also choose to create and manage a key that is specific to a single project, which will be included by default on servers deployed into a particular project. This 2nd option is useful if you don’t want to use a personal key that you leverage in lots of places on a shared server.

Adding Your SSH Key to Your Account

Once you have SSH keys set up on your local machine, you can add your public key to your Equinix Metal account.

SSH Key management is in your Personal Settings, on the SSH Keys tab. Click + Add Key to add a new SSH Key to your account. Open the <> file and paste its contents into the Key field. Name the key and click Add.

Adding SSH Keys with the API

You can add a public key to your account by sending a POST request to the /ssh-keys endpoint of the Equinix Metal API.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"" \
-d '{
    "label": "my machine ssh key",
    "key": "ssh-rsa....."
} '

Adding an SSH Key to your Project

You can add an SSH key to a Project on its Project Settings page, on the SSH Keys tab. This is also where you can find the list of all the project-level SSH keys (if any).

To add an SSH key to a project through the API, send a POST request to the /projects/{id}/ssh-keys endpoint.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"{id}/ssh-keys" \
-d '{
    "label": "my machine ssh key",
    "key": "ssh-rsa....."
} '

Getting Your Key(s) on Your Server(s)

We use our cloud-init service to add all the selected keys (Personal + Project specific + Collaborator) onto each new server at provision time. So as soon as your server is deployed, you can access it via SSH.

Any keys you (or your collaborators) add after a server is provisioned won’t be available on the machine automatically. If you add a key that you want to be able to use to access your existing servers, you need to use the option to associate the new key with specific servers when it is created. This option is also only available through the Equinix Metal console.

After the new key is added in the console, you need to force add it to your server(s). Use our SOS service to login with (root + pw) and manually add the new key on the authorized_keys file.

Managing SSH Keys

You can see the list of SSH Keys on your account in the Equinix Metal console from your Personal Settings, on the SSH Keys tab. To list the SSH keys on your account from the API, send a GET request to the /ssh-keys endpoint.

You can see a list of the SSH Keys on a project from the Project Settings page, on the SSH Keys tab. To list all of the SSH on a Project, send a GET request to the /projects/{id}/ssh-keys endpoint.

If you need to see what SSH keys are on a specific server, you can see them from the Equinix Metal console in the server's detail page, on the SSH Keys tab. You can also get a server's SSH keys from the API by sending a GET request to the /devices/{id}/ssh-keys endpoint.

Removing SSH Keys

You can remove SSH keys from your account in the Equinix Metal console from your Personal Settings, on the SSH Keys tab, and from a project from the Project Settings page, on the SSH Keys tab.

In the API, SSH keys can be removed from your account by sending a DELETE to the /ssh-keys/{id} endpoint. The {id} parameter is the UUID of the SSH key, which you might have to retrieve from getting a list of your account's keys from /ssh-keys or a list of your project's keys from /projects/{id}/ssh-keys.

Keys removed from your account and projects through the console or API are not automatically deleted from servers. You have to remove them manually from the server itself.