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