1CH-IMAGE(1) Charliecloud CH-IMAGE(1)
2
6 ch-image - Build and manage images; completely unprivileged
7
9 $ ch-image [...] build [-t TAG] [-f DOCKERFILE] [...] CONTEXT
10 $ ch-image [...] delete IMAGE_REF
11 $ ch-image [...] import PATH IMAGE_REF
12 $ ch-image [...] list [IMAGE_REF]
13 $ ch-image [...] pull [...] IMAGE_REF [IMAGE_DIR]
14 $ ch-image [...] push [--image DIR] IMAGE_REF [DEST_REF]
15 $ ch-image [...] reset
16 $ ch-image [...] storage-path
17 $ ch-image { --help | --version | --dependencies }
18
20 ch-image is a tool for building and manipulating container images, but
21 not running them (for that you want ch-run). It is completely unprivi‐
22 leged, with no setuid/setgid/setcap helpers. The action to take is
23 specified by a sub-command.
24 Options that print brief information and then exit:
26 -h, --help
28 Print help and exit successfully. If specified before the
29 sub-command, print general help and list of sub-commands; if
30 after the sub-command, print help specific to that sub-com‐
31 mand.
32 --dependencies
34 Report dependency problems on standard output, if any, and
35 exit. If all is well, there is no output and the exit is suc‐
36 cessful; in case of problems, the exit is unsuccessful.
37 --version
39 Print version number and exit successfully.
40 Common options placed before the sub-command:
42 -a, --arch ARCH
44 Use ARCH for architecture-aware registry operations, cur‐
45 rently pull and pulls done within build. ARCH can be: (1)
46 yolo, to bypass architecture-aware code and use the reg‐
47 istry’s default architecture; (2) host, to use the host’s ar‐
48 chitecture, obtained with the equivalent of uname -m (default
49 if --arch not specified); or (3) an architecture name. If the
50 specified architecture is not available, the error message
51 will list which ones are.
52 Notes:
54 1. ch-image is limited to one image per image reference in
56 builder storage at a time, regardless of architecture. For
57 example, if you say ch-image pull --arch=foo baz and then
58 ch-image pull --arch=bar baz, builder storage will contain
59 one image called “baz”, with architecture “bar”.
60 2. Images’ default architecture is usually amd64, so this is
62 usually what you get with --arch=yolo. Similarly, if a
63 registry image is architecture-unaware, it will still be
64 pulled with --arch=amd64 and --arch=host on x86-64 hosts
65 (other host architectures must specify --arch=yolo to pull
66 architecture-unaware images).
67 3. uname -m and image registries often use different names
69 for the same architecture. For example, what uname -m re‐
70 ports as “x86_64” is known to registries as “amd64”.
71 --arch=host should translate if needed, but it’s useful to
72 know this is happening. Directly specified architecture
73 names are passed to the registry without translation.
74 4. Registries treat architecture as a pair of items, archi‐
76 tecture and sometimes variant (e.g., “arm” and “v7”).
77 Charliecloud treats architecture as a simple string and
78 converts to/from the registry view transparently.
79 --no-cache
81 Download everything needed, ignoring the cache.
82 --password-many
84 Re-prompt the user every time a registry password is needed.
85 -s, --storage DIR
87 Set the storage directory (see below for important details).
88 --tls-no-verify
90 Don’t verify TLS certificates of the repository. (Do not use
91 this option unless you understand the risks.)
92 -v, --verbose
94 Print extra chatter; can be repeated.
95
97 If the remote repository needs authentication, Charliecloud will prompt
98 you for a username and password. Note that some repositories call the
99 secret something other than “password”; e.g., GitLab calls it a “per‐
100 sonal access token (PAT)”.
101 These values are remembered for the life of the process and silently
103 re-offered to the registry if needed. One case when this happens is on
104 push to a private registry: many registries will first offer a
105 read-only token when ch-image checks if something exists, then re-au‐
106 thenticate when upgrading the token to read-write for upload. If your
107 site uses one-time passwords such as provided by a security device, you
108 can specify --password-many to provide a new secret each time.
109 These values are not saved persistently, e.g. in a file. Note that we
111 do use normal Python variables for this information, without pinning
112 them into physical RAM with mlock(2) or any other special treatment, so
113 we cannot guarantee they will never reach non-volatile storage.
114 There is no separate login subcommand like Docker. For non-interactive
116 authentication, you can use environment variables CH_IMAGE_USERNAME and
117 CH_IMAGE_PASSWORD. Only do this if you fully understand the implica‐
118 tions for your specific use case, because it is difficult to securely
119 store secrets in environment variables.
120
122 ch-image maintains state using normal files and directories located in
123 its storage directory; contents include temporary images used for
124 building and various caches.
125 In descending order of priority, this directory is located at:
127 -s, --storage DIR
129 Command line option.
130 $CH_IMAGE_STORAGE
132 Environment variable.
133 /var/tmp/$USER.ch
135 Default. (Previously, the default was /var/tmp/$USER/ch-im‐
136 age. If a valid storage directory is found at the old default
137 path, ch-image tries to move it to the new default path.)
138 Unlike many container implementations, there is no notion of storage
140 drivers, graph drivers, etc., to select and/or configure.
141 The storage directory can reside on any filesystem. However, it con‐
143 tains lots of small files and metadata traffic can be intense. For ex‐
144 ample, the Charliecloud test suite uses approximately 400,000 files and
145 directories in the storage directory as of this writing. Place it on a
146 filesystem appropriate for this; tmpfs’es such as /var/tmp are a good
147 choice if you have enough RAM (/tmp is not recommended because ch-run
148 bind-mounts it into containers by default).
149 While you can currently poke around in the storage directory and find
151 unpacked images runnable with ch-run, this is not a supported use case.
152 The supported workflow uses ch-convert to obtain a packed image; see
153 the tutorial for details.
154 The storage directory format changes on no particular schedule. Often
156 ch-image is able to upgrade the directory; however, downgrading is not
157 supported and sometimes upgrade is not possible. In these cases, ch-im‐
158 age will refuse to run until you delete and re-initialize the directory
159 with ch-image reset.
160 WARNING:
162 Network filesystems, especially Lustre, are typically bad choices
163 for the storage directory. This is a site-specific question and your
164 local support will likely have strong opinions.
165
167 Build an image from a Dockerfile and put it in the storage directory.
168 Synopsis
170 $ ch-image [...] build [-t TAG] [-f DOCKERFILE] [...] CONTEXT
171 Description
173 Uses ch-run -w -u0 -g0 --no-home --no-passwd to execute RUN instruc‐
174 tions. Note that FROM implicitly pulls the base image if needed, so you
175 may want to read about the pull subcommand below as well.
176 Required argument:
178 CONTEXT
180 Path to context directory. This is the root of COPY instruc‐
181 tions in the Dockerfile. If a single hyphen (-) is specified:
182 (a) read the Dockerfile from standard input, (b) specifying
183 --file is an error, and (c) there is no context, so COPY will
184 fail. (See --file for how to provide the Dockerfile on stan‐
185 dard input while also having a context.)
186 Options:
188 -b, --bind SRC[:DST]
190 For RUN instructions only, bind-mount SRC at guest DST. The
191 default destination if not specified is to use the same path
192 as the host; i.e., the default is equivalent to
193 --bind=SRC:SRC. If DST does not exist, try to create it as an
194 empty directory, though images do have ten directories
195 /mnt/[0-9] already available as mount points. Can be re‐
196 peated.
197 Note: See documentation for ch-run --bind for important
199 caveats and gotchas.
200 Note: Other instructions that modify the image filesystem,
202 e.g. COPY, can only access host files from the context di‐
203 rectory, regardless of this option.
204 --build-arg KEY[=VALUE]
206 Set build-time variable KEY defined by ARG instruction to
207 VALUE. If VALUE not specified, use the value of environment
208 variable KEY.
209 -f, --file DOCKERFILE
211 Use DOCKERFILE instead of CONTEXT/Dockerfile. If a single hy‐
212 phen (-) is specified, read the Dockerfile from standard in‐
213 put; like docker build, the context directory is still avail‐
214 able in this case.
215 --force
217 Inject the unprivileged build workarounds; see discussion
218 later in this section for details on what this does and when
219 you might need it. If a build fails and ch-image thinks
220 --force would help, it will suggest it.
221 -n, --dry-run
223 Don’t actually execute any Dockerfile instructions.
224 --no-force-detect
226 Don’t try to detect if the workarounds in --force would help.
227 --parse-only
229 Stop after parsing the Dockerfile.
230 -t, --tag TAG
232 Name of image to create. If not specified, infer the name:
233 1. If Dockerfile named Dockerfile with an extension: use the
235 extension with invalid characters stripped, e.g. Docker‐
236 file.@FOO.bar → foo.bar.
237 2. If Dockerfile has extension dockerfile: use the basename
239 with the same transformation, e.g. baz.@QUX.dockerfile ->
240 baz.qux.
241 3. If context directory is not /: use its name, i.e. the last
243 component of the absolute path to the context directory,
244 with the same transformation,
245 4. Otherwise (context directory is /): use root.
247 If no colon present in the name, append :latest.
249 Privilege model
251 ch-image is a fully unprivileged image builder. It does not use any se‐
252 tuid or setcap helper programs, and it does not use configuration files
253 /etc/subuid or /etc/subgid. This contrasts with the “rootless” or “‐
254 fakeroot” modes of some competing builders, which do require privileged
255 supporting code or utilities.
256 This approach does yield some quirks. We provide built-in workarounds
258 that should mostly work (i.e., --force), but it can be helpful to un‐
259 derstand what is going on.
260 ch-image executes all instructions as the normal user who invokes it.
262 For RUN, this is accomplished with ch-run -w --uid=0 --gid=0 (and some
263 other arguments), i.e., your host EUID and EGID both mapped to zero in‐
264 side the container, and only one UID (zero) and GID (zero) are avail‐
265 able inside the container. Under this arrangement, processes running in
266 the container for each RUN appear to be running as root, but many priv‐
267 ileged system calls will fail without the workarounds described below.
268 This affects any fully unprivileged container build, not just Char‐
269 liecloud.
270 The most common time to see this is installing packages. For example,
272 here is RPM failing to chown(2) a file, which makes the package update
273 fail:
274 Updating : 1:dbus-1.10.24-13.el7_6.x86_64 2/4
276 Error unpacking rpm package 1:dbus-1.10.24-13.el7_6.x86_64
277 error: unpacking of archive failed on file /usr/libexec/dbus-1/dbus-daemon-launch-helper;5cffd726: cpio: chown
278 Cleanup : 1:dbus-libs-1.10.24-12.el7.x86_64 3/4
279 error: dbus-1:1.10.24-13.el7_6.x86_64: install failed
280 This one is (ironically) apt-get failing to drop privileges:
282 E: setgroups 65534 failed - setgroups (1: Operation not permitted)
284 E: setegid 65534 failed - setegid (22: Invalid argument)
285 E: seteuid 100 failed - seteuid (22: Invalid argument)
286 E: setgroups 0 failed - setgroups (1: Operation not permitted)
287 By default, nothing is done to avoid these problems, though ch-image
289 does try to detect if the workarounds could help. --force activates the
290 workarounds: ch-image injects extra commands to intercept these system
291 calls and fake a successful result, using fakeroot(1). There are three
292 basic steps:
293 1. After FROM, analyze the image to see what distribution it con‐
295 tains, which determines the specific workarounds.
296 2. Before the user command in the first RUN instruction where the
298 injection seems needed, install fakeroot(1) in the image, if one
299 is not already installed, as well as any other necessary initial‐
300 ization commands. For example, we turn off the apt sandbox (for
301 Debian Buster) and configure EPEL but leave it disabled (for Cen‐
302 tOS/RHEL).
303 3. Prepend fakeroot to RUN instructions that seem to need it, e.g.
305 ones that contain apt, apt-get, dpkg for Debian derivatives and
306 dnf, rpm, or yum for RPM-based distributions.
307 The details are specific to each distribution. ch-image analyzes image
309 content (e.g., grepping /etc/debian_version) to select a configuration;
310 see lib/fakeroot.py for details. ch-image prints exactly what it is do‐
311 ing.
312 Compatibility with other Dockerfile interpreters
314 ch-image is an independent implementation and shares no code with other
315 Dockerfile interpreters. It uses a formal Dockerfile parsing grammar
316 developed from the Dockerfile reference documentation and miscellaneous
317 other sources, which you can examine in the source code.
318 We believe this independence is valuable for several reasons. First, it
320 helps the community examine Dockerfile syntax and semantics critically,
321 think rigorously about what is really needed, and build a more robust
322 standard. Second, it yields disjoint sets of bugs (note that Podman,
323 Buildah, and Docker all share the same Dockerfile parser). Third, be‐
324 cause it is a much smaller code base, it illustrates how Dockerfiles
325 work more clearly. Finally, it allows straightforward extensions if
326 needed to support scientific computing.
327 ch-image tries hard to be compatible with Docker and other inter‐
329 preters, though as an independent implementation, it is not bug-compat‐
330 ible.
331 The following subsections describe differences from the Dockerfile ref‐
333 erence that we expect to be approximately permanent. For not-yet-imple‐
334 mented features and bugs in this area, see related issues on GitHub.
335 None of these are set in stone. We are very interested in feedback on
337 our assessments and open questions. This helps us prioritize new fea‐
338 tures and revise our thinking about what is needed for HPC containers.
339 Context directory
341 The context directory is bind-mounted into the build, rather than
342 copied like Docker. Thus, the size of the context is immaterial, and
343 the build reads directly from storage like any other local process
344 would. However, you still can’t access anything outside the context di‐
345 rectory.
346 Variable substitution
348 Variable substitution happens for all instructions, not just the ones
349 listed in the Dockerfile reference.
350 ARG and ENV cause cache misses upon definition, in contrast with Docker
352 where these variables miss upon use, except for certain cache-excluded
353 variables that never cause misses, listed below.
354 ch-image passes the following proxy environment variables in to the
356 build. Changes to these variables do not cause a cache miss. They do
357 not require an ARG instruction, as documented in the Dockerfile refer‐
358 ence. Unlike Docker, they are available if the same-named environment
359 variable is defined; --build-arg is not required.
360 HTTP_PROXY
362 http_proxy
363 HTTPS_PROXY
364 https_proxy
365 FTP_PROXY
366 ftp_proxy
367 NO_PROXY
368 no_proxy
369 In addition to those listed in the Dockerfile reference, these environ‐
371 ment variables are passed through in the same way:
372 SSH_AUTH_SOCK
374 USER
375 Finally, these variables are also pre-defined but are unrelated to the
377 host environment:
378 PATH=/ch/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
380 TAR_OPTIONS=--no-same-owner
381 Note that ARG and ENV have different syntax despite very similar seman‐
383 tics.
384 COPY
386 Especially for people used to UNIX cp(1), the semantics of the Docker‐
387 file COPY instruction can be confusing.
388 Most notably, when a source of the copy is a directory, the contents of
390 that directory, not the directory itself, are copied. This is docu‐
391 mented, but it’s a real gotcha because that’s not what cp(1) does, and
392 it means that many things you can do in one cp(1) command require mul‐
393 tiple COPY instructions.
394 Also, the reference documentation is incomplete. In our experience,
396 Docker also behaves as follows; ch-image does the same in an attempt to
397 be bug-compatible.
398 1. You can use absolute paths in the source; the root is the context
400 directory.
401 2. Destination directories are created if they don’t exist in the fol‐
403 lowing situations:
404 1. If the destination path ends in slash. (Documented.)
406 2. If the number of sources is greater than 1, either by wildcard or
408 explicitly, regardless of whether the destination ends in slash.
409 (Not documented.)
410 3. If there is a single source and it is a directory. (Not docu‐
412 mented.)
413 3. Symbolic links behave differently depending on how deep in the
415 copied tree they are. (Not documented.)
416 1. Symlinks at the top level — i.e., named as the destination or the
418 source, either explicitly or by wildcards — are dereferenced.
419 They are followed, and whatever they point to is used as the des‐
420 tination or source, respectively.
421 2. Symlinks at deeper levels are not dereferenced, i.e., the symlink
423 itself is copied.
424 4. If a directory appears at the same path in source and destination,
426 and is at the 2nd level or deeper, the source directory’s metadata
427 (e.g., permissions) are copied to the destination directory. (Not
428 documented.)
429 5. If an object appears in both the source and destination, and is at
431 the 2nd level or deeper, and is of different types in the source and
432 destination, then the source object will overwrite the destination
433 object. (Not documented.) For example, if /tmp/foo/bar is a regular
434 file, and /tmp is the context directory, then the following Docker‐
435 file snippet will result in a file in the container at /foo/bar
436 (copied from /tmp/foo/bar); the directory and all its contents will
437 be lost.
438 RUN mkdir -p /foo/bar && touch /foo/bar/baz
440 COPY foo /foo
441 We expect the following differences to be permanent:
443 • Wildcards use Python glob semantics, not the Go semantics.
445 • COPY --chown is ignored, because it doesn’t make sense in an unprivi‐
447 leged build.
448 Features we do not plan to support
450 • Parser directives are not supported. We have not identified a need
451 for any of them.
452 • EXPOSE: Charliecloud does not use the network namespace, so con‐
454 tainerized processes can simply listen on a host port like other un‐
455 privileged processes.
456 • HEALTHCHECK: This instruction’s main use case is monitoring server
458 processes rather than applications. Also, implementing it requires a
459 container supervisor daemon, which we have no plans to add.
460 • MAINTAINER is deprecated.
462 • STOPSIGNAL requires a container supervisor daemon process, which we
464 have no plans to add.
465 • USER does not make sense for unprivileged builds.
467 • VOLUME: This instruction is not currently supported. Charliecloud has
469 good support for bind mounts; we anticipate that it will continue to
470 focus on that and will not introduce the volume management features
471 that Docker has.
472 Examples
474 Build image bar using ./foo/bar/Dockerfile and context directory
475 ./foo/bar:
476 $ ch-image build -t bar -f ./foo/bar/Dockerfile ./foo/bar
478 [...]
479 grown in 4 instructions: bar
480 Same, but infer the image name and Dockerfile from the context direc‐
482 tory path:
483 $ ch-image build ./foo/bar
485 [...]
486 grown in 4 instructions: bar
487 Build using humongous vendor compilers you want to bind-mount instead
489 of installing into the image:
490 $ ch-image build --bind /opt/bigvendor:/opt .
492 $ cat Dockerfile
493 FROM centos:7
494 RUN /opt/bin/cc hello.c
496 #COPY /opt/lib/*.so /usr/local/lib # fail: COPY doesn't bind mount
497 RUN cp /opt/lib/*.so /usr/local/lib # possible workaround
498 RUN ldconfig
499
501 $ ch-image [...] delete IMAGE_REF
502 Delete the image described by the image reference IMAGE_REF from the
504 storage directory.
505
507 Print information about images. If no argument given, list the images
508 in builder storage.
509 Synopsis
511 $ ch-image [...] list [IMAGE_REF]
512 Description
514 Optional argument:
515 IMAGE_REF
517 Print details of what’s known about IMAGE_REF, both locally
518 and in the remote registry, if any.
519 Examples
521 List images in builder storage:
522 $ ch-image list
524 alpine:3.9 (amd64)
525 alpine:latest (amd64)
526 debian:buster (amd64)
527 Print details about Debian Buster image:
529 $ ch-image list debian:buster
531 details of image: debian:buster
532 in local storage: no
533 full remote ref: registry-1.docker.io:443/library/debian:buster
534 available remotely: yes
535 remote arch-aware: yes
536 host architecture: amd64
537 archs available: 386 amd64 arm/v5 arm/v7 arm64/v8 mips64le ppc64le s390x
538
540 $ ch-image [...] import PATH IMAGE_REF
541 Copy the image at PATH into builder storage with name IMAGE_REF. PATH
543 can be:
544 • an image directory
546 • a tarball with no top-level directory (a.k.a. a “tarbomb”)
548 • a standard tarball with one top-level directory
550 If the imported image contains Charliecloud metadata, that will be im‐
552 ported unchanged, i.e., images exported from ch-image builder storage
553 will be functionally identical when re-imported.
554
556 Pull the image described by the image reference IMAGE_REF from a repos‐
557 itory to the local filesystem.
558 Synopsis
560 $ ch-image [...] pull [...] IMAGE_REF [IMAGE_DIR]
561 See the FAQ for the gory details on specifying image references.
563 Description
565 Destination:
566 IMAGE_DIR
568 If specified, place the unpacked image at this path; it is
569 then ready for use by ch-run or other tools. The storage di‐
570 rectory will not contain a copy of the image, i.e., it is
571 only unpacked once.
572 Options:
574 --last-layer N
576 Unpack only N layers, leaving an incomplete image. This op‐
577 tion is intended for debugging.
578 --parse-only
580 Parse IMAGE_REF, print a parse report, and exit successfully
581 without talking to the internet or touching the storage di‐
582 rectory.
583 This script does a fair amount of validation and fixing of the layer
585 tarballs before flattening in order to support unprivileged use despite
586 image problems we frequently see in the wild. For example, device files
587 are ignored, and file and directory permissions are increased to a min‐
588 imum of rwx------ and rw------- respectively. Note, however, that sym‐
589 links pointing outside the image are permitted, because they are not
590 resolved until runtime within a container.
591 The following metadata in the pulled image is retained; all other meta‐
593 data is currently ignored. (If you have a need for additional metadata,
594 please let us know!)
595 • Current working directory set with WORKDIR is effective in down‐
597 stream Dockerfiles.
598 • Environment variables set with ENV are effective in downstream
600 Dockerfiles and also written to /ch/environment for use in ch-run
601 --set-env.
602 • Mount point directories specified with VOLUME are created in the
604 image if they don’t exist, but no other action is taken.
605 Note that some images (e.g., those with a “version 1 manifest”) do not
607 contain metadata. A warning is printed in this case.
608 Examples
610 Download the Debian Buster image matching the host’s architecture and
611 place it in the storage directory:
612 $ uname -m
614 aarch32
615 pulling image: debian:buster
616 requesting arch: arm64/v8
617 manifest list: downloading
618 manifest: downloading
619 config: downloading
620 layer 1/1: c54d940: downloading
621 flattening image
622 layer 1/1: c54d940: listing
623 validating tarball members
624 resolving whiteouts
625 layer 1/1: c54d940: extracting
626 image arch: arm64
627 done
628 Same, specifying the architecture explicitly:
630 $ ch-image --arch=arm/v7 pull debian:buster
632 pulling image: debian:buster
633 requesting arch: arm/v7
634 manifest list: downloading
635 manifest: downloading
636 config: downloading
637 layer 1/1: 8947560: downloading
638 flattening image
639 layer 1/1: 8947560: listing
640 validating tarball members
641 resolving whiteouts
642 layer 1/1: 8947560: extracting
643 image arch: arm (may not match host arm64/v8)
644 Download the same image and place it in /tmp/buster:
646 $ ch-image pull debian:buster /tmp/buster
648 [...]
649 $ ls /tmp/buster
650 bin dev home lib64 mnt proc run srv tmp var
651 boot etc lib media opt root sbin sys usr
652
654 Push the image described by the image reference IMAGE_REF from the lo‐
655 cal filesystem to a repository.
656 Synopsis
658 $ ch-image [...] push [--image DIR] IMAGE_REF [DEST_REF]
659 See the FAQ for the gory details on specifying image references.
661 Description
663 Destination:
664 DEST_REF
666 If specified, use this as the destination image reference,
667 rather than IMAGE_REF. This lets you push to a repository
668 without permanently adding a tag to the image.
669 Options:
671 --image DIR
673 Use the unpacked image located at DIR rather than an image in
674 the storage directory named IMAGE_REF.
675 Because Charliecloud is fully unprivileged, the owner and group of
677 files in its images are not meaningful in the broader ecosystem. Thus,
678 when pushed, everything in the image is flattened to user:group
679 root:root. Also, setuid/setgid bits are removed, to avoid surprises if
680 the image is pulled by a privileged container implementation.
681 Examples
683 Push a local image to the registry example.com:5000 at path /foo/bar
684 with tag latest. Note that in this form, the local image must be named
685 to match that remote reference.
686 $ ch-image push example.com:5000/foo/bar:latest
688 pushing image: example.com:5000/foo/bar:latest
689 layer 1/1: gathering
690 layer 1/1: preparing
691 preparing metadata
692 starting upload
693 layer 1/1: a1664c4: checking if already in repository
694 layer 1/1: a1664c4: not present, uploading
695 config: 89315a2: checking if already in repository
696 config: 89315a2: not present, uploading
697 manifest: uploading
698 cleaning up
699 done
700 Same, except use local image alpine:3.9. In this form, the local image
702 name does not have to match the destination reference.
703 $ ch-image push alpine:3.9 example.com:5000/foo/bar:latest
705 pushing image: alpine:3.9
706 destination: example.com:5000/foo/bar:latest
707 layer 1/1: gathering
708 layer 1/1: preparing
709 preparing metadata
710 starting upload
711 layer 1/1: a1664c4: checking if already in repository
712 layer 1/1: a1664c4: not present, uploading
713 config: 89315a2: checking if already in repository
714 config: 89315a2: not present, uploading
715 manifest: uploading
716 cleaning up
717 done
718 Same, except use unpacked image located at /var/tmp/image rather than
720 an image in ch-image storage. (Also, the sole layer is already present
721 in the remote registry, so we don’t upload it again.)
722 $ ch-image push --image /var/tmp/image example.com:5000/foo/bar:latest
724 pushing image: example.com:5000/foo/bar:latest
725 image path: /var/tmp/image
726 layer 1/1: gathering
727 layer 1/1: preparing
728 preparing metadata
729 starting upload
730 layer 1/1: 892e38d: checking if already in repository
731 layer 1/1: 892e38d: already present
732 config: 546f447: checking if already in repository
733 config: 546f447: not present, uploading
734 manifest: uploading
735 cleaning up
736 done
737
739 $ ch-image [...] reset
740 Delete all images and cache from ch-image builder storage.
742
744 $ ch-image [...] storage-path
745 Print the storage directory path and exit.
747
749 CH_IMAGE_USERNAME, CH_IMAGE_PASSWORD
750 Username and password for registry authentication. See important
751 caveats in section “Authentication” above.
752 CH_LOG_FILE
754 If set, append log chatter to this file, rather than standard
755 error. This is useful for debugging situations where standard
756 error is consumed or lost.
757 Also sets verbose mode if not already set (equivalent to --ver‐
759 bose).
760 CH_LOG_FESTOON
762 If set, prepend PID and timestamp to logged chatter.
763
765 If Charliecloud was obtained from your Linux distribution, use your
766 distribution’s bug reporting procedures.
767 Otherwise, report bugs to: https://github.com/hpc/charliecloud/issues
769
771 charliecloud(7)
772 Full documentation at: <https://hpc.github.io/charliecloud>
774
776 2014–2021, Triad National Security, LLC
7770.26 2023-01-18 00:00 UTC CH-IMAGE(1)