1CONTAINERS-REGISTRIES.CONF(5)(System-CwfOiiNdlTeeA)INERS-REGISTRIES.CONF(5)(System-wide)
2Brent Baude Aug 2017
6
9 containers-registries.conf - Syntax of System Registry Configuration
10 File
11
15 The CONTAINERS-REGISTRIES configuration file is a system-wide configu‐
16 ration file for container image registries. The file format is TOML.
17 Container engines will use the $HOME/.config/containers/registries.conf
20 if it exists, otherwise they will use /etc/containers/registries.conf
21 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 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 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 Choosing a [[registry]] TOML table
45 Given an image name, a single [[registry]] TOML table is chosen based
46 on its prefix field.
47 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 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.
66 As a special case, the prefix field can be missing; if so, it defaults
69 to the value of the location field (described below).
70 Per-namespace settings
73 insecure
74 true or false. By default, container runtimes require TLS when
75 retrieving images from a registry. If insecure is set to true,
76 unencrypted HTTP as well as TLS connections with untrusted cer‐
77 tificates are allowed.
78 blocked
81 true or false. If true, pulling images with matching names is
82 forbidden.
83 Remapping and mirroring registries
86 The user-specified image reference is, primarily, a "logical" image
87 name, always used for naming the image. By default, the image refer‐
88 ence also directly specifies the registry and repository to use, but
89 the following options can be used to redirect the underlying accesses
90 to different registry servers or locations (e.g. to support configura‐
91 tions with no access to the internet without having to change Docker‐
92 files, or to add redundancy).
93 location
96 Accepts the same format as the prefix field, and specifies the
97 physical location of the prefix-rooted namespace.
98 By default, this equal to prefix (in which case prefix can be omitted
101 and the [[registry]] TOML table can only specify location).
102 Example: Given
105 prefix = "example.com/foo"
108 location = "internal-registry-for-example.net/bar"
109 requests for the image example.com/foo/myimage:latest will actually
113 work with the internal-registry-for-example.net/bar/myimage:latest im‐
114 age.
115 With a prefix containing a wildcard in the format: "*.example.com" for
118 subdomain matching, the location can be empty. In such a case, prefix
119 matching will occur, but no reference rewrite will occur. The original
120 requested image string will be used as-is. But other settings like in‐
121 secure / blocked / mirrors will be applied to matching images.
122 Example: Given
125 prefix = "*.example.com"
128 requests for the image blah.example.com/foo/myimage:latest will be used
132 as-is. But other settings like insecure/blocked/mirrors will be applied
133 to matching images
134 mirror An array of TOML tables specifying (possibly-partial) mirrors
137 for the prefix-rooted namespace.
138 The mirrors are attempted in the specified order; the first one that
141 can be contacted and contains the image will be used (and if none of
142 the mirrors contains the image, the primary location specified by the
143 registry.location field, or using the unmodified user-specified refer‐
144 ence, is tried last).
145 Each TOML table in the mirror array can contain the following fields,
148 with the same semantics as if specified in the [[registry]] TOML table
149 directly: - location - insecure
150 mirror-by-digest-only
153 true or false. If true, mirrors will only be used during
154 pulling if the image reference includes a digest. Referencing
155 an image by digest ensures that the same is always used (whereas
156 referencing an image by a tag may cause different registries to
157 return different images if the tag mapping is out of sync).
158 Note that if this is true, images referenced by a tag will only use the
161 primary registry, failing if that registry is not accessible.
162 Note: Redirection and mirrors are currently processed only when reading
165 images, not when pushing to a registry; that may change in the future.
166 Short-Name Aliasing
169 The use of unqualified-search registries entails an ambiguity as it is
170 unclear from which registry a given image, referenced by a short name,
171 may be pulled from.
172 As mentioned in the note at the end of this man page, using short names
175 is subject to the risk of hitting squatted registry namespaces. If the
176 unqualified-search registries are set to ["registry1.com", "reg‐
177 istry2.com"] an attacker may take over a namespace of registry1.com
178 such that an image may be pulled from registry1.com instead of the in‐
179 tended source registry2.com.
180 While it is highly recommended to always use fully-qualified image ref‐
183 erences, existing deployments using short names may not be easily
184 changed. To circumvent the aforementioned ambiguity, so called short-
185 name aliases can be configured that point to a fully-qualified image
186 reference.
187 Short-name aliases can be configured in the [aliases] table in the form
190 of "name"="value" with the left-hand name being the short name (e.g.,
191 "image") and the right-hand value being the fully-qualified image ref‐
192 erence (e.g., "registry.com/namespace/image"). Note that neither
193 "name" nor "value" can include a tag or digest. Moreover, "name" must
194 be a short name and hence cannot include a registry domain or refer to
195 localhost.
196 When pulling a short name, the configured aliases table will be used
199 for resolving the short name. If a matching alias is found, it will be
200 used without further consulting the unqualified-search registries list.
201 If no matching alias is found, the behavior can be controlled via the
202 short-name-mode option as described below.
203 Note that tags and digests are stripped off a user-specified short name
206 for alias resolution. Hence, "image", "image:tag" and "image@digest"
207 all resolve to the same alias (i.e., "image"). Stripped off tags and
208 digests are later appended to the resolved alias.
209 Further note that drop-in configuration files (see containers-reg‐
212 istries.conf.d(5)) can override aliases in the specific loading order
213 of the files. If the "value" of an alias is empty (i.e., ""), the
214 alias will be erased. However, a given "name" may only be specified
215 once in a single config file.
216 Short-Name Aliasing: Modes
219 The short-name-mode option supports three modes to control the behav‐
220 iour of short-name resolution.
221 • enforcing: If only one unqualified-search registry is set, use
224 it as there is no ambiguity. If there is more than one reg‐
225 istry and the user program is running in a terminal (i.e.,
226 stdout & stdin are a TTY), prompt the user to select one of
227 the specified search registries. If the program is not run‐
228 ning in a terminal, the ambiguity cannot be resolved which
229 will lead to an error.
230 • permissive: Behaves as enforcing but does not lead to an error
232 if the program is not running in a terminal. Instead, fall‐
233 back to using all unqualified-search registries.
234 • disabled: Use all unqualified-search registries without
236 prompting.
237 If short-name-mode is not specified at all or left empty, default to
241 the permissive mode. If the user-specified short name was not aliased
242 already, the enforcing and permissive mode if prompted, will record a
243 new alias after a successful pull. Note that the recorded alias will
244 be written to /var/cache/containers/short-name-aliases.conf for root to
245 have a clear separation between possibly human-edited registries.conf
246 files and the machine-generated short-name-aliases-conf. Note that
247 $HOME/.cache is used for rootless users. If an alias is specified in a
248 registries.conf file and also the machine-generated short-name-
249 aliases.conf, the short-name-aliases.conf file has precedence.
250 Normalization of docker.io references
253 The Docker Hub docker.io is handled in a special way: every push and
254 pull operation gets internally normalized with /library if no other
255 specific namespace is defined (for example on docker.io/namespace/im‐
256 age).
257 (Note that the above-described normalization happens to match the be‐
260 havior of Docker.)
261 This means that a pull of docker.io/alpine will be internally trans‐
264 lated to docker.io/library/alpine. A pull of docker.io/user/alpine will
265 not be rewritten because this is already the correct remote path.
266 Therefore, to remap or mirror the docker.io images in the (implied)
269 /library namespace (or that whole namespace), the prefix and location
270 fields in this configuration file must explicitly include that /library
271 namespace. For example prefix = "docker.io/library/alpine" and not pre‐
272 fix = "docker.io/alpine". The latter would match the docker.io/alpine/*
273 repositories but not the docker.io/[library/]alpine image).
274 EXAMPLE
277 unqualified-search-registries = ["example.com"]
278 [[registry]]
280 prefix = "example.com/foo"
281 insecure = false
282 blocked = false
283 location = "internal-registry-for-example.com/bar"
284 [[registry.mirror]]
286 location = "example-mirror-0.local/mirror-for-foo"
287 [[registry.mirror]]
289 location = "example-mirror-1.local/mirrors/foo"
290 insecure = true
291 Given the above, a pull of example.com/foo/image:latest will try:
295 1. example-mirror-0.local/mirror-for-foo/image:latest
296 2. example-mirror-1.local/mirrors/foo/image:latest
297 3. internal-registry-for-example.net/bar/image:latest
298 in order, and use the first one that exists.
301
304 VERSION 1 format is still supported but it does not support using reg‐
305 istry mirrors, longest-prefix matches, or location rewriting.
306 The TOML format is used to build a simple list of registries under
309 three categories: registries.search, registries.insecure, and reg‐
310 istries.block. You can list multiple registries using a comma sepa‐
311 rated list.
312 Search registries are used when the caller of a container runtime does
315 not fully specify the container image that they want to execute. These
316 registries are prepended onto the front of the specified container im‐
317 age until the named image is found at a registry.
318 Note that insecure registries can be used for any registry, not just
321 the registries listed under search.
322 The registries.insecure and registries.block lists have the same mean‐
325 ing as the insecure and blocked fields in the current version.
326 EXAMPLE
329 The following example configuration defines two searchable registries,
330 one insecure registry, and two blocked registries.
331 [registries.search]
334 registries = ['registry1.com', 'registry2.com']
335 [registries.insecure]
337 registries = ['registry3.com']
338 [registries.block]
340 registries = ['registry.untrusted.com', 'registry.unsafe.com']
341
346 We recommend always using fully qualified image names including the
347 registry server (full dns name), namespace, image name, and tag (e.g.,
348 registry.redhat.io/ubi8/ubi:latest). When using short names, there is
349 always an inherent risk that the image being pulled could be spoofed.
350 For example, a user wants to pull an image named foobar from a registry
351 and expects it to come from myregistry.com. If myregistry.com is not
352 first in the search list, an attacker could place a different foobar
353 image at a registry earlier in the search list. The user would acciden‐
354 tally pull and run the attacker's image and code rather than the in‐
355 tended content. We recommend only adding registries which are com‐
356 pletely trusted, i.e. registries which don't allow unknown or anonymous
357 users to create accounts with arbitrary names. This will prevent an im‐
358 age from being spoofed, squatted or otherwise made insecure. If it is
359 necessary to use one of these registries, it should be added at the end
360 of the list.
361 It is recommended to use fully-qualified images for pulling as the des‐
364 tination registry is unambiguous. Pulling by digest (i.e.,
365 quay.io/repository/name@digest) further eliminates the ambiguity of
366 tags.
367
371 containers-auth.json(5) containers-certs.d(5)
372
376 Dec 2019, Warning added for unqualified image names by Tom Sweeney
377 tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩
378 Mar 2019, Added additional configuration format by Sascha Grunert
381 sgrunert@suse.com ⟨mailto:sgrunert@suse.com⟩
382 Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg
385 vrothberg@suse.com ⟨mailto:vrothberg@suse.com⟩
386 Jun 2018, Updated by Tom Sweeney tsweeney@redhat.com
389 ⟨mailto:tsweeney@redhat.com⟩
390 Aug 2017, Originally compiled by Brent Baude bbaude@redhat.com
393 ⟨mailto:bbaude@redhat.com⟩
394configuration reCgOiNsTtArIyNERS-REGISTRIES.CONF(5)(System-wide)