SSH - Secure Shell

This tour describes the steps to remotely connect to a UNIX machine with graphics forwarding. Some of it is specific to servers running at Cal Poly San Luis Obispo but the basic setup instructions are likely universal.

We need the ability to work on a remote computer from the command line of a terminal on the computer in front of us by using the network to connect. We also want graphics from the remote computer to display on our local machine. To do that we need a program that will connect to the machine and a protocol for passing the graphical information back and forth.

ssh is a program that encrypts all communications between the local and remote computer. Because graphical information is data-intensive, ssh does not allow remote graphics by default. In order to force ssh to forward graphical output, we have to give it the flag -X, that stands for "X forwarding". "X" is the graphical windowing system used on UNIX machines, such as the dirac cluster.

Preface: X Forwarding

• Unix machines have been able to run software on a remote machine and display the GUI locally for almost two decades.

• Linux machines support X Forwarding with no extra software. Any terminal on Linux should do X Forwarding.

• Mac OS X machines need a program called Xquartz (for versions > 10.6) and the Terminal app.

• Windows users need two pieces of software: a secure shell program (ssh) to establish the remote connection and an X Server to handle the local display.

Getting started on Linux

Linux supports X Forwarding with no extra software. Any terminal on Linux should do X Forwarding. To connect to a remote machine with X Forwarding enabled, just use the -X flag with ssh:

$ ssh -X <username>@dirac5.calpoly.edu

where you replace <username> with your Cal Poly username.

Getting started on Mac

The X forwarding system is not built in to Mac OSX by default (except in 10.7) but can be downloaded and installed relatively painlessly. As long as you are running any version $\ge$ 10.7, you can get an X server from the XQuartz project. Download, install it and then follow the instructions that say to log out and back in to make the changes work. For versions earlier than 10.7, things are more complicated. Come see me for help.

For versions $<$ 10.8, you may need to update your ssh configuration settings to allow X11 forwarding from the dirac cluster. Use nano to create a file called ~/.ssh/config:

$ nano ~/.ssh/config

(note the placement of the . in front of ssh) with the following lines in it:

Host dirac5.calpoly.edu
ForwardX11 yes
ForwardX11Trusted yes

Now to connect to a remote machine with X Forwarding enabled, just use the -X flag with ssh in a terminal window:

$ ssh -X <username>@dirac5.calpoly.edu

where you replace <username> with your Cal Poly username.

Getting started on Windows

Many of you will connect to the Dirac computing cluster via a PC running Windows, essentially making the PC a terminal. The PC interacts with the server through the X-windows system, forwarding the display from the server to the PC. Software must be installed on the PC to make this link work and the best software (so far) for this task is the PuTTy terminal emulator and the Xming X-window client. PuTTY is a free SSH client. Through PuTTY we connect to a remote machine on campus. Xming is a PC X Window Server. This enables programs being run remotely to be displayed on your desktop.

You can download PuTTy, Xming, and Xming-fonts installers from these sources:

• PuTTy: http://the.earth.li/~sgtatham/putty/latest/x86/putty-0.63-installer.exe
• Xming: http://sourceforge.net/project/downloading.php?group_id=156984&filename=Xming-6-9-0-31-setup.exe
• Xming-fonts: http://sourceforge.net/project/downloading.php?group_id=156984&filename=Xming-fonts-7-5-0-70-setup.exe

For details on setting them up once they are downloaded, have a look at

• PuTTy: https://rcc.its.psu.edu/user_guides/remote_connectivity/putty/
• Xming: https://rcc.its.psu.edu/user_guides/remote_display/xming/
• Xming-fonts: Be sure to check boxes for the 100dpi and the DejaVu TTFs

The only difference is that you will use dirac5.calpoly.edu for the hostname when you configure PuTTy.

Basic Workflow:

Below is what we did in class the first time we logged in to dirac and set up our environment. After that initial setup, you only need to do items 1, 4, and the first part of 5, remembering that after logging in, before you do any work, do a git pull origin master to make sure you are up to date with the remote (github) repository.

Using ssh to connect to the dirac cluster

This opened a firefox session on dirac, but the graphical window appeared on our local machine. When we were done, we closed the firefox window but our terminal window was still running the python kernel. To exit from the notebook completely, we also had to type <ctrl>-c once or twice in the terminal to get the command line prompt back.

1. Open a Terminal window and connect to a remote computer (in this case, the dirac cluster) using ssh (secure shell). Here is the command we enter to log onto dirac5:

$ ssh -X <username>@dirac5.calpoly.edu

2. Once we are logged onto dirac for the first time, we have to set up our environment to have the paths to all of the programs we want to run in our PATH variable. Instead of having everybody type in the contents of the .bash_profile file, we can use the copy command cp, to copy jklay's file to our home directory. To do that enter the following command:

$ cp ~jklay/.bash_profile .

The ~jklay part is a shortcut to jklay's home directory. This same shortcut will work for any user account on the machine. The "dot" at the end of the command tells the copy command to copy the file with the same name as the source file in the current directory. As we have seen, the general form of the command is

$ cp <source> <destination>

where the source is a file and the target can be either a new filename, a path to a directory or a path plus filename. Since we just created the file, our environment hasn't been configured yet. Either log out and back in again or source the file so that the aliases and PATH are set for the current session:

$ source .bash_profile

3. We can clone our github repository to dirac so that whenever we work on that machine, we have our repository available.

$ git clone https://github.com/<github-username>/<github-reponame>.git

This is the standard git checkout command, or you can open a browser window and copy the link directly from your github site.

Set up the global configuration of git by cd-ing to the repository directory and source-ing the configure script:

$ cd PHYS202-S14
$ source ConfigureGit.sh

4. Verify that you can run the ipython notebook with our newly configured environment.

$ ipynb

This opens a firefox session on dirac, but the graphical window appears on our local machine. When we are done, we can close the firefox window and type <ctrl>-c once or twice in the terminal window to stop the python kernal and to get the command line prompt back.

5. Before logging out of dirac, practice the workflow of checking the git status and making sure our local (on dirac) changes are in sync with the remote (github) repository.

$ cd PHYS202-S14
$ git status
$ git add <ANY MODIFIED/CREATED FILES>
$ git commit -m "<MESSAGE>"
$ git push origin master
$ git status
$ exit

To log out of dirac type exit at the command line prompt. Now we are back on our local (180-272) computer again. Check the git status of the local (180-272) repository before proceeding to work.

$ cd
$ cd PHYS202-S14
$ git status
$ git pull origin master
$ ipynb

All content is under a modified MIT License, and can be freely used and adapted. See the full license text here.