Note: You cannot get a shell on GCE login nodes. Please see the document above explaining which computers to use.
None of the steps below will work until you request the GCE project.
These commands and examples presume you are using OpenSSH. For other versions of SSH, including PuTTY, SSH.COM, etc, please find resources elsewhere related to these tools in how to use their SSH implementation and how to generate the associated keys. Our system only accepts and uses public keys in the OpenSSH format.
SSH authentication to GCE hosts is primarily done with the use of SSH keys. It is required that SSH keys in the GCE use strong passphrases.
If you haven’t already, please read up on login, compute, and home nodes you will use in GCE.
Creating SSH Keys:
Generate a pair of SSH keys with the ssh-keygen command; in this example we create an ed25519 key. ed25519 is the newest and preferred key type, though older OSes may not have support. SSH key algorithm options in order of most preferred to least are ed25519, ecdsa, rsa, dsa. If you use RSA, you should use a minimum of 4096 for a key length, but bear in mind it’s on its way out and newer OSes will not use it. ecdsa keys need to be at least 512 bytes. dsa is not recommended.
# ssh-keygen -a 100 -t ed25519 Generating public/private ed25519 key pair. Enter file in which to save the key (/Users/USER/.ssh/id_ed25519):
(You can change the name of the ssh key here and is useful if you have several keys – make note of the name if you use a different one other than the default. We will presume you went with the defaults here. Note: If you choose a different name you will need to specify the key to use in the ssh config file or in the ssh command itself.)
Enter passphrase (empty for no passphrase):
(A strong passphrase is required)
Enter same passphrase again:
(Repeat the strong passphrase)
Your identification has been saved in /Users/USER/.ssh/id_ed25519.
(This is your private key. Keep it secure, do not share it, and be cognizant of where you store it.)
Your public key has been saved in /Users/USER/.ssh/id_ed25519.pub. The key fingerprint is: SHA256:lSglfiIzcdJumCtz1RI03sulFJ3pA3hZcFMbPPEY14Y USER@foo
(This is your public key.)
Adding your public key to your account
After you generate your SSH key pair, add ONLY the public key to your account at https://accounts.cels.anl.gov.
- Copy the contents of the .pub file generated above (in the example above, ~/.ssh/id_ed25519.pub)
- Choose “Add Key” at the bottom of the Account Information page after login.
- Paste what you copied into the “Key” section that appears. The “Description” is purely informational and allows you to give it a meaningful or memorable name/description for future reference.
You will then be able to SSH to “home nodes” and “compute nodes” directly while on a trusted internal network. If you used a different key name other than id_ed25519, you’ll want to edit your .ssh/config to make it more convenient. See below.
How to SSH into GCE
No GCE compute resources are directly accessible from offsite.
The bare minimum command you should be able to run once you’ve done the above is this:
ssh -J <your argonne username>@logins.cels.anl.gov <your argonne username>@homes.cels.anl.gov
Please note: You absolutely have to put in your real username. If you copy and paste the above without replacing the username field it will fail. If you try the above and it fails, please make sure you have used the correct username.
If you would like to have a shorthand way of doing this, read on. But until the above command works for you nothing below this point will. If you want a quick and easy solution to be able to SSH from offsite, place the appropriate configuration on your local computer.
In all of the examples below, replace yourargonneusername with your actual Argonne username. Otherwise, it will fail.
Windows: Copy the following two lines of configuration and paste them into the .ssh\config file from your home directory. Typically, this is C:\Users\yourname\.ssh\config. If the file does not exist, create it.
Host *.cels.anl.gov !logins.cels.anl.gov ProxyJump [email protected]
Linux/Unix/macOS: Copy the following two lines of configuration and paste them into ~/.ssh/config. If the file does not exist, create it.
Host *.cels.anl.gov !logins.cels.anl.gov ProxyJump [email protected]
After you’ve done the above, you can ssh to hosts in gce with the command “ssh yourargonneusername@homes.cels.anl.gov” – this should work for any hostname that ends in .cels.anl.gov.
If you chose a non-default name for your key file above, you will need to specify it on the commandline, such as “ssh -i ~/.ssh/name-of-PRIVATE-keyfile yourargonneusername@homes.cels.anl.gov” or you will need to add the line “IdentityFile /path/to/privatekeyfile” under the ProxyJump line in the above configuration file.
If you find this doesn’t work, or want to fine tune this, read on for more detailed instructions and how to customize this for more advanced setups. You should also see the man page or this handy guide.
Detailed instructions for those who want to fine tune this
The recipe below will let you trivially SSH to home nodes, compute nodes, or even your GCE desktop from offsite. These directions presume you are using a unix-based OS, such as Linux, macOS, or the Windows Subsystem for Linux (WSL). If you are using the build-in SSH in Windows, pay attention to any notes calling out the differences in the section below.
First, make sure ~/.ssh/.control_channels exists on your local machine, the ssh session will create some control channel sockets in this dir.
mkdir -p ~/.ssh/.control_channels
Edit your ~/.ssh/config similar to the example ~/.ssh/config below. Do not simply copy and paste, you need to substitute your Argonne username in the “User” line.
################################################### ControlPath ~/.ssh/.control_channels/%h:%p:%r Host login-gce User yourargonneusername IdentityFile /path/to/private_ssh_key_created_above Hostname logins.cels.anl.gov ControlMaster auto ControlPersist yes LogLevel FATAL Host homes-gce User yourargonneusername IdentityFile/path/to/private_ssh_key_created_above Hostname homes.cels.anl.gov ProxyJump login-gce ForwardX11Trusted yes ###################################################
Note: If your local machine username does not match your ANL username you can add “User anlusername” under each of the hosts so the ssh connection is made using the correct username. Also, if you used a different key name in the steps above, you’ll need to add an IdentityFile directive in the relevant hosts. See here for full docs on the ssh config file.
With the above parameters, running “ssh homes-gce” will set the control channel to logins.cels.anl.gov and subsequently providing you with a shell on homes.cels.anl.gov. You can add additional host/proxy command entries to connect to other machines using the same SSH tunnel. For example, if you want to connect to your CELS-managed workstation from offsite, you can add to your ~/.ssh/config file something similar to the following example, changing the hostname to the appropriate name:
################################################### Host workstation-offsite Hostname workstation.cels.anl.gov ProxyJump login-gce ForwardX11Trusted yes ###################################################
This will use the same ssh control channel we setup in the previous example to connect to your workstation.
You can also create a general wildcard entry that would tunnel all SSH connections through the logins. Example:
################################################### Host *.cels.anl.gov ProxyJump login-gce ForwardX11Trusted yes ###################################################
With the above any SSH to a hostname ending with .cels.anl.gov will be tunneled through the login nodes.
Note: Do not store your ssh private key on the NFS shared filesystem, this includes the home dir of your GCE workstation if you have one. In most cases you should not need your ssh key once logged in to one of the CELS GCE managed machines: home nodes, compute nodes, workstations. Once logged in to one of these you will be able to ssh between these type of managed nodes without further use of the private key.