SSH - Overview and Guide

Quick Roundup - What is SSH?

SSH stands for the Secure SHell. It is a way to provide a secure way of permitting remote login access and file transfer across a network. SSH commands completely encrypt the connection between client and server.

SSH provides authentication, encryption, optional compression, and tunneling. One of the best examples of tunneling is the X Window Protocol (X11); most of our systems are set up to do X tunneling by default. What this means is that the DISPLAY variable is pre-set for you. SSH has now become the most popular means of remote access and file copying all over the net, and its use is mandated by Security Policies, including our own, as the only way for internet login access to our machines.

The Secure Shell originated in Finland, but the version NRAO uses on its Unix (Linux, Solaris, and Mac OS/X) machines comes from the OpenSSH group, which in turn is part of the OpenBSD Operating System. While OpenSSH supports both protocol versions 1 and 2, we only use and recommend version 2. OpenSSH is free software.

There are three levels at which you can use the Secure Shell:

Bare bones: just use the slogin or ssh or scp commands. You have to enter your password every time.

Key based access: Use SSH keys, have a passphrase, use ssh-agent so you don't need to enter password for each and every invocation of slogin or scp.

Advanced use: as above, but also use features such as tunneling for X11, web proxies, or other protocols through the connection; restrict networks from which connections can be made, and confine access to certain commands.

As you can see, you can either use the secure shell in a mode where you supply your password on the server for each and every login (the bare bones level mentioned above), or you can use keys and an agent to "cache" your identity and only enter a passphrase challenge once per X11 (or Windows or OSX) session. Most users will find using the agent and keys much easier in the long term, at the cost of a small one-time effort of key setup.

IMPORTANT: The login or "Bastion" Servers

Each site has a login server that accepts SSH connections from the internet at large. These bastion servers are the only way for you to connect via SSH to NRAO's internal network.

These servers are set up to ignore your personal authorized_keys file (see below for details on that file) and use one managed by the system administrators instead. If you have a demonstrable need for an entry in the system's authorized_keys file for your account, you must:

Contact your local helpdesk with the request, including a short description of why you need it;

Verify to them that your private key is indeed encrypted with a passphrase; and Supply them with your public key (identity.pub) or tell them where it is located if not in the default ~/.ssh/ location.

Requests for such additions will by default be set up only to allow such key based access from NRAO networks (from=*.nrao.edu). Expanding the range to allow additional networks to use key based access will be only where it is needed and must be as narrow as feasible (class B, C, or D network ranges).

Where can I get SSH for...

Windows: For most use, especially home or personal laptops, use PuTTY. This is free software that doesn't need "installed"; just download, unpack, and run.

For NRAO/CV or AUI machines, you may already have SecureCRT in your "Start" menu. It has a few different features than putty (and predated it).

Linux: you already have OpenSSH! It comes with almost all modern distributions: Red Hat, Ubuntu, Fedora, Debian, SuSE, Gentoo, etc. Also on the BSD variants OpenBSD, FreeBSD, NetBSD.

Mac OSX: Comes with OpenSSH.

Solaris: OpenSSH is installed on all NRAO Solaris systems.

Something else: Ask one of us!

The SSH Agent

The ssh-agent program allows you to cache your private ssh key(s) so that you only get the passphrase challenge once per session. It avoids having to enter the passphrase for each ssh or slogin or scp command that you use.

A pre-requisite for making (sensible) use of the agent is the (usually one-time) generation of keys. See the section below on ssh keys for how to create a public-private set of keys for your account, if you have not already done so.

To add your default key to the agent, just type this in a terminal window (Linux or Mac): ssh-add </dev/null and you should get a pop-up dialog asking for the passphrase.  You only need to do this once per session; the agent keeps the key cached for as long as you are logged in (even over suspend or hibernate events).

SSH For Mac Users

For those sitting in front of Mac OSX systems, ssh-agent works just like it does under Linux, except that the SSH_AUTH_SOCK variable is not needed. Also, ssh-agent can store key passphrases in your system keychain.

SSH For Windows Users

The PuTTY package comes with a program called Pageant that provides the same functionality as ssh-agent on other platforms. It requires that you have generated a private key in *.PPK format. When run, pageant will put an icon (a computer wearing a hat) into the system tray. Right-clicking on this icon brings up a menu including view keys and add key. Use these to add a key once you have generated it (see below).

SSH For Linux/Unix Users

As all NRAO desktop and laptop Linux systems are configured to use GNOME or KDE, the ssh-agent process is automatically started for you. You do not have to edit any configuration file, nor do you have to start it by hand. It's there for you to use.

For other systems, check if the agent is already running by checking your environment: echo $SSH_AUTH_SOCK should give more than a blank line. If it is not running, use the text-only access method in the next section.

SSH For Text-only Access

For those who prefer not to use this app, or if you are using a Solaris system or a text-only login such as a server or one of the Virtual Consoles of a Linux system, you may need to start ssh-agent manually. Once you have logged on, or have a terminal window running, type this:

eval `ssh-agent`

Note: Users with tcsh or csh as their login shell should type eval `ssh-agent -c` instead.

Basic Use

• Top of Page
• Previous Section: The SSH Agent
• Current Section: SSH Basic Commands

SSH Key-based Access

This section shows you how to create and use a set of ssh keys for your NRAO accounts. Most users will want to read the section for desktop users, but we present laptop users first to avoid duplication of key generating effort.

NOTE on sshpass: Most modern Linux distros will include a utility called "sshpass" that supposedly makes things easier for you, letting you have the experience and ease of use of ssh keys without actually generating a key.  Unfortunately all sshpass does is encourage you to put your password in plain text in what is most likely a VERY insecure location.  This violates NRAO's Computing Security Policy, so use of sshpass is not permitted at the Observatory.

SSH For Laptop Users

You probably have a local account or accounts on your laptop. The best procedure for you is to generate a _passphrase-enabled_ key (i.e., one with a non-blank passphrase) on the laptop for each account. Don't overlook any admin or root accounts which you may also have on the laptop.

See below in the _For Desktop Users_ section for how to do the key generation. Once done, you may copy these generated files to your account on the filer at your site(s); you can use, for example:

scp ~/.ssh/{identity,authorized_keys} login:.ssh/

An alternative command, one that preserves date/time stamps, is:

rsync -av -e ssh ~/.ssh/{identity,authorized_keys} login:.ssh/

Either of these commands will copy your public and private key, and the authorized keys file, from your laptop to your NRAO account at your local site.

SSH For Desktop Users

To generate or re-generate your ssh keys, you give the following commands in a terminal window:

ssh-keygen -b 521 -t ecdsa


This commands generates an ECDSA (Eliptical Curve Digital Signature Algorithim) of 521 bits.  Prior to RHEL8, an RSA or DSA key was usable for logins, but starting with RHEL8 DSA keys are considered insecure and will not be accepted.  Make sure you enter a good, memorable passphrase. You should NOT use your NRAO password as your passphrase; not only does having them different follow best practices, it also makes it harder for an intruder to spread a potential break-in further.  You should also not use a blank (no) passphrase, as that allows anyone to use your keyfile if they obtain it.

This ssh-keygen command will generate a ECDSA key pair:

id_ecdsa being the private key (and protected so only you can read it), and

id_ecdsa.pub being the public key.

The private key is encrypted with your passphrase. As of RHEL8 we prefer 521 ECDSA keys to be used.

Then enter this command:

ssh-copy-id username@hostname


                That command will copy your public key into your ssh configuration to allow you to log in.  If you only have an existing RSA or DSA key, and are attempting to update access to an RHEL8 machine you will need to run the copy id command against and existing RHEL7 machine.  Once the new key is in place it should start to work to log in to an RHEL8 machine.

You can change the phrase on your private key later by using this command:

cd ~/.ssh; ssh-keygen -p -f id_ecdsa

It will prompt you for old phrase, and the new one (twice for verification). There is no need to alter the public key; the passphrase is used only to unlock the private one.

Warning : You must use a passphrase for your NRAO account's ssh key if you generate one. While the ssh-keygen dialog suggests you can use an empty passphrase, not using a passphrase is a violation of NRAO Policy, because it can put you and others at risk.

Adding your Key to the SSH Agent

• Top of Page
• Previous Section: The SSH Agent
• Current Section: Key-based Access

Suppose you have just logged in to a brand new gdm session on your desktop or laptop, sometime after having generated the keys as shown above. In a terminal window, type this:

ssh-add

This will prompt for your new passphrase. For more security and a GUI, you can instead type:

ssh-add </dev/null

After either of these, you can verify that your key is in the agent by giving the command:

ssh-add -l

Now, you can use ssh to connect to other local systems (those where your account shares the same home directory). Example: From my desktop in Charlottesville, I want to log into the bonobo system in the AIPS Caige across the hall. I simply type:

ssh bonobo

in a terminal window, and I am able to get in with no password or passphrase challenge, because my ssh-agent took care of the authorization for me. Not only that, it automatically forwards both agent and X11 information, so further ssh connections from bonobo elsewhere will work, and any X applications will also show up on my desktop screen.

Note: The ssh command has options to disable agent forwarding and/or X11 forwarding; see the manual page (man ssh) for details.

If it ever becomes necessary, you can delete all keys from the agent with:

ssh-add -D

Finally, when you log out of your desktop or laptop (i.e., end your gdm or X11 session), your ssh-agent will also be shut down and all cached keys are deactivated. You will need to add your key to the newly started agent the next time you log in.

Multiple Site Issues with Keys

See the note above about the possibility of generating different keys on systems with different home areas.

Warning : Before proceeding with these instructions, you may want to remove (or move) old keys and files from the remote ~/.ssh/ area.

Most users now have a single home area on Unix/Linux systems across NRAO. This means, for example, that Charlottesville staff who travel to Green Bank or the AOC will get their CV filer login area when they log into systems in GB or NM. However, some users had "legacy" pre-existing accounts with separate home areas in CV, GB, and NM and these separate home areas have been preserved. If you have separate home areas at multiple NRAO sites, you can verify this by logging in to each login host login.site.nrao.edu and typing df . to see on which filer your home area lives. If you have only one login area, and have gone through the key generation as shown above, there is no need to do anything more.

If you have separate home areas at different NRAO sites, and/or if you want to set up secure key based permissions between NRAO and accounts at other institutions or at home (using encrypted, passphrase-enabled keys only!!!), here are two possible strategies to achieve this. Please only choose one of them:

Either use the scp command shown above to copy your keys from your local site to the other remote site(s). For example, to copy keys generated on login.cv.nrao.edu to login.gb.nrao.edu you give this command on a CV system:

scp ~/.ssh/{identity,authorized_keys} login.gb.nrao.edu:.ssh/

You will of course be prompted for the password to your account at the remote site for this command. After the keys are in place, that should no longer happen; scp and the other "s" commands will get you in without a password challenge, as long as you have added your key to the agent with ssh-add at the start of your gdm (X11) session.

Note: This command does not copy your public key identity.pub to the remote site; it's already in your authorized_keys file anyway.

Alternatively, you can use ssh login.gb.nrao.edu (continuing the example above), and go through the procedure of generating a completely separate set of keys there. Then you need to decide on the trust relationship you want between the different accounts.

To permit your CV key to allow you into the GB account, you append the CV public key to the GB authorized_keys file. This can either be done by copying and pasting in editors in two windows, or in a single command on the GB (remote) system:

( ssh login.cv.nrao.edu cat ~/.ssh/identity.pub ) >>~/.ssh/authorized_keys

Warning: Note the two >> greater-than signs, not one; this appends instead of overwriting the target file!

To permit your GB key to access your CV account, you want to append the GB public key to the CV code>authorized_keys file. Just reverse the direction of the previous example.

The authorized_keys file can contain many records (each comprising of one rather long line of text) for many keys. Further, you have additional control in this file over the source of the connections you will allow; See below ().

What's this authorized_keys file?

Many of us may find we have both an authorized_keys file and another called authorized_keys2. You do not need two separate files anymore. When the second version of ssh came out years ago, it had the ability to use DSA keys as well as RSA keys. However, servers running older versions of the ssh server could not cope with the new DSA keys, so this workaround was used: put DSA keys in the authorized_keys2 file and keep RSA1 keys in the authorized_keys file.

However, because of numerous updates and security fixes, just about nobody is (or should be) running a ssh server that only supports ssh version 1. So it is safe to just have a single authorized_keys file in your ~/.ssh/ directory.

Advanced Use

• Top of Page
• Previous Section: Key-based Access
  
• Current Section: SSH Advanced Use
  

Tunneling, Compression

Please see the SSH Tunneling for Linux and Mac page for a detailed user guide.

The first thing most newcomers to SSH notice on using it for remote logins is that the DISPLAY environment variable is already set. You can immediately start running X client programs on the remote machine, and have the display show up on your desktop or laptop (the screen in front of you). Do not use the obsolete xhost, xauth, or other commands, and do not try to set the variable yourself. It just works!

In addition, the normal ssh behaviour is to tunnel your ssh agent information, so that (on the remote host) if you give another ssh command to a more distant host, that more distant host will still be able to "see" your local ssh agent. This is particularly useful when logging into the login.{site}.nrao.edu "bastion hosts" or login servers, which are the only ones exposed to the outside internet. When you are at another institution or travelling, or connecting from your NRAO laptop at home perhaps, you will often want to do this two-hop step to get to your desktop, for example: ssh login.cv.nrao.edu, then from there, ssh mydesktop.cv.nrao.edu

But tunneling doesn't stop there. You can tunnel practically any Internet protocol through a SSH connection. The most obvious candidates are POP3 and IMAP for remote e-mail reading.

As for compression, it's enabled with the -C switch on the slogin or ssh or scp command line, or in your ~/.ssh/config file. For text-based activities on a modem connection, compression can realize a 2- or 3-fold apparent improvement in bandwidth; this can make, for example, use of the X11 version of emacs usable over a 28.8 K-baud PPP modem connection. Some postscript files may transfer via scp at close to 10 Kbytes/second under such circumstances.

Restricting the Remote Command

There are two ways in which you can "batten down" a permitted connection by using your authorized_keys file:

you could for example prepend a key in the file with the string from=*.nrao.edu to restrict access to NRAO domain names. See the manual page on the ssh daemon (=man sshd=) for details, and the manual page on ssh_config for the wildcard patterns you can use.

Secure FTP

For those who prefer the old-style ftp command interface (account based, not anonymous), there is good news. The sftp program (psftp for PuTTY) provides this by a special SSH connection to the remote host. Just type, for example:

sftp login.cv.nrao.edu

and you will find yourself (after the password ­ or passphrase ­ challenge) in a very familiar environment. Most of the usual ftp commands will work for you, and you can type help for additional information.

Windows users who need to use SFTP can use FileZilla.

Debugging, Problems

Short version: ssh -v. Add one or two more v's for even more and ridiculous levels of verbosity.

Some problems you encounter may be due to lax permissions on the server end. For example, your ~/.ssh/ directory cannot be group writable (but does need to be world readable). If you must have a copy of your private key on the destination server, it must be protected against reading by anyone except you: chmod 0600 id_dsa.

See also Stupid SSH Tricks, a talk given to the Local Unix User's Group (CHUUG) in Charlottesville some years ago by Pat Murphy.

For more information, see the manual page for ssh. What you've read on this page here covers just the basics.