Scroll to navigation

CH-TUG(1) Charliecloud CH-TUG(1)

NAME

ch-tug - Pull and flatten image from repository to local filesystem

SYNOPSIS

$ ch-tug [OPTIONS] IMAGE_REF


DESCRIPTION

WARNING:

This script is experimental. Please report the bugs you find so we can fix them!


Pull the image described by IMAGE_REF from a repository by HTTPS and flatten it to a local filesystem. The resulting image directory can be used by ch-run(1) or feed into other processing.

This script does a fair amount of validation and fixing of the layer tarballs before flattening in order to support unprivileged use despite image problems we frequently see in the wild. For example, device files are ignored, and file and directory permissions are increased to a minimum of rwx------ and rw------- respectively. Note, however, that symlinks pointing outside the image are permitted, because they are not resolved until runtime within a container.

Typically this script is not used directly. Most tasks instead use the underlying code during image build with ch-grow(1).

Other arguments:

Print help and exit.
Report any dependency problems and exit. If all is well, there is no output and the exit code is zero; in case of problems, the exit code is non-zero.
Use DIR to store downloaded layers and metadata. If not specified but environment variable CH_GROW_STORAGE is, then use $CH_GROW_STORAGE/dlcache; the default is /var/tmp/$USER/ch-grow/dlcache.
Always download files, even if they already exist in --dl-cache.
Subdirectory of --unpack-dir to hold the flattened image. Can be the empty string, in which case --unpack-dir is used directly. The default is IMAGE_REF with slashes replaced by percent signs.
Parse IMAGE_REF, print a parse report, and exit successfully.
Directory containing flattened images. If not specified but environment variable CH_GROW_STORAGE is, then use $CH_GROW_STORAGE/img; the default is /var/tmp/$USER/ch-grow/img.
Print extra chatter; can be repeated.
Print version number and exit.



EXAMPLES

Download the classic Docker “hello-world” image and flatten it into /var/tmp/$USER/ch-grow/img/hello-world:

$ ch-tug hello-world
pulling image: hello-world
manifest: downloading
layer 1/1: 1b930d0: downloading
layer 1/1: 1b930d0: listing
validating tarball members
resolving whiteouts
flattening image
creating new image: /var/tmp/charlie/ch-grow/img/hello-world
layer 1/1: 1b930d0: extracting
done
$ ls /var/tmp/$USER/ch-grow/img/hello-world
hello
$ ls /var/tmp/$USER/ch-grow/dlcache
1b930d010525941c1d56ec53b97bd057a67ae1865eebf042686d2a2d18271ced.tar.gz
hello-world.manifest.json


Download the image “charliecloud/whiteout:2020-01-10” and flatten it:

$ ch-tug charliecloud/whiteout:2020-01-10
pulling image: charliecloud/whiteout:2020-01-10
manifest: downloading
layer 1/86: e7c96db: downloading
layer 2/86: 4816f76: downloading
[...]
layer 85/86: 59b7abe: extracting
layer 86/86: e756ca6: extracting
done
$ ls /var/tmp/$USER/ch-grow/img
charliecloud%whiteout:2020-01-10


Download the “hello-world” image and flatten it into /tmp/foo:

$ ch-tug --unpack-dir=/tmp --image-subdir=foo hello-world
[...]
$ ls /tmp/foo
hello


Same as above:

$ ch-tug --unpack-dir=/tmp/foo --image-subdir='' hello-world
[...]
$ ls /tmp/foo
hello


REPORTING BUGS

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>

SEE ALSO

charliecloud(1)

Full documentation at: <https://hpc.github.io/charliecloud>

COPYRIGHT

2014–2020, Triad National Security, LLC

2020-08-22 18:37 Coordinated Universal Time 0.18