NERSCPowering Scientific Discovery Since 1974

Setting Up Your User Environment

PDSF Defined Environment

When new users are added to the PDSF machines, the login shell is set according to the user's request. You can choose between csh, tcsh, or bash. You can change your startup shell by logging into NIM.

Paths and environment variables are controlled by startup files (also known as dot files). On PDSF the startup files are symbolic links to read-only files that NERSC controls (if they are not, see the Migrating to New Startup Files Section below). For each standard dot file, there is also a user-writable '.ext' file where you may add your own custom variables and settings. For example, in csh you would want to customize the .login.ext and .cshrc.ext files. These files are all in your home directory (remember to use "ls -la" if you want to see them). Be sure to augment variables like PATH, MANPATH, and LD_LIBRARY_PATH instead of overwriting them. Otherwise you may be unable to access modules or other standard commands (ls, cp, etc.). See the User Modifications to Environment Section below for more details.

Certain Linux commands (such as make and less) actually open a new shell when they're invoked. When this happens, either the .cshrc or .bashrc files are executed again depending on whether your shell is csh/tcsh or bash. For this reason, you should put things you want executed only once into .login.ext (csh/tcsh) or .profile.ext (bash). This includes things like module commands, sourcing other scripts to set up your environment, any echo commands, or chos commands.

CHOS

PDSF offers several different Scientific Linux environments. For a list of all available chos environments and how to switch between them, see this page. Currently the default chos is Scientific Linux 5.3, but we recommend starting with Scientific Linux 6.4.

User Modifications to Environment

PDSF has adopted the modules package as the method for specifying the user environment to access different versions of compilers, libraries, man pages, etc (for more information see the introductory page on modules). For this reason it is very important that you avoid redefining paths and environment variables as is the practice with some other UNIX machines. With the use of modules much of the environment is now controlled by the system. In order to avoid confusion between system settings and your modifications to the environment variables, you should alway make changes by way of augmentation rather than redefinition of the PATH, etc.

For example, users of csh/tcshrc shell would modify the path variable in the .cshrc.ext/.tcshrc.ext file this way:

   set path = ($path /project1/bin /project2/bin)

For users of a bash shell, the way to modify the path variable in the .bashrc.ext file is:

   PATH=$PATH:/project1/bin:/project2/bin

Caution when customizing the environment

You are encouraged to become familiar with the default, system-defined environment before making customizations.

You should be sure that your customizations do not conflict with system defined environment variables and aliases. If you find that something is "missing" in your envinronment, first remove your customizations and see if they are causing a conflict with the system-defined environment.

Caution when modifying path

You should never redefine your path; rather additional directories should be prepended or appended to the existing path. Most path modifications should be done by modules rather than directly by the user.

Commands such as:

   set path = (dir1 dir2 ...)
setenv LD_LIBRARY_PATH dir1:dir2 ...

are an invitation to disaster.

Migrating to New Startup Files

In the old scheme, every new user was given a copy of the startup files in their home directory that they could modify as they wished. In the new scheme (implemented in May, 2013), the startup files are read-only links to central files. User specific commands and variables are contained in the ".ext" files. The ".ext" files are also where you can source experiment specific software. Using this scheme will allow you to switch freely between various chos settings (SL53 to SL64 for example).

Here are instructions for how to upgrade to this new scheme:

cd into your home directory and run "fixdots"

PDSF > cd
PDSF > fixdots


If fixdots is not found, you may have to type the full path. For SL53 this is /common/usg/bin/fixdots and for SL62 and SL64 it's /usr/common/usg/bin/fixdots.

This archives your existing dot files in your home directory in a directory called KeepDots.<Date>.<Time Stamp> and creates the new dot files.
Once you have run the fixdots command, you can check your new environment by opening a new window. Keep the original window open because it will be easier to make changes there if anything is missing.
You can use diff to find any shell variables you had set in your old dot files that you want to transfer to the new .ext file.


PDSF > diff .cshrc KeepDots.<Date>.<Time Stamp>/.cshrc


Depending on which login shell you use (query with echo $SHELL) you will want to check different sets of dot files:
csh:  .cshrc and .login
tcsh:  .tcshrc and .login
bash.profile (or .bash_profile) and .bashrc

These new dot files also come with a debugging mode. If the file .dbgdot is created in your home directory (by typing "touch .dbgdot"), output will be printed when each dot file is opened by the system. This feature is intended only to give an idea of the order in which the dot files are read and should not be used during normal running. To turn it off, type "rm .dbgdot". Here's an example of what someone with a tcsh login will see with the .dbgdot file in place:

entering .cshrc/.tcshrc
entering .tcshrc.ext
exiting .tcshrc.ext
exiting .cshrc/.tcshrc
entering .login
entering .login.ext
exiting .login.ext
exiting .login

Keep in mind that while this .dbgdot file is in your home directory any commands that create a new shell (like "less" or "make") will have unexpected output. For example, using less to read a file will display the above output instead of the file contents. Also, other environment scripts may not interact well with the debug feature. For instance, runinng "source /common/atlas/scripts/setupATLAS.sh" and "setupATLAS" will generate a number of errors in debugging mode. For this reason we recommend only using the debugging mode to get a feel for the order of file loading and not for normal operation.

ATLAS users

If you have the lines

source /common/atlas/scripts/setupATLAS.sh
setupATLAS

in your dot files, you must include these lines in the .bash_profile.ext or .profile.ext. Do NOT put them in .bashrc.ext or they will be recursively reloaded. Also these lines will not work in bash if they are inside an if/then statement (this is a pecularity of bash). Finally, if the .bashrc.ext file echoes anything to the screen, this will cause problems when "setupATLAS" is run. Any echo statements should be put in .bash_profile.ext or .profile.ext.


If you find anything that doesn't work, please open a ticket at consult@nersc.gov. If necessary, you can undo this change by copying the dot files in KeepDots.<Date>.<Time Stamp> back into your home directory.