[[Include(WikiToC)]]
=== Configuring SSH Keys === #ConfiguringSSHKeys

SSH access to [wiki:/Architecture/Domains COSMOS domains] requires the use of public key authentication. If you try to connect using the username and password that you use for accessing the scheduler and status pages, you will receive the following message:

{{{#!shell-session
not_a_user@laptop:~$ ssh not_a_user@bed.cosmos-lab.org
not_a_user@bed.cosmos-lab.org: Permission denied (publickey).
}}}

You need to configure the SSH client on your computer to use a private key for connecting to COSMOS machines instead of a password. 

Additionally, the corresponding public key needs to be added to your COSMOS account. 

This page describes the procedure for:
* generating a public/private key pair
* configuring your SSH client to use the private key
* uploading the public key to your COSMOS account.

The instructions here are for specific SSH client software, if you use a different SSH client than those referenced here, please follow the documentation provided with that SSH client and use the instructions here for reference.

1. Select the OS of your computer '''

[[CollapsibleStart(Linux)]]
''NOTE: These instructions are NOT for Ubuntu running on Windows using Windows Subsystem for Linux (WSL).''

These instructions assume you will be using a standard command-line SSH client for linux. If you have not already done so, ensure that you have it installed by running the following commands in a command-line terminal:
{{{#!shell
sudo apt-get update
sudo apt-get install openssh-client
}}}

==== Generating keys
 Each distribution has their own location for the specific generation tools. These instructions are based on the  documentation for Ubuntu ([https://help.ubuntu.com/community/SSH/OpenSSH/Keys located here]). 

 To create your public and private SSH keys, open a command-line terminal and type:
{{{#!shell
ssh-keygen -t rsa
}}}
 You will be prompted for a location to save the keys, and a passphrase for the keys which we highly recommend using. This passphrase does not have to be the same as your COSMOS account password.
{{{#!shell-session
Generating public/private rsa key pair.
Enter file in which to save the key (...):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ...
Your public key has been saved in ...
Your public key is now available as .ssh/id_rsa.pub in your home folder.
}}}

 This process will generate and store a private key and a public key file. The private key will be stored in the file and location you specify when prompted, and the public key file will be named the same as your private key file but with a .pub extension.

[[BR]]
==== Uploading your public key to your COSMOS account
 To upload you public key to your cosmos account, do the following:
 1. Go to [https://wiki.cosmos-lab.org/cPanel/accountManagement/adminAuthKeys Profile] and sign in with your COSMOS username and password

 2. Click on "Change My Profile" option in the left side menu

 3. Click the "Choose File" button next to "Public key file"
 
 4. Navigate to where your '''public key file''' is stored (typically /home/your_username/.ssh)

 5. Select the .pub file corresponding to the key you wish to use for COSMOS access

 6. Click "Open"

 7. Click the "Update Profile" button

 As a side note, expect to see a default auto generated public key in the list (ends with @internal1). This is used for SSH access between machines inside the COSMOS network. Please do NOT delete this key.

 [[Image(ControlPanel.jpg, width=700)]]

[[BR]]
==== Configuring your SSH client
  Under normal circumstances, as long as the private key file is located in the /home/your_username/.ssh/ folder, the command line SSH client will use the correct key when connecting.
 To test your setup, open a command-line terminal and (replacing ''your_cosmos_username'' with your own COSMOS username) type:
{{{#!shell-session
ssh your_cosmos_username@gw.orbit-lab.org
}}}
 You should be prompted to enter your key file passphrase and be able to successfully connect.

 Type {{{exit}}} and press the Enter key to end the SSH session.

[[BR]]
==== Common issues and how to solve them
 * If you receive a message like the following:
{{{#!shell-session
The authenticity of host 'gw.orbit-lab.org (128.6.192.134)' can't be established.
ECDSA key fingerprint is SHA256:iLKtq2Z8wB3ADJdEyM1CwoU85gOeqIUyB4GOJ2YloQg.
Are you sure you want to continue connecting (yes/no)?
}}}
 This is a normal message that occurs when your computer connects via SSH to another that it has never connected to before or if the "fingerprint" of the other machine changed (due to replacement or reconfiguration). Simply type {{{yes}}} and connection will proceed normally.
[[BR]]
 * If you receive a message like the following:
{{{#!shell-session
Permission denied (publickey).
}}}
 Try connecting again but manually specifying the location where your private SSH key is stored as in the following example:
{{{#!shell-session
ssh -i /path_to_where_key_is_stored/private_ssh_key_name your_cosmos_username@gw.orbit-lab.org
}}}

[[CollapsibleEnd]]

[[BR]]

[[CollapsibleStart(Windows)]]
Select your SSH client:

[[CollapsibleStart(PowerShell)]]
These instructions assume that you are using the built-in SSH client provided in Windows !PowerShell.

==== Generating Keys
 1. Open a !PowerShell terminal.

 2. Enter the following command at the prompt:
{{{#!shell-session
ssh-keygen.exe
}}}
 Follow the prompts to generate your SSH key pair. For security reasons, we recommend entering a passphrase for your key. An example of the output you will see is shown below.
{{{#!shell-session
PS C:\Users\local_user> ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (C:\Users\local_user/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in C:\Users\local_user/.ssh/id_rsa.
Your public key has been saved in C:\Users\local_user/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:/sR9z7I0dW40cKcUabv2yv7VAAkLy+snm4tpt9UW6qg local_user@local-pc
The key's randomart image is:
+---[RSA 3072]----+
|        . .   .. |
|       . . o .o. |
|        o . oo.o.|
|         .   o+o.|
|        S   . oo+|
|       S . + .o=+|
|        + * +.+.=|
|      .o.@ . +.=o|
|     .Eo*oo  .==+|
+----[SHA256]-----+
}}}

==== Uploading your public key to you COSMOS account
 ''NOTE: Internet Explorer is not supported for Control Panel operations (including key upload)''

 To upload you public key to your cosmos account, do the following:
 1. Go to [https://wiki.cosmos-lab.org/cPanel/accountManagement/adminAuthKeys Profile] and sign in with your COSMOS username and password

 2. Click on "Change My Profile" option in the left side menu

 3. Click the "Choose File" button next to "Public key file"

 4. Navigate to where your '''public key file''' is stored (in the previous example it would be something like C:\Users\local_user\.ssh\id_rsa.pub)

 5. Select the public key file you wish to use for COSMOS access

 6. Click "Open"

 7. Click the "Update Profile" button

 As a side note, expect to see a default auto generated public key in the list (ends with @internal1). This is used for SSH access between machines inside the COSMOS network. Please do NOT delete this key.

 [[Image(ControlPanel.jpg, width=700)]]

[[BR]]
==== Configuring your SSH client

 Under normal circumstances, as long as the private key file is located in the C:\Users\local_user\.ssh\ folder, the command line SSH client will use the correct key when connecting.

 To test your setup, open a !PowerShell terminal and (replacing your_cosmos_username with your own COSMOS username) type:
{{{#!shell-session
ssh your_cosmos_username@gw.cosmos-lab.org
}}}

 You should be prompted to enter your key file passphrase and be able to successfully connect.

 If necessary, you can also manually specify the path to your private SSH key as follows:
{{{#!shell-session
ssh -i C:\Users\local_user\.ssh\id_rsa your_cosmos_username@gw.cosmos-lab.org
}}}

 Type exit and press the Enter key to end the SSH session.

[[CollapsibleEnd]]

[[CollapsibleStart(PuTTY)]]
These instructions assume that you are using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY] as your SSH client.

==== Generating Keys
 In PuTTY, the key generation is handled by a separate program named ''puttygen.exe''. If you installed PuTTY via the installer, there should be an icon for PuTTYgen in your Start menu, otherwise [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html download it from here].

 1. Open PuTTYgen

 2. Click the "Generate" button and follow the instructions in the "Key" section of the window

 || [[Image(puttygen01.png, 250px)]] || [[Image(puttygen02.png, 250px)]] ||

 3. Type a passphrase of your choice in the "Key passphrase" and "Confirm passphrase" fields. This passphrase does not have to be the same as your COSMOS account password.

 || [[Image(puttygen03.png, 250px)]] ||

 4. Click the "Save private key" button

 || [[Image(puttygen04.png, 250px)]] ||

 5. Save the private key file somewhere you will remember on your computer. Do not share this key with anyone!

 6. After saving the private key file, right-click in the big text box labeled "Public key for pasting into OpenSSH authorized_keys file" and click "Select All" from the popup menu to highlight the entire public key

 || [[Image(puttygen05.png, 250px)]] ||

 8. Right-click again in the same big box and click "Copy" from the popup menu

 || [[Image(puttygen06.png, 250px)]] ||

 9. Open Notepad from your Start menu

 10. Paste what you just copied from PuTTYgen into Notepad. The contents should start with {{{ssh-rsa}}} and end with something like {{{rsa-key-20180621}}} (the same as the "Key comment" field in PuTTYgen)

 11. Save this file somewhere you will remember on your computer. This is your public key file.

 12. Close PuTTYgen

[[BR]]
==== Uploading your public key to you COSMOS account
 ''NOTE: Internet Explorer is not supported for Control Panel operations (including key upload)''

 To upload you public key to your cosmos account, do the following:
 1. Go to [https://wiki.cosmos-lab.org/cPanel/accountManagement/adminAuthKeys Profile] and sign in with your COSMOS username and password

 2. Click on "Change My Profile" option in the left side menu

 3. Click the "Choose File" button next to "Public key file"

 4. Navigate to where your '''public key file''' is stored (the file you saved with Notepad in the previous section)

 5. Select the public key file you wish to use for COSMOS access

 6. Click "Open"

 7. Click the "Update Profile" button

 As a side note, expect to see a default auto generated public key in the list (ends with @internal1). This is used for SSH access between machines inside the COSMOS network. Please do NOT delete this key.

 [[Image(ControlPanel.jpg, width=700)]]

[[BR]]
==== Configuring your SSH client

 1. Open PuTTY.

 || [[Image(putty01.png, 250px)]] ||

 2. Navigate through the left side menu tree to "SSH" then "Auth".

 || [[Image(putty02.png, 250px)]] ||

 3. Click the "Browse" button next to the "Private key file for authentication" field.

 || [[Image(putty03.png, 250px)]] ||

 4. Navigate to where you saved your '''private key file''' in the previous section and select it.

 5. Navigate through the left side menu tree back to "Session".

 || [[Image(putty04.png, 250px)]] ||

 6. Enter a name for this connection in the "Saved Sessions" field and click the "Save" button.

 || [[Image(putty05.png, 250px)]] ||

 7. Now whenever you open PuTTY, select the session name you gave in the previous step and click "Load", this will load the private key file automatically so you do not have to repeat the prior steps each time (as long as you do not move it to a different folder on your computer).

 || [[Image(putty06.png, 250px)]] ||

 8. Type {{{your_cosmos_username@gw.orbit-lab.org}}} (replacing ''your_cosmos_username'' with your own COSMOS username) into the "Host Name (or IP address)" field and click the "Open" button. You should be prompted to enter your key file passphrase and be able to successfully connect.

 || [[Image(putty07.png, 250px)]] ||

 9. Type {{{exit}}} and press the Enter key to end the SSH session.

[[CollapsibleEnd]]

[[CollapsibleEnd]]

[[BR]]

[[CollapsibleStart(Mac)]]

Mac OS has a native command line ssh client that can be used to remotely log into consoles. From the Finder select Applications -> Utilities -> Terminal to open a command line terminal.

==== Generating keys
Generate the public and private keys using the following command
{{{
ssh-keygen -t rsa
}}}

Follow the prompt to save the keys in the default location, use a passphrase for additional security. Once your keys are saved successfully, a 'randomart' will be generated.
{{{#!shell-session
your_username@Macintrash ~ % ssh-keygen -t rsa -C mac
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/your_username/.ssh/id_rsa): 
Created directory '/Users/your_username/.ssh'.
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /Users/your_username/.ssh/id_rsa.
Your public key has been saved in /Users/your_username/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:sclFUKMVPUAUBEk+Qa3MZhLv3qfo/BWY+B5huCajS5U mac
The key's randomart image is:
+---[RSA 2048]----+
|       o*X%=     |
|      ...=..o    |
|       ==..  .   |
|      .oBO o     |
|      E=S = .    |
|     .  .+ . .   |
|    . o.o.o .    |
|   . . =.o.o.    |
|    o. .+.+o     |
+----[SHA256]-----+
}}}

[[BR]]
==== Uploading your public key to you COSMOS account
 To upload you public key to your cosmos account, do the following:
 1. Go to [https://wiki.cosmos-lab.org/cPanel/accountManagement/adminAuthKeys Profile] and sign in with your COSMOS username and password

 2. Click on "Change My Profile" option in the left side menu

 3. Click the "Choose File" button next to "Public key file"
 
 4. Navigate to where your '''public key file''' is stored (typically /Users/your_username/.ssh)

 5. Select the .pub file corresponding to the key you wish to use for COSMOS access

 6. Click "Open"

 7. Click the "Update Profile" button

 As a side note, expect to see a default auto generated public key in the list (ends with @internal1). This is used for SSH access between machines inside the COSMOS network. Please do NOT delete this key.

 [[Image(ControlPanel.jpg, width=700)]]

[[BR]]
==== Configuring your SSH client
 Under normal circumstances, as long as the private key file is located in the /Users/your_username/.ssh/ folder, the command line SSH client will use the correct key when connecting.

 To test your setup, open a command-line terminal and (replacing ''your_orbit_username'' with your own ORBIT username) type:
{{{
ssh your_orbit_username@gw.orbit-lab.org
}}}
 You should be prompted to enter your key file passphrase and be able to successfully connect.

 Type {{{exit}}} and press the Enter key to end the SSH session.

[[CollapsibleEnd]]

=== Common issues and how to solve them

==== If you deleted the "@internal1" key from your profile

 As long as you have at least one public key configured in your profile, use your SSH client to connect to {{{gw.orbit-lab.org}}} and run the following commands there. You do not need to make a reservation in the scheduler for this.

 '''Make sure you are connected to gw.orbit-lab.org and running all of the following commands on gw.orbit-lab.org!
{{{#!shell-session
rm ~/.ssh/id_rsa
rm ~/.ssh/id_rsa.pub
ssh-keygen -t rsa -C "@internal1"
}}}

 Press 'Enter' at every prompt so that the default filename (id_rsa) and no password is used.

 Then type the following command:
{{{#!shell-session
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
}}}

 The internal key should now be restored.

==== Warning about "authenticity of host can't be established"

 If you receive a message like the following:
{{{ #!shell-session
The authenticity of host 'gw.orbit-lab.org (128.6.192.134)' can't be established.
ECDSA key fingerprint is SHA256:iLKtq2Z8wB3ADJdEyM1CwoU85gOeqIUyB4GOJ2YloQg.
Are you sure you want to continue connecting (yes/no)?
}}}

 or

  || [[Image(putty_alert.png, 250px)]] ||

 This is a normal message that occurs when your computer connects via SSH to another that it has never connected to before or if the "fingerprint" of the other machine changed (due to replacement or reconfiguration). Simply type {{{yes}}} or click "Yes" and connection will proceed normally.
[[BR]]