NAME

       containers-registries.d - Directory for various registries configurations

DESCRIPTION

       The  registries  configuration  directory  contains configuration for various registries (servers storing
       remote container images), and for content stored in them, so that the configuration does not have  to  be
       provided  in  command-line  options  over and over for every command, and so that it can be shared by all
       users of containers/image.

       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); applications may allow  using
       a different directory instead.

Directory Structure

       The  directory  may  contain  any  number  of files with the extension .yaml, each using the YAML format.
       Other than the mandatory extension, names of the files don’t matter.

       The contents of these files are merged together; to have a well-defined and easy to understand  behavior,
       there  can  be  only  one  configuration  section  describing  a  single  namespace within a registry (in
       particular there can be at most one one default-docker section across all files, and there can be at most
       one instance of any key under the docker section; these sections are documented later).

       Thus, it is forbidden to have two conflicting configurations for a single registry or scope,  and  it  is
       also forbidden to split a configuration for a single registry or scope across more than one file (even if
       they are not semantically in conflict).

Registries, Scopes and Search Order

       Each YAML file must contain a “YAML mapping” (key-value pairs).  Two top-level keys are defined:

              • default-docker  is  the  configuration section (as documented below) for registries implementing
                "Docker Registry HTTP API V2".

       This key is optional.

              • docker is a mapping, using individual registries implementing "Docker Registry HTTP API V2",  or
                namespaces  and  individual  images  within these registries, as keys; the value assigned to any
                such key is a configuration section.

       This key is optional.

       Scopes matching individual images are named Docker references in the fully expanded form, either
          using a tag or digest. For example, docker.io/library/busybox:latest (not busybox:latest).

       More general scopes are prefixes of individual-image scopes, and specify a repository  (by  omitting  the
       tag or digest),
          a repository namespace, or a registry host (and a port if it differs from the default).

       Note that if a registry is accessed using a hostname+port configuration, the port-less hostname
          is not used as parent scope.

       When searching for a configuration to apply for an individual container image, only the configuration for
       the  most-precisely  matching  scope  is  used;  configuration using more general scopes is ignored.  For
       example, if any configuration exists for docker.io/library/busybox, the configuration  for  docker.io  is
       ignored   (even   if   some   element  of  the  configuration  is  defined  for  docker.io  and  not  for
       docker.io/library/busybox).

   Built-in Defaults
       If no docker section can be found for the container image, and no default-docker section is configured:

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

              • Sigstore attachments will not be read/written.

Individual Configuration Sections

       A single configuration section is selected for a container image using the process described above.   The
       configuration section is a YAML mapping, with the following keys:

              • lookaside-staging  defines  an  URL  of of the signature storage, used for editing it (adding or
                deleting signatures).

       This key is optional; if it is missing, lookaside below is used.

              • lookaside defines an URL of the signature storage.   This  URL  is  used  for  reading  existing
                signatures, and if lookaside-staging does not exist, also for adding or removing them.

       This key is optional; if it is missing, no signature storage is defined (no signatures
          are  download  along  with  images,  adding  new  signatures  is possible only if lookaside-staging is
       defined).

              • use-sigstore-attachments specifies whether sigstore image attachments (signatures,  attestations
                and  the  like)  are going to be read/written along with the image.  If disabled, the images are
                treated as if no attachments exist; attempts to write attachments fail.

Examples

   Using Containers from Various Origins
       The following demonstrates how to to consume and run images from various registries and namespaces:

       docker:
           registry.database-supplier.com:
               lookaside: https://lookaside.database-supplier.com
           distribution.great-middleware.org:
               lookaside: https://security-team.great-middleware.org/lookaside
           docker.io/web-framework:
               lookaside: https://lookaside.web-framework.io:8080

   Developing and Signing Containers, Staging Signatures
       For developers in example.com:

              • Consume most container images using the public servers also used by clients.

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

              • Craft an individual exception for a single branch a specific developer is working on locally.

       docker:
           registry.example.com:
               lookaside: https://registry-lookaside.example.com
           registry.example.com/mydepartment:
               lookaside: https://lookaside.mydepartment.example.com
               lookaside-staging: file:///mnt/mydepartment/lookaside-staging
           registry.example.com/mydepartment/myproject:mybranch:
               lookaside: http://localhost:4242/lookaside
               lookaside-staging: file:///home/useraccount/webroot/lookaside

   A Global Default
       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 without listing each domain
       individually. This is expected to rarely happen, usually only for staging new signatures.

       default-docker:
           lookaside-staging: file:///mnt/company/common-lookaside-staging

AUTHORS

       Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩

Man                                               Registries.d                        containers-registries.d(5)