ch-convert - Convert an image from one format to another
$ ch-convert [-i FMT] [-o FMT] [OPTION ...] IN OUT
Copy image IN to OUT and convert its format. Replace
OUT if it already exists, unless --no-clobber is specified. It
is an error if IN and OUT have the same format; use the
format’s own tools for that case.
ch-run can run container images that are plain directories
or (optionally) SquashFS archives. However, images can take on a variety of
other formats as well. The main purpose of this tool is to make images in
those other formats available to ch-run.
For best performance, ch-convert should be invoked only
once, producing the final format actually needed.
- IN
- Descriptor for the input image. For image builders, this is an image
reference; otherwise, it’s a filesystem path.
- OUT
- Descriptor for the output image.
- -h,
--help
- Print help and exit.
- -i, --in-fmt
FMT
- Input image format is FMT. If omitted, inferred as described
below.
- -n,
--dry-run
- Don’t read the input or write the output. Useful for testing format
inference.
- --no-clobber
- Error if OUT already exists, rather than replacing it.
- -o, --out-fmt
FMT
- Output image format is FMT; inferred if omitted.
- --tmp DIR
- A sub-directory for temporary storage is created in DIR and removed
at the end of a successful conversion. If this script crashes or
errors out, the temporary directory is left behind to assist in
debugging. Storage may be needed up to twice the uncompressed size
of the image, depending on the input and output formats. Default:
$TMPDIR if specified; otherwise /var/tmp.
- -v,
--verbose
- Print extra chatter. Can be repeated.
ch-convert knows about these values of FMT:
- ch-image
- Internal storage for Charliecloud’s unprivileged image builder
(Dockerfile interpreter) ch-image.
- dir
- Ordinary filesystem directory (i.e., not a mount point) containing an
unpacked image. Output directories that already exist are replaced if they
look like an image; otherwise, exit with an error.
- docker
- Internal storage for Docker.
- podman
- Internal storage for Podman.
- squash
- SquashFS filesystem archive containing the flattened image. SquashFS
archives are much like tar archives but are mountable, including by
ch-run’s internal SquashFUSE mounting. Most systems have at
least the SquashFS-Tools installed which allows unpacking into a
directory, just like tar. Due to this greater flexibility, SquashFS is
preferred to tar.
Note: Conversions to and from SquashFS are quite noisy
due to the verbosity of the underlying mksquashfs(1) and
unsquashfs(1) tools.
- tar
- Tar archive containing the flattened image with no layer sub-archives;
i.e., the output of docker export works but the output of docker
save does not. Output tarballs are always gzipped and must end in
.tar.gz; input tarballs can be any compression acceptable to
tar(1).
All of these are local formats; ch-convert does not know
how to push or pull images.
ch-convert tries to save typing by guessing formats when
they are reasonably clear. This is done against filenames, rather than file
contents, so the rules are the same for output descriptors that do not yet
exist.
Format inference is done for both IN and OUT. The
first matching glob below yields the inferred format. Paths need not exist
in the filesystem.
- 1.
- *.sqfs, *.squash, *.squashfs: SquashFS.
- 2.
- *.tar, *.t?z, *.tar.?, *.tar.??: Tarball.
- 3.
- /*, ./*, i.e. absolute path or relative path with explicit
dot: Directory.
- 4.
- If ch-image is installed: ch-image internal storage.
- 5.
- If Podman is installed: Podman internal storage.
- 6.
- If Docker is installed: Docker internal storage.
- 7.
- Otherwise: No format inference.
Typical build-to-run sequence for image foo/bar using
ch-run’s internal SquashFUSE code, inferring the output
format:
$ sudo docker build -t foo/bar -f Dockerfile .
[...]
$ ch-convert foo/bar:latest /var/tmp/foobar.sqfs
input: docker foo/bar:latest
output: squashfs /var/tmp/foobar.sqfs
copying ...
done
$ ch-run /var/tmp/foobar.sqfs -- echo hello
hello
Same conversion, but no format inference:
$ ch-convert -i ch-image -o squash foo/bar:latest /var/tmp/foobar.sqfs
input: docker foo/bar:latest
output: squashfs /var/tmp/foobar.sqfs
copying ...
done
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
charliecloud(7)
Full documentation at:
<https://hpc.github.io/charliecloud>
2014–2022, Triad National Security, LLC and others