Experience has shown that requiring untrained users to manually edit their ``dot'' files (e.g., $HOME/.bashrc, $HOME/.login, $HOME/.logout, etc.) can result in damaged user environments. Side effects of damaged user environments include:
The OSCAR switcher package is an attempt to provide a simple mechanism to allow users to manipulate their environment. The switcher package provides a convenient command-line interface to manipulate the inclusion of packages in a user's environment. Users are not required to manually edit their ``dot'' files, nor are they required to know what the inclusion of a given package in the environment entails.2 For example, if a user specifies that they want LAM/MPI in their environment, switcher will automatically add the appropriate entries to the $PATH and $MANPATH environment variables.
Finally, the OSCAR switcher package provides a two-level set of defaults: a system-level default and a user-level default. User-level defaults (if provided) override corresponding system-level defaults. This allows a system administrator to (for example) specify which MPI implementation users should have in their environment by setting the system-level default. Specific users, however, may decide that they want a different implementation in their environment and set their personal user-level default.
Note, however, that switcher does not change the environment of the shell from which it was invoked. This is a critical fact to remember when administrating your personal environment or the cluster. While this may seem inconvenient at first, switcher was specifically designed this way for two reasons:
The OSCAR switcher package contains two sub-packages: modules and env-switcher. The modules package can be used by itself (usually for advanced users). The env-switcher package provides a persistent modules-based environment.
The modules package (see http://modules.sourceforge.net/) provides an elegant solution for individual packages to install (and uninstall) themselves from the current environment. Each OSCAR package can provide a modulefile that will set (or unset) relevant environment variables, create (or destroy) shell aliases, etc.
An OSCAR-ized modules RPM is installed during the OSCAR installation process. Installation of this RPM has the following notable effects:
Most users will not use any modules commands directly - they will only use the env-switcher package. However, the modules package can be used directly by advanced users (and scripts).
The env-switcher package provides a persistent modulues-based environment. That is, env-switcher ensures to load a consistent set of modules for each shell invocation (including corner cases such as non-interactive remote shells via rsh/ssh). env-switcher is what allows users to manipulate their environment by using a simple command line interface - not by editing ``dot'' files.
It is important to note that using the switcher command alters the environment of all future shells / user environments. switcher does not change the environment of the shell from which it was invoked. This may seem seem inconvenient at first, but was done deliberately. See the rationale provided at the beginning of this section for the reasons why.
env-switcher manipulates four different kinds of entities: tags, attributes, and values.
There are a few built-in attributes with special meanings (any other attribute will be ignored by env-switcher, and can therefore be used to cache arbitrary values). ``default'' is probably the most-commonly used attribute - its value specifies which package will be loaded (as such, its value is always a name). For example, setting the ``default'' attribute on the ``mpi'' tag to a given value will control which MPI implementation is loaded into the environment.
env-switcher operates at two different levels: system-level and user-level. The system-level tags, attributes, and values are stored in a central location. User-level tags, attributes, and values are stored in each user's $HOME directory.
When env-switcher looks up entity that it manipulates (for example, to determine the value of the ``default'' attribute on the ``mpi'' tag), it attempts to resolves the value in a specific sequence:
In this way, a four-tiered set of defaults can be effected: specific user-level, general user-level, specific system-level, and general system-level.
The most common env-switcher commands that users will invoke are:
List all available tags.
List all defined attributes for the tag <tag>.
A shortcut nomenclature to set the ``default'' attribute on <tag> equal to the value <value>. If the -system parameter is used, the change will affect the system-level defaults; otherwise, the user's personal user-level defaults are changed.
Show the all attribute / value pairs for the tag <tag>. The values shown will be for attributes that have a resolvable value (using the resolution sequence described above). Hence, this output may vary from user to user for a given <tag> depending on the values of user-level defaults.
Remove the attribute <attr> from a given tag. If the -system parameter is used, the change will affect the system level defaults; otherwise, the user's personal user-level defaults are used.
Section 2.10.3 shows an example scenario using the switcher command detailing how to change which MPI implementation is used, both at the system-level and user-level.
See the man page for switcher(1) and the output of switcher -help for more details on the switcher command.
Starting with the OSCAR 1.3 series, there is a generalized mechanism to both set a system-level default MPI implementation, and also to allow users to override the system-level default with their own choice of MPI implementation.
This allows multiple MPI implementations to be installed on an OSCAR cluster (e.g., LAM/MPI and MPICH), yet still provide unambiguous MPI implementation selection for each user such that ``mpicc foo.c -o foo'' will give deterministic results.
The system-level default MPI implementation can be set in two different (yet equivalent) ways:
# switcher mpi --list
This will list all the MPI implementations available. To set the system-level default, execute the command:
# switcher mpi = name --system
where ``name'' is one of the names from the output of the -list command.
NOTE: System-level defaults for switcher are currently propogated to the nodes on a periodic basis. If you set the system-level MPI default, you will either need to wait until the next automatic ``push'' of configuration information, or manually execute the /opt/opium/bin/sync_users command to push the changes to the compute nodes.
NOTE: Using the switcher command to change the default MPI implementation will modify the PATH and MANPATH for all future shell invocations - it does not change the environment of the shell in which it was invoked. For example:
# which mpicc /opt/lam-1.2.3/bin/mpicc # switcher mpi = mpich-4.5.6 --system # which mpicc /opt/lam-1.2.3/bin/mpicc # bash # which mpicc /opt/mpich-4.5.6/bin/mpicc
Setting a user-level default is essentially the same as setting the system-level default, except without the -system argument. This will set the user-level default instead of the system-level default:
$ switcher mpi = lam-1.2.3
Using the special name none will indicate that no module should be loaded for the mpi tag. It is most often used by users to specify that they do not want a particular software package loaded.
$ switcher mpi = none
Removing a user default (and therefore reverting to the system-level default) is done by removing the default attribute:
$ switcher mpi --show user:default=mpich-1.2.4 system:exists=true $ switcher mpi --rm-attr default $ switcher mpi --show system:default=lam-6.5.6 system:exists=true
switcher immediately affects the environment of all future shell invocations (including the environment of scripts). To get a full list of options available, read the switcher(1) man page, and/or run switcher -help.
root 2002-11-08