Skip to content

FF chevron

Your Account and Environment

This page discuss various aspects of your user account and environment on the DIT maintained UMD HPC clusters.

Home directory and dot files

Note

NOTE: As the HPC clusters are intended for research, all content under a user's home directory, like all other data on the cluster, is considered to be research related, and is at some level considered property of the University and the faculty PIs of the allocations through which you receive your access to the cluster.

Your home directory is your main directory, the directory in which you start when you log into the cluster, and it is also where many settings to customize your experience on the cluster are stored. The storage aspects of your home directory are discussed in more detail on the page discussing the different storage tiers available; here we primarily discuss aspects pertaining to that customization.

Your home directory also contains various configuration and settings which control the behavior of your login sessions on the cluster. These are normally contained in files starting with a period (.), generically called "dot files". By default, the "ls" command does not display dot files, so these files are generally present but not noticed.

Many packages will create dot files or directories named after themselves in your home directory; most of these are beyond the scope of this document. Some common ones are:

  • .ssh: This contains various data related to the ssh command. The contents of this directory can impact system security, and should be owned by you with file permissions "rwx------".
  • .profile: This is a shell script file which is processed for all "login" shells, i.e. shells intended for interactive use. This script, if present, should be compatible with any Bourne-like shell, as many shells will look for it. It is implicitly "sourced" at the start of every interactive shell.
  • .bash_profile: This is used exclusively by the bash shell instead of the .profile script. If omitted, bash will look for a .profile script instead.
  • .bashrc: This is a shell script which is implicitly "sourced" at the start of every bash shell (interactive shells as well as non-interactive shells and even bash scripts).

The .bash_profile and .bashrc files are useful to set environmental variables, etc. for your environment. In particular, it is useful for setting custom PATHs, custom Python library paths, etc. E.g., if your research group maintains a bunch of common codes and/or scripts under /scratch/zt1/project/foo-prj/shared/bin, you can have that directory added to your PATH (so that the shell will find it without you providing a full path) by adding to your ~/.bash_profile a line like:

Example

PATH="/scratch/zt1/project/foo-prj/shared/bin:${PATH}"

By adding the above to your ~/.bash_profile file, the research group bin directory will be added to your PATH for all interactive shells, but not for non-interactive shells (unless explicitly they explicitly source the profile script). To make the addition of the group bin directory to the PATH in all shells, place the line in the ~/.bashrc file instead of the ~/.bash_profile file. (The decision of whether to place such directives in .bashrc or .bashrc_profile depends on exactly what is desired; usually you can just add it to .bashrc unless it might adversely impact some scripts.)

Other types of shells will have their own .*rc file, and may have shell specific profile files as well (though they generally will default to using ~/.profile).

Tip

You should ensure that your .bash_profile and .bashrc files do not generate output (except possibly in interactive mode).
Certain applications (e.g. scp) can fail with weird error messages if these files produce stray output.

Useful environment settings

This section discusses some useful environment settings. Before we discuss specific settings, we discuss how to set environmental variables.

Note

This section is specific to the "bash" shell. Although most users on Zaratan use the bash shell, if you changed your default login shell, it might be different. In such cases, you will need to consult the documentation for the shell you are using.

To set an environmental variable, you can do something like export VARIABLE_NAME=VALUE. There should not be any spaces between the variable name, the equal sign, and the value. Note that this will replace the old value of the variable (if any) with the new value. In order to append or prepend something to an existing variable, say foo, you could use something like export foo="PREFIX${foo}${SUFFIX}" where PREFIX is a literal string to prefix the old value of $foo with, and SUFFIX is the name of a variable containing the string to append to the variable.

Some variables you might wish to customize:

  • PATH: this should be a colon (:) delimited list of paths to directories from which to look for commands. By default, when you login into one of the login nodes of the cluster, your path will include the directories containing the standard operating system and other utilities you are accustomed to. You might wish to prefix this with the paths to directories containing your personal or group executables. NOTE: it is generally advised not to delete the default directories from the PATH, as doing so might cause you difficulties accessing standard commands.
  • PYTHONPATH: this instructs python where to look for libraries. It will be adjusted when you "module load python", but you might wish to add your own personal python directories here.
  • PS1: This can be used to customize your shell prompt. Any text you give here will appear in your prompt before each command. You can also use special charaters to display special strings like the date, the time, the hostname, your username, the full or last component of the current directory, etc.

Tip

Be careful not to delete the default directories from your PATH setting, as doing so could make it difficult for you to access standard command.

Tip

It is recommended that when making changes to your .bashrc or .bash_profile files that you:

  1. Make a backup copy of the files first
  2. Leave a shell session open in one window
  3. Start a new shell session in another window and test that all is working well

Command aliases

You can also use the alias command in bash to create command aliases. For example, you might wish to make an alias ll for the ls -l command, you can use something like:

Example

login-1:~> alias ll="ls -l"
login-1:~> ll temp.txt
-rw-r--r--. 1 johndoe users 371 Mar 15  2025 temp.txt

You can also use it to create an alias with the same name as an existing command to set some default options. For example, to always use the -F argument with ls (which will cause ls to display various suffixes on entries depending on file type, e.g. a "*" after executable files, a "/" after directories, etc), you could use

Example

login-1:~> alias ls="ls -F"
login-1:~> ls ~
bin/        myscript.sh*    priv/       text.txt
login-1:~> /bin/ls ~
bin         myscript.sh     priv        text.txt

In the above case, bin and priv are directories and myscript.sh is executable, as seen by the suffixes in the first output. The second output shows that you can override the alias setting by providing a full path to the command.

Generally, you will want to add the aliases to one of your dot files; if they are only for interactive use, the .profile file is a good choice. If they are for both interactive and non-interactive use (e.g. you plan to use them in batch scripts), the .bashrc file is a better choice.

Suppressing output from dot files

Certain applications (e.g. scp) can have issues if there is extraneous or unexpected output when you ssh into a node, typically due to output from your dot files.

Generally you are encouraged to code your dot files so that they do not generate any output. But if you need to have your dot files output something, you should wrap the lines generating the output in a conditional structure so that the output is only generated for interactive shells. E.g.,

Example

# excerpt from a .bashrc or .bash_profile script
if [ "x$PS1" == "x"  ]; then
    # We are in an interactive shell, can generate output
    echo "The current time is"
    date
fi

This script excerpt will print the current time when you log in, but only for an interactive shell (due to the wrapper checking for if the prompt variable is defined). A similar excerpt for a C-like shell would be

Example

# excerpt from a .cshrc or similar
if ( $?prompt )
    echo "The current time is"
    date
endif

Your home directory contains symbolic links to your personal scratch and SHELL directories. For each project named foo to which you belong, you should see:

  • A symlink scratch.foo pointing to /scratch/zt1/project/foo/user/USERNAME where USERNAME is your username.
  • A symlink SHELL.foo pointing to /afs/shell.umd.edu/project/foo/user/USERNAME

In addition, there will be symlinks scratch and SHELL pointing to one of the scratch.foo and SHELL.foo symlinks, respectively.

Most users only belong to a single project, and so the existance of scratch.foo and scratch is a bit redundant, but this structure is maintained because some users belong to multiple projects. The situation for SHELL and SHELL.foo is similar.

The specific project to which the scratch and SHELL symlinks point is somewhat arbitrary, and depends on a number of factors, including the order in which you were added to the allocations in the projects. You can use the ls -l command to see what project they are pointing to. You can change which project they point to by using ln command, e.g. to change the scratch symlink to point to scratch.bar and similar for SHELL, you can issue the commands

Example

login-3:~> ls -l  ~/scratch
lrwxrwxrwx. 1 smith zt-foo 12 Sep 26  2024 /home/smith/scratch -> scratch.foo
login-3:~> ls -l  ~/SHELL
lrwxrwxrwx. 1 smith zt-foo 12 Sep 26  2024 /home/smith/SHELL -> SHELL.foo
login-3:~> ln -sf ~/scratch.bar ~/scratch
login-3:~> ln -sf ~/SHELL.bar ~/SHELL
login-3:~> ls -l  ~/scratch
lrwxrwxrwx. 1 smith zt-foo 12 Mar 18  2025 /home/smith/scratch -> scratch.bar
login-3:~> ls -l  ~/SHELL
lrwxrwxrwx. 1 smith zt-foo 12 Mar 18  2025 /home/smith/SHELL -> SHELL.bar

Note

NOTE: while we describe these subdirectories as "personal", please note that all content on the HPC clusters, including the "personal" scratch and SHELL directories, are considered research data and are under the ownership of the PI(s) of the project. I.e., systems staff will grant any requests by the PI of the project for access to this data.

Changing your default shell

When you ssh into one of the login nodes, you will receive a shell prompt. There are many flavors of shells on Unix systems; you will be presented with an instance of your "default login shell" --- for most users this will be the "bash" shell. The system sets the "default login shell" for all users on Zaratan to "bash", and this will remain your default shell until/unless you change it.

Tip

We recommend the "bash" shell for your default shell, as recent versions are both user friendly (or as user friendly as any shell), provides a full set of features for scripting, and is also the default shell for most Linux distributions. This last fact means that not only are you most likely to have encountered it on other linux systems, and that if you search for documentation on the web, it will most likely be using the bash shell.

While we recommend the "bash" shell, we do not require its use. If you wish to use a different Unix shell for your default login shell you can do so. Unfortunately, at this time the only way to change your default login shell is to open a ticket with HPC staff stating what you shell you wish. Currently supported shells are:

  • bash: The Bourne-Again shell, the recommended default login shell. Unless you requested your default login shell be changed, this is your default login shell.
  • sh: The Bourne shell. This lacks most of the more "user-friendly" features added to bash, and Bash is mostly a superset of this shell. We do not recommend this as your default login shell.
  • tcsh: This shell is an enhancement of the C shell, and is relatively user-friendly, but sacrifices many of the features useful for advanced scripting found in the bash shell. We do not recommend it for any but the most basic scripts (as you likely will eventually need something it does not support), nor as your login shell as then you need to use one shell for interactive use and another for scripting.
  • csh: The C shell. Although we do not recommend tcsh, if you really want a C-like shell we recommend tcsh over csh.
  • zsh: The Z shell. This shell is largely similar to the bash shell, but added some features to the bash shell (although some of the features that were unique to zsh have subsequently been added to bash).

Requests for shells other than the above will be considered on a case by case basis.