IS&T-Maintained Locker Configuration Guidelines

Unlike lockers maintained by non-Athena software maintainers (such as the sipb, outland, infoagents, consult and gnu lockers), most lockers maintained by Athena software maintainers generally don't contain multiple, unrelated applications, but usually only one (or at most a small functionally-related application group). We generally find it easier to work this way, particularly for applications where we need to keep multiple version running concurrently. To make life easier for locker maintainers and users, we have also adopted some specific locker configuration guidelines. These lockers are found under /afs/ in the AFS hierarchy. Some of the major lockers currently set up in this configuration include:

  • java
  • maple
  • math
  • matlab
  • sas
  • labview
  • stata
  • tecplot
  • xess

Here is a description from a user's point of view, using matlab as an example:

Typing add matlab adds a "small" base locker which mounts below /mit/matlab. The application itself is not in this locker, but its appropriate bin directory (such as /mit/matlab/arch/amd64_ubuntu1404/bin) contains a "generic" startup script (or more precisely, a link to a platform-independent script in /mit/matlab/arch/share/bin) called matlab that does two main things: 1. it attaches another version locker actually containing the software, and 2. it invokes another script (of same name, matlab) in the appropriate bin directory of the version locker, which actually launches the application. We generally write such scripts in Perl.

In our example, the version locker might be matlab_v8.5 and you would see it mounted below /mit/matlab_v8.5 after you run the base locker script. The naming convention for the version-specific lockers will follow this pattern, i.e. <software>_v<version>, where <version> will be a version descriptor. The "generic" startup script is "smart enough" to know that you normally will want to run the latest version available.

The startup script can also take a local command-line option switch to explicitly specify a version, i.e. if you want to run release 8.4 even though 8.5 is available, you could type add matlab followed by matlab -ver 8.4. If the application also uses its own command-line switches, they should follow the "version-selection" one just described (i.e., put our local version-selection switch in the first position if you use it, which is optional). For example: matlab -ver 8.4 -n. If a particular version/platform combination is not available, you should get an informative error message to that effect. In general, the currently recommended, default version is the one with the simplest launch command (i.e. add matlab; matlab). We generally put a symbolic link at the top level of the base locker to the various version lockers currently available, so you can easily see what versions there are, and one named current which points to the current default version. Thus, with our convention, a "software locker" always consists of a pair of lockers, the base locker and a version locker for a specific software version.

Another way to run applications is to add the version locker directly, bypassing the base locker- for the example above, this would be done by typing add matlab_v8.4 followed by matlab (the version selecting command-line switch is now unnecessary since you have already specified the version implicitly in the add command). We don't generally recommend that you launch this way- one reason is that the base locker script sometimes sends you operational messages about the software that you would miss if you add the version locker directly.

One of the advantages of this system is that it allows overlapping versions during a transition, and at least the last prior version will most likely be around for a couple of months after the new one is installed. We also have flexibility in setting the default to any version for which a version locker exists. In some cases there may be reasons for keeping around older versions more or less indefinitely, and these may be explicitly listed in What Runs Where.

The use of separate local mount points (such as /mit/matlab_v8.4 and /mit/matlab_v8.5) also allows access to different versions of an application at the same time, or easy switching back and forth which otherwise would be cumbersome. This may sometimes be useful for comparison purposes.

Our launch scripts also incorporate a system for sending messages to users, either "once only" or "every launch". The former requires remembering that a user has seen a particular message. We do this with a "magic cookie" system that writes information to a file .sw_messages in each user's home directory. As a "dotfile" this is normally invisible on ordinary directory listings but you should see it if you type ls -a in your home directory. If this file is deleted by intent or by accident, you will get repeats of any messages currently being sent, even if you have seen them before. Normally you wouldn't want to delete it- it shouldn't get bigger than a few hundred bytes or so.

We also have standard locker documentation conventions: a file README.athena at the top locker level has some important basic information; if we have written a local Web page it will be in file www/home.html, in subdirectory www at the top locker level. Most of our lockers also have a README.config file with configuration and setup information, although this is mostly of use to locker maintainers.