## A short ssh-agent tutorial

Note: this tutorial is only relevant to UPC users if any of the following are true

1. You are using ssh to launch UDP-based UPC programs with upcrun;
2. You are using ssh to launch ibv-, ofi- or mxm-based UPC programs with upcrun, because spawning such programs via MPI is disabled (either when your Berkeley UPC compiler was configured, or by an environment variable setting);
3. Your Berkeley UPC installation is configured to use a remote UPC-to-C translator via ssh. (This is the case if you are asked for a password when you try to compile a UPC program with upcc).

Here is a rather abbreviated tutorial on setting up ssh-agent, which is a program that 'remembers' your ssh passwords for you.

1. You need to generate an SSH public/private key pair on the host on which you'll use upcc. Do this via "`ssh-keygen -t rsa`". You'll be asked to enter a password. Pick a good one, and remember it. The result should be two files, `id_rsa` and `id_rsa.pub,` both in your `$HOME/.ssh` directory.

2. Copy the public key file to the host where the UPC-to-C translator is located. Example: "`scp ~/.ssh/id_rsa.pub somelinuxbox.lbl.gov:`" Open (or create) your `$HOME/.ssh/authorized_keys2` file. Cut and paste the contents of the `id_rsa.pub` file into it. Make sure there are no line breaks--the contents of id_rsa.pub should show up at one line in the file. Close `authorized_keys2,` and make sure only you can read or write it (`chmod 600 .ssh/authorized_keys`). Delete the id_rsa.pub file that you copied over (`rm ~/id_rsa.pub`).

3. Test to see if everything is working so far: go back to the first host, and enter "`ssh somelinuxbox.lbl.gov`". You should see that ssh now asks you for the password to your key, not your general login password. If you don't see this, make sure all the files in your`~/.ssh` directories on both machines are readable/writable only by you, and try passing the "`-v`" flag to ssh to see what's going on.

4. Now that you can log on, you want to avoid typing your password all the time. Setting up ssh-agent will do this. ssh-agent is a wrapper program--you run it with the name of another command, like "`ssh-agent bash`", or "`ssh-agent startx`". All children of the program started by ssh-agent can share a one-time authentication you provide. Once you start bash (or X, etc.) from ssh-agent, enter "`ssh-add`", and you will be prompted for the password to your ssh key. After this, you should be able to use your key without entering your password again.

Now that we've got the basics covered, here are some more ssh pointers:

1. You can create a `$HOME/.ssh/config` file to contain settings for ssh on both a global and per-host basis. For instance, you may have a different username than your normal one on some machine. To ssh to it, you can either use "`ssh -l username hostname"`, or you can enter a "`User`" directive in your config file. Since some utilities (like CVS, and upcc), don't let you fiddle much with the way ssh/scp are invoked, you'll need to set any options like this in the config file. You can also set up aliases in the config file, which can eliminate tedious typing. For instance,

               Host falcon falcon.ccs.ornl.gov
                   HostName falcon.ccs.ornl.gov
                   User jduell
                   Compression yes
                   Protocol 2

               Host *
                   ForwardAgent yes
                   ForwardX11 yes

   Allows me to type "`ssh falcon`" and get the equivalent of "`ssh -C -2 jduell@falcon.ccs.ornl.gov`".

   You must specify global options at the end of the config file, using the "`Host *`" as the target. Here I've set up "`ForwardX11`", which allows you to run X11 programs on the remote host securely (they are tunneled over the secure connection), if not quickly. "`ForwardAgent`" tells ssh to use transitive authentication--i.e. if you enter your password via `ssh-add` on one machine, then ssh to another that accepts that key, you should be able to then ssh to a third machine that also accepts the key without ever entering your password again. Some hosts turn this off, however, so don't count on it always working.

2. Setting up your desktop machine to always run ssh-agent as the parent of `startx` makes life easy: every shell you launch on your desktop can share a single ssh-add. There are several ways to do this:

   - Your X server may already launch an ssh-agent for the entire X session by default. Apparently Debian does this.

   - If your window manager allows you to specify an `~/.xsession` file to launch programs during X startup, you can add lines in it to launch ssh-agent at startup (and also pop up a window to ask you your password). See this guide for details.

   - You can set up your computer to boot into a command line instead of a GUI login screen, and then launch X with "`ssh-agent startx`". On most Unices, the difference between booting into the GUI or not is a matter of setting the default runlevel in `/etc/inittab.` On Red Hat, for instance, you can change this simply by changing a line in `/etc/inittab` from "`id:5:initdefault:`" instead of "`id:3:initdefault:`".

   - Wade into your window manager startup script(s), and find a clever place to put an `ssh-agent` command.