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          squash SquashFS filesystem archive containing the  flattened  image.
73                 SquashFS  archives  are much like tar archives but are mount‐
74                 able, including by  ch-run’s  internal  SquashFUSE  mounting.
75                 Most systems have at least the SquashFS-Tools installed which
76                 allows unpacking into a directory, just like tar. Due to this
77                 greater flexibility, SquashFS is preferred to tar.
78
79                 Note: Conversions to and from SquashFS are quite noisy due to
80                 the  verbosity  of  the  underlying  mksquashfs(1)  and   un‐
81                 squashfs(1) tools.
82
83          tar    Tar  archive  containing  the  flattened  image with no layer
84                 sub-archives; i.e., the output of docker export works but the
85                 output  of  docker  save does not. Output tarballs are always
86                 gzipped and must end in .tar.gz; input tarballs  can  be  any
87                 compression acceptable to tar(1).
88
89       All of these are local formats; ch-convert does not know how to push or
90       pull images.
91

FORMAT INFERENCE

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

EXAMPLES

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

REPORTING BUGS

138       If  Charliecloud  was  obtained  from your Linux distribution, use your
139       distribution’s bug reporting procedures.
140
141       Otherwise, report bugs to: https://github.com/hpc/charliecloud/issues
142

COPYRIGHT

149       2014–2021, Triad National Security, LLC
150
151
152
153
1540.26                         2022-01-24 00:00 UTC                CH-CONVERT(1)