ssh (secure shell) - how to use it

How should I authenticate myself
How do I use an authentication agent
How do I tunnel X11 through an ssh connection?
Using port forwarding in general
Using compression
Debugging
When things go wrong ...

How should I authenticate myself

The simplest use of slogin and friends will seem identical in terms of perceived behaviour to rlogin and equivalents, in that you will either be prompted for your normal password, or the server will honour an entry in your .rhosts file on the server machine.

You need do nothing other than type the appropriate command in order to use this authentication method.

You should be careful about using .rhosts to suppress the password check. Although ssh makes this much safer, it is still the case that you should only add sets of machines that are administratively similar and maintained to a similar level of security to your .rhosts file.

It is an extremely bad idea, except in very rare circumstances, to add machines that are on administratively separate networks to your .rhosts file

using RSA authentication

An alternative method of authentication is to use an RSA key. In order to do this, you will need to generate a key. You do this with the ssh-keygen utility. A typical interaction might involve (note use of <RTN> to indicate use of the return key):

prompt% ssh-keygen
Initializing random number generator...
Generating p: ........++ (distance 182)
Generating q: ............................++ (distance 434)
Computing the keys...
Testing the keys...
Key generation complete.
Enter file in which to save the key (/home/dir/user/.ssh/identity):<RTN>
Enter passphrase: <some random text>
Enter the same passphrase again: <some random text>
Your identification has been saved in /home/dir/user/.ssh/identity
Your public key is:
1024 35 133777033195454181308534301974704215516539776344994037802989908354767
14809022511208822265100038232396074598360105164668587433566772840306116723704
52235058852243181484380680715862992398347915669158374936097579417481571914065
09059282441280449801889096111489361541665530985707255386642739026912791701192
792431243 user@host
Your public key has been saved in /home/dir/user/.ssh/identity.pub

You should always use a good passphrase when you create your private key - this will protect against compromise of the machine on which you store it, or of the network across which the file containing the private key may be NFS exported. As a rough guide, a passphrase should be between 10 and 30 characters long, and not consist of a simple sentence, as English words in normal sentences only generate one or two bits of "entropy" in the resulting passphrase (ie the information content of each word is surprisingly low). On the other hand, it shouldn't be so random and unmemorable that you find you have to write it down.

In order to use your key, you need to make sure that any machine you wish to connect to knows the public half of the key. You can do this by copying the contents of the public key file (/home/dir/user/.ssh/identity.pub in the example above) to the file named $HOME/.ssh/authorized_keys (where $HOME is your home directory) in each case.

Once you've done all this, you will find that instead of the interaction that you're used to with slogin and friends, in which you were probably prompted for a password as:
user@host's password:
you will now get prompted as follows:
Enter passphrase for RSA key 'user@host':
and should then type in the passphrase that you used to encrypt the file containing your private authorization key when you ran ssh-keygen originally.

This doesn't seem to have gained us anything over using straight password authentication, but seems to require more typing of passwords/passphrases than rhosts with RSA host authentication, so why should we bother?

The reason to use RSA authentication is that we can set up an authentication agent to do all the hard work of sending RSA authorization keys for us, and save ourselves a lot of work without noticeable loss of security.

How do I use an authentication agent?

Ideally what we want is for every session we establish to be able to use the authentication agent, so we never have to bother with typing pass phrases. We just want to type a pass phrase once when we turn up at our computer ...

For the moment, assume that the intention is to sit down in front of a machine running X11, and for all the remote logins we run in various windows to be authenticated for us. There are two possible cases:

you start the X11 server yourself using xinit or startx: In this case, your window manager (and subsequently all the X11 programs such as xterm that you run from it) will be child processes (or descendants) of a process that runs the file $HOME/.xinitrc.
you log in to a terminal that's already running an X11 server: In this case, the terminal will initially have a window for you to type your login name and password into (ie it is running xdm, dtlogin or vuelogin. When you have logged in, it will run your window manager and any other X11 programs such as xterm as child processes (or descendants) of a process that runs the file $HOME/.xsession.

The simplest way of dealing with this is to put the line
eval `ssh-agent`
(note that those are back-quote symbols) at the beginning of both $HOME/.xinitrc and $HOME/.xsession files. You will also want to put the line
ssh-agent -k
(note that there are no back-quote symbols in this case) at the end of these files. If the last thing previously in these files was run with exec then you should remove that word (ie replace
exec fvwm
with
fvwm
This latter command will seek out any running ssh-agent process and kill it. Once our X11 session has shut down, we have no requirement for an authentication agent any more, and it is preferable (more secure) for it to no longer be active.

Note that we have set things up so that there is an authentication agent that any instances of slogin, ssh or scp called in that X11 session will know about and use, but we haven't told it any authentication keys. So sometime we will need, in any window we have available, to run the ssh-add command for any identities we wish to have automatically authenticated. Alternatively if you run ssh-add < /dev/null, it will run the program with an X11 interface that you can type into - this can usefully be integrated into your .xsession file.

Note also that if you leave your terminal unattended in this state (ie after you've used ssh-add), anyone wandering up to it will be able to log in to any of the machines that trust your authentication key. This is no more insecure than if you had a .rhosts file trusting the machine, but re-emphasises the need to be careful about leaving terminals unattended for any length of time.

How do I tunnel X11 through an ssh connection?

This should be a fairly simple section - if either slogin or ssh notice that the DISPLAY environment variable is set on the client side, they will automatically set up an X11 forwarding tunnel on the connection. Thus, all you should need to know is that, if your local session can start X11 programs successfully, and you run an ssh session to a remote machine using slogin or ssh, then you should be able to start X11 programs in the remote session and have them display locally without needing to do anything special at all.

However, if you want to know more detail as to how this works, they do several things to do this:

On the server (remote) side, set up a dummy X server listening on a different port than normal (normally adding 10 to the default port number).
On the server (remote) side, set the environment variable DISPLAY in the user's session to servername:10.0 (or 11.0 if it had to use the port 11 away from the default, because the tenth was in use, etc.).
On the server (remote) side, arrange for a suitable random X authorization token ("magic cookie") to be used by the dummy X server.
On the server (remote) side, arrange for the authorization token that it has invented (see previous item) to be inserted in the user's $HOME/.Xauthority file.
Arrange for ssh port forwarding between the dummy X server on the server (remote) side, and an X protocol forwarder on the client (local) side.
On the client (local) side, set up an X protocol forwarder that accepts forwarded X connections from the ssh tunnel, fixes the authorization token to be one extracted from the local $HOME/.Xauthority file for the current (local) value of the DISPLAY variable, and passes the X connection on to the X server indicated by that DISPLAY variable.

Using port forwarding in general

If you need to use this, you should only do so if you are capable of acquiring and understanding the documentation provided with the ssh package. Briefly, this facility has been disabled on CUED machines for operational reasons. However, providing care is taken and disruption is not caused, there is no reason for an individual not to run their own sshd configured to support port forwarding.

Using compression

There are several different questions to be answered here:

"How do I use compression?" is very easily answered - all the ssh family of programs take a -C flag which causes compression to be switched on.
"When should I use compression?":
- Reasons to use compression
  - connecting via a modem
  - connecting via some other slow connection
  - highly compressible data
- Reasons not to use compression
  - slow processor at one or other end of connection
  - working across local network connection (ethernet or faster)
  - data already well compressed or difficult to compress
  - running programs that require minimum latency interactions
Basically, if you're connected across a slow link, and transferring ordinary files, you can easily get anywhere between a doubling of speed and a factor of five speedup in file transfer. If however, you are using scp to copy a file that has already been compressed (for instance has a .gz or .Z suffix, then it is very likely that attempting to use compression will actually slow you down.
An example of highly compressible data that may well benefit from the use of compression would be the bitmaps frequently transferred during the typical X11 session. So if you were using X11 connection forwarding through an ssh session, compression might well help you.
However many X11 programs behave sub-optimally when there is significant latency (ie delay) in the interactions between keyboard/mouse and the program. Unfortunately the process of compressing data unavoidably introduces additional latency - this can result in undesirable behaviour with some programs. See the section on compression tuning for more relevant information, however.
How do I tune compression?: the compression algorithm used in ssh is the same as that used by gzip, and can be similarly tuned to be fast-and-not-so-good or slow-and-effective. This is done by setting the CompressionLevel option to a number between 1 and 9 as follows:
- slogin -C -o CompressionLevel=1 remotehost
  will use fast, lower-latency and comparatively ineffective compression.
- scp -C -o CompressionLevel=9 host:file newfile
  will use the slowest, highest latency and most effective compression.
The default compression level used if the -C flag is used with no additional CompressionLevel option is 6, which works well for most cases.

In summary, there is no point in using compression unless you're on a slow link. It will be of benefit when transferring files that aren't already compressed, and may be of use when running remote X11 applications.

Debugging ssh

The simplest way of debugging ssh is to use the -v flag to get the client to indicate what it's doing. If you can't determine what is going wrong from this, you will either need expert assistance, or access to a ssh server that you can control and run in debugging mode.

When things go wrong ...

server key changed

If you see something like

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@       WARNING: HOST IDENTIFICATION HAS CHANGED!         @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the host key has just been changed.
Please contact your system administrator.
Add correct host key in /home/snake1/jpmg/.ssh/known_hosts to get rid of this message.
Agent forwarding is disabled to avoid attacks by corrupted servers.
X11 forwarding is disabled to avoid attacks by corrupted servers.

This indicates that the host public key that your client believes is valid for the server you're trying to connect to doesn't match the host key that the server is using.

As the message indicates, it either means someone is trying to subvert your connection, or that a system administrator has for some reason changed the host key for the server.

You should at this point contact the administrator of the server in question to find out what is happening.

server key not yet known
If you see something like
```
Host key not found from the list of known hosts.
Are you sure you want to continue connecting (yes/no)? 
```
this just means that your client doesn't yet know a host key for the server you're connecting to. If you believe it is unlikely that anyone is going to choose precisely this time to attempt to intercept and spoof your attempt to connect to the server in question, then saying yes at this point will result in the server host public key being added to your (but not the client machine's) list of known hosts.
my authentication agent doesn't automatically authenticate me
You have remembered that you need to use ssh-add to tell the authentication agent about any authentication keys you want it to know about, haven't you?
ssh-agent still doesn't seem to do the right thing
One possibility is that ssh-agent is guessing wrongly as to what kind of shell you're using. When it is run without any other arguments, it tries to guess your shell, and outputs appropriate text to set environment variables in that shell. If it guessed wrong, the environment variables that need setting for correct operation won't be.
If you're running bash, ksh, sh, or any other Bourne-shell derivative, try running ssh-agent with the -s flag. If you're running csh or tcsh then try running ssh-agent with the -c flag.
I've got lots of ssh-agent processes running
Make sure you're calling ssh-agent -k at the end of your X11 session (look at the section on using an authentication agent for details).
my slogin process won't die
This is most commonly because there is still a tunnelled connection that is utilising the ssh session. This will most often be an X11 client, although it could equally be an authentication agent forwarding, or indeed an arbitrary port forwarding that you've set up. You will need to try and identify any X11 clients or subsequent log in sessions to other machines that were started from within the ssh session, and kill them off.
There is a bug in ssh-1.2.26 (at least, and possibly more recent versions), that on some operating systems causes an ssh session to fail to succesfully shut down the tunnelled connection that it sets up for authentication forwarding. This will cause the session to hang as it tries to shut down, listing one or more authentication forwarders as still being active.
If you really can't get the tunnelled connection to die properly, you can use the escape sequence ~. (tilde followed by period) to force it to disconnect. Note that this escape sequence is also trapped by the rlogin family of programs, and so nested rlogins and slogins may not behave quite as you expect if you use the escape sequence.
slogin from a session on a vt220
It has been observed that attempts to use slogin from a session running on a vt220 terminal acting as a machine console, results in a number of normal ascii printing characters being re-mapped to control characters or otherwise mis-behaving. A fix for this is not known at this time.
X11 forwarding fails to work
X11 forwarding has very occasionally been observed to fail - an incorrect authorization cookie appears to get inserted in the ~/.Xauthority file. A reliable cause for this has not yet been established - any further information about this to bugs@eng.cam.ac.uk welcomed.
Update There appear to be two causes for this. One is a bug in the X11R6.4 libX11 library that causes it to try to optimise X11 connections that it believes to be to the local host - unfortunately it is is overeager to do this, and so tries to use a local unix domain socket to communicate with the tunneled ssh X11 connection (which is not at all sensible). For a fix, contact jpmg@eng.cam.ac.uk.
The second is that certain kinds of X11 session can insert entries in the ~/.Xauthority file that cause the ssh X11 tunnel to fail to correctly authenticate itself. The precise nature of this is yet to be determined, but cleaning out all old un-needed entries in the ~/.Xauthority file should help.
anything else
If you find any other misfeatures in the ssh programs installed in CUED , please contact bugs@eng.cam.ac.uk, giving as much detail as possible.

[Help]

Updated on 8th October, 1998
Patrick Gosling

jpmg@eng.cam.ac.uk