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
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>