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.

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

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

SEE ALSO

       charliecloud(7)

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

COPYRIGHT

       2014–2022, Triad National Security, LLC and others