6f9067
% CONTAINERS-REGISTRIES.CONF(5) System-wide registry configuration file
6f9067
% Brent Baude
6f9067
% Aug 2017
6f9067
6f9067
# NAME
6f9067
containers-registries.conf - Syntax of System Registry Configuration File
6f9067
6f9067
# DESCRIPTION
6f9067
The CONTAINERS-REGISTRIES configuration file is a system-wide configuration
6f9067
file for container image registries. The file format is TOML.
6f9067
6f9067
By default, the configuration file is located at `/etc/containers/registries.conf`.
6f9067
6f9067
# FORMATS
6f9067
6f9067
## VERSION 2
6f9067
VERSION 2 is the latest format of the `registries.conf` and is currently in
6f9067
beta. This means in general VERSION 1 should be used in production environments
6f9067
for now.
6f9067
6f9067
### GLOBAL SETTINGS
6f9067
6f9067
`unqualified-search-registries`
6f9067
: An array of _host_[`:`_port_] registries to try when pulling an unqualified image, in order.
6f9067
6f9067
### NAMESPACED `[[registry]]` SETTINGS
6f9067
6f9067
The bulk of the configuration is represented as an array of `[[registry]]`
6f9067
TOML tables; the settings may therefore differ among different registries
6f9067
as well as among different namespaces/repositories within a registry.
6f9067
6f9067
#### Choosing a `[[registry]]` TOML table
6f9067
6f9067
Given an image name, a single `[[registry]]` TOML table is chosen based on its `prefix` field.
6f9067
6f9067
`prefix`
6f9067
: A prefix of the user-specified image name, i.e. using one of the following formats:
6f9067
    - _host_[`:`_port_]
6f9067
    - _host_[`:`_port_]`/`_namespace_[`/`_namespace_…]
6f9067
    - _host_[`:`_port_]`/`_namespace_[`/`_namespace_…]`/`_repo_
6f9067
    - _host_[`:`_port_]`/`_namespace_[`/`_namespace_…]`/`_repo_(`:`_tag|`@`_digest_)
6f9067
6f9067
    The user-specified image name must start with the specified `prefix` (and continue
6f9067
    with the appropriate separator) for a particular `[[registry]]` TOML table to be
6f9067
    considered; (only) the TOML table with the longest match is used.
6f9067
6f9067
    As a special case, the `prefix` field can be missing; if so, it defaults to the value
6f9067
    of the `location` field (described below).
6f9067
6f9067
#### Per-namespace settings
6f9067
6f9067
`insecure`
6f9067
: `true` or `false`.
6f9067
    By default, container runtimes require TLS when retrieving images from a registry.
6f9067
    If `insecure` is set to `true`, unencrypted HTTP as well as TLS connections with untrusted
6f9067
    certificates are allowed.
6f9067
6f9067
`blocked`
6f9067
: `true` or `false`.
6f9067
    If `true`, pulling images with matching names is forbidden.
6f9067
6f9067
#### Remapping and mirroring registries
6f9067
6f9067
The user-specified image reference is, primarily, a "logical" image name, always used for naming
6f9067
the image.  By default, the image reference also directly specifies the registry and repository
6f9067
to use, but the following options can be used to redirect the underlying accesses
6f9067
to different registry servers or locations (e.g. to support configurations with no access to the
6f9067
internet without having to change `Dockerfile`s, or to add redundancy).
6f9067
6f9067
`location`
6f9067
: Accepts the same format as the `prefix` field, and specifies the physical location
6f9067
    of the `prefix`-rooted namespace.
6f9067
6f9067
    By default, this equal to `prefix` (in which case `prefix` can be omitted and the
6f9067
    `[[registry]]` TOML table can only specify `location`).
6f9067
6f9067
    Example: Given
6f9067
    ```
6f9067
    prefix = "example.com/foo"
6f9067
    location = "internal-registry-for-example.net/bar"
6f9067
    ```
6f9067
    requests for the image `example.com/foo/myimage:latest` will actually work with the
6f9067
    `internal-registry-for-example.net/bar/myimage:latest` image.
6f9067
6f9067
`mirror`
6f9067
: An array of TOML tables specifying (possibly-partial) mirrors for the
6f9067
    `prefix`-rooted namespace.
6f9067
6f9067
    The mirrors are attempted in the specified order; the first one that can be
6f9067
    contacted and contains the image will be used (and if none of the mirrors contains the image,
6f9067
    the primary location specified by the `registry.location` field, or using the unmodified
6f9067
    user-specified reference, is tried last).
6f9067
6f9067
    Each TOML table in the `mirror` array can contain the following fields, with the same semantics
6f9067
    as if specified in the `[[registry]]` TOML table directly:
6f9067
    - `location`
6f9067
    - `insecure`
6f9067
6f9067
`mirror-by-digest-only`
6f9067
: `true` or `false`.
6f9067
    If `true`, mirrors will only be used during pulling if the image reference includes a digest.
6f9067
    Referencing an image by digest ensures that the same is always used
6f9067
    (whereas referencing an image by a tag may cause different registries to return
6f9067
    different images if the tag mapping is out of sync).
6f9067
6f9067
    Note that if this is `true`, images referenced by a tag will only use the primary
6f9067
    registry, failing if that registry is not accessible.
6f9067
6f9067
*Note*: Redirection and mirrors are currently processed only when reading images, not when pushing
6f9067
to a registry; that may change in the future.
6f9067
6f9067
### EXAMPLE
6f9067
6f9067
```
6f9067
unqualified-search-registries = ["example.com"]
6f9067
6f9067
[[registry]]
6f9067
prefix = "example.com/foo"
6f9067
insecure = false
6f9067
blocked = false
6f9067
location = "internal-registry-for-example.com/bar"
6f9067
6f9067
[[registry.mirror]]
6f9067
location = "example-mirror-0.local/mirror-for-foo"
6f9067
6f9067
[[registry.mirror]]
6f9067
location = "example-mirror-1.local/mirrors/foo"
6f9067
insecure = true
6f9067
```
6f9067
Given the above, a pull of `example.com/foo/image:latest` will try:
6f9067
    1. `example-mirror-0.local/mirror-for-foo/image:latest`
6f9067
    2. `example-mirror-1.local/mirrors/foo/image:latest`
6f9067
    3. `internal-registry-for-example.net/bar/myimage:latest`
6f9067
6f9067
in order, and use the first one that exists.
6f9067
6f9067
## VERSION 1
6f9067
VERSION 1 can be used as alternative to the VERSION 2, but it does not support
6f9067
using registry mirrors, longest-prefix matches, or location rewriting.
6f9067
6f9067
The TOML format is used to build a simple list of registries under three
6f9067
categories: `registries.search`, `registries.insecure`, and `registries.block`.
6f9067
You can list multiple registries using a comma separated list.
6f9067
6f9067
Search registries are used when the caller of a container runtime does not fully specify the
6f9067
container image that they want to execute.  These registries are prepended onto the front
6f9067
of the specified container image until the named image is found at a registry.
6f9067
6f9067
Note that insecure registries can be used for any registry, not just the registries listed
6f9067
under search.
6f9067
6f9067
The `registries.insecure` and `registries.block` lists have the same meaning as the
6f9067
`insecure` and `blocked` fields in VERSION 2.
6f9067
6f9067
### EXAMPLE
6f9067
The following example configuration defines two searchable registries, one
6f9067
insecure registry, and two blocked registries.
6f9067
6f9067
```
6f9067
[registries.search]
6f9067
registries = ['registry1.com', 'registry2.com']
6f9067
6f9067
[registries.insecure]
6f9067
registries = ['registry3.com']
6f9067
6f9067
[registries.block]
6f9067
registries = ['registry.untrusted.com', 'registry.unsafe.com']
6f9067
```
6f9067
6f9067
# HISTORY
6f9067
Mar 2019, Added additional configuration format by Sascha Grunert <sgrunert@suse.com>
6f9067
6f9067
Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg <vrothberg@suse.com>
6f9067
6f9067
Jun 2018, Updated by Tom Sweeney <tsweeney@redhat.com>
6f9067
6f9067
Aug 2017, Originally compiled by Brent Baude <bbaude@redhat.com>