1containers.conf(5)(Container) file containers.conf(5)(Container)
2
3
4
6 containers.conf - The container engine configuration file specifies de‐
7 fault configuration options and command-line flags for container en‐
8 gines.
9
10
11
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
18
19 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
24
25 Fields specified in containers conf override the default options, as
26 well as options in previously read containers.conf files.
27
28
29 Not all options are supported in all container engines.
30
31
32 Note container engines also use other configuration files for configur‐
33 ing the environment.
34
35
36 • storage.conf for configuration of container and images stor‐
37 age.
38
39 • registries.conf for definition of container registires to
40 search while pulling. container images.
41
42 • policy.conf for controlling which images can be pulled to the
43 system.
44
45
46
47
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
53
54 [table1]
55 option = value
56
57 [table2]
58 option = value
59
60 [table3]
61 option = value
62
63 [table3.subtable1]
64 option = value
65
66
67
69 The containers table contains settings pertaining to the OCI runtime
70 that can configure and manage the OCI runtime.
71
72
73 annotations = [] List of annotations. Specified as "key=value" pairs to
74 be added to all containers.
75
76
77 Example: "run.oci.keep_original_groups=1"
78
79
80 apparmor_profile="container-default"
81
82
83 Used to change the name of the default AppArmor profile of container
84 engines. The default profile name is "container-default".
85
86
87 cgroups="enabled"
88
89
90 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
95
96 cgroupns="private"
97
98
99 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
103
104 default_capabilities=[]
105
106
107 List of default capabilities for containers.
108
109
110 The default list is:
111
112
113 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
129
130
131 default_sysctls=[]
132
133
134 A list of sysctls to be set in containers by default, specified as
135 "name=value".
136
137
138 Example:"net.ipv4.ping_group_range=0 1000".
139
140
141 default_ulimits=[]
142
143
144 A list of ulimits to be set in containers by default, specified as
145 "name=soft-limit:hard-limit".
146
147
148 Example: "nofile=1024:2048".
149
150
151 devices=[]
152
153
154 List of devices. Specified as 'device-on-host:device-on-container:per‐
155 missions'.
156
157
158 Example: "/dev/sdc:/dev/xvdc:rwm".
159
160
161 dns_options=[]
162
163
164 List of default DNS options to be added to /etc/resolv.conf inside of
165 the container.
166
167
168 dns_searches=[]
169
170
171 List of default DNS search domains to be added to /etc/resolv.conf in‐
172 side of the container.
173
174
175 dns_servers=[]
176
177
178 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
182
183 env=["PATH=/usr/local/sbin:/usr/lo‐
184 cal/bin:/usr/sbin:/usr/bin:/sbin:/bin", "TERM=xterm"]
185
186
187 Environment variable list for the container process, used for passing
188 environment variables to the container.
189
190
191 env_host=false
192
193
194 Pass all host environment variables into the container.
195
196
197 http_proxy=true
198
199
200 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
207
208 init=false
209
210
211 Run an init inside the container that forwards signals and reaps pro‐
212 cesses.
213
214
215 init_path="/usr/libexec/podman/catatonit"
216
217
218 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
222
223 ipcns="private"
224
225
226 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
231
232 keyring=true
233
234
235 Indicates whether the container engines create a kernel keyring for use
236 within the container.
237
238
239 label=true
240
241
242 Indicates whether the container engine uses MAC(SELinux) container sep‐
243 aration via labeling. This option is ignored on disabled systems.
244
245
246 log_driver="k8s-file"
247
248
249 Logging driver for the container. Available options: k8s-file and jour‐
250 nald.
251
252
253 log_size_max=-1
254
255
256 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
261
262 netns="private"
263
264
265 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
271
272 no_hosts=false
273
274
275 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
279
280 pidns="private"
281
282
283 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
288
289 pids_limit=1024
290
291
292 Maximum number of processes allowed in a container. 0 indicates that no
293 limit is imposed.
294
295
296 rootless_networking="slirp4netns"
297
298
299 Set type of networking rootless containers should use. Valid options
300 are slirp4netns or cni.
301
302
303 seccomp_profile="/usr/share/containers/seccomp.json"
304
305
306 Path to the seccomp.json profile which is used as the default seccomp
307 profile for the runtime.
308
309
310 shm_size="65536k"
311
312
313 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
318
319 tz=""
320
321
322 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
327
328 Examples:
329 tz="local"
330 tz="America/New_York"
331
332
333 umask="0022"
334
335
336 Sets umask inside the container.
337
338
339 userns="host"
340
341
342 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
347
348 userns_size=65536
349
350
351 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
355
356 utsns="private"
357
358
359 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
364
366 The network table contains settings pertaining to the management of CNI
367 plugins.
368
369
370 cni_plugin_dirs=["/opt/cni/bin/",]
371
372
373 List of paths to directories where CNI plugin binaries are located.
374
375
376 default_network="podman"
377
378
379 The network name of the default CNI network to attach pods to.
380
381
382 default_subnet="10.88.0.0/16"
383
384
385 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
389
390 network_config_dir="/etc/cni/net.d/"
391
392
393 Path to the directory where CNI configuration files are located.
394
395
396 volumes=[]
397
398
399 List of volumes. Specified as "directory-on-host:directory-in-con‐
400 tainer:options".
401
402
403 Example: "/db:/var/lib/db:ro".
404
405
407 The engine table contains configuration options used to set up con‐
408 tainer engines such as Podman and Buildah.
409
410
411 active_service=""
412
413
414 Name of destination for accessing the Podman service. See SERVICE DES‐
415 TINATION TABLE below.
416
417
418 cgroup_check=false
419
420
421 CgroupCheck indicates the configuration has been rewritten after an up‐
422 grade to Fedora 31 to change the default OCI runtime for cgroupsv2.
423
424
425 cgroup_manager="systemd"
426
427
428 The cgroup management implementation used for the runtime. Supports
429 cgroupfs and systemd.
430
431
432 conmon_env_vars=[]
433
434
435 Environment variables to pass into Conmon.
436
437
438 conmon_path=[]
439
440
441 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
445
446 The default list is:
447
448
449 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
460
461
462 detach_keys="ctrl-p,ctrl-q"
463
464
465 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
470
471 enable_port_reservation=true
472
473
474 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
481
482 env=[]
483
484
485 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
491
492 events_logger="journald"
493
494
495 Default method to use when logging events. Valid values: file, jour‐
496 nald, and none.
497
498
499 hooks_dir=["/etc/containers/oci/hooks.d", ...]
500
501
502 Path to the OCI hooks directories for automatically executed hooks.
503
504
505 image_default_format="oci"|"v2s2"|"v2s1"
506
507
508 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
513
514 image_default_transport="docker://"
515
516
517 Default transport method for pulling and pushing images.
518
519
520 image_parallel_copies=0
521
522
523 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
527
528 infra_command="/pause"
529
530
531 Command to run the infra container.
532
533
534 infra_image="k8s.gcr.io/pause:3.4.1"
535
536
537 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
542
543 lock_type="shm"
544
545
546 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
552
553 machine_enabled=false
554
555
556 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
560
561 multi_image_archive=false
562
563
564 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
569
570 namespace=""
571
572
573 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
579
580 network_cmd_path=""
581
582
583 Path to the slirp4netns binary.
584
585
586 network_cmd_options=[]
587
588
589 Default options to pass to the slirp4netns binary.
590
591
592 Example "allow_host_loopback=true"
593
594
595 no_pivot_root=false
596
597
598 Whether to use chroot instead of pivot_root in the runtime.
599
600
601 num_locks=2048
602
603
604 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
609
610 pull_policy="always"|"missing"|"never"
611
612
613 Pull image before running or creating a container. The default is miss‐
614 ing.
615
616
617 • 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
622 • 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
626 • 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
630
631
632 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
637
638 runtime=""
639
640
641 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
645
646 runtime_supports_json=["crun", "runc", "kata", "runsc"]
647
648
649 The list of the OCI runtimes that support --format=json.
650
651
652 runtime_supports_nocgroups=["crun"]
653
654
655 The list of OCI runtimes that support running containers without
656 CGroups.
657
658
659 runtime_supports_kvm=["kata"]
660
661
662 The list of OCI runtimes that support running containers with KVM sepa‐
663 ration.
664
665
666 static_dir="/var/lib/containers/storage/libpod"
667
668
669 Directory for persistent libpod files (database, etc). By default this
670 will be configured relative to where containers/storage stores contain‐
671 ers.
672
673
674 stop_timeout=10
675
676
677 Number of seconds to wait for container to exit before sending kill
678 signal.
679
680
681 tmp_dir="/run/libpod"
682
683
684 The path to a temporary directory to store per-boot container. Must be
685 a tmpfs (wiped after reboot).
686
687
689 The service_destinations table contains configuration options used to
690 set up remote connections to the podman service for the podman API.
691
692
693 [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
697
698 Example URIs:
699
700
701 • rootless local - unix://run/user/1000/podman/podman.sock
702
703 • rootless remote - ssh://user@engineering.lab.com‐
704 pany.com/run/user/1000/podman/podman.sock
705
706 • rootfull local - unix://run/podman/podman.sock
707
708 • rootfull remote - ssh://root@10.10.1.136:22/run/podman/pod‐
709 man.sock
710
711
712
713 identity="~/.ssh/id_rsa
714
715
716 Path to file containing ssh identity key
717
718
719 volume_path="/var/lib/containers/storage/volumes"
720
721
722 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
727
728 [engine.volume_plugins]
729
730
731 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
736
737
739 containers.conf
740
741
742 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
749
750 If the CONTAINERS_CONF path environment variable is set, just this path
751 will be used. This is primarily used for testing.
752
753
754 Fields specified in the containers.conf file override the default op‐
755 tions, as well as options in previously read containers.conf files.
756
757
758 storage.conf
759
760
761 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
765
766 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
770
771
773 containers-storage.conf(5), containers-policy.json(5), containers-reg‐
774 istries.conf(5)
775
776
777
778configuration engine containers.conf(5)(Container)