1containers.conf(5) configuration containers.conf(5)
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
14 it exists and modify the defaults for running containers on the host.
15 containers.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, and /etc/containers/contain‐
21 ers.conf.d/.conf files if they exist. When running in rootless mode,
22 they also read $HOME/.config/containers/containers.conf and $HOME/.con‐
23 fig/containers/containers.conf.d/.conf files.
24 Fields specified in containers conf override the default options, as
27 well as options in previously read containers.conf files.
28 Config files in the .d directories, are added in alpha numeric sorted
31 order and must end in .conf.
32 Not all options are supported in all container engines.
35 Note container engines also use other configuration files for configur‐
38 ing the environment.
39 • storage.conf for configuration of container and images stor‐
42 age.
43 • registries.conf for definition of container registires to
45 search while pulling. container images.
46 • policy.conf for controlling which images can be pulled to the
48 system.
49
54 The TOML format ⟨https://github.com/toml-lang/toml⟩ is used as the en‐
55 coding of the configuration file. Every option is nested under its ta‐
56 ble. No bare options are used. The format of TOML can be simplified to:
57 [table1]
60 option = value
61 [table2]
63 option = value
64 [table3]
66 option = value
67 [table3.subtable1]
69 option = value
70
74 The containers table contains settings to configure and manage the OCI
75 runtime.
76 annotations = [] List of annotations. Specified as "key=value" pairs to
79 be added to all containers.
80 Example: "run.oci.keep_original_groups=1"
83 apparmor_profile="container-default"
86 Used to change the name of the default AppArmor profile of container
89 engines. The default profile name is "container-default".
90 cgroups="enabled"
93 Determines whether the container will create CGroups. Options are:
96 enabled Enable cgroup support within container
97 disabled Disable cgroup support, will inherit cgroups from parent
98 no-conmon Do not create a cgroup dedicated to conmon.
99 cgroupns="private"
102 Default way to to create a cgroup namespace for the container. Options
105 are: private Create private Cgroup Namespace for the container. host
106 Share host Cgroup Namespace with the container.
107 default_capabilities=[]
110 List of default capabilities for containers.
113 The default list is:
116 default_capabilities = [
119 "AUDIT_WRITE",
120 "CHOWN",
121 "DAC_OVERRIDE",
122 "FOWNER",
123 "FSETID",
124 "KILL",
125 "MKNOD",
126 "NET_BIND_SERVICE",
127 "NET_RAW",
128 "SETGID",
129 "SETPCAP",
130 "SETUID",
131 "SYS_CHROOT",
132 ]
133 default_sysctls=[]
137 A list of sysctls to be set in containers by default, specified as
140 "name=value".
141 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".
151 Example: "nofile=1024:2048".
154 devices=[]
157 List of devices. Specified as 'device-on-host:device-on-container:per‐
160 missions'.
161 Example: "/dev/sdc:/dev/xvdc:rwm".
164 dns_options=[]
167 List of default DNS options to be added to /etc/resolv.conf inside of
170 the container.
171 dns_searches=[]
174 List of default DNS search domains to be added to /etc/resolv.conf in‐
177 side of the container.
178 dns_servers=[]
181 A list of dns servers to override the DNS configuration passed to the
184 container. The special value “none” can be specified to disable cre‐
185 ation of /etc/resolv.conf in the container.
186 env=["PATH=/usr/local/sbin:/usr/lo‐
189 cal/bin:/usr/sbin:/usr/bin:/sbin:/bin", "TERM=xterm"]
190 Environment variable list for the container process, used for passing
193 environment variables to the container.
194 env_host=false
197 Pass all host environment variables into the container.
200 http_proxy=true
203 Default proxy environment variables will be passed into the container.
206 The environment variables passed in include: http_proxy, https_proxy,
207 ftp_proxy, no_proxy, and the upper case versions of these. The no_proxy
208 option is needed when host system uses a proxy but container should not
209 use proxy. Proxy environment variables specified for the container in
210 any other way will override the values passed from the host.
211 init=false
214 Run an init inside the container that forwards signals and reaps pro‐
217 cesses.
218 init_path="/usr/libexec/podman/catatonit"
221 Path to the container-init binary, which forwards signals and reaps
224 processes within containers. Note that the container-init binary will
225 only be used when the --init for podman-create and podman-run is set.
226 ipcns="private"
229 Default way to to create a IPC namespace for the container. Options
232 are:
233 private Create private IPC Namespace for the container.
234 host Share host IPC Namespace with the container.
235 keyring=true
238 Indicates whether the container engines create a kernel keyring for use
241 within the container.
242 label=true
245 Indicates whether the container engine uses MAC(SELinux) container sep‐
248 aration via labeling. This option is ignored on disabled systems.
249 log_driver="k8s-file"
252 Logging driver for the container. Available options: k8s-file and jour‐
255 nald.
256 log_size_max=-1
259 Maximum size allowed for the container's log file. Negative numbers in‐
262 dicate that no size limit is imposed. If it is positive, it must be >=
263 8192 to match/exceed conmon's read buffer. The file is truncated and
264 re-opened so the limit is never exceeded.
265 log_tag=""
268 Default format tag for container log messages. This is useful for cre‐
271 ating a specific tag for container log messages. Container log messages
272 default to using the truncated container ID as a tag.
273 netns="private"
276 Default way to to create a NET namespace for the container. Options
279 are:
280 private Create private NET Namespace for the container.
281 host Share host NET Namespace with the container.
282 none Containers do not use the network.
283 no_hosts=false
286 Create /etc/hosts for the container. By default, container engines
289 manage /etc/hosts, automatically adding the container's own IP ad‐
290 dress.
291 pidns="private"
294 Default way to to create a PID namespace for the container. Options
297 are:
298 private Create private PID Namespace for the container.
299 host Share host PID Namespace with the container.
300 pids_limit=1024
303 Maximum number of processes allowed in a container. 0 indicates that no
306 limit is imposed.
307 prepare_volume_on_create=false
310 Copy the content from the underlying image into the newly created vol‐
313 ume when the container is created instead of when it is started. If
314 false, the container engine will not copy the content until the con‐
315 tainer is started. Setting it to true may have negative performance im‐
316 plications.
317 rootless_networking="slirp4netns"
320 Set type of networking rootless containers should use. Valid options
323 are slirp4netns or cni.
324 seccomp_profile="/usr/share/containers/seccomp.json"
327 Path to the seccomp.json profile which is used as the default seccomp
330 profile for the runtime.
331 shm_size="65536k"
334 Size of /dev/shm. The format is <number><unit>. number must be greater
337 than 0. Unit is optional and can be: b (bytes), k (kilobytes),
338 m(megabytes), or g (gigabytes). If you omit the unit, the system uses
339 bytes. If you omit the size entirely, the system uses 65536k.
340 tz=""
343 Set timezone in container. Takes IANA timezones as well as local, which
346 sets the timezone in the container to match the host machine. If not
347 set, then containers will run with the time zone specified in the im‐
348 age.
349 Examples:
352 tz="local"
353 tz="America/New_York"
354 umask="0022"
357 Sets umask inside the container.
360 userns="host"
363 Default way to to create a USER namespace for the container. Options
366 are:
367 private Create private USER Namespace for the container.
368 host Share host USER Namespace with the container.
369 userns_size=65536
372 Number of UIDs to allocate for the automatic container creation. UIDs
375 are allocated from the “container” UIDs listed in /etc/subuid &
376 /etc/subgid.
377 utsns="private"
380 Default way to to create a UTS namespace for the container. Options
383 are:
384 private Create private UTS Namespace for the container.
385 host Share host UTS Namespace with the container.
386
389 The network table contains settings pertaining to the management of CNI
390 plugins.
391 cni_plugin_dirs=[]
394 List of paths to directories where CNI plugin binaries are located.
397 The default list is:
400 cni_plugin_dirs = [
403 "/usr/local/libexec/cni",
404 "/usr/libexec/cni",
405 "/usr/local/lib/cni",
406 "/usr/lib/cni",
407 "/opt/cni/bin",
408 ]
409 default_network="podman"
413 The network name of the default CNI network to attach pods to.
416 default_subnet="10.88.0.0/16"
419 The subnet to use for the default CNI network (named above in de‐
422 fault_network). If the default network does not exist, it will be au‐
423 tomatically created the first time a tool is run using this subnet.
424 network_config_dir="/etc/cni/net.d/"
427 Path to the directory where CNI configuration files are located.
430 volumes=[]
433 List of volumes. Specified as "directory-on-host:directory-in-con‐
436 tainer:options".
437 Example: "/db:/var/lib/db:ro".
440
443 The engine table contains configuration options used to set up con‐
444 tainer engines such as Podman and Buildah.
445 active_service=""
448 Name of destination for accessing the Podman service. See SERVICE DES‐
451 TINATION TABLE below.
452 cgroup_manager="systemd"
455 The cgroup management implementation used for the runtime. Supports
458 cgroupfs and systemd.
459 conmon_env_vars=[]
462 Environment variables to pass into Conmon.
465 conmon_path=[]
468 Paths to search for the conmon container manager binary. If the paths
471 are empty or no valid path was found, then the $PATH environment vari‐
472 able will be used as the fallback.
473 The default list is:
476 conmon_path=[
479 "/usr/libexec/podman/conmon",
480 "/usr/local/libexec/podman/conmon",
481 "/usr/local/lib/podman/conmon",
482 "/usr/bin/conmon",
483 "/usr/sbin/conmon",
484 "/usr/local/bin/conmon",
485 "/usr/local/sbin/conmon",
486 "/run/current-system/sw/bin/conmon",
487 ]
488 detach_keys="ctrl-p,ctrl-q"
492 Keys sequence used for detaching a container. Specify the keys se‐
495 quence used to detach a container. Format is a single character [a-Z]
496 or a comma separated sequence of ctrl-<value>, where <value> is one of:
497 a-z, @, ^, [, \, ], ^ or _
498 enable_port_reservation=true
501 Determines whether the engine will reserve ports on the host when they
504 are forwarded to containers. When enabled, when ports are forwarded to
505 containers, they are held open by conmon as long as the container is
506 running, ensuring that they cannot be reused by other programs on the
507 host. However, this can cause significant memory usage if a container
508 has many ports forwarded to it. Disabling this can save memory.
509 env=[]
512 Environment variables to be used when running the container engine
515 (e.g., Podman, Buildah). For example "http_proxy=internal.proxy.com‐
516 pany.com". Note these environment variables will not be used within
517 the container. Set the env section under [containers] table, if you
518 want to set environment variables for the container.
519 events_logger="journald"
522 Default method to use when logging events. Valid values: file, jour‐
525 nald, and none.
526 helper_binaries_dir=["/usr/libexec/podman", ...]
529 A is a list of directories which are used to search for helper bina‐
532 ries.
533 The default paths on Linux are: - /usr/local/libexec/podman - /usr/lo‐
536 cal/lib/podman - /usr/libexec/podman - /usr/lib/podman
537 The default paths on macOS are: - /usr/local/opt/podman/libexec
540 - /opt/homebrew/bin - /opt/homebrew/opt/podman/libexec - /usr/lo‐
541 cal/bin - /usr/local/libexec/podman - /usr/local/lib/podman
542 - /usr/libexec/podman - /usr/lib/podman
543 The default path on Windows is: - C:\Program Files\RedHat\Podman
546 hooks_dir=["/etc/containers/oci/hooks.d", ...]
549 Path to the OCI hooks directories for automatically executed hooks.
552 image_default_format="oci"|"v2s2"|"v2s1"
555 Manifest Type (oci, v2s2, or v2s1) to use when pulling, pushing, build‐
558 ing container images. By default images pulled and pushed match the
559 format of the source image. Building/committing defaults to OCI. Note:
560 image_build_format is deprecated.
561 image_default_transport="docker://"
564 Default transport method for pulling and pushing images.
567 image_parallel_copies=0
570 Maximum number of image layers to be copied (pulled/pushed) simultane‐
573 ously. Not setting this field will fall back to containers/image de‐
574 faults. (6)
575 infra_command="/pause"
578 Command to run the infra container.
581 infra_image="k8s.gcr.io/pause:3.4.1"
584 Infra (pause) container image name for pod infra containers. When run‐
587 ning a pod, we start a pause process in a container to hold open the
588 namespaces associated with the pod. This container does nothing other
589 then sleep, reserving the pods resources for the lifetime of the pod.
590 lock_type="shm"
593 Specify the locking mechanism to use; valid values are "shm" and
596 "file". Change the default only if you are sure of what you are doing,
597 in general "file" is useful only on platforms where cgo is not avail‐
598 able for using the faster "shm" lock type. You may need to run "podman
599 system renumber" after you change the lock type.
600 machine_enabled=false
603 Indicates if Podman is running inside a VM via Podman Machine. Podman
606 uses this value to do extra setup around networking from the container
607 inside the VM to to host.
608 multi_image_archive=false
611 Allows for creating archives (e.g., tarballs) with more than one image.
614 Some container engines, such as Podman, interpret additional arguments
615 as tags for one image and hence do not store more than one image. The
616 default behavior can be altered with this option.
617 namespace=""
620 Default engine namespace. If the engine is joined to a namespace, it
623 will see only containers and pods that were created in the same name‐
624 space, and will create new containers and pods in that namespace. The
625 default namespace is "", which corresponds to no namespace. When no
626 namespace is set, all containers and pods are visible.
627 network_cmd_path=""
630 Path to the slirp4netns binary.
633 network_cmd_options=["enable_ipv6=true",]
636 Default options to pass to the slirp4netns binary.
639 Valid options values are:
642 • allow_host_loopback=true|false: Allow the slirp4netns to reach
645 the host loopback IP (10.0.2.2, which is added to /etc/hosts
646 as host.containers.internal for your convenience). Default is
647 false.
648 • mtu=MTU: Specify the MTU to use for this network. (Default is
650 65520).
651 • cidr=CIDR: Specify ip range to use for this network. (Default
653 is 10.0.2.0/24).
654 • enable_ipv6=true|false: Enable IPv6. Default is false. (Re‐
656 quired for outbound_addr6).
657 • outbound_addr=INTERFACE: Specify the outbound interface slirp
659 should bind to (ipv4 traffic only).
660 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
662 should bind to.
663 • outbound_addr6=INTERFACE: Specify the outbound interface slirp
665 should bind to (ipv6 traffic only).
666 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
668 should bind to.
669 • port_handler=rootlesskit: Use rootlesskit for port forwarding.
671 Default. Note: Rootlesskit changes the source IP address of
672 incoming packets to a IP address in the container network
673 namespace, usually 10.0.2.100. If your application requires
674 the real source IP address, e.g. web server logs, use the
675 slirp4netns port handler. The rootlesskit port handler is also
676 used for rootless containers when connected to user-defined
677 networks.
678 • port_handler=slirp4netns: Use the slirp4netns port forwarding,
680 it is slower than rootlesskit but preserves the correct source
681 IP address. This port handler cannot be used for user-defined
682 networks.
683 no_pivot_root=false
687 Whether to use chroot instead of pivot_root in the runtime.
690 num_locks=2048
693 Number of locks available for containers and pods. Each created con‐
696 tainer or pod consumes one lock. The default number available is 2048.
697 If this is changed, a lock renumbering must be performed, using the
698 podman system renumber command.
699 pull_policy="always"|"missing"|"never"
702 Pull image before running or creating a container. The default is miss‐
705 ing.
706 • missing: attempt to pull the latest image from the registries
709 listed in registries.conf if a local image does not exist.
710 Raise an error if the image is not in any listed registry and
711 is not present locally.
712 • always: pull the image from the first registry it is found in
714 as listed in registries.conf. Raise an error if not found in
715 the registries, even if the image is present locally.
716 • never: do not pull the image from the registry, use only the
718 local version. Raise an error if the image is not present lo‐
719 cally.
720 remote = false Indicates whether the application should be running in
724 remote mode. This flag modifies the --remote option on container en‐
725 gines. Setting the flag to true will default podman --remote=true for
726 access to the remote Podman service.
727 runtime=""
730 Default OCI specific runtime in runtimes that will be used by default.
733 Must refer to a member of the runtimes table. Default runtime will be
734 searched for on the system using the priority: "crun", "runc", "kata".
735 runtime_supports_json=["crun", "runc", "kata", "runsc", "krun"]
738 The list of the OCI runtimes that support --format=json.
741 runtime_supports_kvm=["kata", "krun"]
744 The list of OCI runtimes that support running containers with KVM sepa‐
747 ration.
748 runtime_supports_nocgroups=["crun", "krun"]
751 The list of OCI runtimes that support running containers without
754 CGroups.
755 image_copy_tmp_dir="/var/tmp"
758 Default location for storing temporary container image content. Can be
761 overridden with the TMPDIR environment variable. If you specify "stor‐
762 age", then the location of the container/storage tmp directory will be
763 used. If set then it is the users responsibility to cleanup storage.
764 Configure tmpfiles.d(5) to cleanup storage.
765 service_timeout=5
768 Number of seconds to wait without a connection before the podman sys‐
771 tem service times out and exits
772 static_dir="/var/lib/containers/storage/libpod"
775 Directory for persistent libpod files (database, etc). By default this
778 will be configured relative to where containers/storage stores contain‐
779 ers.
780 stop_timeout=10
783 Number of seconds to wait for container to exit before sending kill
786 signal.
787 tmp_dir="/run/libpod"
790 The path to a temporary directory to store per-boot container. Must be
793 a tmpfs (wiped after reboot).
794 volume_path="/var/lib/containers/storage/volumes"
797 Directory where named volumes will be created in using the default vol‐
800 ume driver. By default this will be configured relative to where con‐
801 tainers/storage store containers. This convention is followed by the
802 default volume driver, but may not be by other drivers.
803 chown_copied_files=true
806 Determines whether file copied into a container will have changed own‐
809 ership to the primary uid/gid of the container.
810
813 The service_destinations table contains configuration options used to
814 set up remote connections to the podman service for the podman API.
815 [service_destinations.{name}] URI to access the Podman service
818 uri="ssh://user@production.example.com/run/user/1001/podman/pod‐
819 man.sock"
820 Example URIs:
823 • rootless local - unix://run/user/1000/podman/podman.sock
826 • rootless remote - ssh://user@engineering.lab.com‐
828 pany.com/run/user/1000/podman/podman.sock
829 • rootfull local - unix://run/podman/podman.sock
831 • rootfull remote - ssh://root@10.10.1.136:22/run/podman/pod‐
833 man.sock
834 identity="~/.ssh/id_rsa
838 Path to file containing ssh identity key
841 [engine.volume_plugins]
844 A table of all the enabled volume plugins on the system. Volume plugins
847 can be used as the backend for Podman named volumes. Individual plugins
848 are specified below, as a map of the plugin name (what the plugin will
849 be called) to its path (filepath of the plugin's unix socket).
850
853 The secret table contains settings for the configuration of the secret
854 subsystem.
855 driver=file
858 Name of the secret driver to be used. Currently valid values are:
861 * file
862 * pass
863 [secrets.opts]
866 The driver specific options object.
869
872 The machine table contains configurations for podman machine VMs
873 cpus=1 Number of CPU's a machine is created with.
876 disk_size=10
879 The size of the disk in GB created when init-ing a podman-machine VM
882 image="testing"
885 Default image used when creating a new VM using podman machine init.
888 Options: testing, stable, next, or a custom path or download URL to an
889 image
890 memory=2048
893 Memory in MB a machine is created with.
896
900 containers.conf
901 Distributions often provide a /usr/share/containers/containers.conf
904 file to define default container configuration. Administrators can
905 override fields in this file by creating /etc/containers/contain‐
906 ers.conf to specify their own configuration. Rootless users can further
907 override fields in the config by creating a config file stored in the
908 $HOME/.config/containers/containers.conf file.
909 If the CONTAINERS_CONF path environment variable is set, just this path
912 will be used. This is primarily used for testing.
913 Fields specified in the containers.conf file override the default op‐
916 tions, as well as options in previously read containers.conf files.
917 storage.conf
920 The /etc/containers/storage.conf file is the default storage configura‐
923 tion file. Rootless users can override fields in the storage config by
924 creating $HOME/.config/containers/storage.conf.
925 If the CONTAINERS_STORAGE_CONF path environment variable is set, this
928 path is used for the storage.conf file rather than the default. This
929 is primarily used for testing.
930
934 containers-storage.conf(5), containers-policy.json(5), containers-reg‐
935 istries.conf(5), tmpfiles.d(5)
936engine Container containers.conf(5)