Tips for Using Athena Software

Running locker applications on Linux machines running the OpenAFS client

Introduction

Because Athena is based on a fully distributed file system, much of the software you run is not on your local hard drive and there is a potentially unlimited amount of it available, from many places on the network. Since our file system, AFS (for Andrew File System), is worldwide, this can give you access to software set up by other AFS sites in many places (of course, all users, including you, are responsible for setting access permissions in accordance with license obligations). This filesystem will appear as a tree below /afs on your workstation; however, is is not a good idea to try to see what is there by moving to that directory and typing ls: this command can take a very long time to complete as the file system will need to get an acknowlegement from every AFS server in the world, which will appear as a directory when the command completes. In addition, almost all the time some AFS servers are not accessible due to various problems, and this introduces additional delays.

The software described in What Runs Where is a subset of this, which is "officially" maintained by the IS&T Software Release group and closely affiliated MIT groups such as SIPB. In order to keep the list to a manageable size, applications are listed which in our judgement are of most general use to Athena end-users, with emphasis on support for undergraduate education. A good deal of it is Third Party commercial software, including our major Third Party Applications such as Matlab, SAS and a number of others. Other categories include productivity tools such as Email and desktop utilities, and programming tools such as compilers and programming libraries. Much of our software cannot legally be made accessible to those outside MIT (and in some cases to some people inside MIT), and for that reason we restrict access appropriately. Online documentation is frequently certificate-protected for the same reason.

What is not included: many small, specialized UNIX utilities that typically are bundled with the operating system, software limited to staff use, highly specialized or technical software of most use to "experts", software being used for testing or evaluation (and often restricted by license) and software only used in a small number of MIT courses. Also not included: most software only available in lockers that are not well supported or subject to sudden change.

Athena file systems are subject to a further classification that affects how you access software. Some is on the local hard drive of the machine you are working on (or set up in a special way that makes it act as though it is), and, provided that your UNIX path is set appropriately, all you generally need to do to run an application foo stored in this way is to type its name at the UNIX prompt.

athena% foo

An application can also be stored in a locker, and if such is the case you must perform one additional step before running it: if the application above had been stored in a locker called bar, you need to do

athena% add bar

before invoking it. After you do this, the top level of locker bar will (usually but not always) be mounted at /mit/bar on the machine you are working on. A locker can be thought of as a container for an application or group of related applications that you can make accessible by running a command such as add.

There are a number of reasons for doing this that get somewhat technical, but in general software in lockers is easier for maintainers to install and modify quickly, outside of the Athena release cycle. Since you need to know which locker to add, the LOCKER column in the table gives this information where relevant. In some situations, a command related to add called attach is more appropriate and you will see some references to this. add does a few more things than attach; it adds the appropriate bin directories to your path automatically so that binaries in the locker can be found, and it does the equivalent for UNIX manual pages as well. A common but not universal naming convention is for a locker to have the same name as the application stored in it (add matlab; matlab). If you are working on a non-Athena machine with OpenAFS, the details may be different but the concept of running software out of a locker is the same.

On Athena machines you can also launch applications from the Gnome menus or the older Dash menus (if you use Login Options -> Login using Dash interface). In that case you don't need to know if the application is in a locker or not because the launcher is pre-programmed to handle these details automatically. Some, but not all of our locker applications are set up to be launched in this way.

A recent trend is to move software that formerly resided on "packs" (read-only directories stored on network file servers) onto the local hard drive of the machine, and to install and update it by using industry standard installers such as Red Hat's rpm installer or Sun's pkgadd- this is largely possible due to the ever increasing size and decreasing cost of hard drives. Although it doesn't affect the locker vs. non-locker distinction that users need to be aware of when launching software, it has major significance for laptop users when running off the network- by having much of an Athena release installed locally, it becomes potentially feasible to run disconnected "laptop-Athena" machines. IS&T is in fact working on adapting Linux Athena machines to run in this way- there are still some remaining issues that need to be worked out, particularly in handling and resynchronizing AFS and in dealing with things like Kerberos tickets and AFS tokens that are time- and network-sensitive. Local installation can also speed application launch considerably (particularly large, complex applications), and some widely used applications like firefox , Acrobat Reader and Open Office are now being handled this way. IS&T has recently developed a specialized service called "local-lockers" that can assist users installing local copies of lockers for performance reasons.

Athena has guidelines for organizing locker directories in a multiplatform environment that are also affected by requirements of our AFS distributed file system. See the man pages for athdir, a specialized Athena command relating to this, and lockers, for more details (type man athdir or man lockers at the Athena prompt). See also the Locker Maintenance Guide.

There is no centrally maintained list of all available lockers on Athena and these come and go over time- however, some tend to stay around and contain interesting software - places you might want to check for a variety of applications, many of which are not listed in What Runs Where on Athena, include the sipb, outland, potluck, games, watchmaker, gnu, graphics, infoagents and consult lockers.

SIPB pioneered "Linux-Athena" and "NetBSD-Athena", which were ways of making Intel/Linux and Intel/NetBSD machines closely resemble an Athena workstation- this was not exactly Athena however, and some Athena features were missing, notably automatic updates to new Athena releases. Although SIPB still supports these projects to some extent, they are being largely superseded by the more recent IS&T-developed full Linux-Athena port. NetBSD-Athena has been eclipsed by the success of Linux, and the number of MIT users on this platform is now quite small.

SIPB maintains a lot of Linux software, in the sipb, outland, graphics and various other lockers. Among the major Third Party Athena packages, almost all are now available for Linux- the notable exception being FrameMaker (and SAS, for licensing reasons).

As of June 2003, SGI machines have been removed from Athena, and information about SGI software is no longer in What Runs Where. There are plans to phase out Suns as well, and we expect these to be removed by Summer 2010, leaving Linux as the sole Athena platform.

Information

In many cases, a UNIX man page is available. If an application is called foo, man foo may give you a man page (if it's in a locker called bar, you will need to add bar first). To see what (if any) man pages are available for software in lockers such as bar, cd to /mit/bar/man after adding it (if directory man exists), and look for files in subdirectories of man (like man1, man3 etc.). For example, if you find /mit/bar/man/man1/foo.1, then doing man foo should give you a man page for foo.

Many GUI applications have an online help system. Look for a menu or menu button called Help or something similar. Some programs have an external help system which is started from another command at the UNIX prompt. Since this is not obvious, it is explicitly stated for applications that use this kind of system. We are starting to see html or pdf help systems on the Web, accessible via Web browsers- this is becoming increasingly common. These may be installed locally, or at the vendor's Web site. The latter, if available, is usually more up-to-date.

For interactive applications that use a text-only (non-graphical) interface (these typically present an internal prompt similar to but usually distinct from the UNIX prompt), typing ? or help may give help (stata).

Non-interactive applications launched from the UNIX prompt sometimes give help if you add a -h or -help or -? command-line switch, or in case the application always requires at least one command line argument, typing the application name without any arguments may give help.

For software in lockers, looking for README or relevant text files (with extensions such as .txt or .doc) at the top level of the locker may be fruitful. But beware that READMEs can get out of date! Most lockers maintained by IS&T Academic Computing contain a file README.athena and README.config at the top level that contain a summary of useful information. A few of our major Athena Third Party packages have a local Web page. If one exists, it will be located in a www subdirectory below the top level of the locker.

If you are using Athena applications for course work, and particularly if the course has formal computer labs or projects, course TAs may have relevant information or handouts that you cannot easily get anywhere else- ask your TA!

If you are looking for a locker that you are not sure is available or if you can't remember the name exactly, but can guess a piece of the name, you can use ls, "wildcarding" for the piece below /afs/athena/software since that's where Academic Computing-maintained Third Party packages are located in AFS. For example, to look for all autocad lockers, you might try:

athena% ls -d /afs/athena/software/autocad*

which might return /afs/athena/software/autocad/, /afs/athena/software/autocad_v13/ and /afs/athena/software/autocad_v12/. You could then add whichever one you want by using the last piece of the path, which is the locker name (athena% add autocad etc.). Note that in this case two of these are version-specific lockers under new Athena locker configuration guidelines.

For very technical or complex applications, you may need to get information from a vendor manual. Some of these are available in certain Athena clusters or on reserve in libraries. Athena consultants have some in the Consulting Office. Since this is constantly changing, it is best to check with them about what is available.You can also send mail to the 3partysw@mit.edu mailing list to inquire about manual availability.

Running Athena Software

Running Athena applications can sometimes be unintuitive:

Some applications, particularly utilities, take a variety of command-line switches or optional forms that are not listed due to space constraints. You really need to get information about what these are and what they do- see the Information section above and look for man pages.

Some applications come as a "bundle" of separate programs, or as one primary one with a number of "helper" utilities (Zephyr, FrameMaker). Due to space constraints, the full list is not always explicitly given in What Runs Where. If the software is in a locker, you can look in the appropriate bin directory to see what applications can be launched (for example if Sun application foo is in locker bar, look in /mit/bar/arch/sun4x_510/bin; you may see other helper applications there besides foo).

Athena software occasionally runs only on computers in certain locations for licensing reasons, although as of this writing there are no such applications.

X applications can often be launched either "in the background"(add bar; foo &) or "in the foreground" (add bar; foo). Many of our launch instructions and startup scripts are geared towards the former- usually the only difference is that background applications free up the launch window for further use while the application is running, which can be a bit more convenient.

Some Athena applications are subject to version skew (different versions available on Sun and Linux), because vendors have dropped platforms from their product line. This is indicated in the entry Versions: there is version skew. Generally, doing add bar followed by foo will run the latest version of foo available for that platform. These and other operational issues are addressed in locker configuration guidelines.

In some cases, a locker's name is not the same as the mount point- for example, there is an old version of Motif in the motif1.2 locker; you access it by typing attach motif1.2 but the root of the tree for this distribution will appear below /mit/motif. This is unusual and may be confusing but a few lockers are set up in this way.

A number of applications create configuration files in user home directories (typically as "dot files" or "dot directories" which are normally user-invisible to the standard ls command (ls -a will show them). These can be binary or editable text files. Deleting or editing these can affect how applications run, possibly in unexpected ways. However if you are sure you know what you are doing, you can sometimes make your own configuration customizations. In some cases, "dot directories" are created for storing user-created data files (ac3d). These directories can sometimes hold a fair number of files which can use up a significant amount of your quota. Sometimes these are platform and/or version dependent, so you will have multiple sets of them if you work on more than one Athena platform.

Data generated by applications can be platform-dependent (SAS), although this is becoming uncommon. If this is the case, conversion utilities or a common "interchange" data format usually exist. Incompatibilities between data files created by different releases of the same application are common. Typically newer application releases can read data files produced by older ones, but not vice-versa. Usually data is "irreversibly" converted to the newer format, so you will need to keep a backup copy in the old format if you need to keep using the older release of the program.

A small number of packages require sourcing a file containing application-specific settings or commands after adding the relevant locker but before giving the launch command.

In some cases, this is done by accessing the locker via setup instead of add. This attaches the locker and automatically sources commands contained in a dotfile .attachrc at the top level of the locker. An example of this is WebEQ.

Common Problems

If you try to launch an application and something starts, but it doesn't seem to be what you want or it runs incorrectly, you may have the wrong UNIX path setting- on large UNIX file systems it is not uncommon for totally different applications to have the same name. The UNIX which command will tell you what version of an executable you are running by printing the full path to it (i.e. which calendar might return /usr/bin/calendar). In most circumstances, using the correct locker add and launch commands should set the correct path automatically, but errors can creep in, particularly if you modify your path. You can try detaching one or all attached lockers, then re-adding the locker for the application you want to run which may fix the problem. Doing add -f foo instead of add foo will set the bin directories in this locker at the front of your path, so applications in the locker will be run even if others with the same name are elsewhere in your path. This is relevant in cases like java on Suns, where a different java version (that you may not want to use) is found rather than the version in the java locker by default, because its path is earlier in the default Athena path. Another possibility is to type a full path to the application launch command- i.e. If you are trying to run a Sun application foo in locker bar and you normally start it with add bar followed by foo, you can try /mit/bar/arch/sun4x_510/bin/foo instead.

These problems can be subtle- there can be multiple versions of the same application on Athena, and you may actually be running a different version from the one you think you are, especially if you have been trying different versions (see Athena locker configuration guidelines for a versioning system we have set up for Third Party applications). Another possibility is that application startup scripts can have the same name as the application binary; the correct way to start the application is by invoking the startup script (which usually does necessary preparatory work before launching the binary). Invoking the binary directly can produce unexpected (and usually undesired) results, but this might happen accidentally if the binary is found earlier in your path than the startup script, or if you happen to cd to the directory containing the binary.

If you get a message like: There doesn't appear to be an executable called foo... on this platform... when you attempt to launch application foo, it means that we do not have the version of this application you are trying to run for the platform you are using, or we may not have any version of it for this platform. Consult the platform availability table on the main What Runs Where page for details, and please let us know if we have an erroneous entry!

Some applications, mostly utilities, are designed to do I/O via stdin and stdout. Generally these are intended to connect to other programs through a mechanism such as UNIX pipes. If you are unaware of this and just type the application name at the UNIX prompt, the computer will seem to do nothing after you hit Return (it will not give you back a UNIX prompt); it is really waiting for input. If you suspect this, you need to get more information about how the application is supposed to work.

Some applications, particularly very large, compute-intensive GUI ones, may take so long to start up that you may think they are not running (notably Pro-Engineer). This can take 5-10 min, especially if network load is heavy, or if multiple people are all launching at once, like students in an electronic classroom. If something isn't running after 10-15 minutes on a lightly loaded network, it is most likely broken (and you should report it via sendbug).

Some applications generate large amounts of temporary data that can overfill available /tmp or /usr/tmp temorary storage if this has not been cleared for a while - you will get error messages about all the disk space being used up. You can usually fix this by deleting files in these directories, but you must be careful because certain files have to stay there while you are logged in. Typically these are small - a few K or so, so it's usually safe to delete "big" files ( over 50-100K or so) to free up space.You will probably need to exit and restart the application.

If you get a message like all licenses in use it is due to some of our software being limited to a certain number of concurrent users by a license manager. This is given where relevant in the listings by the entry Licenses: xx floating licenses; you will have to wait until one frees up (we do not support "waiting queues" on Athena even though some applications allow for this). It's unlikely that you will experience this problem, except for applications where we have a small number of licenses. Sometimes license servers can go down- a message like unable to connect to license server would indicate this. You should report this to the Athena consultants if it persists for more than a few minutes.

You might get a message saying access denied or something similar. This may happen in two ways:

One is due to a piece of MIT-developed software called a wrapper that is placed "on top of" certain Third Party Athena applications. The wrapper performs two functions- it can limit access to certain specified machines (which implicitly controls locations where software may be run), and it allows us to monitor and count usage (for privacy considerations, user IDs are not logged). This is done primarily to allow us to comply with license obligations in cases where the vendor does not build their own license manager into the software but requires limiting the number of concurrent users, and to let us generate usage statistics. The wrapper must maintain continuous network contact with a server to perform its function, and network outages or disconnected laptop operation can cause access denials (in practice these have been quite rare). As of this writing the wrapper does not impose restrictions by I.P. address, but this may change in the future as per the license server restriction below.

The other is due to the application containing a floating license manager imposed by the software vendor. For security reasons, in 2005 we put access limitations on all our floating license servers that limit granting of licenses to machines with I.P. address in the ranges allocated to MIT.

You should not expect to be denied access due to an I.P. address not being in the allowed range for machines on the main MIT campus or if you use Tether, but it's likely that you will if you live off campus and connect through an independent ISP such as Comcast or RCN. In that case you will need to install and use the MIT VPN (Virtual Private Network) which effectively gives you an MIT I.P. address.

If you are running on a laptop and the application you are using is either under control of a license server or the MIT wrapper, you will generally need to maintain network connectivity to allow these mechanisms to function, even if the software is on your local hard drive.

Remote Access to Athena

Athena may be accessed remotely over the network by authorized users; the preferred connection method is ssh although users with access to a kerberized telnet client (such as Athena telnet) can also use that. Besides some necessary software, all you need is internet access and you should be able to connect from anywhere. Graphical applications will only be feasible if you have a fast connection (T1 or faster, DSL, cable or optical); 56K modem speeds will not be adequate. As the machines you connect to are on the MIT campus, you will not have any problems running software limited to MIT machines (i.e. you won't need to use the VPN if you are connecting from off campus). Files generated by running programs will be stored in your Athena home directory. Note that in some cases graphical applications will not run remotely, particularly 3d applications requiring OpenGL. The graphical Mathematica interface will not run remotely due to font issues.

Users can connect to and run programs remotely on a pool of Athena Sun machines (called, for historical reasons "Athena dialups"), or on a Linux machine maintained by SIPB called linerva. linerva is not a standard Athena machine, and not all Athena applications will run on it, though most will. There are several options depending on the platform you are on, the type of application you want to run (non-graphical or graphical) and the platform the application runs on (Linux or Sun). In all cases below where a login is requested, you should use your Athena username and password. remote client below refers to the machine you are using to connect to Athena.

• Sun non-graphical applications, all remote client platforms: you can connect securely to a Sun Athena dialup through a Web browser running a Java applet called Mindterm SSH (your browser will need a recent Java plugin installed). Once you are logged in you can run non-graphical Athena Sun applications in the usual way. This service is not available for Linux applications.
• Graphical (X) applications (or non-graphical applications):
  • Linux remote client: from a terminal window:
    • Sun application: connect by running ssh -Y athena.dialup.mit.edu
    • Linux application: connect by running ssh -Y linerva.mit.edu
  • Macintosh remote client: you need Apple X11, which may not be installed by default. It should be available on your installation media, or from Apple's Web site. From an X11 terminal window:
    • Sun application: connect by running ssh -Y athena.dialup.mit.edu
    • Linux application: connect by running ssh -Y linerva.mit.edu
  • Windows remote client: you need SecureCRT and X-Win32 from the MIT download site. Please note that X-Win32 support is only available from the vendor, not MIT. Launch X-Win32, then SecureCRT. From SecureCRT:
    • Sun application: if File -> Connect shows an Athena entry, select that, then Connect. Otherwise, choose File -> Quick Connect, leave default settings but make sure Protocol is set to SSH2, and enter your Athena username for Username. Enter athena.dialup.mit.edu for Hostname then click Connect. Reenter your Username and Athena password if asked. Selecting Save Session will let you choose this connection from File -> Connect on subsequent logins. Pick Yes to "Allow connection from host 127.0.0.1" queries.
    • Linux application: do as for Sun above using File -> Quick Connect, but set Hostname to linerva.mit.edu.

Linux users have the additional option of using the OpenAFS client to run Linux Athena software directly on the remote client. In this case files generated by running applications can optionally be stored locally (if you have your home directory set to a location on the remote client) or in your Athena home directory (if you have your home directory set to that location). Generally your home directory is defined by setting the HOME environment variable to the desired path. If you are off-campus you will need to use the MIT VPN client to use applications restricted to the MIT campus. As a consequence of how AFS caches files, you may notice, especially from off campus, that applications take a long time to launch the first time you run them. Subsequent launches should be much faster.

Running locker applications on Linux machines running the OpenAFS client

IS&T has made available a version of the OpenAFS client for Linux machines running several Red Hat Enterprise Linux releases tailored for use in our environment. The notes below refer to recent versions of OpenAFS, 1.4.1 and later. Installing this client will give you access to almost the entire set of Linux applications in lockers maintained by IS&T Software Release, including most Third Party commercial applications (to access many of the latter from off-campus you will need to install the VPN client). You can identify such lockers by the presence of a file README.athena at the top level. Lockers maintained by others may or may not be configured in a way that is compatible with OpenAFS operation. Installation instructions are here (RHEL 3 and 4) and here (RHEL5).

Fedora users may or may not be able to use the MIT OpenAFS binaries directly, depending on which Fedora version you are running. You may want to try using a repository that supplies OpenAFS rpms, such as ATrpms. More details for installing OpenAFS from ATrpms on Fedora 8 are here. Ubuntu and Debian users can install OpenAFS from the repositories for these distributions following instructions from SIPB. Please note that IS&T doesn't support these latter two ways of using OpenAFS, and that you may need to figure out some configuration details on your own.

Once the client is installed you are ready to go. There are some significant differences between running applications this way and running them on a standard Athena machine:

• the attach and detach commands are available, but don't support all the options available with the Athena version; add is available, and it supports the -f switch (which puts the appropriate bin directory in the locker being added at the front of your path), as well as the -r switch.
• you will need to separately authenticate to AFS, using the kinit command. In using kinit, you log in with your Athena password which may be different from the one you use to log on to the machine. If you forget this step, you may get confusing error messages when you try to run locker software. You do this as follows:
  
  $ kinit username (username is your Athena username; enter your Athena password as prompted)
  
• to run an application like xess for example, you can proceed as on an Athena machine: type add xess on the command line followed by xess. As on Athena, lockers will be mounted below /mit on the local machine. Note: if you've just installed the OpenAFS client, you will need to log out and back in once for the add command to be accessible.
• if you have a locally installed application that has the same name as one in a locker, it may be launched instead of the one in the locker; if you don't want this, you should use add with the -f switch to put the locker version first on your path (i.e. add -f xess, followed by xess).
• for applications (such as Open Office and many others) that store configuration and data files in your home directory, the value of $HOME will generally be used to determine this; it can either be your local home directory on the machine you are working on, or your AFS home directory, but if you want the latter you will need to reset $HOME yourself and attach your AFS home directory locally by using the attach command (as you do for attaching other lockers). If you use the default home directory it will generally be the (non-AFS) one on the local machine.
• printing will only work if you have it working on the machine already; in general, if you can use lpr to print from the command line it will most likely work from within applications. You will be able to print to Athena printers if you install LPRng configured for MIT.
• the default Redhat Linux shell is Bourne shell (sh)-compatible; if you are running an application that needs a C shell (csh) invocation to run like setup or source, you will need to start a C shell manually from the command-line first; you can do that by just typing csh. If the launch instructions call for using setup (i.e. setup foo), replace this by attach foo; source /mit/foo/.attachrc
• because we can't assume that all machines installed by users will be in the same, standard configuration, it may happen that some applications in lockers fail to launch over OpenAFS, typically with errors about missing dynamic libraries. If this happens to you, note the exact name of the missing libraries and contact the Athena consultants. They should be able to determine in most cases what packages you are missing and tell you how to install them.
• the OpenAFS client now defines an appropriate value of the ATHENA_SYS and ATHENA_SYS_COMPAT environment variables; you can use scripts that refer to these variables.