Differences

This shows you the differences between two versions of the page.

--- caviness:login [2019/06/27 14:56]
frey created
+++ caviness:login [2020/11/09 15:14] (current)
frey [Shell customization]
@@ Line 1: / Line 1: @@
 ====== 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 the user 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.  The user's SSH client will always use the first address returned.)).
+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
+  workgroup1
+  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]].