====== Accessing the Cluster ======

Caviness currently features two //login nodes// through which users interact with the cluster.  The host name ''caviness.hpc.udel.edu'' will connect you to one of those two nodes((//Round-robin DNS load balancing// returns multiple IP addresses when the name ''caviness.hpc.udel.edu'' is looked-up, in random order.  Your SSH client will use the first IP address returned.)).  For example, from a terminal window on a Mac or Linux client:

<code>
localhost$ ssh «username»@caviness.hpc.udel.edu
    :
[«username»@login01 ~]$
</code>

The default shell prompt on Caviness displays the name of the login node.  If a user must connect to a specific login node, use that node's full domain name:

<code>
localhost$ ssh «username»@login00.caviness.hpc.udel.edu
    :
[«username»@login00 ~]$
</code>

When reporting connection problems, please include the ''-vvv'' flag in your ''ssh'' command to produce verbose output and include that output in your help ticket.

**Do not run the ''ssh-keygen'' command on Caviness.**  This command can destroy your account's ability to login to compute nodes without requesting a password.  If you do this by mistake, you can either:

  * recover an older copy of ''~/.ssh'' from your home directory's [[abstract:zfs-snapshots|ZFS snapshots]]
  * execute ''mv ~/.ssh ~/.ssh.bak'', logout and log in to Caviness again (the system will generate a new key pair for you)

===== Workgroups =====

Each entity that invests in the Caviness cluster is given a //workgroup// which encompasses sponsored user accounts, on-cluster storage, and purchased compute resources.  The workgroup name (referenced as **«workgroup»** in this documentation) can refer to

  * The Unix group to which all sponsored user accounts are members
  * The [[caviness:resources#workgroup_directories|shared storage]] allocated to the workgroup
  * The Slurm:
    * Account to which jobs are submitted
    * Partition which grants priority-access to purchased compute resources

The default workgroup for all users is **everyone**; this workgroup has no Slurm partitions available to it and no shared storage space.  To change your shell to a specific workgroup, use the ''workgroup'' command:

<code>
[«username»@login00 ~]$ workgroup -g «workgroup»
[(«workgroup»:«username»)@login00 ~]$
</code>

The ''workgroup'' command is often the first command you will issue after logging-in to the cluster, since it prepares the shell for work within a specific workgroup context((The workgroup's VALET package definitions will become available to you, and the ''$WORKDIR'' environment variable will point to the shared storage.  Also, the Slurm ''sbatch''/''srun''/''salloc'' commands will default to using the «workgroup» account for job submission.)).

<WRAP center round tip 60%>
Workgroups can create a ''$WORKDIR/sw/bin'' directory and add executables to it.  If that directory exists, it is automatically prepended to a sponsored user's ''$PATH'' when using the ''workgroup'' command to enter that workgroup.
</WRAP>

Thereafter, the ''exit'' command will return you to your original login shell:

<code>
[(«workgroup»:«username»)@login00 ~]$ exit
[«username»@login00 ~]$
</code>

==== Workgroup queries ====

The ''workgroup'' command also allows you to query to which workgroups you belong:

<code>
[«username»@login00 ~]$ workgroup --query workgroups
 1001  workgroup1
 1010  workgroup10
</code>

All available options are summarized using the ''workgroup --help'' command.
===== Shell customization =====

**Alteration of your ''.bashrc'' and ''.bash_profile'' files is strongly discouraged.**  Adding directories to the ''PATH'', ''LD_LIBRARY_PATH'', and ''PYTHONPATH'' environment variables is best done using VALET packages and **not** by adding code to your ''.bashrc'' file.  Keeping ''.bashrc'' and ''.bash_profile'' as close to pristine as possible often prevents difficult-to-debug problems from occurring when running jobs on the cluster.

The ''.bash_udit'' file in your home directory controls shell customizations offered by UD IT:

^Variable^Description^
|''IT_WANT_ENV_EXTENSIONS''|Set to ''yes'' to enable the effects of the other variables|
|''IT_SET_WORKGROUP_ON_LOGIN''|Set to ''yes'' to automatically change to your default workgroup at login|
|''IT_DEFAULT_WORKGROUP''|The name of the workgroup to use by default; if unspecified, then the first workgroup listed by the ''workgroup --query workgroups'' command|
|''IT_WORKGROUP_CHDIR''|Change to the workgroup's ''$WORKDIR'' by default|

For example, if the user edits ''.bash_udit'' to set:

<code>
IT_WANT_ENV_EXTENSIONS="yes"
IT_DEFAULT_WORKGROUP="«workgroup»"
IT_WORKGROUP_CHDIR="yes"
IT_SET_WORKGROUP_ON_LOGIN="no"
</code>

then the shell and ''workgroup'' command will behave as follows:

<code>
localhost$ ssh «username»@caviness.hpc.udel.edu
    :
[«username»@login01 ~]$ workgroup
WARNING:  Your working directory has been changed to /work/«workgroup»

[(«workgroup»:«username»)@login01 «workgroup»]$
</code>

All additional adjustments to the shell environment should be handled using [[caviness:valet|VALET]].