Basic Usage

Setup Locations

The Setup Locations screen allows for choosing a one or more locations on which to install the package. The user must have a valid login for each machine listed and the machine must be reachable via secure shell (SSH). Locations can be inserted using a regular expressions to define multiple locations with similar names. For example, entering a location as someone@somewhere[0-2].example.com would create three locations of someone@somewhere0.example.com, someone@somewhere1.example.com, someone@somewhere2.example.com. If a group of machines will be used for the installation of several packages, the user may wish to write a script file containing the list of machines. An example of such a file exists later in this document.

Figure 1. Setup Locations

Setup Locations

This screenshot shows the setup locations dialog of the ReST Installer. This user has setup 8 locations on which the software should be installed.

Setup Logical Groups

A logical group should consist of locations grouped by filesystems and binary compatibility. In other words, if five machines share a common filesystem and programs compiled on one machine may be run on all, then these machines should be placed in a logical group. By creating logical groups, the Rest Installer is able to reduce the network traffic, file space and time needed to install the package. Two important entities exist among logical groups: build masters and file masters. When installing a package, some parts of the package may only need to be executed on one machine for every machine in the group to benefit from that action. In this case the command will only be run on the build master of the group. Every group must have a build master. If no build master is explicitly selected by the user, one will be automatically chosen from the group. Once a build master is selected, a single asterisk will appear by its name. To explicitly choose a build master, select one machine in the group and press the Set Buildmaster button below the group list.

Multiple logical groups may share a common filesystem, making it possible to transfer files to one machine and have them available to machines within multiple logical groups. For this reason file master entities exist. A file master is an extension of a build master, so if a machine is a file master, it is also the build master of its logical group. To select a filemaster, choose a machine and press the Set Filemaster button below the groups list. This will cause a window to appear, which will include all of the defined groups. To select multiple groups within this window, hold the ctrl key while clicking on the group name. When you have selected the desired groups, press Ok . Selecting a file master will only affect the build master of the group to which the new file master belongs. All other groups will remain unchanged. When a machine has been selected as a file master, two asterisks will appear by its name.

By default a logical group is created for all machines unselected in the groups panel. This group is known as RSI_DEFAULT and may be treated as a normal logical group or treated as separate machines, each in their own logical group. By default the RSI_DEFAULT group is treated as a logical group. To treat each machine as an independent group, simply uncheck the RSI_DEFAULT grouped checkbox on the groups panel.

Figure 2. Setup Logical Groups

Setup Logical Groups

This screenshot shows the setup logical groups dialog of the ReST Installer. This user has split the 8 machines into 2 groups by selecting a group for 4 machines, while leaving the remaining machines in the RSI_DEFAULT.

Setup Actions

Actions can be added to either a location or a logical group. Adding an action to a logical group will cause the action to be performed on each location in the group and is very useful in adding actions to many locations quickly. To add an action to a location or logical group, select the target of the action, click on the + button and then select the action(s). To remove actions, select the group or location with the actions, select the actions and then click on the - button.

Figure 3. Setup Actions

Setup Actions

This screenshot shows the setup actions dialog of the ReST Installer. This user has added the Remove default touched file action to the RSI_DEFAULT group.

Setup Authentication

The final step before software installation is configuring how the ReST Installer will access the remote machines. At this time ReST can only access machines via Secure Shell (SSH). The preferred authentication method is via public key authentication. If you have SSH keys that can be used to authenticate with the remote machines, press the Add button next to the keys field. This will allow you to select one or more OpenSSH formatted private key files to use for authentication. If you have used the ReST Installer with SSH keys before, the keys you have previously used will already appear in this field. It is important to note that any key listed in the text field will not be removed when adding a new key. If a key is to be replaced, first it's path must be manually removed and then the new key must be added using the add button.

If key-based authentication is not an option, users may create password groups from the listed machines. A password group contains machines that require the same password for remote access. Creating password groups is done in the same way as creating logical groups; simply select the desired machines and press the >> button to move the machines into the new group, then just name the group for convenience. Now when the Installer tries to access the machines in this group, you will only be asked for the password once. Be warned, however, that this convenience is achieved by caching the password to memory, which is a potential security hazzard. Users who do not want this behavior should use SSH keys for authentication.

The final step of configuring authentication is to point the ReST Installer to your current known_hosts file. When SSH makes a connection to an unknown machine it caches the server's key in a known hosts file to compare against at the next login. If you already have a known hosts file, use the Select button to choose your known hosts file. If you do not have one, simply enter the name of the file that you would like to use. By using a known hosts file that has already been populated with keys, you avoid being asked to authorize the keys of the remote machines.

Figure 4. Setup Authentication

Setup Authentication

This screenshot shows the setup authentication dialog of the ReST Installer. This user has provided the location of an SSH key and known_hosts file.

The Installation

Once you have given the needed authentication credentials, you will see the list of locations and the status of their installation. The icon to the left of the location name will show the machine status, either non started, in progress, warning, error, or completed. To the right of the location name appears what is currently being performed on the location or an error message. Once all the locations have been attempted and have either completed or failed, the next button will become available. Press the next button to complete the installation.

If an error occurs during the installation process it may be useful to view the output generated on the location. ReST saves the output of the previous installation to an XML file so that the user may attempt to learn why failures occur. The output file is saved in the user's home area in the subdirectory .rest/output/LOCATION.xml, where LOCATION is the shorted hostname of the desired location. Windows users should know that the .rest directory will appear in C:\Documents and Settings\USERNAME. A web-based utility has been provided to give users an easy way to view this output file. This utility can be found at http://icl.cs.utk.edu/rest/ under the Tools menu item.

If the installation completed without an error, the software can be found in the rest/ subdirectory of the user's home area. At this time there is no way to change the installation directory for rest packages, although this feature will be added in later versions. Currently the software is installed in HOME/rest/GROUPNAME/PACKAGEBASE/. For example, the BLAS package has a package base of libs, so if the install was configured for a group named group1, then the library would be found in HOME/rest/group1/libs.