SSH Keys¶

Linux, Mac, and Windows 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 <default_location>:

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. If you selected the default location, your public key is located at /home/<name>/.ssh/<key-name>.pub on Linux, /Users/<name>/.ssh/<key-name>.pub on 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, /Users/<name>/.ssh/<key-name> on Mac, or C:\Users\<name>/.ssh/<key_name> on Windows, if you selected the default location. Do not share your private key.

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:

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:

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:

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "rsa-key-xxxxxx"
....
---- END SSH2 PUBLIC KEY ----

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

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 user profile, on the SSH Keys tab. Click + Add Key to add a new SSH Key to your account.

On your machine, if you're on windows, just open the <key_name.pub> file with a text editor like Notepad.

If you're on Linux type:

cat /home/<name>/.ssh/<key-name>.pub

On Mac, type:

cat /Users/<name>/.ssh/<key-name>.pub

Then copy and paste the contents into the Public Key field on the Portal. Name the key and click Add.

Once the SSH key has been added, it will appear in the list of SSH keys on your account. If you need to rename or update the key, click Edit.

You can add an SSH key to your user with the metal ssh-key create command. Send in the full SSH public key string to the --key flag and a name or other user-friendly description with the --label flag.

metal ssh-key create --key <ssh-rsa AAAAB3N...user@domain.com> --label <string>

If you need to update an SSH key, you can do so with the metal ssh-key update command. You can update either the --label, the --key, or both.

metal ssh-key update -i <SSH-key_UUID> --key <public_key> --label <string>

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>" \
"https://api.equinix.com/metal/v1/ssh-keys" \
-d '{
    "label": "my machine ssh key",
    "key": "ssh-rsa....."
} '

If you need to update an SSH key, send a PUT request to the /ssh-keys/{id} endpoint. You can update either the "label", the "key", or both.

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/ssh-keys/{id}" \
-d '{
    "label": "my machine ssh key",
    "key": "ssh-rsa....."
} '

You can add an SSH key to a Project on its Project Settings page, on the SSH Keys tab.

Once the SSH key has been added, it will appear in the list of SSH keys in the Project. If you need to rename or update the key, click Edit.

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>" \
"https://api.equinix.com/metal/v1/projects/{id}/ssh-keys" \
-d '{
    "label": "my machine ssh key",
    "key": "ssh-rsa....."
} '

If you need to update an SSH key, send a PUT request to the /ssh-keys/{id} endpoint. You can update either the "label", the "key", or both.

curl -X PUT \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/ssh-keys/{id}" \
-d '{
    "label": "my machine ssh key",
    "key": "ssh-rsa....."
} '

You can see which SSH keys are on a specific server from the Equinix Metal console in the server's detail page, on the SSH Keys tab.

The SSH keys that have been added to a server at provision-time can be retrieved from the CLI with the metal device get command with the --output flag to specify the JSON output. The list can be found in the ssh-keys object in the response.

metal device get -i <device_id> -o json

You can also get a server's SSH keys from the API by sending a GET request to the /devices/{id}/ssh-keys endpoint.

curl -X GET -H 'X-Auth-Token: <API_TOKEN>' \
"https://api.equinix.com/metal/v1/devices/{id}/ssh-keys"

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.

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

You can remove Personal SSH keys from your account in the Equinix Metal console from your user profile, on the SSH Keys tab. Click Delete on the key you want to remove. The SSH key will not be added to any future servers that you provision.

You can remove Project SSH keys from the Project Settings page, on the SSH Keys tab. Click Delete on the key you want to remove. The SSH key will not be added to any future servers that you provision in this Project.

You can remove an SSH key from your user account with the metal ssh-key delete command.

metal ssh-key delete --id <SSH-key_UUID>

The SSH key will not be added to any future servers that you provision.

In the API, SSH keys can be removed from your account by sending a DELETE to the /ssh-keys/{id} endpoint.

curl -X DELETE -H 'X-Auth-Token: <API_TOKEN>' \
"https://api.equinix.com/metal/v1/ssh-keys/{id}"