From f7a2950680ae0f9292a888cf800a3c1a46ca4bc7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bob=20Dr=C3=B6ge?= Date: Mon, 2 Feb 2026 16:29:10 +0100 Subject: [PATCH] use exec instead of run for eessi_container.sh, update output of eessi_container -h --- docs/getting_access/eessi_container.md | 100 ++++++++++++++----------- 1 file changed, 57 insertions(+), 43 deletions(-) diff --git a/docs/getting_access/eessi_container.md b/docs/getting_access/eessi_container.md index 8777b872cf..b4701a3811 100644 --- a/docs/getting_access/eessi_container.md +++ b/docs/getting_access/eessi_container.md @@ -11,7 +11,7 @@ illustrating the use of the script. - Apptainer 1.0.0 (_or newer_), or Singularity 3.7.x - Check with `apptainer --version` or `singularity --version` - - Support for the `--fusemount` option in the ``shell`` and ``run`` subcommands is required + - Support for the `--fusemount` option in the ``shell`` and ``exec`` subcommands is required - Git - Check with `git --version` @@ -69,41 +69,55 @@ You should see the following output ``` usage: ./eessi_container.sh [OPTIONS] [[--] SCRIPT or COMMAND] OPTIONS: - -a | --access {ro,rw} - ro (read-only), rw (read & write) [default: ro] - -c | --container IMG - image file or URL defining the container to use - [default: docker://ghcr.io/eessi/build-node:debian11] - -g | --storage DIR - directory space on host machine (used for - temporary data) [default: 1. TMPDIR, 2. /tmp] - -h | --help - display this usage information [default: false] - -i | --host-injections - directory to link to for host_injections - [default: /..storage../opt-eessi] - -l | --list-repos - list available repository identifiers [default: false] - -m | --mode MODE - with MODE==shell (launch interactive shell) or - MODE==run (run a script or command) [default: shell] - -n | --nvidia MODE - configure the container to work with NVIDIA GPUs, - MODE==install for a CUDA installation, MODE==run to - attach a GPU, MODE==all for both [default: false] - -r | --repository CFG - configuration file or identifier defining the - repository to use [default: EESSI via - container configuration] - -u | --resume DIR/TGZ - resume a previous run from a directory or tarball, - where DIR points to a previously used tmp directory - (check for output 'Using DIR as tmp ...' of a previous - run) and TGZ is the path to a tarball which is - unpacked the tmp dir stored on the local storage space - (see option --storage above) [default: not set] - -s | --save DIR/TGZ - save contents of tmp directory to a tarball in - directory DIR or provided with the fixed full path TGZ - when a directory is provided, the format of the - tarball's name will be {REPO_ID}-{TIMESTAMP}.tgz - [default: not set] - -v | --verbose - display more information [default: false] - -x | --http-proxy URL - provides URL for the env variable http_proxy - [default: not set]; uses env var $http_proxy if set - -y | --https-proxy URL - provides URL for the env variable https_proxy - [default: not set]; uses env var $https_proxy if set - - If value for --mode is 'run', the SCRIPT/COMMAND provided is executed. If + -a | --access {ro,rw} - sets access globally for all CVMFS repositories: + ro (read-only), rw (read & write) [default: ro] + -b | --extra-bind-paths - specify extra paths to be bound into the container. + To specify multiple bind paths, separate by comma. + Example: '/src:/dest:ro,/src2:/dest2:rw' + -c | --container IMG - image file or URL defining the container to use + [default: docker://ghcr.io/eessi/build-node:debian12] + -f | --fakeroot - run the container with --fakeroot [default: false] + -g | --storage DIR - directory space on host machine (used for + temporary data) [default: 1. TMPDIR, 2. /tmp] + -h | --help - display this usage information [default: false] + -i | --host-injections - directory to link to for host_injections + [default: /..storage../opt-eessi] + -l | --list-repos - list available repository identifiers [default: false] + -m | --mode MODE - with MODE==shell (launch interactive shell) or + MODE==exec/run (run a script or command) [default: shell] + -n | --nvidia MODE - configure the container to work with NVIDIA GPUs, + MODE==install for a CUDA installation, MODE==run to + attach a GPU, MODE==all for both [default: false] + -o | --overlay-tool ARG - tool to use to create (read-only or writable) overlay; + selected tool *must* be available in container image being used; + can be 'fuse-overlayfs' or 'unionfs' [default: unionfs] + -p | --pass-through ARG - argument to pass through to the launch of the + container; can be given multiple times [default: not set] + -r | --repository CFG - configuration file or identifier defining the + repository to use; can be given multiple times; + CFG may include suffixes ',access={ro,rw},mode={bind,fuse}' to + overwrite the global access and/or mount mode for this repository; + use 'None' to not mount any repositories + [default: software.eessi.io via CVMFS config available + via default container, see --container] + -u | --resume DIR/TGZ - resume a previous run from a directory or tarball, + where DIR points to a previously used tmp directory + (check for output 'Using DIR as tmp ...' of a previous + run) and TGZ is the path to a tarball which is + unpacked the tmp dir stored on the local storage space + (see option --storage above) [default: not set] + -s | --save DIR/TGZ - save contents of tmp directory to a tarball in + directory DIR or provided with the fixed full path TGZ + when a directory is provided, the format of the + tarball's name will be {REPO_ID}-{TIMESTAMP}.tgz + [default: not set] + -v | --verbose - display more information [default: false] + -x | --http-proxy URL - provides URL for the env variable http_proxy + [default: not set]; uses env var $http_proxy if set + -y | --https-proxy URL - provides URL for the env variable https_proxy + [default: not set]; uses env var $https_proxy if set + + If value for --mode is 'exec' or 'run', the SCRIPT/COMMAND provided is executed. If arguments to the script/command start with '-' or '--', use the flag terminator '--' to let eessi_container.sh stop parsing arguments. ``` @@ -158,7 +172,7 @@ Let's "`ls /cvmfs/software.eessi.io`" through the `eessi_container.sh` script to check if the CernVM-FS EESSI repository is accessible: ``` { .bash .copy } -./eessi_container.sh --mode run ls /cvmfs/software.eessi.io +./eessi_container.sh --mode exec ls /cvmfs/software.eessi.io ``` You should see an output such as @@ -177,7 +191,7 @@ Note that this time no interactive shell session is started in the container: only the provided command is run in the container, and when that finishes you are back in the shell session where you ran the `eessi_container.sh` script. -This is because we used the `--mode run` command line option. +This is because we used the `--mode exec` command line option. !!! Note The last line in the output is the output of the `ls` command, @@ -194,7 +208,7 @@ CMD="ls -l /cvmfs/software.eessi.io" ``` !!! Note - We changed the mode from `run` to `shell` because we use a different method + We changed the mode from `exec` to `shell` because we use a different method to let the script run _our_ command, by feeding it in via the `stdin` input channel using `<<<`. Because `shell` is the default value for `--mode` we can also omit this and @@ -289,7 +303,7 @@ linux/x86_64/intel/skylake_avx512 ``` Lines 7 to 20 show the output of the script `eessi_architectures.sh`. -If you want to use the mode `run`, you have to make the script's location +If you want to use the mode `exec`, you have to make the script's location available inside the container. This can be done by mapping the current directory (`${PWD}`), @@ -299,13 +313,13 @@ inside the container using the `$SINGULARITY_BIND` or For example: ``` { .bash .copy } -SINGULARITY_BIND=${PWD}:/scripts ./eessi_container.sh --mode run /scripts/eessi_architectures.sh +SINGULARITY_BIND=${PWD}:/scripts ./eessi_container.sh --mode exec /scripts/eessi_architectures.sh ``` ## Running scripts or commands with parameters starting with `-` or `--` Let's assume we would like to get more information about the entries of `/cvmfs/software.eessi.io`. If we would just run ``` { .bash .copy } -./eessi_container.sh --mode run ls -lH /cvmfs/software.eessi.io +./eessi_container.sh --mode exec ls -lH /cvmfs/software.eessi.io ``` we would get an error message such as ``` { .bash .no-copy } @@ -335,7 +349,7 @@ We can resolve this in two ways: 2. Using the flag terminator `--` which tells `eessi_container.sh` to stop parsing command line arguments. For example, ``` { .bash .copy } - ./eessi_container.sh --mode run -- ls -lH /cvmfs/software.eessi.io + ./eessi_container.sh --mode exec -- ls -lH /cvmfs/software.eessi.io ``` which should result in the output similar to ``` { .yaml .no-copy }