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.