e2e81a
% CONTAINERS-REGISTRIES.CONF 5 System-wide registry configuration file
5dd126
% Brent Baude
5dd126
% Aug 2017
5dd126
5dd126
# NAME
5dd126
containers-registries.conf - Syntax of System Registry Configuration File
5dd126
5dd126
# DESCRIPTION
5dd126
The CONTAINERS-REGISTRIES configuration file is a system-wide configuration
5dd126
file for container image registries. The file format is TOML.
5dd126
5dd126
Container engines will use the `$HOME/.config/containers/registries.conf` if it exists, otherwise they will use `/etc/containers/registries.conf`
5dd126
5dd126
### GLOBAL SETTINGS
5dd126
5dd126
`unqualified-search-registries`
5dd126
: An array of _host_[`:`_port_] registries to try when pulling an unqualified image, in order.
5dd126
5dd126
`credential-helpers`
5dd126
: 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.
5dd126
5dd126
### NAMESPACED `[[registry]]` SETTINGS
5dd126
5dd126
The bulk of the configuration is represented as an array of `[[registry]]`
5dd126
TOML tables; the settings may therefore differ among different registries
5dd126
as well as among different namespaces/repositories within a registry.
5dd126
5dd126
#### Choosing a `[[registry]]` TOML table
5dd126
5dd126
Given an image name, a single `[[registry]]` TOML table is chosen based on its `prefix` field.
5dd126
5dd126
`prefix`: A prefix of the user-specified image name, i.e. using one of the following formats:
5dd126
  - _host_[`:`_port_]
5dd126
  - _host_[`:`_port_]`/`_namespace_[`/`_namespace_…]
5dd126
  - _host_[`:`_port_]`/`_namespace_[`/`_namespace_…]`/`_repo_
5dd126
  - _host_[`:`_port_]`/`_namespace_[`/`_namespace_…]`/`_repo_(`:`_tag|`@`_digest_)
5dd126
  - [`*.`]_host_
5dd126
5dd126
The user-specified image name must start with the specified `prefix` (and continue
5dd126
with the appropriate separator) for a particular `[[registry]]` TOML table to be
5dd126
considered; (only) the TOML table with the longest match is used. It can
5dd126
also include wildcarded subdomains in the format `*.example.com`.
5dd126
The wildcard should only be present at the beginning as shown in the formats
5dd126
above. Other cases will not work. For example, `*.example.com` is valid but
5dd126
`example.*.com`, `*.example.com/foo` and `*.example.com:5000/foo/bar:baz` are not.
169ddb
Note that `*` matches an arbitrary number of subdomains. `*.example.com` will hence
2b1b9b
match `bar.example.com`, `foo.bar.example.com` and so on.
5dd126
5dd126
As a special case, the `prefix` field can be missing; if so, it defaults to the value
5dd126
of the `location` field (described below).
5dd126
5dd126
#### Per-namespace settings
5dd126
5dd126
`insecure`
5dd126
: `true` or `false`.
5dd126
By default, container runtimes require TLS when retrieving images from a registry.
5dd126
If `insecure` is set to `true`, unencrypted HTTP as well as TLS connections with untrusted
5dd126
certificates are allowed.
5dd126
5dd126
`blocked`
5dd126
: `true` or `false`.
5dd126
If `true`, pulling images with matching names is forbidden.
5dd126
5dd126
#### Remapping and mirroring registries
5dd126
5dd126
The user-specified image reference is, primarily, a "logical" image name, always used for naming
5dd126
the image.  By default, the image reference also directly specifies the registry and repository
5dd126
to use, but the following options can be used to redirect the underlying accesses
5dd126
to different registry servers or locations (e.g. to support configurations with no access to the
5dd126
internet without having to change `Dockerfile`s, or to add redundancy).
5dd126
5dd126
`location`
5dd126
: Accepts the same format as the `prefix` field, and specifies the physical location
5dd126
of the `prefix`-rooted namespace.
5dd126
5dd126
By default, this equal to `prefix` (in which case `prefix` can be omitted and the
5dd126
`[[registry]]` TOML table can only specify `location`).
5dd126
5dd126
Example: Given
5dd126
```
5dd126
prefix = "example.com/foo"
5dd126
location = "internal-registry-for-example.net/bar"
5dd126
```
5dd126
requests for the image `example.com/foo/myimage:latest` will actually work with the
5dd126
`internal-registry-for-example.net/bar/myimage:latest` image.
5dd126
5dd126
With a `prefix` containing a wildcard in the format: "*.example.com" for subdomain matching,
5dd126
the location can be empty. In such a case,
5dd126
prefix matching will occur, but no reference rewrite will occur. The
5dd126
original requested image string will be used as-is. But other settings like
5dd126
`insecure` / `blocked` / `mirrors` will be applied to matching images.
5dd126
5dd126
Example: Given
5dd126
```
5dd126
prefix = "*.example.com"
5dd126
```
5dd126
requests for the image `blah.example.com/foo/myimage:latest` will be used
5dd126
as-is. But other settings like insecure/blocked/mirrors will be applied to matching images
5dd126
5dd126
`mirror`
5dd126
: An array of TOML tables specifying (possibly-partial) mirrors for the
2b1b9b
`prefix`-rooted namespace (i.e., the current `[[registry]]` TOML table).
5dd126
5dd126
The mirrors are attempted in the specified order; the first one that can be
5dd126
contacted and contains the image will be used (and if none of the mirrors contains the image,
5dd126
the primary location specified by the `registry.location` field, or using the unmodified
5dd126
user-specified reference, is tried last).
5dd126
2b1b9b
Each TOML table in the `mirror` array can contain the following fields:
2b1b9b
- `location`: same semantics
2b1b9b
as specified in the `[[registry]]` TOML table
2b1b9b
- `insecure`: same semantics
2b1b9b
as specified in the `[[registry]]` TOML table
2b1b9b
- `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.
2b1b9b
Note that this per-mirror setting is allowed only when `mirror-by-digest-only` is not configured for the primary registry.
5dd126
5dd126
`mirror-by-digest-only`
5dd126
: `true` or `false`.
5dd126
If `true`, mirrors will only be used during pulling if the image reference includes a digest.
2b1b9b
Note that if all mirrors are configured to be digest-only, images referenced by a tag will only use the primary
2b1b9b
registry.
2b1b9b
If all mirrors are configured to be tag-only, images referenced by a digest will only use the primary
2b1b9b
registry.
2b1b9b
5dd126
Referencing an image by digest ensures that the same is always used
5dd126
(whereas referencing an image by a tag may cause different registries to return
5dd126
different images if the tag mapping is out of sync).
5dd126
5dd126
5dd126
*Note*: Redirection and mirrors are currently processed only when reading images, not when pushing
5dd126
to a registry; that may change in the future.
5dd126
5dd126
#### Short-Name Aliasing
5dd126
The use of unqualified-search registries entails an ambiguity as it is
5dd126
unclear from which registry a given image, referenced by a short name,
5dd126
may be pulled from.
5dd126
5dd126
As mentioned in the note at the end of this man page, using short names is
5dd126
subject to the risk of hitting squatted registry namespaces.  If the
5dd126
unqualified-search registries are set to `["registry1.com", "registry2.com"]`
5dd126
an attacker may take over a namespace of registry1.com such that an image may
5dd126
be pulled from registry1.com instead of the intended source registry2.com.
5dd126
5dd126
While it is highly recommended to always use fully-qualified image references,
5dd126
existing deployments using short names may not be easily changed.  To
5dd126
circumvent the aforementioned ambiguity, so called short-name aliases can be
5dd126
configured that point to a fully-qualified image
5dd126
reference.
5dd126
5dd126
Short-name aliases can be configured in the `[aliases]` table in the form of
5dd126
`"name"="value"` with the left-hand `name` being the short name (e.g., "image")
5dd126
and the right-hand `value` being the fully-qualified image reference (e.g.,
5dd126
"registry.com/namespace/image").  Note that neither "name" nor "value" can
5dd126
include a tag or digest.  Moreover, "name" must be a short name and hence
5dd126
cannot include a registry domain or refer to localhost.
5dd126
5dd126
When pulling a short name, the configured aliases table will be used for
5dd126
resolving the short name.  If a matching alias is found, it will be used
5dd126
without further consulting the unqualified-search registries list.  If no
5dd126
matching alias is found, the behavior can be controlled via the
5dd126
`short-name-mode` option as described below.
5dd126
5dd126
Note that tags and digests are stripped off a user-specified short name for
5dd126
alias resolution.  Hence, "image", "image:tag" and "image@digest" all resolve
5dd126
to the same alias (i.e., "image").  Stripped off tags and digests are later
5dd126
appended to the resolved alias.
5dd126
5dd126
Further note that drop-in configuration files (see containers-registries.conf.d(5))
5dd126
can override aliases in the specific loading order of the files.  If the "value" of
5dd126
an alias is empty (i.e., ""), the alias will be erased.  However, a given
5dd126
"name" may only be specified once in a single config file.
5dd126
5dd126
5dd126
#### Short-Name Aliasing: Modes
5dd126
5dd126
The `short-name-mode` option supports three modes to control the behaviour of
5dd126
short-name resolution.
5dd126
5dd126
* `enforcing`: If only one unqualified-search registry is set, use it as there
5dd126
  is no ambiguity.  If there is more than one registry and the user program is
5dd126
  running in a terminal (i.e., stdout & stdin are a TTY), prompt the user to
5dd126
  select one of the specified search registries.  If the program is not running
5dd126
  in a terminal, the ambiguity cannot be resolved which will lead to an error.
5dd126
5dd126
* `permissive`: Behaves as enforcing but does not lead to an error if the
5dd126
  program is not running in a terminal.  Instead, fallback to using all
5dd126
  unqualified-search registries.
5dd126
5dd126
* `disabled`: Use all unqualified-search registries without prompting.
5dd126
5dd126
If `short-name-mode` is not specified at all or left empty, default to the
5dd126
`permissive` mode.  If the user-specified short name was not aliased already,
5dd126
the `enforcing` and `permissive` mode if prompted, will record a new alias
5dd126
after a successful pull.  Note that the recorded alias will be written to
5dd126
`/var/cache/containers/short-name-aliases.conf` for root to have a clear
5dd126
separation between possibly human-edited registries.conf files and the
5dd126
machine-generated `short-name-aliases-conf`.  Note that `$HOME/.cache` is used
5dd126
for rootless users.  If an alias is specified in a
5dd126
`registries.conf` file and also the machine-generated
5dd126
`short-name-aliases.conf`, the `short-name-aliases.conf` file has precedence.
5dd126
5dd126
#### Normalization of docker.io references
5dd126
5dd126
The Docker Hub `docker.io` is handled in a special way: every push and pull
5dd126
operation gets internally normalized with `/library` if no other specific
5dd126
namespace is defined (for example on `docker.io/namespace/image`).
5dd126
5dd126
(Note that the above-described normalization happens to match the behavior of
5dd126
Docker.)
5dd126
5dd126
This means that a pull of `docker.io/alpine` will be internally translated to
5dd126
`docker.io/library/alpine`. A pull of `docker.io/user/alpine` will not be
5dd126
rewritten because this is already the correct remote path.
5dd126
5dd126
Therefore, to remap or mirror the `docker.io` images in the (implied) `/library`
5dd126
namespace (or that whole namespace), the prefix and location fields in this
5dd126
configuration file must explicitly include that `/library` namespace. For
5dd126
example `prefix = "docker.io/library/alpine"` and not `prefix =
5dd126
"docker.io/alpine"`. The latter would match the `docker.io/alpine/*`
5dd126
repositories but not the `docker.io/[library/]alpine` image).
5dd126
5dd126
### EXAMPLE
5dd126
5dd126
```
5dd126
unqualified-search-registries = ["example.com"]
5dd126
5dd126
[[registry]]
5dd126
prefix = "example.com/foo"
5dd126
insecure = false
5dd126
blocked = false
5dd126
location = "internal-registry-for-example.com/bar"
5dd126
5dd126
[[registry.mirror]]
5dd126
location = "example-mirror-0.local/mirror-for-foo"
5dd126
5dd126
[[registry.mirror]]
5dd126
location = "example-mirror-1.local/mirrors/foo"
5dd126
insecure = true
2b1b9b
2b1b9b
[[registry]]
2b1b9b
location = "registry.com"
2b1b9b
2b1b9b
[[registry.mirror]]
2b1b9b
location = "mirror.registry.com"
5dd126
```
5dd126
Given the above, a pull of `example.com/foo/image:latest` will try:
2b1b9b
2b1b9b
1. `example-mirror-0.local/mirror-for-foo/image:latest`
2b1b9b
2. `example-mirror-1.local/mirrors/foo/image:latest`
2b1b9b
3. `internal-registry-for-example.net/bar/image:latest`
5dd126
5dd126
in order, and use the first one that exists.
5dd126
2b1b9b
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.
2b1b9b
5dd126
## VERSION 1 FORMAT - DEPRECATED
5dd126
VERSION 1 format is still supported but it does not support
5dd126
using registry mirrors, longest-prefix matches, or location rewriting.
5dd126
5dd126
The TOML format is used to build a simple list of registries under three
5dd126
categories: `registries.search`, `registries.insecure`, and `registries.block`.
5dd126
You can list multiple registries using a comma separated list.
5dd126
5dd126
Search registries are used when the caller of a container runtime does not fully specify the
5dd126
container image that they want to execute.  These registries are prepended onto the front
5dd126
of the specified container image until the named image is found at a registry.
5dd126
5dd126
Note that insecure registries can be used for any registry, not just the registries listed
5dd126
under search.
5dd126
5dd126
The `registries.insecure` and `registries.block` lists have the same meaning as the
5dd126
`insecure` and `blocked` fields in the current version.
5dd126
5dd126
### EXAMPLE
5dd126
The following example configuration defines two searchable registries, one
5dd126
insecure registry, and two blocked registries.
5dd126
5dd126
```
5dd126
[registries.search]
5dd126
registries = ['registry1.com', 'registry2.com']
5dd126
5dd126
[registries.insecure]
5dd126
registries = ['registry3.com']
5dd126
5dd126
[registries.block]
5dd126
registries = ['registry.untrusted.com', 'registry.unsafe.com']
5dd126
```
5dd126
5dd126
# NOTE: RISK OF USING UNQUALIFIED IMAGE NAMES
5dd126
We recommend always using fully qualified image names including the registry
5dd126
server (full dns name), namespace, image name, and tag
5dd126
(e.g., registry.redhat.io/ubi8/ubi:latest). When using short names, there is
5dd126
always an inherent risk that the image being pulled could be spoofed. For
5dd126
example, a user wants to pull an image named `foobar` from a registry and
5dd126
expects it to come from myregistry.com. If myregistry.com is not first in the
5dd126
search list, an attacker could place a different `foobar` image at a registry
5dd126
earlier in the search list. The user would accidentally pull and run the
5dd126
attacker's image and code rather than the intended content. We recommend only
5dd126
adding registries which are completely trusted, i.e. registries which don't
5dd126
allow unknown or anonymous users to create accounts with arbitrary names. This
5dd126
will prevent an image from being spoofed, squatted or otherwise made insecure.
5dd126
If it is necessary to use one of these registries, it should be added at the
5dd126
end of the list.
5dd126
5dd126
It is recommended to use fully-qualified images for pulling as
5dd126
the destination registry is unambiguous. Pulling by digest
5dd126
(i.e., quay.io/repository/name@digest) further eliminates the ambiguity of
5dd126
tags.
5dd126
5dd126
# SEE ALSO
5dd126
 containers-auth.json(5) containers-certs.d(5)
5dd126
5dd126
# HISTORY
5dd126
Dec 2019, Warning added for unqualified image names by Tom Sweeney <tsweeney@redhat.com>
5dd126
5dd126
Mar 2019, Added additional configuration format by Sascha Grunert <sgrunert@suse.com>
5dd126
5dd126
Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg <vrothberg@suse.com>
5dd126
5dd126
Jun 2018, Updated by Tom Sweeney <tsweeney@redhat.com>
5dd126
5dd126
Aug 2017, Originally compiled by Brent Baude <bbaude@redhat.com>