3f07b4
% containers.conf(5) Container engine configuration file
3f07b4
3f07b4
# NAME
3f07b4
containers.conf - The container engine configuration file specifies default
3f07b4
configuration options and command-line flags for container engines.
3f07b4
3f07b4
# DESCRIPTION
3f07b4
Container engines like Podman & Buildah read containers.conf file, if it exists
3f07b4
and modify the defaults for running containers on the host. containers.conf uses
3f07b4
a TOML format that can be easily modified and versioned.
3f07b4
3f07b4
Container engines read the /usr/share/containers/containers.conf and
3f07b4
/etc/containers/containers.conf files if they exists.  When running in rootless
3f07b4
mode, they also read $HOME/.config/containers/containers.conf files.
3f07b4
3f07b4
Fields specified in containers conf override the default options, as well as
3f07b4
options in previously read containers.conf files.
3f07b4
3f07b4
Not all options are supported in all container engines.
3f07b4
3f07b4
Note container engines also use other configuration files for configuring the environment.
3f07b4
3f07b4
* `storage.conf` for configuration of container and images storage.
3f07b4
* `registries.conf` for definition of container registires to search while pulling.
3f07b4
container images.
3f07b4
* `policy.conf` for controlling which images can be pulled to the system.
3f07b4
3f07b4
# FORMAT
3f07b4
The [TOML format][toml] is used as the encoding of the configuration file.
3f07b4
Every option is nested under its table. No bare options are used. The format of
3f07b4
TOML can be simplified to:
3f07b4
3f07b4
    [table1]
3f07b4
    option = value
3f07b4
3f07b4
    [table2]
3f07b4
    option = value
3f07b4
3f07b4
    [table3]
3f07b4
    option = value
3f07b4
3f07b4
    [table3.subtable1]
3f07b4
    option = value
3f07b4
3f07b4
## CONTAINERS TABLE
3f07b4
The containers table contains settings pertaining to the OCI runtime that can
3f07b4
configure and manage the OCI runtime.
3f07b4
3f07b4
**devices**=[]
3f07b4
  List of devices.
3f07b4
  Specified as 'device-on-host:device-on-container:permissions',
3f07b4
  for example: "/dev/sdc:/dev/xvdc:rwm".
3f07b4
3f07b4
**volumes**=[]
3f07b4
  List of volumes.
3f07b4
  Specified as "directory-on-host:directory-in-container:options",
3f07b4
  for example:  "/db:/var/lib/db:ro".
3f07b4
3f07b4
**apparmor_profile**="container-default"
3f07b4
  Used to change the name of the default AppArmor profile of container engines.
3f07b4
The default profile name is "container-default".
3f07b4
3f07b4
**cgroupns**="private"
3f07b4
  Default way to to create a cgroup namespace for the container.
3f07b4
  Options are:
3f07b4
    `private` Create private Cgroup Namespace for the container.
3f07b4
    `host`    Share host Cgroup Namespace with the container.
3f07b4
3f07b4
**cgroups**="enabled"
3f07b4
  Determines  whether  the  container will create CGroups.
3f07b4
  Options are:
3f07b4
    `enabled`   Enable cgroup support within container
3f07b4
    `disabled`  Disable cgroup support, will inherit cgroups from parent
3f07b4
    `no-conmon` Container engine runs run without conmon
3f07b4
3f07b4
**default_capabilities**=[]
3f07b4
  List of default capabilities for containers.
3f07b4
3f07b4
    The default list is:
3f07b4
```
3f07b4
  default_capabilities = [
3f07b4
	"AUDIT_WRITE",
3f07b4
	      "CHOWN",
3f07b4
	      "DAC_OVERRIDE",
3f07b4
	      "FOWNER",
3f07b4
	      "FSETID",
3f07b4
	      "KILL",
3f07b4
	      "MKNOD",
3f07b4
	      "NET_BIND_SERVICE",
3f07b4
	      "NET_RAW",
3f07b4
	      "SETGID",
3f07b4
	      "SETPCAP",
3f07b4
	      "SETUID",
3f07b4
	      "SYS_CHROOT",
3f07b4
  ]
3f07b4
```
3f07b4
3f07b4
**default_sysctls**=[]
3f07b4
  A list of sysctls to be set in containers by default,
3f07b4
specified as "name=value",
3f07b4
for example:"net.ipv4.ping_group_range=0 1000".
3f07b4
3f07b4
**default_ulimits**=[]
3f07b4
  A list of ulimits to be set in containers by default,
3f07b4
specified as "name=soft-limit:hard-limit",
3f07b4
for example:"nofile=1024:2048".
3f07b4
3f07b4
**dns_options**=[]
3f07b4
  List of default DNS options to be added to /etc/resolv.conf inside of the
3f07b4
container.
3f07b4
3f07b4
**dns_searches**=[]
3f07b4
  List of default DNS search domains to be added to /etc/resolv.conf inside of
3f07b4
the container.
3f07b4
3f07b4
**dns_servers**=[]
3f07b4
  A list of dns servers to override the DNS configuration passed to the
3f07b4
container. The special value “none” can be specified to disable creation of
3f07b4
/etc/resolv.conf in the container.
3f07b4
3f07b4
**env**=["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"]
3f07b4
  Environment variable list for the container process, used for passing
3f07b4
environment variables to the container.
3f07b4
3f07b4
**env_host**=false
3f07b4
  Pass all host environment variables into the container.
3f07b4
3f07b4
**hooks_dir**=["/etc/containers/oci/hooks.d", ...]
3f07b4
  Path to the OCI hooks directories for automatically executed hooks.
3f07b4
3f07b4
**http_proxy**=false
3f07b4
  Default proxy environment variables will be passed into the container.
3f07b4
  The environment variables passed in include:
3f07b4
`http_proxy`, `https_proxy`, `ftp_proxy`, `no_proxy`, and the upper case
3f07b4
versions of these. The `no_proxy` option is needed when host system uses a proxy
3f07b4
but container should not use proxy. Proxy environment variables specified for
3f07b4
the container in any other way will override the values passed from the host.
3f07b4
3f07b4
**init**=false
3f07b4
  Run an init inside the container that forwards signals and reaps processes.
3f07b4
3f07b4
**init_path**="/usr/libexec/podman/catatonit"
3f07b4
  Path to the container-init binary, which forwards signals and reaps processes
3f07b4
within containers.  Note that the container-init binary will only be used when
3f07b4
the `--init` for podman-create and podman-run is set.
3f07b4
3f07b4
**ipcns**="private"
3f07b4
  Default way to to create a IPC namespace for the container.
3f07b4
  Options are:
3f07b4
    `private` Create private IPC Namespace for the container.
3f07b4
    `host`    Share host IPC Namespace with the container.
3f07b4
3f07b4
**label**=true
3f07b4
  Indicates whether the container engines use MAC(SELinux) container separation via via labeling. Flag is ignored on disabled systems.
3f07b4
3f07b4
**log_driver**="k8s-file"
3f07b4
  Logging driver for the container. Available options: `k8s-file` and `journald`.
3f07b4
3f07b4
**log_size_max**=-1
3f07b4
  Maximum size allowed for the container's log file. Negative numbers indicate
3f07b4
that no size limit is imposed. If it is positive, it must be >= 8192 to
3f07b4
match/exceed conmon's read buffer. The file is truncated and re-opened so the
3f07b4
limit is never exceeded.
3f07b4
3f07b4
**netns**="private"
3f07b4
  Default way to to create a NET namespace for the container.
3f07b4
  Options are:
3f07b4
    `private` Create private NET Namespace for the container.
3f07b4
    `host`    Share host NET Namespace with the container.
3f07b4
    `none`    Containers do not use the network.
3f07b4
3f07b4
**no_hosts**=false
3f07b4
   Create /etc/hosts for the container.  By default, container engines manage
3f07b4
/etc/hosts, automatically adding  the container's  own  IP  address.
3f07b4
3f07b4
**pids_limit**=1024
3f07b4
  Maximum number of processes allowed in a container. 0 indicates that no limit
3f07b4
is imposed.
3f07b4
3f07b4
**pidns**="private"
3f07b4
  Default way to to create a PID namespace for the container.
3f07b4
  Options are:
3f07b4
    `private` Create private PID Namespace for the container.
3f07b4
    `host`    Share host PID Namespace with the container.
3f07b4
3f07b4
**seccomp_profile**="/usr/share/containers/seccomp.json"
3f07b4
  Path to the seccomp.json profile which is used as the default seccomp profile
3f07b4
for the runtime.
3f07b4
3f07b4
**shm_size**="65536k"
3f07b4
  Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater
3f07b4
than `0`.
3f07b4
  Unit is optional and can be:
3f07b4
`b` (bytes), `k` (kilobytes), `m`(megabytes), or `g` (gigabytes).
3f07b4
If you omit the unit, the system uses bytes. If you omit the size entirely,
3f07b4
the system uses `65536k`.
3f07b4
3f07b4
**utsns**="private"
3f07b4
  Default way to to create a UTS namespace for the container.
3f07b4
  Options are:
3f07b4
    `private` Create private UTS Namespace for the container.
3f07b4
    `host`    Share host UTS Namespace with the container.
3f07b4
3f07b4
**userns**="host"
3f07b4
  Default way to to create a USER namespace for the container.
3f07b4
  Options are:
3f07b4
    `private` Create private USER Namespace for the container.
3f07b4
    `host`    Share host USER Namespace with the container.
3f07b4
3f07b4
**userns_size**=65536
3f07b4
  Number of UIDs to allocate for the automatic container creation. UIDs are
3f07b4
allocated from the “container” UIDs listed in /etc/subuid & /etc/subgid.
3f07b4
3f07b4
## NETWORK TABLE
3f07b4
The `network` table contains settings pertaining to the management of CNI
3f07b4
plugins.
3f07b4
3f07b4
**cni_plugin_dirs**=["/opt/cni/bin/",]
3f07b4
  List of paths to directories where CNI plugin binaries are located.
3f07b4
3f07b4
**default_network**="podman"
3f07b4
  The network name of the default CNI network to attach pods to.
3f07b4
3f07b4
**network_config_dir**="/etc/cni/net.d/"
3f07b4
  Path to the directory where CNI configuration files are located.
3f07b4
3f07b4
## ENGINE TABLE
3f07b4
The `engine` table contains configuration options used to set up container engines such as Podman and Buildah.
3f07b4
3f07b4
**cgroup_check**=false
3f07b4
CgroupCheck indicates the configuration has been rewritten after an upgrade to Fedora 31 to change the default OCI runtime for cgroupsv2.
3f07b4
3f07b4
**cgroup_manager**="systemd"
3f07b4
  The cgroup management implementation used for the runtime. Supports `cgroupfs`
3f07b4
and `systemd`.
3f07b4
3f07b4
**conmon_env_vars**=[]
3f07b4
  Environment variables to pass into Conmon.
3f07b4
3f07b4
**conmon_path**=[]
3f07b4
  Paths to search for the conmon container manager binary. If the paths are
3f07b4
empty or no valid path was found, then the `$PATH` environment variable will be
3f07b4
used as the fallback.
3f07b4
3f07b4
    The default list is:
3f07b4
```
3f07b4
conmon_path=[
3f07b4
		"/usr/libexec/podman/conmon",
3f07b4
		"/usr/local/libexec/podman/conmon",
3f07b4
		"/usr/local/lib/podman/conmon",
3f07b4
		"/usr/bin/conmon",
3f07b4
		"/usr/sbin/conmon",
3f07b4
		"/usr/local/bin/conmon",
3f07b4
		"/usr/local/sbin/conmon",
3f07b4
		"/run/current-system/sw/bin/conmon",
3f07b4
]
3f07b4
```
3f07b4
3f07b4
**detach_keys**="ctrl-p,ctrl-q"
3f07b4
  Keys sequence used for detaching a container.
3f07b4
  Specify the keys sequence used to detach a container.
3f07b4
Format is a single character `[a-Z]` or a comma separated sequence of
3f07b4
`ctrl-<value>`, where `<value>` is one of:
3f07b4
`a-z`, `@`, `^`, `[`, `\`, `]`, `^` or `_`
3f07b4
3f07b4
**enable_port_reservation**=true
3f07b4
  Determines whether the engine will reserve ports on the host when they are
3f07b4
forwarded to containers. When enabled, when ports are forwarded to containers,
3f07b4
they are held open by conmon as long as the container is running, ensuring that
3f07b4
they cannot be reused by other programs on the host. However, this can cause
3f07b4
significant memory usage if a container has many ports forwarded to it.
3f07b4
Disabling this can save memory.
3f07b4
3f07b4
**events_logger**="journald"
3f07b4
  Default method to use when logging events.
3f07b4
  Valid values: `file`, `journald`, and `none`.
3f07b4
3f07b4
**image_default_transport**="docker://"
3f07b4
  Default transport method for pulling and pushing images.
3f07b4
3f07b4
**infra_command**="/pause"
3f07b4
  Command to run the infra container.
3f07b4
3f07b4
**infra_image**="k8s.gcr.io/pause:3.2"
3f07b4
  Infra (pause) container image name for pod infra containers.  When running a
3f07b4
pod, we start a `pause` process in a container to hold open the namespaces
3f07b4
associated with the  pod.  This container does nothing other then sleep,
3f07b4
reserving the pods resources for the lifetime of the pod.
3f07b4
3f07b4
**lock_type**="shm"
3f07b4
  Specify the locking mechanism to use; valid values are "shm" and "file".
3f07b4
Change the default only if you are sure of what you are doing, in general
3f07b4
"file" is useful only on platforms where cgo is not available for using the
3f07b4
faster "shm" lock type.  You may need to run "podman system renumber" after you
3f07b4
change the lock type.
3f07b4
3f07b4
**namespace**=""
3f07b4
  Default engine namespace. If the engine is joined to a namespace, it will see
3f07b4
only containers and pods that were created in the same namespace, and will
3f07b4
create new containers and pods in that namespace.  The default namespace is "",
3f07b4
 which corresponds to no namespace. When no namespace is set, all containers
3f07b4
and pods are visible.
3f07b4
3f07b4
**no_pivot_root**=false
3f07b4
  Whether to use chroot instead of pivot_root in the runtime.
3f07b4
3f07b4
**num_locks**=2048
3f07b4
  Number of locks available for containers and pods. Each created container or
3f07b4
pod consumes one lock.  The default number available is 2048.  If this is
3f07b4
changed, a lock renumbering must be performed, using the
3f07b4
`podman system renumber` command.
3f07b4
3f07b4
**pull_policy**="always"|"missing"|"never"
3f07b4
Pull image before running or creating a container. The default is **missing**.
3f07b4
3f07b4
- **missing**: attempt to pull the latest image from the registries listed in registries.conf if a local image does not exist. Raise an error if the image is not in any listed registry and is not present locally.
3f07b4
- **always**: pull the image from the first registry it is found in as listed in registries.conf. Raise an error if not found in the registries, even if the image is present locally.
3f07b4
- **never**: do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally.
3f07b4
3f07b4
**runtime**="crun"
3f07b4
  Default OCI specific runtime in runtimes that will be used by default. Must
3f07b4
refer to a member of the runtimes table.
3f07b4
3f07b4
**runtime_supports_json**=["crun", "runc", "kata"]
3f07b4
  The list of the OCI runtimes that support `--format=json`.
3f07b4
3f07b4
**runtime_supports_nocgroups**=["crun"]
3f07b4
  The list of OCI runtimes that support running containers without CGroups.
3f07b4
3f07b4
**runtime_supports_kvm**=["kata"]
3f07b4
  The list of OCI runtimes that support running containers with KVM separation.
3f07b4
3f07b4
**static_dir**="/var/lib/containers/storage/libpod"
3f07b4
  Directory for persistent libpod files (database, etc).
3f07b4
By default this will be configured relative to where containers/storage
3f07b4
stores containers.
3f07b4
3f07b4
**stop_timeout**=10
3f07b4
  Number of seconds to wait for container to exit before sending kill signal.
3f07b4
3f07b4
**tmp_dir**="/var/run/libpod"
3f07b4
  The path to a temporary directory to store per-boot container.
3f07b4
Must be a tmpfs (wiped after reboot).
3f07b4
3f07b4
**volume_path**="/var/lib/containers/storage/volumes"
3f07b4
  Directory where named volumes will be created in using the default volume
3f07b4
driver.
3f07b4
  By default this will be configured relative to where containers/storage store
3f07b4
containers. This convention is followed by the default volume driver, but may
3f07b4
not be by other drivers.
3f07b4
3f07b4
# FILES
3f07b4
Distributions often provide a `/usr/share/containers/containers.conf` file to
3f07b4
define default container configuration. Administrators can override fields in
3f07b4
this file by creating `/etc/containers/containers.conf` to specify their own
3f07b4
configuration. Rootless users can further override fields in the config by
3f07b4
creating a config file stored in the
3f07b4
`$HOME/.config/containers/containers.conf` file.
3f07b4
3f07b4
If the `CONTAINERS_CONF` path environment variable is set, just
3f07b4
this path will be used.  This is primarily used for testing.
3f07b4
3f07b4
Fields specified in the containers.conf file override the default options, as
3f07b4
well as options in previously read containers.conf files.
3f07b4
3f07b4
# SEE ALSO
3f07b4
containers-storage.conf(5), containers-policy.json(5), containers-registries.conf(5)
3f07b4
3f07b4
[toml]: https://github.com/toml-lang/toml