ch-image - Man Page

Build an image from a Dockerfile and put it in the storage directory. Use ch-run(1) to execute RUN instructions. Note that FROM implicitly pulls the base image if needed, so you may want to read about the pull subcommand below as well.

Required argument:

CONTEXT

Path to context directory; this is the root of Copy and ADD instructions in the Dockerfile.

Options:

-b,  --bind SRC[:DST]

Bind-mount host directory SRC at container directory DST during RUN instructions. Can be repeated; the default destination if DST is omitted is /mnt/0, /mnt/1, etc.

Note: This applies only to RUN instructions. Other instructions that modify the image filesystem, e.g. Copy, can only access host files from the context directory.

--build-arg KEY[=VALUE]

Set build-time variable KEY defined by ARG instruction to VALUE. If VALUE not specified, use the value of environment variable KEY.

-f,  --file DOCKERFILE

Use DOCKERFILE instead of CONTEXT/Dockerfile. Specify a single hyphen (-) to use standard input; note that in this case, the context directory is still provided, which matches docker build -f - behavior.

--force

Inject the unprivileged build workarounds; see discussion later in this section for details on what this does and when you might need it. If a build fails and ch-image thinks --force would help, it will suggest it.

-n,  --dry-run

Don’t actually execute any Dockerfile instructions.

--no-force-detect

Don’t try to detect if the workarounds in --force would help.

--parse-only

Stop after parsing the Dockerfile.

-t,  -tag TAG

Name of image to create. If not specified, use the final component of path CONTEXT. Append :latest if no colon present.

ch-image is a fully unprivileged image builder. It does not use any setuid or setcap helper programs, and it does not use configuration files /etc/subuid or /etc/subgid. This contrasts with the “rootless” or “fakeroot” modes of some competing builders, which do require privileged supporting code or utilities.

This approach does yield some quirks. We provide built-in workarounds that should mostly work (i.e., --force), but it can be helpful to understand what is going on.

ch-image executes all instructions as the normal user who invokes it. For RUN, this is accomplished with ch-run -w --uid=0 --gid=0 (and some other arguments), i.e., your host EUID and EGID both mapped to zero inside the container, and only one UID (zero) and GID (zero) are available inside the container. Under this arrangement, processes running in the container for each RUN appear to be running as root, but many privileged system calls will fail without the workarounds described below. This affects any fully unprivileged container build, not just Charliecloud.

The most common time to see this is installing packages. For example, here is RPM failing to chown(2) a file, which makes the package update fail:

  Updating   : 1:dbus-1.10.24-13.el7_6.x86_64                            2/4
Error unpacking rpm package 1:dbus-1.10.24-13.el7_6.x86_64
error: unpacking of archive failed on file /usr/libexec/dbus-1/dbus-daemon-launch-helper;5cffd726: cpio: chown
  Cleanup    : 1:dbus-libs-1.10.24-12.el7.x86_64                         3/4
error: dbus-1:1.10.24-13.el7_6.x86_64: install failed

This one is (ironically) apt-get failing to drop privileges:

E: setgroups 65534 failed - setgroups (1: Operation not permitted)
E: setegid 65534 failed - setegid (22: Invalid argument)
E: seteuid 100 failed - seteuid (22: Invalid argument)
E: setgroups 0 failed - setgroups (1: Operation not permitted)

By default, nothing is done to avoid these problems, though ch-image does try to detect if the workarounds could help. --force activates the workarounds: ch-image injects extra commands to intercept these system calls and fake a successful result, using fakeroot(1). There are three basic steps:

1. After FROM, analyze the image to see what distribution it contains, which determines the specific workarounds.
2. Before the user command in the first RUN instruction where the injection seems needed, install fakeroot(1) in the image, if one is not already installed, as well as any other necessary initialization commands. For example, we turn off the apt sandbox (for Debian Buster) and configure EPEL but leave it disabled (for CentOS/RHEL).
3. Prepend fakeroot to RUN instructions that seem to need it, e.g. ones that contain apt, apt-get, dpkg for Debian derivatives and dnf, rpm, or yum for RPM-based distributions.

The details are specific to each distribution. ch-image analyzes image content (e.g., grepping /etc/debian_version) to select a configuration; see lib/fakeroot.py for details. ch-image prints exactly what it is doing.

Delete the image described by the image reference IMAGE_REF from the storage directory.

Pull the image described by the image reference IMAGE_REF from a repository to the local filesystem. See the FAQ for the gory details on specifying image references.

Destination:

IMAGE_DIR

If specified, place the unpacked image at this path; it is then ready for use by ch-run or other tools. The storage directory will not contain a copy of the image, i.e., it is only unpacked once.

Options:

--last-layer N

Unpack only N layers, leaving an incomplete image. This option is intended for debugging.

--parse-only

Parse IMAGE_REF, print a parse report, and exit successfully without talking to the internet or touching the storage directory.

This script does a fair amount of validation and fixing of the layer tarballs before flattening in order to support unprivileged use despite image problems we frequently see in the wild. For example, device files are ignored, and file and directory permissions are increased to a minimum of rwx------ and rw------- respectively. Note, however, that symlinks pointing outside the image are permitted, because they are not resolved until runtime within a container.

The following metadata in the pulled image is retained; all other metadata is currently ignored. (If you have a need for additional metadata, please let us know!)

• Current working directory set with WORKDIR is effective in downstream Dockerfiles.
• Environment variables set with ENV are effective in downstream Dockerfiles and also written to /ch/environment for use in ch-run --set-env.
• Mount point directories specified with VOLUME are created in the image if they don’t exist, but no other action is taken.

Note that some images (e.g., those with a “version 1 manifest”) do not contain metadata. A warning is printed in this case.

Push the image described by the image reference IMAGE_REF from the local filesystem to a repository. See the FAQ for the gory details on specifying image references.

Because Charliecloud is fully unprivileged, the owner and group of files in its images are not meaningful in the broader ecosystem. Thus, when pushed, everything in the image is flattened to user:group root:root. Also, setuid/setgid bits are removed, to avoid surprises if the image is pulled by a privileged container implementation.

Destination:

DEST_REF

If specified, use this as the destination image reference, rather than IMAGE_REF. This lets you push to a repository without permanently adding a tag to the image.

Options:

--image DIR

Use the unpacked image located at DIR rather than an image in the storage directory named IMAGE_REF.

Print the storage directory path and exit.

The context directory is bind-mounted into the build, rather than copied like Docker. Thus, the size of the context is immaterial, and the build reads directly from storage like any other local process would. However, you still can’t access anything outside the context directory.

ch-image can authenticate using one-time passwords, e.g. those provided by a security token. Unlike docker login, it does not assume passwords are persistent.

Variable substitution happens for all instructions, not just the ones listed in the Dockerfile reference.

ARG and ENV cause cache misses upon definition, in contrast with Docker where these variables miss upon use, except for certain cache-excluded variables that never cause misses, listed below.

Like Docker, ch-image pre-defines the following proxy variables, which do not require an ARG instruction. However, they are available if the same-named environment variable is defined; --build-arg is not required. Changes to these variables do not cause a cache miss.

HTTP_PROXY
http_proxy
HTTPS_PROXY
https_proxy
FTP_PROXY
ftp_proxy
NO_PROXY
no_proxy

The following variables are also pre-defined:

PATH=/ch/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
TAR_OPTIONS=--no-same-owner

Note that ARG and ENV have different syntax despite very similar semantics.

Especially for people used to UNIX cp(1), the semantics of the Dockerfile COPY instruction can be confusing.

Most notably, when a source of the copy is a directory, the contents of that directory, not the directory itself, are copied. This is documented, but it’s a real gotcha because that’s not what cp(1) does, and it means that many things you can do in one cp(1) command require multiple COPY instructions.

Also, the reference documentation is incomplete. In our experience, Docker also behaves as follows; ch-image does the same in an attempt to be bug-compatible.

1. You can use absolute paths in the source; the root is the context directory.

2. Destination directories are created if they don’t exist in the following situations:

   1. If the destination path ends in slash. (Documented.)
   2. If the number of sources is greater than 1, either by wildcard or explicitly, regardless of whether the destination ends in slash. (Not documented.)
   3. If there is a single source and it is a directory. (Not documented.)

3. Symbolic links behave differently depending on how deep in the copied tree they are. (Not documented.)

   1. Symlinks at the top level — i.e., named as the destination or the source, either explicitly or by wildcards — are dereferenced. They are followed, and whatever they point to is used as the destination or source, respectively.
   2. Symlinks at deeper levels are not dereferenced, i.e., the symlink itself is copied.
4. If a directory appears at the same path in source and destination, and is at the 2nd level or deeper, the source directory’s metadata (e.g., permissions) are copied to the destination directory. (Not documented.)

5. If an object appears in both the source and destination, and is at the 2nd level or deeper, and is of different types in the source and destination, then the source object will overwrite the destination object. (Not documented.) For example, if /tmp/foo/bar is a regular file, and /tmp is the context directory, then the following Dockerfile snippet will result in a file in the container at /foo/bar (copied from /tmp/foo/bar); the directory and all its contents will be lost.

   RUN mkdir -p /foo/bar && touch /foo/bar/baz
   COPY foo /foo

We expect the following differences to be permanent:

• Wildcards use Python glob semantics, not the Go semantics.
• COPY --chown is ignored, because it doesn’t make sense in an unprivileged build.

• Parser directives are not supported. We have not identified a need for any of them.
• EXPOSE: Charliecloud does not use the network namespace, so containerized processes can simply listen on a host port like other unprivileged processes.
• HEALTHCHECK: This instruction’s main use case is monitoring server processes rather than applications. Also, implementing it requires a container supervisor daemon, which we have no plans to add.
• MAINTAINER is deprecated.
• STOPSIGNAL requires a container supervisor daemon process, which we have no plans to add.
• USER does not make sense for unprivileged builds.
• VOLUME: This instruction is not currently supported. Charliecloud has good support for bind mounts; we anticipate that it will continue to focus on that and will not introduce the volume management features that Docker has.

Build image bar using ./foo/bar/Dockerfile and context directory ./foo/bar:

$ ch-image build -t bar -f ./foo/bar/Dockerfile ./foo/bar
[...]
grown in 4 instructions: bar

Same, but infer the image name and Dockerfile from the context directory path:

$ ch-image build ./foo/bar
[...]
grown in 4 instructions: bar

Build using humongous vendor compilers you want to bind-mount instead of installing into a layer:

$ ch-image build --bind /opt/bigvendor:/opt .
$ cat Dockerfile
FROM centos:7

RUN /opt/bin/cc hello.c
#COPY /opt/lib/*.so /usr/local/lib   # fail: COPY doesn't bind mount
RUN cp /opt/lib/*.so /usr/local/lib  # possible workaround
RUN ldconfig

Download the Debian Buster image and place it in the storage directory:

$ ch-image pull debian:buster
pulling image:   debian:buster

manifest: downloading
layer 1/1: d6ff36c: downloading
layer 1/1: d6ff36c: listing
validating tarball members
resolving whiteouts
flattening image
layer 1/1: d6ff36c: extracting
done

Same, except place the image in /tmp/buster:

$ ch-image pull debian:buster /tmp/buster
[...]
$ ls /tmp/buster
bin   dev  home  lib64  mnt  proc  run   srv  tmp  var
boot  etc  lib   media  opt  root  sbin  sys  usr

Push a local image to the registry example.com:5000 at path /foo/bar with tag latest. Note that in this form, the local image must be named to match that remote reference.

$ ch-image push example.com:5000/foo/bar:latest
pushing image:   example.com:5000/foo/bar:latest
layer 1/1: gathering
layer 1/1: preparing
preparing metadata
starting upload
layer 1/1: a1664c4: checking if already in repository
layer 1/1: a1664c4: not present, uploading
config: 89315a2: checking if already in repository
config: 89315a2: not present, uploading
manifest: uploading
cleaning up
done

Same, except use local image alpine:3.9. In this form, the local image name does not have to match the destination reference.

$ ch-image push alpine:3.9 example.com:5000/foo/bar:latest
pushing image:   alpine:3.9
destination:     example.com:5000/foo/bar:latest
layer 1/1: gathering
layer 1/1: preparing
preparing metadata
starting upload
layer 1/1: a1664c4: checking if already in repository
layer 1/1: a1664c4: not present, uploading
config: 89315a2: checking if already in repository
config: 89315a2: not present, uploading
manifest: uploading
cleaning up
done

Same, except use unpacked image located at /var/tmp/image rather than an image in ch-image storage. (Also, the sole layer is already present in the remote registry, so we don’t upload it again.)

$ ch-image push --image /var/tmp/image example.com:5000/foo/bar:latest
pushing image:   example.com:5000/foo/bar:latest
image path:      /var/tmp/image
layer 1/1: gathering
layer 1/1: preparing
preparing metadata
starting upload
layer 1/1: 892e38d: checking if already in repository
layer 1/1: 892e38d: already present
config: 546f447: checking if already in repository
config: 546f447: not present, uploading
manifest: uploading
cleaning up
done