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
6a0200
By default, the configuration file is located at `/etc/containers/registries.conf`.
6a0200
6a0200
# FORMATS
6a0200
6a0200
## VERSION 2
6a0200
VERSION 2 is the latest format of the `registries.conf` and is currently in
6a0200
beta. This means in general VERSION 1 should be used in production environments
6a0200
for now.
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
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`
6a0200
    3. `internal-registry-for-example.net/bar/myimage:latest`
6a0200
6a0200
in order, and use the first one that exists.
6a0200
6a0200
## VERSION 1
6a0200
VERSION 1 can be used as alternative to the VERSION 2, 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
6a0200
`insecure` and `blocked` fields in VERSION 2.
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
6a0200
# HISTORY
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>