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