SSH Keys¶
SSH is the default method of accessing an Equinix Metal™ server. SSH keys can be associated with your account or project, and added to each server you provision. Equinix Metal also uses SSH keys as authentication for our SOS/OOB console.
Generating SSH Keys¶
To use SSH keys with Equinix Metal, first generate a public and private key pair on your local machine and then associate the public key with your Equinix Metal account or project.
Linux, Mac, and modern Windows versions can generate SSH keys using the ssh-keygen
command to generate a key-pair.
ssh-keygen -t ed25519
For older machines without Ed25519 support, RSA keys are supported with a recommended minimum 2048-bit key size.
ssh-keygen -t rsa -b 2048
You will get a series of prompts through the creation process.
When asked, press enter to accept the default location and key names, which is recommended if this is your first SSH key.
When prompted for a passphrase, it is not required 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. Press enter to leave it empty.
Once key generation is finished, your public key is located at:
/home/<name>/.ssh/<key-name>.pub
on Linux/Users/<name>/.ssh/<key-name>.pub
on MacC:\Users\<name>/.ssh/<key_name>.pub
on Windows
if you accepted the default location. You will upload this key to the Equinix Metal console. The other key file in the same directory, <key_name>
, is the private key. Do not share your private key.
Note - if you are on an older Windows version that does not include a built-in SSH server and client, you will need to download and configure a third-party application such as PuTTY to generate keys and SSH into your servers.
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 local machine, open the <key_name.pub>
file. 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_public_key> --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 <ssh_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": "<string>",
"key": "<ssh_public_key>"
}'
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": "<string>",
"key": "<ssh_public_key>"
}'
SSH Keys - Provisioning Servers¶
When you provision a server, all your user account SSH keys, team member's SSH keys, and Project SSH keys are added to it by default, providing authorized access to the server. It is possible to override this default and specify which keys to add when provisioning a new server.
When provisioning in the console, available SSH keys are displayed on the SSH Keys tab in the Optional Settings.
Select which keys to add to the server.
Note: If all keys (Project, Personal, and Collaborator) are unchecked, all keys will be added to the server by default. There is no way to provision in the Console without SSH keys. To provision without SSH keys, use the API.
To customize which SSH keys are included on a server when provisioning with the API, include the "user_ssh_keys"
or "project_ssh_keys"
parameters in your POST
request to the projects/{id}/devices
endpoint. These will override the default behavior of adding all SSH keys to the server and add only the SSH keys specified.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
"metro": "<metro_code>",
"plan": "<server_type>",
"operating_system": "<os_code>",
"user_ssh_keys": [
<uuid>
],
"project_ssh_keys": [
<uuid>
]
}'
Notable Body Parameters:
"user_ssh_keys"
- An array containing a list of UUIDs of your user account's SSH keys and team members SSH keys used to authorize access this server. These keys will also appear in the device metadata. The users must be members of the project or organization."project_ssh_keys"
- An array containing a list of UUIDs of the Project's SSH keys used to authorize access this server. These keys will also appear in the device metadata.
You can also add SSH public keys that are not uploaded and managed by Equinix Metal to a server by using the "ssh_keys"
body parameter. These keys are added to the server along with any keys defined by "project_ssh_keys"
and "user_ssh_keys"
, or in addition to the default behavior of adding all available SSH keys.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
"metro": "<metro_code>",
"plan": "<server_type>",
"operating_system": "<os_code>",
"ssh_keys": [
{
"key": "<ssh_public_key>",
"label": "<string>"
}
]
}'
Notable Body Parameter:
"ssh_keys"
- An array of SSH key objects that will be added to the server to authorize SSH access to it. These keys will also appear in the device metadata.
If no SSH keys are specified ("user_ssh_keys"
, "project_ssh_keys"
, and "ssh_keys"
are all empty lists or omitted), all available user SSH keys, Project SSH keys, and team member's SSH keys will be included. This is the default behavior.
Provisioning Without SSH Keys¶
To provision a server without SSH keys, you must explicitly include the "no_ssh_keys"
parameter in your POST
request to the projects/{id}/devices
endpoint.
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
"metro": "<metro_code>",
"plan": "<server_type>",
"operating_system": "<os_code>",
"no_ssh_keys": true
}'
Notable Body Parameter:
"no_ssh_keys"
- Boolean that overrides default behavior of attaching user, team member, and Project SSH keys to a server and provisions it without any authorized SSH access.
SSH Keys Post-Provisioning¶
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"
You can add SSH keys to your account or Project at any time, however keys added to your account or your Projects through the console or API are NOT automatically added to the servers. Equinix Metal does not keep any agent or process on provisioned servers to perform this action. To grant access, you have to add SSH keys to the server itself.
If you add a key that you want to use with provisioned servers, check the option to associate the new key with specific servers or all servers when you add it to the console. This option is also only available through the Equinix Metal console.
This does not authorize SSH access directly to the server, but it does allow the new SSH key to be used when logging into and using the SOS/OOB console. You can then use the SOS/OOB console to add your new SSH key to the authorized keys on the server.
Connecting with SSH¶
To SSH into your server, run the command:
ssh root@<your_public_ipv4>
Note: SSH password authentication is disabled by default on Equinix Metal servers.
Removing SSH Keys¶
You can remove SSH keys from your account in the Equinix Metal console from your user profile, on the SSH Keys tab. Click Delete next to the key you want to remove. The SSH key will not be added to any future servers that you provision.
The SSH key will not be added to any future servers that you provision.
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 or from your Projects through the console or API are NOT automatically deleted from servers. Equinix Metal does not keep any agent or process on provisioned servers to perform this action. To revoke access, you have to manually remove SSH keys from the server.