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
atGUESTDIR
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 guestDST
(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