Access Your VM Instance Using SSH

Once you have created a VM Instance using Horizon, you can access this VM Instance through a secure shell (SSH) using an SSH key pair. The following tutorial will walk you through connecting to your VM Instance through SSH using Linux or macOS.

If you have several users that require access to a single instance, you may request they extract and provide you with their public key, which you may add to your instance's /home/cades/.ssh/authorized_keys file. Doing so grants access, as the user cades, to that instance. If desired, you may create specific local accounts, with limited sudo roles, etc. rather than use the cades user account.

Windows users will have to install an SSH client on their machine, and the CADES team recommends PuTTY for this purpose. The CADES team has compiled a separate tutorial for Windows/PuTTY users, linked below.

📖   How to: Access VM Instances Using PuTTY (Windows)

If you would like to access your VM Instance over SSH from outside of the ORNL network, you must first create a firewall (SAFER) exception. All local (within the ORNL network) SSH connections are permitted by default. Request a SAFER exception with source 'VISITORS' and your VM(s) as destination.

Add SSH Keys to an Instance

The first step to adding a key pair is actually to check for existing key pairs on your local machine. If no key pairs exist, then you can generate a new key in the Horizon web GUI.

If you do have an existing key pair on your machine, then you can import the public key using the Horizon web GUI. Alternatively, you can create a new (additional) key for your Instance and use a config file to manage your SSH credentials.

Check for Existing Key Pairs

1. Open a Bash terminal.
2. Execute ls -al ~/.ssh.
3. Check the results of the directory listing.

If the directory listing is empty or the directory is not found, then you do not have an existing SSH key and you should follow the procedure outlined in Generate a New Key Pair.

If the directory contains one of the files listed below, then you do have an existing SSH key, and you can import the public key into your Instance using the Horizon Web GUI by following the procedure outlined in Import Existing Key.

• id_rsa.pub
• d_dsa.pub
• id_ecdsa.pub
• id_ed25519.pub

Generate a New Key Pair

Generate the keys

1. Navigate to the Horizon web interface at https://cloud.cades.ornl.gov/.
2. Log in with your UCAMS credentials.
   • Domain: ornl
   • Username: Your three-letter UCAMS ID
   • Password: Your UCAMS password
3. Navigate to Project → Compute → Access & Security → Key Pairs.
4. In the Key Pairs screen, click the + Create New Pair button.
   
5. In the resulting dialog, name your Key Pair, and click Create Key Pair when you're finished.
   
6. The private key will be downloaded to your local machine as a .pem file. The public key will be stored in OpenStack.
7. Place the downloaded private key in ~/.ssh/, e.g., ~/.ssh/blackmesakey.pem.
8. Secure the private key by setting the permissions to 600 in a Bash terminal.
   $ chmod 600 ~/.ssh/blackmesakey.pem.

📝 Note: Having completed the procedure above, you can now connect to your Instance via SSH using a long-form login (instructions) or you can take these newly generated keys and place them in your local system's default files (instructions).

Key locations for Linux and macOS:

• Private key should be ~/.ssh/id_rsa.
• Public key should be ~/.ssh/id_rsa.pub.

📝 Note: Since we are generating new keys, these files (and the /.ssh/ directory) may not exist on your local machine.

Import Existing Key

If you have an existing key pair that you would like to also use for your OpenStack Project, then you can import the public key using the Horizon web GUI.

1. Navigate to the Horizon web interface at https://cloud.cades.ornl.gov/.
2. Log in with your UCAMS credentials.
   • Username: Your three-letter UCAMS ID
   • Domain: ornl
   • Password: Your UCAMS password
3. Navigate to Project → Compute → Access & Security → Key Pairs.
4. In the Key Pairs screen, click the Import Key Pair button.
5. In the resulting dialog, enter a key pair name in the Key Pair Name field.
6. Copy your public key from the file (e.g., ~/.ssh/id_rsa.pub) on your local machine.
7. Paste the public key in the Public Key text box.
8. Click the Import Key Pair button.
   
9. Confirm your newly imported key appears in the Key Pair list.

Connect to Your VM Instance Using SSH

All VM Instances have SSH access enabled by default. Use your key pair and the user name "cades" for authentication. SSH to your Instance using the Key Pair you configured above.

Find Your Instance's IP

The IP address of your VM instance is shown in the Instances tab in the Horizon web GUI.

1. Navigate to Project → Compute → Instances.
2. From the Instances screen, you can copy the IP address for the desired VM Instance.
   

Connect to Your Instance

Once you have determined the IP address of your VM Instance and placed your keys in ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub, you can connect using a simple SSH command where "cades" is always the user.

Standard login

1. Open a Bash terminal.
2. Execute ssh cades@128.219.186.19.
   • Replace 128.219.186.19 with the IP address of your own Instance.
3. You should now be connected to your VM Instance via SSH.
   • Use the Bash terminal to install your software-stack and perform work.
   • You can also add user credentials to your VM Instance to grant access to other users.

📝 Note: In a newly created Instance, "cades" is the only user name that will correctly authenticate over SSH (using an SSH key pair). A user can add more users, and add public keys for each, once logged in as "cades" (instructions).

Long-form login

If you prefer to specify your key location during login (e.g., you downloaded your key from the Horizon web GUI), you can use a long-form SSH login.

1. Open a Bash terminal.
2. Execute $ ssh -i ~/.ssh/blackmesakey.pem cades@128.219.186.19.
   • Replace ~/.ssh/blackmesakey.pem with the file path of your key.
   • Replace 128.219.186.19 with the IP address of your own Instance.
3. You should now be connected to your VM Instance via SSH.
   • Use the Bash terminal to install your software-stack and perform work.
   • You can also add user credentials to your VM Instance to grant access to other users.

📝 Note: In a newly created Instance, "cades" is the only user name that will correctly authenticate over SSH (using an SSH key pair). A user can add more users, and add public keys for each, once logged in as "cades" (instructions).

Extract Public Key

If you have several users, you can share your public key with them. New users must login using the username 'cades' to gain access to the instance, or you can create another user account for them. Once a user extracts the .pub file they can safely share with another OpenStack user. The receiving user can add that public key to the instance's /home/cades/.ssh/authorized_keys file.

To extract the public key from the private key:

openssl rsa -in privkey.pem -pubout > key.pub

In this way, through exchanging public keys, users can control who has SSH access to their instances.

Users should refrain from insecurely sending someone .pem files as they contains both public and private keys.

Related Tutorials

• Add More Users to VM Instances
• Access VM Instances Using PuTTY (Windows)
• Access Your VM Instances Using Horizon