> For the complete documentation index, see [llms.txt](https://igb.mit.edu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://igb.mit.edu/mini-courses/research-computing-on-engaging-with-vscode/vscode/ssh-configuration.md). # SSH Configuration Before proceeding to the section on using Engaging with VSCode, we need to learn a little bit about SSH and SSH keys. Secure Shell, better known as SSH, is the protocol used for starting a secure, encrypted remote shell to a system. When you connect to Engaging using the terminal (`ssh you@orcd-login.mit.edu`), SecureCRT, the Engaging OnDemand [Shell Access](/mini-courses/research-computing-on-engaging-with-vscode/connecting-to-engaging-via-ondemand/shell-access.md) page, or VSCode, the underlying connection is through an SSH client. SSH allows for a variety of ways to authenticate yourself to the system. A common method is via a password, whereby you enter your user's password when making a connection to the server. Another method is via SSH keys. ## SSH Keys SSH keys consist of a pair: a public key and a private key. * **Public Key**: This key can be shared freely and is used to encrypt data that only the corresponding private key can decrypt. * **Private Key**: This key must be kept secure and private. It is used to decrypt data encrypted with the corresponding public key and to prove the identity of the user. {% hint style="danger" %} Private keys should never be shared with anyone, as they allow access to your Engaging account. {% endhint %} A public key is essentially an identity ("Allen exists"), and a private key is a proof of identity ("I am Allen"). Since a private key is proof of identity, it can be used as authentication to a system without needing a separate password. We'll take advantage of this to login to Engaging with an SSH key instead of with a password. As mentioned previously in [Connecting to Engaging via OnDemand](/mini-courses/research-computing-on-engaging-with-vscode/connecting-to-engaging-via-ondemand.md), after logging in to the Engaging OnDemand web portal, you will have a 24-hour period where logging in to Engaging with SSH keys will not require Duo authentication. ### Setting up SSH key authentication To setup SSH key authentication, you first must generate an SSH key pair. 1. Open the Terminal tab in VSCode: **Terminal** > **New Terminal**. On MacOS, you'll get a new `zsh` terminal, whereas in Windows you'll get a `PowerShell` terminal. 2. Run the `ssh-keygen` command to generate SSH keys. When asked what file to save the key to, use the full example path the command gives you, but replace `id_ed25519` with `orcd` . This will be the name of the SSH keys you use to log in to the Engaging cluster. The rest of the prompts can be left as the defaults. ```bash ssh-keygen -t ed25519 # Generating public/private ed25519 key pair. # Enter file in which to save the key (/Users/asoberan/.ssh/id_ed25519): /Users/asoberan/.ssh/orcd # Enter passphrase (empty for no passphrase): # Enter same passphrase again: # Your identification has been saved in /Users/asoberan/.ssh/orcd # Your public key has been saved in /Users/asoberan/.ssh/orcd.pub # The key fingerprint is: # # The key's randomart image is: # ``` 3. Copy your newly created key to your Engaging account.
MacOS / Linux
ssh-copy-id -i /Users/<your local username>/.ssh/orcd <your Engaging username>@orcd-login.mit.edu
Windows
Get-Content $env:USERPROFILE\.ssh\orcd.pub | ssh asoberan@orcd-login.mit.edu "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
4. Edit your SSH configuration file to use your SSH keys when logging in to Engaging.
MacOS / Linux

The SSH configuration file is located at ~/.ssh/config .

Host orcd-login
    Hostname orcd-login.mit.edu
    IdentityFile ~/.ssh/orcd
    IdentitiesOnly yes
    ControlMaster auto
    ControlPath ~/.ssh/%r@%h:%p
    ControlPersist 300s

Host orcd-compute
ForwardAgent yes
ProxyCommand ssh orcd-login /usr/bin/srun --unbuffered --time=2:00:00 nc localhost 22 -w 10
IdentityFile \~/.ssh/orcd
StrictHostKeyChecking no
ControlMaster auto
ControlPath \~/.ssh/%r@%h:%p
Windows

The SSH configuration file is located at C:\Users\<your local username>\.ssh\config .

Host orcd-login
    HostName orcd-login.mit.edu 
    User <your Engaging username>
    IdentityFile C:\Users\<your local computer username>\.ssh\orcd
    IdentitiesOnly yes

Host orcd-compute
User \
HostName \
ProxyJump orcd-login
5. Now, you can login to Engaging using your SSH keys.
MacOS / LinuxWindows
Engaging Login Node
ssh orcd-login

ssh orcd-login
Engaging Compute Node
ssh orcd-compute

  1. Connect to the login node

    1. ssh orcd-login

  2. Manually request a compute node

    1. salloc -t 2:00:00 -p mit_normal
  3. Edit your SSH configuration file and replace <node name> with the compute node assigned to your request.
  4. Run ssh orcd-compute to connect directly to that compute node for the remainder of your allocated time (in this case, 2:00:00 A.K.A. 2 hours).