1containers-storage.conf(5)(Container)Filecontainers-storage.conf(5)(Container)
2Dan Walsh May 2017
6
9 storage.conf - Syntax of Container Storage configuration file
10
13 The STORAGE configuration file specifies all of the available container
14 storage options for tools using shared container storage, but in a TOML
15 format that can be more easily modified and versioned.
16
19 The [TOML format][toml] is used as the encoding of the configuration
20 file. Every option and subtable listed here is nested under a global
21 "storage" table. No bare options are used. The format of TOML can be
22 simplified to:
23 [table]
26 option = value
27 [table.subtable1]
29 option = value
30 [table.subtable2]
32 option = value
33
37 The storage table supports the following options:
38 driver=""
41 container storage driver (default: "overlay")
42 Default Copy On Write (COW) container storage driver. Valid drivers
43 are "overlay", "vfs", "devmapper", "aufs", "btrfs", and "zfs". Some
44 drivers (for example, "zfs", "btrfs", and "aufs") may not work if your
45 kernel lacks support for the filesystem.
46 graphroot=""
49 container storage graph dir (default: "/var/lib/containers/storage")
50 Default directory to store all writable content created by container
51 storage programs.
52 rootless_storage_path="$HOME/.local/share/containers/storage"
55 Storage path for rootless users. By default the graphroot for root‐
56 less users is set to $XDG_DATA_HOME/containers/storage, if
57 XDG_DATA_HOME is set. Otherwise $HOME/.local/share/containers/storage
58 is used. This field can be used if administrators need to change the
59 storage location for all users.
60 The rootless storage path supports three substations:
63 * `$HOME` => Replaced by the users home directory.
64 * `$UID` => Replaced by the users UID
65 * `$USER` => Replaced by the users name
66 A common use case for this field is to provide a local storage direc‐
70 tory when user home directories are NFS-mounted (podman does not sup‐
71 port container storage over NFS).
72 runroot=""
75 container storage run dir (default: "/var/run/containers/storage")
76 Default directory to store all temporary writable content created by
77 container storage programs.
78 STORAGE OPTIONS TABLE
81 The storage.options table supports the following options:
82 additionalimagestores=[]
85 Paths to additional container image stores. Usually these are
86 read/only and stored on remote network shares.
87 remap-uids="" remap-gids=""
90 Remap-UIDs/GIDs is the mapping from UIDs/GIDs as they should appear
91 inside of a container, to the UIDs/GIDs outside of the container, and
92 the length of the range of UIDs/GIDs. Additional mapped sets can be
93 listed and will be heeded by libraries, but there are limits to the
94 number of mappings which the kernel will allow when you later attempt
95 to run a container.
96 Example
99 remap-uids = 0:1668442479:65536
100 remap-gids = 0:1668442479:65536
101 These mappings tell the container engines to map UID 0 inside of the
104 container to UID 1668442479 outside. UID 1 will be mapped to
105 1668442480. UID 2 will be mapped to 1668442481, etc, for the next 65533
106 UIDs in succession.
107 remap-user="" remap-group=""
110 Remap-User/Group is a user name which can be used to look up one or
111 more UID/GID ranges in the /etc/subuid or /etc/subgid file. Mappings
112 are set up starting with an in-container ID of 0 and then a host-level
113 ID taken from the lowest range that matches the specified name, and
114 using the length of that range. Additional ranges are then assigned,
115 using the ranges which specify the lowest host-level IDs first, to the
116 lowest not-yet-mapped in-container ID, until all of the entries have
117 been used for maps.
118 Example
121 remap-user = "containers"
122 remap-group = "containers"
123 root-auto-userns-user=""
126 Root-auto-userns-user is a user name which can be used to look up one
127 or more UID/GID ranges in the /etc/subuid and /etc/subgid file. These
128 ranges will be partioned to containers configured to create automati‐
129 cally a user namespace. Containers configured to automatically create
130 a user namespace can still overlap with containers having an explicit
131 mapping set. This setting is ignored when running as rootless.
132 auto-userns-min-size=1024
135 Auto-userns-min-size is the minimum size for a user namespace created
136 automatically.
137 auto-userns-max-size=65536
140 Auto-userns-max-size is the maximum size for a user namespace created
141 automatically.
142 STORAGE OPTIONS FOR AUFS TABLE
145 The storage.options.aufs table supports the following options:
146 mountopt=""
149 Comma separated list of default options to be used to mount container
150 images. Suggested value "nodev". Mount options are documented in the
151 mount(8) man page.
152 STORAGE OPTIONS FOR BTRFS TABLE
155 The storage.options.btrfs table supports the following options:
156 min_space=""
159 Specifies the min space in a btrfs volume.
160 size=""
163 Maximum size of a container image. This flag can be used to set
164 quota on the size of container images. (format: [], where unit = b
165 (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
166 STORAGE OPTIONS FOR THINPOOL (devicemapper) TABLE
169 The storage.options.thinpool table supports the following options for
170 the devicemapper driver:
171 autoextend_percent=""
174 Tells the thinpool driver the amount by which the thinpool needs to
175 be grown. This is specified in terms of % of pool size. So a value of
176 20 means that when threshold is hit, pool will be grown by 20% of
177 existing pool size. (default: 20%)
178 autoextend_threshold=""
181 Tells the driver the thinpool extension threshold in terms of per‐
182 centage of pool size. For example, if threshold is 60, that means when
183 pool is 60% full, threshold has been hit. (default: 80%)
184 basesize=""
187 Specifies the size to use when creating the base device, which limits
188 the size of images and containers. (default: 10g)
189 blocksize=""
192 Specifies a custom blocksize to use for the thin pool. (default: 64k)
193 directlvm_device=""
196 Specifies a custom block storage device to use for the thin pool.
197 Required for using graphdriver devicemapper.
198 directlvm_device_force=""
201 Tells driver to wipe device (directlvm_device) even if device already
202 has a filesystem. (default: false)
203 fs="xfs"
206 Specifies the filesystem type to use for the base device. (default:
207 xfs)
208 log_level=""
211 Sets the log level of devicemapper.
212 0: LogLevelSuppress 0 (default)
215 2: LogLevelFatal
216 3: LogLevelErr
217 4: LogLevelWarn
218 5: LogLevelNotice
219 6: LogLevelInfo
220 7: LogLevelDebug
221 min_free_space=""
225 Specifies the min free space percent in a thin pool required for new
226 device creation to succeed. Valid values are from 0% - 99%. Value 0%
227 disables. (default: 10%)
228 mkfsarg=""
231 Specifies extra mkfs arguments to be used when creating the base
232 device.
233 mountopt=""
236 Comma separated list of default options to be used to mount container
237 images. Suggested value "nodev". Mount options are documented in the
238 mount(8) man page.
239 size=""
242 Maximum size of a container image. This flag can be used to set
243 quota on the size of container images. (format: [], where unit = b
244 (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
245 use_deferred_deletion=""
248 Marks thinpool device for deferred deletion. If the thinpool is in
249 use when the driver attempts to delete it, the driver will attempt to
250 delete device every 30 seconds until successful, or when it restarts.
251 Deferred deletion permanently deletes the device and all data stored in
252 the device will be lost. (default: true).
253 use_deferred_removal=""
256 Marks devicemapper block device for deferred removal. If the device
257 is in use when its driver attempts to remove it, the driver tells the
258 kernel to remove the device as soon as possible. Note this does not
259 free up the disk space, use deferred deletion to fully remove the thin‐
260 pool. (default: true).
261 xfs_nospace_max_retries=""
264 Specifies the maximum number of retries XFS should attempt to com‐
265 plete IO when ENOSPC (no space) error is returned by underlying storage
266 device. (default: 0, which means to try continuously.)
267 STORAGE OPTIONS FOR OVERLAY TABLE
270 The storage.options.overlay table supports the following options:
271 ignore_chown_errors = "false"
274 ignore_chown_errors can be set to allow a non privileged user running
275 with a single UID within a user namespace to run containers. The user
276 can pull and use any image even those with multiple uids. Note multi‐
277 ple UIDs will be squashed down to the default uid in the container.
278 These images will have no separation between the users in the con‐
279 tainer. (default: false)
280 mount_program=""
283 Specifies the path to a custom program to use instead of using kernel
284 defaults for mounting the file system. In rootless mode, without the
285 CAP_SYS_ADMIN capability, many kernels prevent mounting of overlay file
286 systems, requiring you to specify a mount_program. The mount_program
287 option is also required on systems where the underlying storage is
288 btrfs, aufs, zfs, overlay, or ecryptfs based file systems.
289 mount_program = "/usr/bin/fuse-overlayfs"
290 mountopt=""
293 Comma separated list of default options to be used to mount container
294 images. Suggested value "nodev". Mount options are documented in the
295 mount(8) man page.
296 size=""
299 Maximum size of a container image. This flag can be used to set
300 quota on the size of container images. (format: [], where unit = b
301 (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
302 STORAGE OPTIONS FOR VFS TABLE
305 The storage.options.vfs table supports the following options:
306 ignore_chown_errors = "false"
309 ignore_chown_errors can be set to allow a non privileged user running
310 with a single UID within a user namespace to run containers. The user
311 can pull and use any image even those with multiple uids. Note multi‐
312 ple UIDs will be squashed down to the default uid in the container.
313 These images will have no separation between the users in the con‐
314 tainer. (default: false)
315 STORAGE OPTIONS FOR ZFS TABLE
318 The storage.options.zfs table supports the following options:
319 fsname=""
322 File System name for the zfs driver
323 mountopt=""
326 Comma separated list of default options to be used to mount container
327 images. Suggested value "nodev". Mount options are documented in the
328 mount(8) man page.
329 size=""
332 Maximum size of a container image. This flag can be used to set
333 quota on the size of container images. (format: [], where unit = b
334 (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
335
338 When running on an SELinux system, if you move the containers storage
339 graphroot directory, you must make sure the labeling is correct.
340 Tell SELinux about the new containers storage by setting up an equiva‐
343 lence record. This tells SELinux to label content under the new path,
344 as if it was stored under /var/lib/containers/storage.
345 semanage fcontext -a -e /var/lib/containers NEWSTORAGEPATH
348 restorecon -R -v NEWSTORAGEPATH
349 The semanage command above tells SELinux to setup the default labeling
353 of NEWSTORAGEPATH to match /var/lib/containers. The restorecon command
354 tells SELinux to apply the labels to the actual content.
355 Now all new content created in these directories will automatically be
358 created with the correct label.
359
362 semanage(8), restorecon(8), mount(8)
363
366 Distributions often provide a /usr/share/containers/storage.conf file
367 to define default storage configuration. Administrators can override
368 this file by creating /etc/containers/storage.conf to specify their own
369 configuration. The storage.conf file for rootless users is stored in
370 the $XDG_CONFIG_HOME/containers/storage.conf file. If $XDG_CONFIG_HOME
371 is not set then the file $HOME/.config/containers/storage.conf is used.
372
375 May 2017, Originally compiled by Dan Walsh dwalsh@redhat.com
376 ⟨mailto:dwalsh@redhat.com⟩ Format copied from crio.conf man page cre‐
377 ated by Aleksa Sarai asarai@suse.de ⟨mailto:asarai@suse.de⟩
378Configuration Storagceontainers-storage.conf(5)(Container)