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.

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

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; otherwise, exit with an
                 error.

          docker Internal storage for Docker.

          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 Docker is installed: Docker internal storage.

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

SEE ALSO

       charliecloud(7)

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

COPYRIGHT

       2014–2021, Triad National Security, LLC

0.26                                          2022-01-30 10:06 UTC                                 CH-CONVERT(1)