Setting up your computing environment


RCF and AFS accounts

Before you can do anything you need an RCF account and an AFS account. Visit the Getting a computer account in STAR for information. When you obtain an account you're automatically given an AFS account as well. The contact person in the last part of the information must be your council representative who must vouch for you. Please, remember to bug your council representative so he can also inform Liz Mogavero of your recent arrival in STAR and send her the updated list of active members from your institution.

Once you have an account you have access to the RHIC AFS cell and the STAR directories and files mounted thereon. You must get an AFS token with the command aklog before accessing any AFS area.

Computers to use

See the Computing Environment or information on STAR and RHIC computers and printers. If you're bringing a computer of your own to BNL contact Jerome Lauret or Wayne Betts regarding an IP address.

Set up your login

This login environment is partly related to HEPiX, a standard within the HENP community and used at many labs. Starting in the middle of 2001, the standard STAR login was chosen to be a stand-alone minimal login instead of the default HEPix login and stack suite (which became unmaintainable and cumbersome). Older users should follow the above instructions and update their .cshrc and .login file if not already done.

The STAR group on the RCF machines is rhstar. The group directory with scripts for the STAR environment is GROUP_DIR = /afs/ There is also a link /afs/ -> /afs/ Note that the initial /afs/ AFS volume needed to change name in mid-2003 to comply with Kerberos 5 authentication and token passing mechanism. It is however a link toward the volume but its use should be discontinued.

If your Unix group is different from star or rhstar, first of all you should ask to the RCF team that you be added to the rhstar group (submit a ticket, see the Software Infrastructure for more instructions). Several possibilities/scenario are now described :

  1. Your account was recently created by the RCF team : there should be nothing to do.
  2. Your account was created on a remote site, and you have access to the RHIC AFS cell : you could either
    • Copy /afs/ and /afs/ as .cshrc and .login in your home directory. Alternatively, the files are located in $GROUP_DIR at your local site (but there is a chicken and an egg issue - without a proper STAR login, GROUP_DIR will not be defined so you may have to ask your local sysadmin where it is located)
         % cp /afs/ ~/.cshrc
         % cp /afs/ ~/.login
    • You may want to copy/clone the /afs/ on a local storage and modify the variable GROUP_DIR located on top of your .login and .cshrc after you have accomplish step 1.

Then you can customize both .cshrc and .login for your taste (or source separate personal setups from them).

When you next logout and log back in, your PATH, MANPATH, and LD_LIBRARY_PATH will include the proper STAR directories. Your environment variables will also include several STAR variables (below).

The group login script

The group environment variables are defined in the group_env.csh script. Some of the more important environment variables set up by this script follows. The variable in blue, if defined before the login scripts are loaded, will not be superseded. Variables in green are likely already defined if the optional component has been deployed on your machine. Variable in red are fixed values on purpose to ensure compatibility and the strict install path MUST be present for STAR's environment to load properly.

  • AFS : afs utility directory [ default = /usr/afsws ]
  • AFS_RHIC : top rhic directory path [ default = /afs/ ]
  • CERN : a canonical base path for the CERN environment. If undefined the first path in the following list found will be used as default starting point: /cern, ${AFS_RHIC}/asis/@sys/cern, /usr/local/cern, /common/star/cern . If the USE_64BITS environment variable is set, the 64 bits path will be assumed. The path ${CERN}64 will be searched (for example /cern64) and if not found, the full previous list will be searched for and additionally, each path with the post-fixed "64" will be also search.
    If nothing is found (still), a default value /cern will be set
  • CERN_LEVEL : base path for the current version of CERN library.
    If undefined, will be set to “pro
  • CERN_ROOT: will equate to ${CERN}/${CERN_LEVEL}
  • CVSROOT : the STAR CVS repository. A local install with AFS access would define this as the AFS version before the login scripts executes. BUT the default is otherwise ${STAR_PATH}/repository if this path is found (for a local install, do NOT create this directory and define CVSROOT to point to the AFS version). A soft-link to the AFS area would equally work.
  • GROUP_DIR : star group login scripts [ default = $AFS_RHIC/star/group/ ] . This directory contains login scripts used to setup the rest of the environment. Note that you should be able to cvs checkout as-is this directory on your local machine / cluster and still be functional. If this is not the case, you should contact the Infrastructure Leader immediately.
  • XOPTSTAR : AFS resident base directory [ default = ${AFS_RHIC}/opt/star (see also $OPTSTAR below). Although this variable may be redefined, it would be hazardous to do so ...
  • OPTSTAR : Base directory for updates of /usr/XXX or /usr/local/XXX [ default = either /opt/star if exists or $XOPTSTAR ]. Note that for a local setup, the entire tree $XOPTSTAR may be installed on your local cluster and $OPTSTAR variable defined appropriately before loading the group environment script.
  • SCRATCH : This variable indicates a SCRATCH space which may be used by a job in a batch system.
    Note the variable SCRATCH_LOCAL is defined, SCRATCH will take its value.
    If undefined, SCRATCH will take the value of (in this order) TMPDIR (if defined), /scratch/$LOGNAME if /scratch exists and is writable or finally, /tmp/$LOGNAME.
  • STAR : the top directory path for the particular version of STAR software
  • STAR_ROOT : the top directory path to all STAR software [default = ${AFS_RHIC}/star or /usr/local/star ]
  • STAR_PATH : the top directory path to STAR release libraries software [ ${STAR_ROOT}/packages]
  • STAR_LEVEL : dev/new/pro/old version of software. If undefined, the default value is “pro
  • STAR_VERSION: SL98d/SL98c/SL98b/SL98a version of software
  • INTELC_VERSION: 9.1, 10.1 and so on, a version of the intel compiler to be considered as default if defined (and if installed)
  • ROOT: If defined, this will be the base path for finding the ROOT package installation files. Each revision is supposed to be appear under ${ROOT} and the STAR ROOT installation directory tree is expected to be found underneath (see Building ROOT in STAR for more information). Essentially, ROOTSYS, ROOT_LEVEL will be set by our login script. If not defined, SAR login will search for it in ${STAR_ROOT}/ROOT .
  • ROOTSYS : ROOT system directory
  • STAR_SYS : architecture (i386_linux2, sun4x_56, i386_sl302 ...).
    This is what is used for AFS access via the @sys replacement.
    In a local installation environment (non-AFS based), this variable need to be used to access the partition containing the equivalent of what you find in AFS land.
  • STAR_HOST_SYS : architecture flag used for separating compilation results (may be be equal to STAR_SYS but usually, contains the compiler style and version in it).
  • STAR_LIB : the top directory path of the particular version of STAR Library (usually set to something like $STAR/.${STAR_HOST_SYS}/lib )
  • STAR_BIN : the pointer to StAF executables, Geant3, stic, ...
  • STAR_DATA : the top directory for ``test'' data samples. This defaults to ${STAR_ROOT}/data but is not essential for the STAR environment. Hence, if this path is not found, the ogin will not define this environment variable and continue. You may also create a soft-link to the AFS area (but this again is not needed and historical).
  • USE_GCC_DIR :  an alternate path for gcc installation. This is a one time definition (you cannot redefine, re-execute the login and have the path reset). Alternatively, the "setup" script provides provision for alternate gcc version to be installed as /opt/gcc/$version (multiple version support) and this environment was only provides for sites that cannot comply with the more flexible location.

Other variables are

  • CLHEP_BASE_DIR : base path for the CLHEP libraries. [ default = ${OPTSTAR} ]
  • QTDIR : the base path for Qt installation. Equal to $OPTSTAR/qt and if found, will overwrite any value previously set. If not found, $OPTSTAR/qt3 and $OPTSTAR/qt4 will be searched in respective order and QTDIR defined accordingly but only if QTDIR is not already defined (no overwrite in this case).
  • INSV : the insure version level. The login script will be looking in $AFS_RHIC/app/$INSV if this directory exists
  • JAVA_ROOT : the base path for java installation. Directories like bin/ man/ etc ... are expected to be below this level [default = latest version in /usr/java ]
Grid related environment variables:
  • WNOSG: a path where a Worker Node, client install of the grid toolkit is available.
  • GLOBUS_PATH : a path to “a” globus installation is available (old VDT or new OSG). If found, WNOSG will NOT be considered.
  • OSG: a path where an OSG installation exists. This will overwrite the GLOBUS/VDT definitions and WNOSG will be ignored.

The following environment variables may, if defined, affect run-time of our STAR code - DO NOT set those yourself unless permission granted.

  • StarEndMakerShell - if defined, prints additional statistics from StMaker related to Memory (using StMemStat) - expensive operation, makes sense on production mode only or when the chain time is much larger than the invocation of statistics collections (i.e. not goof for user anlaysis)
  • HYPERCONFIG_LOCATION - the fully specified location of the HyperCache configuration (replaces the default $STAR_PATH/conf/hyperconfig.json) - debug mode only
  • STAR_DEBUG_DB_RETRIES_ADMINS - used by StDbServiceBroker service, defines a set of administrators who will receive an Email in case of DB connection problems. If defined, an Email will be sent of no connections is granted within STAR_DEBUG_DB_RETRIES_SECONDS (default 1800 seconds or 30 minutes).

The PATH environment variable is appended with directories containing executables which are needed by the STAR computing environment. For example:

  • /usr/afsws/bin : AFS utilities
  • /usr/afsws/etc : AFS utilities
  • /opt/rhic/bin : opt rhic is RHIC wide update for /usr/bin and /usr/local/bin .
  • /usr/local/bin : updates to /usr/bin. At the RCF this is what we took from CERN
  • $STAR/mgr : scripts for ``dev/new/pro/old'' version of STAR library
  • /usr/sbin : System
  • /opt/SUNWspro/bin : System (Sun syste only - obsolete)
  • /usr/ccs/bin : System
  • /usr/ccs/lib : System
  • /usr/bin : System
  • /usr/openwin/bin : System
  • /usr/dt/bin : System
  • /usr/ucb : System
  • /usr/local/bin/X11 : System


Note on /afs/ and /opt/star versus Linux

While at the RCF, /opt/star is a soft link to /afs/, there is a misleading component to the the path /afs/ ... The real path is /afs/ and depends on the result of the translation of the AFS @sys set on YOUR client. The current translation has been so far as follow

Linux release support Notes or
Also supports
Result of fs sysname MUST be
RH 6.1 (obsolete) i386_redhat61
RH 7.2 (obsolete) i386_linux24
RH 8 (obsolete) i386_redhat80
SL 3.0.2 (obsolete - was for gcc 3.2.3, SL 3.0.4, rh3 but no build node available at BNL - EOL was end of 2008) i386_sl302
SL 3.0.5 (obsolete - was gcc 3.2.3 - SL 3.0.{6|7|8|9}, rh3) i386_sl305
SL 4.4 gcc 3.4.6 - SL 4.5, rh4 i386_sl4
SL 5 gcc 4.3.2 - SL 5.3 native, {sl|rh}55 & 56 & 57 with gcc 4.3.2 x8664_sl5 (32 / 64 bits)
i386_sl5 (32 bits only)
SL6 gcc 4.4.6 - SL 6.2 native x8664_sl6 (32 and 64 bits)


A typical problem for off-site facilities is to deploy a version of Linux with no match for sysname (or wrong match). For example, RedHat8.0 set with i386_linux24 will pick up the program in the wrong AFS area, a RedHat 9.0 system would be equally problematic as currently not supported. There are some backward compatibility support for other Linux OS versions we document in the second column. If your OS does not appear in this table, you could send a note for a request support to the offsites or starsofi Hypernews fora.

The sysname is configured in /etc/sysconfig/afs . It uses a default value or is set via a line similar to the following

AFS_POST_INIT="/usr/bin/fs sysname -newsys i386_sl5"