1containers.conf(5)(Container) file containers.conf(5)(Container)
2
6 containers.conf - The container engine configuration file specifies de‐
7 fault configuration options and command-line flags for container en‐
8 gines.
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 en‐
50 coding of the configuration file. Every option is nested under its ta‐
51 ble. No bare options are used. The format of TOML can be simplified to:
52 [table1]
55 option = value
56 [table2]
58 option = value
59 [table3]
61 option = value
62 [table3.subtable1]
64 option = value
65
69 The containers table contains settings pertaining to the OCI runtime
70 that can configure and manage the OCI runtime.
71 annotations = [] List of annotations. Specified as "key=value" pairs to
74 be added to all containers.
75 Example: "run.oci.keep_original_groups=1"
78 apparmor_profile="container-default"
81 Used to change the name of the default AppArmor profile of container
84 engines. The default profile name is "container-default".
85 cgroups="enabled"
88 Determines whether the container will create CGroups. Options are:
91 enabled Enable cgroup support within container
92 disabled Disable cgroup support, will inherit cgroups from parent
93 no-conmon Do not create a cgroup dedicated to conmon.
94 cgroupns="private"
97 Default way to to create a cgroup namespace for the container. Options
100 are: private Create private Cgroup Namespace for the container. host
101 Share host Cgroup Namespace with the container.
102 default_capabilities=[]
105 List of default capabilities for containers.
108 The default list is:
111 default_capabilities = [
114 "AUDIT_WRITE",
115 "CHOWN",
116 "DAC_OVERRIDE",
117 "FOWNER",
118 "FSETID",
119 "KILL",
120 "MKNOD",
121 "NET_BIND_SERVICE",
122 "NET_RAW",
123 "SETGID",
124 "SETPCAP",
125 "SETUID",
126 "SYS_CHROOT",
127 ]
128 default_sysctls=[]
132 A list of sysctls to be set in containers by default, specified as
135 "name=value".
136 Example:"net.ipv4.ping_group_range=0 1000".
139 default_ulimits=[]
142 A list of ulimits to be set in containers by default, specified as
145 "name=soft-limit:hard-limit".
146 Example: "nofile=1024:2048".
149 devices=[]
152 List of devices. Specified as 'device-on-host:device-on-container:per‐
155 missions'.
156 Example: "/dev/sdc:/dev/xvdc:rwm".
159 dns_options=[]
162 List of default DNS options to be added to /etc/resolv.conf inside of
165 the container.
166 dns_searches=[]
169 List of default DNS search domains to be added to /etc/resolv.conf in‐
172 side of the container.
173 dns_servers=[]
176 A list of dns servers to override the DNS configuration passed to the
179 container. The special value “none” can be specified to disable cre‐
180 ation of /etc/resolv.conf in the container.
181 env=["PATH=/usr/local/sbin:/usr/lo‐
184 cal/bin:/usr/sbin:/usr/bin:/sbin:/bin", "TERM=xterm"]
185 Environment variable list for the container process, used for passing
188 environment variables to the container.
189 env_host=false
192 Pass all host environment variables into the container.
195 http_proxy=true
198 Default proxy environment variables will be passed into the container.
201 The environment variables passed in include: http_proxy, https_proxy,
202 ftp_proxy, no_proxy, and the upper case versions of these. The no_proxy
203 option is needed when host system uses a proxy but container should not
204 use proxy. Proxy environment variables specified for the container in
205 any other way will override the values passed from the host.
206 init=false
209 Run an init inside the container that forwards signals and reaps pro‐
212 cesses.
213 init_path="/usr/libexec/podman/catatonit"
216 Path to the container-init binary, which forwards signals and reaps
219 processes within containers. Note that the container-init binary will
220 only be used when the --init for podman-create and podman-run is set.
221 ipcns="private"
224 Default way to to create a IPC namespace for the container. Options
227 are:
228 private Create private IPC Namespace for the container.
229 host Share host IPC Namespace with the container.
230 keyring=true
233 Indicates whether the container engines create a kernel keyring for use
236 within the container.
237 label=true
240 Indicates whether the container engine uses MAC(SELinux) container sep‐
243 aration via labeling. This option is ignored on disabled systems.
244 log_driver="k8s-file"
247 Logging driver for the container. Available options: k8s-file and jour‐
250 nald.
251 log_size_max=-1
254 Maximum size allowed for the container's log file. Negative numbers in‐
257 dicate that no size limit is imposed. If it is positive, it must be >=
258 8192 to match/exceed conmon's read buffer. The file is truncated and
259 re-opened so the limit is never exceeded.
260 netns="private"
263 Default way to to create a NET namespace for the container. Options
266 are:
267 private Create private NET Namespace for the container.
268 host Share host NET Namespace with the container.
269 none Containers do not use the network.
270 no_hosts=false
273 Create /etc/hosts for the container. By default, container engines
276 manage /etc/hosts, automatically adding the container's own IP ad‐
277 dress.
278 pidns="private"
281 Default way to to create a PID namespace for the container. Options
284 are:
285 private Create private PID Namespace for the container.
286 host Share host PID Namespace with the container.
287 pids_limit=1024
290 Maximum number of processes allowed in a container. 0 indicates that no
293 limit is imposed.
294 rootless_networking="slirp4netns"
297 Set type of networking rootless containers should use. Valid options
300 are slirp4netns or cni.
301 seccomp_profile="/usr/share/containers/seccomp.json"
304 Path to the seccomp.json profile which is used as the default seccomp
307 profile for the runtime.
308 shm_size="65536k"
311 Size of /dev/shm. The format is <number><unit>. number must be greater
314 than 0. Unit is optional and can be: b (bytes), k (kilobytes),
315 m(megabytes), or g (gigabytes). If you omit the unit, the system uses
316 bytes. If you omit the size entirely, the system uses 65536k.
317 tz=""
320 Set timezone in container. Takes IANA timezones as well as local, which
323 sets the timezone in the container to match the host machine. If not
324 set, then containers will run with the time zone specified in the im‐
325 age.
326 Examples:
329 tz="local"
330 tz="America/New_York"
331 umask="0022"
334 Sets umask inside the container.
337 userns="host"
340 Default way to to create a USER namespace for the container. Options
343 are:
344 private Create private USER Namespace for the container.
345 host Share host USER Namespace with the container.
346 userns_size=65536
349 Number of UIDs to allocate for the automatic container creation. UIDs
352 are allocated from the “container” UIDs listed in /etc/subuid
353 /etc/subgid.
354 utsns="private"
357 Default way to to create a UTS namespace for the container. Options
360 are:
361 private Create private UTS Namespace for the container.
362 host Share host UTS Namespace with the container.
363
366 The network table contains settings pertaining to the management of CNI
367 plugins.
368 cni_plugin_dirs=["/opt/cni/bin/",]
371 List of paths to directories where CNI plugin binaries are located.
374 default_network="podman"
377 The network name of the default CNI network to attach pods to.
380 default_subnet="10.88.0.0/16"
383 The subnet to use for the default CNI network (named above in de‐
386 fault_network). If the default network does not exist, it will be au‐
387 tomatically created the first time a tool is run using this subnet.
388 network_config_dir="/etc/cni/net.d/"
391 Path to the directory where CNI configuration files are located.
394 volumes=[]
397 List of volumes. Specified as "directory-on-host:directory-in-con‐
400 tainer:options".
401 Example: "/db:/var/lib/db:ro".
404
407 The engine table contains configuration options used to set up con‐
408 tainer engines such as Podman and Buildah.
409 active_service=""
412 Name of destination for accessing the Podman service. See SERVICE DES‐
415 TINATION TABLE below.
416 cgroup_check=false
419 CgroupCheck indicates the configuration has been rewritten after an up‐
422 grade to Fedora 31 to change the default OCI runtime for cgroupsv2.
423 cgroup_manager="systemd"
426 The cgroup management implementation used for the runtime. Supports
429 cgroupfs and systemd.
430 conmon_env_vars=[]
433 Environment variables to pass into Conmon.
436 conmon_path=[]
439 Paths to search for the conmon container manager binary. If the paths
442 are empty or no valid path was found, then the $PATH environment vari‐
443 able will be used as the fallback.
444 The default list is:
447 conmon_path=[
450 "/usr/libexec/podman/conmon",
451 "/usr/local/libexec/podman/conmon",
452 "/usr/local/lib/podman/conmon",
453 "/usr/bin/conmon",
454 "/usr/sbin/conmon",
455 "/usr/local/bin/conmon",
456 "/usr/local/sbin/conmon",
457 "/run/current-system/sw/bin/conmon",
458 ]
459 detach_keys="ctrl-p,ctrl-q"
463 Keys sequence used for detaching a container. Specify the keys se‐
466 quence used to detach a container. Format is a single character [a-Z]
467 or a comma separated sequence of ctrl-<value>, where <value> is one of:
468 a-z, @, ^, [, \, ], ^ or _
469 enable_port_reservation=true
472 Determines whether the engine will reserve ports on the host when they
475 are forwarded to containers. When enabled, when ports are forwarded to
476 containers, they are held open by conmon as long as the container is
477 running, ensuring that they cannot be reused by other programs on the
478 host. However, this can cause significant memory usage if a container
479 has many ports forwarded to it. Disabling this can save memory.
480 env=[]
483 Environment variables to be used when running the container engine
486 (e.g., Podman, Buildah). For example "http_proxy=internal.proxy.com‐
487 pany.com". Note these environment variables will not be used within
488 the container. Set the env section under [containers] table, if you
489 want to set environment variables for the container.
490 events_logger="journald"
493 Default method to use when logging events. Valid values: file, jour‐
496 nald, and none.
497 hooks_dir=["/etc/containers/oci/hooks.d", ...]
500 Path to the OCI hooks directories for automatically executed hooks.
503 image_default_format="oci"|"v2s2"|"v2s1"
506 Manifest Type (oci, v2s2, or v2s1) to use when pulling, pushing, build‐
509 ing container images. By default images pulled and pushed match the
510 format of the source image. Building/committing defaults to OCI. Note:
511 image_build_format is deprecated.
512 image_default_transport="docker://"
515 Default transport method for pulling and pushing images.
518 image_parallel_copies=0
521 Maximum number of image layers to be copied (pulled/pushed) simultane‐
524 ously. Not setting this field will fall back to containers/image de‐
525 faults. (6)
526 infra_command="/pause"
529 Command to run the infra container.
532 infra_image="k8s.gcr.io/pause:3.4.1"
535 Infra (pause) container image name for pod infra containers. When run‐
538 ning a pod, we start a pause process in a container to hold open the
539 namespaces associated with the pod. This container does nothing other
540 then sleep, reserving the pods resources for the lifetime of the pod.
541 lock_type="shm"
544 Specify the locking mechanism to use; valid values are "shm" and
547 "file". Change the default only if you are sure of what you are doing,
548 in general "file" is useful only on platforms where cgo is not avail‐
549 able for using the faster "shm" lock type. You may need to run "podman
550 system renumber" after you change the lock type.
551 machine_enabled=false
554 Indicates if Podman is running inside a VM via Podman Machine. Podman
557 uses this value to do extra setup around networking from the container
558 inside the VM to to host.
559 multi_image_archive=false
562 Allows for creating archives (e.g., tarballs) with more than one image.
565 Some container engines, such as Podman, interpret additional arguments
566 as tags for one image and hence do not store more than one image. The
567 default behavior can be altered with this option.
568 namespace=""
571 Default engine namespace. If the engine is joined to a namespace, it
574 will see only containers and pods that were created in the same name‐
575 space, and will create new containers and pods in that namespace. The
576 default namespace is "", which corresponds to no namespace. When no
577 namespace is set, all containers and pods are visible.
578 network_cmd_path=""
581 Path to the slirp4netns binary.
584 network_cmd_options=[]
587 Default options to pass to the slirp4netns binary.
590 Example "allow_host_loopback=true"
593 no_pivot_root=false
596 Whether to use chroot instead of pivot_root in the runtime.
599 num_locks=2048
602 Number of locks available for containers and pods. Each created con‐
605 tainer or pod consumes one lock. The default number available is 2048.
606 If this is changed, a lock renumbering must be performed, using the
607 podman system renumber command.
608 pull_policy="always"|"missing"|"never"
611 Pull image before running or creating a container. The default is miss‐
614 ing.
615 • missing: attempt to pull the latest image from the registries
618 listed in registries.conf if a local image does not exist.
619 Raise an error if the image is not in any listed registry and
620 is not present locally.
621 • always: pull the image from the first registry it is found in
623 as listed in registries.conf. Raise an error if not found in
624 the registries, even if the image is present locally.
625 • never: do not pull the image from the registry, use only the
627 local version. Raise an error if the image is not present lo‐
628 cally.
629 remote = false Indicates whether the application should be running in
633 remote mode. This flag modifies the --remote option on container en‐
634 gines. Setting the flag to true will default podman --remote=true for
635 access to the remote Podman service.
636 runtime=""
639 Default OCI specific runtime in runtimes that will be used by default.
642 Must refer to a member of the runtimes table. Default runtime will be
643 searched for on the system using the priority: "crun", "runc", "kata".
644 runtime_supports_json=["crun", "runc", "kata", "runsc"]
647 The list of the OCI runtimes that support --format=json.
650 runtime_supports_nocgroups=["crun"]
653 The list of OCI runtimes that support running containers without
656 CGroups.
657 runtime_supports_kvm=["kata"]
660 The list of OCI runtimes that support running containers with KVM sepa‐
663 ration.
664 static_dir="/var/lib/containers/storage/libpod"
667 Directory for persistent libpod files (database, etc). By default this
670 will be configured relative to where containers/storage stores contain‐
671 ers.
672 stop_timeout=10
675 Number of seconds to wait for container to exit before sending kill
678 signal.
679 tmp_dir="/run/libpod"
682 The path to a temporary directory to store per-boot container. Must be
685 a tmpfs (wiped after reboot).
686
689 The service_destinations table contains configuration options used to
690 set up remote connections to the podman service for the podman API.
691 [service_destinations.{name}] URI to access the Podman service
694 uri="ssh://user@production.example.com/run/user/1001/podman/pod‐
695 man.sock"
696 Example URIs:
699 • rootless local - unix://run/user/1000/podman/podman.sock
702 • rootless remote - ssh://user@engineering.lab.com‐
704 pany.com/run/user/1000/podman/podman.sock
705 • rootfull local - unix://run/podman/podman.sock
707 • rootfull remote - ssh://root@10.10.1.136:22/run/podman/pod‐
709 man.sock
710 identity="~/.ssh/id_rsa
714 Path to file containing ssh identity key
717 volume_path="/var/lib/containers/storage/volumes"
720 Directory where named volumes will be created in using the default vol‐
723 ume driver. By default this will be configured relative to where con‐
724 tainers/storage store containers. This convention is followed by the
725 default volume driver, but may not be by other drivers.
726 [engine.volume_plugins]
729 A table of all the enabled volume plugins on the system. Volume plugins
732 can be used as the backend for Podman named volumes. Individual plugins
733 are specified below, as a map of the plugin name (what the plugin will
734 be called) to its path (filepath of the plugin's unix socket).
735
739 containers.conf
740 Distributions often provide a /usr/share/containers/containers.conf
743 file to define default container configuration. Administrators can
744 override fields in this file by creating /etc/containers/contain‐
745 ers.conf to specify their own configuration. Rootless users can further
746 override fields in the config by creating a config file stored in the
747 $HOME/.config/containers/containers.conf file.
748 If the CONTAINERS_CONF path environment variable is set, just this path
751 will be used. This is primarily used for testing.
752 Fields specified in the containers.conf file override the default op‐
755 tions, as well as options in previously read containers.conf files.
756 storage.conf
759 The /etc/containers/storage.conf file is the default storage configura‐
762 tion file. Rootless users can override fields in the storage config by
763 creating $HOME/.config/containers/storage.conf.
764 If the CONTAINERS_STORAGE_CONF path environment variable is set, this
767 path is used for the storage.conf file rather than the default. This
768 is primarily used for testing.
769
773 containers-storage.conf(5), containers-policy.json(5), containers-reg‐
774 istries.conf(5)
775configuration engine containers.conf(5)(Container)