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
26 unqualified image, in order.
27 NAMESPACED [[registry]] SETTINGS
30 The bulk of the configuration is represented as an array of [[reg‐
31 istry]] TOML tables; the settings may therefore differ among different
32 registries as well as among different namespaces/repositories within a
33 registry.
34 Choosing a [[registry]] TOML table
37 Given an image name, a single [[registry]] TOML table is chosen based
38 on its prefix field.
39 prefix A prefix of the user-specified image name, i.e. using one of the
42 following formats:
43 · host[:port]
45 · host[:port]/namespace[/_namespace_…]
47 · host[:port]/namespace[/_namespace_…]/repo
49 · host[:port]/namespace[/_namespace_…]/repo(:_tag|@digest)
51 The user-specified image name must start with the specified prefix (and
53 continue with the appropriate separator) for a particular [[registry]]
54 TOML table to be considered; (only) the TOML table with the longest
55 match is used.As a special case, the prefix field can be missing; if
56 so, it defaults to the value of the location field (described below).
57 Per-namespace settings
60 insecure
61 true or false. By default, container runtimes require TLS when
62 retrieving images from a registry. If insecure is set to true,
63 unencrypted HTTP as well as TLS connections with untrusted cer‐
64 tificates are allowed.
65 blocked
68 true or false. If true, pulling images with matching names is
69 forbidden.
70 Remapping and mirroring registries
73 The user-specified image reference is, primarily, a "logical" image
74 name, always used for naming the image. By default, the image refer‐
75 ence also directly specifies the registry and repository to use, but
76 the following options can be used to redirect the underlying accesses
77 to different registry servers or locations (e.g. to support configura‐
78 tions with no access to the internet without having to change Docker‐
79 files, or to add redundancy).
80 location
83 Accepts the same format as the prefix field, and specifies the
84 physical location of the prefix-rooted namespace.By default,
85 this equal to prefix (in which case prefix can be omitted and
86 the [[registry]] TOML table can only specify location).Example:
87 Given
88 prefix = "example.com/foo"
90 location = "internal-registry-for-example.net/bar"
91 requests for the image example.com/foo/myimage:latest will actually
93 work with the internal-registry-for-example.net/bar/myimage:latest
94 image.
95 mirror An array of TOML tables specifying (possibly-partial) mirrors
98 for the prefix-rooted namespace.The mirrors are attempted in the
99 specified order; the first one that can be contacted and con‐
100 tains the image will be used (and if none of the mirrors con‐
101 tains the image, the primary location specified by the reg‐
102 istry.location field, or using the unmodified user-specified
103 reference, is tried last).Each TOML table in the mirror array
104 can contain the following fields, with the same semantics as if
105 specified in the [[registry]] TOML table directly:
106 · location
108 · insecure
110 mirror-by-digest-only
115 true or false. If true, mirrors will only be used during
116 pulling if the image reference includes a digest. Referencing
117 an image by digest ensures that the same is always used (whereas
118 referencing an image by a tag may cause different registries to
119 return different images if the tag mapping is out of sync).Note
120 that if this is true, images referenced by a tag will only use
121 the primary registry, failing if that registry is not accessi‐
122 ble.
123 Note: Redirection and mirrors are currently processed only when reading
126 images, not when pushing to a registry; that may change in the future.
127 Normalization of docker.io references
130 The Docker Hub docker.io is handled in a special way: every push and
131 pull operation gets internally normalized with /library if no other
132 specific namespace is defined (for example on docker.io/names‐
133 pace/image).
134 (Note that the above-described normalization happens to match the
137 behavior of Docker.)
138 This means that a pull of docker.io/alpine will be internally trans‐
141 lated to docker.io/library/alpine. A pull of docker.io/user/alpine will
142 not be rewritten because this is already the correct remote path.
143 Therefore, to remap or mirror the docker.io images in the (implied)
146 /library namespace (or that whole namespace), the prefix and location
147 fields in this configuration file must explicitly include that /library
148 namespace. For example prefix = "docker.io/library/alpine" and not pre‐
149 fix = "docker.io/alpine". The latter would match the docker.io/alpine/*
150 repositories but not the docker.io/[library/]alpine image).
151 EXAMPLE
154 unqualified-search-registries = ["example.com"]
155 [[registry]]
157 prefix = "example.com/foo"
158 insecure = false
159 blocked = false
160 location = "internal-registry-for-example.com/bar"
161 [[registry.mirror]]
163 location = "example-mirror-0.local/mirror-for-foo"
164 [[registry.mirror]]
166 location = "example-mirror-1.local/mirrors/foo"
167 insecure = true
168 Given the above, a pull of example.com/foo/image:latest will try:
172 1. example-mirror-0.local/mirror-for-foo/image:latest
173 2. example-mirror-1.local/mirrors/foo/image:latest
174 3. internal-registry-for-example.net/bar/image:latest
175 in order, and use the first one that exists.
178
181 VERSION 1 format is still supported but it does not support using reg‐
182 istry mirrors, longest-prefix matches, or location rewriting.
183 The TOML format is used to build a simple list of registries under
186 three categories: registries.search, registries.insecure, and reg‐
187 istries.block. You can list multiple registries using a comma sepa‐
188 rated list.
189 Search registries are used when the caller of a container runtime does
192 not fully specify the container image that they want to execute. These
193 registries are prepended onto the front of the specified container
194 image until the named image is found at a registry.
195 Note that insecure registries can be used for any registry, not just
198 the registries listed under search.
199 The registries.insecure and registries.block lists have the same mean‐
202 ing as the insecure and blocked fields in the current version.
203 EXAMPLE
206 The following example configuration defines two searchable registries,
207 one insecure registry, and two blocked registries.
208 [registries.search]
211 registries = ['registry1.com', 'registry2.com']
212 [registries.insecure]
214 registries = ['registry3.com']
215 [registries.block]
217 registries = ['registry.untrusted.com', 'registry.unsafe.com']
218
223 We recommend always using fully qualified image names including the
224 registry server (full dns name), namespace, image name, and tag (e.g.,
225 registry.redhat.io/ubi8/ubi:latest). When using short names, there is
226 always an inherent risk that the image being pulled could be spoofed.
227 For example, a user wants to pull an image named foobar from a registry
228 and expects it to come from myregistry.com. If myregistry.com is not
229 first in the search list, an attacker could place a different foobar
230 image at a registry earlier in the search list. The user would acciden‐
231 tally pull and run the attacker's image and code rather than the
232 intended content. We recommend only adding registries which are com‐
233 pletely trusted, i.e. registries which don't allow unknown or anonymous
234 users to create accounts with arbitrary names. This will prevent an
235 image from being spoofed, squatted or otherwise made insecure. If it
236 is necessary to use one of these registries, it should be added at the
237 end of the list.
238 It is recommended to use fully-qualified images for pulling as the des‐
241 tination registry is unambiguous. Pulling by digest (i.e.,
242 quay.io/repository/name@digest) further eliminates the ambiguity of
243 tags.
244
248 containers-certs.d(5)
249
253 Dec 2019, Warning added for unqualified image names by Tom Sweeney
254 tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩
255 Mar 2019, Added additional configuration format by Sascha Grunert
258 sgrunert@suse.com ⟨mailto:sgrunert@suse.com⟩
259 Aug 2018, Renamed to containers-registries.conf(5) by Valentin Rothberg
262 vrothberg@suse.com ⟨mailto:vrothberg@suse.com⟩
263 Jun 2018, Updated by Tom Sweeney tsweeney@redhat.com
266 ⟨mailto:tsweeney@redhat.com⟩
267 Aug 2017, Originally compiled by Brent Baude bbaude@redhat.com
270 ⟨mailto:bbaude@redhat.com⟩
271configuration reCgOiNsTtArIyNERS-REGISTRIES.CONF(5)(System-wide)