ch-convert(1)

1CH-CONVERT(1)                    Charliecloud                    CH-CONVERT(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

12       Copy  image IN to OUT and convert its format. Replace OUT if it already
13       exists, unless --no-clobber is specified. It is an error if IN and  OUT
14       have the same format; use the format’s own tools for that case.
15
16       ch-run  can run container images that are plain directories or (option‐
17       ally) SquashFS archives. However, images can take on a variety of other
18       formats  as  well.  The  main purpose of this tool is to make images in
19       those other formats available to ch-run.
20
21       For best performance, ch-convert should be invoked only once, producing
22       the final format actually needed.
23
24          IN     Descriptor  for  the input image. For image builders, this is
25                 an image reference; otherwise, it’s a filesystem path.
26
27          OUT    Descriptor for the output image.
28
29          -h, --help
30                 Print help and exit.
31
32          -i, --in-fmt FMT
33                 Input image format is FMT. If omitted, inferred as  described
34                 below.
35
36          -n, --dry-run
37                 Don’t  read the input or write the output. Useful for testing
38                 format inference.
39
40          --no-clobber
41                 Error if OUT already exists, rather than replacing it.
42
43          -o, --out-fmt FMT
44                 Output image format is FMT; inferred if omitted.
45
46          --tmp DIR
47                 A sub-directory for temporary storage is created in  DIR  and
48                 removed at the end of a successful conversion. If this script
49                 crashes or errors out, the temporary directory is left behind
50                 to assist in debugging. Storage may be needed up to twice the
51                 uncompressed size of the image, depending on  the  input  and
52                 output  formats.  Default:  $TMPDIR  if  specified; otherwise
53                 /var/tmp.
54
55          -v, --verbose
56                 Print extra chatter. Can be repeated.
57

IMAGE FORMATS

59       ch-convert knows about these values of FMT:
60
61          ch-image
62                 Internal  storage  for  Charliecloud’s   unprivileged   image
63                 builder (Dockerfile interpreter) ch-image.
64
65          dir    Ordinary  filesystem directory (i.e., not a mount point) con‐
66                 taining an unpacked image. Output  directories  that  already
67                 exist  are  replaced  if  they look like an image; otherwise,
68                 exit with an error.
69
70          docker Internal storage for Docker.
71
72          podman Internal storage for Podman.
73
74          squash SquashFS filesystem archive containing the  flattened  image.
75                 SquashFS  archives  are much like tar archives but are mount‐
76                 able, including by  ch-run’s  internal  SquashFUSE  mounting.
77                 Most systems have at least the SquashFS-Tools installed which
78                 allows unpacking into a directory, just like tar. Due to this
79                 greater flexibility, SquashFS is preferred to tar.
80
81                 Note: Conversions to and from SquashFS are quite noisy due to
82                 the  verbosity  of  the  underlying  mksquashfs(1)  and   un‐
83                 squashfs(1) tools.
84
85          tar    Tar  archive  containing  the  flattened  image with no layer
86                 sub-archives; i.e., the output of docker export works but the
87                 output  of  docker  save does not. Output tarballs are always
88                 gzipped and must end in .tar.gz; input tarballs  can  be  any
89                 compression acceptable to tar(1).
90
91       All of these are local formats; ch-convert does not know how to push or
92       pull images.
93

FORMAT INFERENCE

95       ch-convert tries to save typing by guessing formats when they are  rea‐
96       sonably  clear.  This  is done against filenames, rather than file con‐
97       tents, so the rules are the same for output descriptors that do not yet
98       exist.
99
100       Format  inference  is done for both IN and OUT. The first matching glob
101       below yields the inferred format. Paths need not exist in the  filesys‐
102       tem.
103
104          1. *.sqfs, *.squash, *.squashfs: SquashFS.
105
106          2. *.tar, *.t?z, *.tar.?, *.tar.??: Tarball.
107
108          3. /*,  ./*,  i.e. absolute path or relative path with explicit dot:
109             Directory.
110
111          4. If ch-image is installed: ch-image internal storage.
112
113          5. If Podman is installed: Podman internal storage.
114
115          6. If Docker is installed: Docker internal storage.
116
117          7. Otherwise: No format inference.
118

EXAMPLES

120       Typical build-to-run sequence for image foo/bar using ch-run’s internal
121       SquashFUSE code, inferring the output format:
122
123          $ sudo docker build -t foo/bar -f Dockerfile .
124          [...]
125          $ ch-convert foo/bar:latest /var/tmp/foobar.sqfs
126          input:   docker    foo/bar:latest
127          output:  squashfs  /var/tmp/foobar.sqfs
128          copying ...
129          done
130          $ ch-run /var/tmp/foobar.sqfs -- echo hello
131          hello
132
133       Same conversion, but no format inference:
134
135          $ ch-convert -i ch-image -o squash foo/bar:latest /var/tmp/foobar.sqfs
136          input:   docker    foo/bar:latest
137          output:  squashfs  /var/tmp/foobar.sqfs
138          copying ...
139          done
140

REPORTING BUGS

142       If  Charliecloud  was  obtained  from your Linux distribution, use your
143       distribution’s bug reporting procedures.
144
145       Otherwise, report bugs to: https://github.com/hpc/charliecloud/issues
146

COPYRIGHT

153       2014–2022, Triad National Security, LLC and others
154
155
156
157
1580.32                         2023-07-19 00:00 UTC                CH-CONVERT(1)