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