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