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
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 This field is required to guarantee proper operation.
47 Valid rootless drivers are "btrfs", "overlay", and "vfs".
48 Rootless users default to the driver defined in the system configura‐
49 tion when possible.
50 When the system configuration uses an unsupported rootless driver,
51 rootless users default to "overlay" if available, otherwise "vfs".
52 graphroot=""
55 container storage graph dir (default: "/var/lib/containers/storage")
56 Default directory to store all writable content created by container
57 storage programs.
58 The rootless graphroot path supports environment variable substitu‐
59 tions (ie. $HOME/containers/storage)
60 When changing the graphroot location on an SELINUX system, ensure
61 the labeling matches the default locations labels with the
62 following commands:
63 # semanage fcontext -a -e /var/lib/containers/storage /NEWSTORAGEPATH
66 # restorecon -R -v /NEWSTORAGEPATH
67 In Rootless Mode you would set
71 # semanage fcontext -a -e $HOME/.local/share/containers NEWSTORAGEPATH
74 $ restorecon -R -v /NEWSTORAGEPATH
75 rootless_storage_path="$HOME/.local/share/containers/storage"
79 Storage path for rootless users. By default the graphroot for root‐
80 less users
81 is set to $XDG_DATA_HOME/containers/storage, if XDG_DATA_HOME is set.
82 Otherwise $HOME/.local/share/containers/storage is used. This field
83 can
84 be used if administrators need to change the storage location for all
85 users.
86 The rootless storage path supports environment variable substitutions
87 (ie. $HOME/containers/storage)
88 A common use case for this field is to provide a local storage direc‐
91 tory when user home directories are NFS-mounted (podman does not sup‐
92 port container storage over NFS).
93 runroot=""
96 container storage run dir (default: "/run/containers/storage")
97 Default directory to store all temporary writable content created by
98 container storage programs.
99 The rootless runroot path supports environment variable substitutions
100 (ie. $HOME/containers/storage)
101 STORAGE OPTIONS TABLE
104 The storage.options table supports the following options:
105 additionalimagestores=[]
108 Paths to additional container image stores. Usually these are
109 read/only and stored on remote network shares.
110 remap-uids="" remap-gids=""
113 Remap-UIDs/GIDs is the mapping from UIDs/GIDs as they should appear
114 inside of a container, to the UIDs/GIDs outside of the container, and
115 the length of the range of UIDs/GIDs. Additional mapped sets can be
116 listed and will be heeded by libraries, but there are limits to the
117 number of mappings which the kernel will allow when you later attempt
118 to run a container.
119 Example
122 remap-uids = 0:1668442479:65536
123 remap-gids = 0:1668442479:65536
124 These mappings tell the container engines to map UID 0 inside of the
127 container to UID 1668442479 outside. UID 1 will be mapped to
128 1668442480. UID 2 will be mapped to 1668442481, etc, for the next 65533
129 UIDs in succession.
130 remap-user="" remap-group=""
133 Remap-User/Group is a user name which can be used to look up one or
134 more UID/GID ranges in the /etc/subuid or /etc/subgid file. Mappings
135 are set up starting with an in-container ID of 0 and then a host-level
136 ID taken from the lowest range that matches the specified name, and us‐
137 ing the length of that range. Additional ranges are then assigned, us‐
138 ing the ranges which specify the lowest host-level IDs first, to the
139 lowest not-yet-mapped in-container ID, until all of the entries have
140 been used for maps.
141 Example
144 remap-user = "containers"
145 remap-group = "containers"
146 root-auto-userns-user=""
149 Root-auto-userns-user is a user name which can be used to look up one
150 or more UID/GID ranges in the /etc/subuid and /etc/subgid file. These
151 ranges will be partitioned to containers configured to create automati‐
152 cally a user namespace. Containers configured to automatically create
153 a user namespace can still overlap with containers having an explicit
154 mapping set. This setting is ignored when running as rootless.
155 auto-userns-min-size=1024
158 Auto-userns-min-size is the minimum size for a user namespace created
159 automatically.
160 auto-userns-max-size=65536
163 Auto-userns-max-size is the maximum size for a user namespace created
164 automatically.
165 disable-volatile=true
168 If disable-volatile is set, then the "volatile" mount optimization is
169 disabled for all the containers.
170 STORAGE OPTIONS FOR AUFS TABLE
173 The storage.options.aufs table supports the following options:
174 mountopt=""
177 Comma separated list of default options to be used to mount container
178 images. Suggested value "nodev". Mount options are documented in the
179 mount(8) man page.
180 STORAGE OPTIONS FOR BTRFS TABLE
183 The storage.options.btrfs table supports the following options:
184 min_space=""
187 Specifies the min space in a btrfs volume.
188 size=""
191 Maximum size of a container image. This flag can be used to set
192 quota on the size of container images. (format: [], where unit = b
193 (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
194 STORAGE OPTIONS FOR THINPOOL (devicemapper) TABLE
197 The storage.options.thinpool table supports the following options for
198 the devicemapper driver:
199 autoextend_percent=""
202 Tells the thinpool driver the amount by which the thinpool needs to
203 be grown. This is specified in terms of % of pool size. So a value of
204 20 means that when threshold is hit, pool will be grown by 20% of ex‐
205 isting pool size. (default: 20%)
206 autoextend_threshold=""
209 Tells the driver the thinpool extension threshold in terms of per‐
210 centage of pool size. For example, if threshold is 60, that means when
211 pool is 60% full, threshold has been hit. (default: 80%)
212 basesize=""
215 Specifies the size to use when creating the base device, which limits
216 the size of images and containers. (default: 10g)
217 blocksize=""
220 Specifies a custom blocksize to use for the thin pool. (default: 64k)
221 directlvm_device=""
224 Specifies a custom block storage device to use for the thin pool. Re‐
225 quired for using graphdriver devicemapper.
226 directlvm_device_force=""
229 Tells driver to wipe device (directlvm_device) even if device already
230 has a filesystem. (default: false)
231 fs="xfs"
234 Specifies the filesystem type to use for the base device. (default:
235 xfs)
236 log_level=""
239 Sets the log level of devicemapper.
240 0: LogLevelSuppress 0 (default)
243 2: LogLevelFatal
244 3: LogLevelErr
245 4: LogLevelWarn
246 5: LogLevelNotice
247 6: LogLevelInfo
248 7: LogLevelDebug
249 metadata_size=""
253 metadata_size is used to set the pvcreate --metadatasize options when
254 creating thin devices. (Default 128k)
255 min_free_space=""
258 Specifies the min free space percent in a thin pool required for new
259 device creation to succeed. Valid values are from 0% - 99%. Value 0%
260 disables. (default: 10%)
261 mkfsarg=""
264 Specifies extra mkfs arguments to be used when creating the base de‐
265 vice.
266 mountopt=""
269 Comma separated list of default options to be used to mount container
270 images. Suggested value "nodev". Mount options are documented in the
271 mount(8) man page.
272 size=""
275 Maximum size of a container image. This flag can be used to set
276 quota on the size of container images. (format: [], where unit = b
277 (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
278 use_deferred_deletion=""
281 Marks thinpool device for deferred deletion. If the thinpool is in
282 use when the driver attempts to delete it, the driver will attempt to
283 delete device every 30 seconds until successful, or when it restarts.
284 Deferred deletion permanently deletes the device and all data stored in
285 the device will be lost. (default: true).
286 use_deferred_removal=""
289 Marks devicemapper block device for deferred removal. If the device
290 is in use when its driver attempts to remove it, the driver tells the
291 kernel to remove the device as soon as possible. Note this does not
292 free up the disk space, use deferred deletion to fully remove the thin‐
293 pool. (default: true).
294 xfs_nospace_max_retries=""
297 Specifies the maximum number of retries XFS should attempt to com‐
298 plete IO when ENOSPC (no space) error is returned by underlying storage
299 device. (default: 0, which means to try continuously.)
300 STORAGE OPTIONS FOR OVERLAY TABLE
303 The storage.options.overlay table supports the following options:
304 ignore_chown_errors = "false"
307 ignore_chown_errors can be set to allow a non privileged user running
308 with a single UID within a user namespace to run containers. The user
309 can pull and use any image even those with multiple uids. Note multi‐
310 ple UIDs will be squashed down to the default uid in the container.
311 These images will have no separation between the users in the con‐
312 tainer. (default: false)
313 inodes=""
316 Maximum inodes in a read/write layer. This flag can be used to set
317 a quota on the inodes allocated for a read/write layer of a container.
318 force_mask = "0000|shared|private"
321 ForceMask specifies the permissions mask that is used for new files
322 and directories. The values "shared" and "private" are accepted. (de‐
323 fault: ""). Octal permission masks are also accepted.
324 ``: Not set
327 All files/directories, get set with the permissions identified
328 within the image.
329 private: it is equivalent to 0700.
332 All files/directories get set with 0700 permissions. The owner
333 has rwx access to the files. No other users on the system can access
334 the files. This setting could be used with networked based home direc‐
335 tories.
336 shared: it is equivalent to 0755.
339 The owner has rwx access to the files and everyone else can read,
340 access and execute them. This setting is useful for sharing containers
341 storage with other users. For instance, a storage owned by root could
342 be shared to rootless users as an additional store. NOTE: All files
343 within the image are made readable and executable by any user on the
344 system. Even /etc/shadow within your image is now readable by any user.
345 OCTAL: Users can experiment with other OCTAL Permissions.
348 Note: The force_mask Flag is an experimental feature, it could change
351 in the future. When "force_mask" is set the original permission mask
352 is stored in the "user.containers.override_stat" xattr and the
353 "mount_program" option must be specified. Mount programs like
354 "/usr/bin/fuse-overlayfs" present the extended attribute permissions to
355 processes within containers rather then the "force_mask" permissions.
356 mount_program=""
359 Specifies the path to a custom program to use instead of using kernel
360 defaults for mounting the file system. In rootless mode, without the
361 CAP_SYS_ADMIN capability, many kernels prevent mounting of overlay file
362 systems, requiring you to specify a mount_program. The mount_program
363 option is also required on systems where the underlying storage is
364 btrfs, aufs, zfs, overlay, or ecryptfs based file systems.
365 mount_program = "/usr/bin/fuse-overlayfs"
366 mountopt=""
369 Comma separated list of default options to be used to mount container
370 images. Suggested value "nodev". Mount options are documented in the
371 mount(8) man page.
372 size=""
375 Maximum size of a read/write layer. This flag can be used to set
376 quota on the size of a read/write layer of a container. (format: [],
377 where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
378 STORAGE OPTIONS FOR VFS TABLE
381 The storage.options.vfs table supports the following options:
382 ignore_chown_errors = "false"
385 ignore_chown_errors can be set to allow a non privileged user running
386 with a single UID within a user namespace to run containers. The user
387 can pull and use any image even those with multiple uids. Note multi‐
388 ple UIDs will be squashed down to the default uid in the container.
389 These images will have no separation between the users in the con‐
390 tainer. (default: false)
391 STORAGE OPTIONS FOR ZFS TABLE
394 The storage.options.zfs table supports the following options:
395 fsname=""
398 File System name for the zfs driver
399 mountopt=""
402 Comma separated list of default options to be used to mount container
403 images. Suggested value "nodev". Mount options are documented in the
404 mount(8) man page.
405 skip_mount_home=""
408 Tell storage drivers to not create a PRIVATE bind mount on their home
409 directory.
410 size=""
413 Maximum size of a container image. This flag can be used to set
414 quota on the size of container images. (format: [], where unit = b
415 (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
416
419 When running on an SELinux system, if you move the containers storage
420 graphroot directory, you must make sure the labeling is correct.
421 Tell SELinux about the new containers storage by setting up an equiva‐
424 lence record. This tells SELinux to label content under the new path,
425 as if it was stored under /var/lib/containers/storage.
426 semanage fcontext -a -e /var/lib/containers NEWSTORAGEPATH
429 restorecon -R -v NEWSTORAGEPATH
430 In rootless mode, you would set
434 semanage fcontext -a -e $HOME/.local/share/containers NEWSTORAGEPATH
437 restorecon -R -v NEWSTORAGEPATH
438 The semanage command above tells SELinux to setup the default labeling
442 of NEWSTORAGEPATH to match /var/lib/containers. The restorecon command
443 tells SELinux to apply the labels to the actual content.
444 Now all new content created in these directories will automatically be
447 created with the correct label.
448
451 Container storage implements XFS project quota controls for overlay
452 storage containers and volumes. The directory used to store the con‐
453 tainers must be an XFS file system and be mounted with the pquota op‐
454 tion.
455 Example /etc/fstab entry:
458 /dev/podman/podman-var /var xfs defaults,x-systemd.device-timeout=0,pquota 1 2
461 Container storage generates project ids for each container and builtin
465 volume, but these project ids need to be unique for the XFS file sys‐
466 tem.
467 The xfs_quota tool can be used to assign a project id to the storage
470 driver directory, e.g.:
471 echo 100000:/var/lib/containers/storage/overlay >> /etc/projects
474 echo 200000:/var/lib/containers/storage/volumes >> /etc/projects
475 echo storage:100000 >> /etc/projid
476 echo volumes:200000 >> /etc/projid
477 xfs_quota -x -c 'project -s storage volumes' /<xfs mount point>
478 In the example above, the storage directory project id will be used as
482 a "start offset" and all containers will be assigned larger project ids
483 (e.g. >= 100000). Then the volumes directory project id will be used
484 as a "start offset" and all volumes will be assigned larger project ids
485 (e.g. >= 200000). This is a way to prevent xfs_quota management from
486 conflicting with containers/storage.
487
490 Distributions often provide a /usr/share/containers/storage.conf file
491 to define default storage configuration. Administrators can override
492 this file by creating /etc/containers/storage.conf to specify their own
493 configuration. Likewise rootless users can create a storage.conf file
494 to override the system storage.conf files. Files should be stored in
495 the $XDG_CONFIG_HOME/containers/storage.conf file. If $XDG_CONFIG_HOME
496 is not set then the file $HOME/.config/containers/storage.conf is used.
497 Note: The storage.conf file overrides all other strorage.conf files.
500 Container engines run by users with a storage.conf file in their home
501 directory do not use options in the system storage.conf files.
502 /etc/projects - XFS persistent project root definition /etc/projid -
505 XFS project name mapping file
506
509 semanage(8), restorecon(8), mount(8), fuse-overlayfs(1), xfs_quota(8),
510 projects(5), projid(5)
511
514 May 2017, Originally compiled by Dan Walsh dwalsh@redhat.com
515 ⟨mailto:dwalsh@redhat.com⟩ Format copied from crio.conf man page cre‐
516 ated by Aleksa Sarai asarai@suse.de ⟨mailto:asarai@suse.de⟩
517Configuration Storagceontainers-storage.conf(5)(Container)