bce470
% containers.conf(5) Container engine configuration file
bce470
bce470
# NAME
bce470
containers.conf - The container engine configuration file specifies default
bce470
configuration options and command-line flags for container engines.
bce470
bce470
# DESCRIPTION
bce470
Container engines like Podman & Buildah read containers.conf file, if it exists
bce470
and modify the defaults for running containers on the host. containers.conf uses
bce470
a TOML format that can be easily modified and versioned.
bce470
bce470
Container engines read the /usr/share/containers/containers.conf and
bce470
/etc/containers/containers.conf, and /etc/containers/containers.conf.d/*.conf files
bce470
if they exist.  When running in rootless mode, they also read
bce470
$HOME/.config/containers/containers.conf and
bce470
$HOME/.config/containers/containers.conf.d/*.conf files.
bce470
bce470
Fields specified in containers conf override the default options, as well as
bce470
options in previously read containers.conf files.
bce470
bce470
Config files in the `.d` directories, are added in alpha numeric sorted order and must end in `.conf`.
bce470
bce470
Not all options are supported in all container engines.
bce470
bce470
Note container engines also use other configuration files for configuring the environment.
bce470
bce470
* `storage.conf` for configuration of container and images storage.
bce470
* `registries.conf` for definition of container registires to search while pulling.
bce470
container images.
bce470
* `policy.conf` for controlling which images can be pulled to the system.
bce470
bce470
# FORMAT
bce470
The [TOML format][toml] is used as the encoding of the configuration file.
bce470
Every option is nested under its table. No bare options are used. The format of
bce470
TOML can be simplified to:
bce470
bce470
    [table1]
bce470
    option = value
bce470
bce470
    [table2]
bce470
    option = value
bce470
bce470
    [table3]
bce470
    option = value
bce470
bce470
    [table3.subtable1]
bce470
    option = value
bce470
bce470
## CONTAINERS TABLE
bce470
The containers table contains settings pertaining to the OCI runtime that can
bce470
configure and manage the OCI runtime.
bce470
bce470
**annotations** = []
bce470
List of annotations. Specified as "key=value" pairs to be added to all containers.
bce470
bce470
Example: "run.oci.keep_original_groups=1"
bce470
bce470
**apparmor_profile**="container-default"
bce470
bce470
Used to change the name of the default AppArmor profile of container engines.
bce470
The default profile name is "container-default".
bce470
bce470
**cgroups**="enabled"
bce470
bce470
Determines  whether  the  container will create CGroups.
bce470
Options are:
bce470
  `enabled`   Enable cgroup support within container
bce470
  `disabled`  Disable cgroup support, will inherit cgroups from parent
bce470
  `no-conmon` Do not create a cgroup dedicated to conmon.
bce470
bce470
**cgroupns**="private"
bce470
bce470
Default way to to create a cgroup namespace for the container.
bce470
Options are:
bce470
`private` Create private Cgroup Namespace for the container.
bce470
`host`    Share host Cgroup Namespace with the container.
bce470
bce470
**default_capabilities**=[]
bce470
bce470
List of default capabilities for containers.
bce470
bce470
The default list is:
bce470
```
bce470
default_capabilities = [
bce470
"AUDIT_WRITE",
bce470
      "CHOWN",
bce470
      "DAC_OVERRIDE",
bce470
      "FOWNER",
bce470
      "FSETID",
bce470
      "KILL",
bce470
      "MKNOD",
bce470
      "NET_BIND_SERVICE",
bce470
      "NET_RAW",
bce470
      "SETGID",
bce470
      "SETPCAP",
bce470
      "SETUID",
bce470
      "SYS_CHROOT",
bce470
]
bce470
```
bce470
bce470
**default_sysctls**=[]
bce470
bce470
A list of sysctls to be set in containers by default,
bce470
specified as "name=value".
bce470
bce470
Example:"net.ipv4.ping_group_range=0 1000".
bce470
bce470
**default_ulimits**=[]
bce470
bce470
A list of ulimits to be set in containers by default,
bce470
specified as "name=soft-limit:hard-limit".
bce470
bce470
Example: "nofile=1024:2048".
bce470
bce470
**devices**=[]
bce470
bce470
List of devices.
bce470
Specified as 'device-on-host:device-on-container:permissions'.
bce470
bce470
Example: "/dev/sdc:/dev/xvdc:rwm".
bce470
bce470
**dns_options**=[]
bce470
bce470
List of default DNS options to be added to /etc/resolv.conf inside of the
bce470
container.
bce470
bce470
**dns_searches**=[]
bce470
bce470
List of default DNS search domains to be added to /etc/resolv.conf inside of
bce470
the container.
bce470
bce470
**dns_servers**=[]
bce470
bce470
A list of dns servers to override the DNS configuration passed to the
bce470
container. The special value “none” can be specified to disable creation of
bce470
/etc/resolv.conf in the container.
bce470
bce470
**env**=["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "TERM=xterm"]
bce470
bce470
Environment variable list for the container process, used for passing
bce470
environment variables to the container.
bce470
bce470
**env_host**=false
bce470
bce470
Pass all host environment variables into the container.
bce470
bce470
**http_proxy**=true
bce470
bce470
Default proxy environment variables will be passed into the container.
bce470
The environment variables passed in include:
bce470
`http_proxy`, `https_proxy`, `ftp_proxy`, `no_proxy`, and the upper case
bce470
versions of these. The `no_proxy` option is needed when host system uses a proxy
bce470
but container should not use proxy. Proxy environment variables specified for
bce470
the container in any other way will override the values passed from the host.
bce470
bce470
**init**=false
bce470
bce470
Run an init inside the container that forwards signals and reaps processes.
bce470
bce470
**init_path**="/usr/libexec/podman/catatonit"
bce470
bce470
Path to the container-init binary, which forwards signals and reaps processes
bce470
within containers.  Note that the container-init binary will only be used when
bce470
the `--init` for podman-create and podman-run is set.
bce470
bce470
**ipcns**="private"
bce470
bce470
Default way to to create a IPC namespace for the container.
bce470
Options are:
bce470
  `private` Create private IPC Namespace for the container.
bce470
  `host`    Share host IPC Namespace with the container.
bce470
bce470
**keyring**=true
bce470
bce470
Indicates whether the container engines create a kernel keyring for use within
bce470
the container.
bce470
bce470
**label**=true
bce470
bce470
Indicates whether the container engine uses MAC(SELinux) container separation via labeling. This option is ignored on disabled systems.
bce470
bce470
**log_driver**="k8s-file"
bce470
bce470
Logging driver for the container. Available options: `k8s-file` and `journald`.
bce470
bce470
**log_size_max**=-1
bce470
bce470
Maximum size allowed for the container's log file. Negative numbers indicate
bce470
that no size limit is imposed. If it is positive, it must be >= 8192 to
bce470
match/exceed conmon's read buffer. The file is truncated and re-opened so the
bce470
limit is never exceeded.
bce470
bce470
**log_tag**=""
bce470
bce470
Default format tag for container log messages.  This is useful for creating a specific tag for container log messages. Container log messages default to using the truncated container ID as a tag.
bce470
bce470
**netns**="private"
bce470
bce470
Default way to to create a NET namespace for the container.
bce470
Options are:
bce470
  `private` Create private NET Namespace for the container.
bce470
  `host`    Share host NET Namespace with the container.
bce470
  `none`    Containers do not use the network.
bce470
bce470
**no_hosts**=false
bce470
bce470
Create /etc/hosts for the container.  By default, container engines manage
bce470
/etc/hosts, automatically adding  the container's  own  IP  address.
bce470
bce470
**pidns**="private"
bce470
bce470
Default way to to create a PID namespace for the container.
bce470
Options are:
bce470
  `private` Create private PID Namespace for the container.
bce470
  `host`    Share host PID Namespace with the container.
bce470
bce470
**pids_limit**=1024
bce470
bce470
Maximum number of processes allowed in a container. 0 indicates that no limit
bce470
is imposed.
bce470
bce470
**prepare_volume_on_create**=false
bce470
bce470
Copy the content from the underlying image into the newly created volume when the container is created instead of when it is started. If `false`, the container engine will not copy the content until the container is started. Setting it to `true` may have negative performance implications.
bce470
bce470
**rootless_networking**="slirp4netns"
bce470
bce470
Set type of networking rootless containers should use.  Valid options are `slirp4netns`
bce470
or `cni`.
bce470
bce470
**seccomp_profile**="/usr/share/containers/seccomp.json"
bce470
bce470
Path to the seccomp.json profile which is used as the default seccomp profile
bce470
for the runtime.
bce470
bce470
**shm_size**="65536k"
bce470
bce470
Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater
bce470
than `0`.
bce470
Unit is optional and can be:
bce470
`b` (bytes), `k` (kilobytes), `m`(megabytes), or `g` (gigabytes).
bce470
If you omit the unit, the system uses bytes. If you omit the size entirely,
bce470
the system uses `65536k`.
bce470
bce470
**tz=**""
bce470
bce470
Set timezone in container. Takes IANA timezones as well as `local`, which sets the timezone in the container to match the host machine.
bce470
If not set, then containers will run with the time zone specified in the image.
bce470
bce470
Examples:
bce470
  `tz="local"`
bce470
  `tz="America/New_York"`
bce470
bce470
**umask**="0022"
bce470
bce470
Sets umask inside the container.
bce470
bce470
**userns**="host"
bce470
bce470
Default way to to create a USER namespace for the container.
bce470
Options are:
bce470
  `private` Create private USER Namespace for the container.
bce470
  `host`    Share host USER Namespace with the container.
bce470
bce470
**userns_size**=65536
bce470
bce470
Number of UIDs to allocate for the automatic container creation. UIDs are
bce470
allocated from the “container” UIDs listed in /etc/subuid & /etc/subgid.
bce470
bce470
**utsns**="private"
bce470
bce470
Default way to to create a UTS namespace for the container.
bce470
Options are:
bce470
  `private` Create private UTS Namespace for the container.
bce470
  `host`    Share host UTS Namespace with the container.
bce470
bce470
bce470
## NETWORK TABLE
bce470
The `network` table contains settings pertaining to the management of CNI
bce470
plugins.
bce470
bce470
**cni_plugin_dirs**=["/opt/cni/bin/",]
bce470
bce470
List of paths to directories where CNI plugin binaries are located.
bce470
bce470
**default_network**="podman"
bce470
bce470
The network name of the default CNI network to attach pods to.
bce470
bce470
**default_subnet**="10.88.0.0/16"
bce470
bce470
The subnet to use for the default CNI network (named above in **default_network**).
bce470
If the default network does not exist, it will be automatically created the first time a tool is run using this subnet.
bce470
bce470
**network_config_dir**="/etc/cni/net.d/"
bce470
bce470
Path to the directory where CNI configuration files are located.
bce470
bce470
**volumes**=[]
bce470
bce470
List of volumes.
bce470
Specified as "directory-on-host:directory-in-container:options".
bce470
bce470
Example:  "/db:/var/lib/db:ro".
bce470
bce470
## ENGINE TABLE
bce470
The `engine` table contains configuration options used to set up container engines such as Podman and Buildah.
bce470
bce470
**active_service**=""
bce470
bce470
Name of destination for accessing the Podman service. See SERVICE DESTINATION TABLE below.
bce470
bce470
**cgroup_manager**="systemd"
bce470
bce470
The cgroup management implementation used for the runtime. Supports `cgroupfs`
bce470
and `systemd`.
bce470
bce470
**conmon_env_vars**=[]
bce470
bce470
Environment variables to pass into Conmon.
bce470
bce470
**conmon_path**=[]
bce470
bce470
Paths to search for the conmon container manager binary. If the paths are
bce470
empty or no valid path was found, then the `$PATH` environment variable will be
bce470
used as the fallback.
bce470
bce470
The default list is:
bce470
```
bce470
conmon_path=[
bce470
    "/usr/libexec/podman/conmon",
bce470
    "/usr/local/libexec/podman/conmon",
bce470
    "/usr/local/lib/podman/conmon",
bce470
    "/usr/bin/conmon",
bce470
    "/usr/sbin/conmon",
bce470
    "/usr/local/bin/conmon",
bce470
    "/usr/local/sbin/conmon",
bce470
    "/run/current-system/sw/bin/conmon",
bce470
]
bce470
```
bce470
bce470
**detach_keys**="ctrl-p,ctrl-q"
bce470
bce470
Keys sequence used for detaching a container.
bce470
Specify the keys sequence used to detach a container.
bce470
Format is a single character `[a-Z]` or a comma separated sequence of
bce470
`ctrl-<value>`, where `<value>` is one of:
bce470
`a-z`, `@`, `^`, `[`, `\`, `]`, `^` or `_`
bce470
bce470
**enable_port_reservation**=true
bce470
bce470
Determines whether the engine will reserve ports on the host when they are
bce470
forwarded to containers. When enabled, when ports are forwarded to containers,
bce470
they are held open by conmon as long as the container is running, ensuring that
bce470
they cannot be reused by other programs on the host. However, this can cause
bce470
significant memory usage if a container has many ports forwarded to it.
bce470
Disabling this can save memory.
bce470
bce470
**env**=[]
bce470
bce470
Environment variables to be used when running the container engine (e.g., Podman, Buildah).  For example "http_proxy=internal.proxy.company.com".
bce470
Note these environment variables will not be used within the container. Set the env section under [containers] table,
bce470
if you want to set environment variables for the container.
bce470
bce470
**events_logger**="journald"
bce470
bce470
Default method to use when logging events.
bce470
Valid values: `file`, `journald`, and `none`.
bce470
bce470
**hooks_dir**=["/etc/containers/oci/hooks.d", ...]
bce470
bce470
Path to the OCI hooks directories for automatically executed hooks.
bce470
bce470
**image_default_format**="oci"|"v2s2"|"v2s1"
bce470
bce470
Manifest Type (oci, v2s2, or v2s1) to use when pulling, pushing, building
bce470
container images. By default images pulled and pushed match the format of the
bce470
source image. Building/committing defaults to OCI.
bce470
Note: **image_build_format** is deprecated.
bce470
bce470
**image_default_transport**="docker://"
bce470
bce470
Default transport method for pulling and pushing images.
bce470
bce470
**image_parallel_copies**=0
bce470
bce470
Maximum number of image layers to be copied (pulled/pushed) simultaneously.
bce470
Not setting this field will fall back to containers/image defaults. (6)
bce470
bce470
**infra_command**="/pause"
bce470
bce470
Command to run the infra container.
bce470
bce470
**infra_image**="k8s.gcr.io/pause:3.4.1"
bce470
bce470
Infra (pause) container image name for pod infra containers.  When running a
bce470
pod, we start a `pause` process in a container to hold open the namespaces
bce470
associated with the  pod.  This container does nothing other then sleep,
bce470
reserving the pods resources for the lifetime of the pod.
bce470
bce470
**lock_type**="shm"
bce470
bce470
Specify the locking mechanism to use; valid values are "shm" and "file".
bce470
Change the default only if you are sure of what you are doing, in general
bce470
"file" is useful only on platforms where cgo is not available for using the
bce470
faster "shm" lock type.  You may need to run "podman system renumber" after you
bce470
change the lock type.
bce470
bce470
**machine_enabled**=false
bce470
bce470
Indicates if Podman is running inside a VM via Podman Machine.
bce470
Podman uses this value to do extra setup around networking from the
bce470
container inside the VM to to host.
bce470
bce470
**multi_image_archive**=false
bce470
bce470
Allows for creating archives (e.g., tarballs) with more than one image.  Some container engines, such as Podman, interpret additional arguments as tags for one image and hence do not store more than one image.  The default behavior can be altered with this option.
bce470
bce470
**namespace**=""
bce470
bce470
Default engine namespace. If the engine is joined to a namespace, it will see
bce470
only containers and pods that were created in the same namespace, and will
bce470
create new containers and pods in that namespace.  The default namespace is "",
bce470
which corresponds to no namespace. When no namespace is set, all containers
bce470
and pods are visible.
bce470
bce470
**network_cmd_path**=""
bce470
bce470
Path to the slirp4netns binary.
bce470
bce470
**network_cmd_options**=[]
bce470
bce470
Default options to pass to the slirp4netns binary.
bce470
bce470
Example "allow_host_loopback=true"
bce470
bce470
**no_pivot_root**=false
bce470
bce470
Whether to use chroot instead of pivot_root in the runtime.
bce470
bce470
**num_locks**=2048
bce470
bce470
Number of locks available for containers and pods. Each created container or
bce470
pod consumes one lock.  The default number available is 2048.  If this is
bce470
changed, a lock renumbering must be performed, using the
bce470
`podman system renumber` command.
bce470
bce470
**pull_policy**="always"|"missing"|"never"
bce470
bce470
Pull image before running or creating a container. The default is **missing**.
bce470
bce470
- **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.
bce470
- **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.
bce470
- **never**: do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally.
bce470
bce470
**remote** = false
bce470
Indicates whether the application should be running in remote mode. This flag modifies the
bce470
--remote option on container engines. Setting the flag to true will default `podman --remote=true` for access to the remote Podman service.
bce470
bce470
**runtime**=""
bce470
bce470
Default OCI specific runtime in runtimes that will be used by default. Must
bce470
refer to a member of the runtimes table. Default runtime will be searched for
bce470
on the system using the priority: "crun", "runc", "kata".
bce470
bce470
**runtime_supports_json**=["crun", "runc", "kata", "runsc"]
bce470
bce470
The list of the OCI runtimes that support `--format=json`.
bce470
bce470
**runtime_supports_kvm**=["kata"]
bce470
bce470
The list of OCI runtimes that support running containers with KVM separation.
bce470
bce470
**runtime_supports_nocgroups**=["crun"]
bce470
bce470
The list of OCI runtimes that support running containers without CGroups.
bce470
bce470
**static_dir**="/var/lib/containers/storage/libpod"
bce470
bce470
Directory for persistent libpod files (database, etc).
bce470
By default this will be configured relative to where containers/storage
bce470
stores containers.
bce470
bce470
**stop_timeout**=10
bce470
bce470
Number of seconds to wait for container to exit before sending kill signal.
bce470
bce470
**tmp_dir**="/run/libpod"
bce470
bce470
The path to a temporary directory to store per-boot container.
bce470
Must be a tmpfs (wiped after reboot).
bce470
bce470
**volume_path**="/var/lib/containers/storage/volumes"
bce470
bce470
Directory where named volumes will be created in using the default volume
bce470
driver.
bce470
By default this will be configured relative to where containers/storage store
bce470
containers. This convention is followed by the default volume driver, but may
bce470
not be by other drivers.
bce470
bce470
**chown_copied_files**=true
bce470
bce470
Determines whether file copied into a container will have changed ownership to
bce470
the primary uid/gid of the container.
bce470
bce470
## SERVICE DESTINATION TABLE
bce470
The `service_destinations` table contains configuration options used to set up remote connections to the podman service for the podman API.
bce470
bce470
**[service_destinations.{name}]**
bce470
URI to access the Podman service
bce470
**uri="ssh://user@production.example.com/run/user/1001/podman/podman.sock"**
bce470
bce470
  Example URIs:
bce470
bce470
- **rootless local**  - unix://run/user/1000/podman/podman.sock
bce470
- **rootless remote** - ssh://user@engineering.lab.company.com/run/user/1000/podman/podman.sock
bce470
- **rootfull local**  - unix://run/podman/podman.sock
bce470
- **rootfull remote** - ssh://root@10.10.1.136:22/run/podman/podman.sock
bce470
bce470
**identity="~/.ssh/id_rsa**
bce470
bce470
Path to file containing ssh identity key
bce470
bce470
**[engine.volume_plugins]**
bce470
bce470
A table of all the enabled volume plugins on the system. Volume plugins can be
bce470
used as the backend for Podman named volumes. Individual plugins are specified
bce470
below, as a map of the plugin name (what the plugin will be called) to its path
bce470
(filepath of the plugin's unix socket).
bce470
bce470
bce470
## SECRET TABLE
bce470
The `secret` table contains settings for the configuration of the secret subsystem.
bce470
bce470
**driver**=file
bce470
bce470
Name of the secret driver to be used.
bce470
Currently valid values are:
bce470
  * file
bce470
  * pass
bce470
bce470
**[secrets.opts]**
bce470
bce470
The driver specific options object.
bce470
bce470
# FILES
bce470
bce470
**containers.conf**
bce470
bce470
Distributions often provide a `/usr/share/containers/containers.conf` file to
bce470
define default container configuration. Administrators can override fields in
bce470
this file by creating `/etc/containers/containers.conf` to specify their own
bce470
configuration. Rootless users can further override fields in the config by
bce470
creating a config file stored in the `$HOME/.config/containers/containers.conf` file.
bce470
bce470
If the `CONTAINERS_CONF` path environment variable is set, just
bce470
this path will be used.  This is primarily used for testing.
bce470
bce470
Fields specified in the containers.conf file override the default options, as
bce470
well as options in previously read containers.conf files.
bce470
bce470
**storage.conf**
bce470
bce470
The `/etc/containers/storage.conf` file is the default storage configuration file.
bce470
Rootless users can override fields in the storage config by creating
bce470
`$HOME/.config/containers/storage.conf`.
bce470
bce470
If the `CONTAINERS_STORAGE_CONF` path environment variable is set, this path
bce470
is used for the storage.conf file rather than the default.
bce470
This is primarily used for testing.
bce470
bce470
# SEE ALSO
bce470
containers-storage.conf(5), containers-policy.json(5), containers-registries.conf(5)
bce470
bce470
[toml]: https://github.com/toml-lang/toml