Search Google Appliance

Tips for Using Athena Software

On this page:
Introduction
Getting Information
Running Athena Software
debathena
Remote Access to Athena
Running the OpenAFS Client

Introduction

Because Athena incorporates 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 network 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; you may, however, have significant delays in completion of file system commands when you change directory to AFS directories at remote sites as network connectivity may be less than ideal. In addition, almost all the time some remote AFS servers are not accessible for various reasons.

The software described in What Runs Where is a subset of the software accessible from an Athena machine, which is "officially" maintained by IS&T and closely affiliated MIT groups such as SIPB. In order to keep the list to a manageable size, applications are listed which in our judgment are of most general use to Athena end-users, with emphasis on support for undergraduate education. A significant part 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, 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 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 by a small fraction of the user community.

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 is typically installed as a Ubuntu package. Provided that your path is set appropriately, all you generally need to do to run an application foo installed in this way is to type its name at the command-line prompt.

athena% foo

An application can also be stored in a locker (lockers are typically storage volumes on remote AFS file servers), 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 type

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. Since you need to know which locker to add, the LOCKER column in the table gives this information where relevant. In some situations, different commands related to add called attach and setup are 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 manual pages as well.

setup works in a different way, in that it can preset a number of things in your environment such as environment variables and your path, and it then launches a terminal window in which these settings are active.

In a small number of cases as alluded to above, an application appears to be installed locally but is really in a locker. This is done by executing an attach and run script that has the same name as the application. This script will attach the locker, then execute the application or its launch script from the locker. An example is freeWRL. The reason for doing this is primarily convenience as the user doesn't need to add the locker.

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 a few applications from the Gnome Launch Icons on the left side of the Gnome interface. Other applications can be launched from the Ubuntu Dash (the Dash launch icon is the topmost icon in the default set of launch icons on the left). Once the Dash is open, you can type in a string that represents part or all of an application you'd like to launch. The Dash will bring up a set of launch icons for installed applications that match the string, and you can click on the one you want to launch it. 

Although most of the time it doesn't make a significant difference if an application is installed locally or in a locker in AFS, there are times when it does- local applications can be run if you are disconnected from the network but applications in lockers can't be since you need continuous network connectivity for the latter. Local installation can also speed application launch considerably (particularly for large, complex applications).

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 Course Locker Maintenance Guide. Athena currently supports 32 bit and 64 bit Linux, and these are considered different platforms (although is some cases a purely 32 bit software installation can be made to run on a 64 bit OS). All public cluster Athena machines are 64 bit now.

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" in the 1990's, 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. The latest version of Athena has evolved from the SIPB-IS&T partnership that produced debathena. It was initially deployed during Summer 2009 and at this time of this writing is based on Ubuntu Precise (12.04).

In the past, SIPB maintained a lot of Linux software in the sipb, outland, graphics and various other lockers; it still does, but a lot of these applications are now installed locally, as Ubuntu packages.

Getting Information

In many cases, a 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 bar (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 athena prompt. Since this is not obvious, commands that certain applications use for this are explicitly listed in What Runs Where. There are also html or pdf help systems on the Web, accessible via Web browsers. These may be installed locally, or at the vendor's Website. The latter, if available, are usually more up-to-date but the version may not match the one on Athena.

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

Non-interactive applications launched from the athena prompt sometimes give help if you add a -h or -help or -? command-line option, 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 contain files README.athena and README.config at the top level that contain a summary of useful information; README.config typically contains information mostly relevant to locker maintainers. 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 base locker for the application.

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.mit.edu/software since that's where IS&T-maintained Third Party packages are located in AFS. For example, to look for all matlab lockers, you might try:

athena% ls -d /afs/athena.mit.edu/software/matlab*

which might return /afs/athena.mit.edu/software/matlab, /afs/athena.mit.edu/software/matlab_v7.6, /afs/athena.mit.edu/software/matlab_v7.7 and /afs/athena/software.mit.edu/matlab_v7.8. You could then add whichever one you want by using the last piece of the path, which is the locker name (athena% add matlab_v7.7 etc.). Note that in this case three of these are version-specific lockers and one (matlab) is a base locker; the distinction is explained in new Athena locker configuration guidelines.

For very technical or complex applications, you may need to get information from a vendor or author manual. Some of these are available in certain Athena clusters or on reserve in libraries; most are now available online. 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 options or alternate invocations 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, ImageMagick). 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 application foo is in locker bar, look in /mit/bar/arch/amd64_ubuntu1204/bin; you may see other 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 restrictions.

Graphical 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.

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 include 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 version dependent, so you may have multiple copies for different platforms and software versions.

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 version 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; this is one of the primary reasons for using the setup command instead of add (Gaussian). This attaches the locker and automatically runs commands contained in a dotfile script .attachrc or .attachrc.bash at the top level of the locker.

debathena

With the debathena release, many software applications that were formerly installed in lockers are now installed locally as Ubuntu packages as part of the debathena-thirdparty metapackage (strictly speaking, this will be installed by default only on cluster workstations, but private workstation owners have the option to install subset groups or the complete set of packages as well). In that case, the application will normally be on your default path and you won't need to add or attach a locker to launch it.

debathena machines also offer users the option of installing any package in the Ubuntu repositories, via the aptitude or synaptic package managers. In the case of public cluster machines, this will be temporary, for the duration of the current login session only, due to the way these machines are configured.

In a few exceptional cases, applications available as Ubuntu packages may both be installed locally as packages and in a locker, or in a locker only even though a package is available (java, eclipse); two reasons for this are cases where the Ubuntu package version is significantly out of date, and applications that require a significant amount of special configuration that cannot easily be applied to locally installed packages. We make a note of this in the relevant What Runs Where entries; in such situations, to get the locker version if both a package and locker version exist you will need to add the appropriate locker with the -f switch, i.e. add -f eclipse-sdk; eclipse

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 path setting- on large file systems it is not uncommon for totally different applications to have the same name. The 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, where a different java version (that you may not want to use) is found rather than the version in the java locker, 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 an application foo in locker bar and you normally start it with add bar followed by foo, you can try /mit/bar/arch/amd64_ubuntu1204/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 usually means we don't 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; in some cases this can happen spuriously because your path isn't set correctly.

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 Linux pipes. If you are unaware of this and just type the application name at the athena prompt, the computer will seem to do nothing after you hit Return (it will not give you back an athena 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. 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 a significant length of time.

You may not be able to run some software applications for a variety of reasons:

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 or failure to launch (in practice outages have been quite rare) and as of this writing the wrapper does not impose any access restrictions. A potential problem with software that uses the wrapper is time synchronization. If your computer's clock is off by more than a few minutes, wrapped applications will fail to launch with error messages like key generator out of range.

Another cause of access denial is due to applications containing a floating license manager imposed by the software vendor. For security reasons we put access limitations on most of our 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 but it's likely that you will be if you live off campus and connect through an independent ISP such as Comcast or Verizon. 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.

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 won't 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 may not run remotely due to font issues.

Users can connect to and run programs remotely on a pool of Athena Linux machines (called, for historical reasons "Athena dialups"). There are several options depending on the platform you are on and the type of application you want to run (non-graphical or graphical). 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.

  • Non-graphical applications, all remote client platforms: you can connect securely to a Linux Athena dialup through a Web browser using an application called shellinabox. Once you are logged in you can run non-graphical Athena Linux applications in the usual way.
  • Graphical (X) applications (or non-graphical applications):
    • Linux remote client: from a terminal window:
      connect by running ssh -Y athena.dialup.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 Website. From an X11 terminal window:
      connect by running ssh -Y athena.dialup.mit.edu
    • Windows remote client: you need X-Win32 from the MIT download site. Please note that X-Win32 technical support is only available from the vendor, not MIT. Configure X-Win32 for an ssh session to a remote Linux host (it should select xterm as the application to run). Choose hostname athena.dialup.mit.edu, and use your Athena username and password when it asks for these. It will save this session under the session name you choose, and in the future you can simply pick this session from the X-Win32 icon in the Windows panel to reconnect.

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 MIT. As a consequence of how AFS caches files, you are likely to 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 the OpenAFS Client on non-Athena machines

Installing OpenAFS on a non-Athena Linux machine will give you access to almost the entire set of Linux applications in lockers maintained by IS&T, including most Third Party commercial applications (to access most of the latter from off-campus you will need to install the VPN client). Lockers maintained by others may or may not be configured in a way that is fully compatible with OpenAFS operation.

Please note that OpenAFS supplied with the various debathena flavors is preconfigured with a number of MIT-specific extras such as the add, attach, detach and setup commands and predefined values for the ATHENA_SYS and ATHENA_SYS_COMPAT environment variables; debathena also supplies MIT-specific utilities like athdir, hesinfo, machtype and various others; these will not be available by just installing OpenAFS on a non-Athena machine. Instructions for making them available are beyond the scope of this document, although advanced users can examine how they are implemented on Athena machines and adapt them for use on non-Athena machines. Given these issues, users desiring OpenAFS access with a lightweight installation may wish to consider the tradeoffs between installing just OpenAFS on vanilla Ubuntu versus one of the lighter weight debathena options such as debathena-standard.

Fedora users are advised to follow instructions here. Ubuntu and Debian users can install OpenAFS from the repositories for these distributions. In all cases, you will need to set the ThisCell file in your OpenAFS installation to athena.mit.edu and you may need to edit the CellServDB file to reflect changes in MIT AFS servers. 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:

  • unless you provide the attach and add commands and define the ATHENA_SYS environment variable as noted above, functionality depending on these will not work.
  • the /mit directory, needed as the standard mount point for lockers, will not exist. You will need to create it manually and may need to sudo to root to do this.
  • you'll need to create a symlink for each locker you use, like

    /mit/foo -> /afs/athena.mit.edu/software/foo

    unless you provide the attach or add commands.

  • unless you provide the add command, you will need to put the correct locker arch hierarchy bin directory on your path in order to be able to launch applications in the locker.
  • some locker applications require the MIT-specific athdir, hesinfo and machtype commands; unless you provide these launch scripts requiring them will not work correctly.
  • 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 computer you are using. 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 when prompted)

  • after running kinit you need to run the aklog command to get AFS tokens:

    $ aklog

  • 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 unless you ensure that the locker version is found first in your path. If you have the add command, using it with the -f option will ensure that this is the case.
  • for applications 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) or by making a mount symlink for this manually. If you use the default home directory it will generally be the (non-AFS) one on the local machine.
  • because non-Athena Linux machines generally are not in the same, standard configuration as Athena machines, it may happen that some applications in lockers fail to launch over OpenAFS, typically with errors about missing libraries. If this happens to you, note their exact names 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.