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.
76 Specified as 'device-on-host:device-on-container:permissions',
77 for example: "/dev/sdc:/dev/xvdc:rwm".
78 volumes=[]
81 List of volumes.
82 Specified as "directory-on-host:directory-in-container:options",
83 for example: "/db:/var/lib/db:ro".
84 apparmor_profile="container-default"
87 Used to change the name of the default AppArmor profile of container
88 engines. The default profile name is "container-default".
89 cgroupns="private"
92 Default way to to create a cgroup namespace for the container.
93 Options are:
94 private Create private Cgroup Namespace for the container.
95 host Share host Cgroup Namespace with the container.
96 default_capabilities=[]
99 List of default capabilities for containers.
100 The default list is:
103 default_capabilities = [
107 "AUDIT_WRITE",
108 "CHOWN",
109 "DAC_OVERRIDE",
110 "FOWNER",
111 "FSETID",
112 "KILL",
113 "MKNOD",
114 "NET_BIND_SERVICE",
115 "NET_RAW",
116 "SETGID",
117 "SETPCAP",
118 "SETUID",
119 "SYS_CHROOT",
120 ]
121 default_sysctls=[]
125 A list of sysctls to be set in containers by default, specified as
126 "name=value", for example:"net.ipv4.ping_group_range=0 1000".
127 default_ulimits=[]
130 A list of ulimits to be set in containers by default, specified as
131 "name=soft-limit:hard-limit", for example:"nofile=1024:2048".
132 dns_options=[]
135 List of default DNS options to be added to /etc/resolv.conf inside of
136 the container.
137 dns_searches=[]
140 List of default DNS search domains to be added to /etc/resolv.conf
141 inside of the container.
142 dns_servers=[]
145 A list of dns servers to override the DNS configuration passed to the
146 container. The special value “none” can be specified to disable cre‐
147 ation of /etc/resolv.conf in the container.
148 env=["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"]
151 Environment variable list for the container process, used for passing
152 environment variables to the container.
153 env_host=false
156 Pass all host environment variables into the container.
157 hooks_dir=["/etc/containers/oci/hooks.d", ...]
160 Path to the OCI hooks directories for automatically executed hooks.
161 http_proxy=false
164 Default proxy environment variables will be passed into the con‐
165 tainer.
166 The environment variables passed in include: http_proxy, https_proxy,
167 ftp_proxy, no_proxy, and the upper case versions of these. The no_proxy
168 option is needed when host system uses a proxy but container should not
169 use proxy. Proxy environment variables specified for the container in
170 any other way will override the values passed from the host.
171 init=false
174 Run an init inside the container that forwards signals and reaps pro‐
175 cesses.
176 init_path="/usr/libexec/podman/catatonit"
179 Path to the container-init binary, which forwards signals and reaps
180 processes within containers. Note that the container-init binary will
181 only be used when the --init for podman-create and podman-run is set.
182 ipcns="private"
185 Default way to to create a IPC namespace for the container.
186 Options are:
187 private Create private IPC Namespace for the container.
188 host Share host IPC Namespace with the container.
189 label=true
192 Indicates whether the container engines use MAC(SELinux) container
193 separation via via labeling. Flag is ignored on disabled systems.
194 log_driver="k8s-file"
197 Logging driver for the container. Available options: k8s-file and
198 journald.
199 log_size_max=-1
202 Maximum size allowed for the container's log file. Negative numbers
203 indicate that no size limit is imposed. If it is positive, it must be
204 >= 8192 to match/exceed conmon's read buffer. The file is truncated and
205 re-opened so the limit is never exceeded.
206 netns="private"
209 Default way to to create a NET namespace for the container.
210 Options are:
211 private Create private NET Namespace for the container.
212 host Share host NET Namespace with the container.
213 none Containers do not use the network.
214 no_hosts=false
217 Create /etc/hosts for the container. By default, container engines
218 manage /etc/hosts, automatically adding the container's own IP
219 address.
220 pids_limit=1024
223 Maximum number of processes allowed in a container. 0 indicates that
224 no limit is imposed.
225 pidns="private"
228 Default way to to create a PID namespace for the container.
229 Options are:
230 private Create private PID Namespace for the container.
231 host Share host PID Namespace with the container.
232 seccomp_profile="/usr/share/containers/seccomp.json"
235 Path to the seccomp.json profile which is used as the default seccomp
236 profile for the runtime.
237 shm_size="65536k"
240 Size of /dev/shm. The format is <number><unit>. number must be
241 greater than 0.
242 Unit is optional and can be: b (bytes), k (kilobytes), m(megabytes),
243 or g (gigabytes). If you omit the unit, the system uses bytes. If you
244 omit the size entirely, the system uses 65536k.
245 utsns="private"
248 Default way to to create a UTS namespace for the container.
249 Options are:
250 private Create private UTS Namespace for the container.
251 host Share host UTS Namespace with the container.
252 userns="host"
255 Default way to to create a USER namespace for the container.
256 Options are:
257 private Create private USER Namespace for the container.
258 host Share host USER Namespace with the container.
259 userns_size=65536
262 Number of UIDs to allocate for the automatic container creation. UIDs
263 are allocated from the “container” UIDs listed in /etc/subuid
264 /etc/subgid.
265
268 The network table contains settings pertaining to the management of CNI
269 plugins.
270 cni_plugin_dirs=["/opt/cni/bin/",]
273 List of paths to directories where CNI plugin binaries are located.
274 default_network="podman"
277 The network name of the default CNI network to attach pods to.
278 network_config_dir="/etc/cni/net.d/"
281 Path to the directory where CNI configuration files are located.
282
285 The engine table contains configuration options used to set up con‐
286 tainer engines such as Podman and Buildah.
287 cgroup_check=false CgroupCheck indicates the configuration has been
290 rewritten after an upgrade to Fedora 31 to change the default OCI run‐
291 time for cgroupsv2.
292 cgroup_manager="systemd"
295 The cgroup management implementation used for the runtime. Supports
296 cgroupfs and systemd.
297 conmon_env_vars=[]
300 Environment variables to pass into Conmon.
301 conmon_path=[]
304 Paths to search for the conmon container manager binary. If the paths
305 are empty or no valid path was found, then the $PATH environment vari‐
306 able will be used as the fallback.
307 The default list is:
310 conmon_path=[
314 "/usr/libexec/podman/conmon",
315 "/usr/local/libexec/podman/conmon",
316 "/usr/local/lib/podman/conmon",
317 "/usr/bin/conmon",
318 "/usr/sbin/conmon",
319 "/usr/local/bin/conmon",
320 "/usr/local/sbin/conmon",
321 "/run/current-system/sw/bin/conmon",
322 ]
323 detach_keys="ctrl-p,ctrl-q"
327 Keys sequence used for detaching a container.
328 Specify the keys sequence used to detach a container. Format is a
329 single character [a-Z] or a comma separated sequence of ctrl-<value>,
330 where <value> is one of: a-z, @, ^, [, \, ], ^ or _
331 enable_port_reservation=true
334 Determines whether the engine will reserve ports on the host when
335 they are forwarded to containers. When enabled, when ports are for‐
336 warded to containers, they are held open by conmon as long as the con‐
337 tainer is running, ensuring that they cannot be reused by other pro‐
338 grams on the host. However, this can cause significant memory usage if
339 a container has many ports forwarded to it. Disabling this can save
340 memory.
341 events_logger="journald"
344 Default method to use when logging events.
345 Valid values: file, journald, and none.
346 image_default_transport="docker://"
349 Default transport method for pulling and pushing images.
350 infra_command="/pause"
353 Command to run the infra container.
354 infra_image="k8s.gcr.io/pause:3.2"
357 Infra (pause) container image name for pod infra containers. When
358 running a pod, we start a pause process in a container to hold open the
359 namespaces associated with the pod. This container does nothing other
360 then sleep, reserving the pods resources for the lifetime of the pod.
361 lock_type="shm"
364 Specify the locking mechanism to use; valid values are "shm" and
365 "file". Change the default only if you are sure of what you are doing,
366 in general "file" is useful only on platforms where cgo is not avail‐
367 able for using the faster "shm" lock type. You may need to run "podman
368 system renumber" after you change the lock type.
369 namespace=""
372 Default engine namespace. If the engine is joined to a namespace, it
373 will see only containers and pods that were created in the same names‐
374 pace, and will create new containers and pods in that namespace. The
375 default namespace is "",
376 which corresponds to no namespace. When no namespace is set, all con‐
377 tainers and pods are visible.
378 no_pivot_root=false
381 Whether to use chroot instead of pivot_root in the runtime.
382 num_locks=2048
385 Number of locks available for containers and pods. Each created con‐
386 tainer or pod consumes one lock. The default number available is 2048.
387 If this is changed, a lock renumbering must be performed, using the
388 podman system renumber command.
389 pull_policy="always"|"missing"|"never" Pull image before running or
392 creating a container. The default is missing.
393 · missing: attempt to pull the latest image from the registries
396 listed in registries.conf if a local image does not exist.
397 Raise an error if the image is not in any listed registry and
398 is not present locally.
399 · always: pull the image from the first registry it is found in
401 as listed in registries.conf. Raise an error if not found in
402 the registries, even if the image is present locally.
403 · never: do not pull the image from the registry, use only the
405 local version. Raise an error if the image is not present
406 locally.
407 runtime="crun"
411 Default OCI specific runtime in runtimes that will be used by
412 default. Must refer to a member of the runtimes table.
413 runtime_supports_json=["crun", "runc", "kata"]
416 The list of the OCI runtimes that support --format=json.
417 runtime_supports_nocgroups=["crun"]
420 The list of OCI runtimes that support running containers without
421 CGroups.
422 runtime_supports_kvm=["kata"]
425 The list of OCI runtimes that support running containers with KVM
426 separation.
427 static_dir="/var/lib/containers/storage/libpod"
430 Directory for persistent libpod files (database, etc). By default
431 this will be configured relative to where containers/storage stores
432 containers.
433 stop_timeout=10
436 Number of seconds to wait for container to exit before sending kill
437 signal.
438 tmp_dir="/var/run/libpod"
441 The path to a temporary directory to store per-boot container. Must
442 be a tmpfs (wiped after reboot).
443 volume_path="/var/lib/containers/storage/volumes"
446 Directory where named volumes will be created in using the default
447 volume driver.
448 By default this will be configured relative to where containers/stor‐
449 age store containers. This convention is followed by the default volume
450 driver, but may not be by other drivers.
451
455 Distributions often provide a /usr/share/containers/containers.conf
456 file to define default container configuration. Administrators can
457 override fields in this file by creating /etc/containers/contain‐
458 ers.conf to specify their own configuration. Rootless users can further
459 override fields in the config by creating a config file stored in the
460 $HOME/.config/containers/containers.conf file.
461 If the CONTAINERS_CONF path environment variable is set, just this path
464 will be used. This is primarily used for testing.
465 Fields specified in the containers.conf file override the default
468 options, as well as options in previously read containers.conf files.
469
473 containers-storage.conf(5), containers-policy.json(5), containers-reg‐
474 istries.conf(5)
475configuration engine containers.conf(5)(Container)