1CONTAINERS-REGISTRIES.CONF(5) configuration CONTAINERS-REGISTRIES.CONF(5)
2
3
4
5Brent Baude Aug 2017
6
7
9 containers-registries.conf - Syntax of System Registry Configuration
10 File
11
12
13
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
239 • enforcing: 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
247 • permissive: 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
251 • disabled: 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
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
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
405 containers-auth.json(5) containers-certs.d(5)
406
407
408
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)