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

By default, the configuration file is located at `/etc/containers/registries.conf`.

# FORMATS

## VERSION 2
VERSION 2 is the latest format of the `registries.conf` and is currently in
beta. This means in general VERSION 1 should be used in production environments
for now.

Every registry can have its own mirrors configured.  The mirrors will be tested
in order for the availability of the remote manifest.  This happens currently
only during an image pull.  If the manifest is not reachable due to connectivity
issues or the unavailability of the remote manifest, then the next mirror will
be tested instead.  If no mirror is configured or contains the manifest to be
pulled, then the initially provided reference will be used as fallback.  It is
possible to set the `insecure` option per mirror, too.

Furthermore it is possible to specify a `prefix` for a registry.  The `prefix`
is used to find the relevant target registry from where the image has to be
pulled.  During the test for the availability of the image, the prefixed
location will be rewritten to the correct remote location.  This applies to
mirrors as well as the fallback `location`.  If no prefix is specified, it
defaults to the specified `location`.  For example, if
`prefix = "example.com/foo"`, `location = "example.com"` and the image will be
pulled from `example.com/foo/image`, then the resulting pull will be effectively
point to `example.com/image`.

By default container runtimes use TLS when retrieving images from a registry.
If the registry is not setup with TLS, then the container runtime will fail to
pull images from the registry. If you set `insecure = true` for a registry or a
mirror you overwrite the `insecure` flag for that specific entry.  This means
that the container runtime will attempt use unencrypted HTTP to pull the image.
It also allows you to pull from a registry with self-signed certificates.

If you set the `unqualified-search = true` for the registry, then it is possible
to omit the registry hostname when pulling images.  This feature does not work
together with a specified `prefix`.

If `blocked = true` then it is not allowed to pull images from that registry.

### EXAMPLE

```
[[registry]]
location = "example.com"
insecure = false
prefix = "example.com/foo"
unqualified-search = false
blocked = false
mirror = [
    { location = "example-mirror-0.local", insecure = false },
    { location = "example-mirror-1.local", insecure = true }
]
```

## VERSION 1
VERSION 1 can be used as alternative to the VERSION 2, but it is not capable in
using registry mirrors or a prefix.

The TOML_format is used to build a simple list for 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 insecure registries can be used for any registry, not just the registries listed
under search.

The fields `registries.insecure` and `registries.block` work as like as the
`insecure` and `blocked` from VERSION 2.

### 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']
```

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