Search Documentation
Search for commands, configurations, or guides.
Start typing to see results
  1. Overview
  2. Deployment
  3. Monitoring
  4. Maintaining
  5. Common Errors and Known Solutions
  6. Features
  7. Extinction Model and Burn-in
  8. Scientific Results
  9. Low-Latency Injections
  10. References
  11. Template Banks
  12. Pastro
  13. Offline Analysis
  14. Offline Filtering Rota
  15. Offline Rota
  16. Dropped data filtering
  17. Offline SNR Optimizer/Coinc generation
  18. MDC Documentation
  19. How to contribute to this documentation
  20. Diagrams
  21. SSH
  1. Overview
  2. Deployment
  3. Monitoring
  4. Maintaining
  5. Common Errors and Known Solutions
  6. Features
  7. Extinction Model and Burn-in
  8. Scientific Results
  9. Low-Latency Injections
  10. References
  11. Template Banks
  12. Pastro
  13. Offline Analysis
  14. Offline Filtering Rota
  15. Offline Rota
  16. Dropped data filtering
  17. Offline SNR Optimizer/Coinc generation
  18. MDC Documentation
  19. How to contribute to this documentation
  20. Diagrams
  21. SSH

SSH

Table of Contents


Creating an SSH key

To create an ssh key (really a public/private key pair) on your laptop, run this command:

ssh-keygen

You can press Enter to accept the default file name and location (the rest of this document assumes it is ~/.ssh/id_rsa). It is LDG policy that you must add a passphrase, but don’t worry, you won’t have to enter it every time you use it.

While the public key file (id_rsa.pub) is something you can share, the contents of the private key file (id_rsa) should never have to leave your laptop.

Next, add the key to your laptop’s ssh agent (leave off the apple argument if you’re not using a Mac):

ssh-add --apple-use-keychain ~/.ssh/id_rsa

You should now see the public key if you run: ssh-add -L

Registering an SSH key with the LDG

In order to use an SSH key to log in to accounts in the LIGO Data Grid (LDG), the key must be registered to your account.

  • Copy the contents of your public key file: cat ~/.ssh/id_rsa.pub (make sure it’s the .pub file!)
  • Click this link: https://ldg.ligo.org/ldg/manage_ssh/
  • Paste the contents of the .pub file into the box at the bottom of the page
  • Click the Submit button

If you have any keys registered which you don’t need to use anymore, simply uncheck the box next to it/them, and then click the Submit button.

Registering an SSH key with GitLab

To use the SSH key with GitLab. The key must be registered with GitLab.

  • Copy the contents of your public key file: cat ~/.ssh/id_rsa.pub (make sure it’s the .pub file!)
  • Click this link: https://git.ligo.org/-/user_settings/ssh_keys
  • Click Add new key
  • Paste the contents of your public key file into the box
  • Change the expiration date if desired
  • Click Add key

You should now be able to clone projects over SSH instead of HTTPS.

You may want to set up your git config on all clusters so that any commits you make will be attributed to you. To do so, log into each cluster and set these:

git config --global user.name "Albert Einstein"
git config --global user.email albert.einstein@ligo.org

SSH configuration

Some extra configuration will make your life much easier, especially as Multi-Factor Authentication (MFA) is becoming more common. There are many ways to set this up, but the following steps will give you a working configuration.

Do this on your laptop:

  • Run mkdir ~/.ssh/sock
  • Create the file ~/.ssh/config on your laptop
  • Copy and paste the configuration below into the config file
  • Replace the two instances of albert.einstein with your username
  • Replace ~/.ssh/id_rsa with the path to your private key (the one without .pub)
  • You probably want to change the cit alias to point to your citlogin# node instead of citlogin0
  • If you are using Linux instead of a Mac, comment or remove the UseKeychain option from the config file. If you are using Windows, see the note below.

Configuration for ~/.ssh/config:

##### Aliases for hosts #####
# Hardcoded friendly names map to default nodes
# Example: `ssh psu`
Host cit
    # You may want to change this to your citlogin# node
    Hostname citlogin0.ligo.caltech.edu
Host psu icds gwave
    Hostname ligo-hd-02.gwave.ics.psu.edu
Host uwm nemo
    Hostname submit.ligo.uwm.edu
Host lho
    Hostname ldas-pcdev6.ligo-wa.caltech.edu
Host llo
    Hostname ldas-pcdev6.ligo-la.caltech.edu

# Map hostnames to full domain names
# First catch short names which specify a LIGO Lab site
# Example: `ssh ldas-pcdev6.ligo-la`
Host *.ligo *.ligo-la *.ligo-wa
    Hostname %h.caltech.edu
# Then send all other ldas-* to CIT unless a full domain is already given.
# Example: ldas-pcdev12
Host ldas-* !ldas-*.edu gstlal cbc citlogin?
    Hostname %h.ligo.caltech.edu
Host ligo-hd-0?
    Hostname %h.gwave.ics.psu.edu
Host submit
    Hostname %h.ligo.uwm.edu

#### Site config ####
# LIGO Lab sites with MFA
Match host *.ligo.caltech.edu,*.ligo-la.caltech.edu,*.ligo-wa.caltech.edu
    GSSAPIAuthentication yes
    GSSAPIDelegateCredentials yes
Match host *.ligo.caltech.edu,!sshproxy.ligo.caltech.edu,!sshmma.ligo.caltech.edu
    ProxyJump sshproxy.ligo.caltech.edu
    ControlMaster no
Match host *.ligo-wa.caltech.edu,!sshproxy.ligo-wa.caltech.edu
    ProxyJump sshproxy.ligo-wa.caltech.edu
    ControlMaster no
Match host *.ligo-la.caltech.edu,!sshproxy.ligo-la.caltech.edu
    ProxyJump sshproxy.ligo-la.caltech.edu
    ControlMaster no

#### Defaults ####
Host *
    User #FIXME albert.einstein
    IdentityFile #FIXME ~/.ssh/id_rsa
    IdentitiesOnly yes
    AddKeysToAgent yes
    ControlMaster auto
    ControlPath ~/.ssh/sock/%r@%h
    ControlPersist 2h
    # For Macs:
    UseKeychain yes

#### Agent forwarding ####
# For personal account at CIT, PSU, UWM, LHO, LLO
Match user #FIXME albert.einstein host *.ligo.caltech.edu,*.gwave.ics.psu.edu,submit.ligo.uwm.edu,*.ligo-?a.caltech.edu
    ForwardAgent yes

Features of the above config:

  • Log in to clusters by typing friendly aliases like ssh citlogin0 and ssh nemo
  • ForwardAgent forwards attempts to use SSH from the cluster back to your laptop (see note below)
  • ControlMaster makes successive logins faster and avoids doing MFA more than once (see note below)

SSH agent forwarding

The ForwardAgent option allows you to use the SSH agent on your laptop for things you do on a cluster. It forwards authentication requests back to your laptop. This means that there is no need to have SSH keys on includingusters.

You can test if agent forwarding is working by running ssh-add -L on a cluster. It should show the SSH key from your laptop.

ControlMaster

The ControlMaster option tells the SSH agent to create a “socket” file for any new connection to a cluster, and to reuse the existing connection/socket for successive logins to the same cluster. This makes it much faster to SSH into the same site after the first connection is made, and it avoids the need to re-authenticate with MFA.

The ControlPersist option sets the amount of time that a connection should be held open after your last SSH login to that cluster exits.

If something goes wrong with a network connection and it becomes unresponsive, you can’t “start fresh” by simply logging in again because it will try to reuse the unresponsive connection. If this happens, you can delete the socket file for that connection at ~/.ssh/sock/user@host, and then open a new one by logging in again.

If you’re using Windows

The SSH client built into PowerShell doesn’t support ControlMaster. It is recommended to install WSL2 and use the Linux SSH client that way. Doing so will allow you to follow standard instructions for many other things as well.

That said, the above configuration can be made to work on Windows if you comment out or delete the three options ControlMaster, ControlPath, and ControlPersist. Be aware that this means you will have to use MFA for every connection to a site with MFA enabled.

MFA

Some LDG sites now require Multi-Factor Authentication (MFA) for SSH connections. Here are instructions for enrolling in MFA:

  • Install the Duo Mobile app on a mobile device
  • Attempt to SSH to a site which requires MFA. For example: ssh sshproxy
  • Follow any of the three links in a browser
  • Make sure to select Duo Mobile as your second factor
  • Follow the on-screen instructions to set up Duo Mobile as your second factor

You should now be able to log in using MFA.

More information about MFA in the LDG, including screenshots of the enrollment process, can be found in this MFA repository.

Using MFA between clusters

To log in to a cluster using MFA, your connection must go through the MFA proxy. If you want to connect from one cluster to another with MFA, you’ll want an ssh config on the cluster where you initiate the connection. You can copy the ~/.ssh/config from your computer to a cluster, create the directory used for sockets (mkdir ~/.ssh/sock), and then comment out or remove these settings from the config you just copied to the cluster:

  • IdentityFile — would try to use a key file that isn’t on the cluster
  • IdentitiesOnly — would refuse to use keys from the forwarded agent
  • AddKeysToAgent — there are no local keys to add to the agent
  • UseKeychain — this is Mac-specific
  • ProxyJump for the cluster with this config — connections inside the cluster don’t need MFA

Since your computer’s config already forwards your SSH agent to the first cluster, this setup will automatically use the ssh key on your computer to connect to the second cluster.