0106cf
% containers-registries.d 5 Registries.d Man Page
fa61e0
% Miloslav Trmač
fa61e0
% August 2016
fa61e0
fa61e0
# NAME
fa61e0
containers-registries.d - Directory for various registries configurations
fa61e0
fa61e0
# DESCRIPTION
fa61e0
fa61e0
The registries configuration directory contains configuration for various registries
fa61e0
(servers storing remote container images), and for content stored in them,
fa61e0
so that the configuration does not have to be provided in command-line options over and over for every command,
fa61e0
and so that it can be shared by all users of containers/image.
fa61e0
fa61e0
By default, the registries configuration directory is `$HOME/.config/containers/registries.d` if it exists, otherwise `/etc/containers/registries.d` (unless overridden at compile-time);
fa61e0
applications may allow using a different directory instead.
fa61e0
fa61e0
## Directory Structure
fa61e0
fa61e0
The directory may contain any number of files with the extension `.yaml`,
fa61e0
each using the YAML format.  Other than the mandatory extension, names of the files
fa61e0
don’t matter.
fa61e0
fa61e0
The contents of these files are merged together; to have a well-defined and easy to understand
fa61e0
behavior, there can be only one configuration section describing a single namespace within a registry
fa61e0
(in particular there can be at most one one `default-docker` section across all files,
fa61e0
and there can be at most one instance of any key under the `docker` section;
fa61e0
these sections are documented later).
fa61e0
fa61e0
Thus, it is forbidden to have two conflicting configurations for a single registry or scope,
fa61e0
and it is also forbidden to split a configuration for a single registry or scope across
fa61e0
more than one file (even if they are not semantically in conflict).
fa61e0
fa61e0
## Registries, Scopes and Search Order
fa61e0
fa61e0
Each YAML file must contain a “YAML mapping” (key-value pairs).  Two top-level keys are defined:
fa61e0
fa61e0
- `default-docker` is the _configuration section_ (as documented below)
fa61e0
   for registries implementing "Docker Registry HTTP API V2".
fa61e0
fa61e0
   This key is optional.
fa61e0
fa61e0
- `docker` is a mapping, using individual registries implementing "Docker Registry HTTP API V2",
fa61e0
   or namespaces and individual images within these registries, as keys;
fa61e0
   the value assigned to any such key is a _configuration section_.
fa61e0
fa61e0
   This key is optional.
fa61e0
fa61e0
   Scopes matching individual images are named Docker references *in the fully expanded form*, either
fa61e0
   using a tag or digest. For example, `docker.io/library/busybox:latest` (*not* `busybox:latest`).
fa61e0
fa61e0
   More general scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest),
fa61e0
   a repository namespace, or a registry host (and a port if it differs from the default).
fa61e0
fa61e0
   Note that if a registry is accessed using a hostname+port configuration, the port-less hostname
fa61e0
   is _not_ used as parent scope.
fa61e0
fa61e0
When searching for a configuration to apply for an individual container image, only
fa61e0
the configuration for the most-precisely matching scope is used; configuration using
fa61e0
more general scopes is ignored.  For example, if _any_ configuration exists for
fa61e0
`docker.io/library/busybox`, the configuration for `docker.io` is ignored
fa61e0
(even if some element of the configuration is defined for `docker.io` and not for `docker.io/library/busybox`).
fa61e0
fa61e0
### Built-in Defaults
fa61e0
462880
If no `docker` section can be found for the container image, and no `default-docker` section is configured:
462880
462880
- The default directory, `/var/lib/containers/sigstore` for root and `$HOME/.local/share/containers/sigstore` for unprivileged user,  will be used for reading and writing signatures.
462880
- Sigstore attachments will not be read/written.
fa61e0
fa61e0
## Individual Configuration Sections
fa61e0
fa61e0
A single configuration section is selected for a container image using the process
fa61e0
described above.  The configuration section is a YAML mapping, with the following keys:
fa61e0
462880
462880
462880
- `lookaside-staging` defines an URL of of the signature storage, used for editing it (adding or deleting signatures).
fa61e0
462880
   This key is optional; if it is missing, `lookaside` below is used.
fa61e0
462880
- `lookaside` defines an URL of the signature storage.
fa61e0
   This URL is used for reading existing signatures,
462880
   and if `lookaside-staging` does not exist, also for adding or removing them.
fa61e0
fa61e0
   This key is optional; if it is missing, no signature storage is defined (no signatures
462880
   are download along with images, adding new signatures is possible only if `lookaside-staging` is defined).
fa61e0
462880
- `use-sigstore-attachments` specifies whether sigstore image attachments (signatures, attestations and the like) are going to be read/written along with the image.
462880
   If disabled, the images are treated as if no attachments exist; attempts to write attachments fail.
fa61e0
fa61e0
## Examples
fa61e0
fa61e0
### Using Containers from Various Origins
fa61e0
fa61e0
The following demonstrates how to to consume and run images from various registries and namespaces:
fa61e0
fa61e0
```yaml
fa61e0
docker:
fa61e0
    registry.database-supplier.com:
462880
        lookaside: https://lookaside.database-supplier.com
fa61e0
    distribution.great-middleware.org:
462880
        lookaside: https://security-team.great-middleware.org/lookaside
fa61e0
    docker.io/web-framework:
462880
        lookaside: https://lookaside.web-framework.io:8080
fa61e0
```
fa61e0
fa61e0
### Developing and Signing Containers, Staging Signatures
fa61e0
fa61e0
For developers in `example.com`:
fa61e0
fa61e0
- Consume most container images using the public servers also used by clients.
fa61e0
- Use a separate signature storage for an container images in a namespace corresponding to the developers' department, with a staging storage used before publishing signatures.
fa61e0
- Craft an individual exception for a single branch a specific developer is working on locally.
fa61e0
fa61e0
```yaml
fa61e0
docker:
fa61e0
    registry.example.com:
462880
        lookaside: https://registry-lookaside.example.com
fa61e0
    registry.example.com/mydepartment:
462880
        lookaside: https://lookaside.mydepartment.example.com
462880
        lookaside-staging: file:///mnt/mydepartment/lookaside-staging
fa61e0
    registry.example.com/mydepartment/myproject:mybranch:
462880
        lookaside: http://localhost:4242/lookaside
462880
        lookaside-staging: file:///home/useraccount/webroot/lookaside
fa61e0
```
fa61e0
fa61e0
### A Global Default
fa61e0
fa61e0
If a company publishes its products using a different domain, and different registry hostname for each of them, it is still possible to use a single signature storage server
fa61e0
without listing each domain individually. This is expected to rarely happen, usually only for staging new signatures.
fa61e0
fa61e0
```yaml
fa61e0
default-docker:
462880
    lookaside-staging: file:///mnt/company/common-lookaside-staging
fa61e0
```
fa61e0
fa61e0
# AUTHORS
fa61e0
fa61e0
Miloslav Trmač <mitr@redhat.com>