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