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