Connecting with SSH
All NERSC computers (except HPSS) are reached using either the Secure Shell (SSH) communication and encryption protocol (version 2) or by Grid tools that use trusted certificates.
HPSS can be accessed securely with ftp or hsi, via the use of encrypted tokens. Please see the HPSS pages for a description of this procedure.
Secure Shell (SSH)
SSH (Secure Shell) is an encryted network protocol used to log into computers over an unsecured network. On UNIX/LINUX/BSD type sytems, SSH is also the name of a suite of software applications for connecting via the SSH protocol. The SSH applications can execute commands on a remote machine and transfer files from one machine to another. All communications are automatically and transparently encrypted, including passwords. Most versions of SSH provide login (ssh, slogin) a remote copy operation (scp), and many also provide a secure ftp client (sftp). Additionally, SSH allows secure X Window connections.
Run ssh on your local workstation, specifying the remote destination machine as follows:
myhost% ssh firstname.lastname@example.org
Password + OTP: enter NIM password for user elvis, immediately followed by the 6-digit one-time password
NOTICE TO USERS
... (message truncated for this purpose)
In the above, a NERSC user named "elvis" connects via a workstation named "myhost" to the system named "cori".
Passwordless logins and file transfers via sshproxy
You can use SSH to set up a convenient environment for connecting and copying files remotely without being prompted for a password each time. We give the basic outline for setting this up below; if you need further help please contact your system administrator.
NERSC no longer allows public/private key pairs, but the sshproxy tool can allow a user to generate a key that is valid for 24 hours. Once you have obtained a key, you can use it to ssh to NERSC systems (e.g., Cori, Denovo, Genepool, PDSF, DTN, ...) without further authentication until the key expires.
The sshproxy service uses a RESTful API for requesting keys. NERSC provides a bash client script that you can use from the command line on a Unix-like computer. A python script will be also available. A Windows client that supports PuTTY will be available soon.
Installing the Client
On Unix-like machines (macOS included), you can download the bash client sshproxy.sh from a project directory:
$ scp email@example.com:/project/projectdirs/mfa/NERSC-MFA/sshproxy.sh .
where myusername is your NERSC login ID.
The sshproxy client, without any arguments, will use your local username, and obtain an ssh key with the default lifetime (24 hours). The private and public key will have the names 'nersc' and 'nersc-cert.pub," and will be stored in your ~/.ssh directory.
Run the sshproxy.sh script from where you installed it. For example, if the script is in your current directory, type:
The script will prompt you to enter your password and OTP, in the same manner as you would do to ssh to a NERSC system with MFA:
Enter your password+OTP:
Enter your NIM password immediately followed by OTP as a single string, as before. Upon successfully authenticating, the client will install an ssh key and display a message showing the path to the key pair installed on your local computer and the expiration date and time for the keys. By default, the name of the files will be ~/.ssh/nersc and ~/.ssh/nersc-cert.pub (you can change the name with a command-line argument).
Enter your password+OTP:
Successfully obtained ssh key /Users/wyang/.ssh/nersc
Key /Users/wyang/.ssh/nersc is valid: from 2018-08-30T12:24:00 to 2018-08-31T12:25:52
You will see three ssh key files (private and public keys, and a certificate containing the corresponding public key) installed in the ~/.ssh directory on your computer:
$ ls -l ~/.ssh/nersc*
-rw------- 1 wyang wyang 3179 Aug 30 12:25 /Users/wyang/.ssh/nersc
-rw------- 1 wyang wyang 1501 Aug 30 12:25 /Users/wyang/.ssh/nersc-cert.pub
-rw------- 1 wyang wyang 1501 Aug 30 12:25 /Users/wyang/.ssh/nersc.pub
The above example shows that an ssh key pair has been created on your local machine. With these keys, you can ssh to NERSC machines without further authentication until these keys expire.
Checking Certificate Expiration
You can check the expiration date and time of an existing ssh key pair. If the ssh key certificate file is ~/.ssh/nersc-cert.pub, run the following command on your local computer:
$ ssh-keygen -L -f ~/.ssh/nersc-cert.pub | grep Valid
Valid: from 2018-08-30T12:24:00 to 2018-08-31T12:25:52
Please note that the times printed are local time (your time), not NERSC time (Pacific Time).
Using sshproxy Keys
You can use the keys you get from the sshproxy to login to NERSC systems by specifying the key file on the command line. For example, to login to cori.nersc.gov with a key named 'nersc':
$ ssh -i ~/.ssh/nersc cori.nersc.gov
This will allow you to login without having to authenticate again.
sshproxy Command-line Options
sshproxy.sh has several command-line options to override its default behavior. You can run 'sshproxy.sh -h' to get a help message.
$ ./sshproxy.sh -h
Usage: sshproxy.sh [-u <user>] [-s <scope>] [-o <filename>] [-U <server URL>]
-u <user> Specify remote username (default: <your_login_name>)
-o <filename> Specify pathname for private key (default: /Users/<your_login_name>/.ssh/nersc)
-s <scope> Specify scope (default: 'default')
-a Add key to ssh-agent (with expiration)
-U <URL> Specify alternate URL for sshproxy server (generally only used for testing purposes)
If your NERSC username is not the same as your local username, you can specify your NERSC username with the '-u' option:
$ ./sshproxy.sh -u myusername
If you would like to have a different name for the ssh key file, you can use the -o option to specify the output filename:
$ ./sshproxy.sh -o mynersc
Note the -a option can be used to automatically add the new key to your ssh-agent. It will also be set with an expiration that matches the keys expiration so that ssh does not try to use the key after it has expired.
If your computer has an old version of ssh (e.g., OpenSSH_7.2), you may have to use the -a flag. Otherwise, ssh and scp commands will require additional flags to work as in the example cases shown below. To see the version info, run the command, 'ssh -V'.
Long-term SSH Keys
The scope option (-s flag) is to accommodate special needs for your work. If automatic workflow needs keys for a long term, you can make a request in a ticket. Click here to submit a request. We will grant such a request only after a review. When your request is approved, we will provide information on how to set the scope.
SSH Configuration File Options
We recommend some options to put in your ssh config file. These options help avoid some potential problems with expiring ssh keys, and provide default key filenames to ssh so that you don't have to specify the key on the command line every time you use ssh. These options can all be overridden on the command-line at any time.
If you typically use only the default 'nersc' key from sshproxy, you can modify your ssh config file to automatically use that key, instead of having to specify it on the command line every time. To do so, edit the file ~/.ssh/config on your local computer to include the following lines:
Host cori*.nersc.gov denovo.nersc.gov gpint*.nersc.gov gpweb*.nersc.gov genepool.nersc.gov pdsf.nersc.gov dtn*.nersc.gov
With that entry, whenever you ssh to one of those NERSC systems, your ssh client will automatically use your proxy key.
If your ssh client does not present a valid ssh key to the ssh server, the server will prompt you to authenticate with NIM password + OTP. Neither the server nor the client will tell you that your key has expired.
Logging in with sshproxy Keys
Once you have generated a valid key, you do not need to provide any further authentication to get into NERSC resources. You can simply connect in the usual ways without providing a password:
$ ssh firstname.lastname@example.org
NOTICE TO USERS
$ scp myfile email@example.com:.
NOTICE TO USERS
Secure Connections from Macs and PCs Using SSH
You will need an SSH-capable application in order to login to NERSC computers. A number of applications are available, both freeware and commercial products. Your local workplace, school, or organization may have a site license for an SSH software package.
Troubleshooting SSH Problems
Some common error messages are:
- "Access Denied" or "Permission Denied" -This is likely a username or password problem. Make sure you are using the proper NERSC user name. You may also have too many login failures or may have been disabled due to extended inactivity. To clear your login failures, simply login to NIM. If you are still unable to login, contact the Account Support Office at 1-800-66-NERSC, menu option 2.
The authenticity of host 'cori.nersc.gov' can't be established.You may get this message the first time you connect to a new machine. Note that many NERSC systems have several distinct login nodes, so you might see the above message for each login node. Just type "yes" to continue.
RSA key fingerprint is <omitted>
Are you sure you want to continue connecting (yes/no)?
NERSC consultants will attempt to help you solve problems concerning access to NERSC machines. However, our consultants have expertise only on software installed by NERSC and running on NERSC computers. This does not include software running locally on users' computers.
The best source of information for configuring your local computer is your local system administrator. Local coworkers can often help. Our consultants are not always able to provide help for the myriad of different programs and platforms that could be used to connect to the Internet.