From Peyton Hall Documentation
Jump to navigation Jump to search

Here you'll find all you need to know about Secure Shell (SSH) and its usage as required in Peyton Hall

5-Minute SSH Key How-To

If you just want to setup remote access to computers in Peyton, this tutorial may be of use. But there's a lot of other information on this page you might be missing out on. Much of what is described here can be done for you via the ssh-setup script (see below).

On the machine you want to login from, do:

 ssh-keygen -t rsa

You'll have to respond with a passphrase. It may be tempting not to have a passphrase, but it's required to have one - read as, "if we find a passphraseless key we will delete it without further consultation" - and you can usually avoid having to type it more than once. You'll also need to say where to put the files; the defaults (~/.ssh/id_rsa and ~/.ssh/ are fine.

The public key ( is something you can show to others, send over email, etc. The private key (id_rsa) is something you should guard carefully; anyone with it can log in (as you) into a machine where you've authorized your public key. With that in mind, make certain no one can see your private key (or even your .ssh directory):

 chmod 700 ~/.ssh
 chmod 600 ~/.ssh/id_rsa

Now, to setup a remote machine to allow logins with this key, copy the public key ( to the remote machine (you can send it to yourself by email, or scp it using your password from a machine within the building). Then, append it to your authorized_keys file:

 cat >> ~/.ssh/authorized_keys

You'll again want to make sure things on the remote machine are sufficiently private:

 chmod 700 ~/.ssh
 chmod 600 ~/.ssh/authorized_keys

If you trust the remote system, you can also put your private key in your ~/.ssh directory there; then you'll be able to use key-based logins between computers in Peyton, or use the same ssh key to log into other sites from both home and work. But be careful with the private key - having the same private key on multiple machines makes it very easy for someone to compromise multiple systems if they can break into one. It can and does has happen, even in university physics and astronomy departments (and between them).

You'll have to type your passphrase whenever you use the key, and it may not seem any different from using a password. But with key-based authentication, one needs both the private key and the passphrase to login, so it's more secure. And, if you use ssh-agent (this is automatic on some operating systems, but there are more instructions on how to use it below), your passphrase can be securely remembered after the first time you type it while you're logged in.


What is SSH?

SSH is a secure networking protocol that uses Public-key cryptography to make sure that all data, including authentication data, is encrypted from end to end. It is similar to 'telnet' in only the fact that it lets you connect to remote computers. However, with 'telnet', 'ftp' and other insecure protocols, your user name and password are sent in cleartext to the remote side - they can be sniffed out anywhere along the network and your password recovered from the traffic. SSH uses encryption to make sure that your password is kept safe - and in fact, can be set so that your password is not even used.

Why should I use SSH?

SSH is required for all logins for security issues (described above). In a switched ethernet environment like ours, cleartext passwords aren't too much of a problem, since there's very few places where one could put a "sniffer" (which captures the network traffic) to read your password. However, in some cable modem setups and even DSL, other people can read the traffic that comes from your computer. If they're looking, and you telnet in at that moment, they've now got your user name and password and can login as you. What's more is that they may be able to exploit deficiencies in the Unix OS from that point to gain root access, and destroy data for not only you but anyone else in the department. This is not a Good Thing.

Because of that, we require that all incoming connections use SSH. We also require that all connections (except those to "Minos") use no password at all, instead using SSH public key authentication (see *IMPORTANT SSH Login Policies*). By restricting logins this way, we are able to allow logins to any machine in the building, from any machine in the world.

SSH versions

All machines in Peyton Hall run a version of OpenSSH. This was chosen over the version available from SSH Communications Security because it's free, usually gets updated more frequently, and comes with Fedora, and even MacOS X. There are a handful of other SSH programs available (see below) for other operating systems and environments. However, most have a few things in common:

  • The ability to use passwords over an encrypted link for authentication
  • Use of public key encryption for authentication
  • Tool for generating/converting keys
  • Ability to tunnel other ports through the SSH connection

Where to get SSH

Setting up a SSH environment

I have written a script called 'ssh-setup' to get you started with SSH. This will walk you through setting up a key, getting it used for authentication, and show you how to use it daily. You can run this script by entering "ssh-setup" at the command line on any of the linux machines in the department. This script will NOT explain all the details of usage, just a basic overview to get you up and running quickly; however, you will need to do a little more research to learn the details of usage. Because SSH is a complex program and protocol, there is no way to just hand you all the information you will need, so after running the script and getting some of the basics, read on for more information.


Before you can use SSH to the fullest extent - and in fact, before you can use it in Peyton Hall to login to another machine, you must create a keypair. There are a few different kinds of keys, which we'll go over here now.

Key types


DO NOT USE DSA KEYS ANY LONGER - they have been shown to be less secure, and recent versions of OpenSSH will disallow their use entirely and skip them if that is the only key present. If you only have a DSA key, you should create a new RSA key as soon as you can and replace the DSA key with the RSA one.


The first type of key we'll go over is the RSA key (in fact, if you only want to create one key, this is the one). RSA keys use the SSH version 2 (SSHv2) protocol, which is more popular and more secure than the older SSHv1 system. To create a RSA key, run the command:

ssh-keygen -t rsa

This will generate output that looks like this (don't worry, we'll go over the parts in a moment):

Generating public/private rsa key pair.
Enter file in which to save the key (/u/user/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /u/user/.ssh/id_rsa.
Your public key has been saved in /u/user/.ssh/
The key fingerprint is:
e0:48:7e:47:5c:5e:6a:ad:71:f1:eb:47:b1:ab:ae:6d user@machine.Princeton.EDU

Now, the questions asked above and what they mean:

  • Enter file in which to save the key
    If you want the key to go to a specific filename, type it here. The usual default (which maps to ~/.ssh/id_rsa) is perfectly fine for most uses, and in fact unless you have a reason for renaming the key you should leave it this way.
  • Enter passphrase (empty for no passphrase)
    Enter same passphrase again
    This is where you should enter your passphrase. To understand what this means, please see the article Passphrases. DO NOT SIMPLY PRESS ENTER!

The remainder of the output tells you the filename for the key, the public portion of the key, and the key's fingerprint - a small hash of the key itself which is slightly less unique, but easier to compare than the entire key length.

Congratulations, you have a RSA SSHv2 keypair! The remainder of this article will assume you're using a RSA key, and that its name is id_rsa (with corresponding file for the public part of the key).


RSA1 keys are a different beast entirely. These are only used with the older version 1 of the SSH protocol (SSHv1), which is no longer developed and has been proven less secure than SSHv2. If for some reason you know you need to connect to some place that does not support SSHv2, then you'll need to generate one of these keys. Again, as with RSA keys, the procedure is the same, just the key type to pass to ssh-keygen differs:

ssh-keygen -t rsa1

Converting keys

If you have a key from a remote location which uses a different SSH program, or you want to send a copy of your key to someplace that doesn't use OpenSSH-compliant programs, you may need to convert your key to make it work. Due to the number of possible programs, it's difficult to explain all the choices for converting keys, however one example is converting a key to work with the program.

ssh-keygen -e (input file) > (output file)


  • -e: tells ssh-keygen to export a key in SECSH format
  • (input file): The key file you wish to convert; may be the public or the private key
  • (output file): The file to store the converted key

Conversely, you can use the '-i' option to ssh-keygen to convert from SECSH format to OpenSSH.


In some cases, your private key file (if that's what you're converting) may need to be unencrypted first. See below for more details.

Installing your keys

A few words on the public key file

The public portion of a keypair (with extension .pub) is meant to be handed out to wherever you wish to connect. This part is used to encrypt some bit of information on the remote machine (the one you're connecting to), which is then sent to the local client. If the local client can then use your private key - either by first asking for your passphrase to decrypt it, or by use of the ssh-agent (see below) - to decrypt the information sent, then the remote server knows that the person who is initiating the connection must have the corresponding private key, and therefore is who they claim to be. If you look at the public key, it will appear similar to this:

ssh-dss AAAAB3NzaC1kc3MA.....b40HgUC4= huston@xanadu

The beginning part tells SSH what kind of key this is. The middle is the key itself, and can also be prefixed with other things if you want specific actions taken with this key (see the man page for Man:sshd(8) section "AUTHORIZED_KEYS FILE FORMAT"). The last part is a comment, which can be anything you like; the default with keys generated by OpenSSH's ssh-keygen will be your username and the host on which you created the key. This is useful when you have a lot of keys, and aren't sure which is which, as you can look at the comment to help you determine which key does what.


SSH public keys are single-lined! The entire key must be written on one line for the SSH daemon to read it, with no line breaks anywhere. When you view the key in some programs, it may appear to take up 8 lines or so, but that is simply word-wrapping in your text editor. You must make sure when copying your key to the authorized_keys file that it is all contained on a single line, or SSH will fail without any error on your end to explain the problem.

The authorized_keys file

To actually use your keys, the software must know that the key you've created is 'authorized' to login as you. In order for that to happen, the public part of the key must be listed in the file ~/.ssh/authorized_keys. The simple way to do this, and make sure that line breaks are not inserted in a key erroneously, is to do the following:

cd ~/.ssh ; cat >> authorized_keys

You can add other public keys that you want to be able to access your account to these files also. Once that's done, any holder of the private key that goes with those public keys will be able to login to the account as you. A benefit of NFS mounted home directories is that you can now login from one machine to another without using your password, just using your SSH keys, since the authorized_keys file would now exist on every machine. You'll still have a passphrase to use for each login, instead of your password, until you follow the instructions for setting up ssh-agent (see below)


Older versions of SSH would have two separate files, like authorized_keys2 and known_hosts2. This was to separate the keys used for version 1 and version 2 of the SSH protocols. Since the older versions would choke on a version 2 key in a version 1 file, this was done to keep everything somewhat together yet separate where necessary. Newer versions of SSH will read both files. You can therefore keep all your keys in just one file, ~/.ssh/authorized_keys, instead of splitting the version two keys into a separate ~/.ssh/authorized_keys2. If you happen across an older system which requires both files used, you will have to do this - but the versions running in the building here can read both types of keys in a single file.

It is VERY IMPORTANT that your authorized_keys file is non-group and non-other writable, ie a 'ls -l' should look like this:

-rw-------    1 huston   huston        676 Aug 31  2001 .ssh/authorized_keys

(They can have the group and other read bit set, but not write). Do this with the command 'chmod 600 ~/.ssh/authorized_keys*'. This is because SSH will silently ignore your keys on the server side if it sees 'loose permissions' on the file, meaning that people other than you could write to it. I say it will silently ignore them, because the server gives no indication to the user that there was any problem, just seems to ignore the keys (it will, however, output a message to the system logs).

Installing keys to (or from) remote hosts

The procedure for installing a key to or from a remote host is the same as above. Simply copy the public part of the key from the host you wish to connect from, and install it on the host you wish to connect to. So if you're using coma in Peyton, and wish to login to the host "overthere", something like this should work:

cat ~/.ssh/ | ssh overthere 'cat >> ~/.ssh/authorized_keys ; chmod 600 ~/.ssh/authorized_keys'

The 'chmod' command is to make sure that the authorized_keys file on the remote side is not set with 'loose permissions' which will cause the login to fail.


A trick I like to use is to always keep a connection open when I'm messing with SSH files. In the above situation, I would have in another window run 'ssh overthere' and had a shell running while I did the command. In this way, after I make the change, if something doesn't work I can still fix the problem through the shell I had opened previously. If, however, you make a mistake and cannot login to fix it, you may require the assistance of a system administrator to fix your files for you - and if it's 2am, it may take a little while before one wakes up to help :>

Conversely, if you wish to install a key such that you can login from "overthere" to any Peyton machine, you'll want to take the public key from the keypair you generated on "overthere", and add it to your ~/.ssh/authorized_keys file in your home directory here. The procedure is the same; just make sure to append to the file, not overwrite what you may have had there previously.

Last but not least, remember that not everyone runs the same version of SSH - there are a few out there, between versions from Unix vendors such as Sun, a commercial version from, and the open source version we run from OpenSSH. Because of this, some of these instructions may be different for other locations. They may use a different type of key (see above for converting a key to work here or elsewhere), or a different method of storing the key for authentication. Check with the systems admin for the remote site if you're having problems, since they should know what is necessary to get SSH working with your key (and they'll appreciate that you're being secure and not using a password all the time).

Changing your key's passphrase

To change your ssh private key's passphrase, use the command:

ssh-keygen -p

ssh-keygen will then prompt you for the location of the private key (the default is usually ok), your current passphrase to unlock the key, and then for a new passphrase twice to lock the key.

Please remember, a good passphrase is similar to a good password. Don't make it the same as your username, real name, repeating characters, your password, or anything else that obvious. You *can* make it long, have spacing, capitalization, and punctuation so it might even be useful to make it a sentence or a group of non-related words. See Passphrases for more information on selecting good passphrases.

SSH in Windows

HowToForge has a nice graphical howto setting up putty with SSH keys. Might want to have a look at, in addition to this section, which is more geared towards our network.

  1. Download PuTTY, Puttygen and Pageant (link above)
    All of the programs are self-contained, so they may be placed wherever you like. There is no installer to run.

You will need an authorized SSH keypair in order to login to our systems remotely. Let's generate a new keypair using PuttyGen.

  1. Double-click puttygen.exe to run it.
  2. At the very bottom of the Window, in the box for "Number of bits in a generated key", change that value to 2048
    This will generate a stronger key.
  3. Click Generate and follow the instructions to move the mouse around the window to generate randomness
  4. Once the key has been generated, type in a Key passphrase to protect the key.
    Please remember, a good passphrase is similar to a good password. Don't make it the same as your username, real name, repeating characters, your password, or anything else that obvious. You *can* make it long, have spacing, capitalization, and punctuation so it might even be useful to make it a sentence or a group of non-related words. See Passphrases for more information on selecting good passphrases.
    You will need to retype your passphrase in the "Confirm passphrase" box.
  5. Now you can save your keys. First click "Save private key".
    We recommend putting the keys in My Documents so you know where they are, and because My Documents gets backed up with TSM as well, if you use that.
  6. Type in a file name and click save (it will automatically get a .ppk extension to identify it as a putty private key).
  7. Now you need to save the public key. Click the appropriate button, type in a filename and hit save.
    It's a good idea to name it the same as your private key *without* the .ppk extension. This makes identifying the pair easy.
  8. Finally, you will want to open notepad and copy the complete contents of the "Public key for pasting into OpenSSH authorized_keys file" window into a text file and save it.
  9. You can then email the key to yourself, save the attachment in Pine or Thunderbird to your home directory, and install the key. If you're not a local user, contact us with your key, and ask to have it added to your account.

To setup your key to login to astro hosts directly:

  1. Open Putty by double-clicking the putty.exe program, and configure the session however you'd like.
    Use whatever host and various options suit your preferences.
  2. Go to Connection -> Data, and put your astro account user name in the "Auto-login username" field.
  3. Look under Connection -> SSH -> Auth for the "private key file for authentication" field.
  4. Click the browse button, select your private key file (the one ending in .ppk from above) from the list and click Open.
  5. Now look at Connection -> SSH and make sure "Preferred SSH protocol version" is set to "2"
  6. Click on Session, type in a session name under Saved Sessions, and click the Save button.
    Now, in the future, when you open Putty, you can recall your settings by just double-clicking the profile name.

When you first connect to the host, Putty might ask you to verify the server is who it says it (it'll do that for every separate host you connect to, just like ssh does). Once you've confirmed, it should tell you it's using your user name and authenticating using your public key. It will then ask you for your passphrase to unlock your private key. Type that in and press enter when done.

For more information on Putty's capabilities, refer to putty's excellent online documentation at The Putty Website.

Using SSH

Actually using SSH is very simple to do. Aside from the comments below, as always be sure to read the man pages for more information.

Basic usage

ssh <hostname>

That's it! If your local username matches the remote username, that's all there is. If not (example, local username is "user", but remote username is "me"), then run ssh like this:

ssh me@<hostname>

That tells the SSH software to login as user 'me' on the specified host.


scp and sftp are available with the SSH2 protocol to copy files to other machines. Here's a basic usage summary:

scp source destination

Either 'source' or 'destination' can be a local file, or a remote file in the form of '[user@]host:file'. For example, to copy the file 'testfile' to your home directory on coma:

scp testfile coma:.

If instead you wish to copy ~/testfile from coma to the current directory, use:

scp coma:testfile .

sftp works in a similar way, but gives a FTP-like interface:

sftp coma

This will give a secure FTP interface to your home directory on coma. SFTP requires that both machines run the same version of SSH; you can override this behavior with the '-1' flag, which will force sftp to use the older version 1 protocol (you must have SSHv1 keys created and installed for this to work):

sftp -1 coma


The ssh-agent process allows you to authenticate your private keys to the local machine, so that you can use them without typing a passphrase every time. Since you should have a long and obnoxious passphrase, this is important to save your typing - especially if you're doing something like a CVS update which would require a lot of consecutive logins.

Starting a ssh-agent

There's two ways to start a ssh-agent process; either by calling a command as a child to the agent, or installing it in the current environment. For example:

ssh-agent <command>

Running an agent this way will make the command specified on the commandline a child of the agent, so the command will inherit the agent's environment. This is important because any other children of these processes will be able to access the agent to authenticate keys. The other method of calling:

eval `ssh-agent`

This will install the agent in the current environment. Note that this does not propagate the agent's environment to other terminal windows, for example, but only works in the current terminal. As of this writing (2007/05) most of the machines in the building will either automatically start an agent when you login via X on the console, or you have some lines in your shell startup files which will start an agent when you login (or both). This way the agent has the entire X11 session as a child, and all programs can use ssh without requiring that you type a password when your keys are authenticated.

Adding keys to a running agent

Now that your agent is running, you'll need to add your keys to it to make them work. Simply using the 'ssh-add' command will do this:

$ ssh-add
Need passphrase for /u/user/.ssh/id_rsa
Enter passphrase for /u/user/.ssh/id_rsa
Identity added: /u/user/.ssh/id_rsa (rsa w/o comment)

If you have multiple keys with standard names (id_rsa, identity) they'll all be added by ssh-add. If they have nonstandard names, you can simply name them on the command line of ssh-add and all the keys you name will be tried. ssh-add will ask for your passphrase, and add the first key; if you have multiple keys, it will then try the same passphrase on all the others and add them if successful; otherwise it will ask again for the passphrase for the next key.

Now, when you attempt to login to another machine, you will not be prompted for a password, passphrase, or anything else. It should simply exchange information between the running ssh-agent, and your keys, and let you login with no hassle:

machine:~$ ssh coma
Last login: Tue Feb 19 15:08:26 2002 from machine

Forwarding your ssh-agent

When you login to a remote machine, you've used the ssh-agent on your local machine to authenticate with your keys. However, if you have a lot of keys authenticated, it's handy to forward your agent through the connection as well. This way, you can 'hop' from one machine to another, taking your credentials with you as you go and not having to run another agent on the far end and authenticate it again.

All the machines in Peyton have agent forwarding setup by default, but if you're connecting from a laptop or home computer you may wish to turn it on. You can do so one of two ways:

  1. Add the -A flag to ssh, ie ssh -A username@hostname
  2. Edit (or create) the file ~/.ssh/config, and include these lines:
Host *
ForwardAgent yes

The first method might be handy for a one-off session, while the second will turn on agent forwarding for all connections.

ssh-agent for Windows

The ssh-agent program that goes along with PuTTY is called Pageant (see above). When you run Pageant, you'll see a little computer with a fedora on it down in your system tray (next to the clock on most Windows sytems).

  1. Double-click the Pageant icon.
    A key list dialog will open. Since you haven't added your key yet, it'll be blank.
  2. Click the "Add Key" button.
  3. Browse for your key, select it, and click "Open".
  4. Pageant will ask for your passphrase; type it in and click OK.

Your key is now loaded into memory and will remain there for Putty to use until you logout or reboot.

To have Pageant start up when you login to Windows, and ask you for your passphrase right away:

  1. Right-click your Start Menu and select "Open".
    This will open a folder view of your personal start menu items.
  2. Open Programs -> Startup.
  3. Go to File -> New -> Shortcut.
    The new shortcut wizard will pop up and ask you to specify the path to the file you want to link to.
  4. Click "Browse" and find pageant.exe. Select it and click OK.
  5. At the end of the string that was just created (the full path to pageant.exe), after any quotes, type in the full path to your private key.
    You'll also want to put the file path and filename in its own set of quotes if it has spaces in it (and most likely it will). For example, if Pageant and your key are in My Documents you should have something that looks like "C:\Documents and Settings\your_username\My Documents\pageant.exe" "C:\Documents and Settings\your_username\My Documents\my_key.ppk"
  6. Click Next and pick a nice name for your shortcut (just about anything works).
  7. Click Finish.

To make sure Pageant has the right command line argument, close Pageant if you have it running (right click the agent icon in the tray and select Exit), then double-click the shortcut you just created. Pageant should pop up a dialog asking you for your passphrase. If it does, you're all set. That same box will pop up every time you login to Windows. If you get an error message, right click the shortcut, select properties and make sure you got the path and key path correct and properly quoted. Then click OK.

If you don't feel like typing in your passphrase when you first login to Windows, select cancel in the box and you'll just have to add your key manually when you want to use it.

ssh-agent for Mac OS X

Most recent versions of MacOS include an ssh-agent that starts up at login, so it should work pretty much the same as it does under Linux. If you are running an old enough version of OSX that it doesn't, you really should upgrade.


You will still need to either copy your keys from your Peyton account, or create new keys. You can use the instructions above since OpenSSH on Mac will operate in the same way.

MacOS SSH 'gotcha's

There's a couple of things to note when using SSH on a Mac:

All forwarding is turned off by default

Apple ships the SSH software on OS X so that all forwarding is turned off. In the Peyton Hall machines, when you ssh from one box to another, your ssh-agent keys and your X11 forwarding information carries through, so you can display things on the local machine from the remote one, and you can login again from the remote machine to another. In order to make the SSH software on the Mac behave like that installed in Peyton, you'll need to either create a file called ~/.ssh/config (if you want to enable it just on your account) or edit the file /etc/ssh_config (if you want to enable it on all the accounts on your Mac you will need to become root first, if you've enabled the root account, or use 'sudo' to exec your favorite editor on the file).
Host *
   ForwardAgent yes
   ForwardX11 yes
   ForwardX11Trusted yes

If you want to forward X11 connections to your Mac (for example, you want to run Matlab or Mathematica on one of our systems and display it on your Mac laptop), you will need to download and install XQuartz, as X11 is no longer included with MacOS.

Tips & Tricks

Here's a few hints, tips and tricks for using SSH which may make it more useful for you.

Automatic startup of ssh-agent

While we have this setup in Peyton for all new accounts, and many of the new machines take this a step further by starting an agent for X11 logins as well, you might have a machine at home that can benefit from this information - or perhaps a machine you use remotely on occasion. First, add to the end of your .bash_profile:

if [ "X$SSH_AUTH_SOCK" = "X" ] ; then
   eval `ssh-agent`

This checks to see if there's an ssh-agent running, and if not it'll start one when you login. You'll know it's started, since when bash hits this section it will echo the line "Agent pid [number]".

Next, to kill the agent when you logout (you don't want authenticated agents laying around the network, do you? No, you don't.) create a file called .bash_logout (or add the following to it if it already exists):

if [ "$SSH_AGENT_PID" -a "$SHLVL" = "1" ] ; then
   eval `ssh-agent -k`

This will check to see if there's an ssh-agent running in the local session (since SSH_AGENT_PID will not be set if it's a subshell, or the agent was carried over from another login), AND that the shell level is 1 (meaning this isn't a subshell on the same machine as the shell in which you started ssh-agent), and eval 'ssh-agent -k', which kills the agent and unsets the variables.

If you use an csh/tcsh, your .login file needs these lines:

if ( ! $?SSH_AUTH_SOCK ) then
   eval `ssh-agent`

And your .logout file:

if ( $?SSH_AGENT_PID && "$SHLVL" == "1" ) then
  eval `ssh-agent -k` || kill -HUP $SSH_AGENT_PID

To automatically start the equivalent process in Windows, see above.

Multiple keys in ssh-agent

If you have a lot of keys, it can be helpful to set all of them to use the same passphrase. This way, when you run 'ssh-add', you won't have to type separate passphrases for each key (it will try your first passphrase on all of them).

Since I have a few keys, I created a script (called 'keys') which I placed in my $PATH that loads all my keys for me at once:

cd ~/.ssh
ssh-add identity id_rsa id_rsa home-key other-key
cd -

SSH key comments

As mentioned before (see above), a key can have a comment attached to it. Once you get to using a lot of keys (ideally, you should have one per "system" you use), they can otherwise be hard to keep track. By making sure the comment on each key is something useful to you, it makes life easier when you need to sort through your authorized_keys file. You can also see the comments when you ask 'ssh-add' to report what keys it has loaded:

prefect:~/.ssh$ ssh-add -l
1024 cd:21:64:86:53:d7:e5:a8:04:48:c9:ed:3f:c4:b1:a7 huston@prefect-rsa1 (RSA1)
1024 84:4a:25:8f:c7:ad:0c:fc:01:d2:3e:ee:51:1c:f0:54 huston@coma.Princeton.EDU (RSA1)

You can add comments to a key with the '-C' option to ssh-keygen, either before or after the key is created. Note that the comment is attached to the public half, not the private key.

Use SSH Socks Proxy instead of VPN

SSH has a neat feature which lets you setup a SOCKS proxy over your ssh connection. This can be useful for applications which support the SOCKS protocol for proxies, generally web browsers. The net effect is that you can access websites as if you're connecting from the remote server instead of your local client. This is significantly more convenient for accessing websites for which you need to be on a specific network, like campus websites. There are two pieces to this puzzle. You need to establish the proxy and you need to tell the application you want to proxy how to use it.

Setting up the proxy for Mac and Linux systems

Just add the -D command line switch along with a port to your ssh connection to a host you want to bounce off of. Port can be anything you want (usually recommend something above 1024). 1080 is the standard port for SOCKS proxies. Example:

ssh -D 1080 user@host

This will setup a socks proxy listening on local port 1080 which will bounce off of 'host'. Next you'll want to setup your client to use a socks proxy for host localhost and port 1080. An example for firefox is further down on this page.

Setting up the proxy for Windows

TODO: Write and test instructions for a couple of the newer ways to do this in Windows 10, including Putty and native openssh -- it may not work exactly the same as Macs and Linux. If you want to contribute instructions, feel free, otherwise I'll get this done the next time I boot into Windows -LHK

Configuring Firefox to use the socks proxy

Click the overflow menu (aka 'hamburger' menu, 3-bars on the upper right side of the Firefox window), hit Preferences, scroll down to Network Settings and hit the Settings button. Select Manual Proxy Configuration Leave HTTP/HTTPS/FTP Proxy lines blank In SOCKS Proxy, enter the proxy host (usually localhost, but Windows may require you to use something different) and the port you selected for the proxy (usually 1080). Make sure SOCKS v5 is selected. You may also want to check the box for Proxy DNS when using SOCKS v5, since some campus sites won't resolve if you don't use a campus DNS server. Hit OK

From this point forward, Firefox will require that you have the ssh proxy up and running in order to browse the web (since it'll want to proxy everything over that). If you need to disable the proxy, you can go back into Network Settings and hit the No Proxy option. It will remember your settings so that they're available the next time you want to use it. If you want to make this easier, there's an extension available which lets you toggle the proxy right from the Firefox toolbar. You may want to check it out.

Using Chrome on Mac OS

I first created a new profile in Chrome by making a new directory:

mkdir ~/Library/Application\ Support/Google/Chrome/ProxiedProfile

While not completely necessary, this allows me to have a proxied connection running in parallel with my existing Chrome connections, since at least on the Mac most things want to use system-wide settings for proxies and such but this allows me to specify a different setting for just this profile. Next I set this as a function in my startup files:

proxy() {
  ssh -D $PROXY_PORT -f -C -q $PROXY_HOST 'sleep 15'
  /Applications/Google\\ Chrome \
    --proxy-server="socks5://$PROXY_PORT" \
    --host-resolver-rules="MAP * , EXCLUDE localhost" \
    --user-data-dir="/Users/huston/Library/Application Support/Google/Chrome/ProxiedProfile" &

Now whenever I want a proxied connection, I type 'proxy' at a terminal prompt. A SSH connection to coma is opened, and then a new Chrome window connects which is proxied via that connection and thus all traffic appears to come from coma.

Connecting to machines via ProxyJump

As part of the University's Secure Internet Border Initiative, most hosts can no longer be accessed via SSH from off campus. If you need to access one of these hosts, and you're using OpenSSH 7.3 or above (this covers most recent releases of Linux distros, MacOS, and Windows), you can use ProxyJump to specify a bastion host to connect to first, before it jumps to your destination host. The easiest way to make this work for ssh and other clients which use ssh (such as scp, sftp, and rsync) is to specify it in your ~/.ssh/config file:

Host * !
  User myuser

This tells ssh to always use a ProxyJump to coma when connecting to any astro host, except coma itself.

You can also do this on the command line:

ssh -J

This will connect to mydesktop by connecting to coma first, then jumping automatically to mydesktop.

The -J option only works for ssh itself. You will need to use one of a few different methods for other commands. scp and sftp need -o ProxyJump and rsync needs -e "ssh -J". Again, I strongly suggest putting this in your ssh config file as noted above since then it should just work for anything which uses ssh.

If you are using Putty on Windows, make sure you're running at least version 0.77. You can then setup a proxy host ( as documented here.

Multiplexing connections to avoid multi-factor authentication prompts

Another trick that can be used to limit the number of times you have to utilize multi-factor authentication when authenticating SSH connections is multiplexing. When you use multiplexing you're combining many SSH connections into a single authenticated connection, and just reusing that path for subsequent connections. Here's an example of how it works:

Host coma
  User myuser
  ControlMaster auto
  ControlPersist yes
  ControlPath ~/.ssh/sockets/%C
  ServerAliveInterval 30
  # This is the default, putting here to document
  ServerAliveCountMax 3

Now your first connection to coma will use whatever normal authentication methods are required, but subsequent connections will simply reuse the already authenticated path. Make sure to create the directory before you try to use this:

mkdir ~/.ssh/sockets

If you then add another stanza using the ProxyJump example above (put this below the coma entry, so coma is matched first and this matches anything else in astro after):

Host *
  User myuser

Now any connection to a host in the astro subdomain will be proxied through coma automatically, and will reuse the existing connection if it can.

Errors & Warnings

This section describes some of the errors and warnings you might see, and what they mean.

The authenticity of host...

The authenticity of host 'coma (' can't be established.
RSA1 key fingerprint is ab:cc:00:8e:c3:b0:ca:7a:00:9c:1a:87:b7:82:67:00.
Are you sure you want to continue connecting (yes/no)?

This message happens whenever you connect to a remote host for the first time. You see it because SSH has never connected to the remote host, so it doesn't know if the host key (which is generated by SSHD when the machine is first setup usually) is correct. If you wanted to be completely paranoid, you could email the systems administrator of the remote machine and verify the key manually with them; if you wanted to be even more paranoid, you could insist that the verification happen in person, so you know that nobody's intercepting the communication. But for that level of paranoia, you're better off communicating using GPG for all email instead.

In this case, you can usually just say 'yes' and you'll see a message that the host key was saved. That, however, becomes important in the next error message scenario.


Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the RSA1 host key has just been changed.
The fingerprint for the RSA1 key sent by the remote host is
Please contact your system administrator.
Add correct host key in /u/user/.ssh/known_hosts to get rid of this message.
Offending key in /u/user/.ssh/known_hosts:1
Password authentication is disabled to avoid trojan horses.
Agent forwarding is disabled to avoid trojan horses.
X11 forwarding is disabled to avoid trojan horses.

If you see this message, *do not ignore it*! This message not only means something bad could be happening, but also that certain things will not work properly. In some cases, if you're using a newer version of OpenSSH, it will not let you connect to the remote host at all; in all cases, it will disable certain services. First, let me explain what this means.

Every machine running SSH has one or more "Host Keys"; these are keys generated when SSH is installed, which are used to identify the remote machine. You've probably seen the message when you first connect to a machine that you've never used before (see above). This error, however, means that the key which it has saved in ~/.ssh/known_hosts is different than the key which it just received from the remote host. Most of the time you see this obnoxious message, either the machine to which you're connecting was replaced with a different one, or the administrator changed the keys (deliberately or accidentally through a reinstall of SSH). Regardless of the reason, you should not ignore the message. You should instead email the administrator of the machine, and ask why you got the message. Usually the admin will simply say the key was changed for such-and-such reason, and you can then follow the instructions to fix the message and continue connecting normally. You should not, however, ignore the message and blindly continue connecting, for a few reasons:

  1. The remote machine may not be the one you're trying to connect to, and any passwords/information you type may be compromised.
  2. The remote machine may be compromised itself, and any passwords/information you send is actually going to a 3rd party, either directly or stored in a file for later retrieval.
  3. If you ignore the above two reasons and decide to connect anyway, things will not function as you might expect them to.

Notice the last few lines of the above error message:

Password authentication is disabled to avoid trojan horses.
Agent forwarding is disabled to avoid trojan horses.
X11 forwarding is disabled to avoid trojan horses.

(This is the output of a newer OpenSSH program; older ones will not disable password authentication)

The first line means that you will not be given the option to type a password to login. So if you don't have a key setup between your machine and the remote one, you're not going to login anyway. The second line means that your ssh-agent authentication will *not* be forwarded (see above for what this means). The third line refers to a service that many people take for granted. X11 forwarding means that when you login to a remote machine, your $DISPLAY variable will be set to the local host, plus some number (localhost:13.0 for example). This X11 connection actually goes to the remote machine's SSH daemon, which will forward the X information down the pipe to your host. This means that when you SSH to a remote machine, you do not have to first type "xhost +remote_machine" and then on the remote machine type "set DISPLAY local_machine:0". Instead SSH will forward your X connection seamlessly, and encrypt it along the way for security. Also with the firewall we run here, you have to use SSH X11 forwarding or else your X11 connection will not be able to come back to your local desktop.

Now, let's say that you've seen the error message, didn't connect to the remote machine, and instead mailed the administrators. They inform you that the key was indeed changed by them for whatever reason, and the fingerprint you saw was the right key, so it's safe to connect. How do you tell this information to SSH? Simple, if you noticed the rest of the error messages:

Add correct host key in /u/user/.ssh/known_hosts to get rid of this message.
Offending key in /u/user/.ssh/known_hosts:1

These two lines tell you exactly where the "offending key", or the remote machine's old key, is located. In this case, it's the first one in ~/.ssh/known_hosts. Simply removing that line from the file and saving it will give you a less obnoxious message, the same one as if you are connecting to the remote machine for the first time. After answering 'yes' to the question of whether or not to accept the key into your known_hosts file, you will connect to the remote host with X forwarding turned on again, as well as agent forwarding.

BadAtom error

If you're using an FC3 or Mac OS X 10.4+ machine (or any other machine with ssh 3.8 or above), and get a message similar to the following when running an X11 program on a remote machine:

The program 'foobar' received an X Window System error.
This probably reflects a bug in the program.
The error was 'BadAtom (invalid Atom parameter)'.

You can fix this two ways:

  1. by running ssh -Y to connect to remote computers
  2. by adding "ForwardX11Trusted yes" to your ssh_config (usually in /etc or /etc/ssh), or your personal ssh config file (~/.ssh/config)

Many times, you'll only find this when running certain programs, while others work just fine. This is because of the way that "ForwardX11Trusted" works normally; certain X11 connections will work normally while others get blocked, and those that get blocked usually cause the program to crash with this cryptic "BadAtom error".

Advanced topics

These topics are a bit more advanced - beginners to SSH shouldn't need to worry themselves about them, but veterans (or those with a hunger for knowledge) may want to read on. Even if you consider yourself a beginner, you may want to browse this area anyway to get an idea of some of the more powerful things you can do with SSH, and why it's a wonderful tool in the Unix world.

Tunneling connections

You can tunnel just about any kind of connection through SSH, if you know how to setup the tunnel first. As an example, let's say you want to use POP3 to read your mail on another machine that you have login access to. Here's what you do:

ssh -L9000:hostname:110 -f hostname 'sleep 30 &'

This will setup a tunnel from the local machine, port 9000, to the remote named host's port 110. The 'sleep 30' is just to give you time to utilize the tunnel before it closes (don't worry about it closing while you're using it, SSH realizes the tunnel is still open and will wait until it's closed). Then you can set your software to connect to localhost port 9000, and it will be just like you connected to 'hostname' port 110, only everything goes through SSH so your user name and password are not sent in cleartext.


What if I'm somewhere that doesn't have SSH available?

Then you're not going to be able to connect here. *DO NOT* try to telnet somewhere that has SSH first, as you've just succeeded in giving your user name and password to whomever wants to listen. Instead, either find someplace that does have SSH access, or do without. Remember that you can always read your email with any web browser that supports encryption, see Roundcube for more information.

What does this error message mean?

If it's not listed in the above section, then contact us and we'll explain it for you (and add it there).

When I try to connect, it doesn't work

The most common problems are:

  1. Bad permissions on your ~/.ssh directory or the files in it (solution above)
  2. Having spaces and/or newline characters in your key (solution above)

If neither of these items work, and the host is one in Peyton Hall, contact us and we can look in the system logs and try to figure out the problem. If the host you're trying to connect to is remote, then contact the administrator(s) there, as we cannot know what the problem is without seeing the logs.

See also