1containers.conf(5)(Container) file containers.conf(5)(Container)
2
6 containers.conf - The container engine configuration file specifies
7 default configuration options and command-line flags for container
8 engines.
9
13 Container engines like Podman Buildah read containers.conf file, if it
14 exists and modify the defaults for running containers on the host. con‐
15 tainers.conf uses a TOML format that can be easily modified and ver‐
16 sioned.
17 Container engines read the /usr/share/containers/containers.conf and
20 /etc/containers/containers.conf files if they exists. When running in
21 rootless mode, they also read $HOME/.config/containers/containers.conf
22 files.
23 Fields specified in containers conf override the default options, as
26 well as options in previously read containers.conf files.
27 Not all options are supported in all container engines.
30 Note container engines also use other configuration files for configur‐
33 ing the environment.
34 · storage.conf for configuration of container and images stor‐
37 age.
38 · registries.conf for definition of container registires to
40 search while pulling. container images.
41 · policy.conf for controlling which images can be pulled to the
43 system.
44
49 The TOML format ⟨https://github.com/toml-lang/toml⟩ is used as the
50 encoding of the configuration file. Every option is nested under its
51 table. No bare options are used. The format of TOML can be simplified
52 to:
53 [table1]
56 option = value
57 [table2]
59 option = value
60 [table3]
62 option = value
63 [table3.subtable1]
65 option = value
66
70 The containers table contains settings pertaining to the OCI runtime
71 that can configure and manage the OCI runtime.
72 devices=[]
75 List of devices. Specified as 'device-on-host:device-on-container:per‐
78 missions'. Example: "/dev/sdc:/dev/xvdc:rwm".
79 volumes=[]
82 List of volumes. Specified as "directory-on-host:directory-in-con‐
85 tainer:options". Example: "/db:/var/lib/db:ro".
86 apparmor_profile="container-default"
89 Used to change the name of the default AppArmor profile of container
92 engines. The default profile name is "container-default".
93 cgroupns="private"
96 Default way to to create a cgroup namespace for the container. Options
99 are: private Create private Cgroup Namespace for the container. host
100 Share host Cgroup Namespace with the container.
101 cgroups="enabled"
104 Determines whether the container will create CGroups. Options are:
107 enabled Enable cgroup support within container
108 disabled Disable cgroup support, will inherit cgroups from parent
109 no-conmon Container engine runs run without conmon
110 default_capabilities=[]
113 List of default capabilities for containers.
116 The default list is:
119 default_capabilities = [
122 "AUDIT_WRITE",
123 "CHOWN",
124 "DAC_OVERRIDE",
125 "FOWNER",
126 "FSETID",
127 "KILL",
128 "MKNOD",
129 "NET_BIND_SERVICE",
130 "NET_RAW",
131 "SETGID",
132 "SETPCAP",
133 "SETUID",
134 "SYS_CHROOT",
135 ]
136 default_sysctls=[]
140 A list of sysctls to be set in containers by default, specified as
143 "name=value". Example:"net.ipv4.ping_group_range=0 1000".
144 default_ulimits=[]
147 A list of ulimits to be set in containers by default, specified as
150 "name=soft-limit:hard-limit". Example: "nofile=1024:2048".
151 dns_options=[]
154 List of default DNS options to be added to /etc/resolv.conf inside of
157 the container.
158 dns_searches=[]
161 List of default DNS search domains to be added to /etc/resolv.conf
164 inside of the container.
165 dns_servers=[]
168 A list of dns servers to override the DNS configuration passed to the
171 container. The special value “none” can be specified to disable cre‐
172 ation of /etc/resolv.conf in the container.
173 env=["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
176 "TERM=xterm"]
177 Environment variable list for the container process, used for passing
180 environment variables to the container.
181 env_host=false
184 Pass all host environment variables into the container.
187 http_proxy=false
190 Default proxy environment variables will be passed into the container.
193 The environment variables passed in include: http_proxy, https_proxy,
194 ftp_proxy, no_proxy, and the upper case versions of these. The no_proxy
195 option is needed when host system uses a proxy but container should not
196 use proxy. Proxy environment variables specified for the container in
197 any other way will override the values passed from the host.
198 init=false
201 Run an init inside the container that forwards signals and reaps pro‐
204 cesses.
205 init_path="/usr/libexec/podman/catatonit"
208 Path to the container-init binary, which forwards signals and reaps
211 processes within containers. Note that the container-init binary will
212 only be used when the --init for podman-create and podman-run is set.
213 ipcns="private"
216 Default way to to create a IPC namespace for the container. Options
219 are:
220 private Create private IPC Namespace for the container.
221 host Share host IPC Namespace with the container.
222 label=true
225 Indicates whether the container engines use MAC(SELinux) container sep‐
228 aration via via labeling. Flag is ignored on disabled systems.
229 log_driver="k8s-file"
232 Logging driver for the container. Available options: k8s-file and jour‐
235 nald.
236 log_size_max=-1
239 Maximum size allowed for the container's log file. Negative numbers
242 indicate that no size limit is imposed. If it is positive, it must be
243 >= 8192 to match/exceed conmon's read buffer. The file is truncated and
244 re-opened so the limit is never exceeded.
245 netns="private"
248 Default way to to create a NET namespace for the container. Options
251 are:
252 private Create private NET Namespace for the container.
253 host Share host NET Namespace with the container.
254 none Containers do not use the network.
255 no_hosts=false
258 Create /etc/hosts for the container. By default, container engines
261 manage /etc/hosts, automatically adding the container's own IP
262 address.
263 pids_limit=1024
266 Maximum number of processes allowed in a container. 0 indicates that no
269 limit is imposed.
270 pidns="private"
273 Default way to to create a PID namespace for the container. Options
276 are:
277 private Create private PID Namespace for the container.
278 host Share host PID Namespace with the container.
279 seccomp_profile="/usr/share/containers/seccomp.json"
282 Path to the seccomp.json profile which is used as the default seccomp
285 profile for the runtime.
286 shm_size="65536k"
289 Size of /dev/shm. The format is <number><unit>. number must be greater
292 than 0. Unit is optional and can be: b (bytes), k (kilobytes),
293 m(megabytes), or g (gigabytes). If you omit the unit, the system uses
294 bytes. If you omit the size entirely, the system uses 65536k.
295 tz=""
298 Set timezone in container. Takes IANA timezones as well as local, which
301 sets the timezone in the container to match the host machine. If not
302 set, then containers will run with the time zone specified in the
303 image. Examples:
304 tz="local"
305 tz="America/New_York"
306 umask="0022"
309 Sets umask inside the container.
312 utsns="private"
315 Default way to to create a UTS namespace for the container. Options
318 are:
319 private Create private UTS Namespace for the container.
320 host Share host UTS Namespace with the container.
321 userns="host"
324 Default way to to create a USER namespace for the container. Options
327 are:
328 private Create private USER Namespace for the container.
329 host Share host USER Namespace with the container.
330 userns_size=65536
333 Number of UIDs to allocate for the automatic container creation. UIDs
336 are allocated from the “container” UIDs listed in /etc/subuid
337 /etc/subgid.
338
341 The network table contains settings pertaining to the management of CNI
342 plugins.
343 cni_plugin_dirs=["/opt/cni/bin/",]
346 List of paths to directories where CNI plugin binaries are located.
349 default_network="podman"
352 The network name of the default CNI network to attach pods to.
355 network_config_dir="/etc/cni/net.d/"
358 Path to the directory where CNI configuration files are located.
361
364 The engine table contains configuration options used to set up con‐
365 tainer engines such as Podman and Buildah.
366 cgroup_check=false
369 CgroupCheck indicates the configuration has been rewritten after an
372 upgrade to Fedora 31 to change the default OCI runtime for cgroupsv2.
373 cgroup_manager="systemd"
376 The cgroup management implementation used for the runtime. Supports
379 cgroupfs and systemd.
380 conmon_env_vars=[]
383 Environment variables to pass into Conmon.
386 conmon_path=[]
389 Paths to search for the conmon container manager binary. If the paths
392 are empty or no valid path was found, then the $PATH environment vari‐
393 able will be used as the fallback.
394 The default list is:
397 conmon_path=[
400 "/usr/libexec/podman/conmon",
401 "/usr/local/libexec/podman/conmon",
402 "/usr/local/lib/podman/conmon",
403 "/usr/bin/conmon",
404 "/usr/sbin/conmon",
405 "/usr/local/bin/conmon",
406 "/usr/local/sbin/conmon",
407 "/run/current-system/sw/bin/conmon",
408 ]
409 detach_keys="ctrl-p,ctrl-q"
413 Keys sequence used for detaching a container. Specify the keys
416 sequence used to detach a container. Format is a single character
417 [a-Z] or a comma separated sequence of ctrl-<value>, where <value> is
418 one of: a-z, @, ^, [, \, ], ^ or _
419 enable_port_reservation=true
422 Determines whether the engine will reserve ports on the host when they
425 are forwarded to containers. When enabled, when ports are forwarded to
426 containers, they are held open by conmon as long as the container is
427 running, ensuring that they cannot be reused by other programs on the
428 host. However, this can cause significant memory usage if a container
429 has many ports forwarded to it. Disabling this can save memory.
430 env=[]
433 Environment variables to be used when running the container engine
436 (e.g., Podman, Buildah). For example "http_proxy=internal.proxy.com‐
437 pany.com". Note these environment variables will not be used within
438 the container. Set the env section under [containers] table, if you
439 want to set environment variables for the container.
440 events_logger="journald"
443 Default method to use when logging events. Valid values: file, jour‐
446 nald, and none.
447 hooks_dir=["/etc/containers/oci/hooks.d", ...]
450 Path to the OCI hooks directories for automatically executed hooks.
453 image_default_transport="docker://"
456 Default transport method for pulling and pushing images.
459 infra_command="/pause"
462 Command to run the infra container.
465 infra_image="k8s.gcr.io/pause:3.2"
468 Infra (pause) container image name for pod infra containers. When run‐
471 ning a pod, we start a pause process in a container to hold open the
472 namespaces associated with the pod. This container does nothing other
473 then sleep, reserving the pods resources for the lifetime of the pod.
474 lock_type="shm"
477 Specify the locking mechanism to use; valid values are "shm" and
480 "file". Change the default only if you are sure of what you are doing,
481 in general "file" is useful only on platforms where cgo is not avail‐
482 able for using the faster "shm" lock type. You may need to run "podman
483 system renumber" after you change the lock type.
484 multi_image_archive=false
487 Allows for creating archives (e.g., tarballs) with more than one image.
490 Some container engines, such as Podman, interpret additional arguments
491 as tags for one image and hence do not store more than one image. The
492 default behavior can be altered with this option.
493 namespace=""
496 Default engine namespace. If the engine is joined to a namespace, it
499 will see only containers and pods that were created in the same names‐
500 pace, and will create new containers and pods in that namespace. The
501 default namespace is "", which corresponds to no namespace. When no
502 namespace is set, all containers and pods are visible.
503 network_cmd_path=""
506 Path to the slirp4netns binary.
509 no_pivot_root=false
512 Whether to use chroot instead of pivot_root in the runtime.
515 num_locks=2048
518 Number of locks available for containers and pods. Each created con‐
521 tainer or pod consumes one lock. The default number available is 2048.
522 If this is changed, a lock renumbering must be performed, using the
523 podman system renumber command.
524 active_service=""
527 Name of destination for accessing the Podman service.
530 [service_destinations]
533 [service_destinations.{name}] uri="ssh://user@production.exam‐
536 ple.com/run/user/1001/podman/podman.sock"
537 Example URIs:
540 · rootless local - unix://run/user/1000/podman/podman.sock
543 · rootless remote - ssh://user@engineering.lab.com‐
545 pany.com/run/user/1000/podman/podman.sock
546 · rootfull local - unix://run/podman/podman.sock
548 · rootfull remote - ssh://root@10.10.1.136:22/run/podman/pod‐
550 man.sock
551 identity="~/.ssh/id_rsa
555 Path to file containing ssh identity key
558 pull_policy="always"|"missing"|"never"
561 Pull image before running or creating a container. The default is miss‐
564 ing.
565 · missing: attempt to pull the latest image from the registries
568 listed in registries.conf if a local image does not exist.
569 Raise an error if the image is not in any listed registry and
570 is not present locally.
571 · always: pull the image from the first registry it is found in
573 as listed in registries.conf. Raise an error if not found in
574 the registries, even if the image is present locally.
575 · never: do not pull the image from the registry, use only the
577 local version. Raise an error if the image is not present
578 locally.
579 runtime="crun"
583 Default OCI specific runtime in runtimes that will be used by default.
586 Must refer to a member of the runtimes table.
587 runtime_supports_json=["crun", "runc", "kata"]
590 The list of the OCI runtimes that support --format=json.
593 runtime_supports_nocgroups=["crun"]
596 The list of OCI runtimes that support running containers without
599 CGroups.
600 runtime_supports_kvm=["kata"]
603 The list of OCI runtimes that support running containers with KVM sepa‐
606 ration.
607 static_dir="/var/lib/containers/storage/libpod"
610 Directory for persistent libpod files (database, etc). By default this
613 will be configured relative to where containers/storage stores contain‐
614 ers.
615 stop_timeout=10
618 Number of seconds to wait for container to exit before sending kill
621 signal.
622 tmp_dir="/var/run/libpod"
625 The path to a temporary directory to store per-boot container. Must be
628 a tmpfs (wiped after reboot).
629 volume_path="/var/lib/containers/storage/volumes"
632 Directory where named volumes will be created in using the default vol‐
635 ume driver. By default this will be configured relative to where con‐
636 tainers/storage store containers. This convention is followed by the
637 default volume driver, but may not be by other drivers.
638
642 containers.conf
643 Distributions often provide a /usr/share/containers/containers.conf
646 file to define default container configuration. Administrators can
647 override fields in this file by creating /etc/containers/contain‐
648 ers.conf to specify their own configuration. Rootless users can further
649 override fields in the config by creating a config file stored in the
650 $HOME/.config/containers/containers.conf file.
651 If the CONTAINERS_CONF path environment variable is set, just this path
654 will be used. This is primarily used for testing.
655 Fields specified in the containers.conf file override the default
658 options, as well as options in previously read containers.conf files.
659 storage.conf
662 The /etc/containers/storage.conf file is the default storage configura‐
665 tion file. Rootless users can override fields in the storage config by
666 creating $HOME/.config/containers/storage.conf.
667 If the CONTAINERS_STORAGE_CONF path environment variable is set, this
670 path is used for the storage.conf file rather than the default. This
671 is primarily used for testing.
672
676 containers-storage.conf(5), containers-policy.json(5), containers-reg‐
677 istries.conf(5)
678configuration engine containers.conf(5)(Container)