containers-registries.d(5)

✨ containers-registries.d(5) ✨

okay bestie, so this is a man page for the containers-registries.d man page — literally the directory where all your registries config lives, no cap 💅. Written by Miloslav Trmač back in August 2016 (an icon, honestly 👑).

---

🌸 NAME 🌸

containers-registries.d — the directory for all your various registries configurations 🎀

---

✨ DESCRIPTION ✨

So the registries configuration directory is where you keep config for various registries (like, servers that store remote container images, iykyk) and for the content stored in them. Why? So you're not out here typing the same command-line options over and over for every single command 😭 — that's giving main character energy of the worst kind — and so that all users of containers/image can share it 🫶.

By default, the registries.d config can come from a vendor in /usr/share/containers/registries.d/, get overridden by an administrator in /etc/containers/registries.d/, and then get overridden per-user in $XDG_CONFIG_HOME/containers/registries.d/ (or in $HOME/.config/containers/registries.d/ if $XDG_CONFIG_HOME isn't set). Layered, iconic, slay 🌈.

Rootless/rootful specific drop-in directories are also consulted where applicable:

• /usr/share/containers/registries.rootful.d/ (UID == 0)
• /usr/share/containers/registries.rootless.d/ (UID > 0)
• /usr/share/containers/registries.rootless.d/<UID>/ (UID > 0)
• /etc/containers/registries.rootful.d/ (UID == 0)
• /etc/containers/registries.rootless.d/ (UID > 0)
• /etc/containers/registries.rootless.d/<UID>/ (UID > 0)

Only files with the .yaml extension are read, fr fr. Applications may allow using a different directory instead (like, via an explicit override) — so it's not always the same vibe check 💜.

---

🦋 Directory Structure 🦋

The directory can contain any number of files with the extension .yaml, each one using the YAML format. Other than the mandatory extension, the names of the files don't matter — name them whatever, bestie, we don't gatekeep 🎀.

The contents of these files are merged together. But 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 default-docker section across all files
• there can be at most one instance of any key under the docker section

(these sections are documented later, don't worry 💖)

So yeah: it is forbidden to have two conflicting configurations for a single registry or scope, and it's 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. Like, no splitting, periodt 💀.

---

🌺 Registries, Scopes and Search Order 🌺

Each YAML file must contain a "YAML mapping" (that's key-value pairs, bestie). 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 — the way that shortcut is right there but nope, we expand 💅).

More general scopes are prefixes of individual-image scopes, and they 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).

Heads up bestie: if a registry is accessed using a hostname+port configuration, the port-less hostname is not used as parent scope. Important detail, don't sleep on it 😭.

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). Most specific wins, no mixing, that's the whole vibe ⭐.

🧚 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. That 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's 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's missing, no signature storage is defined. That means no signatures are download along with images, and adding new signatures is possible only if lookaside-staging is defined. So keep that in mind, bestie 🫶.

• 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. Lowkey a flex, honestly 🔥

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

---

🦋 AUTHORS 🦋

Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩ — the legend himself 💜

---

and that's the whole page, bestie! 🎀 this was the Man source, version Registries.d, dated August 2016 — genuinely iconic, go forth and configure your registries 💅✨