containerd-config.toml

package: containerd

title: containerd-config.toml(5)

summary: configuration file for containerd

text:
# containerd-config.toml(5)

## NAME
containerd-config.toml - configuration file for containerd

## SYNOPSIS
The config.toml file is a configuration file for the containerd daemon. The file must be placed at /etc/containerd/config.toml or specified with the --config option of containerd to be used by the daemon. If the file does not exist at the appropriate location or is not provided via the --config option containerd uses its default configuration settings, which can be displayed with the containerd config(1) command.

## DESCRIPTION
The TOML file used to configure the containerd daemon settings has a short list of global settings followed by a series of sections for specific areas of daemon configuration. There is also a section for plugins that allows each containerd plugin to have an area for plugin-specific configuration and settings.

## FORMAT
version : The version field in the config file specifies the config’s version. If no version number is specified inside the config file then it is assumed to be a version 1 config and parsed as such. Please use version = 2 to enable version 2 config as version 1 has been deprecated.

root : The root directory for containerd metadata. (Default: "/var/lib/containerd")

state : The state directory for containerd (Default: "/run/containerd")

plugin_dir : The directory for dynamic plugins to be stored

[grpc] : Section for gRPC socket listener settings. Contains the following properties:

- address (Default: "/run/containerd/containerd.sock")

- tcp_address

- tcp_tls_cert

- tcp_tls_key

- uid (Default: 0)

- gid (Default: 0)

- max_recv_message_size

- max_send_message_size

[ttrpc] : Section for TTRPC settings. Contains properties:

- address (Default: "")

- uid (Default: 0)

- gid (Default: 0)

[debug] : Section to enable and configure a debug socket listener. Contains four properties:

- address (Default: "/run/containerd/debug.sock")

- uid (Default: 0)

- gid (Default: 0)

- level (Default: "info") sets the debug log level. Supported levels are: "trace", "debug", "info", "warn", "error", "fatal", "panic"

- format (Default: "text") sets log format. Supported formats are "text" and "json"

[metrics] : Section to enable and configure a metrics listener. Contains two properties:

- address (Default: "") Metrics endpoint does not listen by default

- grpc_histogram (Default: false) Turn on or off gRPC histogram metrics

disabled_plugins : Disabled plugins are IDs of plugins to disable. Disabled plugins won't be initialized and started.

required_plugins : Required plugins are IDs of required plugins. Containerd exits if any required plugin doesn't exist or fails to be initialized or started.

[plugins] : The plugins section contains configuration options exposed from installed plugins. The following plugins are enabled by default and their settings are shown below. Plugins that are not enabled by default will provide their own configuration values documentation.

- [plugins."io.containerd.monitor.v1.cgroups"] has one option no_prometheus (Default: false)

- [plugins."io.containerd.service.v1.diff-service"] has one option default, a list by default set to ["walking"]

- [plugins."io.containerd.gc.v1.scheduler"] has several options that perform advanced tuning for the scheduler:

- pause_threshold is the maximum amount of time GC should be scheduled (Default: 0.02),

- deletion_threshold guarantees GC is scheduled after n number of deletions (Default: 0 [not triggered]),

- mutation_threshold guarantees GC is scheduled after n number of database mutations (Default: 100),

- schedule_delay defines the delay after trigger event before scheduling a GC (Default "0ms" [immediate]),

- startup_delay defines the delay after startup before scheduling a GC (Default "100ms")

•

[plugins."io.containerd.runtime.v2.task"] specifies options for configuring the runtime shim:

- platforms specifies the list of supported platforms

- sched_core Core scheduling is a feature that allows only trusted tasks to run concurrently on cpus sharing compute resources (eg: hyperthreads on a core). (Default: false)

•

[plugins."io.containerd.service.v1.tasks-service"] has performance options:

- blockio_config_file (Linux only) specifies path to blockio class definitions (Default: ""). Controls I/O scheduler priority and bandwidth throttling. See blockio configuration ⟨https://github.com/intel/goresctrl/blob/main/doc/blockio.md#configuration⟩ for details of the file format.

- rdt_config_file (Linux only) specifies path to a configuration used for configuring RDT (Default: ""). Enables support for Intel RDT, a technology for cache and memory bandwidth management. See RDT configuration ⟨https://github.com/intel/goresctrl/blob/main/doc/rdt.md#configuration⟩ for details of the file format.

•

[plugins."io.containerd.grpc.v1.cri".containerd] contains options for the CRI plugin, and child nodes for CRI options:

•

default_runtime_name (Default: "runc") specifies the default runtime name

- [plugins."io.containerd.grpc.v1.cri".containerd.runtimes] one or more container runtimes, each with a unique name

- [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.<runtime>] a runtime named <runtime>

- [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.<runtime>.options] options for the named <runtime>, most important:

•

BinaryName specifies the path to the actual runtime to be invoked by the shim, e.g. "/usr/bin/runc"

oom_score : The out of memory (OOM) score applied to the containerd daemon process (Default: 0)

[cgroup] : Section for Linux cgroup specific settings

•

path (Default: "") Specify a custom cgroup path for created containers

[proxy_plugins] : Proxy plugins configures plugins which are communicated to over gRPC

- type (Default: "")

- address (Default: "")

timeouts : Timeouts specified as a duration <!-- [timeouts]

"io.containerd.timeout.shim.cleanup" = "5s"

"io.containerd.timeout.shim.load" = "5s"

"io.containerd.timeout.shim.shutdown" = "3s"

"io.containerd.timeout.task.state" = "2s" -->

imports : Imports is a list of additional configuration files to include. This allows to split the main configuration file and keep some sections separately (for example vendors may keep a custom runtime configuration in a separate file without modifying the main config.toml). Imported files will overwrite simple fields like int or string (if not empty) and will append array and map fields. Imported files are also versioned, and the version can't be higher than the main config.

stream_processors

- accepts (Default: "[]") Accepts specific media-types

- returns (Default: "") Returns the media-type

- path (Default: "") Path or name of the binary

- args (Default: "[]") Args to the binary

## EXAMPLES

### Complete Configuration
The following is a complete config.toml default configuration example:

```
version = 2
root = "/var/lib/containerd"
state = "/run/containerd"
oom_score = 0
imports = ["/etc/containerd/runtime_*.toml", "./debug.toml"]
[grpc]

  address = "/run/containerd/containerd.sock"

  uid = 0

  gid = 0
[debug]

  address = "/run/containerd/debug.sock"

  uid = 0

  gid = 0

  level = "info"
[metrics]

  address = ""

  grpc_histogram = false
[cgroup]

  path = ""
[plugins]

  [plugins."io.containerd.monitor.v1.cgroups"]

    no_prometheus = false

  [plugins."io.containerd.service.v1.diff-service"]

    default = ["walking"]

  [plugins."io.containerd.gc.v1.scheduler"]

    pause_threshold = 0.02

    deletion_threshold = 0

    mutation_threshold = 100

    schedule_delay = 0

    startup_delay = "100ms"

  [plugins."io.containerd.runtime.v2.task"]

    platforms = ["linux/amd64"]

    sched_core = true

  [plugins."io.containerd.service.v1.tasks-service"]

    blockio_config_file = ""

    rdt_config_file = ""
```

### Multiple Runtimes
The following is an example partial configuration with two runtimes:

```
[plugins]

  [plugins."io.containerd.grpc.v1.cri"]

    [plugins."io.containerd.grpc.v1.cri".containerd]

      default_runtime_name = "runc"

      [plugins."io.containerd.grpc.v1.cri".containerd.runtimes]

        [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]

          privileged_without_host_devices = false

          runtime_type = "io.containerd.runc.v2"

          [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]

            BinaryName = "/usr/bin/runc"

        [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.other]

          privileged_without_host_devices = false

          runtime_type = "io.containerd.runc.v2"

          [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.other.options]

            BinaryName = "/usr/bin/path-to-runtime"
```

The above creates two named runtime configurations - named runc and other - and sets the default runtime to runc. The above are used solely for runtimes invoked via CRI. To use the non-default "other" runtime in this example, a spec will include the runtime handler named "other" to specify the desire to use the named runtime config.

The CRI specification includes a runtime_handler field ⟨https://github.com/kubernetes/cri-api/blob/de5f1318aede866435308f39cb432618a15f104e/pkg/apis/runtime/v1/api.proto#L476⟩, which will reference the named runtime.

It is important to note the naming convention. Runtimes are under [plugins."io.containerd.grpc.v1.cri".containerd.runtimes], with each runtime given a unique name, e.g. [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]. In addition, each runtime can have shim-specific options under [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.<runtime>.options], for example, [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options].

The io.containerd.runc.v2 runtime is used to run OCI-compatible runtimes on Linux, such as runc. In the example above, the runtime_type field specifies the shim to use (io.containerd.runc.v2) while the BinaryName field is a shim-specific option which specifies the path to the OCI runtime.

For the example configuration named "runc", the shim will launch /usr/bin/runc as the OCI runtime. For the example configuration named "other", the shim will launch /usr/bin/path-to-runtime instead.

## BUGS
Please file any specific issues that you encounter at

⟨https://github.com/containerd/containerd⟩.

## AUTHOR
Phil Estes ⟨estesp@gmail.com⟩

## SEE ALSO
ctr(8), containerd-config(8), containerd(8)


.containerignore

package: containers-common

title: .containerignore(5)

text:
# .containerignore(5)

## NAME
.containerignore(.dockerignore) - files to ignore buildah or podman build context directory

## INTRODUCTION
Before container engines build an image, they look for a file named .containerignore or .dockerignore in the root context directory. If one of these file exists, the CLI modifies the context to exclude files and directories that match patterns specified in the file. This avoids adding them to images using the ADD or COPY instruction.

The CLI interprets the .containerignore or .dockerignore file as a newline-separated list of patterns similar to the file globs of Unix shells. For the purposes of matching, the root of the context is considered to be both the working and the root directory. For example, the patterns /foo/bar and foo/bar both exclude a file or directory named bar in the foo subdirectory of PATH or in the root of the git repository located at URL. Neither excludes anything else.

If a line in .containerignore or .dockerignore file starts with # in column 1, then this line is considered as a comment and is ignored before interpreted by the CLI.

## EXAMPLES
Here is an example .containerignore file:

```
# comment
*/temp*
*/*/temp*
temp?
```

This file causes the following build behavior: Rule Behavior

```
# comment 	Ignored.
*/temp* 	Exclude files and directories whose names start with temp in any immediate subdirectory of the root.
For example, the plain file /somedir/temporary.txt is excluded, as is the directory /somedir/temp.
*/*/temp* 	Exclude files and directories starting with temp from any subdirectory that is two levels below the
root. For example, /somedir/subdir/temporary.txt is excluded.
temp? 	Exclude files and directories in the root directory whose names are a one-character extension of temp. For example, /tempa and /tempb are excluded.
```

Matching is done using Go’s filepath.Match rules. A preprocessing step removes leading and trailing whitespace and eliminates . and .. elements using Go’s filepath.Clean. Lines that are blank after preprocessing are ignored.

Beyond Go’s filepath.Match rules, Docker also supports a special wildcard string ** that matches any number of directories (including zero). For example, */.go will exclude all files that end with .go that are found in all directories, including the root of the build context.

Lines starting with ! (exclamation mark) can be used to make exceptions to exclusions. The following is an example .containerignore file that uses this mechanism:

```
*.md
!README.md
```

All markdown files except README.md are excluded from the context.

The placement of ! exception rules influences the behavior: the last line of the .containerignore that matches a particular file determines whether it is included or excluded. Consider the following example:

```
*.md
!README*.md
README-secret.md
```

No markdown files are included in the context except README files other than README-secret.md.

Now consider this example:

```
*.md
README-secret.md
!README*.md
```

All of the README files are included. The middle line has no effect because !README*.md matches README-secret.md and comes last.

You can even use the .containerignore file to exclude the Containerfile or Dockerfile and .containerignore files. These files are still sent to the daemon because it needs them to do its job. But the ADD and COPY instructions do not copy them to the image.

Finally, you may want to specify which files to include in the context, rather than which to exclude. To achieve this, specify * as the first pattern, followed by one or more ! exception patterns.

## SEE ALSO
buildah-build(1), podman-build(1), docker-build(1)

## HISTORY
*Sep 2021, Compiled by Dan Walsh (dwalsh at redhat dot com) based on docker.com .dockerignore documentation.


Containerfile

title: Containerfile(5)

text:
# Containerfile(5)

## NAME
Containerfile(Dockerfile) - automate the steps of creating a container image

## INTRODUCTION
The Containerfile is a configuration file that automates the steps of creating a container image. It is similar to a Makefile. Container engines (Podman, Buildah, Docker) read instructions from the Containerfile to automate the steps otherwise performed manually to create an image. To build an image, create a file called Containerfile.

The Containerfile describes the steps taken to assemble the image. When the Containerfile has been created, call the buildah build, podman build, docker build command, using the path of context directory that contains Containerfile as the argument. Podman and Buildah default to Containerfile and will fall back to Dockerfile. Docker only will search for Dockerfile in the context directory.

Dockerfile is an alternate name for the same object. Containerfile and Dockerfile support the same syntax.

## SYNOPSIS
INSTRUCTION arguments

For example:

FROM image

## DESCRIPTION
A Containerfile is a file that automates the steps of creating a container image. A Containerfile is similar to a Makefile.

## USAGE

```
  buildah build .

  podman build .
```

-- Runs the steps and commits them, building a final image.

The path to the source repository defines where to find the context of the

build.

```
  buildah build -t repository/tag .

  podman build -t repository/tag .
```

-- specifies a repository and tag at which to save the new image if the build

succeeds. The container engine runs the steps one-by-one, committing the result

to a new image if necessary, before finally outputting the ID of the new

image.

Container engines reuse intermediate images whenever possible. This significantly

accelerates the build process.

## FORMAT
FROM image [AS <name>]

FROM image:tag [AS <name>]

FROM image@digest [AS <name>]

-- The FROM instruction sets the base image for subsequent instructions. A

valid Containerfile must have either ARG or FROM as its first instruction.

If FROM is not the first instruction in the file, it may only be preceded by

one or more ARG instructions, which declare arguments that are used in the next FROM line in the Containerfile.

The image can be any valid image. It is easy to start by pulling an image from the public

repositories.

-- FROM must appear at least once in the Containerfile.

-- FROM The first FROM command must come before all other instructions in

the Containerfile except ARG

-- FROM may appear multiple times within a single Containerfile in order to create

multiple images. Make a note of the last image ID output by the commit before

each new FROM command.

-- If no tag is given to the FROM instruction, container engines apply the

latest tag. If the used tag does not exist, an error is returned.

-- If no digest is given to the FROM instruction, container engines apply the

latest tag. If the used tag does not exist, an error is returned.

-- A name can be assigned to a build stage by adding AS name to the instruction.

The name can be referenced later in the Containerfile using the FROM or COPY --from=<name> instructions.

MAINTAINER

-- MAINTAINER sets the Author field for the generated images.

Useful for providing users with an email or url for support.

RUN

-- RUN has two forms:

```
  # the command is run in a shell - /bin/sh -c

  RUN <command>

  # Executable form

  RUN ["executable", "param1", "param2"]
```

RUN mounts

--mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]

Attach a filesystem mount to the container

Current supported mount TYPES are bind, cache, secret and tmpfs.

```
   e.g.

   mount=type=bind,source=/path/on/host,destination=/path/in/container,relabel=shared

   mount=type=tmpfs,tmpfs-size=512M,destination=/path/in/container

   mount=type=secret,id=mysecret cat /run/secrets/mysecret

   Common Options:

      · src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field.

      · dst, destination, target: mount destination spec.

      · ro, read-only: true (default) or false.

   Options specific to bind:

      · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).

      . bind-nonrecursive: do not setup a recursive bind mount.  By default it is recursive.

      · from: stage or image name for the root of the source. Defaults to the build context.

      · relabel=shared, z: Relabels src content with a shared label.

      . relabel=private, Z: Relabels src content with a private label.

      Labeling systems like SELinux require proper labels on the bind mounted content mounted into a container. Without a label, the security system might prevent the processes running in side the container from using the content. By default, container engines do not change the labels set by the OS. The relabel flag tells the engine to relabel file objects on the shared mountz.

      The relabel=shared and z options tell the engine that two or more containers will share the mount content. The engine labels the content with a shared content label.

      The relabel=private and Z options tell the engine to label the content with a private unshared label. Only the current container can use a private mount.

      Relabeling walks the file system under the mount and changes the label on each file, if the mount has thousands of inodes, this process takes a long time, delaying the start of the container.

      · rw, read-write: allows writes on the mount.

   Options specific to tmpfs:

      · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.

      · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.

      · tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
Options specific to cache:

      · id: Create a separate cache directory for a particular id.

      · mode: File mode for new cache directory in octal. Default 0755.

      · ro, readonly: read only cache if set.

      · uid: uid for cache directory.

      · gid: gid for cache directory.

      · from: stage name for the root of the source. Defaults to host cache directory.

      · rw, read-write: allows writes on the mount.
```

RUN --network

RUN --network allows control over which networking environment the command is run in.

Syntax: --network=<TYPE>

Network types

Type

Description

default ⟨#run---networkdefault⟩ (default)

Run in the default network.

none ⟨#run---networknone⟩

Run with no network access.

host ⟨#run---networkhost⟩

Run in the host's network environment.

### RUN --network=default
Equivalent to not supplying a flag at all, the command is run in the default network for the build.

### RUN --network=none
The command is run with no network access (lo is still available, but is isolated to this process).

### Example: isolating external effects

```
FROM python:3.6
ADD mypackage.tgz wheels/
RUN --network=none pip install --find-links wheels mypackage
```

pip will only be able to install the packages provided in the tarfile, which can be controlled by an earlier build stage.

### RUN --network=host
The command is run in the host's network environment (similar to buildah build --network=host, but on a per-instruction basis)

RUN Secrets

The RUN command has a feature to allow the passing of secret information into the image build. These secrets files can be used during the RUN command but are not committed to the final image. The RUN command supports the --mount option to identify the secret file. A secret file from the host is mounted into the container while the image is being built.

Container engines pass secret the secret file into the build using the --secret flag.

--mount=type=secret,TYPE-SPECIFIC-OPTION[,...]

•

id is the identifier for the secret passed into the buildah build --secret or podman build --secret. This identifier is associated with the RUN --mount identifier to use in the Containerfile.

•

dst|target|destination rename the secret file to a specific file in the Containerfile RUN command to use.

•

type=secret tells the --mount command that it is mounting in a secret file

```
# shows secret from default secret location:
RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret
```

```
# shows secret from custom secret location:
RUN --mount=type=secret,id=mysecret,dst=/foobar cat /foobar
```

The secret needs to be passed to the build using the --secret flag. The final image built does not container the secret file:

```
 buildah build --no-cache --secret id=mysecret,src=mysecret.txt .
```

-- The RUN instruction executes any commands in a new layer on top of the current

image and commits the results. The committed image is used for the next step in

Containerfile.

-- Layering RUN instructions and generating commits conforms to the core

concepts of container engines where commits are cheap and containers can be created from

any point in the history of an image. This is similar to source control. The

exec form makes it possible to avoid shell string munging. The exec form makes

it possible to RUN commands using a base image that does not contain /bin/sh.

Note that the exec form is parsed as a JSON array, which means that you must

use double-quotes (") around words, not single-quotes (').

CMD

-- CMD has three forms:

```
  # Executable form

  CMD ["executable", "param1", "param2"]`

  # Provide default arguments to ENTRYPOINT

  CMD ["param1", "param2"]`

  # the command is run in a shell - /bin/sh -c

  CMD command param1 param2
```

-- There should be only one CMD in a Containerfile. If more than one CMD is listed, only

the last CMD takes effect.

The main purpose of a CMD is to provide defaults for an executing container.

These defaults may include an executable, or they can omit the executable. If

they omit the executable, an ENTRYPOINT must be specified.

When used in the shell or exec formats, the CMD instruction sets the command to

be executed when running the image.

If you use the shell form of the CMD, the <command> executes in /bin/sh -c:

Note that the exec form is parsed as a JSON array, which means that you must

use double-quotes (") around words, not single-quotes (').

```
  FROM ubuntu

  CMD echo "This is a test." | wc -
```

-- If you run command without a shell, then you must express the command as a

JSON array and give the full path to the executable. This array form is the

preferred form of CMD. All additional parameters must be individually expressed

as strings in the array:

```
  FROM ubuntu

  CMD ["/usr/bin/wc","--help"]
```

-- To make the container run the same executable every time, use ENTRYPOINT in

combination with CMD.

If the user specifies arguments to podman run or docker run, the specified commands

override the default in CMD.

Do not confuse RUN with CMD. RUN runs a command and commits the result.

CMD executes nothing at build time, but specifies the intended command for

the image.

LABEL

-- LABEL <key>=<value> [<key>=<value> ...]or

```
  LABEL <key>[ <value>]

  LABEL <key>[ <value>]

  ...
```

The LABEL instruction adds metadata to an image. A LABEL is a

key-value pair. To specify a LABEL without a value, simply use an empty

string. To include spaces within a LABEL value, use quotes and

backslashes as you would in command-line parsing.

```
  LABEL com.example.vendor="ACME Incorporated"

  LABEL com.example.vendor "ACME Incorporated"

  LABEL com.example.vendor.is-beta ""

  LABEL com.example.vendor.is-beta=

  LABEL com.example.vendor.is-beta=""
```

An image can have more than one label. To specify multiple labels, separate

each key-value pair by a space.

Labels are additive including LABELs in FROM images. As the system

encounters and then applies a new label, new keys override any previous

labels with identical keys.

To display an image's labels, use the buildah inspect command.

EXPOSE

-- EXPOSE <port> [<port>...]

The EXPOSE instruction informs the container engine that the container listens on the

specified network ports at runtime. The container engine uses this information to

interconnect containers using links and to set up port redirection on the host

system.

ENV

-- ENV <key> <value>

The ENV instruction sets the environment variable <key> to

the value <value>. This value is passed to all future

RUN, ENTRYPOINT, and CMD instructions. This is

functionally equivalent to prefixing the command with <key>=<value>. The

environment variables that are set with ENV persist when a container is run

from the resulting image. Use podman inspect to inspect these values, and

change them using podman run --env <key>=<value>.

Note that setting "ENV DEBIAN_FRONTEND=noninteractive" may cause

unintended consequences, because it will persist when the container is run

interactively, as with the following command: podman run -t -i image bash

ADD

-- ADD has two forms:

```
  ADD <src> <dest>

  # Required for paths with whitespace

  ADD ["<src>",... "<dest>"]
```

The ADD instruction copies new files, directories

or remote file URLs to the filesystem of the container at path <dest>.

Multiple <src> resources may be specified but if they are files or directories

then they must be relative to the source directory that is being built

(the context of the build). The <dest> is the absolute path, or path relative

to WORKDIR, into which the source is copied inside the target container.

If the <src> argument is a local file in a recognized compression format

(tar, gzip, bzip2, etc) then it is unpacked at the specified <dest> in the

container's filesystem. Note that only local compressed files will be unpacked,

i.e., the URL download and archive unpacking features cannot be used together.

All new directories are created with mode 0755 and with the uid and gid of 0.

COPY

-- COPY has two forms:

```
  COPY [--chown=<user>:<group>] [--chmod=<mode>] <src> <dest>

  # Required for paths with whitespace

  COPY [--chown=<user>:<group>] [--chmod=<mode>] ["<src>",... "<dest>"]
```

The COPY instruction copies new files from <src> and

adds them to the filesystem of the container at path <dest>. The <src> must be

the path to a file or directory relative to the source directory that is

being built (the context of the build) or a remote file URL. The <dest> is an

absolute path, or a path relative to WORKDIR, into which the source will

be copied inside the target container. If you COPY an archive file it will

land in the container exactly as it appears in the build context without any

attempt to unpack it. All new files and directories are created with mode 0755

and with the uid and gid of 0.

--chown=<user>:<group> changes the ownership of new files and directories.

Supports names, if defined in the containers /etc/passwd and /etc/groups files, or using

uid and gid integers. The build will fail if a user or group name can't be mapped in the container.

Numeric id's are set without looking them up in the container.

--chmod=<mode> changes the mode of new files and directories.

The optional flag --from=name can be used to copy files from a named previous build stage. It

changes the context of <src> from the build context to the named build stage.

ENTRYPOINT

-- ENTRYPOINT has two forms:

```
  # executable form

  ENTRYPOINT ["executable", "param1", "param2"]`

  # run command in a shell - /bin/sh -c

  ENTRYPOINT command param1 param2
```

-- An ENTRYPOINT helps you configure a

container that can be run as an executable. When you specify an ENTRYPOINT,

the whole container runs as if it was only that executable. The ENTRYPOINT

instruction adds an entry command that is not overwritten when arguments are

passed to podman run. This is different from the behavior of CMD. This allows

arguments to be passed to the entrypoint, for instance podman run <image> -d

passes the -d argument to the ENTRYPOINT. Specify parameters either in the

ENTRYPOINT JSON array (as in the preferred exec form above), or by using a CMD

statement. Parameters in the ENTRYPOINT are not overwritten by the podman run arguments. Parameters specified via CMD are overwritten by podman run arguments. Specify a plain string for the ENTRYPOINT, and it will execute in

/bin/sh -c, like a CMD instruction:

```
  FROM ubuntu

  ENTRYPOINT wc -l -
```

This means that the Containerfile's image always takes stdin as input (that's

what "-" means), and prints the number of lines (that's what "-l" means). To

make this optional but default, use a CMD:

```
  FROM ubuntu

  CMD ["-l", "-"]

  ENTRYPOINT ["/usr/bin/wc"]
```

VOLUME

-- VOLUME ["/data"]

The VOLUME instruction creates a mount point with the specified name and marks

it as holding externally-mounted volumes from the native host or from other

containers.

USER

-- USER daemon

Sets the username or UID used for running subsequent commands.

The USER instruction can optionally be used to set the group or GID. The

following examples are all valid:

USER [user | user:group | uid | uid:gid | user:gid | uid:group ]

Until the USER instruction is set, instructions will be run as root. The USER

instruction can be used any number of times in a Containerfile, and will only affect

subsequent commands.

WORKDIR

-- WORKDIR /path/to/workdir

The WORKDIR instruction sets the working directory for the RUN, CMD,

ENTRYPOINT, COPY and ADD Containerfile commands that follow it. It can

be used multiple times in a single Containerfile. Relative paths are defined

relative to the path of the previous WORKDIR instruction. For example:

```
  WORKDIR /a

  WORKDIR b

  WORKDIR c

  RUN pwd
```

In the above example, the output of the pwd command is a/b/c.

ARG

-- ARG <name>[=<default value>]

The ARG instruction defines a variable that users can pass at build-time to

the builder with the podman build and buildah build commands using the

--build-arg <varname>=<value> flag. If a user specifies a build argument that

was not defined in the Containerfile, the build outputs a warning.

Note that a second FROM in a Containerfile sets the values associated with an

Arg variable to nil and they must be reset if they are to be used later in

the Containerfile

```
  [Warning] One or more build-args [foo] were not consumed
```

The Containerfile author can define a single variable by specifying ARG once or many

variables by specifying ARG more than once. For example, a valid Containerfile:

```
  FROM busybox

  ARG user1

  ARG buildno

  ...
```

A Containerfile author may optionally specify a default value for an ARG instruction:

```
  FROM busybox

  ARG user1=someuser

  ARG buildno=1

  ...
```

If an ARG value has a default and if there is no value passed at build-time, the

builder uses the default.

An ARG variable definition comes into effect from the line on which it is

defined in the Containerfile not from the argument's use on the command-line or

elsewhere. For example, consider this Containerfile:

```
  1 FROM busybox

  2 USER ${user:-some_user}

  3 ARG user

  4 USER $user

  ...
```

A user builds this file by calling:

```
  $ podman build --build-arg user=what_user Containerfile
```

The USER at line 2 evaluates to some_user as the user variable is defined on the

subsequent line 3. The USER at line 4 evaluates to what_user as user is

defined and the what_user value was passed on the command line. Prior to its definition by an

ARG instruction, any use of a variable results in an empty string.

Warning: It is not recommended to use build-time variables for

passing secrets like github keys, user credentials etc. Build-time variable

values are visible to any user of the image with the podman history command.

You can use an ARG or an ENV instruction to specify variables that are

available to the RUN instruction. Environment variables defined using the

ENV instruction always override an ARG instruction of the same name. Consider

this Containerfile with an ENV and ARG instruction.

```
  1 FROM ubuntu

  2 ARG CONT_IMG_VER

  3 ENV CONT_IMG_VER=v1.0.0

  4 RUN echo $CONT_IMG_VER
```

Then, assume this image is built with this command:

```
  $ podman build --build-arg CONT_IMG_VER=v2.0.1 Containerfile
```

In this case, the RUN instruction uses v1.0.0 instead of the ARG setting

passed by the user:v2.0.1 This behavior is similar to a shell

script where a locally scoped variable overrides the variables passed as

arguments or inherited from environment, from its point of definition.

Using the example above but a different ENV specification you can create more

useful interactions between ARG and ENV instructions:

```
  1 FROM ubuntu

  2 ARG CONT_IMG_VER

  3 ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}

  4 RUN echo $CONT_IMG_VER
```

Unlike an ARG instruction, ENV values are always persisted in the built

image. Consider a podman build without the --build-arg flag:

```
  $ podman build Containerfile
```

Using this Containerfile example, CONT_IMG_VER is still persisted in the image but

its value would be v1.0.0 as it is the default set in line 3 by the ENV instruction.

The variable expansion technique in this example allows you to pass arguments

from the command line and persist them in the final image by leveraging the

ENV instruction. Variable expansion is only supported for a limited set of

Containerfile instructions. ⟨#environment-replacement⟩

Container engines have a set of predefined ARG variables that you can use without a

corresponding ARG instruction in the Containerfile.

- HTTP_PROXY

- http_proxy

- HTTPS_PROXY

- https_proxy

- FTP_PROXY

- ftp_proxy

- NO_PROXY

- no_proxy

- ALL_PROXY

- all_proxy

To use these, pass them on the command line using --build-arg flag, for

example:

```
  $ podman build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
```

Platform/OS/Arch ARG

-- ARG <name>

When building multi-arch manifest-lists or images for a foreign-architecture,

it's often helpful to have access to platform details within the Containerfile.

For example, when using a RUN curl ... command to install OS/Arch specific

binary into the image. Or, if certain RUN operations are known incompatible

or non-performant when emulating a specific architecture.

There are several named ARG variables available. The purpose of each should be

self-evident by its name. However, in all cases these ARG values are not

automatically populated. You must always declare them within each FROM section

of the Containerfile.

The available ARG <name> variables are available with two prefixes:

•

TARGET... variable names represent details about the currently running build context (i.e. "inside" the container). These are often the most useful:

- TARGETOS: For example linux

- TARGETARCH: For example amd64

- TARGETPLATFORM: For example linux/amd64

- TARGETVARIANT: Uncommonly used, specific to TARGETARCH

•

BUILD... variable names signify details about the host performing the build (i.e. "outside" the container):

- BUILDOS: OS of host performing the build

- BUILDARCH: Arch of host performing the build

- BUILDPLATFORM: Combined OS/Arch of host performing the build

- BUILDVARIANT: Uncommonly used, specific to BUILDARCH

An example Containerfile that uses TARGETARCH to fetch an arch-specific binary could be:

```
  FROM busybox

  ARG TARGETARCH

  RUN curl -sSf -O https://example.com/downloads/bin-${TARGETARCH}.zip
```

Assuming the host platform is linux/amd64 and foreign-architecture emulation

enabled (e.g. qemu-user-static), then running the command:

```
  $ podman build --platform linux/s390x .
```

Would end up running curl on https://example.com/downloads/bin-s390x.zip and producing

a container image suited for the the linux/s390x platform. Note: Emulation isn't

strictly required, these special build-args will also function when building using

podman farm build.

ONBUILD

-- ONBUILD [INSTRUCTION]

The ONBUILD instruction adds a trigger instruction to an image. The

trigger is executed at a later time, when the image is used as the base for

another build. Container engines execute the trigger in the context of the downstream

build, as if the trigger existed immediately after the FROM instruction in

the downstream Containerfile.

You can register any build instruction as a trigger. A trigger is useful if

you are defining an image to use as a base for building other images. For

example, if you are defining an application build environment or a daemon that

is customized with a user-specific configuration.

Consider an image intended as a reusable python application builder. It must

add application source code to a particular directory, and might need a build

script called after that. You can't just call ADD and RUN now, because

you don't yet have access to the application source code, and it is different

for each application build.

-- Providing application developers with a boilerplate Containerfile to copy-paste

into their application is inefficient, error-prone, and

difficult to update because it mixes with application-specific code.

The solution is to use ONBUILD to register instructions in advance, to

run later, during the next build stage.

## SEE ALSO
buildah(1), podman(1), docker(1)

## HISTORY

```
May 2014, Compiled by Zac Dover (zdover at redhat dot com) based on docker.com Dockerfile documentation.
Feb 2015, updated by Brian Goff (cpuguy83@gmail.com) for readability
Sept 2015, updated by Sally O'Malley (somalley@redhat.com)
Oct 2016, updated by Addam Hardy (addam.hardy@gmail.com)
Aug 2021, converted Dockerfile man page to Containerfile by Dan Walsh (dwalsh@redhat.com)
```


containerignore

title: containerignore(5)

text:
# containerignore(5)

## NAME
.containerignore(.dockerignore) - files to ignore buildah or podman build context directory

## INTRODUCTION
Before container engines build an image, they look for a file named .containerignore or .dockerignore in the root context directory. If one of these file exists, the CLI modifies the context to exclude files and directories that match patterns specified in the file. This avoids adding them to images using the ADD or COPY instruction.

The CLI interprets the .containerignore or .dockerignore file as a newline-separated list of patterns similar to the file globs of Unix shells. For the purposes of matching, the root of the context is considered to be both the working and the root directory. For example, the patterns /foo/bar and foo/bar both exclude a file or directory named bar in the foo subdirectory of PATH or in the root of the git repository located at URL. Neither excludes anything else.

If a line in .containerignore or .dockerignore file starts with # in column 1, then this line is considered as a comment and is ignored before interpreted by the CLI.

## EXAMPLES
Here is an example .containerignore file:

```
# comment
*/temp*
*/*/temp*
temp?
```

This file causes the following build behavior: Rule Behavior

```
# comment 	Ignored.
*/temp* 	Exclude files and directories whose names start with temp in any immediate subdirectory of the root.
For example, the plain file /somedir/temporary.txt is excluded, as is the directory /somedir/temp.
*/*/temp* 	Exclude files and directories starting with temp from any subdirectory that is two levels below the
root. For example, /somedir/subdir/temporary.txt is excluded.
temp? 	Exclude files and directories in the root directory whose names are a one-character extension of temp. For example, /tempa and /tempb are excluded.
```

Matching is done using Go’s filepath.Match rules. A preprocessing step removes leading and trailing whitespace and eliminates . and .. elements using Go’s filepath.Clean. Lines that are blank after preprocessing are ignored.

Beyond Go’s filepath.Match rules, Docker also supports a special wildcard string ** that matches any number of directories (including zero). For example, */.go will exclude all files that end with .go that are found in all directories, including the root of the build context.

Lines starting with ! (exclamation mark) can be used to make exceptions to exclusions. The following is an example .containerignore file that uses this mechanism:

```
*.md
!README.md
```

All markdown files except README.md are excluded from the context.

The placement of ! exception rules influences the behavior: the last line of the .containerignore that matches a particular file determines whether it is included or excluded. Consider the following example:

```
*.md
!README*.md
README-secret.md
```

No markdown files are included in the context except README files other than README-secret.md.

Now consider this example:

```
*.md
README-secret.md
!README*.md
```

All of the README files are included. The middle line has no effect because !README*.md matches README-secret.md and comes last.

You can even use the .containerignore file to exclude the Containerfile or Dockerfile and .containerignore files. These files are still sent to the daemon because it needs them to do its job. But the ADD and COPY instructions do not copy them to the image.

Finally, you may want to specify which files to include in the context, rather than which to exclude. To achieve this, specify * as the first pattern, followed by one or more ! exception patterns.

## SEE ALSO
buildah-build(1), podman-build(1), docker-build(1)

## HISTORY
*Sep 2021, Compiled by Dan Walsh (dwalsh at redhat dot com) based on docker.com .dockerignore documentation.


containers-auth.json

title: containers-auth.json(5)

text:
# containers-auth.json(5)

## NAME
containers-auth.json - syntax for the registry authentication file

## DESCRIPTION
A file in JSON format controlling authentication against container image registries. The primary (read/write) file is stored at ${XDG_RUNTIME_DIR}/containers/auth.json on Linux; on Windows and macOS, at $HOME/.config/containers/auth.json.

When searching for the credential for a registry, the following files will be read in sequence until the valid credential is found: first reading the primary (read/write) file, or the explicit override using an option of the calling application. If credentials are not present there, the search continues in ${XDG_CONFIG_HOME}/containers/auth.json (usually /.config/containers/auth.json), $HOME/.docker/config.json, $HOME/.dockercfg.

Except for the primary (read/write) file, other files are read-only unless the user, using an option of the calling application, explicitly points at it as an override.

## FORMAT
The auth.json file stores, or references, credentials that allow the user to authenticate to container image registries. It is primarily managed by a login command from a container tool such as podman login, buildah login, or skopeo login.

Each entry contains a single hostname (e.g., docker.io) or a namespace (e.g., quay.io/user/image) as a key, and credentials in the form of a base64-encoded string as value of auth. The base64-encoded string contains a concatenation of the username, a colon, and the password.

When checking for available credentials, the relevant repository is matched against available keys in its hierarchical order, going from most-specific to least-specific. For example, an image pull for my-registry.local/namespace/user/image:latest will result in a lookup in auth.json in the following order:

- my-registry.local/namespace/user/image

- my-registry.local/namespace/user

- my-registry.local/namespace

- my-registry.local

This way it is possible to setup multiple credentials for a single registry which can be distinguished by their path.

The following example shows the values found in auth.json after the user logged in to their accounts on quay.io and docker.io:

```
{
	"auths": {
		"docker.io": {
			"auth": "erfi7sYi89234xJUqaqxgmzcnQ2rRFWM5aJX0EC="
		},
		"quay.io": {
			"auth": "juQAqGmz5eR1ipzx8Evn6KGdw8fEa1w5MWczmgY="
		}
	}
}
```

This example demonstrates how to use multiple paths for a single registry, while preserving a fallback for my-registry.local:

```
{
	"auths": {
		"my-registry.local/foo/bar/image": {
			"auth": "…"
		},
		"my-registry.local/foo": {
			"auth": "…"
		},
		"my-registry.local": {
			"auth": "…"
		},
	}
}
```

An entry can be removed by using a logout command from a container tool such as podman logout or buildah logout.

In addition, credential helpers can be configured for specific registries, and the credentials-helper software can be used to manage the credentials more securely than storing only base64-encoded credentials in auth.json.

When the credential helper is in use on a Linux platform, the auth.json file would contain keys that specify the registry domain, and values that specify the suffix of the program to use (i.e. everything after docker-credential-). For example:

```
{

    "auths": {

        "localhost:5001": {}

    },

    "credHelpers": {
		"registry.example.com": "secretservice"
	}
}
```

For more information on credential helpers, please reference the GitHub docker-credential-helpers project ⟨https://github.com/docker/docker-credential-helpers/releases⟩.

## SEE ALSO

```
buildah-login(1), buildah-logout(1), podman-login(1), podman-logout(1), skopeo-login(1), skopeo-logout(1)
```

## HISTORY
Feb 2020, Originally compiled by Tom Sweeney ⟨tsweeney@redhat.com⟩


containers-certs.d

title: containers-certs.d(5)

summary: Directory for storing custom container\-registry TLS configurations

text:
# containers-certs.d(5)

## NAME
containers-certs.d - Directory for storing custom container-registry TLS configurations

## DESCRIPTION
A custom TLS configuration for a container registry can be configured by creating a directory under $HOME/.config/containers/certs.d or /etc/containers/certs.d. The name of the directory must correspond to the host:port of the registry (e.g., my-registry.com:5000).

## Directory Structure
A certs directory can contain one or more files with the following extensions:

- *.crt files with this extensions will be interpreted as CA certificates

- *.cert files with this extensions will be interpreted as client certificates

- *.key files with this extensions will be interpreted as client keys

Note that the client certificate-key pair will be selected by the file name (e.g., client.{cert,key}). An exemplary setup for a registry running at my-registry.com:5000 may look as follows:

```
/etc/containers/certs.d/    <- Certificate directory
└── my-registry.com:5000    <- Hostname:port

   ├── client.cert          <- Client certificate

   ├── client.key           <- Client key

   └── ca.crt               <- Certificate authority that signed the registry certificate
```

## HISTORY
Feb 2019, Originally compiled by Valentin Rothberg ⟨rothberg@redhat.com⟩


containers-mounts.conf

title: containers-mounts.conf(5)

text:
# containers-mounts.conf(5)

## NAME
containers-mounts.conf - configuration file for default mounts in containers

## DESCRIPTION
The mounts.conf file specifies volume mount directories that are automatically mounted inside containers. Container processes can then use this content. Usually these directories are used for passing secrets or credentials required by the package software to access remote package repositories. Note that for security reasons, tools adhering to the mounts.conf are expected to copy the contents instead of bind mounting the paths from the host.

## FORMAT
The format of the mounts.conf is the volume format /SRC:/DEST, one mount per line. For example, a mounts.conf with the line /usr/share/secrets:/run/secrets would cause the contents of the /usr/share/secrets directory on the host to be mounted on the /run/secrets directory inside the container. Setting mountpoints allows containers to use the files of the host, for instance, to use the host's subscription to some enterprise Linux distribution.

## FILES
Some distributions may provide a /usr/share/containers/mounts.conf file to provide default mounts, but users can create a /etc/containers/mounts.conf, to specify their own special volumes to mount in the container. When Podman runs in rootless mode, the file $HOME/.config/containers/mounts.conf will override the default if it exists.

## HISTORY
Aug 2018, Originally compiled by Valentin Rothberg ⟨vrothberg@suse.com⟩


containers-policy.json

title: containers-policy.json(5)

text:
# containers-policy.json(5)

## NAME
containers-policy.json - syntax for the signature verification policy file

## DESCRIPTION
Signature verification policy files are used to specify policy, e.g. trusted keys, applicable when deciding whether to accept an image, or individual signatures of that image, as valid.

By default, the policy is read from $HOME/.config/containers/policy.json, if it exists, otherwise from /etc/containers/policy.json; applications performing verification may allow using a different policy instead.

## FORMAT
The signature verification policy file, usually called policy.json, uses a JSON format. Unlike some other JSON files, its parsing is fairly strict: unrecognized, duplicated or otherwise invalid fields cause the entire file, and usually the entire operation, to be rejected.

The purpose of the policy file is to define a set of policy requirements for a container image, usually depending on its location (where it is being pulled from) or otherwise defined identity.

Policy requirements can be defined for:

•

An individual scope in a transport. The transport values are the same as the transport prefixes when pushing/pulling images (e.g. docker:, atomic:), and scope values are defined by each transport; see below for more details.

Usually, a scope can be defined to match a single image, and various prefixes of

such a most specific scope define namespaces of matching images.

•

A default policy for a single transport, expressed using an empty string as a scope

•

A global default policy.

If multiple policy requirements match a given image, only the requirements from the most specific match apply, the more general policy requirements definitions are ignored.

This is expressed in JSON using the top-level syntax

```
{

    "default": [/* policy requirements: global default */]

    "transports": {

        transport_name: {

            "": [/* policy requirements: default for transport $transport_name */],

            scope_1: [/* policy requirements: default for $scope_1 in $transport_name */],

            scope_2: [/*…*/]

            /*…*/

        },

        transport_name_2: {/*…*/}

        /*…*/

    }
}
```

The global default set of policy requirements is mandatory; all of the other fields (transports itself, any specific transport, the transport-specific default, etc.) are optional. <!-- NOTE: Keep this in sync with transports/transports.go! -->

## Supported transports and their scopes
See containers-transports(5) for general documentation about the transports and their reference syntax.

### atomic:
The deprecated atomic: transport refers to images in an Atomic Registry.

Supported scopes use the form hostname[:port][/namespace[/imagestream [:tag]]], i.e. either specifying a complete name of a tagged image, or prefix denoting a host/namespace/image stream, or a wildcarded expression starting with *. for matching all subdomains. For wildcarded subdomain matching, *.example.com is a valid case, but example*.*.com is not.

Note: The hostname and port refer to the container registry host and port (the one used e.g. for docker pull), not to the OpenShift API host and port.

### containers-storage:
Supported scopes have the form [storage-specifier]image-scope.

[storage-specifier] is usually [graph-driver-name@graph-root], e.g. [overlay@/var/lib/containers/storage].

image-scope matching the individual image is - a named Docker reference in the fully expanded form, either using a tag or digest. For example, docker.io/library/busybox:latest (not busybox:latest) - and/or (depending on which one the user’s input provides) @image-id

More general scopes are prefixes of individual-image scopes, and specify a less-precisely-specified image, or a repository (by omitting first the image ID, if any; then the digest, if any; and finally a tag, if any), a repository namespace, or a registry host (by only specifying the host name and possibly a port number).

Finally, two full-store specifiers matching all images in the store are valid scopes: - [graph-driver-name@graph-root] and - [graph-root]

Note that some tools like Podman and Buildah hard-code overrides of the signature verification policy for “push” operations, allowing these operations regardless of configuration in policy.json.

### dir:
The dir: transport refers to images stored in local directories.

Supported scopes are paths of directories (either containing a single image or subdirectories possibly containing images).

Note: - The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. - The top-level scope "/" is forbidden; use the transport default scope "",

for consistency with other transports.

### docker:
The docker: transport refers to images in a registry implementing the "Docker Registry HTTP API V2".

Scopes matching individual images are named Docker references in the fully expanded form, either using a tag or digest. For example, docker.io/library/busybox:latest (not busybox:latest).

More general scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest), a repository namespace, or a registry host (by only specifying the host name and possibly a port number) or a wildcarded expression starting with *., for matching all subdomains (not including a port number). For wildcarded subdomain matching, *.example.com is a valid case, but example*.*.com is not.

### docker-archive:
Only the default "" scope is supported.

### docker-daemon:
For references using the algo:digest format (referring to an image ID), only the default "" scope is used.

For images using a named reference, scopes matching individual images are in the fully expanded form, either using a tag or digest. For example, docker.io/library/busybox:latest (not busybox:latest).

More general named scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest), a repository namespace, or a registry host (by only specifying the host name and possibly a port number) or a wildcarded expression starting with *., for matching all subdomains (not including a port number). For wildcarded subdomain matching, *.example.com is a valid case, but example*.*.com is not.

### oci:
The oci: transport refers to images in directories compliant with "Open Container Image Layout Specification".

Supported scopes are paths to directories (either containing an OCI layout, or subdirectories possibly containing OCI layout directories). The reference annotation value, if any, is not used.

Note: - The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. - The top-level scope "/" is forbidden; use the transport default scope "",

for consistency with other transports.

### oci-archive:
Supported scopes are paths to OCI archives, and their parent directories (either containing a single archive, or subdirectories possibly containing archives). The reference annotation value, if any, is not used.

Note: - The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. - The top-level scope "/" is forbidden; use the transport default scope "",

for consistency with other transports.

### sif:
Supported scopes are paths to Singularity images, and their parent directories (either containing images, or subdirectories possibly containing images).

Note: - The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored. - The top-level scope "/" is forbidden; use the transport default scope "",

for consistency with other transports.

### tarball:
The tarball: transport is an implementation detail of some import workflows. Only the default "" scope is supported.

## Policy Requirements
Using the mechanisms above, a set of policy requirements is looked up. The policy requirements are represented as a JSON array of individual requirement objects. For an image to be accepted, all of the requirements must be satisfied simultaneously.

The policy requirements can also be used to decide whether an individual signature is accepted (= is signed by a recognized key of a known author); in that case some requirements may apply only to some signatures, but each signature must be accepted by at least one requirement object.

The following requirement objects are supported:

### insecureAcceptAnything
A simple requirement with the following syntax

```
{"type":"insecureAcceptAnything"}
```

This requirement accepts any image (but note that other requirements in the array still apply).

When deciding to accept an individual signature, this requirement does not have any effect; it does not cause the signature to be accepted, though.

This is useful primarily for policy scopes where no signature verification is required; because the array of policy requirements must not be empty, this requirement is used to represent the lack of requirements explicitly.

### reject
A simple requirement with the following syntax:

```
{"type":"reject"}
```

This requirement rejects every image, and every signature.

### signedBy
This requirement requires an image to be signed using “simple signing” with an expected identity, or accepts a signature if it is using an expected identity and key.

```
{

    "type":    "signedBy",

    "keyType": "GPGKeys", /* The only currently supported value */

    "keyPath": "/path/to/local/keyring/file",

    "keyPaths": ["/path/to/local/keyring/file1","/path/to/local/keyring/file2"…],

    "keyData": "base64-encoded-keyring-data",

    "signedIdentity": identity_requirement
}
```

<!-- Later: other keyType values --> Exactly one of keyPath, keyPaths and keyData must be present, containing a GPG keyring of one or more public keys. Only signatures made by these keys are accepted.

The signedIdentity field, a JSON object, specifies what image identity the signature claims about the image. One of the following alternatives are supported:

•

The identity in the signature must exactly match the image identity. Note that with this, referencing an image by digest (with a signature claiming a repository:tag identity) will fail.

```
  {"type":"matchExact"}
```

•

If the image identity carries a tag, the identity in the signature must exactly match; if the image identity uses a digest reference, the identity in the signature must be in the same repository as the image identity (using any tag).

(Note that with images identified using digest references, the digest from the reference is validated even before signature verification starts.)

```
  {"type":"matchRepoDigestOrExact"}
```

•

The identity in the signature must be in the same repository as the image identity. This is useful e.g. to pull an image using the :latest tag when the image is signed with a tag specifying an exact image version.

```
  {"type":"matchRepository"}
```

•

The identity in the signature must exactly match a specified identity. This is useful e.g. when locally mirroring images signed using their public identity.

```
  {

      "type": "exactReference",

      "dockerReference": docker_reference_value

  }
```

•

The identity in the signature must be in the same repository as a specified identity. This combines the properties of matchRepository and exactReference.

```
  {

      "type": "exactRepository",

      "dockerRepository": docker_repository_value

  }
```

•

Prefix remapping:

If the image identity matches the specified prefix, that prefix is replaced by the specified “signed prefix”

(otherwise it is used as unchanged and no remapping takes place);

matching then follows the matchRepoDigestOrExact semantics documented above

(i.e. if the image identity carries a tag, the identity in the signature must exactly match,

if it uses a digest reference, the repository must match).

The prefix and signedPrefix values can be either host[:port] values

(matching exactly the same host[:port], string),

repository namespaces, or repositories (i.e. they must not contain tags/digests),

and match as prefixes of the fully expanded form.

For example, docker.io/library/busybox (not busybox) to specify that single repository,

or docker.io/library (not an empty string) to specify the parent namespace of docker.io/library/busybox==busybox).

The prefix value is usually the same as the scope containing the parent signedBy requirement.

```
  {

      "type": "remapIdentity",

      "prefix": prefix,

      "signedPrefix": prefix,

  }
```

If the signedIdentity field is missing, it is treated as matchRepoDigestOrExact.

Note: matchExact, matchRepoDigestOrExact and matchRepository can be only used if a Docker-like image identity is provided by the transport. In particular, the dir: and oci: transports can be only used with exactReference or exactRepository. <!-- ### `signedBaseLayer` -->

### sigstoreSigned
This requirement requires an image to be signed using a sigstore signature with an expected identity and key.

```
{

    "type":    "sigstoreSigned",

    "keyPath": "/path/to/local/public/key/file",

    "keyPaths": ["/path/to/first/public/key/one", "/path/to/first/public/key/two"],

    "keyData": "base64-encoded-public-key-data",

    "keyDatas": ["base64-encoded-public-key-one-data", "base64-encoded-public-key-two-data"]

    "fulcio": {

        "caPath": "/path/to/local/CA/file",

        "caData": "base64-encoded-CA-data",

        "oidcIssuer": "https://expected.OIDC.issuer/",

        "subjectEmail", "expected-signing-user@example.com",

    },

    "pki": {

        "caRootsPath": "/path/to/local/CARoots/file",

        "caRootsData": "base64-encoded-CARoots-data",

        "caIntermediatesPath": "/path/to/local/CAIntermediates/file",

        "caIntermediatesData": "base64-encoded-CAIntermediates-data",

        "subjectHostname": "expected-signing-hostname.example.com",

        "subjectEmail": "expected-signing-user@example.com"

    },

    "rekorPublicKeyPath": "/path/to/local/public/key/file",

    "rekorPublicKeyPaths": ["/path/to/local/public/key/one","/path/to/local/public/key/two"],

    "rekorPublicKeyData": "base64-encoded-public-key-data",

    "rekorPublicKeyDatas": ["base64-encoded-public-key-one-data","base64-encoded-public-key-two-data"],

    "signedIdentity": identity_requirement
}
```

Exactly one of keyPath, keyPaths, keyData, keyDatas, fulcio and pki must be present.

If keyPath or keyData is present, it contains a sigstore public key. Only signatures made by this key are accepted.

If keyPaths or keyDatas is present, it contains sigstore public keys. Only signatures made by any key in the list are accepted.

If fulcio is present, the signature must be based on a Fulcio-issued certificate. One of caPath and caData must be specified, containing the public key of the Fulcio instance. Both oidcIssuer and subjectEmail are mandatory, exactly specifying the expected identity provider, and the identity of the user obtaining the Fulcio certificate.

If pki is present, the signature must be based on a non-Fulcio X.509 certificate. One of caRootsPath and caRootsData must be specified, containing certificates of the CAs. Only one of caIntermediatesPath and caIntermediatesData can be present, containing certificates of the intermediate CAs. One of subjectEmail and subjectHostname must be specified, exactly specifying the expected identity to which the certificate was issued.

At most one of rekorPublicKeyPath, rekorPublicKeyPaths, rekorPublicKeyData and rekorPublicKeyDatas can be present; it is mandatory if fulcio is specified. If a Rekor public key is specified, the signature must have been uploaded to a Rekor server and the signature must contain an (offline-verifiable) “signed entry timestamp” proving the existence of the Rekor log record, signed by one of the provided public keys.

The signedIdentity field has the same semantics as in the signedBy requirement described above. Note that cosign-created signatures only contain a repository, so only matchRepository and exactRepository can be used to accept them (and that does not protect against substitution of a signed image with an unexpected tag).

To use this with images hosted on image registries, the use-sigstore-attachments option needs to be enabled for the relevant registry or repository in the client's containers-registries.d(5).

## Examples
It is strongly recommended to set the default policy to reject, and then selectively allow individual transports and scopes as desired.

### A reasonably locked-down system
(Note that the /*…*/ comments are not valid in JSON, and must not be used in real policies.)

```
{

    "default": [{"type": "reject"}], /* Reject anything not explicitly allowed */

    "transports": {

        "docker": {

            /* Allow installing images from a specific repository namespace, without cryptographic verification.

               This namespace includes images like openshift/hello-openshift and openshift/origin. */

            "docker.io/openshift": [{"type": "insecureAcceptAnything"}],

            /* Similarly, allow installing the “official” busybox images.  Note how the fully expanded

               form, with the explicit /library/, must be used. */

            "docker.io/library/busybox": [{"type": "insecureAcceptAnything"}],

            /* Allow installing images from all subdomains */

            "*.temporary-project.example.com": [{"type": "insecureAcceptAnything"}],

            /* A sigstore-signed repository */

            "hostname:5000/myns/sigstore-signed-with-full-references": [

                {

                    "type": "sigstoreSigned",

                    "keyPath": "/path/to/sigstore-pubkey.pub"

                }

            ],

            /* A sigstore-signed repository using the community Fulcio+Rekor servers.

               The community servers’ public keys can be obtained from

               https://github.com/sigstore/sigstore/tree/main/pkg/tuf/repository/targets .  */

            "hostname:5000/myns/sigstore-signed-fulcio-rekor": [

                {

                    "type": "sigstoreSigned",

                    "fulcio": {

                        "caPath": "/path/to/fulcio_v1.crt.pem",

                        "oidcIssuer": "https://github.com/login/oauth",

                        "subjectEmail": "test-user@example.com"

                    },

                    "rekorPublicKeyPath": "/path/to/rekor.pub",

                }

            ],

            /* A Sigstore-signed repository using a certificate generated by a custom public-key infrastructure.*/

            "hostname:5000/myns/sigstore-signed-byopki": [

                {

                    "type": "sigstoreSigned",

                    "pki": {

                        "caRootsPath": "/path/to/pki_root_crts.pem",

                        "caIntermediatesPath": "/path/to/pki_intermediate_crts.pem",

                        "subjectHostname": "test-user.example.com"

                        "subjectEmail": "test-user@example.com"

                    }

                }

            ],

            /* A sigstore-signed repository, accepts signatures by /usr/bin/cosign */

            "hostname:5000/myns/sigstore-signed-allows-malicious-tag-substitution": [

                {

                    "type": "sigstoreSigned",

                    "keyPath": "/path/to/sigstore-pubkey.pub",

                    "signedIdentity": {"type": "matchRepository"}

                }

            ],

            /* A sigstore-signed repository using the community Fulcio+Rekor servers,

               accepts signatures by /usr/bin/cosign.

               The community servers’ public keys can be obtained from

               https://github.com/sigstore/sigstore/tree/main/pkg/tuf/repository/targets .  */

            "hostname:5000/myns/sigstore-signed-fulcio-rekor- allows-malicious-tag-substitution": [

                {

                    "type": "sigstoreSigned",

                    "fulcio": {

                        "caPath": "/path/to/fulcio_v1.crt.pem",

                        "oidcIssuer": "https://github.com/login/oauth",

                        "subjectEmail": "test-user@example.com"

                    },

                    "rekorPublicKeyPath": "/path/to/rekor.pub",

                    "signedIdentity": { "type": "matchRepository" }

                }

            ]

              /* Other docker: images use the global default policy and are rejected */

        },

        "dir": {

            "": [{"type": "insecureAcceptAnything"}] /* Allow any images originating in local directories */

        },

        "atomic": {

            /* The common case: using a known key for a repository or set of repositories */

            "hostname:5000/myns/official": [

                {

                    "type": "signedBy",

                    "keyType": "GPGKeys",

                    "keyPath": "/path/to/official-pubkey.gpg"

                }

            ],

            /* A more complex example, for a repository which contains a mirror of a third-party product,

               which must be signed-off by local IT */

            "hostname:5000/vendor/product": [

                { /* Require the image to be signed by the original vendor, using the vendor's repository location. */

                    "type": "signedBy",

                    "keyType": "GPGKeys",

                    "keyPath": "/path/to/vendor-pubkey.gpg",

                    "signedIdentity": {

                        "type": "exactRepository",

                        "dockerRepository": "vendor-hostname/product/repository"

                    }

                },

                { /* Require the image to _also_ be signed by a local reviewer. */

                    "type": "signedBy",

                    "keyType": "GPGKeys",

                    "keyPath": "/path/to/reviewer-pubkey.gpg"

                }

            ],

            /* A way to mirror many repositories from a single vendor */

            "private-mirror:5000/vendor-mirror": [

                { /* Require the image to be signed by the original vendor, using the vendor's repository location.

                     For example, private-mirror:5000/vendor-mirror/productA/image1:latest needs to be signed as

                     vendor.example/productA/image1:latest . */

                    "type": "signedBy",

                    "keyType": "GPGKeys",

                    "keyPath": "/path/to/vendor-pubkey.gpg",

                    "signedIdentity": {

                        "type": "remapIdentity",

                        "prefix": "private-mirror:5000/vendor-mirror",

                        "signedPrefix": "vendor.example.com"

                    }

                }

            ]

        }

    }
}
```

### Completely disable security, allow all images, do not trust any signatures

```
{

    "default": [{"type": "insecureAcceptAnything"}]
}
```

## SEE ALSO
atomic(1)

## HISTORY
August 2018, Rename to containers-policy.json(5) by Valentin Rothberg ⟨vrothberg@suse.com⟩

September 2016, Originally compiled by Miloslav Trmač ⟨mitr@redhat.com⟩


containers-registries.conf

title: containers-registries.conf(5)

text:
# containers-registries.conf(5)

## NAME
containers-registries.conf - Syntax of System Registry Configuration File

## DESCRIPTION
The CONTAINERS-REGISTRIES configuration file is a system-wide configuration file for container image registries. The file format is TOML.

Container engines will use the $HOME/.config/containers/registries.conf if it exists, otherwise they will use /etc/containers/registries.conf

### GLOBAL SETTINGS
unqualified-search-registries : An array of host[:port] registries to try when pulling an unqualified image, in order.

credential-helpers : An array of default credential helpers used as external credential stores. Note that "containers-auth.json" is a reserved value to use auth files as specified in containers-auth.json(5). The credential helpers are set to ["containers-auth.json"] if none are specified.

additional-layer-store-auth-helper : A string containing the helper binary name. This enables passing registry credentials to an

Additional Layer Store every time an image is read using the docker://

transport so that it can access private registries. See the 'Enabling Additional Layer Store to access to private registries' section below for

more details.

### NAMESPACED [[registry]] SETTINGS
The bulk of the configuration is represented as an array of [[registry]] TOML tables; the settings may therefore differ among different registries as well as among different namespaces/repositories within a registry.

### Choosing a [[registry]] TOML table
Given an image name, a single [[registry]] TOML table is chosen based on its prefix field.

prefix: A prefix of the user-specified image name, i.e. using one of the following formats:

- host[:port]

- host[:port]/namespace[/_namespace_…]

- host[:port]/namespace[/_namespace_…]/repo

- host[:port]/namespace[/_namespace_…]/repo(:_tag|@digest)

- [*.]host

The user-specified image name must start with the specified prefix (and continue with the appropriate separator) for a particular [[registry]] TOML table to be considered; (only) the TOML table with the longest match is used. It can also include wildcarded subdomains in the format *.example.com. The wildcard should only be present at the beginning as shown in the formats above. Other cases will not work. For example, *.example.com is valid but example.*.com, *.example.com/foo and *.example.com:5000/foo/bar:baz are not. Note that * matches an arbitrary number of subdomains. *.example.com will hence match bar.example.com, foo.bar.example.com and so on.

As a special case, the prefix field can be missing; if so, it defaults to the value of the location field (described below).

### Per-namespace settings
insecure : true or false. By default, container runtimes require TLS when retrieving images from a registry. If insecure is set to true, unencrypted HTTP as well as TLS connections with untrusted certificates are allowed.

blocked : true or false. If true, pulling images with matching names is forbidden.

### Remapping and mirroring registries
The user-specified image reference is, primarily, a "logical" image name, always used for naming the image. By default, the image reference also directly specifies the registry and repository to use, but the following options can be used to redirect the underlying accesses to different registry servers or locations (e.g. to support configurations with no access to the internet without having to change Dockerfiles, or to add redundancy).

location : Accepts the same format as the prefix field, and specifies the physical location of the prefix-rooted namespace.

By default, this is equal to prefix (in which case prefix can be omitted and the [[registry]] TOML table can only specify location).

Example: Given

```
prefix = "example.com/foo"
location = "internal-registry-for-example.com/bar"
```

requests for the image example.com/foo/myimage:latest will actually work with the internal-registry-for-example.com/bar/myimage:latest image.

With a prefix containing a wildcard in the format: "*.example.com" for subdomain matching, the location can be empty. In such a case, prefix matching will occur, but no reference rewrite will occur. The original requested image string will be used as-is. But other settings like insecure / blocked / mirrors will be applied to matching images.

Example: Given

```
prefix = "*.example.com"
```

requests for the image blah.example.com/foo/myimage:latest will be used as-is. But other settings like insecure/blocked/mirrors will be applied to matching images

mirror : An array of TOML tables specifying (possibly-partial) mirrors for the prefix-rooted namespace (i.e., the current [[registry]] TOML table).

The mirrors are attempted in the specified order; the first one that can be contacted and contains the image will be used (and if none of the mirrors contains the image, the primary location specified by the registry.location field, or using the unmodified user-specified reference, is tried last).

Each TOML table in the mirror array can contain the following fields: - location： same semantics as specified in the [[registry]] TOML table - insecure： same semantics as specified in the [[registry]] TOML table - pull-from-mirror: all, digest-only or tag-only. If "digest-only"， mirrors will only be used for digest pulls. Pulling images by tag can potentially yield different images, depending on which endpoint we pull from. Restricting mirrors to pulls by digest avoids that issue. If "tag-only", mirrors will only be used for tag pulls. For a more up-to-date and expensive mirror that it is less likely to be out of sync if tags move, it should not be unnecessarily used for digest references. Default is "all" (or left empty), mirrors will be used for both digest pulls and tag pulls unless the mirror-by-digest-only is set for the primary registry. Note that this per-mirror setting is allowed only when mirror-by-digest-only is not configured for the primary registry.

mirror-by-digest-only : true or false. If true, mirrors will only be used during pulling if the image reference includes a digest. Note that if all mirrors are configured to be digest-only, images referenced by a tag will only use the primary registry. If all mirrors are configured to be tag-only, images referenced by a digest will only use the primary registry.

Referencing an image by digest ensures that the same is always used (whereas referencing an image by a tag may cause different registries to return different images if the tag mapping is out of sync).

Note: Redirection and mirrors are currently processed only when reading a single image, not when pushing to a registry nor when doing any other kind of lookup/search on a on a registry. This may change in the future.

### Short-Name Aliasing
The use of unqualified-search registries entails an ambiguity as it is unclear from which registry a given image, referenced by a short name, may be pulled from.

As mentioned in the note at the end of this man page, using short names is subject to the risk of hitting squatted registry namespaces. If the unqualified-search registries are set to ["registry1.com", "registry2.com"] an attacker may take over a namespace of registry1.com such that an image may be pulled from registry1.com instead of the intended source registry2.com.

While it is highly recommended to always use fully-qualified image references, existing deployments using short names may not be easily changed. To circumvent the aforementioned ambiguity, so called short-name aliases can be configured that point to a fully-qualified image reference.

Short-name aliases can be configured in the [aliases] table in the form of "name"="value" with the left-hand name being the short name (e.g., "image") and the right-hand value being the fully-qualified image reference (e.g., "registry.com/namespace/image"). Note that neither "name" nor "value" can include a tag or digest. Moreover, "name" must be a short name and hence cannot include a registry domain or refer to localhost.

When pulling a short name, the configured aliases table will be used for resolving the short name. If a matching alias is found, it will be used without further consulting the unqualified-search registries list. If no matching alias is found, the behavior can be controlled via the short-name-mode option as described below.

Note that tags and digests are stripped off a user-specified short name for alias resolution. Hence, "image", "image:tag" and "image@digest" all resolve to the same alias (i.e., "image"). Stripped off tags and digests are later appended to the resolved alias.

Further note that drop-in configuration files (see containers-registries.conf.d(5)) can override aliases in the specific loading order of the files. If the "value" of an alias is empty (i.e., ""), the alias will be erased. However, a given "name" may only be specified once in a single config file.

### Short-Name Aliasing: Modes
The short-name-mode option supports three modes to control the behaviour of short-name resolution.

•

enforcing: If only one unqualified-search registry is set, use it as there is no ambiguity. If there is more than one registry and the user program is running in a terminal (i.e., stdout stdin are a TTY), prompt the user to select one of the specified search registries. If the program is not running in a terminal, the ambiguity cannot be resolved which will lead to an error.

•

permissive: Behaves as enforcing but does not lead to an error if the program is not running in a terminal. Instead, fallback to using all unqualified-search registries.

•

disabled: Use all unqualified-search registries without prompting.

If short-name-mode is not specified at all or left empty, default to the permissive mode. If the user-specified short name was not aliased already, the enforcing and permissive mode if prompted, will record a new alias after a successful pull. Note that the recorded alias will be written to /var/cache/containers/short-name-aliases.conf for root to have a clear separation between possibly human-edited registries.conf files and the machine-generated short-name-aliases-conf. Note that $HOME/.cache is used for rootless users. If an alias is specified in a registries.conf file and also the machine-generated short-name-aliases.conf, the short-name-aliases.conf file has precedence.

### Normalization of docker.io references
The Docker Hub docker.io is handled in a special way: every push and pull operation gets internally normalized with /library if no other specific namespace is defined (for example on docker.io/namespace/image).

(Note that the above-described normalization happens to match the behavior of Docker.)

This means that a pull of docker.io/alpine will be internally translated to docker.io/library/alpine. A pull of docker.io/user/alpine will not be rewritten because this is already the correct remote path.

Therefore, to remap or mirror the docker.io images in the (implied) /library namespace (or that whole namespace), the prefix and location fields in this configuration file must explicitly include that /library namespace. For example prefix = "docker.io/library/alpine" and not prefix = "docker.io/alpine". The latter would match the docker.io/alpine/* repositories but not the docker.io/[library/]alpine image).

### EXAMPLE

```
unqualified-search-registries = ["example.com"]
[[registry]]
prefix = "example.com/foo"
insecure = false
blocked = false
location = "internal-registry-for-example.com/bar"
[[registry.mirror]]
location = "example-mirror-0.local/mirror-for-foo"
[[registry.mirror]]
location = "example-mirror-1.local/mirrors/foo"
insecure = true
[[registry]]
location = "registry.com"
[[registry.mirror]]
location = "mirror.registry.com"
```

Given the above, a pull of example.com/foo/image:latest will try:

1.

example-mirror-0.local/mirror-for-foo/image:latest

2.

example-mirror-1.local/mirrors/foo/image:latest

3.

internal-registry-for-example.com/bar/image:latest

in order, and use the first one that exists.

Note that a mirror is associated only with the current [[registry]] TOML table. If using the example above, pulling the image registry.com/image:latest will hence only reach out to mirror.registry.com, and the mirrors associated with example.com/foo will not be considered.

### Enabling Additional Layer Store to access to private registries
The additional-layer-store-auth-helper option enables passing registry credentials to an Additional Layer Store so that it can access private registries.

When accessing a private registry via an Additional Layer Store, a helper binary needs to be provided. This helper binary is registered via the additional-layer-store-auth-helper option. Every time an image is read using the docker:// transport, the specified helper binary is executed and receives registry credentials from stdin in the following format.

```
{

  "$image_reference": {

    "username": "$username",

    "password": "$password",

    "identityToken": "$identityToken"

  }
}
```

The format of $image_reference is $repo{:$tag|@$digest}.

Additional Layer Stores can use this helper binary to access the private registry.

## VERSION 1 FORMAT - DEPRECATED
VERSION 1 format is still supported but it does not support using registry mirrors, longest-prefix matches, or location rewriting.

The TOML format is used to build a simple list of registries under three categories: registries.search, registries.insecure, and registries.block. You can list multiple registries using a comma separated list.

Search registries are used when the caller of a container runtime does not fully specify the container image that they want to execute. These registries are prepended onto the front of the specified container image until the named image is found at a registry.

Note that insecure registries can be used for any registry, not just the registries listed under search.

The registries.insecure and registries.block lists have the same meaning as the insecure and blocked fields in the current version.

### EXAMPLE
The following example configuration defines two searchable registries, one insecure registry, and two blocked registries.

```
[registries.search]
registries = ['registry1.com', 'registry2.com']
[registries.insecure]
registries = ['registry3.com']
[registries.block]
registries = ['registry.untrusted.com', 'registry.unsafe.com']
```

## NOTE: RISK OF USING UNQUALIFIED IMAGE NAMES
We recommend always using fully qualified image names including the registry server (full dns name), namespace, image name, and tag (e.g., registry.redhat.io/ubi8/ubi:latest). When using short names, there is always an inherent risk that the image being pulled could be spoofed. For example, a user wants to pull an image named foobar from a registry and expects it to come from myregistry.com. If myregistry.com is not first in the search list, an attacker could place a different foobar image at a registry earlier in the search list. The user would accidentally pull and run the attacker's image and code rather than the intended content. We recommend only adding registries which are completely trusted, i.e. registries which don't allow unknown or anonymous users to create accounts with arbitrary names. This will prevent an image from being spoofed, squatted or otherwise made insecure. If it is necessary to use one of these registries, it should be added at the end of the list.

It is recommended to use fully-qualified images for pulling as the destination registry is unambiguous. Pulling by digest (i.e., quay.io/repository/name@digest) further eliminates the ambiguity of tags.

## SEE ALSO
containers-auth.json(5) containers-certs.d(5)

## HISTORY
Dec 2019, Warning added for unqualified image names by Tom Sweeney ⟨tsweeney@redhat.com⟩

Mar 2019, Added additional configuration format by Sascha Grunert ⟨sgrunert@suse.com⟩

Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg ⟨vrothberg@suse.com⟩

Jun 2018, Updated by Tom Sweeney ⟨tsweeney@redhat.com⟩

Aug 2017, Originally compiled by Brent Baude ⟨bbaude@redhat.com⟩


containers-registries.conf.d

title: containers-registries.conf.d(5)

summary: directory for drop\-in registries.conf files

text:
# containers-registries.conf.d(5)

## NAME
containers-registries.conf.d - directory for drop-in registries.conf files

## DESCRIPTION
CONTAINERS-REGISTRIES.CONF.D is a system-wide directory for drop-in configuration files in the containers-registries.conf(5) format.

By default, the directory is located at /etc/containers/registries.conf.d.

## CONFIGURATION PRECEDENCE
Once the main configuration at /etc/containers/registries.conf is loaded, the files in /etc/containers/registries.conf.d are loaded in alpha-numerical order. Then the conf files in $HOME/.config/containers/registries.conf.d are loaded in alpha-numerical order, if they exist. If the $HOME/.config/containers/registries.conf is loaded, only the conf files under $HOME/.config/containers/registries.conf.d are loaded in alpha-numerical order. Specified fields in a conf file will overwrite any previous setting. Note that only files with the .conf suffix are loaded, other files and sub-directories are ignored.

For instance, setting the unqualified-search-registries in /etc/containers/registries.conf.d/myregistries.conf will overwrite previous settings in /etc/containers/registries.conf. The [[registry]] tables merged by overwriting existing items if the prefixes are identical while new ones are added.

All drop-in configuration files must be specified in the version 2 of the containers-registries.conf(5) format.

## SEE ALSO
containers-registries.conf(5)

## HISTORY
Mar 2020, Originally compiled by Valentin Rothberg ⟨rothberg@redhat.com⟩


containers-registries.d

title: containers-registries.d(5)

text:
# containers-registries.d(5)

## NAME
containers-registries.d - Directory for various registries configurations

## DESCRIPTION
The registries configuration directory contains configuration for various registries (servers storing remote container images), and for content stored in them, so that the configuration does not have to be provided in command-line options over and over for every command, and so that it can be shared by all users of containers/image.

By default, the registries configuration directory is $HOME/.config/containers/registries.d if it exists, otherwise /etc/containers/registries.d (unless overridden at compile-time); applications may allow using a different directory instead.

## Directory Structure
The directory may contain any number of files with the extension .yaml, each using the YAML format. Other than the mandatory extension, names of the files don’t matter.

The contents of these files are merged together; to have a well-defined and easy to understand behavior, there can be only one configuration section describing a single namespace within a registry (in particular there can be at most one one default-docker section across all files, and there can be at most one instance of any key under the docker section; these sections are documented later).

Thus, it is forbidden to have two conflicting configurations for a single registry or scope, and it is also forbidden to split a configuration for a single registry or scope across more than one file (even if they are not semantically in conflict).

## Registries, Scopes and Search Order
Each YAML file must contain a “YAML mapping” (key-value pairs). Two top-level keys are defined:

•

default-docker is the configuration section (as documented below) for registries implementing "Docker Registry HTTP API V2".

This key is optional.

•

docker is a mapping, using individual registries implementing "Docker Registry HTTP API V2", or namespaces and individual images within these registries, as keys; the value assigned to any such key is a configuration section.

This key is optional.

Scopes matching individual images are named Docker references in the fully expanded form, either

using a tag or digest. For example, docker.io/library/busybox:latest (not busybox:latest).

More general scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest),

a repository namespace, or a registry host (and a port if it differs from the default).

Note that if a registry is accessed using a hostname+port configuration, the port-less hostname

is not used as parent scope.

When searching for a configuration to apply for an individual container image, only the configuration for the most-precisely matching scope is used; configuration using more general scopes is ignored. For example, if any configuration exists for docker.io/library/busybox, the configuration for docker.io is ignored (even if some element of the configuration is defined for docker.io and not for docker.io/library/busybox).

### Built-in Defaults
If no docker section can be found for the container image, and no default-docker section is configured:

- The default directory, /var/lib/containers/sigstore for root and $HOME/.local/share/containers/sigstore for unprivileged user, will be used for reading and writing signatures.

- Sigstore attachments will not be read/written.

## Individual Configuration Sections
A single configuration section is selected for a container image using the process described above. The configuration section is a YAML mapping, with the following keys: <!-- `sigstore` and `sigstore-staging` are deprecated and intentionally not documented here. -->

•

lookaside-staging defines an URL of of the signature storage, used for editing it (adding or deleting signatures).

This key is optional; if it is missing, lookaside below is used.

•

lookaside defines an URL of the signature storage. This URL is used for reading existing signatures, and if lookaside-staging does not exist, also for adding or removing them.

This key is optional; if it is missing, no signature storage is defined (no signatures

are download along with images, adding new signatures is possible only if lookaside-staging is defined).

•

use-sigstore-attachments specifies whether sigstore image attachments (signatures, attestations and the like) are going to be read/written along with the image. If disabled, the images are treated as if no attachments exist; attempts to write attachments fail.

## Examples

### Using Containers from Various Origins
The following demonstrates how to to consume and run images from various registries and namespaces:

```
docker:

    registry.database-supplier.com:

        lookaside: https://lookaside.database-supplier.com

    distribution.great-middleware.org:

        lookaside: https://security-team.great-middleware.org/lookaside

    docker.io/web-framework:

        lookaside: https://lookaside.web-framework.io:8080
```

### Developing and Signing Containers, Staging Signatures
For developers in example.com:

- Consume most container images using the public servers also used by clients.

- Use a separate signature storage for an container images in a namespace corresponding to the developers' department, with a staging storage used before publishing signatures.

- Craft an individual exception for a single branch a specific developer is working on locally.

```
docker:

    registry.example.com:

        lookaside: https://registry-lookaside.example.com

    registry.example.com/mydepartment:

        lookaside: https://lookaside.mydepartment.example.com

        lookaside-staging: file:///mnt/mydepartment/lookaside-staging

    registry.example.com/mydepartment/myproject:mybranch:

        lookaside: http://localhost:4242/lookaside

        lookaside-staging: file:///home/useraccount/webroot/lookaside
```

### A Global Default
If a company publishes its products using a different domain, and different registry hostname for each of them, it is still possible to use a single signature storage server without listing each domain individually. This is expected to rarely happen, usually only for staging new signatures.

```
default-docker:

    lookaside-staging: file:///mnt/company/common-lookaside-staging
```

## AUTHORS
Miloslav Trmač ⟨mitr@redhat.com⟩