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 continue
59 with the appropriate separator) for a particular `[[registry]]` TOML table to be
60 considered; (only) the TOML table with the longest match is used. It can
61 also include wildcarded subdomains in the format `*.example.com` along as mentioned
62 above. The wildcard should only be present at the beginning as shown in the formats
63 above. Other cases will not work. For example, `*.example.com` is valid but
64 `example.*.com`, `*.example.com/foo` and `*.example.com:5000/foo/bar:baz` are not.
65 As a special case, the `prefix` field can be missing; if so, it defaults to the value
67 of the `location` field (described below).
68 Per-namespace settings
72 insecure
73 true or false. By default, container runtimes require TLS when
74 retrieving images from a registry. If insecure is set to true,
75 unencrypted HTTP as well as TLS connections with untrusted cer‐
76 tificates are allowed.
77 blocked
80 true or false. If true, pulling images with matching names is
81 forbidden.
82 Remapping and mirroring registries
85 The user-specified image reference is, primarily, a "logical" image
86 name, always used for naming the image. By default, the image refer‐
87 ence also directly specifies the registry and repository to use, but
88 the following options can be used to redirect the underlying accesses
89 to different registry servers or locations (e.g. to support configura‐
90 tions with no access to the internet without having to change Docker‐
91 files, or to add redundancy).
92 location
95 Accepts the same format as the prefix field, and specifies the
96 physical location of the prefix-rooted namespace.By default,
97 this equal to prefix (in which case prefix can be omitted and
98 the [[registry]] TOML table can only specify location).Example:
99 Given
100 prefix = "example.com/foo"
102 location = "internal-registry-for-example.net/bar"
103 requests for the image example.com/foo/myimage:latest will actually
105 work with the internal-registry-for-example.net/bar/myimage:latest im‐
106 age.With a prefix containing a wildcard in the format: "*.example.com"
107 for subdomain matching, the location can be empty. In such a case, pre‐
108 fix matching will occur, but no reference rewrite will occur. The orig‐
109 inal requested image string will be used as-is. But other settings like
110 insecure / blocked / mirrors will be applied to matching images.Exam‐
111 ple: Given
112 prefix = "*.example.com"
114 requests for the image blah.example.com/foo/myimage:latest will be used
116 as-is. But other settings like insecure/blocked/mirrors will be applied
117 to matching images
118 mirror An array of TOML tables specifying (possibly-partial) mirrors
121 for the prefix-rooted namespace.The mirrors are attempted in the
122 specified order; the first one that can be contacted and con‐
123 tains the image will be used (and if none of the mirrors con‐
124 tains the image, the primary location specified by the reg‐
125 istry.location field, or using the unmodified user-specified
126 reference, is tried last).Each TOML table in the mirror array
127 can contain the following fields, with the same semantics as if
128 specified in the [[registry]] TOML table directly:
129 • location
131 • insecure
133 mirror-by-digest-only
138 true or false. If true, mirrors will only be used during
139 pulling if the image reference includes a digest. Referencing
140 an image by digest ensures that the same is always used (whereas
141 referencing an image by a tag may cause different registries to
142 return different images if the tag mapping is out of sync).Note
143 that if this is true, images referenced by a tag will only use
144 the primary registry, failing if that registry is not accessi‐
145 ble.
146 Note: Redirection and mirrors are currently processed only when reading
149 images, not when pushing to a registry; that may change in the future.
150 Short-Name Aliasing
153 The use of unqualified-search registries entails an ambiguity as it is
154 unclear from which registry a given image, referenced by a short name,
155 may be pulled from.
156 As mentioned in the note at the end of this man page, using short names
159 is subject to the risk of hitting squatted registry namespaces. If the
160 unqualified-search registries are set to ["registry1.com", "reg‐
161 istry2.com"] an attacker may take over a namespace of registry1.com
162 such that an image may be pulled from registry1.com instead of the in‐
163 tended source registry2.com.
164 While it is highly recommended to always use fully-qualified image ref‐
167 erences, existing deployments using short names may not be easily
168 changed. To circumvent the aforementioned ambiguity, so called
169 short-name aliases can be configured that point to a fully-qualified
170 image reference.
171 Short-name aliases can be configured in the [aliases] table in the form
174 of "name"="value" with the left-hand name being the short name (e.g.,
175 "image") and the right-hand value being the fully-qualified image ref‐
176 erence (e.g., "registry.com/namespace/image"). Note that neither
177 "name" nor "value" can include a tag or digest. Moreover, "name" must
178 be a short name and hence cannot include a registry domain or refer to
179 localhost.
180 When pulling a short name, the configured aliases table will be used
183 for resolving the short name. If a matching alias is found, it will be
184 used without further consulting the unqualified-search registries list.
185 If no matching alias is found, the behavior can be controlled via the
186 short-name-mode option as described below.
187 Note that tags and digests are stripped off a user-specified short name
190 for alias resolution. Hence, "image", "image:tag" and "image@digest"
191 all resolve to the same alias (i.e., "image"). Stripped off tags and
192 digests are later appended to the resolved alias.
193 Further note that drop-in configuration files (see containers-reg‐
196 istries.conf.d(5)) can override aliases in the specific loading order
197 of the files. If the "value" of an alias is empty (i.e., ""), the
198 alias will be erased. However, a given "name" may only be specified
199 once in a single config file.
200 Short-Name Aliasing: Modes
203 The short-name-mode option supports three modes to control the behav‐
204 iour of short-name resolution.
205 • enforcing: If only one unqualified-search registry is set, use
208 it as there is no ambiguity. If there is more than one reg‐
209 istry and the user program is running in a terminal (i.e.,
210 stdout stdin are a TTY), prompt the user to select one of the
211 specified search registries. If the program is not running in
212 a terminal, the ambiguity cannot be resolved which will lead
213 to an error.
214 • permissive: Behaves as enforcing but does not lead to an error
216 if the program is not running in a terminal. Instead, fall‐
217 back to using all unqualified-search registries.
218 • disabled: Use all unqualified-search registries without
220 prompting.
221 If short-name-mode is not specified at all or left empty, default to
225 the permissive mode. If the user-specified short name was not aliased
226 already, the enforcing and permissive mode if prompted, will record a
227 new alias after a successful pull. Note that the recorded alias will
228 be written to /var/cache/containers/short-name-aliases.conf for root to
229 have a clear separation between possibly human-edited registries.conf
230 files and the machine-generated short-name-aliases-conf. Note that
231 $HOME/.cache is used for rootless users. If an alias is specified in a
232 registries.conf file and also the machine-generated
233 short-name-aliases.conf, the short-name-aliases.conf file has prece‐
234 dence.
235 Normalization of docker.io references
238 The Docker Hub docker.io is handled in a special way: every push and
239 pull operation gets internally normalized with /library if no other
240 specific namespace is defined (for example on docker.io/namespace/im‐
241 age).
242 (Note that the above-described normalization happens to match the be‐
245 havior of Docker.)
246 This means that a pull of docker.io/alpine will be internally trans‐
249 lated to docker.io/library/alpine. A pull of docker.io/user/alpine will
250 not be rewritten because this is already the correct remote path.
251 Therefore, to remap or mirror the docker.io images in the (implied)
254 /library namespace (or that whole namespace), the prefix and location
255 fields in this configuration file must explicitly include that /library
256 namespace. For example prefix = "docker.io/library/alpine" and not pre‐
257 fix = "docker.io/alpine". The latter would match the docker.io/alpine/*
258 repositories but not the docker.io/[library/]alpine image).
259 EXAMPLE
262 unqualified-search-registries = ["example.com"]
263 [[registry]]
265 prefix = "example.com/foo"
266 insecure = false
267 blocked = false
268 location = "internal-registry-for-example.com/bar"
269 [[registry.mirror]]
271 location = "example-mirror-0.local/mirror-for-foo"
272 [[registry.mirror]]
274 location = "example-mirror-1.local/mirrors/foo"
275 insecure = true
276 Given the above, a pull of example.com/foo/image:latest will try:
280 1. example-mirror-0.local/mirror-for-foo/image:latest
281 2. example-mirror-1.local/mirrors/foo/image:latest
282 3. internal-registry-for-example.net/bar/image:latest
283 in order, and use the first one that exists.
286
289 VERSION 1 format is still supported but it does not support using reg‐
290 istry mirrors, longest-prefix matches, or location rewriting.
291 The TOML format is used to build a simple list of registries under
294 three categories: registries.search, registries.insecure, and reg‐
295 istries.block. You can list multiple registries using a comma sepa‐
296 rated list.
297 Search registries are used when the caller of a container runtime does
300 not fully specify the container image that they want to execute. These
301 registries are prepended onto the front of the specified container im‐
302 age until the named image is found at a registry.
303 Note that insecure registries can be used for any registry, not just
306 the registries listed under search.
307 The registries.insecure and registries.block lists have the same mean‐
310 ing as the insecure and blocked fields in the current version.
311 EXAMPLE
314 The following example configuration defines two searchable registries,
315 one insecure registry, and two blocked registries.
316 [registries.search]
319 registries = ['registry1.com', 'registry2.com']
320 [registries.insecure]
322 registries = ['registry3.com']
323 [registries.block]
325 registries = ['registry.untrusted.com', 'registry.unsafe.com']
326
331 We recommend always using fully qualified image names including the
332 registry server (full dns name), namespace, image name, and tag (e.g.,
333 registry.redhat.io/ubi8/ubi:latest). When using short names, there is
334 always an inherent risk that the image being pulled could be spoofed.
335 For example, a user wants to pull an image named foobar from a registry
336 and expects it to come from myregistry.com. If myregistry.com is not
337 first in the search list, an attacker could place a different foobar
338 image at a registry earlier in the search list. The user would acciden‐
339 tally pull and run the attacker's image and code rather than the in‐
340 tended content. We recommend only adding registries which are com‐
341 pletely trusted, i.e. registries which don't allow unknown or anonymous
342 users to create accounts with arbitrary names. This will prevent an im‐
343 age from being spoofed, squatted or otherwise made insecure. If it is
344 necessary to use one of these registries, it should be added at the end
345 of the list.
346 It is recommended to use fully-qualified images for pulling as the des‐
349 tination registry is unambiguous. Pulling by digest (i.e.,
350 quay.io/repository/name@digest) further eliminates the ambiguity of
351 tags.
352
356 containers-auth.json(5) containers-certs.d(5)
357
361 Dec 2019, Warning added for unqualified image names by Tom Sweeney
362 tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩
363 Mar 2019, Added additional configuration format by Sascha Grunert
366 sgrunert@suse.com ⟨mailto:sgrunert@suse.com⟩
367 Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg
370 vrothberg@suse.com ⟨mailto:vrothberg@suse.com⟩
371 Jun 2018, Updated by Tom Sweeney tsweeney@redhat.com
374 ⟨mailto:tsweeney@redhat.com⟩
375 Aug 2017, Originally compiled by Brent Baude bbaude@redhat.com
378 ⟨mailto:bbaude@redhat.com⟩
379configuration reCgOiNsTtArIyNERS-REGISTRIES.CONF(5)(System-wide)