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 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
Personal Keys vs Project Keys¶
Equinix Metal has two types of SSH Keys, Personal SSH keys and Project SSH keys. A personal key will be included on all new servers in the projects that you own, or of which you are a collaborator.
A Project SSH key 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 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....."
} '
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.
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....."
} '
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.
To see what keys are on a provisioned server:
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"
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.
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.
Now go to Session, enter the public IP address of your server, give a name to the session, and click Open.
Removing SSH Keys¶
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}"
Note: 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.