HOWTO: To connect via SSH Bastion Servers for Linux, Mac, and Unix

Purpose

ERIS maintains a group of OpenSSH servers intended to provide researchers and other interested parties with Secure Shell access to hosts within the Mass General Brigham computer network. The latest iteration of these SSH bastions work somewhat differently from previous versions; in particular, there is no interactive shell provided to the user. Users are expected to authenticate to the SSH servers only as an intermediate step in connecting to another host on the Mass General Brigham computer network. The sections below describe how to request access to the research SSH servers, and subsequently how to authenticate and use them to remotely access your servers and workstations inside the MGB firewall.

Requirements

• Users are expected to have a basic level of familiarity with the Unix command line. This page gives instructions specifically for authenticating and forwarding connections through our SSH servers, and is not intended to be a complete shell tutorial.
• You should be connecting with an up-to-date OpenSSH client (version 6.6 or newer is required; 7.3 or newer highly recommended. Older clients may not support all of the mandatory security enhancements of the server, in which case your connection attempt may be refused.
  
  • The versions of ssh which ship with the following releases/distributions have been tested and are known to work:
    
    • macOS 10.15 
    • Debian 9 (Stretch)
    • Ubuntu 18.04 LTS (Narcoleptic Narwhal, or something)
    • Fedora 29 (I'm losing interest in the nicknames—just pay attention to the number, will ya?)
    • RHEL/CentOS 7 (...)
  • Above is not an exhaustive list, as we cannot possibly test every OS or Distribution out there—if your OpenSSH client is version 7 or newer, is is very likely to work
  • Out-of-date operating systems (those no longer receiving security patches) may not be able to connect, and no support is provided. Update.

Note
These instructions assume you are connecting from a Unix-like operating system, with a command-line ssh client. If you are using Windows 10 you may also enable the Windows Subsystem for Linux, in which case the instructions below apply. On all currently supported versions of Windows, PuTTY is a free alternative; instructions are linked in the Related items at the bottom of this page.

First Steps

• If you have never used the research SSH servers before, you must request access. Complete the request form.
• When your account is added to the SSH servers, you will be sent an auto-generated email which includes an SSH key pair, and in a separate email, a password for the encrypted Private Key.
  
  • The subject of these and related emails will begin with "Research SSH: ..."
  • You must save the Private Key. The recommended (default) location for this type of key is ~/.ssh/id_ecdsa
    
    • If you need to save your Private Key to an alternate location or file name, you will need to use the -i flag with ssh (append to the examples below). See ssh(1).
  • We do not save the Private Key anywhere after we send it to you; if you lose it, you must open a Service Now ticket or contact rcc@partners.org and request your account be re-keyed.
  • You may save the included Public Key for use on other servers if you wish.

Note on saving keys:
Some email clients (e.g. Apple Mail) may automatically append a ".txt" extension to text-based files for which it does not recognize another file type. Additionally, it is not intuitive on some systems how to save the file to a hidden directory, like .ssh. In such cases, the following steps are recommended:

• Using your email program, save the attached keys to an intermediate location, such as your Desktop. Note the names of the files as saved.
• Open a Terminal window, move the files to their correct names and location, and change the file permissions:

mv ~/Desktop/id_ecdsa.txt ~/.ssh/id_ecdsa
mv ~/Desktop/id_ecdsa.pub ~/.ssh/id_ecdsa.pub
chmod 0600 ~/.ssh/id_ecdsa

Changing SSH key passphrase
It is possible to change the encryption passphrase of your SSH Private Key, utilizing the command below. On a reasonably fast client system, it is recommended you utilize the -a flag with a higher-than-default number of rounds, to hamper brute-force attacks on the password should your key become compromised. You will first be prompted for the current password, then for a new password (twice to avoid typographic errors).

ssh-keygen -p -a 64 -f ~/.ssh/id_ecdsa

Connecting to a shell prompt

• The following instructions apply to command-line only sessions using up-to-date versions of ssh (those newer than 7.3);  for older versions which do not feature the -J flag, see "old port-forwarding method," below.
• You will first open a session with the SSH Bastion in one terminal window (or tab), then you will leave the session open and connect to your destination host in another window/tab.
• Every example in <angle brackets>, including the brackets themselves, represents a variable you are to replace with a username.
  
  • More generally, these instructions will not work if you copy/paste the examples with no editing.  There is no such host as "example.mgb.org" and <MGB_Username> would not authenticate to it even if there were.

Initiating session on the SSH Bastion

ssh <MGB_Username>@ssh.mgb.org

• Having entered the above command, you will be prompted for the following credentials:
  
  • The password to unlock your Private Key, which was provided when you registered.
  • Your Mass General Brigham password.
• You will be greeted by a welcome banner, which includes an abbreviated version of these instructions.
• You may see a blinking cursor, but the server will not accept any commands directly.
• ssh(1) escape sequences, beginning with ~, should function to change options to your session; see the Tips section, below.
• Leave the session open and proceed to the next step.
• In a new window or tab, connect to a host inside the Mass General Brigham computer network as follows:

Connecting to your endpoint

ssh -J <MGB_Username>@ssh.mgb.org <Username_on_endpoint>@example.mgb.org

Connecting (old port-forwarding method)

• The following instructions apply to older versions of ssh(1), which do not support the ProxyJump option, and for connecting to ports other than 22.
• The Research SSH servers do not provide an interactive shell; they only open some ports in the firewall through which you may connect to other hosts.
• Initiate your connection to establish "port-forwarding" as in the example below.
  
  • We use port 2022 to forward in the example, but you may chose any port not in use and greater than 1024 to map to the destination port (in this case, ssh on "somehost" running on the standard port 22). See ssh(1) for more details in using the -L flag.
  • Substitute your Mass General Brigham user name for <MGB_Username>

Opening a port-forwarding session

ssh -L 2022:example.mgb.org:22 <MGB_Username>@ssh.mgb.org

• You may forward multiple ports to different servers if you wish, by including additional -L directives.
• Having entered the above command, you will be prompted for the following credentials:
  
  • The password to unlock your Private Key, which was provided when you registered.
  • Your Mass General Brigham password.
• You will be greeted by a welcome banner, which includes an abbreviated version of these instructions.
• You may see a blinking cursor, but the server will not accept any commands directly.
  
  • ssh(1) escape sequences, beginning with ~, should function to change options to your session; see the Tips section, below.
• Leave the session open and proceed to the next step.
• It a new tab or window, connect to your ultimate destination as follows:

Connecting to the MGB internal host

ssh -l <username_on_endpoint> -p 2022 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no localhost 

• The port, as specified by "-p 2022," must match one of the ports you forwarded in the previous command.
• You should obviously make a substitution for <username_on_endpoint>, which may or may not be your MGB user name, depending on what host you are connecting to.
• The other options shown subdue current and future warnings about the host key for "localhost," since that is not a unique name for any other servers you may connect to using this method.
• You may still check the host key manually if you are concerned about the possibility of a man-in-the-middle attack.
• You will be connected to the remote host ("example.mgb.org") and asked to authenticate using that system's configured method.

Tips & Warnings

New Hostname
Note that the hostname for the Research SSH servers has changed:

• The old servers were at ssh.research.partners.org — this is now the wrong address, and those servers are offline.

• New servers are at ssh.mgb.org

• ssh.partners.org also works for the time being, but users are encouraged to transition to the mgb.org domain.

Adding ports/hosts after connecting
Should you wish to connect to an additional MGB host you had not thought of when you initiated your session, you need not start over. From the (mostly) non-interactive ssh session window, use the escape sequence ~C and specify an additional tunnel parameter, in the same format as you would have in the initial command-line.  In the following example, we forward port 4000 from an MGB host so we can connect a NoMachine session locally;  note the "ssh>" prompt is shown in this example instead of the standard $ or %; do not type it:

ssh> -L4001:another-example.mgb.org:4000

Caching your authentication keys
If you intend to open multiple connections using your SSH keys, and want to relieve yourself of the hassle of entering the passphrase repeatedly, you may cache decrypted private keys using ssh-agent(1).

Related

HOWTO: Connect to the SSH Bastion Servers from Windows