| CH-RUN(1) | Charliecloud | CH-RUN(1) |
ch-run - Run a command in a Charliecloud container
$ ch-run [OPTION...] NEWROOT CMD [ARG...]
Run command CMD in a Charliecloud container using the flattened and unpacked image directory located at NEWROOT.
In addition to any directories specified by the user with --bind, ch-run has standard host files and directories that are bind-mounted in as well.
The following host files and directories are bind-mounted at the same location in the container. These cannot be disabled.
Three additional bind mounts can be disabled by the user:
By default, different ch-run invocations use different user and mount namespaces (i.e., different containers). While this has no impact on sharing most resources between invocations, there are a few important exceptions. These include:
--join is designed to address this by placing related ch-run commands (the “peer group”) in the same container. This is done by one of the peers creating the namespaces with unshare(2) and the others joining with setns(2).
To do so, we need to know the number of peers and a name for the group. These are specified by additional arguments that can (hopefully) be left at default values in most cases:
Caveats:
ch-run leaves environment variables unchanged, i.e. the host environment is passed through unaltered, except:
This section describes these features.
The default tweaks happen first, and then --set-env and --unset-env in the order specified on the command line. The latter two can be repeated arbitrarily many times, e.g. to add/remove multiple variable sets or add only some variables in a file.
By default, ch-run makes the following environment variable changes:
Thus, we change $HOME to /home/$USER, unless --no-home is specified, in which case it is left unchanged.
Some of these distributions (e.g., Fedora 24) have also dropped /bin from the default $PATH. This is a problem when the guest OS does not have a merged /usr (e.g., Debian 8 “Jessie”). Thus, we add /bin to $PATH if it’s not already present.
Further reading:
The purpose of --set-env=FILE is to set environment variables that cannot be inherited from the host shell, e.g. Dockerfile ENV directives or other build-time configuration. FILE is a host path to provide the greatest flexibility; guest paths can be specified by prepending the image path.
ch-builder2tar(1) lists variables specified at build time in Dockerfiles in the image in file /ch/environment. To set these variables: --set-env=$IMG/ch/environment.
Variable values in FILE replace any already set. If a variable is repeated, the last value wins.
The syntax of FILE is key-value pairs separated by the first equals character (=, ASCII 61), one per line, with optional single straight quotes (', ASCII 39) around the value. Empty lines are ignored. Newlines (ASCII 10) are not permitted in either key or value. No variable expansion, comments, etc. are provided. The value may be empty, but not the key. (This syntax is designed to accept the output of printenv and be easily produced by other simple mechanisms.) Examples of valid lines:
| Line | Key | Value |
| FOO=bar | FOO | bar |
| FOO=bar=baz | FOO | bar=baz |
| FLAGS=-march=foo -mtune=bar | FLAGS | -march=foo -mtune=bar |
| FLAGS='-march=foo -mtune=bar' | FLAGS | -march=foo -mtune=bar |
| FOO= | FOO | (empty string) |
| FOO='' | FOO | (empty string) |
| FOO='''' | FOO | '' (two single quotes) |
Example invalid lines:
| Line | Problem |
| FOO bar | no separator |
| =bar | key cannot be empty |
Example valid lines that are probably not what you want:
| Line | Key | Value | Problem |
| FOO="bar" | FOO | "bar" | double quotes aren’t stripped |
| FOO=bar # baz | FOO | bar # baz | comments not supported |
| PATH=$PATH:/opt/bin | PATH | $PATH:/opt/bin | variables not expanded |
| FOO=bar | FOO | bar | leading space in key |
| FOO= bar | FOO | bar | leading space in value |
The purpose of --unset-env=GLOB is to remove unwanted environment variables. The argument GLOB is a glob pattern (dialect fnmatch(3) with no flags); all variables with matching names are removed from the environment.
WARNING:
GLOB must be a non-empty string.
Example 1: Remove the single environment variable FOO:
$ export FOO=bar $ env | fgrep FOO FOO=bar $ ch-run --unset-env=FOO $CH_TEST_IMGDIR/chtest -- env | fgrep FOO $
Example 2: Hide from a container the fact that it’s running in a Slurm allocation, by removing all variables beginning with SLURM. You might want to do this to test an MPI program with one rank and no launcher:
$ salloc -N1 $ env | egrep '^SLURM' | wc
44 44 1092 $ ch-run $CH_TEST_IMGDIR/mpihello-openmpi -- /hello/hello [... long error message ...] $ ch-run --unset-env='SLURM*' $CH_TEST_IMGDIR/mpihello-openmpi -- /hello/hello 0: MPI version: Open MPI v3.1.3, package: Open MPI root@c897a83f6f92 Distribution, ident: 3.1.3, repo rev: v3.1.3, Oct 29, 2018 0: init ok cn001.localdomain, 1 ranks, userns 4026532530 0: send/receive ok 0: finalize ok
Example 3: Clear the environment completely (remove all variables):
$ ch-run --unset-env='*' $CH_TEST_IMGDIR/chtest -- env $
Note that some programs, such as shells, set some environment variables even if started with no init files:
$ ch-run --unset-env='*' $CH_TEST_IMGDIR/debian9 -- bash --noprofile --norc -c env SHLVL=1 PWD=/ _=/usr/bin/env $
Run the command echo hello inside a Charliecloud container using the unpacked image at /data/foo:
$ ch-run /data/foo -- echo hello hello
Run an MPI job that can use CMA to communicate:
$ srun ch-run --join /data/foo -- bar
If Charliecloud was obtained from your Linux distribution, use your distribution’s bug reporting procedures.
Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues>
Full documentation at: <https://hpc.github.io/charliecloud>
2014–2020, Triad National Security, LLC
| 2020-12-20 14:44 Coordinated Universal Time | 0.21 |