Docs/User Guide

Introduction
This is a guide to using the St. Olaf Beowulf Clusters through the command line interface. If you haven't already, [mailto:beowulf@stolaf.edu contact us] to discuss your project and get an account on the development cluster. Depending on your programming experience, we will direct you towards resources for developing Beowulf cluster software. Or, you may want to work with a Computer Science student to develop software. If you decide to write your own software, you are ready to connect to the development cluster and begin programming. If you are working with someone else to develop software, you may still want to read this guide so you are familiar with running programs on the clusters.

Connecting to the Development Cluster

 * 1) Make sure you have a development cluster account. You or someone in your team should [mailto:beowulf@stolaf.edu contact the Beowulf Project Team] to get access to the development cluster. The development cluster and the production cluster are separate systems, and you might not have access to the production cluster while you are in the early stages of your project. Once you have access to the development cluster, you use your St. Olaf username and password to log in.
 * 2) Make sure you have the right software to connect. Currently, the only way to use the Clusters is through the command line interface using Secure Shell (SSH). Instructions for using SSH varry by platform.
 * 3) * Windows - We recommend a free program called PuTTY. On a St. Olaf machine, you can find PuTTY in the Start menu under St. Olaf Apps. Enter  in the Host Name box and click Open. A terminal window will open where you can enter your St. Olaf username, followed by your St. Olaf password.
 * 4) * Mac OS X - Open the Terminal application in the Utilities folder of Applications. Enter the following: ssh [username]@castaway.public.stolaf.edu where  is your St. Olaf username. You will be prompted for a password, which is your St. Olaf password.
 * 5) * Linux - Most Linux distributions include an SSH client that can be accessed from any terminal. Look for online documentation for your Linux distribution if an SSH client is not available. Once you are in a terminal, enter the following: ssh [username]@castaway.public.stolaf.edu where  is your St. Olaf username. You will be prompted for a password, which is your St. Olaf password.
 * 6) * Note The first time you connect to each of the Clusters, you may be asked a question about an SSH key. Type or click Yes so that you continue connecting to the Cluster.
 * 7) Verify that you are at the command prompt. You should now see a command prompt similar to [13:15:14 frederit@c-admin ~]$ with the current time and your username.

Editing or Uploading Programs and Data

 * 1) Decide what programs you will run on the cluster. You may choose to edit source code while logged in to the cluster using a program such as   or  . Or, you may want to upload programs from your own computer to the cluster. Save anything you are working on to your home directory , where   is your username.
 * 2) If necessary, upload programs and data. Use SCP to upload files from your own computer to the cluster. SCP is similar to FTP, but it operates over SSH and thus encrypts your data as it is transfered. Instructions for using SCP varry by platform.
 * 3) * Windows - We recommend a free program called WinSCP. On a St. Olaf machine, you can find WinSCP in the Start menu. Enter  in the Host Name box, enter your username and password and the appropriate boxes, and then click Open.
 * 4) * Mac OS X - Open the Terminal application in the Utilities folder of Applications. Enter the following: scp [localfile] [username]@castaway.public.stolaf.edu:~/ where  is your St. Olaf username and   is the file you want to copy from your local machine. You will be prompted for your password.
 * 5) * Linux - Most Linux distributions include an SCP client that can be accessed from any terminal. Look for online documentation for your Linux distribution if an SCP client is not available. Once you are in a terminal, enter the following: scp [localfile] [username]@castaway.public.stolaf.edu:~/ where  is your St. Olaf username and   is the file you want to copy from your local machine. You will be prompted for your password.
 * 6) * Note The first time you connect to each of the Clusters with SCP, you may be asked a question about an SSH key. Type or click Yes so that you continue connecting to the Cluster.
 * 7) * Note Don't confuse SSH with SCP. SCP is based in part on SSH, but you will usually use different software to copy files with SCP than you use to open a terminal with SSH.

Distribute your Program to the Cluster Nodes
The following instructions are for launching programs with MPI. You may launch programs you have written in C using the MPI libraries, or you may launch ordinary sequential programs. Programs written with MPI can communicate between nodes, while sequential programs run independently on each node. All software on the Clusters must be compatible with our distribution of Linux. See the end of this guide for instructions on compiling MPI programs.


 * 1) Decide what files every node will need to run your program. When you launch a program with MPI, the same program is launched on each node of the cluster that is allocated to you. So, your program must be copied to the same location on each node. We accomplish this with a   directory. You copy your program and data to this directory and then run a command that distributes these files to all cluster nodes. If your program uses any data files, you must copy those files as well.
 * 2) Copy your program and data files to the data directory. Use the   command to copy your files to , where [username] is your username. Make sure you copy your executable program and any other files that your program needs to run.

Run Your Program

 * 1) Make sure you have an allocation of cluster nodes. A [mailto:bw-root@stolaf.edu Beowulf Project administrator] must assign a subset of the Cluster's node to you when you want to run a program. You can see what nodes are assigned to you by entering cat /home/[username]/hostfile, where   is your username. If this file is empty, [mailto:beowulf@stolaf.edu contact us]. The number of lines in this file is the number of nodes your programs will run on.
 * 2) Run your program by entering run-application /home/[username]/[programfile], where   is your username and   is your executable program.
 * 3) Collect output. You will see the output from all nodes running your program on your terminal.

Backup, Cleanup, and Logout

 * 1) Backup your data. The Beowulf Clusters are not designed to store data for long periods of time. Whenever you write a program or generate data, make sure you download your files with SCP and save them to your local computer. The [mailto:beowulf@stolaf.edu Beowulf Project team] can help you backup any large files you may have.
 * 2) Delete unneccessary large files. Space on the Clusters is limited. If you have any large data files, please remove them from your   and   directories when you are finished with them. The system will periodically delete files from nodes that are no longer in your   directory.
 * 3) Logout of the system using the   command.

Compiling MPI Applications
When compiling using the gcc suite, the traditional commands include gcc, g++, and so forth. Replace each of these commands with one of the equivalent following:


 * mpic++
 * mpicc
 * mpiCC
 * mpicxx
 * mpif77
 * mpif90

These commands pass on some additional flags to the [gcc | g++ | etc] executables so that they know where to find the mpi headers and libraries.

Reporting problems
Take these steps to report a problem:


 * 1) Search the wiki that you are on now to make sure the problem has not already been documented and fixed
 * 2) Send an email to [mailto:bw-root@stolaf.edu bw-root@stolaf.edu].
 * 3) Contact a current administrator if you hear no response.