Project 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.
A Project SSH key is specific to a single project, which will be included by default on servers deployed into a particular project. This option is useful if you don’t want to use a personal SSH key on a shared server.
Generating a Project SSH Key¶
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 Project.
To generate an SSH key pair, use the ssh-keygen command on Linux, Mac, and modern Windows machines. Note: We recommend that you specify a unique SSH key name and location to be used for the key pair. This will ensure that you do not overwrite any existing SSH keys.
ssh-keygen -t ed25519 -f ~/.ssh/<proj_key_name>
For older machines without Ed25519 support, RSA keys are supported with a recommended 2048-bit minimum key size.
ssh-keygen -t rsa -b 2048 -f ~/.ssh/<proj_key_name>
The public key is named <proj_key_name>.pub. You will upload this key to the Equinix Metal console. The other key file in the same directory, <proj_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 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": "<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>"
} '
Project 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 Project 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 Project SSH keys are included on a server when provisioning with the API, include the "project_ssh_keys" parameter in your POST request to the projects/{id}/devices endpoint. This 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>",
"project_ssh_keys": [
<uuid>
]
}'
Notable Body Parameter:
"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", 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.
Project 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 Project at any time, however keys added to 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.
Removing Project SSH Keys¶
You can remove Project SSH keys from the Project Settings page, 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 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 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.