1CONTAINERS-REGISTRIES.CONF(5)    configuration   CONTAINERS-REGISTRIES.CONF(5)
2
3
4
5Brent Baude Aug 2017
6
7

NAME

9       containers-registries.conf  -  Syntax  of System Registry Configuration
10       File
11
12
13

DESCRIPTION

15       The CONTAINERS-REGISTRIES configuration file is a system-wide  configu‐
16       ration file for container image registries. The file format is TOML.
17
18
19       Container engines will use the $HOME/.config/containers/registries.conf
20       if it exists, otherwise they will use /etc/containers/registries.conf
21
22
23   GLOBAL SETTINGS
24       unqualified-search-registries
25              An array of host[:port] registries to try when  pulling  an  un‐
26              qualified image, in order.
27
28
29       credential-helpers
30              An  array of default credential helpers used as external creden‐
31              tial stores.  Note that  "containers-auth.json"  is  a  reserved
32              value to use auth files as specified in containers-auth.json(5).
33              The credential helpers are set  to  ["containers-auth.json"]  if
34              none are specified.
35
36
37   NAMESPACED [[registry]] SETTINGS
38       The  bulk  of  the  configuration  is represented as an array of [[reg‐
39       istry]] TOML tables; the settings may therefore differ among  different
40       registries  as well as among different namespaces/repositories within a
41       registry.
42
43
44   Choosing a [[registry]] TOML table
45       Given an image name, a single [[registry]] TOML table is  chosen  based
46       on its prefix field.
47
48
49       prefix:  A  prefix  of the user-specified image name, i.e. using one of
50       the following formats:
51         - host[:port]
52         - host[:port]/namespace[/_namespace_…]
53         - host[:port]/namespace[/_namespace_…]/repo
54         - host[:port]/namespace[/_namespace_…]/repo(:_tag|@digest)
55         - [*.]host
56
57
58       The user-specified image name must start with the specified prefix (and
59       continue  with the appropriate separator) for a particular [[registry]]
60       TOML table to be considered; (only) the TOML  table  with  the  longest
61       match  is used. It can also include wildcarded subdomains in the format
62       *.example.com.  The wildcard should only be present at the beginning as
63       shown  in  the  formats  above. Other cases will not work. For example,
64       *.example.com is valid but example.*.com, *.example.com/foo and *.exam‐
65       ple.com:5000/foo/bar:baz  are  not.   Note  that * matches an arbitrary
66       number of subdomains. *.example.com will hence  match  bar.example.com,
67       foo.bar.example.com and so on.
68
69
70       As  a special case, the prefix field can be missing; if so, it defaults
71       to the value of the location field (described below).
72
73
74   Per-namespace settings
75       insecure
76              true or false.  By default, container runtimes require TLS  when
77              retrieving  images from a registry.  If insecure is set to true,
78              unencrypted HTTP as well as TLS connections with untrusted  cer‐
79              tificates are allowed.
80
81
82       blocked
83              true  or  false.  If true, pulling images with matching names is
84              forbidden.
85
86
87   Remapping and mirroring registries
88       The user-specified image reference is,  primarily,  a  "logical"  image
89       name,  always  used for naming the image.  By default, the image refer‐
90       ence also directly specifies the registry and repository  to  use,  but
91       the  following  options can be used to redirect the underlying accesses
92       to different registry servers or locations (e.g. to support  configura‐
93       tions  with  no access to the internet without having to change Docker‐
94       files, or to add redundancy).
95
96
97       location
98              Accepts the same format as the prefix field, and  specifies  the
99              physical location of the prefix-rooted namespace.
100
101
102       By  default,  this equal to prefix (in which case prefix can be omitted
103       and the [[registry]] TOML table can only specify location).
104
105
106       Example: Given
107
108
109              prefix = "example.com/foo"
110              location = "internal-registry-for-example.net/bar"
111
112
113
114       requests for the  image  example.com/foo/myimage:latest  will  actually
115       work  with the internal-registry-for-example.net/bar/myimage:latest im‐
116       age.
117
118
119       With a prefix containing a wildcard in the format: "*.example.com"  for
120       subdomain  matching,  the location can be empty. In such a case, prefix
121       matching will occur, but no reference rewrite will occur. The  original
122       requested  image string will be used as-is. But other settings like in‐
123       secure / blocked / mirrors will be applied to matching images.
124
125
126       Example: Given
127
128
129              prefix = "*.example.com"
130
131
132
133       requests for the image blah.example.com/foo/myimage:latest will be used
134       as-is. But other settings like insecure/blocked/mirrors will be applied
135       to matching images
136
137
138       mirror An array of TOML tables  specifying  (possibly-partial)  mirrors
139              for  the prefix-rooted namespace (i.e., the current [[registry]]
140              TOML table).
141
142
143       The mirrors are attempted in the specified order; the  first  one  that
144       can  be  contacted  and contains the image will be used (and if none of
145       the mirrors contains the image, the primary location specified  by  the
146       registry.location  field, or using the unmodified user-specified refer‐
147       ence, is tried last).
148
149
150       Each TOML table in the mirror array can contain the following fields: -
151       location: same semantics as specified in the [[registry]] TOML table -
152       insecure: same semantics as specified in the [[registry]] TOML table -
153       pull-from-mirror:  all,  digest-only  or  tag-only.  If "digest-only",
154       mirrors will only be used for digest pulls. Pulling images by  tag  can
155       potentially yield different images, depending on which endpoint we pull
156       from.  Restricting mirrors to pulls by digest avoids  that  issue.   If
157       "tag-only", mirrors will only be used for tag pulls.  For a more up-to-
158       date and expensive mirror that it is less likely to be out of  sync  if
159       tags  move,  it should not be unnecessarily used for digest references.
160       Default is "all" (or left empty), mirrors will be used for both  digest
161       pulls  and  tag  pulls  unless the mirror-by-digest-only is set for the
162       primary registry.  Note that this per-mirror setting  is  allowed  only
163       when mirror-by-digest-only is not configured for the primary registry.
164
165
166       mirror-by-digest-only
167              true  or  false.   If  true,  mirrors  will  only be used during
168              pulling if the image reference includes a digest.  Note that  if
169              all  mirrors are configured to be digest-only, images referenced
170              by a tag will only use the primary registry.  If all mirrors are
171              configured  to  be  tag-only, images referenced by a digest will
172              only use the primary registry.
173
174
175       Referencing an image by digest ensures that the  same  is  always  used
176       (whereas  referencing  an image by a tag may cause different registries
177       to return different images if the tag mapping is out of sync).
178
179
180       Note: Redirection and mirrors are currently processed only when reading
181       images, not when pushing to a registry; that may change in the future.
182
183
184   Short-Name Aliasing
185       The  use of unqualified-search registries entails an ambiguity as it is
186       unclear from which registry a given image, referenced by a short  name,
187       may be pulled from.
188
189
190       As mentioned in the note at the end of this man page, using short names
191       is subject to the risk of hitting squatted registry namespaces.  If the
192       unqualified-search   registries  are  set  to  ["registry1.com",  "reg‐
193       istry2.com"] an attacker may take over  a  namespace  of  registry1.com
194       such  that an image may be pulled from registry1.com instead of the in‐
195       tended source registry2.com.
196
197
198       While it is highly recommended to always use fully-qualified image ref‐
199       erences,  existing  deployments  using  short  names  may not be easily
200       changed.  To circumvent the aforementioned ambiguity, so called  short-
201       name  aliases  can  be configured that point to a fully-qualified image
202       reference.
203
204
205       Short-name aliases can be configured in the [aliases] table in the form
206       of  "name"="value"  with the left-hand name being the short name (e.g.,
207       "image") and the right-hand value being the fully-qualified image  ref‐
208       erence   (e.g.,  "registry.com/namespace/image").   Note  that  neither
209       "name" nor "value" can include a tag or digest.  Moreover, "name"  must
210       be  a short name and hence cannot include a registry domain or refer to
211       localhost.
212
213
214       When pulling a short name, the configured aliases table  will  be  used
215       for resolving the short name.  If a matching alias is found, it will be
216       used without further consulting the unqualified-search registries list.
217       If  no  matching alias is found, the behavior can be controlled via the
218       short-name-mode option as described below.
219
220
221       Note that tags and digests are stripped off a user-specified short name
222       for  alias  resolution.  Hence, "image", "image:tag" and "image@digest"
223       all resolve to the same alias (i.e., "image").  Stripped off  tags  and
224       digests are later appended to the resolved alias.
225
226
227       Further  note  that  drop-in  configuration  files (see containers-reg‐
228       istries.conf.d(5)) can override aliases in the specific  loading  order
229       of  the  files.   If  the  "value" of an alias is empty (i.e., ""), the
230       alias will be erased.  However, a given "name" may  only  be  specified
231       once in a single config file.
232
233
234   Short-Name Aliasing: Modes
235       The  short-name-mode  option supports three modes to control the behav‐
236       iour of short-name resolution.
237
238
239enforcing: If only one unqualified-search registry is set, use
240                it  as  there is no ambiguity.  If there is more than one reg‐
241                istry and the user program is running  in  a  terminal  (i.e.,
242                stdout  &  stdin  are a TTY), prompt the user to select one of
243                the specified search registries.  If the program is  not  run‐
244                ning  in  a  terminal,  the ambiguity cannot be resolved which
245                will lead to an error.
246
247permissive: Behaves as enforcing but does not lead to an error
248                if  the  program is not running in a terminal.  Instead, fall‐
249                back to using all unqualified-search registries.
250
251disabled:  Use  all  unqualified-search   registries   without
252                prompting.
253
254
255
256       If  short-name-mode  is  not specified at all or left empty, default to
257       the permissive mode.  If the user-specified short name was not  aliased
258       already,  the  enforcing and permissive mode if prompted, will record a
259       new alias after a successful pull.  Note that the recorded  alias  will
260       be written to /var/cache/containers/short-name-aliases.conf for root to
261       have a clear separation between possibly  human-edited  registries.conf
262       files  and  the  machine-generated  short-name-aliases-conf.  Note that
263       $HOME/.cache is used for rootless users.  If an alias is specified in a
264       registries.conf   file   and  also  the  machine-generated  short-name-
265       aliases.conf, the short-name-aliases.conf file has precedence.
266
267
268   Normalization of docker.io references
269       The Docker Hub docker.io is handled in a special way:  every  push  and
270       pull  operation  gets  internally  normalized with /library if no other
271       specific namespace is defined (for example  on  docker.io/namespace/im‐
272       age).
273
274
275       (Note  that  the above-described normalization happens to match the be‐
276       havior of Docker.)
277
278
279       This means that a pull of docker.io/alpine will  be  internally  trans‐
280       lated to docker.io/library/alpine. A pull of docker.io/user/alpine will
281       not be rewritten because this is already the correct remote path.
282
283
284       Therefore, to remap or mirror the docker.io  images  in  the  (implied)
285       /library  namespace  (or that whole namespace), the prefix and location
286       fields in this configuration file must explicitly include that /library
287       namespace. For example prefix = "docker.io/library/alpine" and not pre‐
288       fix = "docker.io/alpine". The latter would match the docker.io/alpine/*
289       repositories but not the docker.io/[library/]alpine image).
290
291
292   EXAMPLE
293              unqualified-search-registries = ["example.com"]
294
295              [[registry]]
296              prefix = "example.com/foo"
297              insecure = false
298              blocked = false
299              location = "internal-registry-for-example.com/bar"
300
301              [[registry.mirror]]
302              location = "example-mirror-0.local/mirror-for-foo"
303
304              [[registry.mirror]]
305              location = "example-mirror-1.local/mirrors/foo"
306              insecure = true
307
308              [[registry]]
309              location = "registry.com"
310
311              [[registry.mirror]]
312              location = "mirror.registry.com"
313
314
315
316       Given the above, a pull of example.com/foo/image:latest will try:
317
318
319                1. example-mirror-0.local/mirror-for-foo/image:latest
320
321                2. example-mirror-1.local/mirrors/foo/image:latest
322
323                3. internal-registry-for-example.net/bar/image:latest
324
325
326
327       in order, and use the first one that exists.
328
329
330       Note  that  a  mirror  is associated only with the current [[registry]]
331       TOML table.  If  using  the  example  above,  pulling  the  image  reg‐
332       istry.com/image:latest   will  hence  only  reach  out  to  mirror.reg‐
333       istry.com, and the mirrors associated with example.com/foo will not  be
334       considered.
335
336

VERSION 1 FORMAT - DEPRECATED

338       VERSION  1 format is still supported but it does not support using reg‐
339       istry mirrors, longest-prefix matches, or location rewriting.
340
341
342       The TOML format is used to build a  simple  list  of  registries  under
343       three  categories:  registries.search,  registries.insecure,  and  reg‐
344       istries.block.  You can list multiple registries using  a  comma  sepa‐
345       rated list.
346
347
348       Search  registries are used when the caller of a container runtime does
349       not fully specify the container image that they want to execute.  These
350       registries  are prepended onto the front of the specified container im‐
351       age until the named image is found at a registry.
352
353
354       Note that insecure registries can be used for any  registry,  not  just
355       the registries listed under search.
356
357
358       The  registries.insecure and registries.block lists have the same mean‐
359       ing as the insecure and blocked fields in the current version.
360
361
362   EXAMPLE
363       The following example configuration defines two searchable  registries,
364       one insecure registry, and two blocked registries.
365
366
367              [registries.search]
368              registries = ['registry1.com', 'registry2.com']
369
370              [registries.insecure]
371              registries = ['registry3.com']
372
373              [registries.block]
374              registries = ['registry.untrusted.com', 'registry.unsafe.com']
375
376
377
378

NOTE: RISK OF USING UNQUALIFIED IMAGE NAMES

380       We  recommend  always  using  fully qualified image names including the
381       registry server (full dns name), namespace, image name, and tag  (e.g.,
382       registry.redhat.io/ubi8/ubi:latest).  When  using short names, there is
383       always an inherent risk that the image being pulled could  be  spoofed.
384       For example, a user wants to pull an image named foobar from a registry
385       and expects it to come from myregistry.com. If  myregistry.com  is  not
386       first  in  the  search list, an attacker could place a different foobar
387       image at a registry earlier in the search list. The user would acciden‐
388       tally  pull  and  run the attacker's image and code rather than the in‐
389       tended content. We recommend only  adding  registries  which  are  com‐
390       pletely trusted, i.e. registries which don't allow unknown or anonymous
391       users to create accounts with arbitrary names. This will prevent an im‐
392       age  from being spoofed, squatted or otherwise made insecure.  If it is
393       necessary to use one of these registries, it should be added at the end
394       of the list.
395
396
397       It is recommended to use fully-qualified images for pulling as the des‐
398       tination  registry   is   unambiguous.   Pulling   by   digest   (i.e.,
399       quay.io/repository/name@digest)  further  eliminates  the  ambiguity of
400       tags.
401
402
403

SEE ALSO

405       containers-auth.json(5) containers-certs.d(5)
406
407
408

HISTORY

410       Dec 2019, Warning added for unqualified  image  names  by  Tom  Sweeney
411       tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩
412
413
414       Mar  2019,  Added  additional  configuration  format  by Sascha Grunert
415       sgrunert@suse.com ⟨mailto:sgrunert@suse.com⟩
416
417
418       Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg
419       vrothberg@suse.com ⟨mailto:vrothberg@suse.com⟩
420
421
422       Jun     2018,    Updated    by    Tom    Sweeney    tsweeney@redhat.com
423       ⟨mailto:tsweeney@redhat.com⟩
424
425
426       Aug  2017,  Originally  compiled  by  Brent   Baude   bbaude@redhat.com
427       ⟨mailto:bbaude@redhat.com⟩
428
429
430
431registry                          System-wide    CONTAINERS-REGISTRIES.CONF(5)
Impressum