Ubuntu Manpage: ch-convert - Convert an image from one format to another

Provided by: charliecloud-builders_0.38-3_amd64

NAME

       ch-convert - Convert an image from one format to another

SYNOPSIS

          $ ch-convert [-i FMT] [-o FMT] [OPTION ...] IN OUT

DESCRIPTION

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.

--no-xattrs
Ignore xattrs and ACLs when converting. Overrides $CH_XATTRS.

-o, --out-fmt FMT
Output image format is FMT; inferred if omitted.

-q, --quiet
Be quieter; can be repeated. Incompatible with -v. See the FAQ entry on verbosity for details.

-s, --storage DIR
Set the storage directory. Equivalent to the same option for ch-image(1) and ch-run(1).

--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.

--xattrs
Preserve xattrs and ACLs when converting.

IMAGE FORMATS

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. If the output directory
is empty, the conversion should use the directory without overwriting it. If the directory
doesn’t look like an image and isn’t empty, 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.

FORMAT INFERENCE

       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.

EXAMPLES

       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

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

COPYRIGHT

       2014–2023, Triad National Security, LLC and others

0.38                                          2025-04-06 08:24 UTC                                 CH-CONVERT(1)