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

NAME

6       ch-image - Build and manage images; completely unprivileged
7

SYNOPSIS

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

DESCRIPTION

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
25       Options that print brief information and then exit:
26
27          -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
33          --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
38          --version
39                 Print version number and exit successfully.
40
41       Common options placed before the sub-command:
42
43          -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
53                 Notes:
54
55                 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
61                 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
68                 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
75                 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
80          --no-cache
81                 Download everything needed, ignoring the cache.
82
83          --password-many
84                 Re-prompt the user every time a registry password is needed.
85
86          -s, --storage DIR
87                 Set the storage directory (see below for important details).
88
89          --tls-no-verify
90                 Don’t  verify TLS certificates of the repository. (Do not use
91                 this option unless you understand the risks.)
92
93          -v, --verbose
94                 Print extra chatter; can be repeated.
95

AUTHENTICATION

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
102       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
110       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
115       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

STORAGE DIRECTORY

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
126       In descending order of priority, this directory is located at:
127
128          -s, --storage DIR
129                 Command line option.
130
131          $CH_IMAGE_STORAGE
132                 Environment variable.
133
134          /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
139       Unlike many container implementations, there is no  notion  of  storage
140       drivers, graph drivers, etc., to select and/or configure.
141
142       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
150       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
155       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
161       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

BUILD

167       Build an image from a Dockerfile and put it in the storage directory.
168
169   Synopsis
170          $ ch-image [...] build [-t TAG] [-f DOCKERFILE] [...] CONTEXT
171
172   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
177       Required argument:
178
179          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
187       Options:
188
189          -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
198                 Note:  See  documentation  for  ch-run  --bind  for important
199                 caveats and gotchas.
200
201                 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
205          --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
210          -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
216          --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
222          -n, --dry-run
223                 Don’t actually execute any Dockerfile instructions.
224
225          --no-force-detect
226                 Don’t try to detect if the workarounds in --force would help.
227
228          --parse-only
229                 Stop after parsing the Dockerfile.
230
231          -t, --tag TAG
232                 Name of image to create. If not specified, infer the name:
233
234                 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
238                 2. If Dockerfile has extension dockerfile: use  the  basename
239                    with  the same transformation, e.g. baz.@QUX.dockerfile ->
240                    baz.qux.
241
242                 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
246                 4. Otherwise (context directory is /): use root.
247
248                 If no colon present in the name, append :latest.
249
250   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
257       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
261       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
271       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
275            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
281       This one is (ironically) apt-get failing to drop privileges:
282
283          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
288       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
294          1. After FROM, analyze the image to see what  distribution  it  con‐
295             tains, which determines the specific workarounds.
296
297          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
304          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
308       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
313   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
319       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
328       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
332       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
336       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
340   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
347   Variable substitution
348       Variable  substitution  happens for all instructions, not just the ones
349       listed in the Dockerfile reference.
350
351       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
355       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
361          HTTP_PROXY
362          http_proxy
363          HTTPS_PROXY
364          https_proxy
365          FTP_PROXY
366          ftp_proxy
367          NO_PROXY
368          no_proxy
369
370       In addition to those listed in the Dockerfile reference, these environ‐
371       ment variables are passed through in the same way:
372
373          SSH_AUTH_SOCK
374          USER
375
376       Finally,  these variables are also pre-defined but are unrelated to the
377       host environment:
378
379          PATH=/ch/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
380          TAR_OPTIONS=--no-same-owner
381
382       Note that ARG and ENV have different syntax despite very similar seman‐
383       tics.
384
385   COPY
386       Especially  for people used to UNIX cp(1), the semantics of the Docker‐
387       file COPY instruction can be confusing.
388
389       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
395       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
399       1. You can use absolute paths in the source; the root  is  the  context
400          directory.
401
402       2. Destination  directories are created if they don’t exist in the fol‐
403          lowing situations:
404
405          1. If the destination path ends in slash. (Documented.)
406
407          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
411          3. If there is a single source and it is  a  directory.  (Not  docu‐
412             mented.)
413
414       3. Symbolic  links  behave  differently  depending  on  how deep in the
415          copied tree they are. (Not documented.)
416
417          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
422          2. Symlinks at deeper levels are not dereferenced, i.e., the symlink
423             itself is copied.
424
425       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
430       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
439                 RUN mkdir -p /foo/bar && touch /foo/bar/baz
440                 COPY foo /foo
441
442       We expect the following differences to be permanent:
443
444       • Wildcards use Python glob semantics, not the Go semantics.
445
446COPY --chown is ignored, because it doesn’t make sense in an unprivi‐
447         leged build.
448
449   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
453EXPOSE: 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
457HEALTHCHECK: 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
461MAINTAINER is deprecated.
462
463STOPSIGNAL requires a container supervisor daemon process,  which  we
464         have no plans to add.
465
466USER does not make sense for unprivileged builds.
467
468VOLUME: 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
473   Examples
474       Build  image  bar  using  ./foo/bar/Dockerfile  and  context  directory
475       ./foo/bar:
476
477          $ ch-image build -t bar -f ./foo/bar/Dockerfile ./foo/bar
478          [...]
479          grown in 4 instructions: bar
480
481       Same,  but  infer the image name and Dockerfile from the context direc‐
482       tory path:
483
484          $ ch-image build ./foo/bar
485          [...]
486          grown in 4 instructions: bar
487
488       Build using humongous vendor compilers you want to  bind-mount  instead
489       of installing into the image:
490
491          $ ch-image build --bind /opt/bigvendor:/opt .
492          $ cat Dockerfile
493          FROM centos:7
494
495          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

DELETE

501          $ ch-image [...] delete IMAGE_REF
502
503       Delete  the  image  described by the image reference IMAGE_REF from the
504       storage directory.
505

LIST

507       Print information about images. If no argument given, list  the  images
508       in builder storage.
509
510   Synopsis
511          $ ch-image [...] list [IMAGE_REF]
512
513   Description
514       Optional argument:
515
516          IMAGE_REF
517                 Print  details  of what’s known about IMAGE_REF, both locally
518                 and in the remote registry, if any.
519
520   Examples
521       List images in builder storage:
522
523          $ ch-image list
524          alpine:3.9 (amd64)
525          alpine:latest (amd64)
526          debian:buster (amd64)
527
528       Print details about Debian Buster image:
529
530          $ 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

IMPORT

540          $ ch-image [...] import PATH IMAGE_REF
541
542       Copy the image at PATH into builder storage with name  IMAGE_REF.  PATH
543       can be:
544
545       • an image directory
546
547       • a tarball with no top-level directory (a.k.a. a “tarbomb”)
548
549       • a standard tarball with one top-level directory
550
551       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

PULL

556       Pull the image described by the image reference IMAGE_REF from a repos‐
557       itory to the local filesystem.
558
559   Synopsis
560          $ ch-image [...] pull [...] IMAGE_REF [IMAGE_DIR]
561
562       See the FAQ for the gory details on specifying image references.
563
564   Description
565       Destination:
566
567          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
573       Options:
574
575          --last-layer N
576                 Unpack  only  N layers, leaving an incomplete image. This op‐
577                 tion is intended for debugging.
578
579          --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
584       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
592       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
596          • Current working directory set with WORKDIR is effective  in  down‐
597            stream Dockerfiles.
598
599          • 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
603          • Mount  point  directories specified with VOLUME are created in the
604            image if they don’t exist, but no other action is taken.
605
606       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
609   Examples
610       Download  the  Debian Buster image matching the host’s architecture and
611       place it in the storage directory:
612
613          $ 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
629       Same, specifying the architecture explicitly:
630
631          $ 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
645       Download the same image and place it in /tmp/buster:
646
647          $ 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

PUSH

654       Push the image described by the image reference IMAGE_REF from the  lo‐
655       cal filesystem to a repository.
656
657   Synopsis
658          $ ch-image [...] push [--image DIR] IMAGE_REF [DEST_REF]
659
660       See the FAQ for the gory details on specifying image references.
661
662   Description
663       Destination:
664
665          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
670       Options:
671
672          --image DIR
673                 Use the unpacked image located at DIR rather than an image in
674                 the storage directory named IMAGE_REF.
675
676       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
682   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
687          $ 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
701       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
704          $ 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
719       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
723          $ 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

RESET

739          $ ch-image [...] reset
740
741       Delete all images and cache from ch-image builder storage.
742

STORAGE-PATH

744          $ ch-image [...] storage-path
745
746       Print the storage directory path and exit.
747

ENVIRONMENT VARIABLES

749       CH_IMAGE_USERNAME, CH_IMAGE_PASSWORD
750              Username and password for registry authentication. See important
751              caveats in section “Authentication” above.
752
753       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
758              Also sets verbose mode if not already set (equivalent to  --ver‐
759              bose).
760
761       CH_LOG_FESTOON
762              If set, prepend PID and timestamp to logged chatter.
763

REPORTING BUGS

765       If  Charliecloud  was  obtained  from your Linux distribution, use your
766       distribution’s bug reporting procedures.
767
768       Otherwise, report bugs to: https://github.com/hpc/charliecloud/issues
769

SEE ALSO

771       charliecloud(7)
772
773       Full documentation at: <https://hpc.github.io/charliecloud>
774
776       2014–2021, Triad National Security, LLC
777
778
779
780
7810.26                         2023-01-18 00:00 UTC                  CH-IMAGE(1)
Impressum