Provided by: golang-github-containers-image_5.16.0-3_all bug


       containers-registries.conf - Syntax of System Registry Configuration File


       The  CONTAINERS-REGISTRIES  configuration  file  is  a  system-wide configuration file for
       container image registries. The file format is TOML.

       Container engines will use  the  $HOME/.config/containers/registries.conf  if  it  exists,
       otherwise they will use /etc/containers/registries.conf

              An  array  of  host[:port]  registries to try when pulling an unqualified image, in

              An array of default credential helpers used as external  credential  stores.   Note
              that  "containers-auth.json"  is a reserved value to use auth files as specified in
              containers-auth.json(5).      The     credential     helpers     are     set     to
              ["containers-auth.json"] if none are specified.

       The  bulk of the configuration is represented as an array of [[registry]] TOML tables; the
       settings may therefore differ among  different  registries  as  well  as  among  different
       namespaces/repositories within a registry.

   Choosing a [[registry]] TOML table
       Given an image name, a single [[registry]] TOML table is chosen based on its prefix field.

       prefix:  A  prefix  of  the  user-specified  image  name,  i.e. using one of the following
         - host[:port]
         - host[:port]/namespace[/_namespace_…]
         - host[:port]/namespace[/_namespace_…]/repo
         - host[:port]/namespace[/_namespace_…]/repo(:_tag|@digest)
         - [*.]host

       The user-specified image name must start with the specified prefix (and continue with  the
       appropriate  separator)  for a particular [[registry]] TOML table to be considered; (only)
       the TOML table with the longest match is used. It can also include  wildcarded  subdomains
       in  the  format  *   The  wildcard should only be present at the beginning as
       shown in the formats above. Other cases will not work. For example, * is valid
       but example.*.com, * and * are not.

       As a special case, the prefix field can be missing; if so, it defaults to the value of the
       location field (described below).

   Per-namespace settings
              true or false.  By default, container runtimes require TLS when  retrieving  images
              from  a  registry.   If  insecure  is  set to true, unencrypted HTTP as well as TLS
              connections with untrusted certificates are allowed.

              true or false.  If true, pulling images with matching names is forbidden.

   Remapping and mirroring registries
       The user-specified image reference is, primarily, a "logical" image name, always used  for
       naming  the  image.   By default, the image reference also directly specifies the registry
       and repository to use, but the following options can be used to  redirect  the  underlying
       accesses  to  different registry servers or locations (e.g. to support configurations with
       no access to the internet without having to change Dockerfiles, or to add redundancy).

              Accepts the same format as the prefix field, and specifies the physical location of
              the prefix-rooted namespace.

       By default, this equal to prefix (in which case prefix can be omitted and the [[registry]]
       TOML table can only specify location).

       Example: Given

              prefix = ""
              location = ""

       requests  for  the  image  will  actually  work  with  the image.

       With a prefix containing a wildcard in the format: "*" for subdomain matching,
       the location can be empty. In such a case, prefix matching will occur,  but  no  reference
       rewrite  will  occur.  The  original  requested image string will be used as-is. But other
       settings like insecure / blocked / mirrors will be applied to matching images.

       Example: Given

              prefix = "*"

       requests for the image will be used as-is.  But  other
       settings like insecure/blocked/mirrors will be applied to matching images

       mirror An array of TOML tables specifying (possibly-partial) mirrors for the prefix-rooted

       The mirrors are attempted in the specified order; the first one that can be contacted  and
       contains  the  image  will  be  used  (and  if none of the mirrors contains the image, the
       primary location specified  by  the  registry.location  field,  or  using  the  unmodified
       user-specified reference, is tried last).

       Each  TOML  table  in  the  mirror  array  can contain the following fields, with the same
       semantics as if specified in the [[registry]] TOML table directly: - location - insecure

              true or false.  If true, mirrors will only be used  during  pulling  if  the  image
              reference  includes a digest.  Referencing an image by digest ensures that the same
              is always used  (whereas  referencing  an  image  by  a  tag  may  cause  different
              registries to return different images if the tag mapping is out of sync).

       Note  that if this is true, images referenced by a tag will only use the primary registry,
       failing if that registry is not accessible.

       Note: Redirection and mirrors are currently processed only when reading images,  not  when
       pushing to a registry; that may change in the future.

   Short-Name Aliasing
       The  use of unqualified-search registries entails an ambiguity as it is unclear from which
       registry a given image, referenced by a short name, may be pulled from.

       As mentioned in the note at the end of this man page, using short names is subject to  the
       risk  of  hitting  squatted registry namespaces.  If the unqualified-search registries are
       set to ["", ""]  an  attacker  may  take  over  a  namespace  of  such that an image may be pulled from instead of the intended

       While it is highly recommended to always use fully-qualified  image  references,  existing
       deployments using short names may not be easily changed.  To circumvent the aforementioned
       ambiguity, so called short-name aliases can be configured that point to a  fully-qualified
       image reference.

       Short-name  aliases can be configured in the [aliases] table in the form of "name"="value"
       with the left-hand name being the short name (e.g.,  "image")  and  the  right-hand  value
       being  the  fully-qualified  image reference (e.g., "").  Note
       that neither "name" nor "value" can include a tag or digest.  Moreover, "name" must  be  a
       short name and hence cannot include a registry domain or refer to localhost.

       When  pulling  a  short  name, the configured aliases table will be used for resolving the
       short name.  If a matching alias is found, it will be used without further consulting  the
       unqualified-search  registries  list.   If no matching alias is found, the behavior can be
       controlled via the short-name-mode option as described below.

       Note that tags and digests  are  stripped  off  a  user-specified  short  name  for  alias
       resolution.   Hence, "image", "image:tag" and "image@digest" all resolve to the same alias
       (i.e., "image").  Stripped off tags and digests are later appended to the resolved alias.

       Further note that drop-in configuration files  (see  containers-registries.conf.d(5))  can
       override  aliases  in the specific loading order of the files.  If the "value" of an alias
       is empty (i.e., ""), the alias will be erased.   However,  a  given  "name"  may  only  be
       specified once in a single config file.

   Short-Name Aliasing: Modes
       The  short-name-mode  option  supports  three modes to control the behaviour of short-name

              • enforcing: If only one unqualified-search registry is set, use it as there is  no
                ambiguity.  If there is more than one registry and the user program is running in
                a terminal (i.e., stdout  stdin are a TTY), prompt the user to select one of  the
                specified  search  registries.   If the program is not running in a terminal, the
                ambiguity cannot be resolved which will lead to an error.

              • permissive: Behaves as enforcing but does not lead to an error if the program  is
                not  running  in  a  terminal.  Instead, fallback to using all unqualified-search

              • disabled: Use all unqualified-search registries without prompting.

       If short-name-mode is not specified at all or left empty, default to the permissive  mode.
       If  the  user-specified  short  name was not aliased already, the enforcing and permissive
       mode if prompted, will record a new alias after a successful pull.  Note that the recorded
       alias  will be written to /var/cache/containers/short-name-aliases.conf for root to have a
       clear  separation  between   possibly   human-edited   registries.conf   files   and   the
       machine-generated  short-name-aliases-conf.   Note  that $HOME/.cache is used for rootless
       users.  If an alias is specified in a registries.conf file and also the  machine-generated
       short-name-aliases.conf, the short-name-aliases.conf file has precedence.

   Normalization of references
       The  Docker  Hub is handled in a special way: every push and pull operation gets
       internally normalized with /library if no other specific namespace is defined (for example

       (Note that the above-described normalization happens to match the behavior of Docker.)

       This   means   that   a   pull  of  will  be  internally  translated  to A pull of will not  be  rewritten  because
       this is already the correct remote path.

       Therefore, to remap or mirror the images in the (implied) /library namespace (or
       that whole namespace), the prefix and location fields  in  this  configuration  file  must
       explicitly     include     that    /library    namespace.    For    example    prefix    =
       "" and not prefix = "". The latter would match the* repositories but not the[library/]alpine image).

              unqualified-search-registries = [""]

              prefix = ""
              insecure = false
              blocked = false
              location = ""

              location = "example-mirror-0.local/mirror-for-foo"

              location = "example-mirror-1.local/mirrors/foo"
              insecure = true

       Given the above, a pull of will try:
           1. example-mirror-0.local/mirror-for-foo/image:latest
           2. example-mirror-1.local/mirrors/foo/image:latest

       in order, and use the first one that exists.


       VERSION  1  format  is  still  supported  but  it does not support using registry mirrors,
       longest-prefix matches, or location rewriting.

       The TOML format is used to build a simple  list  of  registries  under  three  categories:,  registries.insecure,  and  registries.block.   You  can  list multiple
       registries using a comma separated list.

       Search registries are used when the caller of a container runtime does not  fully  specify
       the  container  image  that they want to execute.  These registries are prepended onto the
       front of the specified container image until the named image is found at a registry.

       Note that insecure registries can be used for any registry, not just the registries listed
       under search.

       The  registries.insecure  and registries.block lists have the same meaning as the insecure
       and blocked fields in the current version.

       The following example  configuration  defines  two  searchable  registries,  one  insecure
       registry, and two blocked registries.

              registries = ['', '']

              registries = ['']

              registries = ['', '']


       We  recommend always using fully qualified image names including the registry server (full
       dns name), namespace, image name, and tag (e.g., When
       using  short  names, there is always an inherent risk that the image being pulled could be
       spoofed. For example, a user wants to pull an image  named  foobar  from  a  registry  and
       expects it to come from If is not first in the search list,
       an attacker could place a different foobar image at a registry earlier in the search list.
       The  user  would  accidentally  pull and run the attacker's image and code rather than the
       intended content. We recommend only adding registries which are completely  trusted,  i.e.
       registries  which don't allow unknown or anonymous users to create accounts with arbitrary
       names. This will prevent an image from being spoofed, squatted or otherwise made insecure.
       If  it  is  necessary to use one of these registries, it should be added at the end of the

       It is recommended to use fully-qualified images for pulling as the destination registry is
       unambiguous.  Pulling  by digest (i.e., further eliminates
       the ambiguity of tags.


       containers-auth.json(5) containers-certs.d(5)


       Dec 2019, Warning added for unqualified image names  by  Tom  Sweeney⟩

       Mar  2019,  Added  additional  configuration  format  by  Sascha Grunert⟩

       Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg⟩

       Jun 2018, Updated by Tom Sweeney⟩

       Aug 2017, Originally compiled by Brent Baude