Using X-Windows (X11) and secure shell (SSH) to connect to a remote UNIX server (host)

Using the Desktop SSH agent to manage your identity keys

X-Windows (X11) and SSH software let you run certain types of software on a remote UNIX server (host) while displaying and controlling the software's graphical user interface (GUI) on your local desktop system. In a cluster computing environment, X11 and SSH are typically used to connect to the cluster's head node as illustrated below.
cluster computing environment

Linux desktop use

Standard Linux distributions come with OpenSSH (e.g. OpenSSH_4.3p2 ), a bash shell (e.g., GNU bash, version 3.2.25), and an X11 server (e.g., X.Org version: 1.4.2 ). Each account on the desktop has a home directory for the storage of private files. Inside this home directory, there is a hidden directory (.ssh) that OpenSSH uses as a place for a configuration files and keys. There are identity keys, host keys, and authorized keys stored in special files. Linux users should set up the home directory for accounts which will be used with remote connection services.

The SSH agent and agent forwarding increase productivity when you are using OpenSSH. It is possible that your Linux desktop is already setup with an SSH agent. To test your agent, type the command:

ssh-add -l
If you get a message like "The agent has no identities." then you have an SSH agent running. (This is what happens with newer MacOS desktops).

If however, you get a message like "Could not open a connection to your authentication agent." then you do not have an agent to connect to. Go the the document Linux Desktop Configuration with Bash for a tutorial showing how to use the bash shell with an ssh-agent connection defined.

Note on typography: The example sessions show prompts in bold and typing hints in red. Several of the prompts are for secret passphrases or passwords, which are not displayed as you type (not echoed). Do not leave them empty or type the hint, e.g., -- some secret --.

This tutorial assumes you have an ssh-agent connection established (checked with the ssh-add -l command). As you proceed through the steps, you will be adding files to the hidden SSH ( .ssh ) directory within your home directory .

Generate your identity keys

Your identity is established by a public/private key pair. The process below will set the keys with a comment and a passphrase. The comment is stored in the private key file and may appear when you are asked for the passphrase. You will need to supply the passphrase to establish your identity.
  1. Start with a window open in your home directory.
  2. Type the bash command ssh-keygen with a comment as a hint to remember the new password you will set. Choose the default file name when asked.
    [jdoe@laptop ~]$ ssh-keygen -C "laptop Jan4"
    Generating public/private rsa key pair.
    Enter file in which to save the key (/home/jdoe/.ssh/id_rsa): 
    Enter passphrase (empty for no passphrase): -- new secret --
    Enter same passphrase again: -- repeat secret --
    Your identification has been saved in /home/jdoe/.ssh/id_rsa.
    Your public key has been saved in /home/jdoe/.ssh/
    The key fingerprint is:
    82:9a:02:fb:b2:72:68:ef:8b:e6:6e:45:ca:1f:0f:1b laptop Jan4
    [jdoe@laptop ~]$

    Note: Some installations may require a key length and/or type. The ssh-keygen options -b 2048 -t rsa work well.

Configure SSH for remote host connections

In addition to your desktop Linux system, you will be using remote hosts as services. To use a service, you will need an account on the service host (for example, account joedoe on the HPC host In addition, you may have accounts on other service hosts (for example, account train15 on the training host You will choose a service name for each host and add lines to your .ssh/config file. Include the account name (User), the host name (Hostname), and any SSH options you may want on this host (for example, ForwardX11 and ForwardAgent).

  1. To configure a "compute" service for your joedoe@mills account, add the lines to your .ssh/config file:
    Host compute
    User joedoe
    ForwardX11 yes
    ForwardX11Trusted yes
    ForwardAgent yes
  2. To configure a "train" service for your train15@centos account, add the lines to your .ssh/config file:
    Host train
    User train15
    ForwardAgent yes

Add your public identity key to the remote authorized keys file

Start with a window open in your home directory.

  1. Type the command ssh-add to add your newly created identity to the ssh agent.
  2. [jdoe@laptop ~]$ ssh-add
    Enter passphrase for /Users/jdoe/.ssh/id_rsa: -- known secret --
    Identity added: /Users/jdoe/.ssh/id_rsa (/Users/jdoe/.ssh/id_rsa)
    [jdoe@laptop ~]$

    Note: You need to repeat this step if you want to use your identity. The desktop SSH agent is available to all windows and applications on the desktop. You only need to do it once per desktop session. It is usually possible to have your identity added for each desktop session. Consult your desktop documentation.

  3. Assuming you used compute as the service name (as in the config file above), connect to this service with the ssh compute command. If this is the first time you have connected to this host, you will be asked to continue (answer "yes"). Then you will be asked for your remote account password:
  4. [jdoe@laptop ~]$ ssh compute 'ssh-add -L >> .ssh/authorized_keys'
    The authenticity of host ' (' can't be established.
    RSA key fingerprint is 56:b7:cf:1f:ac:6c:85:f7:49:79:fa:b8:df:19:66:cb.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added ','' (RSA) to the list of known hosts.'s password: -- known secret --
    [jdoe@laptop ~]$
  5. You may add other remote hosts to your .ssh/config file, for example, train, by repeating the last step. If you return later to configure a new remote host, repeat step 1 to add your identity.
  6. Note: If you get a .ssh/authorized_keys: No such file or directory message from the remote host, you do not have your SSH directory set up on the host. The easiest way to fix this is to log on to the host and generate your identity there.

Test the ssh services with X11

Start with a window open in your home directory. If you do not have any identity keys in your SSH agent, you can add them with the ssh-add command.

  1. Test the X11 configuration by typing the UNIX command ssh train xclock -bg green. A green xclock should appear on your X11 display:
  2. [jdoe@laptop ~]$ ssh compute xclock -bg green

    Note: If this test fails, either you do not have the ForwardX11 option set, you do not have X11 configured properly on the the remote host, or you may need to explicitly start an X11 server on you desktop.

  3. You should not get a shell prompt. To stop the clock, close the xclock window (You can also type a CTRL-C in the shell window). You should now have the shell prompt:
  4. [jdoe@laptop ~]$
  5. Remove the added identity from the ssh agent with the ssh-add -d command.
  6. [jdoe@laptop ~]$ ssh-add -d
    Identity removed: /home/jdoe/.ssh/id_rsa (/home/jdoe/.ssh/
    [jdoe@laptop ~]$

Helpful Tips

At this point, your SSH directory is populated with all the necessary keys and a configuration file with two services: compute and train and you have tested your use of X11. You do not need to do this again to use these two services with your desktop.

Start a new window and type the ssh-add -l command to check to see if you have any identity keys. If you need to add a key, use the ssh-add command to add your home directory key with a passphrase. where you intend to work on remote hosts. This way you only need to supply your passphrase once.

While you have an identity key, consider these tips as ways to log in to a service or use your services to extend your local shell.

Following is a list of possible commands you can use at the shell prompt:

  1. Log in to a remote host. (No password or passphrase is required.) This example confines all commands to one window with the shell prompt, jdoe@laptop or joedoe@mills, indicating where your shell command will be executed. It is easier if you use the same shell on all systems.
  2. [jdoe@laptop ~]$ ssh compute
    Last login: Wed Jan  4 15:04:02 2012 from
    [joedoe@mills ~]$

    The session on the remote host (mills) continues in the same window. Type the exit command to log out of mills and return to your original shell prompt (laptop).

    [joedoe@mills ~]$ exit
    Connection to closed.
    [jdoe@laptop ~]$
  3. Start a new window that is logged on to a remote host. This example opens a new xterm window on the remote host and returns to the jdoe@laptop prompt for more commands.
  4. [jdoe@laptop ~]$ xterm -e ssh compute &
    [2] 29879
    [jdoe@laptop ~]$

    A Last login: line and the joedoe@mills prompt will be appear in a new window. All commands typed in this window will be executed on the computer server. Typing exit will log you out from the server, and close the window. The xterm will be running on your local machine with process id 29879. You may use other X11 terminal emulators that are on your local desktop. For example, you may use gnome-terminal -x in place of xterm -e.

  5. Log in to a remote host in a new window. In this example, the xterm is running on the remote host, which allows you to execute a remote host command such as screen illustrated in example 4 below.

  6. [jdoe@laptop ~]$ ssh -f compute 'xterm -ls'
    [jdoe@laptop ~]$ 

    The joedoe@mills prompt will appear in a new window. The xterm will be running on the remote machine. Typing exit will log you out of the server and close the window. You may use any X11 terminal emulator that is installed on the remote host.

  7. Executing a remote command in a loop. This example shows how to execute a loop to distribute the work to multiple services. You do not normally type loops and the command line, but the same basic loop can be done in a script. If you add the option -f to the ssh command then the commands on the services will be forked and you can run them concurrently.

  8. [jdoe@laptop ~]$  for h in train compute; do
    > ssh $h 'hostname && uptime'
    > done
      18:00:36 up 265 days,  7:37,  1 user,  load average: 0.00, 0.00, 0.00
      18:00:37 up 19 days, 14:33,  4 users,  load average: 0.38, 0.22, 0.19
    [jdoe@laptop ~]$  

    This will echo the SSH services train and compute and then output from the hostname && uptime compound command on each host. Make sure you put compound commands in single quotes to make sure both parts execute.

    When you are done with the home directory key, you should remove it with the ssh-add -d command. Remember that the SSH agent is configured in the desktop and all applications can use your identity while it is added to the agent.