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="shareable"
229 Default way to to create a IPC namespace for the container. Options
232 are:
233 host Share host IPC Namespace with the container.
234 none Create shareable IPC Namespace for the container without a
235 private /dev/shm.
236 private Create private IPC Namespace for the container, other con‐
237 tainers are not allowed to share it.
238 shareable Create shareable IPC Namespace for the container.
239 keyring=true
242 Indicates whether the container engines create a kernel keyring for use
245 within the container.
246 label=true
249 Indicates whether the container engine uses MAC(SELinux) container sep‐
252 aration via labeling. This option is ignored on disabled systems.
253 log_driver="k8s-file"
256 Logging driver for the container. Available options: k8s-file and jour‐
259 nald.
260 log_size_max=-1
263 Maximum size allowed for the container's log file. Negative numbers in‐
266 dicate that no size limit is imposed. If it is positive, it must be >=
267 8192 to match/exceed conmon's read buffer. The file is truncated and
268 re-opened so the limit is never exceeded.
269 log_tag=""
272 Default format tag for container log messages. This is useful for cre‐
275 ating a specific tag for container log messages. Container log messages
276 default to using the truncated container ID as a tag.
277 netns="private"
280 Default way to to create a NET namespace for the container. Options
283 are:
284 private Create private NET Namespace for the container.
285 host Share host NET Namespace with the container.
286 none Containers do not use the network.
287 no_hosts=false
290 Create /etc/hosts for the container. By default, container engines man‐
293 age /etc/hosts, automatically adding the container's own IP ad‐
294 dress.
295 pidns="private"
298 Default way to to create a PID namespace for the container. Options
301 are:
302 private Create private PID Namespace for the container.
303 host Share host PID Namespace with the container.
304 pids_limit=1024
307 Maximum number of processes allowed in a container. 0 indicates that no
310 limit is imposed.
311 prepare_volume_on_create=false
314 Copy the content from the underlying image into the newly created vol‐
317 ume when the container is created instead of when it is started. If
318 false, the container engine will not copy the content until the con‐
319 tainer is started. Setting it to true may have negative performance im‐
320 plications.
321 seccomp_profile="/usr/share/containers/seccomp.json"
324 Path to the seccomp.json profile which is used as the default seccomp
327 profile for the runtime.
328 shm_size="65536k"
331 Size of /dev/shm. The format is <number><unit>. number must be greater
334 than 0. Unit is optional and can be: b (bytes), k (kilobytes),
335 m(megabytes), or g (gigabytes). If you omit the unit, the system uses
336 bytes. If you omit the size entirely, the system uses 65536k.
337 tz=""
340 Set timezone in container. Takes IANA timezones as well as local, which
343 sets the timezone in the container to match the host machine. If not
344 set, then containers will run with the time zone specified in the im‐
345 age.
346 Examples:
349 tz="local"
350 tz="America/New_York"
351 umask="0022"
354 Sets umask inside the container.
357 userns="host"
360 Default way to to create a USER namespace for the container. Options
363 are:
364 private Create private USER Namespace for the container.
365 host Share host USER Namespace with the container.
366 userns_size=65536
369 Number of UIDs to allocate for the automatic container creation. UIDs
372 are allocated from the “container” UIDs listed in /etc/subuid &
373 /etc/subgid.
374 utsns="private"
377 Default way to to create a UTS namespace for the container. Options
380 are:
381 private Create private UTS Namespace for the container.
382 host Share host UTS Namespace with the container.
383 volumes=[]
386 List of volumes. Specified as "directory-on-host:directory-in-con‐
389 tainer:options".
390 Example: "/db:/var/lib/db:ro".
393
396 The network table contains settings pertaining to the management of CNI
397 plugins.
398 network_backend=""
401 Network backend determines what network driver will be used to set up
404 and tear down container networks. Valid values are "cni" and "ne‐
405 tavark". The default value is empty which means that it will automati‐
406 cally choose CNI or netavark. If there are already containers/images or
407 CNI networks preset it will choose CNI.
408 Before changing this value all containers must be stopped otherwise it
411 is likely that iptables rules and network interfaces might leak on the
412 host. A reboot will fix this.
413 cni_plugin_dirs=[]
416 List of paths to directories where CNI plugin binaries are located.
419 The default list is:
422 cni_plugin_dirs = [
425 "/usr/local/libexec/cni",
426 "/usr/libexec/cni",
427 "/usr/local/lib/cni",
428 "/usr/lib/cni",
429 "/opt/cni/bin",
430 ]
431 default_network="podman"
435 The network name of the default network to attach pods to.
438 default_subnet="10.88.0.0/16"
441 The subnet to use for the default network (named above in default_net‐
444 work). If the default network does not exist, it will be automatically
445 created the first time a tool is run using this subnet.
446 default_subnet_pools=[]
449 DefaultSubnetPools is a list of subnets and size which are used to al‐
452 locate subnets automatically for podman network create. It will iter‐
453 ate through the list and will pick the first free subnet with the given
454 size. This is only used for ipv4 subnets, ipv6 subnets are always as‐
455 signed randomly.
456 The default list is (10.89.0.0-10.255.255.0/24):
459 default_subnet_pools = [
462 {"base" = "10.89.0.0/16", "size" = 24},
463 {"base" = "10.90.0.0/15", "size" = 24},
464 {"base" = "10.92.0.0/14", "size" = 24},
465 {"base" = "10.96.0.0/11", "size" = 24},
466 {"base" = "10.128.0.0/9", "size" = 24},
467 ]
468 network_config_dir="/etc/cni/net.d/"
472 Path to the directory where network configuration files are located.
475 For the CNI backend the default is "/etc/cni/net.d" as root and
476 "$HOME/.config/cni/net.d" as rootless. For the netavark backend
477 "/etc/containers/networks" is used as root and "$graphroot/networks" as
478 rootless.
479
482 The engine table contains configuration options used to set up con‐
483 tainer engines such as Podman and Buildah.
484 active_service=""
487 Name of destination for accessing the Podman service. See SERVICE DES‐
490 TINATION TABLE below.
491 cgroup_manager="systemd"
494 The cgroup management implementation used for the runtime. Supports
497 cgroupfs and systemd.
498 conmon_env_vars=[]
501 Environment variables to pass into Conmon.
504 conmon_path=[]
507 Paths to search for the conmon container manager binary. If the paths
510 are empty or no valid path was found, then the $PATH environment vari‐
511 able will be used as the fallback.
512 The default list is:
515 conmon_path=[
518 "/usr/libexec/podman/conmon",
519 "/usr/local/libexec/podman/conmon",
520 "/usr/local/lib/podman/conmon",
521 "/usr/bin/conmon",
522 "/usr/sbin/conmon",
523 "/usr/local/bin/conmon",
524 "/usr/local/sbin/conmon",
525 "/run/current-system/sw/bin/conmon",
526 ]
527 detach_keys="ctrl-p,ctrl-q"
531 Keys sequence used for detaching a container. Specify the keys se‐
534 quence used to detach a container. Format is a single character [a-Z]
535 or a comma separated sequence of ctrl-<value>, where <value> is one of:
536 a-z, @, ^, [, \, ], ^ or _
537 enable_port_reservation=true
540 Determines whether the engine will reserve ports on the host when they
543 are forwarded to containers. When enabled, when ports are forwarded to
544 containers, they are held open by conmon as long as the container is
545 running, ensuring that they cannot be reused by other programs on the
546 host. However, this can cause significant memory usage if a container
547 has many ports forwarded to it. Disabling this can save memory.
548 env=[]
551 Environment variables to be used when running the container engine
554 (e.g., Podman, Buildah). For example "http_proxy=internal.proxy.com‐
555 pany.com". Note these environment variables will not be used within
556 the container. Set the env section under [containers] table, if you
557 want to set environment variables for the container.
558 events_logfile_path=""
561 Define where event logs will be stored, when events_logger is "file".
564 events_logfile_max_size=0
567 Sets the maximum size for events_logfile_path in bytes. When the limit
570 is exceeded, the logfile will be rotated and the old one will be
571 deleted. If the maximumn size is set to 0, then no limit will be ap‐
572 plied, and the logfile will not be rotated.
573 events_logger="journald"
576 Default method to use when logging events. Valid values: file, jour‐
579 nald, and none.
580 helper_binaries_dir=["/usr/libexec/podman", ...]
583 A is a list of directories which are used to search for helper bina‐
586 ries.
587 The default paths on Linux are: - /usr/local/libexec/podman - /usr/lo‐
590 cal/lib/podman - /usr/libexec/podman - /usr/lib/podman
591 The default paths on macOS are: - /usr/local/opt/podman/libexec
594 - /opt/homebrew/bin - /opt/homebrew/opt/podman/libexec - /usr/lo‐
595 cal/bin - /usr/local/libexec/podman - /usr/local/lib/podman
596 - /usr/libexec/podman - /usr/lib/podman
597 The default path on Windows is: - C:\Program Files\RedHat\Podman
600 hooks_dir=["/etc/containers/oci/hooks.d", ...]
603 Path to the OCI hooks directories for automatically executed hooks.
606 image_default_format="oci"|"v2s2"|"v2s1"
609 Manifest Type (oci, v2s2, or v2s1) to use when pulling, pushing, build‐
612 ing container images. By default images pulled and pushed match the
613 format of the source image. Building/committing defaults to OCI. Note:
614 image_build_format is deprecated.
615 image_default_transport="docker://"
618 Default transport method for pulling and pushing images.
621 image_parallel_copies=0
624 Maximum number of image layers to be copied (pulled/pushed) simultane‐
627 ously. Not setting this field will fall back to containers/image de‐
628 faults. (6)
629 infra_command="/pause"
632 Infra (pause) container image command for pod infra containers. When
635 running a pod, we start a /pause process in a container to hold open
636 the namespaces associated with the pod. This container does nothing
637 other then sleep, reserving the pods resources for the lifetime of the
638 pod.
639 infra_image=""
642 Infra (pause) container image for pod infra containers. When running a
645 pod, we start a pause process in a container to hold open the name‐
646 spaces associated with the pod. This container does nothing other then
647 sleep, reserving the pods resources for the lifetime of the pod. By de‐
648 fault container engines run a builtin container using the pause exe‐
649 cutable. If you want override specify an image to pull.
650 lock_type="shm"
653 Specify the locking mechanism to use; valid values are "shm" and
656 "file". Change the default only if you are sure of what you are doing,
657 in general "file" is useful only on platforms where cgo is not avail‐
658 able for using the faster "shm" lock type. You may need to run "podman
659 system renumber" after you change the lock type.
660 machine_enabled=false
663 Indicates if Podman is running inside a VM via Podman Machine. Podman
666 uses this value to do extra setup around networking from the container
667 inside the VM to to host.
668 multi_image_archive=false
671 Allows for creating archives (e.g., tarballs) with more than one image.
674 Some container engines, such as Podman, interpret additional arguments
675 as tags for one image and hence do not store more than one image. The
676 default behavior can be altered with this option.
677 namespace=""
680 Default engine namespace. If the engine is joined to a namespace, it
683 will see only containers and pods that were created in the same name‐
684 space, and will create new containers and pods in that namespace. The
685 default namespace is "", which corresponds to no namespace. When no
686 namespace is set, all containers and pods are visible.
687 network_cmd_path=""
690 Path to the slirp4netns binary.
693 network_cmd_options=["enable_ipv6=true",]
696 Default options to pass to the slirp4netns binary.
699 Valid options values are:
702 • allow_host_loopback=true|false: Allow the slirp4netns to reach
705 the host loopback IP (10.0.2.2, which is added to /etc/hosts
706 as host.containers.internal for your convenience). Default is
707 false.
708 • mtu=MTU: Specify the MTU to use for this network. (Default is
710 65520).
711 • cidr=CIDR: Specify ip range to use for this network. (Default
713 is 10.0.2.0/24).
714 • enable_ipv6=true|false: Enable IPv6. Default is false. (Re‐
716 quired for outbound_addr6).
717 • outbound_addr=INTERFACE: Specify the outbound interface slirp
719 should bind to (ipv4 traffic only).
720 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
722 should bind to.
723 • outbound_addr6=INTERFACE: Specify the outbound interface slirp
725 should bind to (ipv6 traffic only).
726 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
728 should bind to.
729 • port_handler=rootlesskit: Use rootlesskit for port forwarding.
731 Default. Note: Rootlesskit changes the source IP address of
732 incoming packets to a IP address in the container network
733 namespace, usually 10.0.2.100. If your application requires
734 the real source IP address, e.g. web server logs, use the
735 slirp4netns port handler. The rootlesskit port handler is also
736 used for rootless containers when connected to user-defined
737 networks.
738 • port_handler=slirp4netns: Use the slirp4netns port forwarding,
740 it is slower than rootlesskit but preserves the correct source
741 IP address. This port handler cannot be used for user-defined
742 networks.
743 no_pivot_root=false
747 Whether to use chroot instead of pivot_root in the runtime.
750 num_locks=2048
753 Number of locks available for containers and pods. Each created con‐
756 tainer or pod consumes one lock. The default number available is 2048.
757 If this is changed, a lock renumbering must be performed, using the
758 podman system renumber command.
759 pull_policy="always"|"missing"|"never"
762 Pull image before running or creating a container. The default is miss‐
765 ing.
766 • missing: attempt to pull the latest image from the registries
769 listed in registries.conf if a local image does not exist.
770 Raise an error if the image is not in any listed registry and
771 is not present locally.
772 • always: pull the image from the first registry it is found in
774 as listed in registries.conf. Raise an error if not found in
775 the registries, even if the image is present locally.
776 • never: do not pull the image from the registry, use only the
778 local version. Raise an error if the image is not present lo‐
779 cally.
780 remote = false Indicates whether the application should be running in
784 remote mode. This flag modifies the --remote option on container en‐
785 gines. Setting the flag to true will default podman --remote=true for
786 access to the remote Podman service.
787 runtime=""
790 Default OCI specific runtime in runtimes that will be used by default.
793 Must refer to a member of the runtimes table. Default runtime will be
794 searched for on the system using the priority: "crun", "runc", "kata".
795 runtime_supports_json=["crun", "runc", "kata", "runsc", "krun"]
798 The list of the OCI runtimes that support --format=json.
801 runtime_supports_kvm=["kata", "krun"]
804 The list of OCI runtimes that support running containers with KVM sepa‐
807 ration.
808 runtime_supports_nocgroups=["crun", "krun"]
811 The list of OCI runtimes that support running containers without
814 CGroups.
815 image_copy_tmp_dir="/var/tmp"
818 Default location for storing temporary container image content. Can be
821 overridden with the TMPDIR environment variable. If you specify "stor‐
822 age", then the location of the container/storage tmp directory will be
823 used. If set then it is the users responsibility to cleanup storage.
824 Configure tmpfiles.d(5) to cleanup storage.
825 service_timeout=5
828 Number of seconds to wait without a connection before the podman sys‐
831 tem service times out and exits
832 static_dir="/var/lib/containers/storage/libpod"
835 Directory for persistent libpod files (database, etc). By default this
838 will be configured relative to where containers/storage stores contain‐
839 ers.
840 stop_timeout=10
843 Number of seconds to wait for container to exit before sending kill
846 signal.
847 exit_command_delay=300
850 Number of seconds to wait for the API process for the exec call before
853 sending exit command mimicking the Docker behavior of 5 minutes (in
854 seconds).
855 tmp_dir="/run/libpod"
858 The path to a temporary directory to store per-boot container. Must be
861 a tmpfs (wiped after reboot).
862 volume_path="/var/lib/containers/storage/volumes"
865 Directory where named volumes will be created in using the default vol‐
868 ume driver. By default this will be configured relative to where con‐
869 tainers/storage store containers. This convention is followed by the
870 default volume driver, but may not be by other drivers.
871 chown_copied_files=true
874 Determines whether file copied into a container will have changed own‐
877 ership to the primary uid/gid of the container.
878 compression_format=""
881 Specifies the compression format to use when pushing an image. Sup‐
884 ported values are: gzip, zstd and zstd:chunked.
885
888 The service_destinations table contains configuration options used to
889 set up remote connections to the podman service for the podman API.
890 [service_destinations.{name}] URI to access the Podman service
893 uri="ssh://user@production.example.com/run/user/1001/podman/pod‐
894 man.sock"
895 Example URIs:
898 • rootless local - unix://run/user/1000/podman/podman.sock
901 • rootless remote - ssh://user@engineering.lab.com‐
903 pany.com/run/user/1000/podman/podman.sock
904 • rootfull local - unix://run/podman/podman.sock
906 • rootfull remote - ssh://root@10.10.1.136:22/run/podman/pod‐
908 man.sock
909 identity="~/.ssh/id_rsa
913 Path to file containing ssh identity key
916 [engine.volume_plugins]
919 A table of all the enabled volume plugins on the system. Volume plugins
922 can be used as the backend for Podman named volumes. Individual plugins
923 are specified below, as a map of the plugin name (what the plugin will
924 be called) to its path (filepath of the plugin's unix socket).
925
928 The secret table contains settings for the configuration of the secret
929 subsystem.
930 driver=file
933 Name of the secret driver to be used. Currently valid values are:
936 * file
937 * pass
938 [secrets.opts]
941 The driver specific options object.
944
947 The machine table contains configurations for podman machine VMs
948 cpus=1 Number of CPU's a machine is created with.
951 disk_size=10
954 The size of the disk in GB created when init-ing a podman-machine VM
957 image=""
960 Default image used when creating a new VM using podman machine init.
963 Options: On Linux/Mac, testing, stable, next. On Windows, the major
964 version of the OS (e.g 35). For all platforms you can alternatively
965 specify a custom path or download URL to an image. The default is test‐
966 ing on Linux/Mac, and 35 on Windows.
967 memory=2048
970 Memory in MB a machine is created with.
973 user=""
976 Username to use and create on the podman machine OS for rootless con‐
979 tainer access. The default value is user. On Linux/Mac the default is‐
980 core.
981 volumes=["$HOME:$HOME"]
984 Host directories to be mounted as volumes into the VM by default. En‐
987 vironment variables like $HOME as well as complete paths are supported
988 for the source and destination. An optional third field :ro can be used
989 to tell the container engines to mount the volume readonly.
990
994 containers.conf
995 Distributions often provide a /usr/share/containers/containers.conf
998 file to define default container configuration. Administrators can
999 override fields in this file by creating /etc/containers/contain‐
1000 ers.conf to specify their own configuration. Rootless users can further
1001 override fields in the config by creating a config file stored in the
1002 $HOME/.config/containers/containers.conf file.
1003 If the CONTAINERS_CONF path environment variable is set, just this path
1006 will be used. This is primarily used for testing.
1007 Fields specified in the containers.conf file override the default op‐
1010 tions, as well as options in previously read containers.conf files.
1011 storage.conf
1014 The /etc/containers/storage.conf file is the default storage configura‐
1017 tion file. Rootless users can override fields in the storage config by
1018 creating $HOME/.config/containers/storage.conf.
1019 If the CONTAINERS_STORAGE_CONF path environment variable is set, this
1022 path is used for the storage.conf file rather than the default. This
1023 is primarily used for testing.
1024
1028 containers-storage.conf(5), containers-policy.json(5), containers-reg‐
1029 istries.conf(5), tmpfiles.d(5)
1030engine Container containers.conf(5)