3. Charliecloud command reference

This section is a comprehensive description of the usage and arguments of the Charliecloud commands. Its content is identical to the commands’ man pages.

3.1. ch-build

Wrapper for docker build that works around some of its annoying behaviors.

3.1.1. Synopsis

$ ch-build -t TAG [ARGS ...] CONTEXT

3.1.2. Description

Build a Docker image named TAG described by Dockerfile ./Dockerfile or as specified. Pass the HTTP proxy environment variables through with --build-arg.

Sudo privileges are required to run the docker command.

Arguments:

--file
Dockerfile to use (default: ./Dockerfile)
-t
name (tag) of Docker image to build
--help
print help and exit
--version
print version and exit

Additional arguments are accepted and passed unchanged to docker build.

3.1.3. Examples

Create a Docker image tagged foo and specified by the file Dockerfile located in the current working directory. Use /bar as the Docker context directory:

$ ch-build -t foo /bar

Equivalent to above:

$ ch-build -t foo --file=./Dockerfile /bar

Instead, use the Dockerfile /baz/qux.docker:

$ ch-build -t foo --file=/baz/qux.docker /bar

Note that calling your Dockerfile anything other than Dockerfile will confuse people.

3.2. ch-build2dir

Build a Charliecloud image from Dockerfile and unpack it.

3.2.1. Synopsis

$ ch-build2dir CONTEXT DEST [ARGS ...]

3.2.2. Description

Build a Docker image as specified by the file Dockerfile in the current working directory and context directory CONTEXT. Unpack it in DEST.

Sudo privileges are required to run the docker command.

This runs the following command sequence: ch-build, ch-docker2tar, and ch-tar2dir but provides less flexibility than the individual commands.

Arguments:

CONTEXT
Docker context directory
DEST
directory in which to place image tarball and directory
ARGS
additional arguments passed to ch-build
--help
print help and exit
--version
print version and exit

3.3. ch-docker2tar

Flatten a Docker image into a Charliecloud image tarball.

3.3.1. Synopsis

$ ch-docker2tar IMAGE OUTDIR

3.3.2. Description

Flattens the Docker image tagged IMAGE into a Charliecloud tarball in directory OUTDIR.

Sudo privileges are required to run docker export.

Additional arguments:

--help
print help and exit
--version
print version and exit

3.3.3. Example

$ ch-docker2tar hello /var/tmp
57M /var/tmp/hello.tar.gz
$ ls -lh /var/tmp
-rw-r-----  1 reidpr reidpr  57M Feb 13 16:14 hello.tar.gz

3.4. ch-docker-run

Run a command in a Docker container.

3.4.1. Synopsis

$ ch-docker-run [-i] [-b HOSTDIR:GUESTDIR ...] TAG CMD [ARGS ...]

3.4.2. Description

Runs the command CMD in a Docker container using the image named TAG.

Sudo privileges are required for docker run.

CMD is run under your user ID. The users and groups inside the container match those on the host.

Note

This command is intended as a convenience for debugging images and Charliecloud. Routine use for running applications is not recommended. Instead, use ch-run.

Arguments:

-i
run interactively with a pseudo-TTY
-b
bind-mount HOSTDIR at GUESTDIR inside the container (can be repeated)
--help
print help and exit
--version
print version and exit

3.5. ch-run

Run a command in a Charliecloud container.

3.5.1. Synopsis

$ ch-run [OPTION...] NEWROOT CMD [ARG...]

3.5.2. Description

Run command CMD in a Charliecloud container using the flattened and unpacked image directory located at NEWROOT.

-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 group GID within container
--is-setuid
exit successfully if compiled for setuid, else fail
--no-home
do not bind-mount your home directory (by default, your home directory is mounted at /home/$USER in the container)
-t, --private-tmp
use container-private /tmp (by default, /tmp is shared with the host)
-u, --uid=UID
run as user UID within container
-v, --verbose
be more verbose (debug if repeated)
-w, --write
mount image read-write (by default, the image is mounted read-only)
-?, --help
print help and exit
--usage
print a short usage message and exit
-V, --version
print version and exit

3.5.3. Example

Run the command echo hello inside a Charliecloud container using the unpacked image at /data/foo:

$ ch-run /data/foo -- echo hello
hello

3.6. ch-ssh

Run a remote command in a Charliecloud container.

3.6.1. Synopsis

$ CH_RUN_ARGS="NEWROOT [ARG...]"
$ ch-ssh [OPTION...] HOST CMD [ARG...]

3.6.2. Description

Runs command CMD in a Charliecloud container on remote host HOST. Use the content of environment variable CH_RUN_ARGS as the arguments to ch-run on the remote host.

Note

Words in CH_RUN_ARGS are delimited by spaces only; it is not shell syntax.

3.6.3. Example

On host bar.example.com, run the command echo hello inside a Charliecloud container using the unpacked image at /data/foo with starting directory /baz:

$ hostname
foo
$ export CH_RUN_ARGS='--cd /baz /data/foo'
$ ch-ssh bar.example.com -- hostname
bar

3.7. ch-tar2dir

Unpack an image tarball into a directory.

3.7.1. Synopsis

$ ch-tar2dir TARBALL DIR

3.7.2. Description

Extract the tarball TARBALL into a subdirectory of DIR. TARBALL must contain a Linux filesystem image, e.g. as created by ch-docker2tar.

Inside DIR, a subdirectory will be created whose name corresponds to the name of the tarball with the .tar.gz suffix removed. If such a directory exists already and appears to be a Charliecloud container image, it is removed and replaced. If the existing directory doesn’t appear to be a container image, the script aborts with an error.

Additional arguments:

--help
print help and exit
--verbose
be more verbose
--version
print version and exit

Warning

Placing DIR on a shared file system can cause significant metadata load on the file system servers. This can result in poor performance for you and all your colleagues who use the same file system. Please consult your site admin for a suitable location.

3.7.3. Example

$ ls -lh /var/tmp
total 57M
-rw-r-----  1 reidpr reidpr  57M Feb 13 16:14 hello.tar.gz
$ ch-tar2dir /var/tmp/hello.tar.gz /var/tmp
creating new image /var/tmp/hello
/var/tmp/hello unpacked ok
$ ls -lh /var/tmp
total 57M
drwxr-x--- 22 reidpr reidpr 4.0K Feb 13 16:29 hello
-rw-r-----  1 reidpr reidpr  57M Feb 13 16:14 hello.tar.gz