bwHPC Wiki - User contributions [en]

Main Page

2026-08-11T09:50:47Z

H Schumacher: added link to news and success stories

'''Welcome to the bwHPC Wiki.'''

bwHPC represents services and resources in the State of '''B'''aden-'''W'''ürttemberg, Germany, for High Performance Computing ('''HPC'''), Data Intensive Computing ('''DIC''') and Large Scale Scientific Data Management ('''LS2DM''').

The main bwHPC web page is at '''[https://www.bwhpc.de/ https://www.bwhpc.de/]''' including the latest [https://www.bwhpc.de/news.html News] and [https://www.bwhpc.de/projects.php Success Stories].

Many topics depend on the cluster system you use.
First choose the cluster you use, then select the correct topic.


{{Template:Status|ok|Status: Ok}}





{| style=" background:#eeeefe; width:100%;"
| style="padding:8px; background:#dedefe; font-size:120%; font-weight:bold; text-align:left" | Courses / eLearning
|-
|
* [https://training.bwhpc.de/ eLearning and Online Courses]
* [https://hpc-wiki.info/hpc/Introduction_to_Linux_in_HPC Introduction to Linux in HPC (external resource)]
|}

{| style=" background:#deffee; width:100%;"
| style="padding:8px; background:#cef2e0; font-size:120%; font-weight:bold; text-align:left" | [[File:Clusternodes.svg|x20px]] Need Access to a Cluster?
|-
|
* [[When to use an HPC Cluster]]
* [[Running Calculations]]
* [[Registration]]
|}

{| style=" background:#deffee; width:100%;"
| style="padding:8px; background:#cef2e0; font-size:120%; font-weight:bold; text-align:left" | [[File:Clusternodes.svg|x20px]] HPC System Specific Documentation
|-
|
bwHPC encompasses several HPC compute clusters at different universities in Baden-Württemberg. Each cluster is dedicated to [https://www.bwhpc.de/bwhpc-domains.php specific research domains].

Documentation differs between compute clusters, please see cluster specific overview pages:
{|
|-
| style="padding:5px; width:30%" | [[BwUniCluster3.0|bwUniCluster 3.0]]
| style="padding-left:20px;" | General Purpose, Teaching
|-
| style="padding:5px; width:30%" | [[BinAC2|bwForCluster BinAC 2]]
| style="padding-left:20px;" | Bioinformatics, Astrophysics, Geosciences, Pharmacy, and Medical Informatics
|-
| style="padding:5px; width:30%" | [[Helix|bwForCluster Helix]]
| style="padding-left:20px;" | Structural and Systems Biology, Medical Science, Soft Matter, Computational Humanities, and Mathematics and Computer Science
|-
| style="padding:5px; width:30%" | [[:JUSTUS2| bwForCluster JUSTUS 2]]
| style="padding-left:20px;" | Theoretical Chemistry, Condensed Matter Physics, and Quantum Sciences
|-
| style="padding:5px; width:30%" | [[NEMO2|bwForCluster NEMO 2]]
| style="padding-left:20px;" | Neurosciences, Particle Physics, Materials Science, and Microsystems Engineering
|}
|-
|bwHPC Clusters: [https://www.bwhpc.de/cluster.php operational status]
Further Compute Clusters in Baden-Württemberg (separate access policies):
* [[DACHS | Datenanalyse Cluster der Hochschulen (DACHS)]]
* bwHPC tier 1: [https://kb.hlrs.de/platforms/index.php/Hunter_(HPE) Hunter] ([https://www.hlrs.de/apply-for-computing-time getting access])
* bwHPC tier 2: [https://www.nhr.kit.edu/userdocs/horeka HoreKa] ([https://www.nhr.kit.edu/userdocs/horeka/projects/ getting access])
|}

{| style="background:#deffee; width:100%;"
| style="padding:8px; background:#cef2e0; font-size:120%; font-weight:bold; text-align:left" | [[File:Clusternodes.svg|x20px]] Documentation valid for all Clusters
|-
|
* [[Environment Modules| Software Environment Modules]]: usage of preexisting software
* [https://www.bwhpc.de/software.html List of Software] on all clusters
* [[Data Transfer|Data Transfer]]: working with files [[File:Notebook.svg|x15px]] <---> [[File:Clusternodes.svg|x15px]]
* [[Development| Development]]: software, programming languages, parallel pogramming
* [[Energy Efficient Cluster Usage | (Energy) Efficient Cluster Usage]] for low waiting times and fast running jobs
* [[HPC Glossary]]

{| style="height:100%; background:#ffeaef; width:100%"
| style="padding:8px; background:#f5dfdf; font-size:120%; font-weight:bold; text-align:left" | [[File:Storage_small.svg|x15px]] Scientific Data Storage
|-
|
User guides of available scientific data storage services:
* [[SDS@hd]]: Everyone can join existing storage projects, entitlement needed for creating your own, [https://sds-hd.urz.uni-heidelberg.de/management/shib/sds_costs.php cost sheet]
* [https://uni-tuebingen.de/einrichtungen/zentrum-fuer-datenverarbeitung/projekte/laufende-projekte/bwsfs bwSFS]
Associated, but local scientific storage services are:
* [https://wiki.scc.kit.edu/lsdf/index.php/Category:LSDF_Online_Storage LSDF Online Storage] (only for KIT and KIT partners)
|}

{| style="height:100%; background:#ffeaef; width:100%"
| style="padding:8px; background:#f5dfdf; font-size:120%; font-weight:bold; text-align:left" | [[File:Storage_small.svg|x15px]] Scientific Data Archiving
|-
|
For user guides of the scientific data archiving services:
* [https://www.rda.kit.edu/english bwDataArchive]: Open to all scientists at KIT and institutions in Baden-Württemberg that have signed a service agreement with KIT
Associated, but local archiving services for scientific data are:
* [https://www.urz.uni-heidelberg.de/de/service-katalog/speicher/heiarchive heiARCHIVE] (only for members of Heidelberg University)
For instructions on how to move the data, depending on the offered connections, can be found under [[Data Transfer | Data Transfer]].
|}

{| style="height:100%; background:#ffeaef; width:100%"
| style="padding:8px; background:#f5dfdf; font-size:120%; font-weight:bold; text-align:left" | Research Data Management
|-
|
* [https://www.forschungsdaten.org/index.php/FDM-Kontakte#Deutschland Research Data Management (RDM)] contact persons
* [https://www.forschungsdaten.info Portal for Research Data Management] (Forschungsdaten.info)
|}
{| style=" background:#eeeefe; width:100%;"
| style="padding:8px; background:#dedefe; font-size:120%; font-weight:bold; text-align:left" | Support
|-
|
* [[BwSupportPortal|Submit a Ticket in our Support Portal]]
Support is provided by the [https://www.bwhpc.de/teams.php bwHPC Competence Centers]:
|}
{| style=" background:#e6e9eb; width:100%;"
| style="padding:8px; background:#d1dadf; font-size:120%; font-weight:bold; text-align:left" | Acknowledgement
|-
|
* Please [[Acknowledgement|acknowledge]] our resources in your publications.
|}

MediaWiki:Sidebar

2026-08-11T08:18:07Z

H Schumacher: removed "cluster"

MediaWiki:Sidebar

2026-08-11T08:16:58Z

H Schumacher: added engergy efficient cluster usage

BwForCluster JUSTUS 2 Slurm HOWTO

2026-07-30T17:06:49Z

H Schumacher: added interactive job cancelling

{{Justus2}}

This is a collection of howtos and convenient Slurm commands for JUSTUS 2.

Some commands behave slightly different depending on whether they are executed
by a system administrator or by a regular user, as Slurm prevents regular users from accessing critical system information and viewing job and usage information of other users.

= GENERAL INFORMATION =

== How to find a general quick start user guide? ==

https://slurm.schedmd.com/quickstart.html

== How to find Slurm FAQ? ==

https://slurm.schedmd.com/faq.html

== How to find a Slurm cheat sheet? ==

https://slurm.schedmd.com/pdfs/summary.pdf

== How to find Slurm tutorials? ==

https://slurm.schedmd.com/tutorials.html

== How to get more information on Slurm? ==

(Almost) every Slurm command has a man page. Use it.

Online versions: https://slurm.schedmd.com/man_index.html

== How to find hardware specific details about JUSTUS 2? ==

See our Wiki page: [[Hardware and Architecture (bwForCluster JUSTUS 2)|Hardware and Architecture]]

= JOB SUBMISSION =

== How to submit a serial batch job? ==

Use [https://slurm.schedmd.com/sbatch.html sbatch] command:

<pre>$ sbatch <job-script> </pre>

Sample job script template for serial job:

<source lang="bash">
#!/bin/bash
# Allocate one node
#SBATCH --nodes=1
# Number of program instances to be executed
#SBATCH --ntasks-per-node=1
# 8 GB memory required per node
#SBATCH --mem=8G
# Maximum run time of job
#SBATCH --time=1:00:00
# Give job a reasonable name
#SBATCH --job-name=serial_job
# File name for standard output (%j will be replaced by job id)
#SBATCH --output=serial_job-%j.out
# File name for error output
#SBATCH --error=serial_job-%j.err

# Load software modules as needed, e.g.
# module load foo/bar

# Run serial program
./my_serial_program
</source>

Sample code for serial program: [[Media:Hello_serial.c | Hello_serial.c]]

'''Notes:'''
* --nodes=1 and --ntasks-per-node=1 may be replaced by --ntasks=1.
* If not specified, stdout and stderr are both written to slurm-%j.out.

== How to find working sample scripts for my program? ==

Most software modules for applications provide working sample batch scripts.
Check with [[Software_Modules_Lmod#Module_specific_help | module help]] command, e.g.
<pre>
$ module help chem/vasp # display module help for VASP
$ module help math/matlab # display module help for Matlab
</pre>

== How to harden job scripts against common errors? ==

The bash shell provides several options that support users in disclosing hidden bugs and writing safer job scripts.
In order to activate these safeguard settings users can insert the following lines in their scripts (after all #SBATCH directives):

<source lang="bash">
[...]
set -o errexit # (or set -e) cause batch script to exit immediately when a command fails.
set -o pipefail # cause batch script to exit immediately also when the command that failed is embedded in a pipeline
set -o nounset # (or set -u) causes the script to treat unset variables as an error and exit immediately
[...]
</source>

== How to submit an interactive job? ==

Use [https://slurm.schedmd.com/salloc.html salloc] command, e.g.:
<pre>$ salloc --nodes=1 --ntasks-per-node=8</pre>

'''Note:'''

In previous Slurm versions < 20.11 the use of [https://slurm.schedmd.com/srun.html srun] has been the recommended way for launching interactive jobs, e.g.:

<pre>$ srun --nodes=1 --ntasks-per-node=8 --pty bash </pre>

Although this still works with current Slurm versions this is considered '''deprecated ''' for current Slurm versions as it may cause issues when launching additional jobs steps from within the interactive job environment. Use [https://slurm.schedmd.com/salloc.html salloc] command.

== How to enable X11 forwarding for an interactive job? ==

Use '--x11' flag, e.g.

<pre>
$ salloc --nodes=1 --ntasks-per-node=8 --x11 # run shell with X11 forwarding enabled
</pre>

'''Note:'''
* For X11 forwarding to work, you must also enable X11 forwarding for your ssh login from your local computer to the cluster, i.e.:
<pre>local> ssh -X <username>@justus2.uni-ulm.de></pre>

== How to convert Moab batch job scripts to Slurm? ==

Replace Moab/Torque job specification flags and environment variables in your job
scripts by their corresponding Slurm counterparts.

'''Commonly used Moab job specification flags and their Slurm equivalents'''

{| width=750px class="wikitable"
! Option !! Moab (msub) !! Slurm (sbatch)
|-
| Script directive || #MSUB || #SBATCH
|-
| Job name || -N <name> || --job-name=<name> (-J <name>)
|-
| Account || -A <account> || --account=<account> (-A <account>)
|-
| Queue || -q <queue> || --partition=<partition> (-p <partition>)
|-
| Wall time limit || -l walltime=<hh:mm:ss> || --time=<hh:mm:ss> (-t <hh:mm:ss>)
|-
| Node count || -l nodes=<count> || --nodes=<count> (-N <count>)
|-
| Core count || -l procs=<count> || --ntasks=<count> (-n <count>)
|-
| Process count per node || -l ppn=<count> || --ntasks-per-node=<count>
|-
| Core count per process || || --cpus-per-task=<count> (-c <count>)
|-
| Memory limit per node || -l mem=<limit> || --mem=<limit>
|-
| Memory limit per process || -l pmem=<limit> || --mem-per-cpu=<limit>
|-
| Job array || -t <array indices> || --array=<indices> (-a <indices>)
|-
| Node exclusive job || -l naccesspolicy=singlejob || --exclusive
|-
| Initial working directory || -d <directory> (default: $HOME) || --chdir=<directory> (-D <directory>) (default: submission directory)
|-
| Standard output file || -o <file path> || --output=<file> (-o <file>)
|-
| Standard error file || -e <file path> || --error=<file> (-e <file>)
|-
| Combine stdout/stderr to stdout || -j oe || --output=<combined stdout/stderr file>
|-
| Mail notification events || -m <event> || --mail-type=<events> (valid types include: NONE, BEGIN, END, FAIL, ALL)
|-
| Export environment to job || -V || --export=ALL (default)
|-
| Don't export environment to job || (default) || --export=NONE
|-
| Export environment variables to job || -v <var[=value][,var2=value2[, ...]]> || --export=<var[=value][,var2=value2[,...]]>
|}

'''Notes:'''
* Default initial job working directory is $HOME for Moab. For Slurm the default working directory is where you submit your job from.
* By default Moab does not export any environment variables to the job's runtime environment. With Slurm most of the login environment variables are exported to your job's runtime environment. This includes environment variables from software modules that were loaded at job submission time (and also $HOSTNAME variable).

'''Commonly used Moab/Torque script environment variables and their Slurm equivalents

{| width=750px class="wikitable"
! Information !! Moab !! Torque !! Slurm
|-
| Job name || $MOAB_JOBNAME || $PBS_JOBNAME || $SLURM_JOB_NAME
|-
| Job ID || $MOAB_JOBID || $PBS_JOBID || $SLURM_JOB_ID
|-
| Submit directory || $MOAB_SUBMITDIR || $PBS_O_WORKDIR || $SLURM_SUBMIT_DIR
|-
| Number of nodes allocated || $MOAB_NODECOUNT || $PBS_NUM_NODES || $SLURM_JOB_NUM_NODES (and: $SLURM_NNODES)
|-
| Node list || $MOAB_NODELIST || cat $PBS_NODEFILE || $SLURM_JOB_NODELIST
|-
| Number of processes || $MOAB_PROCCOUNT || $PBS_TASKNUM || $SLURM_NTASKS
|-
| Requested tasks per node || --- || $PBS_NUM_PPN || $SLURM_NTASKS_PER_NODE
|-
| Requested CPUs per task || --- || --- || $SLURM_CPUS_PER_TASK
|-
| Job array index || $MOAB_JOBARRAYINDEX || $PBS_ARRAY_INDEX || $SLURM_ARRAY_TASK_ID
|-
| Job array range || $MOAB_JOBARRAYRANGE || - || $SLURM_ARRAY_TASK_COUNT
|-
| Queue name || $MOAB_CLASS || $PBS_QUEUE || $SLURM_JOB_PARTITION
|-
| QOS name || $MOAB_QOS || --- || $SLURM_JOB_QOS
|-
| Number of processes per node | --- || $PBS_NUM_PPN || $SLURM_TASKS_PER_NODE
|-
| Job user || $MOAB_USER || $PBS_O_LOGNAME || $SLURM_JOB_USER
|-
| Hostname || $MOAB_MACHINE || $PBS_O_HOST || $SLURMD_NODENAME
|}

'''Note:'''

* See [https://slurm.schedmd.com/sbatch.html sbatch] man page for a complete list of flags and environment variables.

== How to emulate Moab output file names? ==

Use the following directives:

<pre>
#SBATCH --output="%x.o%j"
#SBATCH --error="%x.e%j"
</pre>

== How to pass command line arguments to the job script? ==

Run <pre>$ sbatch <job-script> arg1 arg2 ...</pre>

Inside the job script the arguments can be accessed as $1, $2, ...

E.g.:

<source lang="bash">
[...]
infile="$1"
outfile="$2"
./my_serial_program < "$infile" > "$outfile" 2>&1
[...]
</source>

'''Notes:'''

* Do '''not''' use $1, $2, ... in "#SBATCH" lines. These parameters can be used only within the regular shell script.

== How to request local scratch (SSD/NVMe) at job submission? ==

Use '--gres=scratch:nnn' option to allocate nnn GB of local (i.e. node-local) scratch space for the entire job.

Example: '--gres=scratch:100' will allocate 100 GB scratch space on a locally attached NVMe device.

'''Notes:'''

* Do '''not''' add any unit (such as --gres=scratch:100G). This would be treated as requesting an amount of 10^9 * 100GB of scratch space.

* Multinode jobs get nnn GB of local scratch space on every node of the job.

* Environment variable '''$SCRATCH''' will point to
** /scratch/<user>.<jobid> when local scratch has been requested. This will be on locally attached SSD/NVMe devices.
** /tmp/<user>.<jobid> when no local scratch has been requested. This will be in memory and, thus, be limited in size.

* Environment variable '''$TMPDIR''' always points to /tmp/<user>.<jobid>. This will always be in memory and, thus, limited in size.

* For backward compatibility environment variable $RAMDISK always points to /tmp/<user>.<jobid>

* Scratch space allocation in /scratch will be enforced by quota limits

* Data written to $TMPDIR will always count against allocated memory.

* Data written to local scratch space will automatically be removed at the end of the job.

== How to request GPGPU nodes at job submission? ==

Use '--gres=gpu:<count>' option to allocate 1 or 2 GPUs per node for the entire job.

Example: '--gres=gpu:1' will allocate one GPU per node for this job.

'''Notes:'''

* GPGPU nodes are equipped with two Nvidia V100S cards

* Environment variables $CUDA_VISIBLE_DEVICES, $SLURM_JOB_GPUS and $GPU_DEVICE_ORDINAL will denote card(s) allocated for the job.

* CUDA Toolkit is available as software module devel/cuda.

== How to clean-up or save files before a job times out? ==

Possibly you would like to clean up the work directory or save intermediate result files in case a job times out.

The following sample script may serve as a blueprint for implementing a pre-termination function to perform clean-up or file recovery actions.

<source lang="bash">
#!/bin/bash
# Allocate one node
#SBATCH --nodes=1
# Number of program instances to be executed
#SBATCH --ntasks-per-node=1
# 2 GB memory required per node
#SBATCH --mem=2G
# Request 10 GB local scratch space
#SBATCH --gres=scratch:10
# Maximum run time of job
#SBATCH --time=10:00
# Send the USR1 signal 120 seconds before end of time limit
#SBATCH --signal=B:USR1@120
# Give job a reasonable name
#SBATCH --job-name=signal_job
# File name for standard output (%j will be replaced by job id)
#SBATCH --output=signal_job-%j.out
# File name for error output
#SBATCH --error=signal_job-%j.err

# Define the signal handler function
# Note: This is not executed here, but rather when the associated
# signal is received by the shell.
finalize_job()
{
# Do whatever cleanup you want here. In this example we copy
# output file(s) back to $SLURM_SUBMIT_DIR, but you may implement
# your own job finalization code here.
echo "function finalize_job called at `date`"
cd $SCRATCH
mkdir -vp "$SLURM_SUBMIT_DIR"/results
tar czvf "$SLURM_SUBMIT_DIR"/results/${SLURM_JOB_ID}.tgz output*.txt
exit
}

# Call finalize_job function as soon as we receive USR1 signal
trap 'finalize_job' USR1

# Copy input files for this job to the scratch directory (if needed).
# Note: Environment variable $SCRATCH always points to a scratch directory
# automatically created for this job. Environment variable $SLURM_SUBMIT_DIR
# points to the path where this script was submitted from.
# Example:
# cp -v "$SLURM_SUBMIT_DIR"/input*.txt "$SCRATCH"

# Change working directory to local scratch directory
cd "$SCRATCH"

# Load software modules as needed, e.g.
# module load foo/bar

# This is where the actual work is done. In this case we just create
# a sample output file for 900 (=15*60) seconds, but since we asked
# Slurm for 600 seconds only it will not be able finish within this
# wall time.
# Note: It is important to run this task in the background
# by placing the & symbol at the end. Otherwise the signal handler
# would not be executed until that process has finished, which is not
# what we want.
(for i in `seq 15`; do echo "Hello World at `date +%H:%M:%S`."; sleep 60; done) >output.txt 2>&1 &

# Note: The command above is just for illustration. Normally you would just run
# my_program >output.txt 2>&1 &

# Tell the shell to wait for background task(s) to finish.
# Note: This is important because otherwise the parent shell
# (this script) would proceed (and terminate) without waiting for
# background task(s) to finish.
wait

# If we get here, the job did not time out but finished in time.

# Release user defined signal handler for USR1
trap - USR1

# Do regular cleanup and save files. In this example we simply call
# the same function that we defined as a signal handler above, but you
# may implement your own code here.
finalize_job

exit
</source>

'''Notes:'''

* The number of seconds specified in --signal option must match the runtime of the pre-termination function and must not exceed 65535 seconds.

* Due to the resolution of event handling by Slurm, the signal may be sent a little earlier than specified.

== How to submit a multithreaded batch job? ==

Sample job script template for a job running one multithreaded program instance:

<source lang="bash">
#!/bin/bash
# Allocate one node
#SBATCH --nodes=1
# Number of program instances to be executed
#SBATCH --ntasks-per-node=1
# Number of cores per program instance
#SBATCH --cpus-per-task=8
# 8 GB memory required per node
#SBATCH --mem=8G
# Maximum run time of job
#SBATCH --time=1:00:00
# Give job a reasonable name
#SBATCH --job-name=multithreaded_job
# File name for standard output (%j will be replaced by job id)
#SBATCH --output=multithreaded_job-%j.out
# File name for error output
#SBATCH --error=multithreaded_job-%j.err

# Load software modules as needed, e.g.
# module load foo/bar

export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK}
export MKL_NUM_THREADS=${SLURM_CPUS_PER_TASK}

# Run multithreaded program
./my_multithreaded_program
</source>

Sample code for multithreaded program: [[Media:Hello_openmp.c | Hello_openmp.c]]

'''Notes:'''

* In our configuration each physical core is considered a "CPU".

* On JUSTUS 2 it is recommended to specify a number of cores per task ('--cpus-per-task') that is either an integer divisor of 24 or (at most) 48.

* Required memory can also by specified per allocated CPU with '--mem-per-cpu' option.

* The '--mem' and '--mem-per-cpu' options are mutually exclusive.

== How to submit an array job? ==

Use [https://slurm.schedmd.com/sbatch.html#OPT_array -a] (or [https://slurm.schedmd.com/sbatch.html#OPT_array --array]) option, e.g.

<pre>$ sbatch -a 1-16%8 ...</pre>

This will submit 16 tasks to be executed, each one indexed by SLURM_ARRAY_TASK_ID ranging from 1 to 16, but will limit the number of simultaneously running tasks from this job array to 8.

Sample job script template for an array job:

<source lang="bash">
#!/bin/bash
# Number of cores per individual array task
#SBATCH --ntasks=1
#SBATCH --array=1-16%8
#SBATCH --mem=4G
#SBATCH --time=01:00:00
#SBATCH --job-name=array_job
#SBATCH --output=array_job-%A_%a.out
#SBATCH --error=array_job-%A_%a.err

# Load software modules as needed, e.g.
# module load foo/bar

# Print the task id.
echo "My SLURM_ARRAY_TASK_ID: " $SLURM_ARRAY_TASK_ID

# Add lines here to run your computations, e.g.
# ./my_program <input.$SLURM_ARRAY_TASK_ID

</source>

'''Notes:'''

* Placeholder %A will be replaced by the master job id, %a will be replaced by the array task id.

* Every sub job in an array job will have its own unique environment variable $SLURM_JOB_ID. Environment variable $SLURM_ARRAY_JOB_ID will be set to the first job array index value for all tasks.

* The remaining options in the sample job script are the same as the options used in other, non-array jobs. In the example above, we are requesting that each array task be allocated 1 CPU (--ntasks=1) and 4 GB of memory (--mem=4G) for up to one hour (--time=01:00:00).

* More information: https://slurm.schedmd.com/job_array.html

== How to delay the start of a job? ==

Use [https://slurm.schedmd.com/sbatch.html#OPT_begin -b] (or [https://slurm.schedmd.com/sbatch.html#OPT_begin --begin]) option in order to defer the allocation of the job until the specified time.

Examples:

<pre>
sbatch --begin=20:00 ... # job can start after 8 p.m.
sbatch --begin=now+1hour ... # job can start 1 hour after submission
sbatch --begin=teatime ... # job can start at teatime (4 p.m.)
sbatch --begin=2023-12-24T20:00:00 ... # job can start after specified date/time
</pre>

== How to submit dependency (chain) jobs? ==

Use [https://slurm.schedmd.com/sbatch.html#OPT_dependency -d] (or [https://slurm.schedmd.com/sbatch.html#OPT_dependency --dependency]) option, e.g.

<pre>$ sbatch -d afterany:123456 ...</pre>

This will defer the submitted job until the specified job 123456 has terminated.

Slurm supports a number of different dependency types, e.g.:

<pre>
-d after:123456 # job can begin execution after the specified job has begun execution
-d afterany:123456 # job can begin execution after the specified job has finished
-d afternotok:123456 # job can begin execution after the specified job has failed (exit code not equal zero)
-d afterok:123456 # job can begin execution after the specified job has successfully finished (exit code zero)
-d singleton # job can begin execution after any previously job with the same job name and user have finished
</pre>

'''Note:''' Multiple jobs can be specified by separating their job ids by colon characters (:), e.g.

<pre> $ sbatch -d afterany:123456:123457 ... </pre>

This will defer the submitted job until the specified jobs 123456 and 123457 have both finished.

== How to deal with invalid job dependencies? ==

Use [https://slurm.schedmd.com/sbatch.html#OPT_kill-on-invalid-dep --kill-on-invalid-dep=yes] option in order to automatically terminate jobs which can never run due to invalid dependencies. By default the job stays pending with reason 'DependencyNeverSatisfied' to allow review and appropriate action by the user.

'''Note:''' A job dependency may also become invalid if a job has been submitted with '-d afterok:<jobid>' but the specified dependency job has failed, e.g. because it timed out (i.e. exceeded its wall time limit).

== How to submit an MPI batch job? ==

Suggested reading: https://slurm.schedmd.com/mpi_guide.html

Sample job script template for an MPI job:

<source lang="bash">
#!/bin/bash
# Allocate two nodes
#SBATCH --nodes=2
# Number of program instances to be executed
#SBATCH --ntasks-per-node=48
# Allocate 32 GB memory per node
#SBATCH --mem=32gb
# Maximum run time of job
#SBATCH --time=1:00:00
# Give job a reasonable name
#SBATCH --job-name=mpi_job
# File name for standard output (%j will be replaced by job id)
#SBATCH --output=mpi_job-%j.out
# File name for error output
#SBATCH --error=mpi_job-%j.err

# Add lines here to run your computations, e.g.
#
# Option 1: Lauch MPI tasks by using mpirun
#
# for OpenMPI and GNU compiler:
#
# module load compiler/gnu
# module load mpi/openmpi
# mpirun ./my_mpi_program
#
# for Intel MPI and Intel complier:
#
# module load compiler/intel
# module load mpi/impi
# mpirun ./my_mpi_program
#
# Option 2: Launch MPI tasks by using srun
#
# for OpenMPI and GNU compiler:
#
# module load compiler/gnu
# module load mpi/openmpi
# srun ./my_mpi_program
#
# for Intel MPI and Intel compiler:
#
module load compiler/intel
module load mpi/impi
srun ./my_mpi_program

</source>

Sample code for MPI program: [[Media:Hello_mpi.c | Hello_mpi.c]]

'''Notes'''

* SchedMD recommends to use srun and many (most?) sites do so as well. The rationale is that srun is more tightly integrated with the scheduler and provides more consistent and reliable resource tracking and accounting for individual jobs and job steps. mpirun may behave differently for different MPI implementations and versions. There are reports that claim "strange behavior" of mpirun especially when using task affinity and core binding. Using srun is supposed to resolve these issues and is therefore highly recommended.
* Do not run batch jobs that launch a large number (hundreds or thousands) short running (few minutes or less) MPI programs, e.g. from a shell loop. Every single MPI invocation does generate its own job step and sends remote procedure calls to the Slurm controller server. This can result in degradation of performance for both, Slurm and the application, especially if many of that jobs happen to run at the same time. Jobs of that kind can even get stuck without showing any further activity until hitting the wall time limit. For high throughput computing (e.g. processing a large number of files with every single task running independently from each other and very shortly), consider a more appropriate parallelization paradigm that invokes independent serial (non-MPI) processes in parallel at the same time. This approach is sometimes referred to as "[https://en.wikipedia.org/wiki/Embarrassingly_parallel pleasingly parallel]" workload. GNU Parallel is a shell tool that facilitates executing serial tasks in parallel. On JUSTUS 2 this tool is available as a software module "system/parallel".

== How to submit a hybrid MPI/OpenMP job? ==

Sample job script template for an hybrid job:

<source lang="bash">
#!/bin/bash
# Number of nodes to allocate
#SBATCH --nodes=4
# Number of MPI instances (ranks) to be executed per node
#SBATCH --ntasks-per-node=2
# Number of threads per MPI instance
#SBATCH --cpus-per-task=24
# Allocate 8 GB memory per node
#SBATCH --mem=8gb
# Maximum run time of job
#SBATCH --time=1:00:00
# Give job a reasonable name
#SBATCH --job-name=hybrid_job
# File name for standard output (%j will be replaced by job id)
#SBATCH --output=hybrid_job-%j.out
# File name for error output
#SBATCH --error=hybrid_job-%j.err

export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK}
export MKL_NUM_THREADS=${SLURM_CPUS_PER_TASK}

module load compiler/intel
module load mpi/impi
srun ./my_hybrid_program

# or:
# mpirun ./my_hybrid_program

</source>

Sample code for hybrid program: [[Media:Hello_hybrid.c | Hello_hybrid.c]]

'''Notes:'''

* $SLURM_CPUS_PER_TASK is only set if the '--cpus-per-task' option is specified.

== How to request specific node(s) at job submission? ==

Use [https://slurm.schedmd.com/sbatch.html#OPT_nodelist -w] (or [https://slurm.schedmd.com/sbatch.html#OPT_nodelist --nodelist]) option, e.g.:

<pre>$ sbatch -w <node1>,<node2> ...</pre>

Also see [https://slurm.schedmd.com/sbatch.html#OPT_nodefile -F] (or [https://slurm.schedmd.com/sbatch.html#OPT_nodefile --nodefile]) option.

== How to exclude specific nodes from job? ==

Use [https://slurm.schedmd.com/sbatch.html#OPT_exclude -x] (or [https://slurm.schedmd.com/sbatch.html#OPT_exclude --exclude]) option, e.g.:

<pre>$ sbatch -x <node1>,<node2> ...</pre>

== How to get exclusive jobs? ==

Use '--exclusive' option on job submission. This makes sure that there will be no other jobs running on your nodes. Very useful for benchmarking!

'''Note:'''

* --exclusive option does '''not''' mean that you automatically get full access to all the resources which the node might provide without explicitly requesting them.

== How to avoid sharing nodes with other users? ==

Use '--exclusive=user' option on job submission. This will still allow multiple jobs of one and the same user on the nodes.

''' Note:'''

* Depending on configuration, exclusive=user may (and probably will) be the default node access policy on JUSTUS 2.

== How to submit batch job without job script? ==

Use [https://slurm.schedmd.com/sbatch.html#OPT_wrap --wrap] option.

Example:

<pre>$ sbatch --nodes=2 --ntasks-per-node=16 --wrap "sleep 600"</pre>

'''Note:''' May be useful for testing purposes.

= JOB MONITORING AND CONTROL =

== How to prevent Slurm performance degradation? ==

Almost every invocation of a Slurm client command (e.g. squeue, sacct, sprio or sshare) sends a remote procedure call (RPC) to the Slurm control daemon and/or database.
If enough remote procedure calls come in at once, this can result in a degradation of performance of the Slurm services for all users, possibly resulting in a denial of service.

Therefore, '''do not run Slurm client commands that send remote procedure calls from loops in shell scripts or other programs''' (such as 'watch squeue'). Always ensure to limit calls to squeue, sstat, sacct etc. to the minimum necessary for the information you are trying to gather.

Slurm does collect RPC counts and timing statistics by message type and user for diagnostic purposes.

== How to view information about submitted jobs? ==

Use [https://slurm.schedmd.com/squeue.html squeue] command, e.g.:

<pre>
$ squeue # all jobs owned by user (all jobs owned by all users for admins)
$ squeue --me # all jobs owned by user (same as squeue for regular users)
$ squeue -u <username> # jobs of specific user
$ squeue -t PENDING # pending jobs only
$ squeue -t RUNNING # running jobs only
</pre>

'''Notes:'''

* The output format of [https://slurm.schedmd.com/squeue.html squeue] (and most other Slurm commands) is highly configurable to your needs. Look for the --format or --Format options.

* Every invocation of squeue sends a remote procedure call to the Slurm database server. '''Do not run squeue or other Slurm client commands from loops in shell scripts or other programs''' as this can result in a degradation of performance. Ensure that programs limit calls to squeue to the minimum necessary for the information you are trying to gather.

== How to cancel jobs? ==

Use [https://slurm.schedmd.com/scancel.html scancel] command, e.g.

<pre>
$ scancel <jobid> # cancel specific job
$ scancel <jobid>_<index> # cancel indexed job in a job array
$ scancel -u <username> # cancel all jobs of specific user
$ scancel -u <username> -i # cancel all jobs of specific user interactively
$ scancel -t PENDING # cancel pending jobs
$ scancel -t RUNNING # cancel running jobs
</pre>

== How to show job script of a running job? ==

Use [https://slurm.schedmd.com/scontrol.html scontrol] command:

<pre>
$ scontrol write batch_script <job_id> <file>
$ scontrol write batch_script <job_id> -
</pre>

* If file name is omitted default file name will be slurm-<job_id>.sh
* If file name is - (i.e. dash) job script will be written to stdout.

== How to get estimated start time of a job? ==

<pre>$ squeue --start</pre>

'''Notes:'''
* Estimated start times are dynamic and can change at any moment. Exact start times of individual jobs are usually unpredictable.
* Slurm will report N/A for the start time estimate if nodes are not currently being reserved by the scheduler for the job to run on.

== How to show remaining walltime of running jobs? ==

Use [https://slurm.schedmd.com/squeue.html squeue] with format option "%L", e.g.:

<pre> $ squeue -t r -o "%u %i %L" </pre>

== How to check priority of jobs? ==

Use [https://slurm.schedmd.com/squeue.html squeue] with format options "%Q" and/or "%p", e.g.:

<pre>
$ squeue -o "%8i %8u %15a %.10r %.10L %.5D %.10Q"
</pre>

Use [https://slurm.schedmd.com/sprio.html sprio] command to display the priority components (age/fairshare/...) for each job:

<pre>
$ sprio
</pre>

Use "[https://slurm.schedmd.com/sshare.html sshare] command for listing the shares of associations, e.g. accounts.

<pre>
$ sshare
</pre>

== How to prevent (hold) jobs from being scheduled for execution? ==

<pre>
$ scontrol hold <job_id>
</pre>

== How to unhold job? ==

<pre>
$ scontrol release <job_id>
</pre>

== How to suspend a running job? ==

<pre>
$ scontrol suspend <job_id>
</pre>

== How to resume a suspended job? ==

<pre>
$ scontrol resume <job_id>
</pre>

== How to requeue (cancel and resubmit) a particular job? ==

<pre>
$ scontrol requeue <job_id>
</pre>

== How to monitor resource usage of running job(s)? ==

Use "[https://slurm.schedmd.com/sstat.html sstat] command.

'sstat -e' command shows a list of fields that can be specified with the '--format' option.

Example:

<pre>
$ sstat --format=JobId,AveCPU,AveRSS,MaxRSS -j <jobid>
</pre>

This will show average CPU time, average and maximum memory consumption of all tasks in the running job.
Ideally, average CPU time equals the number of cores allocated for the job multiplied by the current run time of the job.
The maximum memory consumption gives an estimate of the peak amount of memory actually needed so far. This can be compared with the amount of memory requested for the job. Over-requesting memory can result in significant waste of compute resources.

'''Notes:'''

* Users can also ssh into compute nodes that they have one or more running jobs on. Once logged in, they can use standard Linux process monitoring tools like ps, (h)top, free, vmstat, iostat, du, ...

* Users can also attach an interactive shell under an already allocated job by running the following command: <pre>srun --jobid <job> --overlap --pty /bin/bash</pre> Once logged in, they can again use standard Linux process monitoring tools like ps, (h)top, free, vmstat, iostat, du, ... For a single node job the user does not even need to know the node that the job is running on. For a multinode job, the user can still use '-w <node>' option to specify a specific node.

== How to get detailed job information ==

<pre>
$ scontrol show job 1234 # For job id 1234
$ scontrol show jobs # For all jobs
$ scontrol -o show jobs # One line per job
</pre>

== How to modify a pending/running job? ==

Use

<pre>$ scontrol update JobId=<jobid> ...</pre>

E.g.: <pre>$ scontrol update JobId=42 TimeLimit=7-0</pre>

This will modify the time limit of the job to 7 days.

'''Note:''' Update requests for '''running''' jobs are mostly restricted to Slurm administrators. In particular, only an administrator can increase the TimeLimit of a job.

== How to show accounting data of completed job(s)? ==

Use [https://slurm.schedmd.com/sacct.html sacct] command.

'sacct -e' command shows a list of fields that can be
specified with the '--format' option.

== How to retrieve job history and accounting? ==

For a specific job:

<pre>
$ sacct -j <jobid> --format=User,JobID,Jobname,partition,state,time,start,end,elapsed,MaxRss,MaxVMSize,nnodes,ncpus,nodelist
</pre>

For a specific user:

<pre>
$ sacct -u <user> --format=User,JobID,Jobname,partition,state,time,start,end,elapsed,MaxRss,MaxVMSize,nnodes,ncpus,nodelist
</pre>

Note: Default time window is the current day.

Starting from a specific date:

<pre>
$ sacct -u <user> -S 2020-01-15 --format=User,JobID,Jobname,partition,state,time,start,end,elapsed,MaxRss,MaxVMSize,nnodes,ncpus,nodelist
</pre>

Within a time window:

<pre>
$ sacct -u <user> -S 2020-01-15 -E 2020-01-31 --format=User,JobID,Jobname,partition,state,time,start,end,elapsed,MaxRss,MaxVMSize,nnodes,ncpus,nodelist
</pre>

'''Note:'''

You can also set the environment variable $SACCT_FORMAT to specify the default format. To get a general idea of how efficiently a job utilized its resources, the following format can be used:

<pre>
export SACCT_FORMAT="JobID,JobName,Elapsed,NCPUs,TotalCPU,CPUTime,ReqMem,MaxRSS,MaxDiskRead,MaxDiskWrite,State,ExitCode"
</pre>

To find how efficiently the CPUs were used, divide TotalCPU by CPUTime. To find how efficiently memory were used, devide MaxRSS by ReqMem. But be aware that sacct memory usage measurement doesn't catch very rapid memory spikes. If your job got killed for running out of memory, it '''did run out of memory''' even if sacct reports a lower memory usage than would trigger an out-of-memory-kill. A job that reads or writes excessively to disk might be bogged down significantly by I/O operations.

== How to get efficiency information of completed job(s)? ==

Use <pre>$ seff <jobid> </pre> command for some brief information.

'''Note:''' It is good practice to have a look at the efficiency of your job(s) on completion '''and we expect you to do so'''. This way you can improve your job specifications in the future.

== How to get complete field values from sstat and sacct commands? ==

When using the [https://slurm.schedmd.com/sacct.html#OPT_format --format] option for listing various fields you can put a %NUMBER afterwards to specify how many characters should be printed.

E.g. '--format=User%30' will print 30 characters for the user name (right justified). A %-30 will print 30 characters left justified.

sstat and sacct also provide the '--parsable' and '--parsable2' option to always print full field values delimited with a pipe '|' character by default.
The delimiting character can be specified by using the '--delimiter' option, e.g. '--delimiter=","' for comma separated values.

== How to retrieve job records for all jobs running/pending at a certain point in time? ==

Use [https://slurm.schedmd.com/sacct.html sacct] with [https://slurm.schedmd.com/sacct.html#OPT_state -s <state>] and [https://slurm.schedmd.com/sacct.html#OPT_starttime -S <start time>] options, e.g.:

<pre>
$ sacct -n -a -X -S 2021-04-01T00:00:00 -s R -o JobID,User%15,Account%10,NCPUS,NNodes,NodeList%1500
</pre>

'''Note:''' When specifying the state "-s <state>" '''and''' the start time "-S <start time>", the default
time window will be set to end time "-E" equal to start time. Thus, you will get a snapshot of all running/pending
jobs at the instance given by "-S <start time>".

== How to get a parsable list of hostnames from $SLURM_JOB_NODELIST? ==

<pre>
$ scontrol show hostnames $SLURM_JOB_NODELIST
</pre>

= ADMINISTRATION =

'''Note:''' Most commands in this section are restricted to system administrators.

== How to stop Slurm from scheduling jobs? ==

You can stop Slurm from scheduling jobs on a per partition basis by
setting that partition's state to DOWN. Set its state UP to resume
scheduling. For example:

<pre>
$ scontrol update PartitionName=foo State=DOWN
$ scontrol update PartitionName=foo State=UP
</pre>

== How to print actual hardware configuration of a node? ==

<pre>
$ slurmd -C # print hardware configuration plus uptime
$ slurmd -G # print generic resource configuration
</pre>

== How to reboot (all) nodes as soon as they become idle? ==

<pre>
$ scontrol reboot ASAP nextstate=RESUME <node1>,<node2> # specific nodes
$ scontrol reboot ASAP nextstate=RESUME ALL # all nodes
</pre>

== How to cancel pending reboot of nodes? ==

<pre>
$ scontrol cancel_reboot <node1>,<node2>
</pre>

== How to check current node status? ==

<pre>
$ scontrol show node <node>
</pre>

== How to instruct all Slurm daemons to re-read the configuration file ==

<pre>
$ scontrol reconfigure
</pre>

== How to prevent a user from submitting new jobs? ==

Use the following [https://slurm.schedmd.com/sacctmgr.html sacctmgr] command:

<pre>
$ sacctmgr update user <username> set maxsubmitjobs=0
</pre>

'''Notes:'''

*Job submission is then rejected with the following message:
<pre>
$ sbatch job.slurm
sbatch: error: AssocMaxSubmitJobLimit
sbatch: error: Batch job submission failed: Job violates accounting/QOS policy (job submit limit, user's size and/or time limits)
</pre>

* Use the following command to release the limit:
<pre>
$ sacctmgr update user <username> set maxsubmitjobs=-1
</pre>

== How to drain node(s)? ==

<pre>
$ scontrol update NodeName=<node1>,<node2> State=DRAIN Reason="Some Reason"
</pre>

Notes:

* Reason is mandatory.

* Do '''not''' just set state DOWN to drain nodes. This will kill any active jobs that may run on that nodes.

== How to list reason for nodes being drained or down? ==

<pre>
$ sinfo -R
</pre>

== How to resume node state? ==

<pre>
$ scontrol update NodeName=<node1>,<node2> State=RESUME
</pre>

== How to create a reservation on nodes? ==

Suggested reading: https://slurm.schedmd.com/reservations.html

<pre>
$ scontrol create reservation user=root starttime=now duration=UNLIMITED flags=maint,ignore_jobs nodes=ALL
$ scontrol create reservation user=root starttime=2020-12-24T17:00 duration=12:00:00 flags=maint,ignore_jobs nodes=<node1>,<node2>
$ scontrol show reservation
</pre>

'''Note:''' Add "FLEX" flag to allow jobs that qualify for the reservation to start before the reservation begins (and continue after it starts).
Add "MAGNETIC" flag to attract jobs that qualify for the reservation to run in that reservation without having requested it at submit time.

== How to create a floating reservation on nodes? ==

Use the flag "TIME_FLOAT" and a start time that is relative to the current time (use the keyword "now").
In the example below, the nodes are prevented from starting any jobs exceeding a walltime of 2 days.

<pre>
$ scontrol create reservation user=root starttime=now+2days duration=UNLIMITED flags=maint,ignore_jobs,time_float nodes=<node1>,<node2>
</pre>

'''Note:''' Floating reservation are not intended to run jobs, but to prevent long running jobs from being initiated on specific nodes. Attempts by users to make use of a floating reservation will be rejected. When ready to perform the maintenance, place the nodes in DRAIN state and delete the reservation.

== How to use a reservation? ==

<pre>
$ sbatch --reservation=foo_6 ... script.slurm
</pre>

== How to delete a reservation? ==

<pre>
$ scontrol delete ReservationName=foo_6
</pre>

== How to get node oriented information similar to 'mdiag -n'? ==

<pre>
$ sinfo -N -l
</pre>

Fields can be individually customized. See [https://slurm.schedmd.com/sinfo.html sinfo] man page. For example:

<pre>
$ sinfo -N --format="%8N %12P %.4C %.8O %.6m %.6e %.8T %.20E"

NODELIST PARTITION CPUS CPU_LOAD MEMORY FREE_M STATE REASON
n0001 standard* 0/16 0.01 128000 120445 idle none
n0002 standard* 0/16 0.01 128000 120438 idle none
n0003 standard* 0/0/ N/A 128000 N/A down* Not responding
</pre>

== How to get node oriented information similar to 'pbsnodes'? ==

<pre>
$ scontrol show nodes # One paragraph per node (all nodes)
$ scontrol show nodes <node1>,<node2> # One paragraph per node (specified nodes)
$ scontrol -o show nodes # One line per node (all nodes)
$ scontrol -o show nodes <node1>,<node2> # One line per node (specified nodes)
</pre>

== How to update multiple jobs of a user with a single scontrol command? ==

Not possible. But you can e.g. use squeue to build the script taking
advantage of its filtering and formatting options.

<pre>
$ squeue -tpd -h -o "scontrol update jobid=%i priority=1000" >my.script
</pre>

You can also identify the list of jobs and add them to the JobID all at once, for example:

<pre>
$ scontrol update JobID=123 qos=reallylargeqos
$ scontrol update JobID=123,456,789 qos=reallylargeqos
$ scontrol update JobID=[123-400],[500-600] qos=reallylargeqos
</pre>

Another option is to use the JobName, if all the jobs have the same name.

<pre>
$ scontrol update JobName="foobar" UserID=johndoe qos=reallylargeqos
</pre>

However, Slurm does not allow the UserID filter alone.

== How to create a new account? ==

Add account at top level in association tree:

<pre>
$ sacctmgr add account <accountname> Cluster=justus Description="Account description" Organization="none"
</pre>

Add account as child of some parent account in association tree:

<pre>
$ sacctmgr add account <accountname> parent=<parent_accountname>
</pre>

== How to move account to another parent? ==

<pre>
$ sacctmgr modify account name=<accountname> set parent=<new_parent_accountname>
</pre>

== How to delete an account? ==

<pre>
$ sacctmgr delete account name=<accountname>
</pre>

== How to add a new user? ==

<pre>
$ sacctmgr add user <username> DefaultAccount=<accountname>
</pre>

== How to add/remove users from an account? ==

<pre>
$ sacctmgr add user <username> account=<accountname> # Add user to account
$ sacctmgr add user <username> account=<accountname2> # Add user to a second account
$ sacctmgr remove user <username> where account=<accountname> # Remove user from this account
</pre>

== How to change default account of a user? ==

<pre>
$ sacctmgr modify user where user=<username> set DefaultAccount=<default_account>
</pre>

'''Note:''' The user must already be associated with the account you want to set as default.

== How to show account information? ==

<pre>
$ sacctmgr show assoc
$ sacctmgr show assoc tree
</pre>

== How to implement user resource throttling policies? ==

Quoting from https://bugs.schedmd.com/show_bug.cgi?id=3600#c4

With Slurm, the associations are meant to establish base limits on the
defined partitions, accounts and users. Because limits propagate down
through the association tree, you only need to define limits at a high
level and those limits will be applied to all partitions, accounts and
users that are below it (parent to child). You can also override those
high level (parent) limits by explicitly setting different limits at
any lower level (on the child). So using the association tree is the
best way to get some base limits applied that you want for most cases.
QOS's are meant to override any of those base limits for exceptional
cases. Like Maui, you can use QOS's to set a different priority.
Again, the QOS would be overriding the base priority that could be set
in the associations.

== How to set a resource limit for an individual user? ==

Suggested reading: https://slurm.schedmd.com/resource_limits.html

Example:

<pre>
$ sacctmgr modify user <username> set maxjobs=1 # Limit maximum number of running jobs for user
$ sacctmgr list assoc user=<username> format=user,maxjobs # Show that limit
$ sacctmgr modify user <username> set maxjobs=-1 # Remove that limit
</pre>

== How to retrieve historical resource usage for a specific user or account? ==

Use [https://slurm.schedmd.com/sreport.html sreport] command.

Examples:
<pre>
$ sreport cluster UserUtilizationByAccount Start=2021-01-01 End=2021-12-31 -t Hours user=<username> # Report cluster utilization of given user broken down by accounts
$ sreport cluster AccountUtilizationByUser Start=2021-01-01 End=2021-12-31 -t Hours account=<account> # Report cluster utilization of given account broken down by users
</pre>

'''Notes:'''
* By default CPU resources will be reported. Use '-T' option for other trackable resources, e.g. '-T cpu,mem,gres/gpu,gres/scratch'.
* On JUSTUS 2 registered compute projects ("Rechenvorhaben") are uniquely mapped to Slurm accounts of the same name. Thus, 'AccountUtilizationByUser' can also be used to report the aggregated cluster utilization of compute projects.
* Can be executed by regular users as well in which case Slurm will only report their own usage records (but along with the total usage of the associated account in the case of 'AccountUtilizationByUser').

== How to fix/reset a user's RawUsage value? ==

<pre>
$ sacctmgr modify user <username> where Account=<account> set RawUsage=<number>
</pre>

== How to create/modify/delete QOSes? ==

Suggested reading: https://slurm.schedmd.com/qos.html

Examples:

<pre>
$ sacctmgr show qos # Show existing QOSes
$ sacctmgr add qos verylong # Create new QOS verylong
$ sacctmgr modify qos verylong set MaxWall=28-00:00:00 # Set maximum walltime limit
$ sacctmgr modify qos verylong set MaxTRESPerUser=cpu=4 # Set maximum maximum number of CPUS a user can allocate at a given time
$ sacctmgr modify qos verylong set flags=denyonlimit # Prevent submission if job requests exceed any limits of QOS
$ sacctmgr modify user <username> set qos+=verylong # Add a QOS to a user account
$ sacctmgr modify user <username> set qos-=verylong # Remove a QOS from a user account
$ sacctmgr delete qos verylong # Delete that QOS
</pre>

== How to find (and fix) runaway jobs? ==

<pre>$ sacctmgr show runaway</pre>

'''Notes:'''
* Runaway jobs are orphaned jobs that don't exist in the Slurm controller but have a start and no end time in the Slurm data base. Runaway jobs mess with accounting and affects new jobs of users who have too many runaway jobs.
* If there are jobs in this state this command will also provide an option to fix them. This will set the end time for each job to the latest out of the start, eligible, or submit times, and set the state to completed.

== How to show a history of database transactions? ==

<pre>$ sacctmgr list transactions</pre>

'''Note:''' Useful to get timestamps for when a user/account/qos has been created/modified/removed etc.

Development/VS Code

2026-07-27T17:05:26Z

H Schumacher: added kill command for VS Code Server

== Overview ==

[[File:vscode.png|thumb|Visual Studio Code, Source: https://code.visualstudio.com/|450px]]

[https://github.com/Microsoft/vscode Visual Studio Code] (VS Code) is an open source source-code editor from Microsoft. It has become one of the most popular IDEs according to a [https://survey.stackoverflow.co/2024/technology#1-integrated-development-environment stackoverflow survey]. The functionality of VS Code can easily be extended by installing extensions. These extensions allow for almost arbitrary '''language support''', '''debugging''' or '''remote development'''. You can install VS Code locally and use it for remote development.

== Visual Studio Code ==
Visual Studio Code (VS Code) is a lightweight, extensible code editor from Microsoft that supports many programming languages and features like debugging, and integrated Git. It offers a rich extension marketplace to add language support, themes, and tools tailored to your workflow. VS Code runs on Windows, macOS, and Linux and is popular for its speed, customizability, and strong community ecosystem.

=== Using AI agents ===
When deploying AI agents on the bwHPC clusters, users must exercise extreme caution and maintain full oversight of the agent's activities. You are fully responsible for all actions initiated by an agent, including any security breaches or system disruptions it may cause. It is mandatory to strictly monitor resource usage on login nodes, as these are shared resources intended only for lightweight tasks. Any agent found consuming excessive CPU or memory on a login node will be terminated immediately to ensure stability for other users. To comply with usage policies, all AI-driven workloads which generate heavy load must be submitted to the Slurm batch queues rather than running directly on the login nodes.

=== Extension: Remote-SSH ===

In order to remotely develop and debug code at HPC facilities, you can use the [https://code.visualstudio.com/docs/remote/ssh '''Remote - SSH''' extension]. The extension allows you to connect your locally installed VS Code with the remote servers. So in contrast to using graphical IDEs within a remote desktop session (RDP, VNC), there are no negative effects like e.g. laggy reactions to your input or blurred display of fonts.

==== Installation and Configuration ====

[[File:vscode-extensions-button.png|vscode-extensions-button.png|30px]] 
In order to install the Remote - SSH extension, just click on the Extensions (Erweiterungen) button in the left side bar and enter “remote ssh” in the search field. Choose '''Remote - SSH''' from the occurring list and click on '''Install'''.
 
[[File:vscode-remoteexplorer-button.png|vscode-remoteexplorer-button.png|30px]] 
In order to configure remote connections, open the Remote-Explorer extension. On Linux Systems, the file <code>~/.ssh/config</code> is automatically evaluated. The targets within this file already appear in the left side bar.
 
[[File:vscode-remoteexplorer-add.png|vscode-remoteexplorer-add.png|350px]] 
If there are no remote ssh targets defined within this file, you can easily add one by clicking on the + symbol. Make sure that “SSH Targets” is active in the drop down menu of the Remote-Explorer. Enter the connection details <code><user>@<server></code>. You will be asked, whether the file <code>~/.ssh/config</code> should be modified or if another config file should be used or created.

A minimal entry within <code>~/.ssh/config</code> in order to have a remote target to be listed there could look like this:

$ cat ~/.ssh/config
Host uc3.scc.kit.edu
HostName uc3.scc.kit.edu
User xy_ab1234

==== Connect to Login Nodes ====

[[File:vscode-remoteexplorer-button.png|vscode-remoteexplorer-button.png|30px]] 
In order to connect to a remote SSH target, open the Remote-Explorer. Right-click a target and connect in the current or a new window. TOTP and password can be entered in the corresponding input fields that open.

You are now logged in on the remote server. As usual, you can open a project directory with the standard key binding Ctrl+k Ctrl+o. You can now edit and debug code.

'''Attention''': Please remember that you are running and debugging the code on a login node. Do not perform resource-intensive tasks. Furthermore, no GPU resources are available to you.

Extensions, which are installed locally, are only usable on your local machine and are not automatically installed remotely. However, as soon as you open the Extensions-Explorer during a remote session, VS Code proposes to install the locally installed extensions remotely.

==== Disconnect from Login Nodes ====

[[File:vscode-remoteexplorer-indicator.png|images/vscode-remoteexplorer-indicator.png|200px]] 
If you want to end your remote session, click the green box in the lower left corner. In the input box that opens, select the “Close Remote Connection” option. If you simply close your VS Code window, some server-side components of VS Code will continue to run remotely.

If you encounter any issues with the remote connection or if you didn't end the sessions correctly, it can help to kill the VS Code Server on the host. This is done by going to the Command Palette (via the 'Manage' wheel in the lower left corner) and executing the following command:

<code> Remote-SSH: Kill VS Code Server on Host </code>

=== Access to Compute Nodes ===

The workflow described above does not allow debugging on compute nodes that have been requested via an interactive Slurm job, for example. Debugging GPU codes is therefore also not possible, since this kind of resource is only accessible within Slurm jobs.
We strongly discourage using the Code Tunnel application, as it violates our access policies. In this scenario, an application running on the compute node connects to a Microsoft or GitHub server. The locally running VS Code then connects to the compute nodes via these external servers, thereby bypassing the login nodes.



== Code-Server ==

The application [https://github.com/cdr/code-server code-server] allows to run the server part of VS Code on any machine, it can be accessed in the web browser running on your local computer. This enables, for example, development and debugging on compute nodes.
Code-server runs a web server which serves on an unprivileged port. In order to connect your web browser to the remotely running code server, you have to forward this port via a SSH tunnel.

[[File:code-server.png|thumb|code-server.png|VS Code in web browser: code-server, Source: https://github.com/cdr/code-server">https://github.com/cdr/code-server|400px]]

=== Install Code-Server ===

Code-server is pre-installed on bwUniCluster and accessible via an Lmod module:
<source lang="bash">module load devel/code-server</source>

On clusters with no code-server module, the application can easily be installed with the description available on the official [https://github.com/coder/code-server GitHub page].

=== Start Code-Server ===

Code-server can be run on either login nodes or compute nodes. In the example shown, an interactive job is started on a GPU partition to run code-server there.

<syntaxhighlight lang="console">$ salloc -p accelerated --gres=gpu:4 --time=30:00 # Start interactive job with 1 GPU
$ module load devel/code-server # Load code-server module</syntaxhighlight>
When code-server is started, it opens a web server listening on a certain port. The user has to '''specify the port'''. It can be chosen freely in the unprivileged range (above 1024). If a port is already assigned, e.g. because several users choose the same port, another port must be chosen.

By starting code-server, you are running a web server that can be accessed by anyone logged in to the cluster. To prevent other people from gaining access to your account and data, this web server is '''password protected'''. If no variable <code>PASSWORD</code> is defined, the password in the default config file <code>~/.config/code-server/config.yaml</code> is used. If you want to define your own password, you can either change it in the config file or export the variable <code>PASSWORD</code>.

<syntaxhighlight lang="console">$ PASSWORD=<mySecret> \
code-server \
--bind-addr 0.0.0.0:8081 \
--auth password # Start code-server on port 8081</syntaxhighlight>

{| style="background:#FFCCCC; width:100%;"
| '''Security implications'''
Please note that by starting <code>code-server</code> you are running a web server that can be accessed by everyone logged in on the cluster. 
* '''If password protection is disabled, anybody can access your account and your data.'''
* Choose a '''secure password'''!
* Do '''NOT''' use <code>code-server --link</code>!
|}

=== Connect to code-server ===
[[File:code-server-hk.png|thumb|Code-server running on GPU node.|400px]]

As soon as code-server is running, it can be accessed in the web browser. In order to establish the connection, a SSH tunnel from your local computer to the remote server has to be created via:

<syntaxhighlight lang="console">$ ssh -L 8081:<computeNodeID>:8081 <userID>@<hostname></syntaxhighlight>
You need to enter the <code>computeNodeID</code> of the node on which the interactive Slurm job is running. If you have started code server on a login node, just enter <code>localhost</code>. Now you can open http://127.0.0.1:8081 in your web browser. Possibly, you have to allow your browser to open an insecure (non-https) site. The login site looks as follows:

[[File:code-server-login.png|Code-server login page.|300px]]

Enter the password from <code>~/.config/code-server/config.yaml</code> or from the <code>PASSWORD</code> variable. After clicking the “Submit” button, the familiar VS Code interface will open in your browser.

=== End code-server session ===

If you want to temporarily log out from your code-server session you can open the “Application Menu” in the left side bar and click on “Log out”. To '''terminate''' the code-server session, you have to cancel it in the interactive Slurm job by pressing ++ctrl+c++.

== Connect to Remote Jupyter Kernel ==
To work with your python scripts and notebooks within VSCode while using the resources of a compute node, you can create a batch job that launches JupyterLab and connect to it via VS Code. To do so, please follow the instructions below. Any parts of the scripts that might need adjustments are marked with the keyword "@params".

=== Simple Use Case ===
The most basic steps are to set a password for JupyterLab, start a job which runs JupyterLab, get the connection details from the output log and connect to it locally. The following instructions explain these steps and provide an additional script that replaces the manual step of looking into the output file.

# Load a python module and set a password on the cluster for JupyterLab:
#: <syntaxhighlight lang="bash">
module load devel/miniforge
jupyter notebook --generate-config
jupyter notebook password
</syntaxhighlight>
# Define a batch script to start a JupyterLab Job. Please adjust the first part according to your needs and your specific cluster.
#: <pre>~/jupyterlab.slurm</pre>
#: <syntaxhighlight lang="bash">
#!/bin/bash

#SBATCH --partition=cpu-single
#SBATCH --job-name=jupyterlab
#SBATCH --time=00:10:00
#SBATCH --ntasks=1
#SBATCH --cpus-per-task 1
#SBATCH --mail-user=my_email_address #my_email_address # to use this generic version, add "alias my_email_address=<yourEmailAddress>" to the ~/.bashrc file
#SBATCH --mail-type=ALL

# @param: change this to your preferred python or conda module
module load devel/miniforge

# @param: cluster address for ssh connection
hostAddress=helix.bwservices.uni-heidelberg.de

PORT=$(( ( RANDOM % 9999 ) + 1024 ))
jupyter lab --no-browser --ip=0.0.0.0 --port=${PORT}
HOSTID=$(squeue -h -o "%A %N %j" | grep jupyterlab | awk '{print $2}')
echo "Connect"
echo "ssh -N -L ${PORT}:${HOSTID}:${PORT} ${USER}@$hostAddress"
echo "Job {$SLURM_JOB_ID} running on node {$SLURM_NODEID} on host {$HOSTID}."

returned_code=$?
echo "> Script completed with exit code ${returned_code}"
exit ${returned_code}
</syntaxhighlight>
# Run a wrapper script to execute the batch script and extract needed information from the slurm output file. You could save it together with other utility scripts in a "bin" directory in your home folder.
#: <pre>./bin/run_jupyterlab_simple.sh</pre>
#: <syntaxhighlight lang="bash">

#!/bin/bash

# Define parameters
jobscript=~/jupyterlab.slurm
hostAddress=helix.bwservices.uni-heidelberg.de

# Run job
job_id=$(sbatch $jobscript | awk '{print $4}')
echo "jobid: $job_id"

# Outfile name
slurm_out=slurm-${job_id}.out

# Wait for output file
while [ ! -f $slurm_out ]; do
sleep 2;
done

# Wait until url is written in output file
while [ -z ${url} ]; do
sleep 1;
url=$(grep -o 'http[^ ]*' $slurm_out | head -n 1);
done

# Extract hostID and port from output. The pattern assumes a node name with a length of 6 characters and a port with a length of 3, 4 or 5 numbers.
url_pattern="http://([a-z0-9]{6}):([0-9]{3,5})/lab"
if [[ $url =~ $url_pattern ]]; then
hostID=${BASH_REMATCH[1]}
port=${BASH_REMATCH[2]}
echo "To connect with the JupyterLab kernel, please enter the following into your local commandline: "
echo "ssh -N -L $port:$hostID:$port ${USER}@$hostAddress";
echo ""
echo "Note: It is normal that the ssh command doesn't end after providing the credentials. Ending the command would mean ending the local connection to the kernel."
echo ""
echo "Afterwards, you can use the URL"
echo " http://127.0.0.1:${port}/lab "
echo ""
echo "to:"
echo "- use the kernel in VSCode ('Existing Jupyter Server...', enter URL, enter password, confirm '127.0.0.1', choose kernel) or "
echo "- open JupyterLab in your browser with the URL"
else
echo "The needed information couldn't be found in the slurm output. Please contact your support unit if you need help with fixing this problem."
fi
# rm $slurm_out
</syntaxhighlight>
# Follow the instructions on the commandline to connect to the Jupyter kernel from your local machine or the Helix login node. More detailed instructions can be found below.

==== Connect to a running job ====

The job runs on a specific compute node and port. With this information, you can create a ssh connection to it. But first, you need to decide, in which way you want to work with your python code. The options are:

# The code is placed locally on your computer.
# The code is placed on the cluster and you've mounted the folder locally. (= The files on the cluster are accessible from within your local VS Code)
# The code is placed on the cluster and you work on the cluster via a remote connection in VS Code.

Depending on the use case, you need to execute the ssh command in a different place:

# Open VS Code on your computer.
# Open VS Code on your computer.
# Open VS Code on your computer and connect to the cluster.

Then open a terminal and execute the ssh command, which is given in the commandline output of the wrapper script. If the terminal isn't already open, go to menu item "Terminal" at the top of the window and choose "New Terminal" (or "new -> command prompt" on Windows).
It is normal that the command doesn't end after you've put in your credentials. Leave the terminal open and go on with the next step.

To use the jupyter kernel that is running on the cluster node, you need to connect this kernel. This is similar to connecting any other kernel:

# Open your code file.
# Click "Select Kernel" in the upper right corner.
# Choose "Existing Jupyter Server...".
# Enter the URL that was given by the wrapper script.
# Enter your JupyterLab password that you set in the first step of these instructions.
# Confirm the prefilled value "127.0.0.1" by pressing Enter.
# Choose one of the virtual environments that you've created on the cluster. You should see all python environments. To see the conda environments as well, you need to [[Helix/bwVisu/JupyterLab#Python_version | register them as ipykernel]] first.

=== Complex Use Case ===
If you have different use cases for juypterlab, you could use a more flexible wrapper script, for example:

<pre>./bin/run_jupyterlab.sh</pre>

<syntaxhighlight lang="bash">
#!/bin/bash
# Starts a jupyter kernel on a node and provides information on how to connect to it locally.
# If you have only one use case and therefore need only one combination of slurm settings for your jupyter jobs, then you can use the simpler script.
# This script supports explorative analyses by allowing to overwrite parameters via commandline.
# Different job configurations can be defined in advance and then used with a given short name (cpu, gpu,...).

programname=$0
function help {
'''help text'''
echo ""
echo "Starts a jupyterlab kernel"
echo ""
echo "usage example: $programname --param_set cpu"
echo ""
echo " --param_set string name of the parameter set"
echo " (examples: cpu, gpu)"
echo " --jobscript string optional, path of batch script"
echo " (default: ~/jupyterlab.slurm)"
echo " --slurm_out string optional, name of slurm output file"
echo " (default: slurm-${job_id}.out)"
}

# These parameters are set later in the script. Providing them via commandline, overwrites their values set in the script.
jobscript=None
slurm_out=None

# Process parameters
while [ $# -gt 0 ]; do
if [[ $1 == "--help" ]]; then
help
exit 0
# when given -p as parameter, use its value for the variable param_set
elif [[ $1 == "-p" ]]; then
param_set="$2"
shift
elif [[ $1 == "--"* ]]; then
v="${1/--/}"
declare "$v"="$2"
shift
fi
shift
done

function define_param_set(){
'''Define parameter sets for sbatch'''
# Define different sets
cpu=(--partition=cpu-single --mem=2gb)
gpu=(--partition=gpu-single --mem=3gb --gres=gpu:1)

param_set=${1}
param_set=$param_set[@]
param_set=("${!param_set}")

# Add params that are the same for all sets
param_set+=(--ntasks=1)
}

# @param: jobscript, name of the slurm batch script to execute
if [ "$jobscript" = "None" ]; then
jobscript=~/jupyterlab.slurm
fi

# @param: cluster address for ssh connection
hostAddress=helix.bwservices.uni-heidelberg.de

# Translate given param_set value to actual set of parameters
define_param_set $param_set
echo "param_set: ${param_set[*]}"

# Run job
job_id=$(sbatch ${param_set[@]} $jobscript | awk '{print $4}')
echo "jobid: $job_id"

# @param: slurm_out, the filename for the slurm output file
if [ "$slurm_out" = "None" ]; then
slurm_out=slurm-${job_id}.out
fi

# Wait for output file
while [ ! -f $slurm_out ]; do
sleep 1;
done

# Wait until url is written in output file
while [ -z ${url} ]; do
sleep 1;
url=$(grep -o 'http[^ ]*' $slurm_out | head -n 1);
done

# Extract hostID and port from output.
url_pattern="http://([a-z0-9]{6}):([0-9]{3,5})/lab"
if [[ $url =~ $url_pattern ]]; then
hostID=${BASH_REMATCH[1]}
port=${BASH_REMATCH[2]}
echo "To connect with the JupyterLab kernel, please enter the following into your local commandline: "
echo "ssh -N -L $port:$hostID:$port ${USER}@$hostAddress";
fi

echo "Afterwards, you can either"
echo "- use the kernel in VSCode or "
echo "- open JupyterLab with this URL: "
echo " http://127.0.0.1:${port}/lab "
echo "Note: It is normal that the ssh command doesn't end after providing the credentials. Ending the command would mean ending the local connection to the kernel."
#rm $slurm_out
</syntaxhighlight>

SDS@hd/SV Management

2026-07-24T12:52:53Z

H Schumacher: added hint regarding ORCiD users

== Roles in a SV ==
There are four different roles in an SV. Depending on the role, different management activites can be executed at the [https://sds-hd.urz.uni-heidelberg.de/management SDS@hd Managementtool]. These are described below. They include top level management of user access.

=== SV Member or Guest ===
At the [https://sds-hd.urz.uni-heidelberg.de/management SDS@hd Managementtool] members/guests can...
* ...view the status of your SV memberships (active/inactive)
* ...view the status of the SV (active/inactive, end date). (Removing people from the list completely is not possible, yet.)

=== SV Manager ===
Additionally to the abilities of a coworker, a manager can...
* ...change the SV password
* ...enable others to join the SV
*# Provide them with the SV acronym. You can look it up at the [https://sds-hd.urz.uni-heidelberg.de/management/shib/info_sv.php SDS@hd Managementtool].
*# Provide them with the SV password. The SV responsible received the initial password via email. Caution: Make sure to share the SV password. Do not share your personal service password which you set in registration step B at bwServices.
*# Afterwards, they can join by following the [[SDS@hd/Registration | registration steps]].
* ...change the status of SV members (active/inactive). Make sure to especially manage the access of those members that joined with their ORCiD account. Otherwise, they'll have access forever.

=== SV Responsible (SVV) ===
Additionally to the abilities of a manager, the responsible can...
* ...enable the guest folder
* ...change the role of SV members (guest/full member)
* ...hand over the SV responsibility
* ...cancel the SV when it is not needed anymore

== Yearly storage project (SV) extension ==

Once a year the SV responsible person needs to apply for a lifetime extension of the storage project. As part of the application, you will be asked to inform us of publications for which the storage project was used. As long as SDS@hd is used appropriately, an extension will be granted.

Data Transfer/Rclone

2026-07-20T16:21:13Z

H Schumacher: Added Checksumming

[https://rclone.org/docs/ Rclone] is a command line tool to manage files on remote systems (e.g. high performance clusters, data and cloud storage systems, archiving services). 
Rclone either synchronizes in one direction only or its mounting functionality is used with <code>rclone mount</code>. 
Data can be piped between two completely remote locations. When moving data within the same system and the data transfer protocol allows for server side copy, no local download is necessary. 
One advantage is that the transfer is multithreaded and it operates on a file level basis.
'''Caution:''' When using Rclone with 2FA it is necessary to connect via ssh key instead of a password.

== Installation ==

Rclone is a Go program and comes as a single binary file.

# Download the relevant binary.
# Extract the <code>rclone</code> executable (<code>rclone.exe</code>).
# You can use the executables without further installation. For easy use, it is recommended to add the binary to your PATH environment variable. Information on how to do this can be found below.

Detailed information regarding different operating systems can be found here:

* Installation on [https://rclone.org/install/#windows Windows]
*: To use rclone after the installation, you have to open a terminal (cmd or PowerShell) in the folder where the rclone.exe file is. This can be done with a right click in the empty space wihin the rclone folder and then choosing "open in terminal". Then run all commands with a leading './' (for example <code>./rclone config</code>. To be able to simply use "rclone" anywhere, you can add it to your path. For instructions see the [[Data_Transfer/Rclone#Troubleshooting | Troubleshooting]] section.
* Installation on [https://rclone.org/install/#macos macOS]
** If Rclone shall be used together with sftp, the [[Data_Transfer/SSHFS#Installation | sshfs installation]] instructions must be followed after installing Rclone.
* Installation on [https://rclone.org/install/#script-installation Linux]

== Usage Rclone ==

To use Rclone you have to define a config file. Afterwards you can connect by using the name of your configured connections.

=== Configure Remote ===

Before you can start using Rclone, you need to set up a remote. This means to configure a specific connection by providing authentication information, the network protocol that you want to use and a name for this configuration so that you can use it later on.

To configure a remote for a specific service, you need the following information:

* <code><remotehost></code>
* <code><username></code>
* <code><servicePassword></code>

Furthermore, you have to decide on:

* <code>network protocol</code> (for example webDAV, smb, sftp)
* <code>remote-name</code> (for example you can use the name of the service you want to connect to)

You have three different options to set up a new remote as described in the following sections. It's enough to choose one of those.

'''Oneliner''' 

Open a terminal and define all parameters in one command. If a ssh key shall be used instead of a password, it might be easier to adjust the config file directly as described in the next section.
<syntaxhighlight lang="bash"># smb
rclone config create <remote-name> smb host=<remotehost> user=<username> domain=<domain> pass=<password> --obscure
# sftp
rclone config create <remote-name> sftp host=<remotehost> user=<username> pass=<password> --obscure
# webdav
rclone config create <remote-name> webdav url=<remotehost> user=<username> pass=<password> --obscure
</syntaxhighlight>

'''Adjust Config File''' 
<syntaxhighlight lang="bash">
# Make sure that a config file exists. Access rights for the config file are set to 600.
rclone config touch
# Get the location of the file:
rclone config file
</syntaxhighlight>
Open the file and use one of the following snippets as template for your connection:
<syntaxhighlight lang="bash">[<remote-name>]
type = smb
host = <hostname>
user = <userID>
domain = <e.g. BWSERVICESAD>

[<remote-name>]
type = webdav
url = <hostURL>
vendor = other
user = <userID>

[<remote-name>]
type = sftp
host = <hostname>
user = <userID>
key_use_agent = false

[<remote-name-ssh-key-version>]
type = sftp
host = <hostname>
user = <userID>
key_file = ~/.ssh/id_ed25519
pubkey_file = ~/.ssh/id_ed25519.pub
key_use_agent = true
shell_type = none
</syntaxhighlight>
To add the password, please use the following command. Make sure to keep the prepended space so that the command is not saved in your command history.
<syntaxhighlight> rclone config update <remote-name> pass=<password> --obscure</syntaxhighlight>

'''Interactive Setup''' 

Execute:
<syntaxhighlight>rclone config</syntaxhighlight>
This will guide you through an interactive setup process. It's quite helpful for checking out which options there are and what the config file looks like after setting values that deviate from the default values. You can find detailed instructions at the website:

* [https://rclone.org/webdav/ Connect via webdav]
* [https://rclone.org/smb/ Connect via smb]
* [https://rclone.org/sftp/ Connect via sftp]

=== Use Remote ===

To see all configured remotes:
<syntaxhighlight lang="bash">rclone config
# Exit with 'q'.
</syntaxhighlight>

The syntax to use Rclone is like this:

<pre>rclone [options] subcommand <parameters> <parameters...>
</pre>
List all elements in the folder XX:
<syntaxhighlight lang="bash">rclone lsf <remote-name>:XX
# List elements from subfolders as well:
rclone lsf --max-depth 2 <remote-name>:XX
</syntaxhighlight>
Copies /local/path to the remote path

<pre>rclone copy </local/path> <remote-name>:<remote/path>
</pre>
Copies fom remote path to /local/path

<pre>rclone copy <remote-name>:<remote/path> </local/path>
</pre>
Moves the contents of the source directory to the destination directory.

<pre>rclone move <remote-name>:<source/path> <remote-name>:<destination/path>
</pre>
More subcommands can be found [https://rclone.org/docs/#subcommands here].

== Usage Rclone Mount ==

Before you can follow the instructions in this chapter, you need to have set up a [[Data_Transfer/Rclone#Usage_Rclone | remote]].
More detailed information on how to use rclone mount can be found [https://rclone.org/commands/rclone_mount/ here].

=== Windows ===

To run rclone mount on Windows, you will need to [https://winfsp.dev/rel/ download and install WinFsp] first.

<syntaxhighlight lang="python"># mount under drive letter X (or any other free letter)
rclone mount --vfs-cache-mode full <remote-name>:<path/to/remote/files> X:
# or provide the path to a nonexisting folder:
rclone mount --vfs-cache-mode full <remote-name>:<path/to/remote/files> <C:\path\parentDir\nonexistingFoldername></syntaxhighlight>
To unmount, the command can be stopped in the terminal with the key combination CTRL+C. Alternatively, a mounted drive can be unmounted by making a right click on the drive name in the file explorer and choose "Eject". 
In contrast to Linux/Mac, there is no background mode.

=== MacOS & Linux ===

You can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the <code>--daemon</code> flag to force background mode. If this doesn't work, you can put an <code>&</code> at the end of the command instead.

Create an empty directory on your local machine and then execute

<syntaxhighlight lang="bash"># to mount the root folder:
rclone mount --vfs-cache-mode full <remote-name>: /path/to/empty/folder
# to mount a subfolder:
rclone mount --vfs-cache-mode full <remote-name>:folderX/folderY /path/to/empty/folder
# to unmount:
fusermount -uz /path/to/mounted/folder </syntaxhighlight>

== Best Practices ==

Rclone has a lot of useful options.

=== Checksumming ===
Data transfers can break when there is an interruption in the network or an interruption on the side of the remote destination. When doing the transfer on your local computer, make sure to prevent sleep mode while the transfer is ongoing.
While you can make rclone produce log output, you might still overlook that there were some transfer issues in between and at the destination you might see the correct folders but might overlook that they are actually empty. To prevent these cases, the source data can be compared with the destination data as follows:

# A sum file needs to be generated that contains the hashes for the source data:
#: <syntaxhighlight lang="bash">rclone hashsum SHA1 <path/to/source/data> -L --output-file <sumfile_name>
</syntaxhighlight>
# After the transfer, the sum file gets compared to the destination data:
#: <syntaxhighlight lang="bash"># --combined flag: It will write a file (or stdout) which contains all file paths with a symbol and then a space and then the path to tell you what happened to it.
# --one-way flag: the command only checks that files in the source match the files in the destination. Additional files in the destination that are not in the source will not be detected.
# --error <errorfile_name> flag: Report all files with errors (hashing or reading) to this file
rclone checksum SHA1 <sumfile_name> <remote-name>:<path/to/destination/data> --stats-log-level=DEBUG -vv --combined --one-way --error <errorfile_name></syntaxhighlight>

See the Rclone documentation for details on the comparison and output options: [https://rclone.org/commands/rclone_hashsum/ rclone hashsum], [https://rclone.org/commands/rclone_checksum/ rclone checksum]

=== Performance ===

To be able to utilize a larger bandwidth, it is helpful to add the following options for increased performance:

<pre>
--transfers <int>
</pre>

Number of file transfers to run in parallel (default: 4). Depending on the local Network, read and write speeds on the file system, and current load, different values might be best. For large transfers, it is advised to test local performance with different values beforehand.

* In our tests, we observed the best results between 8 and 32.
* For regular use cases, we recommend 16 as the default.
* Values above 64 are not recommended and degrade performance.

<pre>
--multi-thread-streams <int>
</pre>

Number of streams to use for multithreaded downloads (default: 4). Only important on very large files. This will cause multithreaded up/download on chunk-sized bits of the file.

The optimal value is highly specific to the local network and used Hardware. For regular use cases, we recommend 4 as the default.

'''Hint:''' Keep in mind that a broken file transfer has to start from the beginning. If there is no overall performance improvement when transferring files in parallel because the network is not capable enough, it is for example better to transfer four files in serial and therefore each with full speed, instead of transferring the four files in parallel with 1/4 of the speed each. If an interruption occurs in the middle, you have two files left to transfer in the first case but four files left in the second case.

=== Debugging and Statistics ===
To get updates on current progress, use:
<pre>
--stats
</pre>
Interval between printing stats, e.g. 500ms, 60s, 5m (0 to disable) (default 1m0s).

To get debug information, use:
<pre>
--log-level=DEBUG
--stats-log-level=DEBUG
</pre>

== Troubleshooting ==
# Windows: Adding rclone to the path
#: Needed information: path to the rclone.exe file. If you chose to install via 'winget', the path is "C:\Users\<user>\AppData\Local\Microsoft\WinGet\Packages\Rclone.Rclone_Microsoft.Winget.Source.... . Please look up the exact path.
#:* Option 1: Add the rclone.exe file to a folder that is already in the path. You can move it to "C:\Windows\System32\". Then open a new terminal window and test if the command "rclone config" works.
#:* Option 2: Add the path of the rclone.exe file to your Windows Path variable:
#:*: Open the Start Search and type env. Choose "Edit environment variables"
#:*: Click the "Environment Variables" button.
#:*: Edit the user variables and add the path to your rclone.exe file.

Helix/Slurm

2026-07-20T15:47:26Z

H Schumacher: fixed formatting

= General information about Slurm =
The bwForCluster Helix uses Slurm as batch system.
* Slurm documentation: https://slurm.schedmd.com/documentation.html
* Slurm cheat sheet: https://slurm.schedmd.com/pdfs/summary.pdf
* Slurm tutorials: https://slurm.schedmd.com/tutorials.html

= Slurm Command Overview =

{| width=750px class="wikitable"
! Slurm commands !! Brief explanation
|-
| [https://slurm.schedmd.com/sbatch.html sbatch] || Submits a job and queues it in an input queue
|-
| [https://slurm.schedmd.com/salloc.html salloc] || Request resources for an interactive job
|-
| [https://slurm.schedmd.com/squeue.html squeue] || Displays information about active, eligible, blocked, and/or recently completed jobs
|-
| [https://slurm.schedmd.com/scontrol.html scontrol] || Displays detailed job state information
|-
| [https://slurm.schedmd.com/scontrol.html sstat] || Displays status information about a running job
|-
| [https://slurm.schedmd.com/scancel.html scancel] || Cancels a job
|-
|}

= Job Submission =

Batch jobs are submitted with the command:

<syntaxhighlight lang="bash">sbatch <job-script> </syntaxhighlight>

A job script contains options for Slurm in lines beginning with <code>#SBATCH</code> as well as your commands which you want to execute on the compute nodes. For example:

<syntaxhighlight lang="slurm">#!/bin/bash
#SBATCH --partition=cpu-single
#SBATCH --ntasks=1
#SBATCH --time=00:20:00
#SBATCH --mem=1gb
#SBATCH --export=NONE
echo 'Hello world'
</syntaxhighlight>

This jobs requests one core (--ntasks=1) and 1 GB memory (--mem=1gb) for 20 minutes (--time=00:20:00) on nodes provided by the partition ''cpu-single''.

For the sake of a better reproducibility of jobs it is recommended to use the option --export=NONE to prevent the propagation of environment variables from the submit session into the job environment and to load required software modules in the job script.

== Partitions ==

On bwForCluster Helix it is necessary to request a partition with <code>--partition=<partition_name></code> on job submission. Within a partition, job allocations are routed automatically to the most suitable compute node(s) for the requested resources (e.g. amount of nodes and cores, memory, number of GPUs). The ''devel'' partition is the default partition, if no partition is requested.

The partitions ''devel'', ''cpu-single'' and ''gpu-single'' are operated in shared mode, i.e. jobs from different users can run on the same node. Jobs can get exclusive access to compute nodes in these partitions with the <code>--exclusive</code> option. The partitions ''cpu-multi'' and ''gpu-multi'' are operated in exclusive mode. Jobs in these partitions automatically get exclusive access to the requested compute nodes.

{| class="wikitable"
|-
! style="width:20%"| Partition
! style="width:20%"| Node Access Policy
! style="width:20%"| [https://wiki.bwhpc.de/e/Helix/Hardware#Compute_Nodes Node Types]
! style="width:20%"| Default
! style="width:20%"| Limits
|-
| devel
| shared
| cpu, gpu4
| ntasks=1, time=00:10:00, mem-per-cpu=2gb
| nodes=2, time=00:30:00
|-
| cpu-single
| shared
| cpu, fat
| ntasks=1, time=00:30:00, mem-per-cpu=2gb
| nodes=1, time=120:00:00
|-
| gpu-single
| shared
| gpu4, gpu8
| ntasks=1, time=00:30:00, mem-per-cpu=2gb
| nodes=1, time=120:00:00
|-
| cpu-multi
| job exclusive
| cpu
| nodes=2, time=00:30:00
| nodes=32, time=48:00:00
|-
| gpu-multi
| job exclusive
| gpu4
| nodes=2, time=00:30:00
| nodes=8, time=48:00:00
|}

== GPU requests ==

For the partitions ''gpu-single'' and ''gpu-multi'' is it required to request GPU resources.
* The number of GPUs per node is requested with the option <code>--gres=gpu:<number-of-gpus></code>.
* It is recommended to request a suitable GPU type for your application with the option <code>--gres=gpu:<gpu-type>:<number-of-gpus></code>.
** For <gpu-type> put the 'GPU Type' listed in the [https://wiki.bwhpc.de/e/Helix/Hardware#Compute_Nodes Compute Nodes table].
*** Example for a request of two A40 GPUs: <code>--gres=gpu:A40:2</code>
*** Example for a request of one A100 GPU: <code>--gres=gpu:A100:1</code>
** If you are unsure on which GPU type your code runs faster, please run a test case and compare the run times. In general the following applies:
*** A40 GPUs are optimized for single precision computations.
*** A100 and H200 GPUs offer better performance for double precision computations or if the code makes use of tensor cores.
** To only get A100 or H200 for double precision computations, a matching constraint can be added to the job parameters by using <code>--constraint=fp64</code>. This way, only GPU types with FP64 capability (double precision) are allowed.
* GPUs that are suitable for a specific GPU memory requirement can be requested with option <code>--gres=gpu:<number-of-gpus>,gpumem_per_gpu:<required-gpumem>GB</code>.
*: Hint: This only restricts the selection of possible GPU types. For the job the total GPU memory per GPU is available as listed in the line 'GPU memory per GPU' of the [https://wiki.bwhpc.de/e/Helix/Hardware#Compute_Nodes Compute Nodes table].

== Examples ==

Here you can find some example scripts for batch jobs.

=== Serial Programs ===

<syntaxhighlight lang="slurm">
#!/bin/bash
#SBATCH --partition=cpu-single
#SBATCH --ntasks=1
#SBATCH --time=20:00:00
#SBATCH --mem=4gb
./my_serial_program
</syntaxhighlight>

'''Notes:'''
* Jobs with "--mem" up to 236gb can run on all node types associated with the cpu-single partition.

=== Multi-threaded Programs ===

<syntaxhighlight lang="slurm">
#!/bin/bash
#SBATCH --partition=cpu-single
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=1
#SBATCH --cpus-per-task=16
#SBATCH --time=01:30:00
#SBATCH --mem=50gb
export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK}
./my_multithreaded_program
</syntaxhighlight>

'''Notes:'''
* Jobs with "--ntasks-per-node" up to 64 and "--mem" up to 236gb can run on all node types associated with the cpu-single partition.
* With <code>export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK}</code> you can set the number of threads according to the number of resources requested.

=== MPI Programs ===

<syntaxhighlight lang="slurm">
#!/bin/bash
#SBATCH --partition=cpu-multi
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=64
#SBATCH --time=12:00:00
module load compiler/gnu
module load mpi/openmpi
srun ./my_mpi_program
</syntaxhighlight>

'''Notes:'''
* "--mem" requests the memory per node. The maximum is 236gb.
* The Compiler and MPI modules used for the compilation must be loaded before the start of the program.
* It is recommended to start MPI programs with 'srun'.

=== GPU Programs ===

<syntaxhighlight lang="slurm">
#!/bin/bash
#SBATCH --partition=gpu-single
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=8
#SBATCH --gres=gpu:A40:1
#SBATCH --time=12:00:00
#SBATCH --mem=16gb

module load devel/cuda
export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK}
./my_cuda_program
</syntaxhighlight>

'''Notes:'''
* The CUDA module used for compilation must be loaded before the start of the program.

=== More Examples ===

Further batch script examples are available on bwForCluster Helix in the directory: <code>/opt/bwhpc/common/system/slurm-examples</code>

= Interactive Jobs =

'''Hint:''' For convenient access to specific GUI applications (JupyterLab, RStudio, ...) on the cluster, we provide a web-based platform: 
→ '''[[Helix/bwVisu | bwVisu]]'''

Interactive jobs must NOT run on the login nodes, however resources for interactive jobs can be requested using srun. The following example requests an interactive session on 1 core for 2 hours:

<syntaxhighlight lang="bash">salloc --partition=cpu-single --ntasks=1 --time=2:00:00 </syntaxhighlight>

After execution of this command wait until the queueing system has granted you the requested resources. Once granted you will be automatically logged on the allocated compute node.

If you use applications or tools which provide a GUI, enable X-forwarding for your interactive session with:

<syntaxhighlight lang="bash">salloc --partition=cpu-single --ntasks=1 --time=2:00:00 --x11 </syntaxhighlight>

Once the walltime limit has been reached you will be automatically logged out from the compute node.

'''Delay the start of a job''' by using [https://slurm.schedmd.com/sbatch.html#OPT_begin -b] (or [https://slurm.schedmd.com/sbatch.html#OPT_begin --begin]) option in order to defer the allocation of the job until the specified time. Examples:
<syntaxhighlight lang="bash">salloc --begin=20:00 ... # job can start after 8 p.m.
salloc --begin=now+1hour ... # job can start 1 hour after submission
salloc --begin=teatime ... # job can start at teatime (4 p.m.)
salloc --begin=2023-12-24T20:00:00 ... # job can start after specified date/time
</syntaxhighlight>

= Job Monitoring =

Jobs can be monitored via the job monitoring portal or via the commandline.

== Job Monitoring Portal ==
For detailed information about your jobs and their efficiency (requested resources vs. used resources) visit the job monitoring portal:

→ https://helix-monitoring.bwservices.uni-heidelberg.de

== Commandline Commands ==
Depending on the job state and type you can use different commands to get information on the job.

=== Information about Submitted Jobs ===

For an overview of your submitted jobs use the command:

<syntaxhighlight lang="bash">squeue
# Show the estimated start time, additionally:
squeue --start</syntaxhighlight>

To get detailed information about a specific job use the command:

<syntaxhighlight lang="bash">scontrol show job <jobid></syntaxhighlight>

'''Notes:''' 
A job start may be delayed for various reasons:
* <code>QOSMaxCpuPerUserLimit</code> - There is a limit to how many CPU cores a user can use at the same time. The job exceeds this limit.
* <code>QOSMaxGRESPerUser</code> - There is a limit to how many GPUs a user can use at the same time. The job exceeds this limit.
* <code>QOSMinGRES</code> - The job was submitted to a gpu partition without requesting a GPU.
* <code>Priority</code> - There are currently other jobs with a higher priority but afterwards your job will run.
* <code>launch failed requeued held</code> - The job has failed to start. You may be able to resume it using scontrol. Alternatively you can cancel it and submit it again.
For further reasons please refer to: https://slurm.schedmd.com/job_reason_codes.html

=== Information about resource usage of running jobs ===

You can monitor the resource usage of running jobs with the sstat command. For example:

<pre>
sstat --format=JobId,AveCPU,AveRSS,MaxRSS -j <jobid>
</pre>

This will show average CPU time, average and maximum memory consumption of all tasks in the running job.

'sstat -e' command shows a list of fields that can be specified with the '--format' option.

=== Interactive access to running jobs ===

It is also possible to attach an interactive shell to a running job with command:

<syntaxhighlight lang="bash">srun --jobid=<jobid> --overlap --pty /bin/bash</syntaxhighlight>

Commands like 'top' show you the most busy processes on the node. To exit 'top' type 'q'.

To monitor your GPU processes use the command 'nvidia-smi'.

=== Job Feedback ===
You get feedback on resource usage and job efficiency for completed jobs with the command:

<syntaxhighlight lang="bash">
seff <jobid>
</syntaxhighlight>

Example Output:

<syntaxhighlight lang="bash">
============================= JOB FEEDBACK =============================
Job ID: 12345678
Cluster: helix
User/Group: hd_ab123/hd_hd
State: COMPLETED (exit code 0)
Nodes: 2
Cores per node: 64
CPU Utilized: 3-04:11:46
CPU Efficiency: 97.90% of 3-05:49:52 core-walltime
Job Wall-clock time: 00:36:29
Memory Utilized: 432.74 GB (estimated maximum)
Memory Efficiency: 85.96% of 503.42 GB (251.71 GB/node)
</syntaxhighlight>

Explanation:
* Nodes: Number of allocated nodes for the job.
* Cores per node: Number of physical cores per node allocated for the job.
* CPU Utilized: Sum of utilized core time.
* CPU Efficiency: 'CPU Utilized' with respect to core-walltime (= 'Nodes' x 'Cores per node' x 'Job Wall-clock time') in percent.
* Job Wall-clock time: runtime of the job.
* Memory Utilized: Sum of memory used. For multi node MPI jobs the sum is only correct when srun is used instead of mpirun.
* Memory Efficiency: 'Memory Utilized' with respect to total allocated memory for the job.

= Accounting =

Jobs are billed for allocated CPU cores, memory and GPUs.

To see the accounting data of a specific job:

<syntaxhighlight lang="bash">sacct -j <jobid> --format=user,jobid,account,nnodes,ncpus,time,elapsed,AllocTRES%50</syntaxhighlight>

To retrieve the job history for a specific user for a certain time frame:

<syntaxhighlight lang="bash">sacct -u <user> -S 2022-08-20 -E 2022-08-30 --format=user,jobid,account,nnodes,ncpus,time,elapsed,AllocTRES%50</syntaxhighlight>

= Overview about free resources =

On the login nodes the following command shows what resources are available for immediate use:

<syntaxhighlight lang="bash">sinfo_t_idle</syntaxhighlight>

Helix/Slurm

2026-07-20T15:45:53Z

H Schumacher: moved gpu text from example to gpu section, included constraint section into gpu section, placed bwvisu and the monitoring portal in the beginning of he corresponding section; reformatting, removed dollar signs at the start of commands; add explantion for delay because of 'Priority'

= General information about Slurm =
The bwForCluster Helix uses Slurm as batch system.
* Slurm documentation: https://slurm.schedmd.com/documentation.html
* Slurm cheat sheet: https://slurm.schedmd.com/pdfs/summary.pdf
* Slurm tutorials: https://slurm.schedmd.com/tutorials.html

= Slurm Command Overview =

{| width=750px class="wikitable"
! Slurm commands !! Brief explanation
|-
| [https://slurm.schedmd.com/sbatch.html sbatch] || Submits a job and queues it in an input queue
|-
| [https://slurm.schedmd.com/salloc.html salloc] || Request resources for an interactive job
|-
| [https://slurm.schedmd.com/squeue.html squeue] || Displays information about active, eligible, blocked, and/or recently completed jobs
|-
| [https://slurm.schedmd.com/scontrol.html scontrol] || Displays detailed job state information
|-
| [https://slurm.schedmd.com/scontrol.html sstat] || Displays status information about a running job
|-
| [https://slurm.schedmd.com/scancel.html scancel] || Cancels a job
|-
|}

= Job Submission =

Batch jobs are submitted with the command:

<syntaxhighlight lang="bash">sbatch <job-script> </syntaxhighlight>

A job script contains options for Slurm in lines beginning with <code>#SBATCH</code> as well as your commands which you want to execute on the compute nodes. For example:

<syntaxhighlight lang="slurm">#!/bin/bash
#SBATCH --partition=cpu-single
#SBATCH --ntasks=1
#SBATCH --time=00:20:00
#SBATCH --mem=1gb
#SBATCH --export=NONE
echo 'Hello world'
</syntaxhighlight>

This jobs requests one core (--ntasks=1) and 1 GB memory (--mem=1gb) for 20 minutes (--time=00:20:00) on nodes provided by the partition ''cpu-single''.

For the sake of a better reproducibility of jobs it is recommended to use the option --export=NONE to prevent the propagation of environment variables from the submit session into the job environment and to load required software modules in the job script.

== Partitions ==

On bwForCluster Helix it is necessary to request a partition with <code>--partition=<partition_name></code> on job submission. Within a partition, job allocations are routed automatically to the most suitable compute node(s) for the requested resources (e.g. amount of nodes and cores, memory, number of GPUs). The ''devel'' partition is the default partition, if no partition is requested.

The partitions ''devel'', ''cpu-single'' and ''gpu-single'' are operated in shared mode, i.e. jobs from different users can run on the same node. Jobs can get exclusive access to compute nodes in these partitions with the <code>--exclusive</code> option. The partitions ''cpu-multi'' and ''gpu-multi'' are operated in exclusive mode. Jobs in these partitions automatically get exclusive access to the requested compute nodes.

{| class="wikitable"
|-
! style="width:20%"| Partition
! style="width:20%"| Node Access Policy
! style="width:20%"| [https://wiki.bwhpc.de/e/Helix/Hardware#Compute_Nodes Node Types]
! style="width:20%"| Default
! style="width:20%"| Limits
|-
| devel
| shared
| cpu, gpu4
| ntasks=1, time=00:10:00, mem-per-cpu=2gb
| nodes=2, time=00:30:00
|-
| cpu-single
| shared
| cpu, fat
| ntasks=1, time=00:30:00, mem-per-cpu=2gb
| nodes=1, time=120:00:00
|-
| gpu-single
| shared
| gpu4, gpu8
| ntasks=1, time=00:30:00, mem-per-cpu=2gb
| nodes=1, time=120:00:00
|-
| cpu-multi
| job exclusive
| cpu
| nodes=2, time=00:30:00
| nodes=32, time=48:00:00
|-
| gpu-multi
| job exclusive
| gpu4
| nodes=2, time=00:30:00
| nodes=8, time=48:00:00
|}

== GPU requests ==

For the partitions ''gpu-single'' and ''gpu-multi'' is it required to request GPU resources.
* The number of GPUs per node is requested with the option <code>--gres=gpu:<number-of-gpus></code>.
* It is recommended to request a suitable GPU type for your application with the option <code>--gres=gpu:<gpu-type>:<number-of-gpus></code>.
** For <gpu-type> put the 'GPU Type' listed in the [https://wiki.bwhpc.de/e/Helix/Hardware#Compute_Nodes Compute Nodes table].
*** Example for a request of two A40 GPUs: <code>--gres=gpu:A40:2</code>
*** Example for a request of one A100 GPU: <code>--gres=gpu:A100:1</code>
** If you are unsure on which GPU type your code runs faster, please run a test case and compare the run times. In general the following applies:
*** A40 GPUs are optimized for single precision computations.
*** A100 and H200 GPUs offer better performance for double precision computations or if the code makes use of tensor cores.
** To only get A100 or H200 for double precision computations, a matching constraint can be added to the job parameters by using <code>--constraint=fp64</code>. This way, only GPU types with FP64 capability (double precision) are allowed.
* GPUs that are suitable for a specific GPU memory requirement can be requested with option <code>--gres=gpu:<number-of-gpus>,gpumem_per_gpu:<required-gpumem>GB</code>.
*: Hint: This only restricts the selection of possible GPU types. For the job the total GPU memory per GPU is available as listed in the line 'GPU memory per GPU' of the [https://wiki.bwhpc.de/e/Helix/Hardware#Compute_Nodes Compute Nodes table].

== Examples ==

Here you can find some example scripts for batch jobs.

=== Serial Programs ===

<syntaxhighlight lang="slurm">
#!/bin/bash
#SBATCH --partition=cpu-single
#SBATCH --ntasks=1
#SBATCH --time=20:00:00
#SBATCH --mem=4gb
./my_serial_program
</syntaxhighlight>

'''Notes:'''
* Jobs with "--mem" up to 236gb can run on all node types associated with the cpu-single partition.

=== Multi-threaded Programs ===

<syntaxhighlight lang="slurm">
#!/bin/bash
#SBATCH --partition=cpu-single
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=1
#SBATCH --cpus-per-task=16
#SBATCH --time=01:30:00
#SBATCH --mem=50gb
export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK}
./my_multithreaded_program
</syntaxhighlight>

'''Notes:'''
* Jobs with "--ntasks-per-node" up to 64 and "--mem" up to 236gb can run on all node types associated with the cpu-single partition.
* With <code>export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK}</code> you can set the number of threads according to the number of resources requested.

=== MPI Programs ===

<syntaxhighlight lang="slurm">
#!/bin/bash
#SBATCH --partition=cpu-multi
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=64
#SBATCH --time=12:00:00
module load compiler/gnu
module load mpi/openmpi
srun ./my_mpi_program
</syntaxhighlight>

'''Notes:'''
* "--mem" requests the memory per node. The maximum is 236gb.
* The Compiler and MPI modules used for the compilation must be loaded before the start of the program.
* It is recommended to start MPI programs with 'srun'.

=== GPU Programs ===

<syntaxhighlight lang="slurm">
#!/bin/bash
#SBATCH --partition=gpu-single
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=8
#SBATCH --gres=gpu:A40:1
#SBATCH --time=12:00:00
#SBATCH --mem=16gb

module load devel/cuda
export OMP_NUM_THREADS=${SLURM_CPUS_PER_TASK}
./my_cuda_program
</syntaxhighlight>

'''Notes:'''
* The CUDA module used for compilation must be loaded before the start of the program.

=== More Examples ===

Further batch script examples are available on bwForCluster Helix in the directory: <code>/opt/bwhpc/common/system/slurm-examples</code>

= Interactive Jobs =

'''Hint:''' For convenient access to specific GUI applications (JupyterLab, RStudio, ...) on the cluster, we provide a web-based platform: 
→ '''[[Helix/bwVisu | bwVisu]]'''

Interactive jobs must NOT run on the login nodes, however resources for interactive jobs can be requested using srun. The following example requests an interactive session on 1 core for 2 hours:

<syntaxhighlight lang="bash">salloc --partition=cpu-single --ntasks=1 --time=2:00:00 </syntaxhighlight>

After execution of this command wait until the queueing system has granted you the requested resources. Once granted you will be automatically logged on the allocated compute node.

If you use applications or tools which provide a GUI, enable X-forwarding for your interactive session with:

<syntaxhighlight lang="bash">salloc --partition=cpu-single --ntasks=1 --time=2:00:00 --x11 </syntaxhighlight>

Once the walltime limit has been reached you will be automatically logged out from the compute node.

'''Delay the start of a job''' by using [https://slurm.schedmd.com/sbatch.html#OPT_begin -b] (or [https://slurm.schedmd.com/sbatch.html#OPT_begin --begin]) option in order to defer the allocation of the job until the specified time. Examples:
<syntaxhighlight lang="bash">salloc --begin=20:00 ... # job can start after 8 p.m.
salloc --begin=now+1hour ... # job can start 1 hour after submission
salloc --begin=teatime ... # job can start at teatime (4 p.m.)
salloc --begin=2023-12-24T20:00:00 ... # job can start after specified date/time
</syntaxhighlight>

= Job Monitoring =

Jobs can be monitored via the job monitoring portal or via the commandline.

== Job Monitoring Portal ==
For detailed information about your jobs and their efficiency (requested resources vs. used resources) visit the job monitoring portal:

→ https://helix-monitoring.bwservices.uni-heidelberg.de

== Commandline Commands ==
Depending on the job state and type you can use different commands to get information on the job.

=== Information about Submitted Jobs ===

For an overview of your submitted jobs use the command:

<syntaxhighlight lang="bash">squeue
# Show the estimated start time, additionally:
squeue --start</syntaxhighlight>

To get detailed information about a specific job use the command:

<syntaxhighlight lang="bash">scontrol show job <jobid></syntaxhighlight>

'''Notes:''' 
A job start may be delayed for various reasons:
* <code>QOSMaxCpuPerUserLimit</code> - There is a limit to how many CPU cores a user can use at the same time. The job exceeds this limit.
* <code>QOSMaxGRESPerUser</code> - There is a limit to how many GPUs a user can use at the same time. The job exceeds this limit.
* <code>QOSMinGRES</code> - The job was submitted to a gpu partition without requesting a GPU.
* <code>Priority</code> - There are currently other jobs with a higher priority but afterwards your job will run.
* <code>launch failed requeued held</code> - The job has failed to start. You may be able to resume it using scontrol. Alternatively you can cancel it and submit it again.
For further reasons please refer to: https://slurm.schedmd.com/job_reason_codes.html

== Information about resource usage of running jobs ==

You can monitor the resource usage of running jobs with the sstat command. For example:

<pre>
sstat --format=JobId,AveCPU,AveRSS,MaxRSS -j <jobid>
</pre>

This will show average CPU time, average and maximum memory consumption of all tasks in the running job.

'sstat -e' command shows a list of fields that can be specified with the '--format' option.

== Interactive access to running jobs ==

It is also possible to attach an interactive shell to a running job with command:

<syntaxhighlight lang="bash">srun --jobid=<jobid> --overlap --pty /bin/bash</syntaxhighlight>

Commands like 'top' show you the most busy processes on the node. To exit 'top' type 'q'.

To monitor your GPU processes use the command 'nvidia-smi'.

== Job Feedback ==
You get feedback on resource usage and job efficiency for completed jobs with the command:

<syntaxhighlight lang="bash">
seff <jobid>
</syntaxhighlight>

Example Output:

<syntaxhighlight lang="bash">
============================= JOB FEEDBACK =============================
Job ID: 12345678
Cluster: helix
User/Group: hd_ab123/hd_hd
State: COMPLETED (exit code 0)
Nodes: 2
Cores per node: 64
CPU Utilized: 3-04:11:46
CPU Efficiency: 97.90% of 3-05:49:52 core-walltime
Job Wall-clock time: 00:36:29
Memory Utilized: 432.74 GB (estimated maximum)
Memory Efficiency: 85.96% of 503.42 GB (251.71 GB/node)
</syntaxhighlight>

Explanation:
* Nodes: Number of allocated nodes for the job.
* Cores per node: Number of physical cores per node allocated for the job.
* CPU Utilized: Sum of utilized core time.
* CPU Efficiency: 'CPU Utilized' with respect to core-walltime (= 'Nodes' x 'Cores per node' x 'Job Wall-clock time') in percent.
* Job Wall-clock time: runtime of the job.
* Memory Utilized: Sum of memory used. For multi node MPI jobs the sum is only correct when srun is used instead of mpirun.
* Memory Efficiency: 'Memory Utilized' with respect to total allocated memory for the job.

= Accounting =

Jobs are billed for allocated CPU cores, memory and GPUs.

To see the accounting data of a specific job:

<syntaxhighlight lang="bash">sacct -j <jobid> --format=user,jobid,account,nnodes,ncpus,time,elapsed,AllocTRES%50</syntaxhighlight>

To retrieve the job history for a specific user for a certain time frame:

<syntaxhighlight lang="bash">sacct -u <user> -S 2022-08-20 -E 2022-08-30 --format=user,jobid,account,nnodes,ncpus,time,elapsed,AllocTRES%50</syntaxhighlight>

= Overview about free resources =

On the login nodes the following command shows what resources are available for immediate use:

<syntaxhighlight lang="bash">sinfo_t_idle</syntaxhighlight>

Data Transfer

2026-07-20T14:46:23Z

H Schumacher: Added hint for checksumming, added rclone ssh key option for windows, changed formatting

== Overview ==

Data transfer is the exchange of files between two systems. Before data transfer can happen, you need to go through the following steps:

# Choose the two [[#Data_Storage_Systems|data storage systems]] that shall exchange data.
# Choose the top level ways of transfer ([[#Ways of Transfer:_Copy,_Sync,_Mount|copy, sync or mount]]) by considering your specific use case.
# Choose a [[#Network_Protocols_&_Transfer_Tools|network protocol or transfer tool]] to use for the communication between the systems.

The recommended setup already includes these three steps. For a full overview, you can reference the tables that show all transfer routes. Those include all possible combinations between systems, top level way of transfer and network protocol / transfer tool.

→ [[Data_Transfer/All_Data_Transfer_Routes|All Data Transfer Routes]]

=== Data Storage Systems ===

Data transfer can happen between a variety of systems. For example:

* [[File:Notebook.svg|x20px]] Local computer or VM (virtual machine)
* [[File:Microscope.svg|x20px]] Data producing machine (sequencer, microscope, ...)
* [[File:Clusternodes.svg|x20px]] HPC system (bwHPC Cluster, ...)
* [[File:Storage_small.svg|x15px]] Storage space (SDS@hd, institute server, ...)
* [[File:Cloud.svg|x15px]] Cloud resource (Nextcloud, ...)

=== Ways of Transfer: Copy, Sync, Mount ===

The top level ways of transfer are:

* '''Copy:''' A simple copy command is the most basic way to transfer data. This is most efficient for very big data files that shall be retrieved from or moved to a remote location. And it can be most convenient, if you prefer moving your files via commandline instead of using a file browser. Examples: [[Data_Transfer/SCP|scp]], [[Data_Transfer/SFTP|sftp]], [[Data_Transfer/Rclone|rclone]]
* '''Sync:''' If the data is intended to be kept on both systems and undergoes change on only one of the systems, it makes sense to use a synchronization command instead. This way, only the changed files in one location are updated in the other location. Good use cases are backups or data transfers that go mostly in one direction like moving data from a sequencer to a storage space. A disadvantage is that the data needs storage space on both systems. Examples: [[Data_Transfer/Rsync|rsync]], [[Data_Transfer/Rclone|rclone]]
* '''Mount:''' If the data undergoes change on both systems or is too big to store locally, then mounting is the most convenient solution. This allows you to see and work with the data as if it were stored locally on your computer while it is still placed on the remote system. All changes that you implement happen directly on the original data so that you don't need to copy or synchronize anything. Additionally, you'll see all changes that another party does to the data with just a very short delay. Disadvantages are that you need defined edit sessions starting with a mount and ending with a clean unmount of your files and with a stable network connection during the session. Also, file operations on the remote system become much slower via a remotely sshfs-mounted system. Examples: [[Data_Transfer/SSHFS|sshfs]], [[SDS@hd/Access/SMB|smb]], [[Data_Transfer/WebDAV|webdav]], [[SDS@hd/Access/NFS|nfs]], [[Data_Transfer/Rclone|rclone]]
[[File:CopySyncMount.png|x250px]]
Figure 1: Top level transfer routes



=== Network Protocols & Transfer Tools ===

{| class="wikitable" style="vertical-align:middle;"
|- style="font-weight:bold;"
! Basic Network Protocol
! Used By Network Protocol
|-
| ssh
| [[Data_Transfer/SCP | scp]], [[Data_Transfer/SFTP | sftp]], [[Data_Transfer/Rsync | rsync]]
|-
| http(s)
| [[Data_Transfer/WebDAV | WebDAV]]
|-
| [[SDS@hd/Access/SMB | smb]]
| -
|-
| [[SDS@hd/Access/NFS | NFS]]
| -
|}
For every data transfer a network protocol to use for the communication between the systems must be chosen. The basic network protocols and the network protocols that build directly upon those are shown in the table on the right. These protocols can either be used rather directly or through tools that provide the protocol together with additional features. A tool can either mean a command line tool or a tool with a graphical user interface.

A comprehensive overview of all transfer options (network protocols and tools) can be found on the page [[Data_Transfer/All_Data_Transfer_Routes|all data transfer routes]].

== Recommended Setup ==
[[File:Bwhpc diagram simplenobox.jpg|thumb|Main routes for mounting|x150px]]
# When you are working with a <ins>development environment</ins> that allows remote connections (e.g. [[Development/VS_Code | VS Code]]), this is the first choice.
# Otherwise, the main tools/protocols for transferring data are as follows:
#* Windows:
#** '''[[Data_Transfer/Graphical_Clients#MobaXterm|MobaXterm]]''' is a graphical user interface that allows logging in to the cluster with ssh as well as transferring data via a file browser or using command line tools for the transfer.
#** '''[[Data_Transfer/Rclone|Rclone]]''' can be used to mount the data as a drive in your file explorer so that you can access the files programmatically as well. An [[Registration/SSH | ssh key]] is needed when used with 2FA.
#* MacOS and Linux:
#** '''[[Data_Transfer/SSHFS|sshfs]]''' is quickly set up for mounting under stable connections.
#** '''[[Data_Transfer/Rclone|Rclone]]''' for mount, copy and sync. An [[Registration/SSH | ssh key]] is needed when used with 2FA.
#* SDS@hd: See the [[SDS@hd/Access|SDS@hd Access]] page.

== Best Practices ==

Here, you can find best practices in the case of...
* '''...strong firewall restrictions:'''
*: → Use ssh or http(s) based protocols, for example [[Data_Transfer/WebDAV|'''WebDav''']] and [[Data_Transfer/SFTP|sftp]]. For very strict facilities, ssh based protocols might not be allowed.
* '''...when sharing data with collaborators...'''
** ...outside of Baden-Württemberg
**: → Use the [[SDS@hd|SDS@hd]] storage.
** ...that are less comfortable with the command line
**: → Let them mount the folder.
* '''...transferring many small files:''' → Compress the files to one.
* '''...ensuring correct data transfers:'''
*: → Use checksumming. For example with [[Data_Transfer/Rclone | Rclone]].

For advanced topics see [[Data_Transfer/Advanced_Data_Transfer|Advanced Data Transfer]].

Registration/SSH

2026-07-20T14:34:51Z

H Schumacher: corrected validity value for Helix

= SSH Key Authentication for HPC Clusters =

'''SSH Keys''' allow you to log into a system without entering a password. Instead of proving your identity with something you know (a password), you prove it with something you have (a cryptographic key).

{| class="wikitable" style="text-align:center;"
|+ SSH Key Management Methods by Cluster
|-
! Cluster
! Management Method
! Details
|-
| bwUniCluster 3.0
| style="background-color:#90EE90;" | bwIDM Portal
| Centralized key management, 180-day validity (720-day for FIDO2 SK keys)
|-
| bwForCluster BinAC 2
| style="background-color:#FFE4B5;" | ~/.ssh/authorized_keys
| Self-managed, use ssh-copy-id
|-
| bwForCluster Helix
| style="background-color:#90EE90;" | bwServices Portal
| Centralized key management, 90-day validity
|-
| bwForCluster JUSTUS 2
| style="background-color:#FFE4B5;" | ~/.ssh/authorized_keys
| Self-managed, use ssh-copy-id
|-
| bwForCluster NEMO 2
| style="background-color:#90EE90;" | bwIDM Portal
| Centralized key management, 180-day validity (720-day for FIDO2 SK keys)
|}

'''Choose your cluster below:'''
* [[#SSH_Keys_on_BinAC_2_and_JUSTUS_2|BinAC 2 and JUSTUS 2]] - Self-managed keys
* [[#SSH_Keys_via_bwIDM.2FbwServices|bwUniCluster 3.0, Helix, and NEMO2]] - Centralized management

= SSH Keys on BinAC 2 and JUSTUS 2 =

On '''bwForCluster BinAC 2''' and '''bwForCluster JUSTUS 2''', you manage SSH keys yourself using the standard <code>~/.ssh/authorized_keys</code> file.

== Quick Setup with ssh-copy-id ==

The easiest method to add your SSH key:

'''Step 1: Generate an SSH key''' (if you don't have one):
<pre>
ssh-keygen -t ed25519 -C "your_email@example.com"
</pre>

Press Enter to accept the default location, then set a strong passphrase.

'''Step 2: Copy your key to the cluster:'''
<pre>
# For BinAC2:
ssh-copy-id username@login.binac2.uni-tuebingen.de

# For JUSTUS2:
ssh-copy-id username@justus2.uni-ulm.de
</pre>

Enter your service password and OTP when prompted. Your public key will be automatically added to <code>~/.ssh/authorized_keys</code>.

'''Step 3: Test your connection:'''
<pre>
# For BinAC2:
ssh username@login.binac2.uni-tuebingen.de

# For JUSTUS2:
ssh username@justus2.uni-ulm.de
</pre>

You should now be able to log in using your SSH key and OTP.

== Manual Setup (Alternative) ==

If <code>ssh-copy-id</code> is not available on your system:

'''Step 1: Display your public key:'''
<pre>
cat ~/.ssh/id_ed25519.pub
</pre>

Copy the entire output.

'''Step 2: Log into the cluster''' using your service password and OTP

'''Step 3: Add the key to authorized_keys:'''
<pre>
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "paste-your-public-key-here" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
</pre>

Replace <code>paste-your-public-key-here</code> with your actual public key.

= SSH Keys via bwIDM/bwServices =

On '''bwUniCluster 3.0''', '''bwForCluster Helix''', and '''bwForCluster NEMO 2''', SSH keys are managed centrally through the registration service.

== Why Centralized Management? ==

Centralized SSH key management provides:

* Security enforcement: Keys must use strong algorithms; regular keys have 180-day validity, FIDO2 SK keys have 720-day validity
* Centralized control: Review and revoke all keys from one location
* Two key types: Interactive keys (manual logins) and Command keys (automated workflows)

'''Note:''' Self-managed <code>~/.ssh/authorized_keys</code> files are ignored on these clusters.

== Supported Key Types ==

=== Standard SSH Keys ===

* ED25519: 256 bits (recommended)
* RSA: 2048 bits or more
* ECDSA: 521 bits

'''Important:''' Always protect your private keys with a strong passphrase.

=== FIDO2 Hardware Keys ===

'''ED25519-SK''' and '''ECDSA-SK''' keys use hardware security keys (like Yubikey or Feitian ePass FIDO A4B) for authentication:

* Valid for '''720 days''' - no frequent re-registration needed
* No pre-login required - no need to first unlock with password and TOTP
* Hardware-protected - private key never leaves the device
* Physical presence required - must touch key to authenticate

{| class="wikitable" style="text-align:center;"
|+ FIDO2 Key Support by Cluster
|-
! Cluster
! SK Support (ED25519-SK / ECDSA-SK)
|-
| bwUniCluster 3.0
| style="background-color:#90EE90;" | ✓ Supported
|-
| bwForCluster Helix
| style="background-color:#FFB6C1;" | ✗ Not supported
|-
| bwForCluster NEMO 2
| style="background-color:#90EE90;" | ✓ Supported
|}

'''Get started:''' See [[Registration/SSH/SSH-FIDO2-Quick-Start|SSH with FIDO2 - Quick Start Guide]]

== Step 1: Add Your SSH Key to the Portal ==

<div style="border: 3px solid #ffc107; background-color: #fff3cd; margin: 10px 0px 10px 0px;">
'''Important:'''
* Regular SSH keys are valid for '''180 days''' and automatically revoked after expiration. FIDO2 hardware keys (SK) are valid for '''720 days'''.
* Upload only your '''public key''' file (ending in <code>.pub</code>, e.g., <code>~/.ssh/id_ed25519.pub</code>).
</div>

'''1. Generate an SSH key''' (if you don't have one):
* Run in your local terminal: <pre> ssh-keygen -t ed25519 -C "your_email@example.com"
</pre>
* Press Enter to accept the default location, then set a strong passphrase.
* You now have a private key (~/.ssh/id_ed25519) and a public key (~/.ssh/id_ed25519.pub).

'''2. Navigate to SSH key management:'''
* [https://login.bwidm.de/user/ssh-keys.xhtml bwUniCluster 3.0 / NEMO 2] (bwIDM)
* [https://bwservices.uni-heidelberg.de/user/ssh-keys.xhtml bwForCluster Helix] (bwServices)

[[File:BwIDM-twofa.png|center|600px|thumb|My SSH Pubkeys page]]

'''3. Click "Add SSH Key" / "SSH Key Hochladen"'''

[[File:Bwunicluster 2.0 access ssh keys empty.png|center|400px|thumb|Add SSH Key button]]

'''4. Enter key details:'''
* '''Name:''' Descriptive identifier (e.g., "laptop-work", "desktop-home")
* '''SSH Key:''' Paste complete contents of your <code>.pub</code> file
* Click '''Add''' / '''Hinzufügen'''

[[File:Ssh-key.png|center|400px|thumb|Add SSH key dialog]]

'''5. Your key appears in the list:'''

[[File:Ssh-success.png|center|600px|thumb|SSH key successfully added]]

'''6. Bind your key to a cluster''' as either an [[#Step_2A:_Register_Interactive_Key|Interactive Key]] or [[#Step_2B:_Register_Command_Key|Command Key]].

== Step 2A: Register Interactive Key ==

'''Interactive Keys''' are for manual SSH logins.

=== Understanding Key Validity ===

'''Regular SSH Keys''' (RSA, ECDSA, ED25519):
* Require 2-factor authentication unlock
* Valid for limited hours after entering OTP + service password
* Must re-authenticate when validity expires

{| class="wikitable" style="text-align:center;"
|+ Validity Periods for Regular SSH Keys
|-
! Cluster
! Valid Duration
|-
| bwUniCluster 3.0
| 8 hours
|-
| bwForCluster Helix
| 12 hours
|-
| bwForCluster NEMO 2
| 12 hours
|}

'''FIDO2 Hardware Keys''' (ED25519-SK, ECDSA-SK):
* Valid for '''720 days''' - no re-authentication needed
* No pre-login required - no password/TOTP unlock needed
* Authentication via physical key touch only
* Only on bwUniCluster 3.0 and NEMO 2 (not Helix)
* See [[Registration/SSH/SSH-FIDO2-Quick-Start|SSH with FIDO2 - Quick Start Guide]]

=== Registration Steps ===

'''1. Add your public key''' following [[#Step_1:_Add_Your_SSH_Key_to_the_Portal|Step 1]] above

'''2. Navigate to "Registered Services" / "Registrierte Dienste"'''

Click '''Set SSH Key''' / '''SSH Key setzen''' for your cluster

[[File:BwIDM-registered.png|center|600px|thumb|Select cluster]]

'''3. Find your key and click "Add" / "Hinzufügen"'''

[[File:Ssh-service-int.png|center|800px|thumb|Add SSH key to service]]

'''4. Select "Interactive" and confirm'''

* Usage type: '''Interactive'''
* Comment: Optional description
* Click '''Add''' / '''Hinzufügen'''

[[File:Ssh-int.png|center|600px|thumb|Set as Interactive key]]

'''5. Done!''' Your key is active for interactive logins

[[File:Ssh-service.png|center|800px|thumb|SSH key registered]]

== Step 2B: Register Command Key ==

'''Command Keys''' enable automated workflows (e.g., backups, data transfers) without manual login.

=== Security Requirements ===

<div style="border: 3px solid #dc3545; padding: 15px; background-color: #f8d7da; margin: 10px 0;">
Command keys are '''always valid''' (no 2FA required), making them security-sensitive.

'''Mandatory restrictions:'''
* Single command: Specify exact command with full path
* IP restriction: Limit to specific IP address(es) or subnet
* Admin approval: Keys require review before activation
</div>

'''Common use case:''' [[Registration/SSH/rrsync|rrsync for data transfers]]

=== Registration Steps ===

'''1. Add your public key''' following [[#Step_1:_Add_Your_SSH_Key_to_the_Portal|Step 1]] above

'''2. Navigate to "Registered Services"'''

Click '''Set SSH Key''' for your cluster

[[File:BwIDM-registered.png|center|600px|thumb|Select cluster]]

'''3. Find your key and click "Add" / "Hinzufügen"'''

[[File:Ssh-service-com.png|center|800px|thumb|Add SSH key to service]]

'''4. Configure command restrictions:'''

* '''Usage type:''' Select '''Command'''
* '''Command:''' Full path with parameters (see example below)
* '''From:''' IP address or CIDR notation (e.g., <code>192.168.1.0/24</code>)
* '''Comment:''' Explain purpose (speeds up approval)
* Click '''Add''' / '''Hinzufügen'''

{| class="wikitable"
! Example: rrsync for data transfer
|-
| <pre>/usr/local/bin/rrsync -ro /home/aa/aa_bb/aa_abc1/</pre>
'''Note:''' Verify exact path on your cluster (may be <code>/usr/bin/rrsync</code>)
|}

[[File:Ssh-com.png|center|600px|thumb|Configure command key]]

'''5. Wait for approval'''

[[File:Ssh-service.png|center|800px|thumb|Key pending approval]]

== Revoking SSH Keys ==

Revoke keys that are no longer needed or potentially compromised.

<div style="border: 3px solid #6c757d; padding: 15px; background-color: #e2e3e5; margin: 10px 0;">
'''Note:''' Revoked keys are immediately disabled and cannot be reused.
</div>

'''1. Navigate to SSH key management:'''
* [https://login.bwidm.de/user/ssh-keys.xhtml bwUniCluster 3.0 / NEMO 2] (bwIDM)
* [https://bwservices.uni-heidelberg.de/user/ssh-keys.xhtml bwForCluster Helix] (bwServices)

[[File:BwIDM-twofa.png|center|600px|thumb|My SSH Pubkeys page]]

'''2. Click "REVOKE" / "ZURÜCKZIEHEN"''' next to the key you want to disable

'''2.''' Click '''REVOKE''' / '''ZURÜCKZIEHEN''' next to the key you want to disable

[[File:Ssh-success.png|center|800px|thumb|Revoke SSH key]]

SDS@hd/Security

2026-07-20T13:41:06Z

H Schumacher: Added hints and explanations

__FORCETOC__
== Snapshots ==

Snapshots are used to create a point-in-time copy of a file system or file sets.

<ins>Motivation</ins>: Snapshots can be used to quickly restore files or folders that were unintentionally deleted. Snapshots also provide a form of file versioning and the ability to revert to a previous version of a file, depending on the time interval between snapshots. The shorter ago a change was made and/or the longer it was kept the likelier it is that it can still be found in one of the snapshots.

When looking into the <code>.snapshots</code> folder within your SV you can see how often the snapshots are taken and how long they are preserved. For example:
<syntaxhighlight lang="bash">
ls .snapshots
> @GMT-2026.08.10-19.07.13 @GMT-2026.09.09-14.15.00 @GMT-2026.09.14-20.15.00 @GMT-2026.09.16-16.15.00 @GMT-2026.09.19-08.15.00
@GMT-2026.08.11-01.07.13 @GMT-2026.09.09-22.15.00 @GMT-2026.09.14-20.45.00 @GMT-2026.09.16-16.45.00 @GMT-2026.09.19-09.00.00
@GMT-2026.08.11-07.07.13 @GMT-2026.09.10-06.15.00 @GMT-2026.09.14-21.15.00 @GMT-2026.09.16-17.15.00 @GMT-2026.09.19-03.15.00
@GMT-2026.09.19-03.45.00 @GMT-2026.09.19-05.45.00 @GMT-2026.09.19-07.45.00
</syntaxhighlight>

== Hints ==

* It's not allowed to use SDS@hd as a backup for your data. The data on SDS@hd must be actively used. If the data is not actively used, you might find out about an accidental deletion of data far too late so that there isn't a snapshot anymore that contains the deleted data.
* Please avoid keeping duplicate data in your SV. Even if the duplicate data is stored in the SV for a short time period only, it can still make it into a snapshot and use up storage space on SDS@hd for quite a long time.
* When uploading data, please make sure that all the data actually made it into the SV. The snapshots can't capture data that has never reached the SV. Please see [[Data_Transfer | Data Transfer]] for help with ensuring that data transfers were finished successfully.

Running Calculations

2026-07-14T08:32:28Z

H Schumacher: Added monitoring

← This page is used in the [[HPC Glossary]] to explain the term "Batch Scheduler" and "Batch System"
== Life Cycle of a Calculation (Job) ==
[[File:running_calculations_on_cluster.svg|thumb|upright=0.4]]
On your desktop computer you start your calculations and they start immediately, running until they are finished. Then your desktop does mostly nothing, until you start another calculation. A compute cluster has several hundred, maybe a thousand computers (compute nodes), all of them are busy most of the time and many people want to run a great number of calculations. So running your job has to include some extra steps:

# prepare a script (a set commands to run - usually as a shell script), with all the commands that are necessary to run your calculation from start to finish. In addition to the commands necessary to run the calculation, this ''[[batch script]]'' has a header section, in which you specify details like required compute cores (processing units witin a computer), estimated runtime, memory requirements, disk space needed, etc.
# ''Submit'' the script into a queue, where your ''job'' (calculation)
# gets asigned an inital priority, is queued and waits in row with other compute jobs until the resources you requested in the header become available. (Requested time is also a resource!)
# Execution: Once a suitable resource slot is available and your job is in the front of the queue of suitable jobs (suitable with regards to the resource slot), your script is executed on (a) compute node(s). Your calculation runs on that/those node(s) until it is finished or reaches the specified time limit.
# Save results: Include commands to save the calculation results back to a long term storage (e.g. your home directory), at least at the end of your script. What you have not saved until the job finishes won't be saved!
# If your job reaches the specified time limit, all your running processes will be killed and the resources get cleared. So any data that has not been saved will be lost!

The software that distributes jobs on compute nodes is called a '''[[batch system]]''' or '''batch scheduler'''. The software currently used as a [[batch system]] on bwHPC clusters is "Slurm".

Learn more about the functioning of job distribution in

→ '''[[batch system]]'''

== Example Jobs ==

For most software that a bwHPC project installed on the cluster, we have prepared an example job script running some example calculation with that exact software.

How to access these examples is described in the "Software job examples" section of the page

→ '''[[Environment Modules]]'''

== Job Script and Job Submission ==

Batch jobs are submitted with the command:

<syntaxhighlight lang="bash">$ sbatch <job-script> </syntaxhighlight>

A job script contains options for Slurm in lines beginning with #SBATCH as well as your commands which you want to execute on the compute nodes. For example:

<syntaxhighlight lang="slurm">#!/bin/bash
#SBATCH --partition=<cluster specific>
#SBATCH --ntasks-per-node=8
#SBATCH --time=00:05:00
#SBATCH --mem=1gb
#SBATCH --export=NONE
echo 'Here would start your calculation script'
</syntaxhighlight>

Please see cluster specific examples from the links in the next section, because exact options needed differ by cluster.

== Link to Batch System and Examples per Cluster ==

Because of differences in configuration (partly due to different available hardware), each cluster has their own batch system documentation:

→ '''[[BwUniCluster3.0/Running_Jobs|Slurm bwUniCluster 3.0]]'''

→ '''[[JUSTUS2/Jobscripts: Running Your Calculations | Slurm JUSTUS 2]]'''

→ '''[[Helix/Slurm | Slurm Helix]]'''

→ '''[[NEMO2/Slurm | Slurm NEMO2]]'''

→ '''[[BinAC2/Slurm | Slurm BinAC2]]'''

== How To Run Jobs Efficiently ==

When you are running your calculations, you will have to decide on how many compute-cores your job will be simultaneously calculated.
For this, your computational problem will have to be divided into pieces, which always causes some overhead.

How to find a reasonable number of how many compute cores to use for your calculation can be found under

→ '''[[Scaling]]'''

Running calculations on an HPC node consumes a lot of energy. To make the most of the available resources and keep cluster and energy use as efficient as possible please also see our advice for

→ '''[[Efficient Cluster Usage]]'''

To optimize the job efficiency, it is very helpful to check which resources a job has actually used.

→ '''[[Job Monitoring]]'''

Scaling

2026-07-14T07:52:57Z

H Schumacher: Added a summary in the beginning.

'''Scaling'''
<blockquote>Dividing a problem in several sub-problems creates additional work for taking track of the sub-problems and assembling the pieces to solve the whole problem. At some point this additional work becomes larger than the work spent on calculating the actual problem. A problem is called to "scale well", if little such additional work is needed.</blockquote>

Use cases for scaling up parallel programs would be to explore research questions...
* ...in higher resolution
* ...at a larger scale
* ...with increasing complexity

Before you submit large runs, hundreds or thousands of similar calculations, on a bwHPC cluster you should define an optimal amount of compute-cores required for your job. If you use too few cores, your computation may take much too long - if you use too many cores, they will not improve the speed of your computation and all you do by using more cores is wasting compute resources and energy while decreasing your fair share value which means longer waiting times for your future jobs.

A scaling analysis is done by identifying the number of resources (such as the number of cores, nodes, or GPUs) that enable the best performance for a given compute job.

Before getting started, read first the chapter about [[Energy Efficient Cluster Usage | (Energy) Efficient Cluster Usage]] to make sure that you don't scale up an inefficient job.

== Basic Recipe to Determine Core Numbers ==

# Optimizing resource usage is most relevant when submitting many or resource-heavy jobs.
# If you plan to submit many jobs, verify that the core number is acceptable. If the jobs use N cores (i.e. N is 128 for a two-node job), then run the same job with N/2 cores (in this example 64 cores).
# To calculate the speedup, you then divide the (longer) run time of the N/2-core-job by the (shorter) run time of the N-core-job. Typically the speedup is a number between 1.0 (no speedup at all) and 2.0 (perfect speedup - all additional cores speed up the job).
#: a) IF the speedup is better than a factor of 1.7, THEN using N cores is perfectly fine.
#: b) IF the speedup is worse than a factor of 1.7, THEN using N cores wastes too many resources and N/2 cores should be used.

== Considering Resources vs. Queue Time ==

When a job is submitted to the scheduler of an HPC cluster, the job first waits in the queue before being executed on the compute nodes.
The amount of time spent in the queue is called the queue time.
The amount of time it takes for the job to run on the compute nodes is called the execution time.

The figure below shows that the queue time increases with increasing resources (e.g., CPU cores) while the execution time decreases with increasing resources.
One should try to find the optimal set of resources that minimizes the "time to solution" which is the sum of the queue and execution times.
A simple rule is to choose the smallest set of resources that gives a reasonable speed-up over the baseline case.

[[File:Fig_resources_vs_queue_time.jpg|800px|center]]

== Scaling Efficiency ==

When you run a parallel program, the problem has to be cut into several independent pieces. For some problems, this is easier than for others - but in every case, this produces an overhead of time used to divide the problem, distribute parts of it to tasks, and stitch the results together.
For a theoretical amount of "infinite calculations", calculating each problem on one single core would be the most efficient way to use the hardware.
In extreme cases, when the problem is very hard to divide, using more compute cores, can even make the job finish later.

For real calculations, it is often impractical to wait for calculations to finish if they are done on a single core.
Typical calculation times for a job should stay under 2 days, or up to 2 weeks for jobs that cannot use more cores efficiently.
Any longer and the risks such as node failures, cluster downtimes due to maintenance, and getting (possibly wrong) results after too much wait time can become too much of a problem.

A common way to assess the efficiency of a parallel program is through its speedup.
Here, the speedup is defined as the ratio of the time a serial program needs to run to the time for the parallel program that accomplishes the same work.

Speedup= Time(serial program) / Time(parallel program)

A simple example would be a calculation that takes 1000 hours on 1 core.
Without any overhead from parallelization, the same calculation run on 1000 cores would need 1000/100= 10 hours, the ideal speedup.
More realistically, such a calculation for parallelized code would need around 30 hours.

[[File:Fig_speedup.png|400px|center]]

However, there is a theoretical upper limit on how much faster you can solve the original problem by using additional cores ([[Wikipedia:Amdahl%27s_law|Amdahl's Law]]).
While a considerable part of a compute job might parallelize nicely, there is always some portion of time spent on I/O, such as saving or reading from disc, network limitations, communication overhead, or performing calculations that cannot be parallelized, thus reducing the speedup that is possible by simply adding more computational resources.

From the speedup, a useful definition of efficiency can be derived:

Efficiency = Speedup / Number of cores = Time(serial program) / (Time(parallel program) * Number of cores)

The efficiency allows for an estimation of how well your code is using additional cores, and how much of the resources are lost by doing parallelization overhead calculations.
Coming back to the previous example, we can now use the time of a serial calculation (1000 hours), the time our parallelized code took to finish (30 hours), the number of cores we used (100 cores), and calculate the efficiency.

Efficiency = 1000 / (30 * 100) = 0.3

This shows that for this example, only 30% of the resources are used to solve the problem, while 70% of our resources are spent on parallelization overhead.
A semi-arbitrary cut-off for determining if a job is well-scaled is if 50% or less of the computation is wasted on parallelization overhead.
Therefore, we can determine that for this example too many resources are used.

In many cases, the time needed for calculating a given code in serial, on a single core, is not accessible, as this would take a very long time and is usually the reason why an HPC cluster is needed in the first place.
To circumvent this, the relative speedup when doubling the number of cores is calculated.

Relative Speedup (N Cores -> 2N Cores) = Time(N Cores) / Time(2N Cores)

The relative speedup obtained by doubling the number of cores can be used as a rough guideline for a scaling analysis.
If doubling the number of cores results in a relative speedup of above 1.8, the scaling is considered good.
Above 1.7 is considered acceptable, while a relative speedup of less than 1.7 should usually be avoided.
We can illustrate this by using our simple parallelization example from above.
If we assume that our code would have finished in 45 hours when using 50 cores, we can calculate the relative speedup:

Relative Speedup (50 Cores -> 100 Cores) = Time(50 Cores) / Time(100 Cores) = 45 h / 30 h = 1,5

A relative speedup of 1,5 is considered undesirable, so we should run our example code using 50 rather than 100 cores on the HPC cluster.

In the following a scaling analysis from a real example using the program VASP is shown.

[[File:Fig_speedup_and_efficiency_1.png|700px|center]]

[[File:Fig_speedup_and_efficiency_2.png|700px|center]]

== Better Resource Usage by Increasing the System Size ==

Amdahl’s law, as illustrated above, gives the upper limit of speedup for a problem of fixed size.
By simply increasing the number of cores to speed up a calculation your compute job can quickly become very inefficient, and wasteful.
While this appears to be a bottleneck for parallel computing, a different strategy was pointed out ([[Wikipedia:Gustafson's_law|Gustafson's law]]).

A reasonable choice is to use small amounts of resources for small problems and larger quantities of resources for big problems. Thus, researchers can take advantage of available cores by scaling up parallel programs to explore their questions in higher resolution or at a larger scale.

Energy Efficient Cluster Usage

2026-07-14T07:51:47Z

H Schumacher: Restructured content and added more advice

Poor job efficiency means that hardware resources are wasted and a similar overall result could have been achieved using fewer hardware resources, leaving those for other jobs and reducing the queue wait time for all users.
Efficient cluster usage means choosing optimal values for job resources:
* CPU cores
* GPUs
* Memory
* (temporary) storage
* Time

__TOC__

== Motivation ==
'''User perspective'''

Short waiting times including short cycles of trial and error and fast results. The lower the job efficiency the longer the waiting times relative to the shortest possible time.

'''Energy perspective'''

Energy consumption of data centers has been increasing continuously throughout the last decade. In 2020, the energy consumption of all data centers in Germany amounted to around [https://www.bundestag.de/resource/blob/863850/423c11968fcb5c9995e9ef9090edf9e6/WD-8-070-21-pdf-data.pdf 3 percent] of the total electricity produced. Accompanying this large energy consumption are large-scale emissions of CO2 to the atmosphere and thus significant contributions to climate change.
To illustrate this, an average compute job running on a single node for one day may easily consume 10 kWh or even more. That translates roughly to brewing 700 cups of coffee.
Assuming that a typical bwHPC cluster has a few hundred compute nodes, this amounts to the energy consumption of a village for each cluster.
Although a large amount of this energy consumption is an intrinsic requirement of running large HPC clusters (even when it's processors are idle, a cluster uses a lot of energy), efficient use of the available resources is important.

Something to keep in mind:
‎<blockquote>Using as many resources as possible does not make a power user. Using them wisely does.‎</blockquote>

== Recommendations ==

* Use the '''job monitoring''' options of your respective cluster to see the job efficiency and ways to improve it.
* '''Test''' new setups first before submitting a lot of similar jobs or resource demanding jobs.
** Run a single job first before sending many.
** Run a simplified problem on a small number of parallel entities (be it processes or threads) first before requesting many resources.
** Run a time intensive task with a short runtime first to see if it already fails in the first minutes.
* Follow the best practices of your chosen tool, software or programming language and choose the most efficient algorithms for the given problem. There are several places where you might find related documentation:
** Software Module help.
** Software page of your cluster.
** Pages linked at the [[Development]] page. For example information about debugging, performance analysis, specific programming languages etc. . → Use an efficient programming language such as Rust, C, and C++ -- well any compiled language. Do not use any interpreted language like Perl or Python. Since Machine Learning is a hot topic, this deserves a few words: Any ML-Python code using Tensorflow or other libraries will make heavy usage of NumPy and other math packages, which will use C-based implementations. Please make sure, you use the provided Python modules, which are optimized to use Intel MKL and other mathematical libraries.
Further reading:
Rui Pereira, et al: "''Energy efficiency across programming languages: how do energy, time, and memory relate?''", SLE 2017: Proc. of the 10th ACM SIGPLAN Int. Conf. on SW Language Eng., Oct. 2017, pp. 256–267, [https://doi.org/10.1145/3136014.3136031 doi:10.1145/3136014.3136031]
* If you have a task that can be scaled up, please consider a [[Scaling | '''scaling analysis''']].
* Analyse '''memory access patterns''': For small tight loops checking for locks, use the <code>pause</code> instruction.

== Things to avoid ==

* Poor choice of resources compared to the size of the nodes leaves part of the node blocked, but doing nothing:
** Too much (un-needed) memory or disk space requested
* Many small jobs with a short runtime (seconds in extreme cases). A job should run at least 10 minutes.
* When a node has 256 gb memory but only 236 gb are usable (see Hardware table of your cluster) then requesting 256 gb memory needs two nodes.
* GPU: Do not ask for a specific gpu type when your code would be fitting for any type.
* More cores used for a single mpi/openmp parallel computation than useful.
* Writing temporary files to global filesystems when a ram disk or local disk can be used.
* Do not use more parallel processes than there are actual, reasonable parallel tasks. Examples:
** 4 datasets with values for the same 1000 genes each. Method xx shall be used per gene. This operation needs 10 seconds per gene.
*** Case 1: Provide 64 single threaded cores within one job and use one process/thread per gene: This creates a large overhead as only 64 processes can run in parallel while all 5000 processes try to get computing time so that a process might run for 5 seconds and then makes room for another process that also isn't able to finish because another process comes in between.
*** Case 2: Send 1 job per gene so that each job uses method xx on this gene in all 4 datasets: This creates a large overhead as each job only needs 50 seconds while there is a thousand times the overhead of creating and finishing a job.
*** Case 3: Provide 64 cores in one job. Each dataset uses 16 cores. Each core needs to process 1000/16 =~ 63 genes. This needs 63*10 seconds
= 10.5 minutes job runtime with just the overhead of creating a single job and 16 processes without switching between processes.
** → Simple parallelization by hand is advisable. See: A basic introduction to [[Development/Parallel_Programming | Parallel Programming]].

== Fair Share and Scheduler ==
Influence of Efficiency on Fair Share and Scheduler:
* '''Fair Share value:'''
*: The fair share value represents your priority on the cluster. On a busy cluster a low priority leads to longer waiting times as other users with a higher priority have a higher chance of getting free resource slots. The fair share value declines when a lot of cluster resources were used recently. Used is defined as follows:
*:* Requested resources: 4 gpus for 2 hours
*:* Actual resource usage: 1 gpu and job finishes successfully after 1 hour.
*:* Used resources as considered by the fair share value: 4 gpus for 1 hour because the three idle gpus couldn't be used by any other cluster used as they were blocked by this job.
* '''Job scheduler:'''
*: The longer the requested runtime and the more resources are needed in that time the harder it is to find a fitting timeframe where these resources are free.

SDS@hd/Registration/Entitlement

2026-07-13T12:21:49Z

H Schumacher: added a sentence from the service description page

== Get SDS@hd Entitlement ==

New SVs can only be opened by bwIDM members who have the '''sds-hd-sv''' entitlement from their home university. This entitlement may have to be applied for individually at the home organisation. The criteria for awarding the entitlement to a user are entirely up to the respective home organization

To see if you already have the needed entitlement, you can [[SDS@hd/Registration/Entitlement#Check_your_Entitlements|''check your entitlements'']].

If you need the entitlement, follow the instructions for your home university. If none are provided, please contact your local service desk.

* '''Universität Freiburg'''
** Employees of the University of need to fill out this [https://uni-freiburg.de/forms-en/sds-hd-sv-entitlement/ '''form'''].
* '''Universität Heidelberg'''
** Employees of Heidelberg University receive this entitlement automatically. Students can't receive it.
* '''Universität Mannheim'''
** Employees of the University of Mannheim receive this entitlement automatically. Students can't receive it.
* '''Universität Ulm'''
** Please contact the helpdesk. See https://www.uni-ulm.de/einrichtungen/kiz/service-katalog/beratung-schulung-hilfe/helpdesk/

== Check your Entitlements ==

# Log in to https://bwservices.uni-heidelberg.de
# Go to "Index" -> "Personal Data"
# Choose the "Shibboleth" tab
# Search for the following entry: http://bwidm.de/entitlement/sds-hd-sv (this is an attribute and not a link)
If you can find it, you already have the needed entitlement.

→ [[SDS@hd/Registration#b)_Apply_for_new_SV| go forward with the SV application]]

SDS@hd/Acknowledgement

2026-07-13T12:11:31Z

H Schumacher: added third party funded projects

When preparing a publication describing work that involved the usage of SDS@hd, please ensure that you reference the system. The following sample text is suggested as a starting point.

'''SDS@hd Acknowledgement:'''
:<syntaxhighlight>The authors gratefully acknowledge the data storage service SDS@hd supported by the Ministry of Science, Research and the Arts Baden-Württemberg (MWK) and the German Research Foundation (DFG) through grant INST 35/1803-1 FUGG and INST 35/1804-1 LAGG.</syntaxhighlight>

If [[Helix/bwVisu|bwVisu]] plays an important role for your project, please also reference this service:

→ '''[[Helix/bwVisu/Acknowledgement|bwVisu Acknowledgement]]'''

In addition, we kindly ask you to notify us of any
* reports
* conference papers
* journal articles
* theses (BSc, MSc, PhD)
* posters
* talks
* third-party funded projects

which contain results obtained on work with SDS@hd by sending an email to
[mailto:sds-hd-support@urz.uni-heidelberg.de sds-hd-support@urz.uni-heidelberg.de] stating:

* SV acronym (e.g. sd16A000)
* author(s)
* title ''or'' booktitle
* journal, volume, pages ''or'' editors, address, publisher
* year.

Such recognition is important for acquiring funding for the next generation hardware, support services, data storage and infrastructure. Thank you!

Registration/bwForCluster/RV/Management

2026-06-22T10:59:31Z

H Schumacher: added RV extension section, redesigned 'change RVV' section

== Roles in a RV ==
There are three different roles in an RV. Depending on your role, different management activites can be executed in the ZAS under [https://zas.bwhpc.de/shib/en/info_rv.php '''My RVs''']. These are described below.

=== RV Coworker ===

A coworker is a typical user who registered themselves via RV acronym and RV password. They...
* ...can check the status of their memberships (active/inactive).
* ...can check the status of the RV (active/inactive & the date when it becomes inactive when it doesn't get prolonged).
* ...can deregister from an RV.
* ...have to acknowledge the cluster in publications and inform the RV responsible of these publications.

=== RV Manager ===

Additionally to the abilities of a coworker, a manager can...

* ...re-activate deregistered or inactive members.
* ...check the list of RV members at [https://zas.bwhpc.de/shib/en/info_rv.php '''My RVs'''] by selecting the RV acronym. After a role change, click '''Save changes''' at the end of the members list.

=== RV Responsible ===

Additionally to the abilities of a manager, the responsible can...

* ...assign managers.
* ...extend the runtime of the RV by one more year. Therefore, a list of publications that were created with the help of the cluster must be provided when submitting the prolongation form.
* ...change the RV responsible.
* ...set a new password if necessary and share the password with future coworkers so that they can join the RV.

==== Renew RV Password ====

If you lose the RV password or want to create a new one, you can simply renew it:

1. Login to [https://zas.bwhpc.de/shib/en/info_rv.php '''My RVs'''] first.
[[File:RV-my.png|center|frame|My RVs.]]

2. Select the RV acronym for your RV.

3. Scroll down and click '''Renew password'''.
[[File:RV-pw.png|center|thumb|400px|Renew RV password.]]

You will get a form that looks similar to the form you got when registering the compute project. Most fields will be pre-filled with the things you entered when registering. Please check if the entered data is still accurate for your compute activity and adjust if necessary.

A new field in the form asks you to fill in the publications that acknowledge the cluster. Please enter the DOIs of those publications. These publications should all have the cluster you used in their Acknowledgement in a format as shown in the [[Acknowledgement]] section for each cluster.

==== Change the RV Responsible ====

<ins>Prerequisites:</ins>

* You need to be the current RV responsible. In case you don't have access to your account anymore, you can ask the cluster support for help.
* The person you want to appoint as new RV responsible is a member of the RV.

<ins>Steps:</ins>

<gallery mode="packed" style="align=left;">
File:RV-my.png|center|frame|'''1.''' Login to [https://zas.bwhpc.de/shib/en/info_rv.php '''My RVs'''] and go to the RV.
File:Rv-hand1.png|right|thumb|400px|'''2.''' Scroll down and click '''Handoff'''.
File:Rv-hand2.png|right|thumb|800px|'''3.''' Select "New RV responsible" from the drop-down menu, check "Agreement" and click "Preview: Handover RV" to continue.
File:Rv-hand3.png|right|thumb|800px|'''4.''' Confirm the handover.
</gallery>
'''5.''' The newly appointed RV responsible gets notified via email. They have to accept within seven days.

==== RV Extension ====
An RV is valid for one year. After that, the RV responsible must apply for an extension of the RV for it to be renewed for another year.

<ins>Hints for specific cases:</ins>
* I don't think that filling in the publication field is very important.
*: → The bwHPC clusters can be used for free but it's very important for us to acquire funding for the next generation hardware, support services, data storage and infrastructure. To get funding, it's essential to provide a list of research publications that benefitted from the clusters. Furthermore, you've personally agreed to report publications in the process of registering for the cluster and you agreed to acknowledge them accordingly. Each cluster provides an example text for the acknowledgement.
* I'm late with the extension application and it would take some time to find out cluster related publications.
*: → Write something like "I will provide them later" and send the list to your cluster's support unit as soon as you have them collected.
* We had a lot of publications but I'm not sure which ones made use of the cluster.
*: → Please don't hand in the whole list but ask the RV members directly.
* We didn't have any cluster related publications.
*: → We would appreciate a short note about the reason. Some examples: "We didn't need the cluster much", "The publication is still work in progress", "We'd appreciate some help for getting started with the cluster usage".
* We have only preprints so far.
*: → You can report them already.
* The purpose and resource needs of the RV have changed.
*: → While it won't change anything for you, we still appreciate it when the information get updated via the RV extension form.
* We forgot to acknowledge the cluster in most of the publications.
*: → That's unfortunate but please report them nevertheless. You can save us the hassle of checking in detail when you provide us with an additional confirmation that the cluster was indeed used. For example "Some acknowledgements are missing but I confirm that the cluster usage was relevant for the publications nevertheless".
* I fear that the RV gets deactivated before the extension application gets accepted.
*: → Depending on the cluster the access will still be possible for a while even if the RV is over its due date. But no new members can join while the extension is pending.
* We didn't use the RV for a long time but now that I want to hand in the RV extension, I don't see the button anymore.
*: → Please write to the support. We can enable the button again for 14 days.
* Looking back I must say that we did some great research with the help of the cluster.
*: We're happy to hear that and would love to show it off at our bwHPC website as [https://www.bwhpc.de/success_stories.php success story]. Don't hesitate to [https://www.bwhpc.de/project_report.php submit] a short summary.

Registration/bwForCluster/Helix

2026-06-17T08:43:27Z

H Schumacher: emphasized main point

__FORCETOC__

== Prerequisites ==

Steps A + B in the [[Registration/bwForCluster | registration process]] must be finished.

== Registration Steps ==

# Visit the bwForCluster Helix '''[https://bwservices.uni-heidelberg.de registration page bwServices]'''.
#: [[File:bwServices_chooseHomeOrganisation.png|right|300px|thumb|Select your home organization]]
# '''Select your home organization''' from the list on the main page and click Proceed/Fortfahren. You will be directed to the ''Identity Provider'' of your home organization.
# Enter the '''username and password''' of your home organization (usually these credentials are also used for other services like email) and click Login/Einloggen.
# When you log in to bwServices for the first time, an overview will appear, with the account information that your home institution submits to the system. Please verify that all data is valid and then click ''Continue/Weiter''.
# You will be redirected back to the bwServices main page. It shows all the statewide services you have access to. Click '''Register/Registrieren''' under the field labeled ''bwForCluster Helix''.
#: [[File:BwIDM-reg.png|center|frame|Register for Helix]]
# bwForCluster Helix uses a '''2-factor authentication''' (2FA) mechanism to increase security.
#: If you have never registered a 2FA token on bwIDM, the following error message will appear:
#: [[File:Bwidm-3-red.png|center|600px|thumb|Second factor missing.]]
#: Use this '''[https://bwservices.uni-heidelberg.de/user/twofa.xhtml link]''' or select '''My Tokens''' in the main menu.
#: To register a new token, please follow these '''[[Registration/2FA|instructions]]'''.
#: Please complete this step before continuing.
# Read the Terms of Use / Nutzungsbedingungen, place a check mark next to ''I have read and accepted the terms of use'' and click ''Register/Registrieren''.
# '''Set a service password''' for bwForCluster Helix and click ''Save/Speichern''.
#: Be sure to use a secure password that is different from any other passwords you currently use or have used on other systems.
[[File:BwIDM-passwd.png|center|600px|thumb|Set service password]]
{|style="background:#deffee; width:70%; margin: auto;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
The service password is your private password for accessing the bwForCluster Helix. Don't ever share it with anyone!
|}

== Registration Website bwServices ==
The registration website '''[https://bwservices.uni-heidelberg.de bwServices]''' offers the following functionality:
* Register for the service.
* Set or change your service password.
* Review your registration details under "Registry Info". This includes your account status (active/lost_access).
* bwServices triggers an update of your user information upon login.
* Registering an [[Registration/SSH | SSH key]]. It can be used for login to ''bwForCluster Helix''.
* Creating tokens for logins that need 2-factor authentication ([[Registration/2FA |2FA]]) like ''bwForCluster Helix'' and ''bwVisu''.
* De-register from the service.

=== Troubleshooting with the Help of bwServices ===
When encountering connection issues with a service, the bwServices website is a good starting point for troubleshooting:
{| style="border: 2px solid #FFD28A; background-color: #ffe0af; padding: 10px; margin-bottom: 1em; width: 100%;"
|-
| '''⚠ Login to bwServices first.''' This triggers an update of your user information within some minutes and solves the connection issue in the following cases:
* User data changed: entitlement, SV/RV status, SV/RV membership status, role or email address changed or uni-id was (re)activated
* Synchronization issues of the service
|}

* <ins>'''Issue:</ins> Expired contract''' or inactive student id:
** No access to state services like the bwHPC clusters or SDS@hd is possible.
** You can see that this is the issue when the login to bwServices via your identity provider is not possible.
* <ins>'''Issue:</ins> Entitlement / RV missing:''' Prerequisites like entitlement ownership or RV membership aren't met (anymore).
** You can see the concrete issue and advice on how to move forward when looking at the registry info of the service on the bwServices website.
** When the issue is solved, the account status changes from LOST_ACCESS to ACTIVE.
* <ins>'''Issue:</ins> Service Password:''' When trying to connect to the service, the service password is not accepted.
** Set a [[#Setting_a_New_Service_Password | new password]].
* <ins>'''Issue:</ins> OTP:''' In the case of login issues with a service that uses 2FA, you can check if you're OTP is working by going in the menu to ''Index'' -> ''My Tokens''.
** If you're token is not working, you might have had too many failed login attempts. You can request a reset of the error counter from the support.
** If the token needs to be reset, please follow the instructions for a [[Helix/Login#Troubleshooting | Lost Token]].

=== Setting a New Service Password ===

At any time, you can set a new service password via [https://bwservices.uni-heidelberg.de/ bwServices] by carrying out the following steps:
# Visit [https://bwservices.uni-heidelberg.de/ bwServices] and select your home organization.
# Authenticate yourself via your home-organizational user id / username and your home-organizational password.
# Find your service and select '''Set Service Password'''.
# Set new service password, repeat it and click the '''Save''' button. Use a secure password that is different from any other passwords you currently use or have used on other systems.
# The page answers e.g. "password has been changed".

SDS@hd/Registration

2026-06-09T09:02:54Z

H Schumacher: changed link from responsible to manager section

== Registration Steps ==

The registration consists of two steps:

* '''Step A:''' Membership in Storage Project (Speichervorhaben/'''SV'''). There are two options:
*: '''a)''' →[[SDS@hd/Registration#a)_Join_existing_SV | Join existing SV]]
*: '''b)''' →[[SDS@hd/Registration#b)_Apply_for_new_SV | Apply for new SV]] (only possible for [https://www.bwidm.de/hochschulen.php bwIDM members])
* '''Step B:''' →[[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service |Registration for SDS@hd Service]]

After finishing the registration, the '''next steps''' are:
* Check which management options there are for your respective role in the SV → [[SDS@hd/SV_Management |SV Management]]
* See how to access and use your storage space → [[SDS@hd/Access | Access]]

[[File:SDS@hd_Registration.png|center|x500px|upright|SDS@hd Registration Process]]

=== Step A: SV Membership ===

You can either join an existing SV or start a new one.

==== a) Join existing SV ====
To join an existing SV as a coworker:
# Get the following information from the SV responsible:
#:* SV acronym
#:* SV password
# Fill in and submit the [https://sds-hd.urz.uni-heidelberg.de/management/shib/sds_collaboration.php SV collaboration form] after logging in to the SDS@hd Managementtool.
#: You are now a member of the SV. The SV owner (and SV managers) will be notified automatically.
→ [[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service | Go on with Step B]] if you are using SDS@hd for the first time.

==== b) Apply for new SV ====

This is typically done only by the leader of a scientific work group or the senior scientist of a research group/collaboration.
Any amount of co-workers can join your SV without having to register another project. You just need to provide them with the SV acronym and SV password. You'll receive this information via e-mail as soon as the SV application was successful.

There are two steps:
# '''Get the permission / entitlement:'''. Your institution has to grant you the permission to start an SDS@hd storage project ("SDS@hd SV entitlement"). Please follow the procedure specific to your institution:
#: → see [[SDS@hd/Registration/Entitlement | Entitlement]].
# '''Apply for a new SV:'''
#: → Fill in the form at the [https://sds-hd.urz.uni-heidelberg.de/management SDS@hd Managementtool].
→ [[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service | Go on with Step B]] if you are using SDS@hd for the first time.

If you register your own SV, you will be:
* ...responsible for providing new members with the necessary information to join the SV. SV managers can do the same.
*: → see [[SDS@hd/SV_Management#SV_Manager | SV Manager]]
* ...held accountable for the co-workers in the SV
* ...asked to provide information for the two reports required by the DFG for their funding of SDS@hd
* ...likely asked for a contribution to a future DFG grant proposal for an extension of the storage system in your area of research ("wissenschaftliches Beiblatt")

=== Step B: Registration for SDS@hd Service ===
[[File:bwServices_chooseHomeOrganisation.png|right|300px|thumb|Select your home organization]]

After step A you have to register your personal account on the storage system and set a service password.

* Visit the registration website '''bwServices''': [https://bwservices.uni-heidelberg.de/ https://bwservices.uni-heidelberg.de]
*# Select your home organization from the list and click ''Proceed''
*#: You will be directed to the ''Identity Provider'' of your home organisation
*# Enter your home-organisational user ID / username and your home-organisational password and click ''Login'' button
*#: You will be redirected back to bwServices
* '''Register''' for the SDS@hd service:
*# Under ''The following services are available'' select the service ''SDS@hd - Scientific Data Storage''.
*# Click ''Register''
* Set your personal '''service password''' for SDS@hd. This is used for accessing SVs.
* The registration is finished.
*: → [[#sds_registration_nextSteps|next steps]]

=== Change Service Password at bwServices ===

→ '''[[Registration/bwForCluster/Helix#Setting_a_New_Service_Password | Setting a New Service Password]]'''

SDS@hd/SV Management

2026-06-09T09:00:50Z

H Schumacher: moved some points from responsible to manager

== Roles in a SV ==
There are four different roles in an SV. Depending on the role, different management activites can be executed at the [https://sds-hd.urz.uni-heidelberg.de/management SDS@hd Managementtool]. These are described below. They include top level management of user access.

=== SV Member or Guest ===
At the [https://sds-hd.urz.uni-heidelberg.de/management SDS@hd Managementtool] members/guests can...
* ...view the status of your SV memberships (active/inactive)
* ...view the status of the SV (active/inactive, end date). (Removing people from the list completely is not possible, yet.)

=== SV Manager ===
Additionally to the abilities of a coworker, a manager can...
* ...change the SV password
* ...enable others to join the SV
*# Provide them with the SV acronym. You can look it up at the [https://sds-hd.urz.uni-heidelberg.de/management/shib/info_sv.php SDS@hd Managementtool].
*# Provide them with the SV password. The SV responsible received the initial password via email. Caution: Make sure to share the SV password. Do not share your personal service password which you set in registration step B at bwServices.
*# Afterwards, they can join by following the [[SDS@hd/Registration | registration steps]].
* ...change the status of SV members (active/inactive)

=== SV Responsible (SVV) ===
Additionally to the abilities of a manager, the responsible can...
* ...enable the guest folder
* ...change the role of SV members (guest/full member)
* ...hand over the SV responsibility
* ...cancel the SV when it is not needed anymore

== Yearly storage project (SV) extension ==

Once a year the SV responsible person needs to apply for a lifetime extension of the storage project. As part of the application, you will be asked to inform us of publications for which the storage project was used. As long as SDS@hd is used appropriately, an extension will be granted.

SDS@hd/SV Management

2026-06-09T07:13:34Z

H Schumacher: fixed unclear instruction

== Roles in a SV ==
There are four different roles in an SV. Depending on the role, different management activites can be executed at the [https://sds-hd.urz.uni-heidelberg.de/management SDS@hd Managementtool]. These are described below. They include top level management of user access.

=== SV Member or Guest ===
At the [https://sds-hd.urz.uni-heidelberg.de/management SDS@hd Managementtool] members/guests can...
* ...view the status of your SV memberships (active/inactive)
* ...view the status of the SV (active/inactive, end date) (Removing people from the list completely is not possible, yet)

=== SV Manager ===
Additionally to the abilities of a coworker, a manager can...
* ...change the status of SV members (active/inactive)

=== SV Responsible (SVV) ===
Additionally to the abilities of a manager, the responsible can...
* ...enable others to join the SV
*# Provide them with the SV acronym. You can look it up at the [https://sds-hd.urz.uni-heidelberg.de/management/shib/info_sv.php SDS@hd Managementtool].
*# Povide them with the SV password. You've received this password via email. You can reset it at the [https://sds-hd.urz.uni-heidelberg.de/management/shib/info_sv.php SDS@hd Managementtool]. Caution: Make sure to share the SV password. Do not share your personal service password which you set in registration step B at bwServices.
*# Afterwards, they can join by following the [[SDS@hd/Registration | registration steps]].
* ...enable the guest folder
* ...change the role of SV members (guest/full member)
* ...change the SV password
* ...hand over the SV responsibility
* ...cancel the SV when it is not needed anymore

== Yearly storage project (SV) extension ==

Once a year the SV responsible person needs to apply for a lifetime extension of the storage project. As part of the application, you will be asked to inform us of publications for which the storage project was used. As long as SDS@hd is used appropriately, an extension will be granted.

Registration/bwForCluster/Helix

2026-06-03T15:07:33Z

H Schumacher: broadened the scope of the second issue

__FORCETOC__

== Prerequisites ==

Steps A + B in the [[Registration/bwForCluster | registration process]] must be finished.

== Registration Steps ==

# Visit the bwForCluster Helix '''[https://bwservices.uni-heidelberg.de registration page bwServices]'''.
#: [[File:bwServices_chooseHomeOrganisation.png|right|300px|thumb|Select your home organization]]
# '''Select your home organization''' from the list on the main page and click Proceed/Fortfahren. You will be directed to the ''Identity Provider'' of your home organization.
# Enter the '''username and password''' of your home organization (usually these credentials are also used for other services like email) and click Login/Einloggen.
# When you log in to bwServices for the first time, an overview will appear, with the account information that your home institution submits to the system. Please verify that all data is valid and then click ''Continue/Weiter''.
# You will be redirected back to the bwServices main page. It shows all the statewide services you have access to. Click '''Register/Registrieren''' under the field labeled ''bwForCluster Helix''.
#: [[File:BwIDM-reg.png|center|frame|Register for Helix]]
# bwForCluster Helix uses a '''2-factor authentication''' (2FA) mechanism to increase security.
#: If you have never registered a 2FA token on bwIDM, the following error message will appear:
#: [[File:Bwidm-3-red.png|center|600px|thumb|Second factor missing.]]
#: Use this '''[https://bwservices.uni-heidelberg.de/user/twofa.xhtml link]''' or select '''My Tokens''' in the main menu.
#: To register a new token, please follow these '''[[Registration/2FA|instructions]]'''.
#: Please complete this step before continuing.
# Read the Terms of Use / Nutzungsbedingungen, place a check mark next to ''I have read and accepted the terms of use'' and click ''Register/Registrieren''.
# '''Set a service password''' for bwForCluster Helix and click ''Save/Speichern''.
#: Be sure to use a secure password that is different from any other passwords you currently use or have used on other systems.
[[File:BwIDM-passwd.png|center|600px|thumb|Set service password]]
{|style="background:#deffee; width:70%; margin: auto;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
The service password is your private password for accessing the bwForCluster Helix. Don't ever share it with anyone!
|}

== Registration Website bwServices ==
The registration website '''[https://bwservices.uni-heidelberg.de bwServices]''' offers the following functionality:
* Register for the service.
* Set or change your service password.
* Review your registration details under "Registry Info". This includes your account status (active/lost_access).
* bwServices triggers an update of your user information upon login.
* Registering an [[Registration/SSH | SSH key]]. It can be used for login to ''bwForCluster Helix''.
* Creating tokens for logins that need 2-factor authentication ([[Registration/2FA |2FA]]) like ''bwForCluster Helix'' and ''bwVisu''.
* De-register from the service.

=== Troubleshooting with the Help of bwServices ===
When encountering connection issues with a service, the bwServices website is a good starting point for troubleshooting:
* <ins>'''Issue:</ins> Expired contract''' or inactive student id:
** No access to state services like the bwHPC clusters or SDS@hd is possible.
** You can see that this is the issue when the login to bwServices via your identity provider is not possible.
* <ins>'''Issue:</ins> Recently (re)activated uni-id or other user data changes:''' Your id at your home organization was (re)activated a short time ago or your email address changed (or sth. similar) but this change didn't get through to the bwHPC cluster or SDS@hd service.
** Login to bwServices. This triggers an update of your user information. Some minutes later, the connection to the service should work again.
* <ins>'''Issue:</ins> Entitlement / RV missing:''' Prerequisites like entitlement ownership or RV membership aren't met (anymore).
** You can see the concrete issue and advice on how to move forward when looking at the registry info of the service on the bwServices website.
** When the issue is solved, the account status changes from LOST_ACCESS to ACTIVE.
* <ins>'''Issue:</ins> Service Password:''' When trying to connect to the service, the service password is not accepted.
** Set a [[#Setting_a_New_Service_Password | new password]].
* <ins>'''Issue:</ins> OTP:''' In the case of login issues with a service that uses 2FA, you can check if you're OTP is working by going in the menu to ''Index'' -> ''My Tokens''.
** If you're token is not working, you might have had too many failed login attempts. You can request a reset of the error counter from the support.
** If the token needs to be reset, please follow the instructions for a [[Helix/Login#Troubleshooting | Lost Token]].

=== Setting a New Service Password ===

At any time, you can set a new service password via [https://bwservices.uni-heidelberg.de/ bwServices] by carrying out the following steps:
# Visit [https://bwservices.uni-heidelberg.de/ bwServices] and select your home organization.
# Authenticate yourself via your home-organizational user id / username and your home-organizational password.
# Find your service and select '''Set Service Password'''.
# Set new service password, repeat it and click the '''Save''' button. Use a secure password that is different from any other passwords you currently use or have used on other systems.
# The page answers e.g. "password has been changed".

Data Transfer/Rclone

2026-06-02T15:30:40Z

H Schumacher: Added instructions for adding rclone to path on windows.

[https://rclone.org/docs/ Rclone] is a command line tool to manage files on remote systems (e.g. high performance clusters, data and cloud storage systems, archiving services). 
Rclone either synchronizes in one direction only or its mounting functionality is used with <code>rclone mount</code>. 
Data can be piped between two completely remote locations. When moving data within the same system and the data transfer protocol allows for server side copy, no local download is necessary. 
One advantage is that the transfer is multithreaded and it operates on a file level basis.
'''Caution:''' When using Rclone with 2FA it is necessary to connect via ssh key instead of a password.

== Installation ==

Rclone is a Go program and comes as a single binary file.

# Download the relevant binary.
# Extract the <code>rclone</code> executable (<code>rclone.exe</code>).
# You can use the executables without further installation. For easy use, it is recommended to add the binary to your PATH environment variable. Information on how to do this can be found below.

Detailed information regarding different operating systems can be found here:

* Installation on [https://rclone.org/install/#windows Windows]
*: To use rclone after the installation, you have to open a terminal (cmd or PowerShell) in the folder where the rclone.exe file is. This can be done with a right click in the empty space wihin the rclone folder and then choosing "open in terminal". Then run all commands with a leading './' (for example <code>./rclone config</code>. To be able to simply use "rclone" anywhere, you can add it to your path. For instructions see the [[Data_Transfer/Rclone#Troubleshooting | Troubleshooting]] section.
* Installation on [https://rclone.org/install/#macos macOS]
** If Rclone shall be used together with sftp, the [[Data_Transfer/SSHFS#Installation | sshfs installation]] instructions must be followed after installing Rclone.
* Installation on [https://rclone.org/install/#script-installation Linux]

== Usage Rclone ==

To use Rclone you have to define a config file. Afterwards you can connect by using the name of your configured connections.

=== Configure Remote ===

Before you can start using Rclone, you need to set up a remote. This means to configure a specific connection by providing authentication information, the network protocol that you want to use and a name for this configuration so that you can use it later on.

To configure a remote for a specific service, you need the following information:

* <code><remotehost></code>
* <code><username></code>
* <code><servicePassword></code>

Furthermore, you have to decide on:

* <code>network protocol</code> (for example webDAV, smb, sftp)
* <code>remote-name</code> (for example you can use the name of the service you want to connect to)

You have three different options to set up a new remote as described in the following sections. It's enough to choose one of those.

'''Oneliner''' 

Open a terminal and define all parameters in one command. If a ssh key shall be used instead of a password, it might be easier to adjust the config file directly as described in the next section.
<syntaxhighlight lang="bash"># smb
rclone config create <remote-name> smb host=<remotehost> user=<username> domain=<domain> pass=<password> --obscure
# sftp
rclone config create <remote-name> sftp host=<remotehost> user=<username> pass=<password> --obscure
# webdav
rclone config create <remote-name> webdav url=<remotehost> user=<username> pass=<password> --obscure
</syntaxhighlight>

'''Adjust Config File''' 
<syntaxhighlight lang="bash">
# Make sure that a config file exists. Access rights for the config file are set to 600.
rclone config touch
# Get the location of the file:
rclone config file
</syntaxhighlight>
Open the file and use one of the following snippets as template for your connection:
<syntaxhighlight lang="bash">[<remote-name>]
type = smb
host = <hostname>
user = <userID>
domain = <e.g. BWSERVICESAD>

[<remote-name>]
type = webdav
url = <hostURL>
vendor = other
user = <userID>

[<remote-name>]
type = sftp
host = <hostname>
user = <userID>
key_use_agent = false

[<remote-name-ssh-key-version>]
type = sftp
host = <hostname>
user = <userID>
key_file = ~/.ssh/id_ed25519
pubkey_file = ~/.ssh/id_ed25519.pub
key_use_agent = true
shell_type = none
</syntaxhighlight>
To add the password, please use the following command. Make sure to keep the prepended space so that the command is not saved in your command history.
<syntaxhighlight> rclone config update <remote-name> pass=<password> --obscure</syntaxhighlight>

'''Interactive Setup''' 

Execute:
<syntaxhighlight>rclone config</syntaxhighlight>
This will guide you through an interactive setup process. It's quite helpful for checking out which options there are and what the config file looks like after setting values that deviate from the default values. You can find detailed instructions at the website:

* [https://rclone.org/webdav/ Connect via webdav]
* [https://rclone.org/smb/ Connect via smb]
* [https://rclone.org/sftp/ Connect via sftp]

=== Use Remote ===

To see all configured remotes:
<syntaxhighlight lang="bash">rclone config
# Exit with 'q'.
</syntaxhighlight>

The syntax to use Rclone is like this:

<pre>rclone [options] subcommand <parameters> <parameters...>
</pre>
List all elements in the folder XX:
<syntaxhighlight lang="bash">rclone lsf <remote-name>:XX
# List elements from subfolders as well:
rclone lsf --max-depth 2 <remote-name>:XX
</syntaxhighlight>
Copies /local/path to the remote path

<pre>rclone copy </local/path> <remote-name>:<remote/path>
</pre>
Copies fom remote path to /local/path

<pre>rclone copy <remote-name>:<remote/path> </local/path>
</pre>
Moves the contents of the source directory to the destination directory.

<pre>rclone move <remote-name>:<source/path> <remote-name>:<destination/path>
</pre>
More subcommands can be found [https://rclone.org/docs/#subcommands here].

== Usage Rclone Mount ==

Before you can follow the instructions in this chapter, you need to have set up a [[Data_Transfer/Rclone#Usage_Rclone | remote]].
More detailed information on how to use rclone mount can be found [https://rclone.org/commands/rclone_mount/ here].

=== Windows ===

To run rclone mount on Windows, you will need to [https://winfsp.dev/rel/ download and install WinFsp] first.

<syntaxhighlight lang="python"># mount under drive letter X (or any other free letter)
rclone mount --vfs-cache-mode full <remote-name>:<path/to/remote/files> X:
# or provide the path to a nonexisting folder:
rclone mount --vfs-cache-mode full <remote-name>:<path/to/remote/files> <C:\path\parentDir\nonexistingFoldername></syntaxhighlight>
To unmount, the command can be stopped in the terminal with the key combination CTRL+C. Alternatively, a mounted drive can be unmounted by making a right click on the drive name in the file explorer and choose "Eject". 
In contrast to Linux/Mac, there is no background mode.

=== MacOS & Linux ===

You can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the <code>--daemon</code> flag to force background mode. If this doesn't work, you can put an <code>&</code> at the end of the command instead.

Create an empty directory on your local machine and then execute

<syntaxhighlight lang="bash"># to mount the root folder:
rclone mount --vfs-cache-mode full <remote-name>: /path/to/empty/folder
# to mount a subfolder:
rclone mount --vfs-cache-mode full <remote-name>:folderX/folderY /path/to/empty/folder
# to unmount:
fusermount -uz /path/to/mounted/folder </syntaxhighlight>

== Best Practices ==

Rclone has a lot of useful options.

=== Performance ===

To be able to utilize a larger bandwidth, it is helpful to add the following options for increased performance:

<pre>
--transfers <int>
</pre>

Number of file transfers to run in parallel (default: 4). Depending on the local Network, read and write speeds on the file system, and current load, different values might be best. For large transfers, it is advised to test local performance with different values beforehand.

* In our tests, we observed the best results between 8 and 32.
* For regular use cases, we recommend 16 as the default.
* Values above 64 are not recommended and degrade performance.

<pre>
--multi-thread-streams <int>
</pre>

Number of streams to use for multithreaded downloads (default: 4). Only important on very large files. This will cause multithreaded up/download on chunk-sized bits of the file.

The optimal value is highly specific to the local network and used Hardware. For regular use cases, we recommend 4 as the default.

=== Debugging and Statistics ===
To get updates on current progress, use:
<pre>
--stats
</pre>
Interval between printing stats, e.g. 500ms, 60s, 5m (0 to disable) (default 1m0s).

To get debug information, use:
<pre>
--log-level=DEBUG
--stats-log-level=DEBUG
</pre>

== Troubleshooting ==
# Windows: Adding rclone to the path
#: Needed information: path to the rclone.exe file. If you chose to install via 'winget', the path is "C:\Users\<user>\AppData\Local\Microsoft\WinGet\Packages\Rclone.Rclone_Microsoft.Winget.Source.... . Please look up the exact path.
#:* Option 1: Add the rclone.exe file to a folder that is already in the path. You can move it to "C:\Windows\System32\". Then open a new terminal window and test if the command "rclone config" works.
#:* Option 2: Add the path of the rclone.exe file to your Windows Path variable:
#:*: Open the Start Search and type env. Choose "Edit environment variables"
#:*: Click the "Environment Variables" button.
#:*: Edit the user variables and add the path to your rclone.exe file.

Helix/Login

2026-06-01T14:04:28Z

H Schumacher: Added token deletion step, changed it-service link

= Prerequisites =
* The three [[registration/bwForCluster|bwForCluster registration]] steps are completed and still valid.
* Your IP address is within the [https://www.belwue.de BelWü] network which connects universities and other scientific institutions in Baden-Württemberg. If your computer is in your university network (e.g. at your office), you should be able to connect to bwForCluster Helix without restrictions. If you are outside the BelWü network (e.g. at home), a VPN (virtual private network) connection to your University network must be established first. Please consult the VPN documentation of your university.
* As credentials you need your Helix [[Helix/Login#Username|username]], [[Registration/Password|service password]] and [[Registration/2FA|2FA token]].
* If you encounter any issues, please have a look at the [[Helix/Login#Troubleshooting|Troubleshooting]] section.

= Login to bwForCluster Helix =

Login to bwForCluster Helix is only possible with a Secure Shell (SSH) client for which you must know your bwForCluster Helix credentials and the hostname of the login nodes.
For more general information on SSH clients, visit the [[Registration/Login/Client|SSH clients Guide]].

== Username ==

Your username on bwForCluster Helix consists of a prefix and your local username.
For prefixes please refer to the [[Registration/Login/Username|Username Guide]].

Example: If your local username at your University is <code>ab123</code> and you are a user from Heidelberg University, your username on the cluster is: <code>hd_ab123</code>.

== Hostnames ==

bwForCluster Helix has two login nodes. In general, you should stay with automatic node selection, so that the connections are evenly distributed between the login nodes. To do this, we use so-called DNS round-robin scheduling which takes care of the node balancing. This means, if you open multiple SSH sessions, these sessions may run on different login nodes. Therefore, processes started in one session might not be visible in other sessions.

{| class="wikitable"
! Hostname !! Destination
|-
| '''helix.bwservices.uni-heidelberg.de''' || one of the two login nodes
|}

== Login with SSH command (Linux, Mac, Windows) ==

Most Unix and Unix-like operating systems such as Linux and Mac OS as well as newer versions of MS Windows (10 and 11), have a built-in SSH client provided by the OpenSSH project.
If you want to use the full set of Linux commands on Windows (10 or 11), you can also install the [https://docs.microsoft.com/en-us/windows/wsl/install Windows Subsystem for Linux] (WSL).

For login use one of the following ssh commands in a commandline (i.e. cmd, terminal, PowerShell):

ssh <username>@helix.bwservices.uni-heidelberg.de
ssh -l <username> helix.bwservices.uni-heidelberg.de

To run graphical applications on the cluster, you need to enable X11 forwarding with the <code>-X</code> flag:

ssh -X -l <username> helix.bwservices.uni-heidelberg.de

To make the login process faster, tell the command that no ssh key authentication is used by adding an additional parameter:

ssh -o PubkeyAuthentication=no <username>@helix.bwservices.uni-heidelberg.de

== Login with graphical SSH client (Windows) ==

For Windows we suggest using [[Data_Transfer/Graphical_Clients#MobaXterm|MobaXterm]] for login and file transfer.

Start MobaXterm and fill in the following fields:
<pre>
Remote name : helix.bwservices.uni-heidelberg.de
Specify user name : <username>
Port : 22
</pre>

After that click on 'ok'. Then a terminal will open where you can enter your credentials.

== Login with SSH key ==

To set up a SSH key for your workflow, read [[Registration/SSH|Registering SSH Keys with your Cluster]].
To login by using the ssh key, use the following command:

ssh -o IdentitiesOnly=yes -i <path_to_private_key> <username>@helix.bwservices.uni-heidelberg.de

== Login Example ==

To login to bwForCluster Helix, proceed as follows:
# Login with SSH command or MoabXterm as shown above.
# The system will ask for a one-time password <code>Your OTP</code> (= Smartphone Token / TAN list element/ ...) . Please enter your OTP and confirm it with Enter/Return. The OTP is not displayed when typing. If you do not have a second factor yet, please create one (see [[Registration/2FA]]).
# The system will ask you for your service password <code>Password:</code>. Please enter it and confirm it with Enter/Return. The password is not displayed when typing. If you do not have a service password yet or have forgotten it, please create one (see [[Registration/Password]]).
# You will be greeted by the cluster with the message of the day, followed by a shell.
<pre>
$ ssh -l hd_ab123 helix.bwservices.uni-heidelberg.de
Your OTP:
Password:

********************************************************************************
* *
* Baden-Wuerttemberg HPC Cluster for *
* Structural and Systems Biology, Medical Science, *
* Soft Matter, Computational Humanities, and *
* Mathematics and Computer Science *
* *
* bwForCluster *
* _ _ _ _ *
* | | | | | | (_) *
* | |__| | ___ | | _ __ __ *
* | __ | / _ \ | | | | \ \/ / *
* | | | | | __/ | | | | > < *
* |_| |_| \___| |_| |_| /_/\_\ *
* *
* *
* (xCAT 2.16.4 / RHEL 8.8 / GPFS 5.1.8) *
* *
* *
* bwHPC Wiki : https://wiki.bwhpc.de/e/Helix *
* Ticket System : https://www.bwhpc.de/supportportal *
* Job Monitoring : https://helix-monitoring.bwservices.uni-heidelberg.de *
* E-learning : https://training.bwhpc.de/ *
* -> 'Introduction to bwForCluster Helix' *
* *
********************************************************************************

Last login: ...
[hd_ab123@login ~]$
</pre>

= Allowed Activities on Login Nodes =

{|style="background:#deffee; width:100%;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
To guarantee usability for all users you must not run your compute jobs on the login nodes.
Compute jobs must be submitted as batch jobs.
Any compute job running on the login nodes will be terminated without notice.
Long-running compilation or long-running pre- or post-processing tasks must also be submitted as batch jobs.
|}

The login nodes are the access points to the compute system, your <code>$HOME</code> directory and your workspaces.
These nodes are shared with all users. Hence, your activities on the login nodes are primarily limited to setting up your batch jobs.
Your activities may also be:
* quick compilation of program code or
* quick pre- and post-processing of results from batch jobs.

We advise to use [[Helix/Slurm#Interactive_Jobs|interactive batch jobs]] for compute and memory intensive compilation and pre- and post-processing tasks.

= Related Information =

* If you want to register a new token for the two factor authentication (2FA), consult the [[Registration/2FA|2FA Guide]].
* If you want to de-register, consult the [[Registration/Deregistration|De-registration Guide]].
* If you need an SSH key for your workflow, read [[Registration/SSH|Registering SSH Keys with your Cluster]].
* Configuring your shell: [[.bashrc Do's and Don'ts]]

= Troubleshooting =

'''Login Problems'''

If you encounter login problems, please double check the prerequisites. If those are valid, it is fastest to first check the following points before contacting the support at the [https://www.bwhpc.de/supportportal.php|bwhpc Suppport Portal].
If there are known issues with the cluster, we'll inform you via e-mail or in the message of the day at the cluster.

* Make sure to not use LAN and WLAN at the same time to prevent connection problems.
* Do [[Registration/bwForCluster/Helix#Troubleshooting_with_the_Help_of_bwServices | troubleshooting with bwServices]].

'''Lost Token'''

# To reset your token you have to (virtually) visit the IT Service at the University of Heidelberg to validate your identity. You can find the information for a virtual or in person visit in the "How to contact us" section here: https://www.urz.uni-heidelberg.de/en/support/it-service. It is recommended to use the Chrome browser for doing the video call.
# Please have an official identification ready (e.g. Führerschein / Personalausweis) and mention that you want a reset of your Helix 2FA token. It is important to emphasize that the token reset is for bwForCluster Helix to avoid confusion with the token that is specific to members/students of the university of Heidelberg.
# After the IT Service deactivated the token, you can delete the token yourself, reload the page and create a new one.
Hint: To be on the safe side, it is advised to create a [[Registration/2FA#Backup_TAN_List|backup TAN list]] additionally to the smartphone token.

Data Transfer/Rclone

2026-05-31T13:42:21Z

H Schumacher: corrected information

[https://rclone.org/docs/ Rclone] is a command line tool to manage files on remote systems (e.g. high performance clusters, data and cloud storage systems, archiving services). 
Rclone either synchronizes in one direction only or its mounting functionality is used with <code>rclone mount</code>. 
Data can be piped between two completely remote locations. When moving data within the same system and the data transfer protocol allows for server side copy, no local download is necessary. 
One advantage is that the transfer is multithreaded and it operates on a file level basis.
'''Caution:''' When using Rclone with 2FA it is necessary to connect via ssh key instead of a password.

== Installation ==

Rclone is a Go program and comes as a single binary file.

# Download the relevant binary.
# Extract the <code>rclone</code> executable (<code>rclone.exe</code>).
# You can use the executables without further installation. For easy use, it is recommended to add the binary to your PATH environment variable. Information on how to do this can be found below.

Detailed information regarding different operating systems can be found here:

* Installation on [https://rclone.org/install/#windows Windows]
* Installation on [https://rclone.org/install/#macos macOS]
** If Rclone shall be used together with sftp, the [[Data_Transfer/SSHFS#Installation | sshfs installation]] instructions must be followed after installing Rclone.
* Installation on [https://rclone.org/install/#script-installation Linux]

== Usage Rclone ==

To use Rclone you have to define a config file. Afterwards you can connect by using the name of your configured connections.

=== Configure Remote ===

Before you can start using Rclone, you need to set up a remote. This means to configure a specific connection by providing authentication information, the network protocol that you want to use and a name for this configuration so that you can use it later on.

To configure a remote for a specific service, you need the following information:

* <code><remotehost></code>
* <code><username></code>
* <code><servicePassword></code>

Furthermore, you have to decide on:

* <code>network protocol</code> (for example webDAV, smb, sftp)
* <code>remote-name</code> (for example you can use the name of the service you want to connect to)

You have three different options to set up a new remote as described in the following sections. It's enough to choose one of those.

'''Oneliner''' 

Open a terminal and define all parameters in one command. If a ssh key shall be used instead of a password, it might be easier to adjust the config file directly as described in the next section.
<syntaxhighlight lang="bash"># smb
rclone config create <remote-name> smb host=<remotehost> user=<username> domain=<domain> pass=<password> --obscure
# sftp
rclone config create <remote-name> sftp host=<remotehost> user=<username> pass=<password> --obscure
# webdav
rclone config create <remote-name> webdav url=<remotehost> user=<username> pass=<password> --obscure
</syntaxhighlight>

'''Adjust Config File''' 
<syntaxhighlight lang="bash">
# Make sure that a config file exists. Access rights for the config file are set to 600.
rclone config touch
# Get the location of the file:
rclone config file
</syntaxhighlight>
Open the file and use one of the following snippets as template for your connection:
<syntaxhighlight lang="bash">[<remote-name>]
type = smb
host = <hostname>
user = <userID>
domain = <e.g. BWSERVICESAD>

[<remote-name>]
type = webdav
url = <hostURL>
vendor = other
user = <userID>

[<remote-name>]
type = sftp
host = <hostname>
user = <userID>
key_use_agent = false

[<remote-name-ssh-key-version>]
type = sftp
host = <hostname>
user = <userID>
key_file = ~/.ssh/id_ed25519
pubkey_file = ~/.ssh/id_ed25519.pub
key_use_agent = true
shell_type = none
</syntaxhighlight>
To add the password, please use the following command. Make sure to keep the prepended space so that the command is not saved in your command history.
<syntaxhighlight> rclone config update <remote-name> pass=<password> --obscure</syntaxhighlight>

'''Interactive Setup''' 

Execute:
<syntaxhighlight>rclone config</syntaxhighlight>
This will guide you through an interactive setup process. It's quite helpful for checking out which options there are and what the config file looks like after setting values that deviate from the default values. You can find detailed instructions at the website:

* [https://rclone.org/webdav/ Connect via webdav]
* [https://rclone.org/smb/ Connect via smb]
* [https://rclone.org/sftp/ Connect via sftp]

=== Use Remote ===

To see all configured remotes:
<syntaxhighlight lang="bash">rclone config
# Exit with 'q'.
</syntaxhighlight>

The syntax to use Rclone is like this:

<pre>rclone [options] subcommand <parameters> <parameters...>
</pre>
List all elements in the folder XX:
<syntaxhighlight lang="bash">rclone lsf <remote-name>:XX
# List elements from subfolders as well:
rclone lsf --max-depth 2 <remote-name>:XX
</syntaxhighlight>
Copies /local/path to the remote path

<pre>rclone copy </local/path> <remote-name>:<remote/path>
</pre>
Copies fom remote path to /local/path

<pre>rclone copy <remote-name>:<remote/path> </local/path>
</pre>
Moves the contents of the source directory to the destination directory.

<pre>rclone move <remote-name>:<source/path> <remote-name>:<destination/path>
</pre>
More subcommands can be found [https://rclone.org/docs/#subcommands here].

== Usage Rclone Mount ==

Before you can follow the instructions in this chapter, you need to have set up a [[Data_Transfer/Rclone#Usage_Rclone | remote]].
More detailed information on how to use rclone mount can be found [https://rclone.org/commands/rclone_mount/ here].

=== Windows ===

To run rclone mount on Windows, you will need to [https://winfsp.dev/rel/ download and install WinFsp] first.

<syntaxhighlight lang="python"># mount under drive letter X (or any other free letter)
rclone mount --vfs-cache-mode full <remote-name>:<path/to/remote/files> X:
# or provide the path to a nonexisting folder:
rclone mount --vfs-cache-mode full <remote-name>:<path/to/remote/files> <C:\path\parentDir\nonexistingFoldername></syntaxhighlight>
To unmount, the command can be stopped in the terminal with the key combination CTRL+C. Alternatively, a mounted drive can be unmounted by making a right click on the drive name in the file explorer and choose "Eject". 
In contrast to Linux/Mac, there is no background mode.

=== MacOS & Linux ===

You can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the <code>--daemon</code> flag to force background mode. If this doesn't work, you can put an <code>&</code> at the end of the command instead.

Create an empty directory on your local machine and then execute

<syntaxhighlight lang="bash"># to mount the root folder:
rclone mount --vfs-cache-mode full <remote-name>: /path/to/empty/folder
# to mount a subfolder:
rclone mount --vfs-cache-mode full <remote-name>:folderX/folderY /path/to/empty/folder
# to unmount:
fusermount -uz /path/to/mounted/folder </syntaxhighlight>

== Best Practices ==

Rclone has a lot of useful options.

=== Performance ===

To be able to utilize a larger bandwidth, it is helpful to add the following options for increased performance:

<pre>
--transfers <int>
</pre>

Number of file transfers to run in parallel (default: 4). Depending on the local Network, read and write speeds on the file system, and current load, different values might be best. For large transfers, it is advised to test local performance with different values beforehand.

* In our tests, we observed the best results between 8 and 32.
* For regular use cases, we recommend 16 as the default.
* Values above 64 are not recommended and degrade performance.

<pre>
--multi-thread-streams <int>
</pre>

Number of streams to use for multithreaded downloads (default: 4). Only important on very large files. This will cause multithreaded up/download on chunk-sized bits of the file.

The optimal value is highly specific to the local network and used Hardware. For regular use cases, we recommend 4 as the default.

=== Debugging and Statistics ===
To get updates on current progress, use:
<pre>
--stats
</pre>
Interval between printing stats, e.g. 500ms, 60s, 5m (0 to disable) (default 1m0s).

To get debug information, use:
<pre>
--log-level=DEBUG
--stats-log-level=DEBUG
</pre>

SDS@hd/Access

2026-05-27T16:06:37Z

H Schumacher: added 'domain' as additional bullet point to avoid confusion

This page provides an overview on how to access data served by SDS@hd. To get an introduction to data transfer in general, see [[Data_Transfer|data transfer]].

'''Notation:''' Please replace all placeholder contents within guillemets <code>< ></code> with the actual value. For example, replace ''<name_of_my_dog>'' with ''Fluffy'' .

== Prerequisites ==

* You need to be [[SDS@hd/Registration|registered]].
* You need to be in the belwue-Network. This means you have to use the VPN Service of your HomeOrganization, if you want to access SDS@hd from outside the bwHPC-Clusters (e.g. via eduroam or from your personal notebook).

== Needed Information, independent of the chosen tool ==

* '''Username:''' You can look it up under your user data at [https://bwservices.uni-heidelberg.de/user/index.xhtml bwServices]. The username is ''<localPrimaryGroup>_<eduPersonPrincipalName>'' . (It is the same as for the bwHPC Clusters. Example: ''hd_ab123''.)
* '''Password:''' The Service Password that you set at bwServices in the [[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service|registration step]].
* '''SV-Acronym:''' Use the lower case version of the acronym for all access options.
* '''Hostname:''' The hostname depends on the chosen network protocol:
** For [[Data_Transfer/SSHFS|SSHFS]] and [[Data_Transfer/SFTP|SFTP]]: ''lsdf02-sshfs.urz.uni-heidelberg.de''
** For [[SDS@hd/Access/SMB|SMB]] and [[SDS@hd/Access/NFS|NFS]]: ''lsdf02.urz.uni-heidelberg.de''
** For [[Data_Transfer/WebDAV|WebDAV]] the url is: ''https://lsdf02-webdav.urz.uni-heidelberg.de''
* '''Domain:''' The domain is ''BWSERVICESAD'' (needed for smb and nfs connections).

== Recommended Setup ==
The following graphic shows the recommended way for accessing SDS@hd via Windows/Mac/Linux. The table provides an overview of the most important access options and links to the related pages. 
If you have various use cases, it is recommended to use [[Data_Transfer/Rclone|Rclone]]. You can copy, sync and mount with it. Thanks to its multithreading capability Rclone is a good fit for transferring big data. 
For an overview of all connection possibilities, please have a look at [[Data_Transfer/All_Data_Transfer_Routes|all data transfer routes]].

[[File:Data_transfer_diagram_simple.jpg|center|500px]]
Figure 1: SDS@hd main transfer routes

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
!
! Use Case
! Windows
! Mac
! Linux
! Possible Bandwith
! Firewall Ports
|-
| [[Data_Transfer/Rclone|Rclone]] + <protocol>
| copy, sync and mount, multithreading
| ✓
| ✓
| ✓
| depends on used protocol
| depends on used protocol
|-
| [[SDS@hd/Access/SMB|SMB]]
| mount as network drive in file explorer or usage via Rclone
| [[SDS@hd/Access/SMB#Windows|✓]]
| [[SDS@hd/Access/SMB#Mac|✓]]
| [[SDS@hd/Access/SMB#Linux|✓]]
| up to 40 Gbit/sec
| 139 (netbios), 135 (rpc), 445 (smb)
|-
| [[Data_Transfer/WebDAV|WebDAV]]
| go to solution for restricted networks
| [✓]
| ✓
| ✓
| up to 100GBit/sec
| 80 (http), 443 (https)
|- style="vertical-align:middle;"
| [[Data_Transfer/Graphical_Clients#MobaXterm|MobaXterm]]
| Graphical User Interface (GUI)
| [[Data_Transfer/Graphical_Clients#MobaXterm|✓]]
| ☓
| ☓
| see sftp
| see sftp
|- style="vertical-align:middle;"
| [[SDS@hd/Access/NFS|NFS]]
| mount for multi-user environments
| ☓
| ☓
| [[SDS@hd/Access/NFS|✓]]
| up to 40 Gbit/sec
| -
|- style="vertical-align:middle;"
| [[Data_Transfer/SSHFS|SSHFS]]
| mount, needs stable internet connection
| ☓
| [[Data_Transfer/SSHFS#MacOS_&_Linux|✓]]
| [[Data_Transfer/SSHFS#MacOS_&_Linux|✓]]
| see sftp
| see sftp
|- style="vertical-align:middle;"
| [[Data_Transfer/SFTP|SFTP]]
| interactive shell, better usability when used together with Rclone
| [[Data_Transfer/SFTP#Windows|✓]]
| [[Data_Transfer/SFTP#MacOS_&_Linux|✓]]
| [[Data_Transfer/SFTP#MacOS_&_Linux|✓]]
| up to 40 Gbit/sec
| 22 (ssh)
|}
Table 1: SDS@hd transfer routes

=== Access from a bwHPC Cluster ===

'''bwUniCluster''' 
You can't mount to your $HOME directory but you can create a mount under $TMPDIR by following the instructions for [[Data_Transfer/Rclone#Usage_Rclone_Mount | Rclone mount]]. It is advised to wait a couple of seconds (<code>sleep 5</code>) before trying to use the mounted directory.

'''bwForCluster Helix''' 
You can directly access your storage space under ''/mnt/sds-hd/'' on all login and compute nodes.

'''bwForCluster BinAC 2''' 
You can directly access your storage space under ''/mnt/sds-hd/'' on all login and compute nodes. The prerequisites are:
* The SV responsible has enabled the SV on BinAC 2 once by writing to [mailto:sds-hd-support@urz.uni-heidelberg.de sds-hd-support@urz.uni-heidelberg.de]
* You have a valid kerberos ticket, which can be fetched with <code>kinit <userID></code>

'''Other''' 
You can mount your SDS@hd SV on the cluster yourself by using [[Data_Transfer/Rclone | Rclone]] with the [[Data_Transfer/Rclone#Usage_Rclone_Mount | Rclone mount]] command. As transfer protocol you can use WebDAV or sftp. For a full overview please have a look at [[Data_Transfer/All_Data_Transfer_Routes | All Data Transfer Routes]].

=== Access via Webbrowser (read-only) ===

Visit [https://lsdf02-webdav.urz.uni-heidelberg.de/ lsdf02-webdav.urz.uni-heidelberg.de] and login with your SDS@hd username and service password. Here you can get an overview of the data in your "Speichervorhaben" and download single files. To be able to do more, like moving data, uploading new files, or downloading complete folders, a suitable client is needed as described above.

== Best Practices ==

* '''Managing access rights'''
** When the SV is mounted on Windows, access rights can be adjusted in the file/folder properties menu. (Users from Heidelberg without Windows can use the [https://www.urz.uni-heidelberg.de/de/service-katalog/desktop-und-arbeitsplatz/windows-terminalserver Windows terminal server]).
** bwForCluster Helix users can change the access rights via Helix by using [[Workspace#Regular_Unix_Permissions | unix permissions]] or [[Workspace#ACLs:_Access_Control_Lists | access control lists]]. On non native mounts ACL changes won't work.
** Additionally to the already mentioned options, the SVV can take over ownership of files by opening a [[Data_Transfer/SFTP|SFTP]] shell and running <code>chown -R <userID> <path/to/folder></code> .

* '''Multiuser environment''' → Use [[SDS@hd/Access/NFS|NFS]]

== Troubleshooting ==

Maintance windows and known issues are communicated via the email list or the News section at the SDS@hd start page in the wiki.

* '''Issue:''' The credentials aren't accepted
*: Check if your credentials work in general by trying the access via webbrowser: [https://lsdf02-webdav.urz.uni-heidelberg.de/].
*: If this doesn't work:
*:: → [[Registration/Login/Username| Check your Username]]
*:: → [[Registration/bwForCluster/Helix#Troubleshooting_with_the_Help_of_bwServices | Troubleshooting with bwServices]]
* '''Other Issue'''
** If available, follow the troubleshooting guide of your specific connection method.
** Make sure to not use LAN and WLAN at the same time to prevent connection problems.
** If you have an institutional account, make sure to be a fully active member of your institution.
If these suggestions didn't help, write to the [mailto:sds-hd-support@urz.uni-heidelberg.de support]. Provide the following information:
* Your operating system
* Does the access via webbrowser work?
*: If yes, provide us with detailed information on how you tried to access your SV (used access method, username, ...).

Data Transfer/Rclone

2026-05-27T16:01:30Z

H Schumacher: improved Windows instructions

[https://rclone.org/docs/ Rclone] is a command line tool to manage files on remote systems (e.g. cloud storage systems). Rclone either synchronizes in one direction only or its mounting functionality is used with <code>rclone mount</code>. Data can be piped between two completely remote locations, sometimes without local download. One advantage is that the transfer is multithreaded and it operates on a file level basis.
'''Caution:''' You can't use Rclone with 2FA.

== Installation ==

Rclone is a Go program and comes as a single binary file.

# Download the relevant binary.
# Extract the <code>rclone</code> executable, <code>rclone.exe</code> on Windows, from the archive.
# You can use the executables without further installation. For easy use, it is recommended to add the binary to your PATH environment variable. Information on how to do this can be found below.

Detailed information regarding different operating systems can be found here:

* Installation on [https://rclone.org/install/#windows Windows]
* Installation on [https://rclone.org/install/#macos macOS]
** If Rclone shall be used together with sftp, the [[Data_Transfer/SSHFS#Installation | sshfs installation]] instructions must be followed after installing Rclone.
* Installation on [https://rclone.org/install/#script-installation Linux]

== Usage Rclone ==

To use Rclone you have to define a config file. Afterwards you can connect by using the name of your configured connections.

=== Configure Remote ===

Before you can start using Rclone, you need to set up a remote. This means to configure a specific connection by providing authentication information, the network protocol that you want to use and a name for this configuration so that you can use it later on.

To configure a remote for a specific service, you need the following information:

* <code><remotehost></code>
* <code><username></code>
* <code><servicePassword></code>

Furthermore, you have to decide on:

* <code>network protocol</code> (for example webDAV, smb, sftp)
* <code>remote-name</code> (for example you can use the name of the service you want to connect to)

You have three different options to set up a new remote as described in the following sections. It's enough to choose one of those.

'''Oneliner''' 

Open a terminal and define all parameters in one command. If a ssh key shall be used instead of a password, it might be easier to adjust the config file directly as described in the next section.
<syntaxhighlight lang="bash"># smb
rclone config create <remote-name> smb host=<remotehost> user=<username> domain=<domain> pass=<password> --obscure
# sftp
rclone config create <remote-name> sftp host=<remotehost> user=<username> pass=<password> --obscure
# webdav
rclone config create <remote-name> webdav url=<remotehost> user=<username> pass=<password> --obscure
</syntaxhighlight>

'''Adjust Config File''' 
<syntaxhighlight lang="bash">
# Make sure that a config file exists. Access rights for the config file are set to 600.
rclone config touch
# Get the location of the file:
rclone config file
</syntaxhighlight>
Open the file and use one of the following snippets as template for your connection:
<syntaxhighlight lang="bash">[<remote-name>]
type = smb
host = <hostname>
user = <userID>
domain = <e.g. BWSERVICESAD>

[<remote-name>]
type = webdav
url = <hostURL>
vendor = other
user = <userID>

[<remote-name>]
type = sftp
host = <hostname>
user = <userID>
key_use_agent = false

[<remote-name-ssh-key-version>]
type = sftp
host = <hostname>
user = <userID>
key_file = ~/.ssh/id_ed25519
pubkey_file = ~/.ssh/id_ed25519.pub
key_use_agent = true
shell_type = none
</syntaxhighlight>
To add the password, please use the following command. Make sure to keep the prepended space so that the command is not saved in your command history.
<syntaxhighlight> rclone config update <remote-name> pass=<password> --obscure</syntaxhighlight>

'''Interactive Setup''' 

Execute:
<syntaxhighlight>rclone config</syntaxhighlight>
This will guide you through an interactive setup process. It's quite helpful for checking out which options there are and what the config file looks like after setting values that deviate from the default values. You can find detailed instructions at the website:

* [https://rclone.org/webdav/ Connect via webdav]
* [https://rclone.org/smb/ Connect via smb]
* [https://rclone.org/sftp/ Connect via sftp]

=== Use Remote ===

To see all configured remotes:
<syntaxhighlight lang="bash">rclone config
# Exit with 'q'.
</syntaxhighlight>

The syntax to use Rclone is like this:

<pre>rclone [options] subcommand <parameters> <parameters...>
</pre>
List all elements in the folder XX:
<syntaxhighlight lang="bash">rclone lsf <remote-name>:XX
# List elements from subfolders as well:
rclone lsf --max-depth 2 <remote-name>:XX
</syntaxhighlight>
Copies /local/path to the remote path

<pre>rclone copy </local/path> <remote-name>:<remote/path>
</pre>
Copies fom remote path to /local/path

<pre>rclone copy <remote-name>:<remote/path> </local/path>
</pre>
Moves the contents of the source directory to the destination directory.

<pre>rclone move <remote-name>:<source/path> <remote-name>:<destination/path>
</pre>
More subcommands can be found [https://rclone.org/docs/#subcommands here].

== Usage Rclone Mount ==

Before you can follow the instructions in this chapter, you need to have set up a [[Data_Transfer/Rclone#Usage_Rclone | remote]].
More detailed information on how to use rclone mount can be found [https://rclone.org/commands/rclone_mount/ here].

=== Windows ===

To run rclone mount on Windows, you will need to [https://winfsp.dev/rel/ download and install WinFsp] first.

<syntaxhighlight lang="python"># mount under drive letter X (or any other free letter)
rclone mount --vfs-cache-mode full <remote-name>:<path/to/remote/files> X:
# or provide the path to a nonexisting folder:
rclone mount --vfs-cache-mode full <remote-name>:<path/to/remote/files> <C:\path\parentDir\nonexistingFoldername></syntaxhighlight>
To unmount, the command can be stopped in the terminal with the key combination CTRL+C. Alternatively, a mounted drive can be unmounted by making a right click on the drive name in the file explorer and choose "Eject". 
In contrast to Linux/Mac, there is no background mode.

=== MacOS & Linux ===

You can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the <code>--daemon</code> flag to force background mode. If this doesn't work, you can put an <code>&</code> at the end of the command instead.

Create an empty directory on your local machine and then execute

<syntaxhighlight lang="bash"># to mount the root folder:
rclone mount --vfs-cache-mode full <remote-name>: /path/to/empty/folder
# to mount a subfolder:
rclone mount --vfs-cache-mode full <remote-name>:folderX/folderY /path/to/empty/folder
# to unmount:
fusermount -uz /path/to/mounted/folder </syntaxhighlight>

== Best Practices ==

Rclone has a lot of useful options.

=== Performance ===

To be able to utilize a larger bandwidth, it is helpful to add the following options for increased performance:

<pre>
--transfers <int>
</pre>

Number of file transfers to run in parallel (default: 4). Depending on the local Network, read and write speeds on the file system, and current load, different values might be best. For large transfers, it is advised to test local performance with different values beforehand.

* In our tests, we observed the best results between 8 and 32.
* For regular use cases, we recommend 16 as the default.
* Values above 64 are not recommended and degrade performance.

<pre>
--multi-thread-streams <int>
</pre>

Number of streams to use for multithreaded downloads (default: 4). Only important on very large files. This will cause multithreaded up/download on chunk-sized bits of the file.

The optimal value is highly specific to the local network and used Hardware. For regular use cases, we recommend 4 as the default.

=== Debugging and Statistics ===
To get updates on current progress, use:
<pre>
--stats
</pre>
Interval between printing stats, e.g. 500ms, 60s, 5m (0 to disable) (default 1m0s).

To get debug information, use:
<pre>
--log-level=DEBUG
--stats-log-level=DEBUG
</pre>

Data Transfer/Rclone

2026-05-27T09:44:49Z

H Schumacher: fixed typo

[https://rclone.org/docs/ Rclone] is a command line tool to manage files on remote systems (e.g. cloud storage systems). Rclone either synchronizes in one direction only or its mounting functionality is used with <code>rclone mount</code>. Data can be piped between two completely remote locations, sometimes without local download. One advantage is that the transfer is multithreaded and it operates on a file level basis.
'''Caution:''' You can't use Rclone with 2FA.

== Installation ==

Rclone is a Go program and comes as a single binary file.

# Download the relevant binary.
# Extract the <code>rclone</code> executable, <code>rclone.exe</code> on Windows, from the archive.
# You can use the executables without further installation. For easy use, it is recommended to add the binary to your PATH environment variable. Information on how to do this can be found below.

Detailed information regarding different operating systems can be found here:

* Installation on [https://rclone.org/install/#windows Windows]
* Installation on [https://rclone.org/install/#macos macOS]
** If Rclone shall be used together with sftp, the [[Data_Transfer/SSHFS#Installation | sshfs installation]] instructions must be followed after installing Rclone.
* Installation on [https://rclone.org/install/#script-installation Linux]

== Usage Rclone ==

To use Rclone you have to define a config file. Afterwards you can connect by using the name of your configured connections.

=== Configure Remote ===

Before you can start using Rclone, you need to set up a remote. This means to configure a specific connection by providing authentication information, the network protocol that you want to use and a name for this configuration so that you can use it later on.

To configure a remote for a specific service, you need the following information:

* <code><remotehost></code>
* <code><username></code>
* <code><servicePassword></code>

Furthermore, you have to decide on:

* <code>network protocol</code> (for example webDAV, smb, sftp)
* <code>remote-name</code> (for example you can use the name of the service you want to connect to)

You have three different options to set up a new remote as described in the following sections. It's enough to choose one of those.

'''Oneliner''' 

Open a terminal and define all parameters in one command. If a ssh key shall be used instead of a password, it might be easier to adjust the config file directly as described in the next section.
<syntaxhighlight lang="bash"># smb
rclone config create <remote-name> smb host=<remotehost> user=<username> domain=<domain> pass=<password> --obscure
# sftp
rclone config create <remote-name> sftp host=<remotehost> user=<username> pass=<password> --obscure
# webdav
rclone config create <remote-name> webdav url=<remotehost> user=<username> pass=<password> --obscure
</syntaxhighlight>

'''Adjust Config File''' 
<syntaxhighlight lang="bash">
# Make sure that a config file exists. Access rights for the config file are set to 600.
rclone config touch
# Get the location of the file:
rclone config file
</syntaxhighlight>
Open the file and use one of the following snippets as template for your connection:
<syntaxhighlight lang="bash">[<remote-name>]
type = smb
host = <hostname>
user = <userID>
domain = <e.g. BWSERVICESAD>

[<remote-name>]
type = webdav
url = <hostURL>
vendor = other
user = <userID>

[<remote-name>]
type = sftp
host = <hostname>
user = <userID>
key_use_agent = false

[<remote-name-ssh-key-version>]
type = sftp
host = <hostname>
user = <userID>
key_file = ~/.ssh/id_ed25519
pubkey_file = ~/.ssh/id_ed25519.pub
key_use_agent = true
shell_type = none
</syntaxhighlight>
To add the password, please use the following command. Make sure to keep the prepended space so that the command is not saved in your command history.
<syntaxhighlight> rclone config update <remote-name> pass=<password> --obscure</syntaxhighlight>

'''Interactive Setup''' 

Execute:
<syntaxhighlight>rclone config</syntaxhighlight>
This will guide you through an interactive setup process. It's quite helpful for checking out which options there are and what the config file looks like after setting values that deviate from the default values. You can find detailed instructions at the website:

* [https://rclone.org/webdav/ Connect via webdav]
* [https://rclone.org/smb/ Connect via smb]
* [https://rclone.org/sftp/ Connect via sftp]

=== Use Remote ===

To see all configured remotes:
<syntaxhighlight lang="bash">rclone config
# Exit with 'q'.
</syntaxhighlight>

The syntax to use Rclone is like this:

<pre>rclone [options] subcommand <parameters> <parameters...>
</pre>
List all elements in the folder XX:
<syntaxhighlight lang="bash">rclone lsf <remote-name>:XX
# List elements from subfolders as well:
rclone lsf --max-depth 2 <remote-name>:XX
</syntaxhighlight>
Copies /local/path to the remote path

<pre>rclone copy </local/path> <remote-name>:<remote/path>
</pre>
Copies fom remote path to /local/path

<pre>rclone copy <remote-name>:<remote/path> </local/path>
</pre>
Moves the contents of the source directory to the destination directory.

<pre>rclone move <remote-name>:<source/path> <remote-name>:<destination/path>
</pre>
More subcommands can be found [https://rclone.org/docs/#subcommands here].

== Usage Rclone Mount ==

Before you can follow the instructions in this chapter, you need to have set up a [[Data_Transfer/Rclone#Usage_Rclone | remote]].
More detailed information on how to use rclone mount can be found [https://rclone.org/commands/rclone_mount/ here].

=== Windows ===

To run rclone mount on Windows, you will need to [https://winfsp.dev/rel/ download and install WinFsp]. To mount on drive letter X or a nonexistent subdirectory, use:

<pre>rclone mount <remote-name>:path/to/files X:
rclone mount <remote-name>:path/to/files C:\path\parent\mount</pre>
In contrast to Linux/Mac, there is no background mode.

=== MacOS & Linux ===

You can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the <code>--daemon</code> flag to force background mode. If this doesn't work, you can put an <code>&</code> at the end of the command instead.

Create an empty directory on your local machine and then execute

<pre># to mount the root folder:
rclone mount --vfs-cache-mode full <remote-name>: /path/to/empty/folder
# to mount a subfolder:
rclone mount --vfs-cache-mode full <remote-name>:folderX/folderY /path/to/empty/folder
# to unmount:
fusermount -uz /path/to/mounted/folder </pre>

== Best Practices ==

Rclone has a lot of useful options.

=== Performance ===

To be able to utilize a larger bandwidth, it is helpful to add the following options for increased performance:

<pre>
--transfers <int>
</pre>

Number of file transfers to run in parallel (default: 4). Depending on the local Network, read and write speeds on the file system, and current load, different values might be best. For large transfers, it is advised to test local performance with different values beforehand.

* In our tests, we observed the best results between 8 and 32.
* For regular use cases, we recommend 16 as the default.
* Values above 64 are not recommended and degrade performance.

<pre>
--multi-thread-streams <int>
</pre>

Number of streams to use for multithreaded downloads (default: 4). Only important on very large files. This will cause multithreaded up/download on chunk-sized bits of the file.

The optimal value is highly specific to the local network and used Hardware. For regular use cases, we recommend 4 as the default.

=== Debugging and Statistics ===
To get updates on current progress, use:
<pre>
--stats
</pre>
Interval between printing stats, e.g. 500ms, 60s, 5m (0 to disable) (default 1m0s).

To get debug information, use:
<pre>
--log-level=DEBUG
--stats-log-level=DEBUG
</pre>

Data Transfer/Rclone

2026-05-18T16:11:02Z

H Schumacher: changed lsd to lsf

[https://rclone.org/docs/ Rclone] is a command line tool to manage files on remote systems (e.g. cloud storage systems). Rclone either synchronizes in one direction only or its mounting functionality is used with <code>rclone mount</code>. Data can be piped between two completely remote locations, sometimes without local download. One advantage is that the transfer is multithreaded and it operates on a file level basis.
'''Caution:''' You can't use Rclone with 2FA.

== Installation ==

Rclone is a Go program and comes as a single binary file.

# Download the relevant binary.
# Extract the <code>rclone</code> executable, <code>rclone.exe</code> on Windows, from the archive.
# You can use the executables without further installation. For easy use, it is recommended to add the binary to your PATH environment variable. Information on how to do this can be found below.

Detailed information regarding different operating systems can be found here:

* Installation on [https://rclone.org/install/#windows Windows]
* Installation on [https://rclone.org/install/#macos macOS]
** If Rclone shall be used together with sftp, the [[https://wiki.bwhpc.de/e/Data_Transfer/SSHFS#Installation | sshfs installation]] instructions must be followed after installing Rclone.
* Installation on [https://rclone.org/install/#script-installation Linux]

== Usage Rclone ==

To use Rclone you have to define a config file. Afterwards you can connect by using the name of your configured connections.

=== Configure Remote ===

Before you can start using Rclone, you need to set up a remote. This means to configure a specific connection by providing authentication information, the network protocol that you want to use and a name for this configuration so that you can use it later on.

To configure a remote for a specific service, you need the following information:

* <code><remotehost></code>
* <code><username></code>
* <code><servicePassword></code>

Furthermore, you have to decide on:

* <code>network protocol</code> (for example webDAV, smb, sftp)
* <code>remote-name</code> (for example you can use the name of the service you want to connect to)

You have three different options to set up a new remote as described in the following sections. It's enough to choose one of those.

'''Oneliner''' 

Open a terminal and define all parameters in one command. If a ssh key shall be used instead of a password, it might be easier to adjust the config file directly as described in the next section.
<syntaxhighlight lang="bash"># smb
rclone config create <remote-name> smb host=<remotehost> user=<username> domain=<domain> pass=<password> --obscure
# sftp
rclone config create <remote-name> sftp host=<remotehost> user=<username> pass=<password> --obscure
# webdav
rclone config create <remote-name> webdav url=<remotehost> user=<username> pass=<password> --obscure
</syntaxhighlight>

'''Adjust Config File''' 
<syntaxhighlight lang="bash">
# Make sure that a config file exists. Access rights for the config file are set to 600.
rclone config touch
# Get the location of the file:
rclone config file
</syntaxhighlight>
Open the file and use one of the following snippets as template for your connection:
<syntaxhighlight lang="bash">[<remote-name>]
type = smb
host = <hostname>
user = <userID>
domain = <e.g. BWSERVICESAD>

[<remote-name>]
type = webdav
url = <hostURL>
vendor = other
user = <userID>

[<remote-name>]
type = sftp
host = <hostname>
user = <userID>
key_use_agent = false

[<remote-name-ssh-key-version>]
type = sftp
host = <hostname>
user = <userID>
key_file = ~/.ssh/id_ed25519
pubkey_file = ~/.ssh/id_ed25519.pub
key_use_agent = true
shell_type = none
</syntaxhighlight>
To add the password, please use the following command. Make sure to keep the prepended space so that the command is not saved in your command history.
<syntaxhighlight> rclone config update <remote-name> pass=<password> --obscure</syntaxhighlight>

'''Interactive Setup''' 

Execute:
<syntaxhighlight>rclone config</syntaxhighlight>
This will guide you through an interactive setup process. It's quite helpful for checking out which options there are and what the config file looks like after setting values that deviate from the default values. You can find detailed instructions at the website:

* [https://rclone.org/webdav/ Connect via webdav]
* [https://rclone.org/smb/ Connect via smb]
* [https://rclone.org/sftp/ Connect via sftp]

=== Use Remote ===

To see all configured remotes:
<syntaxhighlight lang="bash">rclone config
# Exit with 'q'.
</syntaxhighlight>

The syntax to use Rclone is like this:

<pre>rclone [options] subcommand <parameters> <parameters...>
</pre>
List all elements in the folder XX:
<syntaxhighlight lang="bash">rclone lsf <remote-name>:XX
# List elements from subfolders as well:
rclone lsf --max-depth 2 <remote-name>:XX
</syntaxhighlight>
Copies /local/path to the remote path

<pre>rclone copy </local/path> <remote-name>:<remote/path>
</pre>
Copies fom remote path to /local/path

<pre>rclone copy <remote-name>:<remote/path> </local/path>
</pre>
Moves the contents of the source directory to the destination directory.

<pre>rclone move <remote-name>:<source/path> <remote-name>:<destination/path>
</pre>
More subcommands can be found [https://rclone.org/docs/#subcommands here].

== Usage Rclone Mount ==

Before you can follow the instructions in this chapter, you need to have set up a [[Data_Transfer/Rclone#Usage_Rclone | remote]].
More detailed information on how to use rclone mount can be found [https://rclone.org/commands/rclone_mount/ here].

=== Windows ===

To run rclone mount on Windows, you will need to [https://winfsp.dev/rel/ download and install WinFsp]. To mount on drive letter X or a nonexistent subdirectory, use:

<pre>rclone mount <remote-name>:path/to/files X:
rclone mount <remote-name>:path/to/files C:\path\parent\mount</pre>
In contrast to Linux/Mac, there is no background mode.

=== MacOS & Linux ===

You can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the <code>--daemon</code> flag to force background mode. If this doesn't work, you can put an <code>&</code> at the end of the command instead.

Create an empty directory on your local machine and then execute

<pre># to mount the root folder:
rclone mount --vfs-cache-mode full <remote-name>: /path/to/empty/folder
# to mount a subfolder:
rclone mount --vfs-cache-mode full <remote-name>:folderX/folderY /path/to/empty/folder
# to unmount:
fusermount -uz /path/to/mounted/folder </pre>

== Best Practices ==

Rclone has a lot of useful options.

=== Performance ===

To be able to utilize a larger bandwidth, it is helpful to add the following options for increased performance:

<pre>
--transfers <int>
</pre>

Number of file transfers to run in parallel (default: 4). Depending on the local Network, read and write speeds on the file system, and current load, different values might be best. For large transfers, it is advised to test local performance with different values beforehand.

* In our tests, we observed the best results between 8 and 32.
* For regular use cases, we recommend 16 as the default.
* Values above 64 are not recommended and degrade performance.

<pre>
--multi-thread-streams <int>
</pre>

Number of streams to use for multithreaded downloads (default: 4). Only important on very large files. This will cause multithreaded up/download on chunk-sized bits of the file.

The optimal value is highly specific to the local network and used Hardware. For regular use cases, we recommend 4 as the default.

=== Debugging and Statistics ===
To get updates on current progress, use:
<pre>
--stats
</pre>
Interval between printing stats, e.g. 500ms, 60s, 5m (0 to disable) (default 1m0s).

To get debug information, use:
<pre>
--log-level=DEBUG
--stats-log-level=DEBUG
</pre>

Data Transfer/Rclone

2026-05-13T14:49:46Z

H Schumacher: Reordered remote setup options

[https://rclone.org/docs/ Rclone] is a command line tool to manage files on remote systems (e.g. cloud storage systems). Rclone either synchronizes in one direction only or its mounting functionality is used with <code>rclone mount</code>. Data can be piped between two completely remote locations, sometimes without local download. One advantage is that the transfer is multithreaded and it operates on a file level basis.
'''Caution:''' You can't use Rclone with 2FA.

== Installation ==

Rclone is a Go program and comes as a single binary file.

# Download the relevant binary.
# Extract the <code>rclone</code> executable, <code>rclone.exe</code> on Windows, from the archive.
# You can use the executables without further installation. For easy use, it is recommended to add the binary to your PATH environment variable. Information on how to do this can be found below.

Detailed information regarding different operating systems can be found here:

* Installation on [https://rclone.org/install/#windows Windows]
* Installation on [https://rclone.org/install/#macos macOS]
** If Rclone shall be used together with sftp, the [[https://wiki.bwhpc.de/e/Data_Transfer/SSHFS#Installation | sshfs installation]] instructions must be followed after installing Rclone.
* Installation on [https://rclone.org/install/#script-installation Linux]

== Usage Rclone ==

To use Rclone you have to define a config file. Afterwards you can connect by using the name of your configured connections.

=== Configure Remote ===

Before you can start using Rclone, you need to set up a remote. This means to configure a specific connection by providing authentication information, the network protocol that you want to use and a name for this configuration so that you can use it later on.

To configure a remote for a specific service, you need the following information:

* <code><remotehost></code>
* <code><username></code>
* <code><servicePassword></code>

Furthermore, you have to decide on:

* <code>network protocol</code> (for example webDAV, smb, sftp)
* <code>remote-name</code> (for example you can use the name of the service you want to connect to)

You have three different options to set up a new remote as described in the following sections. It's enough to choose one of those.

'''Oneliner''' 

Open a terminal and define all parameters in one command. If a ssh key shall be used instead of a password, it might be easier to adjust the config file directly as described in the next section.
<syntaxhighlight lang="bash"># smb
rclone config create <remote-name> smb host=<remotehost> user=<username> domain=<domain> pass=<password> --obscure
# sftp
rclone config create <remote-name> sftp host=<remotehost> user=<username> pass=<password> --obscure
# webdav
rclone config create <remote-name> webdav url=<remotehost> user=<username> pass=<password> --obscure
</syntaxhighlight>

'''Adjust Config File''' 
<syntaxhighlight lang="bash">
# Make sure that a config file exists. Access rights for the config file are set to 600.
rclone config touch
# Get the location of the file:
rclone config file
</syntaxhighlight>
Open the file and use one of the following snippets as template for your connection:
<syntaxhighlight lang="bash">[<remote-name>]
type = smb
host = <hostname>
user = <userID>
domain = <e.g. BWSERVICESAD>

[<remote-name>]
type = webdav
url = <hostURL>
vendor = other
user = <userID>

[<remote-name>]
type = sftp
host = <hostname>
user = <userID>
key_use_agent = false

[<remote-name-ssh-key-version>]
type = sftp
host = <hostname>
user = <userID>
key_file = ~/.ssh/id_ed25519
pubkey_file = ~/.ssh/id_ed25519.pub
key_use_agent = true
shell_type = none
</syntaxhighlight>
To add the password, please use the following command. Make sure to keep the prepended space so that the command is not saved in your command history.
<syntaxhighlight> rclone config update <remote-name> pass=<password> --obscure</syntaxhighlight>

'''Interactive Setup''' 

Execute:
<syntaxhighlight>rclone config</syntaxhighlight>
This will guide you through an interactive setup process. It's quite helpful for checking out which options there are and what the config file looks like after setting values that deviate from the default values. You can find detailed instructions at the website:

* [https://rclone.org/webdav/ Connect via webdav]
* [https://rclone.org/smb/ Connect via smb]
* [https://rclone.org/sftp/ Connect via sftp]

=== Use Remote ===

To see all configured remotes:
<syntaxhighlight lang="bash">rclone config
# Exit with 'q'.
</syntaxhighlight>

The syntax to use Rclone is like this:

<pre>rclone [options] subcommand <parameters> <parameters...>
</pre>
List all directories/containers/buckets in the folder XX.

<pre>rclone lsd <remote-name>:XX
</pre>
Copies /local/path to the remote path

<pre>rclone copy </local/path> <remote-name>:<remote/path>
</pre>
Copies fom remote path to /local/path

<pre>rclone copy <remote-name>:<remote/path> </local/path>
</pre>
Moves the contents of the source directory to the destination directory.

<pre>rclone move <remote-name>:<source/path> <remote-name>:<destination/path>
</pre>
More subcommands can be found [https://rclone.org/docs/#subcommands here].

== Usage Rclone Mount ==

Before you can follow the instructions in this chapter, you need to have set up a [[Data_Transfer/Rclone#Usage_Rclone | remote]].
More detailed information on how to use rclone mount can be found [https://rclone.org/commands/rclone_mount/ here].

=== Windows ===

To run rclone mount on Windows, you will need to [https://winfsp.dev/rel/ download and install WinFsp]. To mount on drive letter X or a nonexistent subdirectory, use:

<pre>rclone mount <remote-name>:path/to/files X:
rclone mount <remote-name>:path/to/files C:\path\parent\mount</pre>
In contrast to Linux/Mac, there is no background mode.

=== MacOS & Linux ===

You can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the <code>--daemon</code> flag to force background mode. If this doesn't work, you can put an <code>&</code> at the end of the command instead.

Create an empty directory on your local machine and then execute

<pre># to mount the root folder:
rclone mount --vfs-cache-mode full <remote-name>: /path/to/empty/folder
# to mount a subfolder:
rclone mount --vfs-cache-mode full <remote-name>:folderX/folderY /path/to/empty/folder
# to unmount:
fusermount -uz /path/to/mounted/folder </pre>

== Best Practices ==

Rclone has a lot of useful options.

=== Performance ===

To be able to utilize a larger bandwidth, it is helpful to add the following options for increased performance:

<pre>
--transfers <int>
</pre>

Number of file transfers to run in parallel (default: 4). Depending on the local Network, read and write speeds on the file system, and current load, different values might be best. For large transfers, it is advised to test local performance with different values beforehand.

* In our tests, we observed the best results between 8 and 32.
* For regular use cases, we recommend 16 as the default.
* Values above 64 are not recommended and degrade performance.

<pre>
--multi-thread-streams <int>
</pre>

Number of streams to use for multithreaded downloads (default: 4). Only important on very large files. This will cause multithreaded up/download on chunk-sized bits of the file.

The optimal value is highly specific to the local network and used Hardware. For regular use cases, we recommend 4 as the default.

=== Debugging and Statistics ===
To get updates on current progress, use:
<pre>
--stats
</pre>
Interval between printing stats, e.g. 500ms, 60s, 5m (0 to disable) (default 1m0s).

To get debug information, use:
<pre>
--log-level=DEBUG
--stats-log-level=DEBUG
</pre>

Data Transfer

2026-05-13T14:42:13Z

H Schumacher: Added ssh key info.

== Overview ==

Data transfer is the exchange of files between two systems. Before data transfer can happen, you need to go through the following steps:

# Choose the two [[#Data_Storage_Systems|data storage systems]] that shall exchange data.
# Choose the top level ways of transfer ([[#Ways of Transfer:_Copy,_Sync,_Mount|copy, sync or mount]]) by considering your specific use case.
# Choose a [[#Network_Protocols_&_Transfer_Tools|network protocol or transfer tool]] to use for the communication between the systems.

The recommended setup already includes these three steps. For a full overview, you can reference the tables that show [[Data_Transfer/All_Data_Transfer_Routes|all transfer routes]]. Those include all possible combinations between systems, top level way of transfer and network protocol / transfer tool.

=== Data Storage Systems ===

Data transfer can happen between a variety of systems. For example:

* [[File:Notebook.svg|x20px]] Local computer or VM (virtual machine)
* [[File:Microscope.svg|x20px]] Data producing machine (sequencer, microscope, ...)
* [[File:Clusternodes.svg|x20px]] HPC system
* [[File:Storage_small.svg|x15px]] Storage space (SDS@hd, institute server, ...)
* [[File:Cloud.svg|x15px]] Cloud resource

=== Ways of Transfer: Copy, Sync, Mount ===

The top level ways of transfer are:

* '''Copy:''' A simple copy command is the most basic way to transfer data. This is most efficient for very big data files that shall be retrieved from or moved to a remote location. And it can be most convenient, if you prefer moving your files via commandline instead of using a file browser. Examples: [[Data_Transfer/SCP|scp]], [[Data_Transfer/SFTP|sftp]]
* '''Sync:''' If the data is intended to be kept on both systems and undergoes change on only one of the systems, it makes sense to use a synchronization command instead. This way, only the changed files in one location are updated in the other location. Good use cases are backups or data transfers that go mostly in one direction like moving data from a sequencer to a storage space. A disadvantage is that the data needs storage space on both systems. Example: [[Data_Transfer/Rsync|rsync]]
* '''Mount:''' If the data undergoes change on both systems or is too big to store locally, then mounting is the most convenient solution. This allows you to see and work with the data as if it were stored locally on your computer while it is still placed on the remote system. All changes that you implement happen directly on the original data so that you don't need to copy or synchronize anything. Additionally, you'll see all changes that another party does to the data with just a very short delay. Disadvantages are that you need defined edit sessions starting with a mount and ending with a clean unmount of your files and with a stable network connection during the session. Also, file operations on the remote system become much slower via a remotely sshfs-mounted system. Example: [[Data_Transfer/SSHFS|sshfs]]
[[File:CopySyncMount.png|x250px]]
Figure 1: Top level transfer routes



=== Network Protocols & Transfer Tools ===

{| class="wikitable" style="vertical-align:middle;"
|- style="font-weight:bold;"
! Basic Network Protocol
! Used By Network Protocol
|-
| ssh
| [[Data_Transfer/SCP | scp]], [[Data_Transfer/SFTP | sftp]], [[Data_Transfer/Rsync | rsync]]
|-
| http(s)
| [[Data_Transfer/WebDAV | WebDAV]]
|-
| [[SDS@hd/Access/SMB | smb]]
| -
|-
| [[SDS@hd/Access/NFS | NFS]]
| -
|}
For every data transfer a network protocol to use for the communication between the systems must be chosen. The basic network protocols and the network protocols that build directly upon those are shown in the table on the right. These protocols can either be used rather directly or through tools that provide the protocol together with additional features. A tool can either mean a command line tool or a tool with a graphical user interface.

A comprehensive overview of all transfer options (network protocols and tools) can be found on the page [[Data_Transfer/All_Data_Transfer_Routes|all data transfer routes]].

== Recommended Setup ==
[[File:Bwhpc diagram simplenobox.jpg|thumb|Main routes for mounting|x150px]]
When you are working with a development environment that allows remote connections, this is the first choice. Otherwise, the main tools/protocols for transferring data are as follows:

* Windows: '''[[Data_Transfer/Graphical_Clients#MobaXterm|MobaXterm]]''' is a graphical user interface that allows logging in to the cluster with ssh as well as transferring data via a file browser or using command line tools for the transfer.
* MacOS and Linux:
** '''[[Data_Transfer/SSHFS|sshfs]]''' is quickly set up for mounting under stable connections.
** '''[[Data_Transfer/Rclone|Rclone]]''' for mount, copy and sync. An [[Registration/SSH | ssh key]] is needed when used with 2FA.
* SDS@hd: See the [[SDS@hd/Access|SDS@hd Access]] page.

== Best Practices ==

* '''Strong firewall restrictions''' -> Use ssh or http(s) based protocols, for example [[Data_Transfer/WebDAV|'''WebDav''']] and [[Data_Transfer/SFTP|sftp]]. For very strict facilities, ssh based protocols might not be allowed.
* '''Share data with collaborators...'''
** ...outside of Baden-Württemberg -> Use the [[SDS@hd|SDS@hd]] storage.
** ...that are less comfortable with the command line -> Let them mount the folder.
* '''Transfer many small files''' -> Compress the files to one.

For advanced topics see [[Data_Transfer/Advanced_Data_Transfer|Advanced Data Transfer]].

Data Transfer/SSHFS

2026-05-13T14:10:07Z

H Schumacher: Rclone link for 2fa cases.

Sshfs is a network protocol for mounting data. It uses [[Data Transfer/SFTP|sftp]] under the hood.

== Installation ==

For the necessary installations follow this link: [https://linuxize.com/post/how-to-use-sshfs-to-mount-remote-directories-over-ssh/ How to use SSHFS to Mount Remote Directories over SSH]. 
a) '''MacOS after the installation''' 
To enable sshfs on your Mac go to: System Preferences -> General tab -> Allow Extensions button 
Then follow the instructions that pop up (make sure that you remember the instructions before shutting down your computer). 
b) '''Linux installation short commands'''
<ul>
<li>Debian/Ubuntu: <code>apt-get install sshfs</code></li>
<li>CentOS/RedHat: <code>dnf install fuse-sshfs</code></li>
<li>If you want to use /etc/fstab, you can do this with the following entry:
<pre>sshfs#<username>@<hostname>: <your_local_mountpoint> fuse defaults,user,noauto,exec,reconnect 0 0 </pre></li></ul>

== Usage ==

=== Windows ===
''Caution: sshfs on Windows doesn't work with 2FA. An alternative is [[Data_Transfer/Rclone | Rclone with sftp]] + [[Registration/SSH | ssh key]].''
<ol style="list-style-type: decimal;">
<li>Go to "This PC" and select "Connect network drive" ("Netzlaufwerk verbinden")</li>
<li>Select a drive (W:) and click on "connect with webpage on which you can save documents and images" (Verbindung mit website herstellen, auf der Sie Dokumente und Bilder speichern können)</li>
<li>Enter the following as address, to connect to the home or root folder:
<syntaxhighlight lang="bash">\sshfs\<username>@<hostname>/</syntaxhighlight>
If you would want to go two folders up, you would add “''../../''” at the end.</li></ol>

=== MacOS & Linux ===

<ol style="list-style-type: decimal;">
<li>Create an empty directory. The cluster/storage folder is going to be mounted to this directory.</li>
<li>Mount a folder from the cluster/storage:
<syntaxhighlight lang="bash"># Home folder
sshfs -o reconnect <username>@<hostname>: <localPath>
# subfolderX
sshfs -o reconnect <username>@<hostname>:subfolderX <localPath></syntaxhighlight></li></ol>

=== Undo mounting ===

'''MacOS & Linux:''' 
If the connection to the cluster broke and you want to remount, you often have to use umount first. Try to remember to always unmount first before retrying. Otherwise it can happen that unmounting is not possible anymore by cmd. Usually the error message in this case tells you that the process is currently busy and therefore cannot umount. In this case, you have to restart the notebook which automatically unmounts everything.

<pre>```bash
umount -f <localPath>
# For example
umount -f /Users/<username>/Documents/mounted
# or use
fusermount -u <localPath>
```</pre>

SDS@hd/Access

2026-05-13T13:46:42Z

H Schumacher: Clarified username and password.

This page provides an overview on how to access data served by SDS@hd. To get an introduction to data transfer in general, see [[Data_Transfer|data transfer]].

'''Notation:''' Please replace all placeholder contents within guillemets <code>< ></code> with the actual value. For example, replace ''<name_of_my_dog>'' with ''Fluffy'' .

== Prerequisites ==

* You need to be [[SDS@hd/Registration|registered]].
* You need to be in the belwue-Network. This means you have to use the VPN Service of your HomeOrganization, if you want to access SDS@hd from outside the bwHPC-Clusters (e.g. via eduroam or from your personal notebook).

== Needed Information, independent of the chosen tool ==

* '''Username:''' You can look it up under your user data at [https://bwservices.uni-heidelberg.de/user/index.xhtml bwServices]. The username is ''<localPrimaryGroup>_<eduPersonPrincipalName>'' . (It is the same as for the bwHPC Clusters. Example: ''hd_ab123''.)
* '''Password:''' The Service Password that you set at bwServices in the [[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service|registration step]].
* '''SV-Acronym:''' Use the lower case version of the acronym for all access options.
* '''Hostname:''' The hostname depends on the chosen network protocol:
** For [[Data_Transfer/SSHFS|SSHFS]] and [[Data_Transfer/SFTP|SFTP]]: ''lsdf02-sshfs.urz.uni-heidelberg.de''
** For [[SDS@hd/Access/SMB|SMB]] and [[SDS@hd/Access/NFS|NFS]]: ''lsdf02.urz.uni-heidelberg.de''. The domain is ''BWSERVICESAD''.
** For [[Data_Transfer/WebDAV|WebDAV]] the url is: ''https://lsdf02-webdav.urz.uni-heidelberg.de''

== Recommended Setup ==
The following graphic shows the recommended way for accessing SDS@hd via Windows/Mac/Linux. The table provides an overview of the most important access options and links to the related pages. 
If you have various use cases, it is recommended to use [[Data_Transfer/Rclone|Rclone]]. You can copy, sync and mount with it. Thanks to its multithreading capability Rclone is a good fit for transferring big data. 
For an overview of all connection possibilities, please have a look at [[Data_Transfer/All_Data_Transfer_Routes|all data transfer routes]].

[[File:Data_transfer_diagram_simple.jpg|center|500px]]
Figure 1: SDS@hd main transfer routes

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
!
! Use Case
! Windows
! Mac
! Linux
! Possible Bandwith
! Firewall Ports
|-
| [[Data_Transfer/Rclone|Rclone]] + <protocol>
| copy, sync and mount, multithreading
| ✓
| ✓
| ✓
| depends on used protocol
| depends on used protocol
|-
| [[SDS@hd/Access/SMB|SMB]]
| mount as network drive in file explorer or usage via Rclone
| [[SDS@hd/Access/SMB#Windows|✓]]
| [[SDS@hd/Access/SMB#Mac|✓]]
| [[SDS@hd/Access/SMB#Linux|✓]]
| up to 40 Gbit/sec
| 139 (netbios), 135 (rpc), 445 (smb)
|-
| [[Data_Transfer/WebDAV|WebDAV]]
| go to solution for restricted networks
| [✓]
| ✓
| ✓
| up to 100GBit/sec
| 80 (http), 443 (https)
|- style="vertical-align:middle;"
| [[Data_Transfer/Graphical_Clients#MobaXterm|MobaXterm]]
| Graphical User Interface (GUI)
| [[Data_Transfer/Graphical_Clients#MobaXterm|✓]]
| ☓
| ☓
| see sftp
| see sftp
|- style="vertical-align:middle;"
| [[SDS@hd/Access/NFS|NFS]]
| mount for multi-user environments
| ☓
| ☓
| [[SDS@hd/Access/NFS|✓]]
| up to 40 Gbit/sec
| -
|- style="vertical-align:middle;"
| [[Data_Transfer/SSHFS|SSHFS]]
| mount, needs stable internet connection
| ☓
| [[Data_Transfer/SSHFS#MacOS_&_Linux|✓]]
| [[Data_Transfer/SSHFS#MacOS_&_Linux|✓]]
| see sftp
| see sftp
|- style="vertical-align:middle;"
| [[Data_Transfer/SFTP|SFTP]]
| interactive shell, better usability when used together with Rclone
| [[Data_Transfer/SFTP#Windows|✓]]
| [[Data_Transfer/SFTP#MacOS_&_Linux|✓]]
| [[Data_Transfer/SFTP#MacOS_&_Linux|✓]]
| up to 40 Gbit/sec
| 22 (ssh)
|}
Table 1: SDS@hd transfer routes

=== Access from a bwHPC Cluster ===

'''bwUniCluster''' 
You can't mount to your $HOME directory but you can create a mount under $TMPDIR by following the instructions for [[Data_Transfer/Rclone#Usage_Rclone_Mount | Rclone mount]]. It is advised to wait a couple of seconds (<code>sleep 5</code>) before trying to use the mounted directory.

'''bwForCluster Helix''' 
You can directly access your storage space under ''/mnt/sds-hd/'' on all login and compute nodes.

'''bwForCluster BinAC 2''' 
You can directly access your storage space under ''/mnt/sds-hd/'' on all login and compute nodes. The prerequisites are:
* The SV responsible has enabled the SV on BinAC 2 once by writing to [mailto:sds-hd-support@urz.uni-heidelberg.de sds-hd-support@urz.uni-heidelberg.de]
* You have a valid kerberos ticket, which can be fetched with <code>kinit <userID></code>

'''Other''' 
You can mount your SDS@hd SV on the cluster yourself by using [[Data_Transfer/Rclone | Rclone]] with the [[Data_Transfer/Rclone#Usage_Rclone_Mount | Rclone mount]] command. As transfer protocol you can use WebDAV or sftp. For a full overview please have a look at [[Data_Transfer/All_Data_Transfer_Routes | All Data Transfer Routes]].

=== Access via Webbrowser (read-only) ===

Visit [https://lsdf02-webdav.urz.uni-heidelberg.de/ lsdf02-webdav.urz.uni-heidelberg.de] and login with your SDS@hd username and service password. Here you can get an overview of the data in your "Speichervorhaben" and download single files. To be able to do more, like moving data, uploading new files, or downloading complete folders, a suitable client is needed as described above.

== Best Practices ==

* '''Managing access rights'''
** When the SV is mounted on Windows, access rights can be adjusted in the file/folder properties menu. (Users from Heidelberg without Windows can use the [https://www.urz.uni-heidelberg.de/de/service-katalog/desktop-und-arbeitsplatz/windows-terminalserver Windows terminal server]).
** bwForCluster Helix users can change the access rights via Helix by using [[Workspace#Regular_Unix_Permissions | unix permissions]] or [[Workspace#ACLs:_Access_Control_Lists | access control lists]]. On non native mounts ACL changes won't work.
** Additionally to the already mentioned options, the SVV can take over ownership of files by opening a [[Data_Transfer/SFTP|SFTP]] shell and running <code>chown -R <userID> <path/to/folder></code> .

* '''Multiuser environment''' → Use [[SDS@hd/Access/NFS|NFS]]

== Troubleshooting ==

Maintance windows and known issues are communicated via the email list or the News section at the SDS@hd start page in the wiki.

* '''Issue:''' The credentials aren't accepted
*: Check if your credentials work in general by trying the access via webbrowser: [https://lsdf02-webdav.urz.uni-heidelberg.de/].
*: If this doesn't work:
*:: → [[Registration/Login/Username| Check your Username]]
*:: → [[Registration/bwForCluster/Helix#Troubleshooting_with_the_Help_of_bwServices | Troubleshooting with bwServices]]
* '''Other Issue'''
** If available, follow the troubleshooting guide of your specific connection method.
** Make sure to not use LAN and WLAN at the same time to prevent connection problems.
** If you have an institutional account, make sure to be a fully active member of your institution.
If these suggestions didn't help, write to the [mailto:sds-hd-support@urz.uni-heidelberg.de support]. Provide the following information:
* Your operating system
* Does the access via webbrowser work?
*: If yes, provide us with detailed information on how you tried to access your SV (used access method, username, ...).

Helix/Login

2026-05-12T10:39:53Z

H Schumacher: Replaced some points with the "troubleshooting with bwServices" link

= Prerequisites =
* The three [[registration/bwForCluster|bwForCluster registration]] steps are completed and still valid.
* Your IP address is within the [https://www.belwue.de BelWü] network which connects universities and other scientific institutions in Baden-Württemberg. If your computer is in your university network (e.g. at your office), you should be able to connect to bwForCluster Helix without restrictions. If you are outside the BelWü network (e.g. at home), a VPN (virtual private network) connection to your University network must be established first. Please consult the VPN documentation of your university.
* As credentials you need your Helix [[Helix/Login#Username|username]], [[Registration/Password|service password]] and [[Registration/2FA|2FA token]].
* If you encounter any issues, please have a look at the [[Helix/Login#Troubleshooting|Troubleshooting]] section.

= Login to bwForCluster Helix =

Login to bwForCluster Helix is only possible with a Secure Shell (SSH) client for which you must know your bwForCluster Helix credentials and the hostname of the login nodes.
For more general information on SSH clients, visit the [[Registration/Login/Client|SSH clients Guide]].

== Username ==

Your username on bwForCluster Helix consists of a prefix and your local username.
For prefixes please refer to the [[Registration/Login/Username|Username Guide]].

Example: If your local username at your University is <code>ab123</code> and you are a user from Heidelberg University, your username on the cluster is: <code>hd_ab123</code>.

== Hostnames ==

bwForCluster Helix has two login nodes. In general, you should stay with automatic node selection, so that the connections are evenly distributed between the login nodes. To do this, we use so-called DNS round-robin scheduling which takes care of the node balancing. This means, if you open multiple SSH sessions, these sessions may run on different login nodes. Therefore, processes started in one session might not be visible in other sessions.

{| class="wikitable"
! Hostname !! Destination
|-
| '''helix.bwservices.uni-heidelberg.de''' || one of the two login nodes
|}

== Login with SSH command (Linux, Mac, Windows) ==

Most Unix and Unix-like operating systems such as Linux and Mac OS as well as newer versions of MS Windows (10 and 11), have a built-in SSH client provided by the OpenSSH project.
If you want to use the full set of Linux commands on Windows (10 or 11), you can also install the [https://docs.microsoft.com/en-us/windows/wsl/install Windows Subsystem for Linux] (WSL).

For login use one of the following ssh commands in a commandline (i.e. cmd, terminal, PowerShell):

ssh <username>@helix.bwservices.uni-heidelberg.de
ssh -l <username> helix.bwservices.uni-heidelberg.de

To run graphical applications on the cluster, you need to enable X11 forwarding with the <code>-X</code> flag:

ssh -X -l <username> helix.bwservices.uni-heidelberg.de

To make the login process faster, tell the command that no ssh key authentication is used by adding an additional parameter:

ssh -o PubkeyAuthentication=no <username>@helix.bwservices.uni-heidelberg.de

== Login with graphical SSH client (Windows) ==

For Windows we suggest using [[Data_Transfer/Graphical_Clients#MobaXterm|MobaXterm]] for login and file transfer.

Start MobaXterm and fill in the following fields:
<pre>
Remote name : helix.bwservices.uni-heidelberg.de
Specify user name : <username>
Port : 22
</pre>

After that click on 'ok'. Then a terminal will open where you can enter your credentials.

== Login with SSH key ==

To set up a SSH key for your workflow, read [[Registration/SSH|Registering SSH Keys with your Cluster]].
To login by using the ssh key, use the following command:

ssh -o IdentitiesOnly=yes -i <path_to_private_key> <username>@helix.bwservices.uni-heidelberg.de

== Login Example ==

To login to bwForCluster Helix, proceed as follows:
# Login with SSH command or MoabXterm as shown above.
# The system will ask for a one-time password <code>Your OTP</code> (= Smartphone Token / TAN list element/ ...) . Please enter your OTP and confirm it with Enter/Return. The OTP is not displayed when typing. If you do not have a second factor yet, please create one (see [[Registration/2FA]]).
# The system will ask you for your service password <code>Password:</code>. Please enter it and confirm it with Enter/Return. The password is not displayed when typing. If you do not have a service password yet or have forgotten it, please create one (see [[Registration/Password]]).
# You will be greeted by the cluster with the message of the day, followed by a shell.
<pre>
$ ssh -l hd_ab123 helix.bwservices.uni-heidelberg.de
Your OTP:
Password:

********************************************************************************
* *
* Baden-Wuerttemberg HPC Cluster for *
* Structural and Systems Biology, Medical Science, *
* Soft Matter, Computational Humanities, and *
* Mathematics and Computer Science *
* *
* bwForCluster *
* _ _ _ _ *
* | | | | | | (_) *
* | |__| | ___ | | _ __ __ *
* | __ | / _ \ | | | | \ \/ / *
* | | | | | __/ | | | | > < *
* |_| |_| \___| |_| |_| /_/\_\ *
* *
* *
* (xCAT 2.16.4 / RHEL 8.8 / GPFS 5.1.8) *
* *
* *
* bwHPC Wiki : https://wiki.bwhpc.de/e/Helix *
* Ticket System : https://www.bwhpc.de/supportportal *
* Job Monitoring : https://helix-monitoring.bwservices.uni-heidelberg.de *
* E-learning : https://training.bwhpc.de/ *
* -> 'Introduction to bwForCluster Helix' *
* *
********************************************************************************

Last login: ...
[hd_ab123@login ~]$
</pre>

= Allowed Activities on Login Nodes =

{|style="background:#deffee; width:100%;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
To guarantee usability for all users you must not run your compute jobs on the login nodes.
Compute jobs must be submitted as batch jobs.
Any compute job running on the login nodes will be terminated without notice.
Long-running compilation or long-running pre- or post-processing tasks must also be submitted as batch jobs.
|}

The login nodes are the access points to the compute system, your <code>$HOME</code> directory and your workspaces.
These nodes are shared with all users. Hence, your activities on the login nodes are primarily limited to setting up your batch jobs.
Your activities may also be:
* quick compilation of program code or
* quick pre- and post-processing of results from batch jobs.

We advise to use [[Helix/Slurm#Interactive_Jobs|interactive batch jobs]] for compute and memory intensive compilation and pre- and post-processing tasks.

= Related Information =

* If you want to register a new token for the two factor authentication (2FA), consult the [[Registration/2FA|2FA Guide]].
* If you want to de-register, consult the [[Registration/Deregistration|De-registration Guide]].
* If you need an SSH key for your workflow, read [[Registration/SSH|Registering SSH Keys with your Cluster]].
* Configuring your shell: [[.bashrc Do's and Don'ts]]

= Troubleshooting =

'''Login Problems'''

If you encounter login problems, please double check the prerequisites. If those are valid, it is fastest to first check the following points before contacting the support at the [https://www.bwhpc.de/supportportal.php|bwhpc Suppport Portal].
If there are known issues with the cluster, we'll inform you via e-mail or in the message of the day at the cluster.

* Make sure to not use LAN and WLAN at the same time to prevent connection problems.
* Do [[Registration/bwForCluster/Helix#Troubleshooting_with_the_Help_of_bwServices | troubleshooting with bwServices]].

'''Lost Token'''

To reset your token you have to visit the IT-Service to validate your identity.
Mention that you want a reset of your Helix 2FA token. It is important to emphasize that the token reset is for bwForCluster Helix to avoid confusion with the token that is specific to members/students of the university of Heidelberg.

You can visit the IT service point of the URZ in person at INF 330, 69120 Heidelberg. Or you can use the video call service. It is recommended to use the Chrome browser for doing the video call. Please have on official identification ready in any case (Führerschein / Personalausweis) .
For further information please see here: https://it-service.uni-heidelberg.de.

To be on the safe side, it is advised to create a [[Registration/2FA#Backup_TAN_List|backup TAN list]] additionally to the smartphone token.

Registration/bwForCluster/Helix

2026-05-12T10:34:50Z

H Schumacher: Added too many failed login attempts issue.

__FORCETOC__

== Prerequisites ==

Steps A + B in the [[Registration/bwForCluster | registration process]] must be finished.

== Registration Steps ==

# Visit the bwForCluster Helix '''[https://bwservices.uni-heidelberg.de registration page bwServices]'''.
#: [[File:bwServices_chooseHomeOrganisation.png|right|300px|thumb|Select your home organization]]
# '''Select your home organization''' from the list on the main page and click Proceed/Fortfahren. You will be directed to the ''Identity Provider'' of your home organization.
# Enter the '''username and password''' of your home organization (usually these credentials are also used for other services like email) and click Login/Einloggen.
# When you log in to bwServices for the first time, an overview will appear, with the account information that your home institution submits to the system. Please verify that all data is valid and then click ''Continue/Weiter''.
# You will be redirected back to the bwServices main page. It shows all the statewide services you have access to. Click '''Register/Registrieren''' under the field labeled ''bwForCluster Helix''.
#: [[File:BwIDM-reg.png|center|frame|Register for Helix]]
# bwForCluster Helix uses a '''2-factor authentication''' (2FA) mechanism to increase security.
#: If you have never registered a 2FA token on bwIDM, the following error message will appear:
#: [[File:Bwidm-3-red.png|center|600px|thumb|Second factor missing.]]
#: Use this '''[https://bwservices.uni-heidelberg.de/user/twofa.xhtml link]''' or select '''My Tokens''' in the main menu.
#: To register a new token, please follow these '''[[Registration/2FA|instructions]]'''.
#: Please complete this step before continuing.
# Read the Terms of Use / Nutzungsbedingungen, place a check mark next to ''I have read and accepted the terms of use'' and click ''Register/Registrieren''.
# '''Set a service password''' for bwForCluster Helix and click ''Save/Speichern''.
#: Be sure to use a secure password that is different from any other passwords you currently use or have used on other systems.
[[File:BwIDM-passwd.png|center|600px|thumb|Set service password]]
{|style="background:#deffee; width:70%; margin: auto;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
The service password is your private password for accessing the bwForCluster Helix. Don't ever share it with anyone!
|}

== Registration Website bwServices ==
The registration website '''[https://bwservices.uni-heidelberg.de bwServices]''' offers the following functionality:
* Register for the service.
* Set or change your service password.
* Review your registration details under "Registry Info". This includes your account status (active/lost_access).
* bwServices triggers an update of your user information upon login.
* Registering an [[Registration/SSH | SSH key]]. It can be used for login to ''bwForCluster Helix''.
* Creating tokens for logins that need 2-factor authentication ([[Registration/2FA |2FA]]) like ''bwForCluster Helix'' and ''bwVisu''.
* De-register from the service.

=== Troubleshooting with the Help of bwServices ===
When encountering connection issues with a service, the bwServices website is a good starting point for troubleshooting:
* <ins>'''Issue:</ins> Expired contract''' or inactive student id:
** No access to state services like the bwHPC clusters or SDS@hd is possible.
** You can see that this is the issue when the login to bwServices via your identity provider is not possible.
* <ins>'''Issue:</ins> Recently (re)activated uni-id:''' Your id at your home organization was (re)activated a short time ago but this change didn't get through to the bwHPC cluster or SDS@hd service.
** Login to bwServices. This triggers an update of your user information. Some minutes later, the connection to the service should work.
* <ins>'''Issue:</ins> Entitlement / RV missing:''' Prerequisites like entitlement ownership or RV membership aren't met (anymore).
** You can see the concrete issue and advice on how to move forward when looking at the registry info of the service on the bwServices website.
** When the issue is solved, the account status changes from LOST_ACCESS to ACTIVE.
* <ins>'''Issue:</ins> Service Password:''' When trying to connect to the service, the service password is not accepted.
** Set a [[#Setting_a_New_Service_Password | new password]].
* <ins>'''Issue:</ins> OTP:''' In the case of login issues with a service that uses 2FA, you can check if you're OTP is working by going in the menu to ''Index'' -> ''My Tokens''.
** If you're token is not working, you might have had too many failed login attempts. You can request a reset of the error counter from the support.
** If the token needs to be reset, please follow the instructions for a [[Helix/Login#Troubleshooting | Lost Token]].

=== Setting a New Service Password ===

At any time, you can set a new service password via [https://bwservices.uni-heidelberg.de/ bwServices] by carrying out the following steps:
# Visit [https://bwservices.uni-heidelberg.de/ bwServices] and select your home organization.
# Authenticate yourself via your home-organizational user id / username and your home-organizational password.
# Find your service and select '''Set Service Password'''.
# Set new service password, repeat it and click the '''Save''' button. Use a secure password that is different from any other passwords you currently use or have used on other systems.
# The page answers e.g. "password has been changed".

Helix/bwVisu/JupyterLab

2026-05-07T14:32:03Z

H Schumacher: Added hint to load modules first.

[https://jupyter.org/ JupyterLab] is an integrated development environment (IDE) that provides a flexible and scalable interface for the Jupyter Notebook system. It supports interactive data science and scientific computing across over 40 programming languages (including Python, Julia, and R).

== Change Python Version ==

The default python version can be seen by running <code>python --version</code> in the terminal.

A different python version can be installed into a new virtual environment and then registered as IPython kernel for the usage in JupyterLab. This is explained in the chapter [[#Add_packages_via_conda_environments | add packages via conda environments]].

== Install Python Packages ==

Python packages can be added by installing them into a virtual environment and then creating an IPython kernel from the virtual environment. 
Kernels can be shared. See the notes below. 
If you want to move a virtual environment, it is adivsed to recreate it in the new place. Otherwise, dependencies based on relative paths will break.

# Create a virtual environment with...
#* [[#Add_packages_via_venv_virtual_environments | ...venv]] or
#* [[#Add_packages_via_Conda_virtual_environments | ...conda]] (choose this option if you want to install a different python version) or
#* ...[https://docs.astral.sh/uv/getting-started/ uv] if you want to install a different python version but don't want to use conda.
# [[#Create_an_IPython_Kernel | Create an IPython kernel]] from the virtual environment
# Use the kernel within JupyterLab
#* By default new kernels are saved under <code>~/.local/share/jupyter</code> and this location is automatically detected. Therefore, new kernels are directly available.
#*:[[File:BwVisu JuypterLab KernelPath.png|In the JupyterLab job configuration form, a custom kernel path can be provided.|right|thumb|x150px]]
#* If the kernel is saved somewhere else, the path can be provided in the "Kernel path" field when configuring the JupyterLab job (see image). For a kernel placed under <code>path_to_parent_dir/share/jupyter/kernels/my_kernel</code> the needed "Kernel path" would be <code>path_to_parent_dir/share/jupyter</code>.
# When the kernel is used the first time, the file <code>notebook_secrets</code> is created automatically. It can be found under "Kernel path". For others to use the kernel, they must have read access to this file. The command <code>chmod 750 notebook_secrets</code> would for example allow the whole SDS@hd SV read access. For the access management in workspaces, please see [[Workspace#Setting_Permissions_for_Sharing_Files| Wokspace Permissions]].

Notes regarding the sharing of IPython kernels
* The virtual environment and the kernel need to be placed in a shared directory. For example at SDS@hd.
* There could be a subdirectory for the virtual environments and one for the kernels.
* The path to the kernels is saved in the environment variable $JUPYTER_DATA_DIR. Jupyter relevant paths can be seen with <code>jupyter --paths</code>

=== Add packages via ''venv'' virtual environments ===
More information about venv or other python virtual environments can be found at the [[Development/Python | Python]] page.

Steps for creating a '''venv''' virtual environment:
<ol style="list-style-type: decimal;">
<li>Open a terminal.</li>
<li>Create a new virtual evironment:
<syntaxhighlight lang="bash">python3 -m venv <env_parent_dir>/<env_name></syntaxhighlight>
* <code>env_parent_dir</code> is the path to the folder where the virtual environment shall be created. Relative paths can be used.
* Caution: If you you want to share the environment with others, make sure to already create it in the shared place.
</li>
<li>Activate the environment:
<syntaxhighlight lang="bash">source <env_parent_dir>/<env_name>/bin/activate</syntaxhighlight></li>
<li>Update pip and install packages:
<syntaxhighlight lang="bash">pip install -U pip --no-user
# when the environment is installed in home
pip install <packagename>
# when the environment is installed somewhere else and shall not have dependencies in home so that others can access it as well
pip install <packagename> --no-user</syntaxhighlight></li>
<li> [[#Create_an_IPython_Kernel | Create an IPython kernel]]</li>
</ol>

=== Add packages via Conda virtual environments ===
More information about using conda can be found at the [[Development/Conda | Conda]] page.

<ol style="list-style-type: decimal;">
<li>Load the miniforge module by clicking first on the blue hexagon icon on the left-hand side of Jupyter's start page and then on the "load" button right of the entry for miniforge in the software module menu.
<li>Open a terminal.</li>
<li>Create a new virtual environment:
* If you are the only person using the environment, you can install it in your home directory:
<syntaxhighlight lang="bash">conda create --name <env_name> python=<python version></syntaxhighlight>
* If you want to install it into a different directory, for example a shared place:
<syntaxhighlight lang="bash">conda create --prefix <path_to_shared_directory>/<env_name> python=<python version>
</syntaxhighlight>
</li>
<li>Activate your environment:
<syntaxhighlight lang="bash">conda activate <myenv></syntaxhighlight></li>
<li>Install your packages:
<syntaxhighlight lang="bash">conda install <mypackage></syntaxhighlight></li>
<li> [[#Create_an_IPython_Kernel | Create an IPython kernel]]</li>
</ol>

== Create an IPython Kernel ==

Python kernels are implementations of the Jupyter notebook environment for different languages or virtual environments. You can switch between kernels easily, allowing you to use the best tool for a specific task.
conda_kernels

=== Create a kernel from a virtual environment ===

<ol>
<li>Activate the virtual environment.</li>
<li>Install the ipykernel package:
<syntaxhighlight lang="bash">pip install ipykernel</syntaxhighlight></li>
<li>Register the virtual environment as custom kernel to Jupyter.
* If you are the only person using the environment:
<syntaxhighlight lang="bash">python3 -m ipykernel install --user --name=<kernel_name></syntaxhighlight>
The kernel can be found under <code>~/.local/share/jupyter/kernels/</code>.
* If you installed the environment in a shared place and want to have the kernel there as well:
<syntaxhighlight lang="bash">python3 -m ipykernel install --prefix <path_to_kernel_folder> --name=<kernel_name></syntaxhighlight>
The kernel can then be found under <code>path_to_kernel_folder/share/jupyter/kernels/<kernel_name></code>. As long as the same <code>path_to_kernel_folder</code> is used, all kernels will be saved next to each other in "kernels".
</li>
</ol>

=== Multi-Language Support ===

JupyterLab supports over 40 programming languages including Python, R, Julia, and Scala. This is achieved through the use of different kernels.

==== R Kernel ====

<ol style="list-style-type: decimal;">
<li>On the cluster:
<pre>$ module load math/R
$ R
> install.packages('IRkernel')</pre></li>
<li>On bwVisu:
<ol style="list-style-type: decimal;">
<li>Start Jupyter App</li>
<li>In left menu: load math/R</li>
<li>Open Console:</li>

<pre>$ R
> IRkernel::installspec(displayname = 'R 4.2')</pre>

<li>Start kernel 'R 4.2' as console or notebook</li>
</ol>
</ol>

==== Julia Kernel ====

Load the math/julia module. Open the Terminal.

<pre>
julia
]
add IJulia
</pre>

After that, Julia is available as a kernel.

== Interactive Widgets ==

JupyterLab supports interactive widgets that can create UI controls for interactive data visualization and manipulation within the notebooks. Example of using an interactive widget:

<pre class="{.python">from ipywidgets import IntSlider
slider = IntSlider()
display(slider)</pre>
These widgets can be sliders, dropdowns, buttons, etc., which can be connected to Python code running in the backend.

== FAQ ==

<ol><li>'''How can I use bwForCluster Helix software modules?'''
First click on the blue hexagon icon on the left-hand side of Jupyter's start page. Then load a module by clicking on the "load" button next to the corresponding module entry.</li>
<li>'''My virtual environment works on Helix but not in the bwVisu JupyterLab job.'''
If the environment uses Helix modules, you have to load the modules in the bwVisu job first. For example, when you used the python 3.13 module for creating the environment, the path to this python version is saved in the environment. When the module is not loadedin bwVisu, the path is not available and you might get an error like "''[...]/bin/python: error while loading shared libraries: libpython3.13.so.1.0: cannot open shared object file: No such file or directory''"</li>
<li>'''How can I navigate to my SDS@hd folder in the file browser?'''
Please see the instructions at the [[Helix/bwVisu/Usage#Files | Usage]] page.</li>
<li>'''I prefer VSCode over JupyterLab. Can I start a JupyterLab job and then connect with it via VSCode?'''
This is not possible. Please start the job directly on Helix instead. You can find the instructions at the [[Development/VS_Code#Connect_to_Remote_Jupyter_Kernel | VSCode page]].</li>
<li>'''My conda commands are interrupted with message 'Killed'.'''
Request more memory when starting Jupyter.</li>
<li>'''Jupyterlab doesn't let me in but asks for a password.'''
Try using more memory for the job. If this doesn't help, try using the inkognito mode of your browser as the browser cache might be the problem.</li>
</ol>

SDS@hd

2026-05-06T13:52:17Z

H Schumacher: Added account management link

[[File:sds-hd-logo.png|350px]]

SDS@hd is a central service for securely storing scientific data (Scientific Data Storage). The service is provided as a state service to researchers of higher education institutions of Baden-Württemberg. It is intended to be used for data that is frequently accessed ('hot data').

{| style=" background:#FEF4AB; width:100%;"
| style="padding:8px; background:#FFE856; font-size:120%; font-weight:bold; text-align:left" | News
|-
|
* November 2022: No special entitlement is needed anymore to participate in an existing storage project.
* September 2023: Service has now been opened for DFN AAI & eduGAIN federation members to participate on existing storage projects.
|}

{| style=" background:#eeeefe; width:100%;"
| style="padding:8px; background:#dedefe; font-size:120%; font-weight:bold; text-align:left" | Training & Support
|-
|
* [https://www.urz.uni-heidelberg.de/en/service-catalogue/storage/sdshd-scientific-data-storage Service description & FAQ]
* [mailto:sds-hd-support@urz.uni-heidelberg.de Submit a Ticket]
|}

{| style=" background:#ffeaef; width:100%;"
| style="padding:8px; background:#f5dfdf; font-size:120%; font-weight:bold; text-align:left" | User Documentation
|-
|
* [[SDS@hd/Registration|Registration]] ([[SDS@hd/SV_Management|SV Management]], [[Registration/bwForCluster/Helix#Registration_Website_bwServices|Account Management]])
* [[SDS@hd/Access|Access]]
* [[SDS@hd/Security|Data Security]]
* [[Helix/bwVisu|bwVisu]] for visualization and interactive data analysis
|}

{| style=" background:#e6e9eb; width:100%;"
| style="padding:8px; background:#d1dadf; font-size:120%; font-weight:bold; text-align:left" | Storage Funding
|-
|
* Please [[SDS@hd/Acknowledgement|acknowledge]] SDS@hd in your publications.

Helix

2026-05-06T13:50:59Z

H Schumacher: Added account management link

[[File:Helix-logo.png|300px]]

The '''bwForCluster Helix''' is dedicated to research in the bwHPC domains Structural and Systems Biology, Medical Science, Soft Matter, Computational Humanities, and Mathematics and Computer Science.

{| style=" background:#FEF4AB; width:100%;"
| style="padding:8px; background:#FFE856; font-size:120%; font-weight:bold; text-align:left" | News
|-
|







* June 2025: [https://www.bwhpc.de/897.php Important notice regarding the use of MathWorks products]
* April 2025: Cluster extension with 3x gpu8 nodes (Nvidia H200)
|}

{| style=" background:#eeeefe; width:100%;"
| style="padding:8px; background:#dedefe; font-size:120%; font-weight:bold; text-align:left" | Training & Support
|-
|
* [[Helix/Getting Started|Getting Started]]
* E-Learning Course [https://training.bwhpc.de/goto.php/crs/695 Introduction to bwForCluster Helix]

* [https://www.bwhpc.de/supportportal.php Submit a Ticket] to support unit 'bwHPC - Support > bwForCluster Helix'

|}

{| style=" background:#deffee; width:100%;"
| style="padding:8px; background:#cef2e0; font-size:120%; font-weight:bold; text-align:left" | User Documentation
|-
|
* [[Registration/bwForCluster|Registration]] ([[Registration/bwForCluster/RV/Management|RV Management]], [[Registration/bwForCluster/Helix#Registration_Website_bwServices|Account Management]])
* [[Helix/Login|Login]]
* [[Helix/Hardware|Hardware and Architecture]]
* [[Helix/Filesystems|File Systems and Workspaces]]
* [[Helix/Software|Cluster Specific Software]]
* [[Helix/Slurm|Batch System (Slurm)]]
* [[Helix/bwVisu|bwVisu]] for visualization and interactive applications
|}

{| style=" background:#e6e9eb; width:100%;"
| style="padding:8px; background:#d1dadf; font-size:120%; font-weight:bold; text-align:left" | Cluster Funding
|-
|
* Please [[Helix/Acknowledgement|acknowledge]] the cluster in your publications.
|}

Data Transfer/Rclone

2026-05-06T11:26:59Z

H Schumacher: Added smb to oneliner and config file

[https://rclone.org/docs/ Rclone] is a command line tool to manage files on remote systems (e.g. cloud storage systems). Rclone either synchronizes in one direction only or its mounting functionality is used with <code>rclone mount</code>. Data can be piped between two completely remote locations, sometimes without local download. One advantage is that the transfer is multithreaded and it operates on a file level basis.
'''Caution:''' You can't use Rclone with 2FA.

== Installation ==

Rclone is a Go program and comes as a single binary file.

# Download the relevant binary.
# Extract the <code>rclone</code> executable, <code>rclone.exe</code> on Windows, from the archive.
# You can use the executables without further installation. For easy use, it is recommended to add the binary to your PATH environment variable. Information on how to do this can be found below.

Detailed information regarding different operating systems can be found here:

* Installation on [https://rclone.org/install/#windows Windows]
* Installation on [https://rclone.org/install/#macos macOS]
* Installation on [https://rclone.org/install/#script-installation Linux]

== Usage Rclone ==

To use Rclone you have to define a config file. Afterwards you can connect by using the name of your configured connections.

=== Configure Remote ===

Before you can start using Rclone, you need to set up a remote. This means to configure a specific connection by providing authentication information, the network protocol that you want to use and a name for this configuration so that you can use it later on.

To configure a remote for a specific service, you need the following information:

* <code><remotehost></code>
* <code><username></code>
* <code><servicePassword></code>

Furthermore, you have to decide on:

* <code>network protocol</code> (for example webDAV, smb, sftp)
* <code>remote-name</code> (for example you can use the name of the service you want to connect to)

You have three different options to set up a new remote which are explained by the following sections.

'''Interactive Setup''' 

Execute:
<pre>rclone config</pre>
This will guide you through an interactive setup process. You can find detailed instructions at the website:

* [https://rclone.org/webdav/ Connect via webdav]
* [https://rclone.org/smb/ Connect via smb]
* [https://rclone.org/sftp/ Connect via sftp]

'''Oneliner''' 

Define all parameters in one command. For example:
<syntaxhighlight lang="bash"># smb
rclone config create <remote-name> smb host=<remotehost> user=<username> domain=<domain> pass=<password> --obscure
# sftp
rclone config create <remote-name> sftp host=<remotehost> user=<username> pass=<password> --obscure
# webdav
rclone config create <remote-name> webdav url=<remotehost> user=<username> pass=<password> --obscure
</syntaxhighlight>

'''Adjust Config File''' 
<syntaxhighlight lang="bash">
# Make sure that a config file exists. Access rights for the config file are set to 600.
rclone config touch
# Get the location of the file:
rclone config file
</syntaxhighlight>
You can use the following snippet as template for your connections.
<syntaxhighlight lang="bash">[<remote-name>]
type = smb
host = <hostname>
user = <userID>
domain = <e.g. BWSERVICESAD>

[<remote-name>]
type = webdav
url = <hostURL>
vendor = other
user = <userID>

[<remote-name>]
type = sftp
host = <hostname>
user = <userID>
key_use_agent = false

[<remote-name-ssh-version>]
type = sftp
host = <hostname>
user = <userID>
key_file = ~/.ssh/id_ed25519
pubkey_file = ~/.ssh/id_ed25519.pub
key_use_agent = true
shell_type = none
</syntaxhighlight>
To add the password, please use the following command. Make sure to keep the prepended space so that the command is not saved in your command history.
<syntaxhighlight> rclone config update <remote-name> pass=<password> --obscure</syntaxhighlight>

=== Use Remote ===

The syntax to use Rclone is like this:

<pre>rclone [options] subcommand <parameters> <parameters...>
</pre>
List all directories/containers/buckets in the folder XX.

<pre>rclone lsd <remote-name>:XX
</pre>
Copies /local/path to the remote path

<pre>rclone copy </local/path> <remote-name>:<remote/path>
</pre>
Copies fom remote path to /local/path

<pre>rclone copy <remote-name>:<remote/path> </local/path>
</pre>
Moves the contents of the source directory to the destination directory.

<pre>rclone move <remote-name>:<source/path> <remote-name>:<destination/path>
</pre>
More subcommands can be found [https://rclone.org/docs/#subcommands here].

== Usage Rclone Mount ==

Before you can follow the instructions in this chapter, you need to have set up a [[Data_Transfer/Rclone#Usage_Rclone | remote]].
Detailed information on how to use rclone mount can be found [https://rclone.org/commands/rclone_mount/ here].

=== Windows ===

To run rclone mount on Windows, you will need to [https://winfsp.dev/rel/ download and install WinFsp]. To mount on drive letter X or a nonexistent subdirectory, use:

<pre>rclone mount <remote-name>:path/to/files X:
rclone mount <remote-name>:path/to/files C:\path\parent\mount</pre>
In contrast to Linux/Mac, there is no background mode.

=== MacOS & Linux ===

You can run mount in either foreground or background (aka daemon) mode. Mount runs in foreground mode by default. Use the <code>--daemon</code> flag to force background mode. If this doesn't work, you can put an <code>&</code> at the end of the command instead.

Create an empty directory on your local machine and then execute

<pre># to mount the root folder:
rclone mount --vfs-cache-mode full <remote-name>: /path/to/empty/folder
# to mount a subfolder:
rclone mount --vfs-cache-mode full <remote-name>:folderX/folderY /path/to/empty/folder
# to unmount:
fusermount -uz /path/to/mounted/folder </pre>

== Best Practices ==

Rclone has a lot of useful options.

=== Performance ===

To be able to utilize a larger bandwidth, it is helpful to add the following options for increased performance:

<pre>
--transfers <int>
</pre>

Number of file transfers to run in parallel (default: 4). Depending on the local Network, read and write speeds on the file system, and current load, different values might be best. For large transfers, it is advised to test local performance with different values beforehand.

* In our tests, we observed the best results between 8 and 32.
* For regular use cases, we recommend 16 as the default.
* Values above 64 are not recommended and degrade performance.

<pre>
--multi-thread-streams <int>
</pre>

Number of streams to use for multithreaded downloads (default: 4). Only important on very large files. This will cause multithreaded up/download on chunk-sized bits of the file.

The optimal value is highly specific to the local network and used Hardware. For regular use cases, we recommend 4 as the default.

=== Debugging and Statistics ===
To get updates on current progress, use:
<pre>
--stats
</pre>
Interval between printing stats, e.g. 500ms, 60s, 5m (0 to disable) (default 1m0s).

To get debug information, use:
<pre>
--log-level=DEBUG
--stats-log-level=DEBUG
</pre>

Helix/bwVisu/Getting Started

2026-05-06T10:50:22Z

H Schumacher: Added image

== Motivation ==

When large quantities of scientific data is created (for example, from simulations), it is often necessary to employ hardware for further processing that is just as powerful as e.g. the HPC cluster that created the data in the first place. Transferring the data to a local workstation for visualization and analysis is typically not only time-consuming because of the data transfer itself, but the workstation may be ill-equipped to handle the workload. For such scenarios, remote solutions are needed, that employ powerful hardware and bring the applications to the data - and not vice versa.

bwVisu provides such a remote service. The user can log in to an intuitive web frontend which manages interactive jobs running on bwForCluster Helix. Once a job has been started, the user can connect to it such that the application appears in a browser window with full 3D hardware acceleration provided by the cluster. The only requirement on the client side is that the browser must support HTML5.

== Registration ==

In order to use bwVisu, it is required to be a user of the [https://wiki.bwhpc.de/e/Registration/bwForCluster bwForCluster Helix] or a user of [https://wiki.bwhpc.de/e/SDS@hd/Registration SDS@hd].
# Register for the service bwVisu at [http://bwservices.uni-heidelberg.de bwServices].
# bwVisu uses a 2-factor authentication (2FA) mechanism to increase security. If you have not registered a 2FA token at bwServices, an error message will appear. Use this '''[https://bwservices.uni-heidelberg.de/user/twofa.xhtml link]''' or select '''My Tokens''' in the main menu of bwServices. To register a new token, please follow these '''[[Registration/2FA|instructions]]'''. Please complete this step before continuing.
# Once your registration has been completed, your user account will be set up. This can take up to 10 minutes, so please wait for around ten minutes before proceeding.

== Login ==

# Go to the bwVisu web frontend at [https://bwvisu.bwservices.uni-heidelberg.de/ bwvisu.bwservices.uni-heidelberg.de].
# Login with the credentials of your home university and provide a 2FA token.

== Usage ==

[[File:Bwvisu2-gui.png|x150px|right|bwVisu Workflow]]
As shown in the image, the usual workflow consists of three steps: You choose an application, define the needed job resources and then connect to the job as soon as it is running. Detailed instructions are [[Helix/bwVisu/Usage|here]].

== Technical Information ==

=== Data storage ===

bwVisu provides no storage space. For data storage you have access to the filesystems of bwForCluster Helix and to SDS@hd.

=== Open OnDemand ===

bwVisu is based on [https://openondemand.org Open OnDemand] an open-source software platform designed to provide easy and streamlined access to high-performance computing (HPC) resources. Developed by the Ohio Supercomputer Center, it allows users to access HPC resources via a standard web browser, eliminating the need for a traditional command line interface.

The platform provides a range of tools and features. bwVisu uses it to provide the following features:
<ol>
<li>'''Web-based Access:''' Users can manage jobs, files, and data directly through their browser.</li>
<li>'''Interactive Applications:'''</li>
<ul>
<li>It supports GUI-based applications like Jupyter Notebooks and RStudio, enabling interactive computing and visualization.</li>
<li>For most bwVisu applications you can connect to a running job with your browser.</li>
<li>Some applications may require a dedicated desktop client.</li>
</ul>
<li>'''Job Management:''' Users can easily submit and manage their interactive computing jobs on HPC resources. For members of bwForCluster Helix, the jobs can be monitored via the [https://helix-monitoring.bwservices.uni-heidelberg.de/ monitoring portal].</li>
<li>'''File Management:''' Provides a file browser that allows users to upload and manage their data files without needing to use command-line tools.</li>
</ol>

Helix/bwVisu/Usage

2026-05-06T10:34:45Z

H Schumacher: Added output.log information, formatting

== Basic Navigation ==

bwVisu is quite simple and intuitively designed to make launching apps on the cluster as user-friendly as possible. Once you have successfully logged into bwVisu, the first thing you see is a list of pinned apps. These are the available apps that you can launch as a job on the cluster.

In the navigation bar, the user has the following options:

<code>Files</code> — <code>Interactive Apps</code> — <code>My Interactive Sessions</code> — <code>Shell</code>

=== Files ===

Here, you can access your home directory on Helix. In a graphical user interface, files can be downloaded and uploaded, and new files and folders can be created. You will encounter an error message if you try to see data that you have no access to.

In the Home Directory the results and logs from the apps are stored. You get the following interface:

[[File:BwVisuFiles.png|bwVisu-files|center|x300px]]

'''For SDS@hd users:''' Data on SDS@hd (under /mnt/sds-hd) can only be accessed from within jobs. Therefore, you need to open a terminal (within a JupyterLab or Rstudio job or directly on Helix) and set a symbolic link to your SDS@hd folder in your home directory. For example like this:
<pre>cd $HOME
mkdir sds-hd
cd sds-hd
ln -s /mnt/sds-hd/sd16a001 sd16a001</pre>

=== Interactive Apps ===

This displays the apps that the user can run on the cluster, possibly across multiple nodes. These apps initiate an interactive session which the user can directly connect to and, depending on the app, receive a graphical interface.

=== My Interactive Sessions ===

At bwVisu, it is possible to start several interactive apps simultaneously. Here, one can view an overview of currently running interactive apps and completed sessions. It is also possible to view the log for each session. As soon as one starts an interactive app, one is automatically redirected here. Even if you log out of bwVisu and log back in, you can still see the information and logs from the finished interactive apps here until you delete it.

=== Shell ===
For bwForCluster Helix users only: After entering your OTP and password a shell on the login node of bwForCluster Helix opens. This way, you can for example create workspaces when you need more space. Please look up the details under [[Helix/Filesystems#Workspaces | Helix Workspaces]]. They can't be seen in the File Viewer but are available within the bwVisu jobs.

== Start a Job ==
[[File:bwVisuConcept.png|center|x170px]]
<ol>
<li> At the start page of the web frontend, you can start a new job by clicking on an application version in the list of pinned apps.</li>
<li>You will now see the application description and options to adjust the job resources.</li>
<ul>
<li> To find the best resource settings for your jobs, please have a look at the [https://helix-monitoring.bwservices.uni-heidelberg.de/ bwForCluster Helix monitoring portal] . There, you can see how much of the requested resources where actually used by your jobs.
<li> At the bottom of the page, beneath the <code>Launch</code> button, you can find a link for accessing the logs/session data of all your jobs.</li>
<li>The interface can differ per app because each app can have individual configuration options. </li>
[[File:bwVisuRStudio.png|bwVisu-rstudio|center|x200px]]</li>
</ul>
<li>Click the <code>Launch</code> button to start a new job with this application. You can't start two jobs with the same application. Launching an app can take some time depending on the requested resources and cluster utilization.</li>
<li>The <code>Interactive Sessions</code> page opens with the details of your job.</li>
<ul>
<li>'''Host:''' Indicates on which nodes the application is running.</li>
<li>'''Time Remaining:''' Each application is given a time limit, which can also be set in advance. In this example, the application is supposed to run for one hour.</li>
<li>'''Session ID:''' This is a link that leads to the folder of the session. Among other things, application logs are displayed here, which can be viewed in the UI.
[[File:BwVisuRstudioRun.png|bwVisu-rstudio-run|center|x200px]] </li>
</li>
</ul>
<li> Connect to the job with your browser by clicking <code>connect to <application></code>. </li>
</ol>

== Adjust noVNC Applications ==
<div><ul>
<li style="display: inline-block; vertical-align: middle; float: right;"> [[File:bwVisu Fiji noVNCMenu.png|thumb|none|x200px|noVNC menu within Fiji]] </li>
<li style="display: inline-block; vertical-align: top; float: right;"> [[File:bwVisu_Fiji_Running.png|thumb|none|x200px|Job details view of a running Fiji Job]] </li>
</ul></div>
noVNC is an open-source VNC browser client. Some bwVisu applications use noVNC and therefore, come with additional options in the view of the job details and an additional menu within the running application.

*'''Running Job View''' on the interactive sessions page
** Compression slider: Before opening the application, you can choose the compression level to use. 0 means no compression while 9 offers the best compression but uses more CPU resources on the cluster which can be slower.
** Image Quality slider: Before opening the application, you can choose the image quality level. With this you can control the desired JPEG quality.
** View Only (Share-able Link) button: By clicking this button the application opens in view only mode. You can share this link with collaborators or students while you launch your noVNC application normally for yourself. This way, others can follow what you are doing. For every job you need to generate a new link.
* '''noVNC menu''' within the running application
** When you open the application you can see an additional menu on the left with options. For the ones using the application in view-only mode it is helpful to select the option to show a dot instead of not showing the mouse cursor at all. Therefore go to "Options" and then "Expand".
** For copying data, you need to use the clipboard. When copying something locally, you need to put it into the clipboard before you can use it within the application. The same goes the other way around.
* '''Adjust window size''' and position of the app by executing a right click at the edge of the app window frame, so that a menu shows up.

== Terminate a Job ==

The job will terminate when the job runtime requested in the job submission form has expired To terminate an application yourself, you can click the delete button or end the application in the interactive session. If the app is terminated in the interactive session, the window no longer shows <code>Running</code> but <code>Completed</code>. With the <code>Delete</code> button, you end the session and also remove the list entry from <code>My Interactive Sessions</code>.

== Troubleshooting ==
Maintance windows and known issues are communicated via the email list or the ''News'' section at the bwVisu start page in the wiki.
* Depending on the problem, it can help to look up the related bwForCluster Helix wiki pages. For example:
*: '''Error:''' Disk space exceeded → '''[https://wiki.bwhpc.de/e/Helix/Filesystems#Troubleshooting Filesystems: Troubleshooting]'''
* '''Issue:''' The webservice is not accessible.
*: If you're a bwForCluster Helix user, you need to have logged in to Helix at least once so that you're home directory gets created. Afterwards, the webservice page should be accessible.
* '''Issue:''' The bwVisu job fails or doesn't start.
*: You can try to look for the issue yourself:
*:* Reload the page without using the cache: <code>Strg+Shift+R</code> (Windows/Linux) or <code>Cmd+Shift+R</code> (Mac)
*:* Empty the browser cache:
*:** Chrome/Edge: <code>Strg+Shift+Entf</code> → choose timeframe all → choose ''Images and Files in Cache'' → choose ''Delete Files''
*:** Firefox: <code>Strg+Shift+Entf</code> → choose timeframe all → choose ''Cache'' → choose ''Delete Files''
*:* Test alternative browser (Firefox, Chrome, Edge, ...)
*:* Use a private session (without saved cookies and cache): <code>Strg+Shift+N</code> (Chrome) or <code>Strg+Shift+P</code> (Firefox).
* '''Support:''' If you can't solve the issue, write to the support and provide the following information:
** Date and time of the issue.
** Job-id (the number in brackets after the jobname)
** The <code>output.log</code> file that you can find when following the session id link.
** Please report patterns that you recognize. For example:
*** The issue happens around a specific time of day.
*** The issue is connected to the duration of usage (e.g. happens always after ca. one hour).
*** The issue appears after specific user interactions (using a specific method, opening the terminal, clicking a specific button, ...)
: You might be asked for further information:
:* The internet browser that you user and its version. For example Firefox 128.
:* Provide more information about network traffic via a HAR-file. First start a job and open the application. Then follow he instructions below:
:** Instructions for Chrome/Edge:
:**# Open developer tools with <code>F12</code> or right click -> ''Inspect'' Then choose the tab ''Network''.
:**# Activate the checkbox ''Preserve log''.
:**# Reproduce the issue in the current tab.
:**# After the problem happened again: Click the export symbol (⬇️) in the menu of the network-tabs and choose ''Export HAR...''.
:** Instructions for Firefox:
:**# Open developer tools with <code>F12</code> and choose the tab ''Network analysis''.
:**# Click the settings symbol (⚙️) and activate ''Continuous Protocol''.
:**# Reproduce the issue in the current tab.
:**# After the problem happened again: Click the settings symbol again (⚙️) and choose ''Save everything as HAR''.

Registration/bwForCluster

2026-05-05T17:43:47Z

H Schumacher: Used same formatting as for bwUniCluster

= Registration bwForCluster =

A bwForCluster is a cluster for a specific [https://www.bwhpc.de/cluster.php research area].
You can apply for a bwForCluster and the "cluster assignment team" will assign you to the appropriate cluster for your research area, taking into account your specific hardware/software needs.
bwForClusters are funded by the German Research Foundation (DFG) and the Ministry of Science, Research and the Arts of Baden-Württemberg on the basis of grant applications (cf. proposals application guidelines according to Art. 91b GG).

All members of the universities in Baden-Württemberg can apply for an account.

The use of the bwForClusters is free of charge.

== Three Steps for Registration ==

[[File:bwForCluster-Registration.png|thumb|right|upright=1.2|bwForCluster Registration Process]]
The registration process for a bwForCluster is divided into three steps, whereby step A+B can be performed in parallel.
When both are completed, you can perform step C.

To which cluster you get access depends on your research area and will be decided in step B.

* Step A: You need to get the '''bwForCluster Entitlement''' from your university/college. → '''[[Registration/bwForCluster/Entitlement|bwForCluster User Access Step A]]'''
* Step B: You need to '''apply for or join a Rechenvorhaben/project''' on the "central application site" (ZAS). → '''[[Registration/bwForCluster/RV|bwForCluster User Access Step B]]'''
* Step C: You need to '''register for a bwForCluster''' (create an account on the cluster). → '''[[Registration/bwForCluster/Service|bwForCluster User Access Step C]]'''

After finishing Step C, you are done with registration.

* To '''login''' to one of the bwForClusters, please refer to the general → '''[[Registration/Login|Login Guide]]'''

== Information for registered users ==

* If you want to check if your '''account''' is still valid on one of the bwForClusters, please refer to the general → '''[[Registration/Account|Account Guide]]'''
* If you want to '''create a second factor''', please refer to → '''[[Registration/2FA|Generate a Second Factor (2FA)]]''' (Justus 2, Helix, NEMO2)
* If you need to '''change or forgot your password''' for a bwForCluster, please refer to the general → '''[[Registration/Password|Password Guide]]'''
* If you want to '''use SSH keys''' on a bwForCluster, please refer to → '''[[Registration/SSH|Registering SSH Keys with your Cluster]]'''
* If you want do '''de-register your user account''' from a bwForCluster, please refer to the general → '''[[Registration/Deregistration|De-registration Guide]]'''

Helix/bwVisu/Usage

2026-05-05T15:39:06Z

H Schumacher: Added things to try and information to report.

== Basic Navigation ==

bwVisu is quite simple and intuitively designed to make launching apps on the cluster as user-friendly as possible. Once you have successfully logged into bwVisu, the first thing you see is a list of pinned apps. These are the available apps that you can launch as a job on the cluster.

In the navigation bar, the user has the following options:

<code>Files</code> — <code>Interactive Apps</code> — <code>My Interactive Sessions</code> — <code>Shell</code>

=== Files ===

Here, you can access your home directory on Helix. In a graphical user interface, files can be downloaded and uploaded, and new files and folders can be created. You will encounter an error message if you try to see data that you have no access to.

In the Home Directory the results and logs from the apps are stored. You get the following interface:

[[File:BwVisuFiles.png|bwVisu-files|center|x300px]]

'''For SDS@hd users:''' Data on SDS@hd (under /mnt/sds-hd) can only be accessed from within jobs. Therefore, you need to open a terminal (within a JupyterLab or Rstudio job or directly on Helix) and set a symbolic link to your SDS@hd folder in your home directory. For example like this:
<pre>cd $HOME
mkdir sds-hd
cd sds-hd
ln -s /mnt/sds-hd/sd16a001 sd16a001</pre>

=== Interactive Apps ===

This displays the apps that the user can run on the cluster, possibly across multiple nodes. These apps initiate an interactive session which the user can directly connect to and, depending on the app, receive a graphical interface.

=== My Interactive Sessions ===

At bwVisu, it is possible to start several interactive apps simultaneously. Here, one can view an overview of currently running interactive apps and completed sessions. It is also possible to view the log for each session. As soon as one starts an interactive app, one is automatically redirected here. Even if you log out of bwVisu and log back in, you can still see the information and logs from the finished interactive apps here until you delete it.

=== Shell ===
For bwForCluster Helix users only: After entering your OTP and password a shell on the login node of bwForCluster Helix opens. This way, you can for example create workspaces when you need more space. Please look up the details under [[Helix/Filesystems#Workspaces | Helix Workspaces]]. They can't be seen in the File Viewer but are available within the bwVisu jobs.

== Start a Job ==
[[File:bwVisuConcept.png|center|x170px]]
<ol>
<li> At the start page of the web frontend, you can start a new job by clicking on an application version in the list of pinned apps.</li>
<li>You will now see the application description and options to adjust the job resources.</li>
<ul>
<li> To find the best resource settings for your jobs, please have a look at the [https://helix-monitoring.bwservices.uni-heidelberg.de/ bwForCluster Helix monitoring portal] . There, you can see how much of the requested resources where actually used by your jobs.
<li> At the bottom of the page, beneath the <code>Launch</code> button, you can find a link for accessing the logs/session data of all your jobs.</li>
<li>The interface can differ per app because each app can have individual configuration options. </li>
[[File:bwVisuRStudio.png|bwVisu-rstudio|center|x200px]]</li>
</ul>
<li>Click the <code>Launch</code> button to start a new job with this application. You can't start two jobs with the same application. Launching an app can take some time depending on the requested resources and cluster utilization.</li>
<li>The <code>Interactive Sessions</code> page opens with the details of your job.</li>
<ul>
<li>'''Host:''' Indicates on which nodes the application is running.</li>
<li>'''Time Remaining:''' Each application is given a time limit, which can also be set in advance. In this example, the application is supposed to run for one hour.</li>
<li>'''Session ID:''' This is a link that leads to the folder of the session. Among other things, application logs are displayed here, which can be viewed in the UI.
[[File:BwVisuRstudioRun.png|bwVisu-rstudio-run|center|x200px]] </li>
</li>
</ul>
<li> Connect to the job with your browser by clicking <code>connect to <application></code>. </li>
</ol>

== Adjust noVNC Applications ==
<div><ul>
<li style="display: inline-block; vertical-align: middle; float: right;"> [[File:bwVisu Fiji noVNCMenu.png|thumb|none|x200px|noVNC menu within Fiji]] </li>
<li style="display: inline-block; vertical-align: top; float: right;"> [[File:bwVisu_Fiji_Running.png|thumb|none|x200px|Job details view of a running Fiji Job]] </li>
</ul></div>
noVNC is an open-source VNC browser client. Some bwVisu applications use noVNC and therefore, come with additional options in the view of the job details and an additional menu within the running application.

*'''Running Job View''' on the interactive sessions page
** Compression slider: Before opening the application, you can choose the compression level to use. 0 means no compression while 9 offers the best compression but uses more CPU resources on the cluster which can be slower.
** Image Quality slider: Before opening the application, you can choose the image quality level. With this you can control the desired JPEG quality.
** View Only (Share-able Link) button: By clicking this button the application opens in view only mode. You can share this link with collaborators or students while you launch your noVNC application normally for yourself. This way, others can follow what you are doing. For every job you need to generate a new link.
* '''noVNC menu''' within the running application
** When you open the application you can see an additional menu on the left with options. For the ones using the application in view-only mode it is helpful to select the option to show a dot instead of not showing the mouse cursor at all. Therefore go to "Options" and then "Expand".
** For copying data, you need to use the clipboard. When copying something locally, you need to put it into the clipboard before you can use it within the application. The same goes the other way around.
* '''Adjust window size''' and position of the app by executing a right click at the edge of the app window frame, so that a menu shows up.

== Terminate a Job ==

The job will terminate when the job runtime requested in the job submission form has expired To terminate an application yourself, you can click the delete button or end the application in the interactive session. If the app is terminated in the interactive session, the window no longer shows <code>Running</code> but <code>Completed</code>. With the <code>Delete</code> button, you end the session and also remove the list entry from <code>My Interactive Sessions</code>.

== Troubleshooting ==
Maintance windows and known issues are communicated via the email list or the News section at the bwVisu start page in the wiki.
* Depending on the problem, it can help to look up the related bwForCluster Helix wiki pages. For example:
*: '''Error:''' Disk space exceeded → '''[https://wiki.bwhpc.de/e/Helix/Filesystems#Troubleshooting Filesystems: Troubleshooting]'''
* '''Issue:''' The webservice is not accessible.
*: If you're a bwForCluster Helix user, you need to have logged in to Helix at least once so that you're home directory gets created. Afterwards, the webservice page should be accessible.
* '''Issue:''' The bwVisu job fails or doesn't start.
*: You can try to look for the issue yourself:
*:* Reload the page without using the cache: `Strg+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
*:* Empty the browser cache:
*:** Chrome/Edge: `Strg+Shift+Entf` → choose timeframe all → choose "Images and Files in Cache" → choose "Delete Files"
*:** Firefox: `Strg+Shift+Entf` → choose timeframe all → choose "Cache" → choose "Delete Files"
*:** Test alternative browser (Firefox, Chrome, Edge, ...)
*:** Use a private session (without saved cookies and cache): `Strg+Shift+P` (Firefox) or `Strg+Shift+N` (Chrome).
*: If this doesn't help, write to the support and provide the following information:
*:* Date and time of the issue.
*:* Job-id
*:* Please report patterns that you recognize. For example:
*:** The issue happens around a specific time of day.
*:** The issue is connected to the duration of usage (e.g. happens always after ca. one hour).
*:** The issue appears after specific user interactions (using a specific method, opening the terminal, clicking a specific button, ...)
*: You might be asked for further information:
*:* The internet browser that you user and its version. For example Firefox 128.
*:* Provide more information about network traffic via a HAR-file.
*:** Instructions for Chrome/Edge:
*:**# Open developer tools with `F12` or right click -> "Inspect"
*:**# Choose the tab "Network"
*:**# Activate the checkbox "Preserve log"
*:**# Reproduce the issue (open new terminal)
*:**# After the problem happened again: Click the Export-Symbol (⬇️) in the menu of the network-tabs and choose "Export HAR..."
*:** Instructions for Firefox:
*:**# Open developer tools with `F12`
*:**# Choose the tab "Network analysis"
*:**# Click the options symbol (⚙️) an activate "Continuous Protocol"
*:**# Reproduce the issue (open new terminal)
*:**# After the problem happened again: Click the option symbol again (⚙️) and choose "Save everything as HAR".

Helix/bwVisu/JupyterLab

2026-05-05T11:24:22Z

H Schumacher: Added instructions for using Helix modules

[https://jupyter.org/ JupyterLab] is an integrated development environment (IDE) that provides a flexible and scalable interface for the Jupyter Notebook system. It supports interactive data science and scientific computing across over 40 programming languages (including Python, Julia, and R).

== Change Python Version ==

The default python version can be seen by running <code>python --version</code> in the terminal.

A different python version can be installed into a new virtual environment and then registered as IPython kernel for the usage in JupyterLab. This is explained in the chapter [[#Add_packages_via_conda_environments | add packages via conda environments]].

== Install Python Packages ==

Python packages can be added by installing them into a virtual environment and then creating an IPython kernel from the virtual environment. 
Kernels can be shared. See the notes below. 
If you want to move a virtual environment, it is adivsed to recreate it in the new place. Otherwise, dependencies based on relative paths will break.

# Create a virtual environment with...
#* [[#Add_packages_via_venv_virtual_environments | ...venv]] or
#* [[#Add_packages_via_Conda_virtual_environments | ...conda]] (choose this option if you want to install a different python version) or
#* ...[https://docs.astral.sh/uv/getting-started/ uv] if you want to install a different python version but don't want to use conda.
# [[#Create_an_IPython_Kernel | Create an IPython kernel]] from the virtual environment
# Use the kernel within JupyterLab
#* By default new kernels are saved under <code>~/.local/share/jupyter</code> and this location is automatically detected. Therefore, new kernels are directly available.
#*:[[File:BwVisu JuypterLab KernelPath.png|In the JupyterLab job configuration form, a custom kernel path can be provided.|right|thumb|x150px]]
#* If the kernel is saved somewhere else, the path can be provided in the "Kernel path" field when configuring the JupyterLab job (see image). For a kernel placed under <code>path_to_parent_dir/share/jupyter/kernels/my_kernel</code> the needed "Kernel path" would be <code>path_to_parent_dir/share/jupyter</code>.
# When the kernel is used the first time, the file <code>notebook_secrets</code> is created automatically. It can be found under "Kernel path". For others to use the kernel, they must have read access to this file. The command <code>chmod 750 notebook_secrets</code> would for example allow the whole SDS@hd SV read access. For the access management in workspaces, please see [[Workspace#Setting_Permissions_for_Sharing_Files| Wokspace Permissions]].

Notes regarding the sharing of IPython kernels
* The virtual environment and the kernel need to be placed in a shared directory. For example at SDS@hd.
* There could be a subdirectory for the virtual environments and one for the kernels.
* The path to the kernels is saved in the environment variable $JUPYTER_DATA_DIR. Jupyter relevant paths can be seen with <code>jupyter --paths</code>

=== Add packages via ''venv'' virtual environments ===
More information about venv or other python virtual environments can be found at the [[Development/Python | Python]] page.

Steps for creating a '''venv''' virtual environment:
<ol style="list-style-type: decimal;">
<li>Open a terminal.</li>
<li>Create a new virtual evironment:
<syntaxhighlight lang="bash">python3 -m venv <env_parent_dir>/<env_name></syntaxhighlight>
* <code>env_parent_dir</code> is the path to the folder where the virtual environment shall be created. Relative paths can be used.
* Caution: If you you want to share the environment with others, make sure to already create it in the shared place.
</li>
<li>Activate the environment:
<syntaxhighlight lang="bash">source <env_parent_dir>/<env_name>/bin/activate</syntaxhighlight></li>
<li>Update pip and install packages:
<syntaxhighlight lang="bash">pip install -U pip --no-user
# when the environment is installed in home
pip install <packagename>
# when the environment is installed somewhere else and shall not have dependencies in home so that others can access it as well
pip install <packagename> --no-user</syntaxhighlight></li>
<li> [[#Create_an_IPython_Kernel | Create an IPython kernel]]</li>
</ol>

=== Add packages via Conda virtual environments ===
More information about using conda can be found at the [[Development/Conda | Conda]] page.

<ol style="list-style-type: decimal;">
<li>Load the miniforge module by clicking first on the blue hexagon icon on the left-hand side of Jupyter's start page and then on the "load" button right of the entry for miniforge in the software module menu.
<li>Open a terminal.</li>
<li>Create a new virtual environment:
* If you are the only person using the environment, you can install it in your home directory:
<syntaxhighlight lang="bash">conda create --name <env_name> python=<python version></syntaxhighlight>
* If you want to install it into a different directory, for example a shared place:
<syntaxhighlight lang="bash">conda create --prefix <path_to_shared_directory>/<env_name> python=<python version>
</syntaxhighlight>
</li>
<li>Activate your environment:
<syntaxhighlight lang="bash">conda activate <myenv></syntaxhighlight></li>
<li>Install your packages:
<syntaxhighlight lang="bash">conda install <mypackage></syntaxhighlight></li>
<li> [[#Create_an_IPython_Kernel | Create an IPython kernel]]</li>
</ol>

== Create an IPython Kernel ==

Python kernels are implementations of the Jupyter notebook environment for different languages or virtual environments. You can switch between kernels easily, allowing you to use the best tool for a specific task.
conda_kernels

=== Create a kernel from a virtual environment ===

<ol>
<li>Activate the virtual environment.</li>
<li>Install the ipykernel package:
<syntaxhighlight lang="bash">pip install ipykernel</syntaxhighlight></li>
<li>Register the virtual environment as custom kernel to Jupyter.
* If you are the only person using the environment:
<syntaxhighlight lang="bash">python3 -m ipykernel install --user --name=<kernel_name></syntaxhighlight>
The kernel can be found under <code>~/.local/share/jupyter/kernels/</code>.
* If you installed the environment in a shared place and want to have the kernel there as well:
<syntaxhighlight lang="bash">python3 -m ipykernel install --prefix <path_to_kernel_folder> --name=<kernel_name></syntaxhighlight>
The kernel can then be found under <code>path_to_kernel_folder/share/jupyter/kernels/<kernel_name></code>. As long as the same <code>path_to_kernel_folder</code> is used, all kernels will be saved next to each other in "kernels".
</li>
</ol>

=== Multi-Language Support ===

JupyterLab supports over 40 programming languages including Python, R, Julia, and Scala. This is achieved through the use of different kernels.

==== R Kernel ====

<ol style="list-style-type: decimal;">
<li>On the cluster:
<pre>$ module load math/R
$ R
> install.packages('IRkernel')</pre></li>
<li>On bwVisu:
<ol style="list-style-type: decimal;">
<li>Start Jupyter App</li>
<li>In left menu: load math/R</li>
<li>Open Console:</li>

<pre>$ R
> IRkernel::installspec(displayname = 'R 4.2')</pre>

<li>Start kernel 'R 4.2' as console or notebook</li>
</ol>
</ol>

==== Julia Kernel ====

Load the math/julia module. Open the Terminal.

<pre>
julia
]
add IJulia
</pre>

After that, Julia is available as a kernel.

== Interactive Widgets ==

JupyterLab supports interactive widgets that can create UI controls for interactive data visualization and manipulation within the notebooks. Example of using an interactive widget:

<pre class="{.python">from ipywidgets import IntSlider
slider = IntSlider()
display(slider)</pre>
These widgets can be sliders, dropdowns, buttons, etc., which can be connected to Python code running in the backend.

== FAQ ==

<ol><li>'''How can I use bwForCluster Helix software modules?'''
First click on the blue hexagon icon on the left-hand side of Jupyter's start page. Then load a module by clicking on the "load" button next to the corresponding module entry.</li>
<li>'''How can I navigate to my SDS@hd folder in the file browser?'''
Open a terminal and set a symbolic link to your SDS@hd folder in your home directory. For example:</li>
<pre>cd $HOME
mkdir sds-hd
cd sds-hd
ln -s /mnt/sds-hd/sd16a001 sd16a001</pre>
<li>'''I prefer VSCode over JupyterLab. Can I start a JupyterLab job and then connect with it via VSCode?'''
This is not possible. Please start the job directly on Helix instead. You can find the instructions at the [[Development/VS_Code#Connect_to_Remote_Jupyter_Kernel | VSCode page]].</li>
<li>'''My conda commands are interrupted with message 'Killed'.'''
Request more memory when starting Jupyter.</li>
<li>'''Jupyterlab doesn't let me in but asks for a password.'''
Try using more memory for the job. If this doesn't help, try using the inkognito mode of your browser as the browser cache might be the problem.</li>
</ol>

File:Bwvisu2-gui.png

2026-04-28T08:25:36Z

H Schumacher:

Registration/bwForCluster/Helix

2026-04-24T11:51:42Z

H Schumacher: bwServices functionality: added ssh key and token

__FORCETOC__

== Prerequisites ==

Steps A + B in the [[Registration/bwForCluster | registration process]] must be finished.

== Registration Steps ==

# Visit the bwForCluster Helix '''[https://bwservices.uni-heidelberg.de registration page bwServices]'''.
#: [[File:bwServices_chooseHomeOrganisation.png|right|300px|thumb|Select your home organization]]
# '''Select your home organization''' from the list on the main page and click Proceed/Fortfahren. You will be directed to the ''Identity Provider'' of your home organization.
# Enter the '''username and password''' of your home organization (usually these credentials are also used for other services like email) and click Login/Einloggen.
# When you log in to bwServices for the first time, an overview will appear, with the account information that your home institution submits to the system. Please verify that all data is valid and then click ''Continue/Weiter''.
# You will be redirected back to the bwServices main page. It shows all the statewide services you have access to. Click '''Register/Registrieren''' under the field labeled ''bwForCluster Helix''.
#: [[File:BwIDM-reg.png|center|frame|Register for Helix]]
# bwForCluster Helix uses a '''2-factor authentication''' (2FA) mechanism to increase security.
#: If you have never registered a 2FA token on bwIDM, the following error message will appear:
#: [[File:Bwidm-3-red.png|center|600px|thumb|Second factor missing.]]
#: Use this '''[https://bwservices.uni-heidelberg.de/user/twofa.xhtml link]''' or select '''My Tokens''' in the main menu.
#: To register a new token, please follow these '''[[Registration/2FA|instructions]]'''.
#: Please complete this step before continuing.
# Read the Terms of Use / Nutzungsbedingungen, place a check mark next to ''I have read and accepted the terms of use'' and click ''Register/Registrieren''.
# '''Set a service password''' for bwForCluster Helix and click ''Save/Speichern''.
#: Be sure to use a secure password that is different from any other passwords you currently use or have used on other systems.
[[File:BwIDM-passwd.png|center|600px|thumb|Set service password]]
{|style="background:#deffee; width:70%; margin: auto;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
The service password is your private password for accessing the bwForCluster Helix. Don't ever share it with anyone!
|}

== Registration Website bwServices ==
The registration website '''[https://bwservices.uni-heidelberg.de bwServices]''' offers the following functionality:
* Register for the service.
* Set or change your service password.
* Review your registration details under "Registry Info". This includes your account status (active/lost_access).
* bwServices triggers an update of your user information upon login.
* Registering an [[Registration/SSH | SSH key]]. It can be used for login to ''bwForCluster Helix''.
* Creating tokens for logins that need 2-factor authentication ([[Registration/2FA |2FA]]) like ''bwForCluster Helix'' and ''bwVisu''.
* De-register from the service.

=== Troubleshooting with the Help of bwServices ===
When encountering connection issues with a service, the bwServices website is a good starting point for troubleshooting:
* <ins>'''Issue:</ins> Expired contract''' or inactive student id:
** No access to state services like the bwHPC clusters or SDS@hd is possible.
** You can see that this is the issue when the login to bwServices via your identity provider is not possible.
* <ins>'''Issue:</ins> Recently (re)activated uni-id:''' Your id at your home organization was (re)activated a short time ago but this change didn't get through to the bwHPC cluster or SDS@hd service.
** Login to bwServices. This triggers an update of your user information. Some minutes later, the connection to the service should work.
* <ins>'''Issue:</ins> Entitlement / RV missing:''' Prerequisites like entitlement ownership or RV membership aren't met (anymore).
** You can see the concrete issue and advice on how to move forward when looking at the registry info of the service on the bwServices website.
** When the issue is solved, the account status changes from LOST_ACCESS to ACTIVE.
* <ins>'''Issue:</ins> Service Password:''' When trying to connect to the service, the service password is not accepted.
** At bwServices a [[#Setting_a_New_Service_Password | new password]] can be set for the service.
* <ins>'''Issue:</ins> OTP:''' In the case of login issues with a service that uses 2FA, you can check if you're OTP is working by going in the menu to ''Index'' -> ''My Tokens''.
** If you're token is not working, please follow the instructions for a [[Helix/Login#Troubleshooting | Lost Token]].

=== Setting a New Service Password ===

At any time, you can set a new service password via [https://bwservices.uni-heidelberg.de/ bwServices] by carrying out the following steps:
# Visit [https://bwservices.uni-heidelberg.de/ bwServices] and select your home organization.
# Authenticate yourself via your home-organizational user id / username and your home-organizational password.
# Find your service and select '''Set Service Password'''.
# Set new service password, repeat it and click the '''Save''' button.
# The page answers e.g. "password has been changed".

Registration/bwForCluster/Helix

2026-04-24T11:40:25Z

H Schumacher: Reformatting, added token issue

__FORCETOC__

== Prerequisites ==

Steps A + B in the [[Registration/bwForCluster | registration process]] must be finished.

== Registration Steps ==

# Visit the bwForCluster Helix '''[https://bwservices.uni-heidelberg.de registration page bwServices]'''.
#: [[File:bwServices_chooseHomeOrganisation.png|right|300px|thumb|Select your home organization]]
# '''Select your home organization''' from the list on the main page and click Proceed/Fortfahren. You will be directed to the ''Identity Provider'' of your home organization.
# Enter the '''username and password''' of your home organization (usually these credentials are also used for other services like email) and click Login/Einloggen.
# When you log in to bwServices for the first time, an overview will appear, with the account information that your home institution submits to the system. Please verify that all data is valid and then click ''Continue/Weiter''.
# You will be redirected back to the bwServices main page. It shows all the statewide services you have access to. Click '''Register/Registrieren''' under the field labeled ''bwForCluster Helix''.
#: [[File:BwIDM-reg.png|center|frame|Register for Helix]]
# bwForCluster Helix uses a '''2-factor authentication''' (2FA) mechanism to increase security.
#: If you have never registered a 2FA token on bwIDM, the following error message will appear:
#: [[File:Bwidm-3-red.png|center|600px|thumb|Second factor missing.]]
#: Use this '''[https://bwservices.uni-heidelberg.de/user/twofa.xhtml link]''' or select '''My Tokens''' in the main menu.
#: To register a new token, please follow these '''[[Registration/2FA|instructions]]'''.
#: Please complete this step before continuing.
# Read the Terms of Use / Nutzungsbedingungen, place a check mark next to ''I have read and accepted the terms of use'' and click ''Register/Registrieren''.
# '''Set a service password''' for bwForCluster Helix and click ''Save/Speichern''.
#: Be sure to use a secure password that is different from any other passwords you currently use or have used on other systems.
[[File:BwIDM-passwd.png|center|600px|thumb|Set service password]]
{|style="background:#deffee; width:70%; margin: auto;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
The service password is your private password for accessing the bwForCluster Helix. Don't ever share it with anyone!
|}

== Registration Website bwServices ==
The registration website '''[https://bwservices.uni-heidelberg.de bwServices]''' offers the following functionality:
* Register for the service
* Set or change your service password
* Review your registration details under "Registry Info". This includes your account status (active/lost_access).
* Triggers an update of your user information upon login.
* De-register from the service

=== Troubleshooting with the Help of bwServices ===
When encountering connection issues with a service, the bwServices website is a good starting point for troubleshooting:
* <ins>'''Issue:</ins> Expired contract''' or inactive student id:
** No access to state services like the bwHPC clusters or SDS@hd is possible.
** You can see that this is the issue when the login to bwServices via your identity provider is not possible.
* <ins>'''Issue:</ins> Recently (re)activated uni-id:''' Your id at your home organization was (re)activated a short time ago but this change didn't get through to the bwHPC cluster or SDS@hd service.
** Login to bwServices. This triggers an update of your user information. Some minutes later, the connection to the service should work.
* <ins>'''Issue:</ins> Entitlement / RV missing:''' Prerequisites like entitlement ownership or RV membership aren't met (anymore).
** You can see the concrete issue and advice on how to move forward when looking at the registry info of the service on the bwServices website.
** When the issue is solved, the account status changes from LOST_ACCESS to ACTIVE.
* <ins>'''Issue:</ins> Service Password:''' When trying to connect to the service, the service password is not accepted.
** At bwServices a [[#Setting_a_New_Service_Password | new password]] can be set for the service.
* <ins>'''Issue:</ins> OTP:''' In the case of login issues with a service that uses 2FA, you can check if you're OTP is working by going in the menu to ''Index'' -> ''My Tokens''.
** If you're token is not working, please follow the instructions for a [[Helix/Login#Troubleshooting | Lost Token]].

=== Setting a New Service Password ===

At any time, you can set a new service password via [https://bwservices.uni-heidelberg.de/ bwServices] by carrying out the following steps:
# Visit [https://bwservices.uni-heidelberg.de/ bwServices] and select your home organization.
# Authenticate yourself via your home-organizational user id / username and your home-organizational password.
# Find your service and select '''Set Service Password'''.
# Set new service password, repeat it and click the '''Save''' button.
# The page answers e.g. "password has been changed".

SDS@hd/Registration

2026-04-23T16:18:50Z

H Schumacher: fixed link, reformatting, added link from step A to B

== Registration Steps ==

The registration consists of two steps:

* '''Step A:''' Membership in Storage Project (Speichervorhaben/'''SV'''). There are two options:
*: '''a)''' →[[SDS@hd/Registration#a)_Join_existing_SV | Join existing SV]]
*: '''b)''' →[[SDS@hd/Registration#b)_Apply_for_new_SV | Apply for new SV]] (only possible for [https://www.bwidm.de/hochschulen.php bwIDM members])
* '''Step B:''' →[[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service |Registration for SDS@hd Service]]

After finishing the registration, the '''next steps''' are:
* Check which management options there are for your respective role in the SV → [[SDS@hd/SV_Management |SV Management]]
* See how to access and use your storage space → [[SDS@hd/Access | Access]]

[[File:SDS@hd_Registration.png|center|x500px|upright|SDS@hd Registration Process]]

=== Step A: SV Membership ===

You can either join an existing SV or start a new one.

==== a) Join existing SV ====
To join an existing SV as a coworker:
# Get the following information from the SV responsible:
#:* SV acronym
#:* SV password
# Fill in and submit the [https://sds-hd.urz.uni-heidelberg.de/management/shib/sds_collaboration.php SV collaboration form] after logging in to the SDS@hd Managementtool.
#: You are now a member of the SV. The SV owner (and SV managers) will be notified automatically.
→ [[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service | Go on with Step B]] if you are using SDS@hd for the first time.

==== b) Apply for new SV ====

This is typically done only by the leader of a scientific work group or the senior scientist of a research group/collaboration.
Any amount of co-workers can join your SV without having to register another project. You just need to provide them with the SV acronym and SV password. You'll receive this information via e-mail as soon as the SV application was successful.

There are two steps:
# '''Get the permission / entitlement:'''. Your institution has to grant you the permission to start an SDS@hd storage project ("SDS@hd SV entitlement"). Please follow the procedure specific to your institution:
#: → see [[SDS@hd/Registration/Entitlement | Entitlement]].
# '''Apply for a new SV:'''
#: → Fill in the form at the [https://sds-hd.urz.uni-heidelberg.de/management SDS@hd Managementtool].
→ [[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service | Go on with Step B]] if you are using SDS@hd for the first time.

If you register your own SV, you will be:
* ...responsibe for providing new members with the necessary information to join the SV
*: → see [[SDS@hd/SV_Management#SV_Responsible_(SVV) | SV Responsible (SVV)]]
* ...held accountable for the co-workers in the SV
* ...asked to provide information for the two reports required by the DFG for their funding of SDS@hd
* ...likely asked for a contribution to a future DFG grant proposal for an extension of the storage system in your area of research ("wissenschaftliches Beiblatt")

=== Step B: Registration for SDS@hd Service ===
[[File:bwServices_chooseHomeOrganisation.png|right|300px|thumb|Select your home organization]]

After step A you have to register your personal account on the storage system and set a service password.

* Visit the registration website '''bwServices''': [https://bwservices.uni-heidelberg.de/ https://bwservices.uni-heidelberg.de]
*# Select your home organization from the list and click ''Proceed''
*#: You will be directed to the ''Identity Provider'' of your home organisation
*# Enter your home-organisational user ID / username and your home-organisational password and click ''Login'' button
*#: You will be redirected back to bwServices
* '''Register''' for the SDS@hd service:
*# Under ''The following services are available'' select the service ''SDS@hd - Scientific Data Storage''.
*# Click ''Register''
* Set your personal '''service password''' for SDS@hd. This is used for accessing SVs.
* The registration is finished.
*: → [[#sds_registration_nextSteps|next steps]]

=== Change Service Password at bwServices ===

→ '''[[Registration/bwForCluster/Helix#Setting_a_New_Service_Password | Setting a New Service Password]]'''

SDS@hd/Registration

2026-04-23T12:16:49Z

H Schumacher: fixed link

== Registration Steps ==

The registration consists of two steps:

* '''Step A:''' Membership in Storage Project (Speichervorhaben/'''SV'''). There are two options:
*: '''a)''' →[[SDS@hd/Registration#a)_Join_existing_SV | Join existing SV]]
*: '''b)''' →[[SDS@hd/Registration#b)_Apply_for_new_SV | Apply for new SV]] (only possible for [https://www.bwidm.de/hochschulen.php bwIDM members])
* '''Step B:''' →[[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service |Registration for SDS@hd Service]]

After finishing the registration, the next steps are:
* Check which management options there are for your respective role in the SV → [[SDS@hd/SV_Management |SV Management]]
* See how to access and use your storage space → [[SDS@hd/Access | Access]]

[[File:SDS@hd_Registration.png|center|x500px|upright|SDS@hd Registration Process]]

=== Step A: SV Membership ===

You can either join an existing SV or start a new one.

==== a) Join existing SV ====
To join an existing SV as a coworker:
# Your advisor (the SV responsible) will provide you with the following data on the SV:
#:* acronym
#:* password
# Login at the SDS@hd Managementtool and fill in the [https://sds-hd.urz.uni-heidelberg.de/management/shib/sds_collaboration.php SV collaboration form]
#: Provide the SV acronym and SV password.
# After submitting the request, you will be assigned to the SV as a member and receive an email with the next steps. The SV owner (and SV managers) will be notified automatically.

==== b) Apply for new SV ====

This is typically done only by the leader of a scientific work group or the senior scientist of a research group/collaboration.
Any amount of co-workers can join your SV without having to register another project. You just need to provide them with the SV acronym and SV password. You'll receive this information via e-mail as soon as the SV application was successful.

There are two steps:
# '''Get the permission / entitlement:'''. Your institution has to grant you the permission to start an SDS@hd storage project ("SDS@hd SV entitlement"). Please follow the procedure specific to your institution:
#: → see [[SDS@hd/Registration/Entitlement | Entitlement]].
# '''Apply for a new SV:'''
#: → Fill in the form at the [https://sds-hd.urz.uni-heidelberg.de/management SDS@hd Managementtool].

If you register your own SV, you will be:
* ...responsibe for providing new members with the necessary information to join the SV
*: → see [[#SV_Responsible:_Manage_the_SV_and_its_Members | SV Responsible: Manage the SV and its Members]]
* ...held accountable for the co-workers in the SV
* ...asked to provide information for the two reports required by the DFG for their funding of SDS@hd
* ...likely asked for a contribution to a future DFG grant proposal for an extension of the storage system in your area of research ("wissenschaftliches Beiblatt")

=== Step B: Registration for SDS@hd Service ===
[[File:bwServices_chooseHomeOrganisation.png|right|300px|thumb|Select your home organization]]

After step 1 you have to register your personal account on the storage system and set a service password.
Please visit:
* [https://bwservices.uni-heidelberg.de/ https://bwservices.uni-heidelberg.de]
*# Select your home organization from the list and click '''Proceed'''
*# You will be directed to the ''Identity Provider'' of your home organisation
*# Enter your home-organisational user ID / username and your home-organisational password and click '''Login''' button
*# You will be redirected back to the registration website [https://bwservices.uni-heidelberg.de/ https://bwservices.uni-heidelberg.de/]
*# <div>Select unter '''The following services are available''' the service '''SDS@hd - Scientific Data Storage'''
*# Click '''Register'''
*# Finally, set a service password for authentication on SDS@hd

=== Change Service Password at bwServices ===

→ '''[[Registration/bwForCluster/Helix#Setting_a_New_Service_Password | Setting a New Service Password]]'''