Main

How to use BGL

Setting up and using SSH keys on Argonne BGL

Reusable password access are not allowed for remote access to BGL. The only option that is available is SSHv2 keys. Argonne BG/L SSH Policy page.

SSH uses keys for authentication. This happens at a host level, and is why you may occasionally be asked if you want to save a key, or notified that a host key has changed. However, SSH also can use keys to authenticate users. Without going into the details of the protocol, this document will lay out how you can generate and install keys, use agents, and reduce the number of times you need to type a password.

There are two files associated with a SSH user key (typically referred to as a key pair):

• The private key file. This file should be carefully protected. It should be readable only by you and stored only on a secure computer (typically your laptop or desktop computer). Private key files should not stored on BGL.
• The public key file. This file is named the same as the private key file but with a .pub extension. It does not need to be as securely protected as the private key file. The contents of the public key file associated with the key you wish to use for BGL access should be placed inside the ~/.ssh/authorized_keys file located on BGL.

Below are the steps necessary to set up your ssh key access. In order to allow key-only access to BGL, you will need to have at least one SSH user key pair. If you don't have a key pair, start with the Generate keys step. If you already have a key pair, you can skip to Install the authorized public key step.

WE REQUIRE THE USE OF A PASSPHRASE.

During the process of generating a key, you will be asked for a passphrase. Please select a strong passphrase. What consitutes a strong passphrase is detailed in the SSH Passphrases section of the SSH policy document.

There are a very limited number of circumstances where a key without a passphrase is acceptable. If you have a strong need to use one, please contact the systems team prior to installing it. The reason for not allowing passwordless ssh keys is that with a copy of your private key, if it has no passphrase, a person can ssh as you to any host to which you've allowed access without knowing a password or passphrase.

Steps to setting up keys for access to BGL

Overview:

1. Generate keys
2. The support team installs your authorized public key
3. Test your SSH installation
4. Use an SSH Agent

Details

1. Generate keys:

   • If your local machine is a Linux, MacOS X, Cygwin, or other Unix based computer:

     To generate a key pair use the command "ssh-keygen" (see the example below). This command will create and store keys in your ~/.ssh directory. It will overwrite any existing keys (unless you specify a different filename with the -f option).

     To generate an RSA key, type:

     ssh-keygen -t rsa -b 4096

     You will be asked for a passphrase. Please carefully read the comments on passphrase selection above before selecting your passphrase. The default file names for an RSA key are id_rsa (private key) and id_rsa.pub (public key).

   • If your local machine is a Windows computer.

     Note: if you use cygwin for SSH, see the unix instructions above.

     If you use SecureCRT, there is a version of SecureCRT that supports agents, you will need that version.

     Generate your key by clicking "Tools", then "Generate Public Key". Follow the prompts (we recommend an RSA key, despite what the text above the selection box says). Choose a strong passphrase (please carefully read the comments on passphrase selection above before selecting your passphrase). Use 4096 for the key length. Important: make a note of where it installs the key. It is probably something like:

     C:\Documents and Settings\USERNAME\Application Data\VanDyke\Identity

     If you upgraded from an old version, it might be:

     C:\Documents and Settings\USERNAME\Application Data\Van Dyke Technologies\Identity

     Type "Yes" to the global public key question.

2. The support team installs authorized public key:

   You will not be able to install your authorized public key on BGL without assistance. In order to install your key, you must take the following steps:

   1. Send us your SSH public key by sending email to support@bgl.mcs.anl.gov with your public key file attached to the email. Please do not include the file in your mail, but send it as an attachment. Once support has received the key, they will upload it to the account database and send you email.

      Please do NOT attempt to verify your ssh key until you receive email from BGL support stating that your ssh key has been received and uploaded to the database. The help desk is unable to verify your key until that has occurred.

   2. Once you have received the email from support saying that they have your key, call the Help Desk at (630) 252-6813 to verify your identity and key.

   3. Once your key and id have been verified, the help desk will notify the support team. They will move the key to your authorized_keys file on BGL and notify you thru email that your account is ready to be used.

   If you already have a SSHv2 key installed set up on BGL, you can use the following methods to install your key:

   • For a Linux, MacOS X, Cygwin, or other Unix based local computer:

     At this point, you should have an id_rsa.pub file in your ~/.ssh directory. That file contains the public key. In order for you to tell BGL that you want to authorize the associated private key to identify you, you need to place that public key on BGL in the ~/.ssh/authorized_keys file.

     To add a key to your authorized keys file, you can do the following:

     1. on your local system:

        cat ~/.ssh/id_rsa.pub

     2. on BGL:

        edit the ~/.ssh/authorized_keys file (or do a 'cat >> ~/.ssh/authorized_keys') and cut and paste the output from the cat of the public key file.

     Or you can use a simple one line command (replacing 'username' with your BGL username), executed on your local machine:

        cat ~/.ssh/id_rsa.pub | ssh username@bgl.mcs.anl.gov 'cat - >> ~/.ssh/authorized_keys'
             

   • For SecureCRT :

     Installing your SecureCRT keys onto BGL is somewhat tricky because SecureCRT stores your public key in a funky format. To get it into the format OpenSSH recognizes:

     1. Log on to BGL using SSH and Unix password authentication.
     2. On the local machine, use Notepad.exe to open the Identity.pub file that was created with the Key Generation wizard.
     3. With the Identity.pub file opened in the Notepad application, open the Edit menu and choose Select All. Once everything is selected, open the Edit menu again and select Copy.
     4. On BGL, complete the following steps:

        1. cat > ~/.ssh/windows-machine-name.ident (where "windows-machine-name" is the name of your machine)
        2. Click on the SecureCRT paste button to paste the contents of the Clipboard (which should now contain the contents of your Identity.pub file).
        3. Issue a CTRL+D to close the Identity.pub file.
        4. Convert the key to one that OpenSSH will recognize using the following command:

           ssh-keygen -i -f ~/.ssh/windows-machine-name.ident >> ~/.ssh/authorized_keys

     5. On the local machine, setup SecureCRT to use the key:

        1. Click "File" then "connect", and for each existing entry, in the list (or for new ones you add) click the "Properties" button (it looks like a hand holding a card).
        2. In the Authentication section under "Connection", change "Primary" to be "PublicKey". Choose "Properties" and make sure it's using your global file.
        3. Click "Options", "Global Options", and under SSH2 heading, check both boxes in the "Agent" section.

     The first SecureCRT session you open will ask the passphrase for the key you generated, and any subsequent ones will not (as long as SecureCRT is running.)

3. Test your SSH installation:

   At this point, if you were to ssh from your local machine to BGL, instead of being asked for a password, you'll see something like this:

           Enter passphrase for key '/homes/<username>/.ssh/id_rsa':
        

   What you type at that prompt is not your Unix password. It is the passphrase you used when you created your key. That passphrase is not stored anywhere. You are no longer using your Unix password.

   In this mode of operation, you will be typing your passphrase each time you log in. There is a way, however, for you to reduce the number of times you need to type the passphrase.

4. Use an SSH Agent:

   If you run an ssh-agent, you can tell it to remember the passphrase for a key while it is running.

   • If your local machine is a Linux or other Unix based computer:

     If your desktop is a Unix-based workstation running X-Windows, it is possible to set it up so that when you log onto the machine, an SSH agent is launched automatically. This is true of all MCS linux workstations. If your machine is not configured to do that, you can launch one by running:

     eval `ssh-agent`

     To add your keys to the agent:

     ssh-add

     You will be asked for the passphrase for your .ssh/id_rsa key.

     Once you have done an ssh-add of a key, you can ssh to other machines that have the associated public key stored in the authorized_keys file without typing your ssh passphrase.

     MacOS users can use GUI tools such as the following to manage keys and agents:

     • SSH Agent
     • SSHKeychain
     • sshLogin

   • If you are using SecureCRT on your local computer:

     If you followed the steps in the section on setting up your ssh keys for Windows, then SecureCRT should be set up to automatically run an ssh-agent. In this case, the first SecureCRT session you open will ask the passphrase for the key you generated, and any subsequent ones will not (as long as SecureCRT is running.)

For more information on using SSH and how to obtain a version for your local machine, please read the MCS Offsite Access document. This document also contains information on why SSH is necessary and pointers to other useful sources of information on ssh and scp.