3. Help text for executables¶
This section contains the --help
output for each of the Charliecloud
exectuables.
3.1. ch-build¶
Wrapper for "docker build" that works around some of its annoying behaviors.
Usage:
$ ch-build [ARGS ...]
ARGS are passed unchanged to "docker build" after the workaround arguments.
Workarounds:
* Add the HTTP proxy environment variables with "--build-arg".
* Default to the Dockerfile in CWD with "--file", if one exists and --file
wasn't already specified, rather than the one at the root of the build
context. This works around Docker's hostility to symlinks (e.g., see
https://github.com/docker/docker/issues/1676).
3.2. ch-build2dir¶
Build a Charliecloud image specified by $PWD/Dockerfile and unpack it.
Equivalent to ch-build, ch-docker2tar, ch-tar2dir sequence but somewhat less
flexible.
Usage:
$ ch-build2dir CONTEXT DEST [ARGS ...]
Arguments:
CONTEXT Docker context directory
DEST Directory in which to place image tarball and directory
ARGS Additional arguments passed to ch-build
You must have sufficient privilege (via sudo) to run the Docker commands.
3.3. ch-docker2tar¶
Flatten a Docker image into a Charliecloud image tarball.
Usage:
$ ch-docker2tar IMAGE OUTDIR
You must have sufficient privilege (via sudo) to run the Docker commands.
3.4. ch-docker-run¶
Run CMD in a Docker container TAG.
Usage:
$ ch-docker-run [-i] [-b HOSTDIR:GUESTDIR ...] TAG CMD [ARGS ...]
The special sauce is:
1. CMD runs as you, not root or whatever is specified in the Dockerfile.
2. Users and groups inside the container match the host.
3. /etc/hosts is patched up to use the network effectively.
Options:
-i Run interactively with a pseudo-TTY
-b Bind-mount HOSTDIR at GUESTDIR inside the container (can be repeated)
You must have sufficient privilege (via sudo) to run the Docker commands.
3.5. ch-run¶
Usage: ch-run [OPTION...] NEWROOT CMD [ARG...]
Run a command in a Charliecloud container.
-b, --bind=SRC[:DST] mount SRC at guest DST (default /mnt/0, /mnt/1, etc.)
-c, --cd=DIR initial working directory in container
-g, --gid=GID run as GID within container
--is-setuid exit successfully if compiled for setuid, else fail
--no-home do not bind-mount your home directory
-t, --private-tmp use container-private /tmp
-u, --uid=UID run as UID within container
-v, --verbose be more verbose (debug if repeated)
-w, --write mount image read-write
-?, --help Give this help list
--usage Give a short usage message
-V, --version print version and exit
Example:
$ ch-run /data/foo -- echo hello
hello
You cannot use this program to actually change your UID.
3.6. ch-ssh¶
Usage: CH_RUN_ARGS="NEWROOT [ARG...]" ch-ssh [OPTION...] HOST CMD [ARG...]
Run a remote command in a Charliecloud container.
Example:
$ export CH_RUN_ARGS=/data/foo
$ ch-ssh example.com -- echo hello
hello
Arguments to ch-run, including the image to activate, are specified in the
CH_RUN_ARGS environment variable. Important caveat: Words in CH_RUN_ARGS are
delimited by spaces only; it is not shell syntax. In particular, quotes and
and backslashes are not interpreted.
3.7. ch-tar2dir¶
Unpack a Docker export tarball into a directory.
Usage:
$ ch-tar2dir TARBALL DIR
Extract the tarball, which must be a Linux filesystem image e.g. from
ch-docker2tar, into a subdirectory of DIR named as the tarball with .tar.gz
removed. For example, if the tarball is foo.tar.gz, unpack into DIR/foo.
If the subdirectory doesn't exist, it is created. If it does exist and appears
to be a Charliecloud container image, it is removed and replaced. Otherwise,
the script aborts with an error.
Warning:
Do not place DIR on a shared filesystem (e.g., your home directory, project
space, scratch) unless specifically instructed by your site admins. Doing so
may cause excess metadata load on the filesystem, resulting in poor
performance for you and everyone else trying to do work at the same time.