containers-config(5)

NAME
containers-config - Rules for loading container engine configuration files

DESCRIPTION
This document describes the loading order of the containers.conf(5), containers-storage.conf(5) and containers-registries.conf(5). Refer to their individual man pages for more details on the file formats.

Search Locations
In the following paths <name> is a placeholder for either containers, storage, or registries depending on the specific config file.

The paths are listed from lowest to highest precedence (i.e. later paths override / are preferred over the earlier paths, see below for details).

Linux and macOS
System defaults:

•   /usr/share/containers/<name>.conf

•   /usr/share/containers/<name>.conf.d/

•   /usr/share/containers/<name>.rootful.conf.d/ (only when UID == 0)

•   /usr/share/containers/<name>.rootless.conf.d/ (only when UID > 0)

•   /usr/share/containers/<name>.rootless.conf.d/<UID>/ (only when UID > 0)

Admin overrides:

•   /etc/containers/<name>.conf

•   /etc/containers/<name>.conf.d/

•   /etc/containers/<name>.rootful.conf.d/ (only when UID == 0)

•   /etc/containers/<name>.rootless.conf.d/ (only when UID > 0)

•   /etc/containers/<name>.rootless.conf.d/<UID>/ (only when UID > 0)

User overrides:

•   $XDG_CONFIG_HOME/containers/<name>.conf or if $XDG_CONFIG_HOME is unset then $HOME/.config/containers/<name>.conf

•   $XDG_CONFIG_HOME/containers/<name>.conf.d/ or if $XDG_CONFIG_HOME is unset then $HOME/.config/containers/<name>.conf.d/

FreeBSD
System defaults:

•   /usr/local/share/containers/<name>.conf

•   /usr/local/share/containers/<name>.conf.d/

•   /usr/local/share/containers/<name>.rootful.conf.d/ (only when UID == 0)

•   /usr/local/share/containers/<name>.rootless.conf.d/ (only when UID > 0)

•   /usr/local/share/containers/<name>.rootless.conf.d/<UID>/ (only when UID > 0)

Admin overrides:

•   /usr/local/etc/containers/<name>.conf

•   /usr/local/etc/containers/<name>.conf.d/

•   /usr/local/etc/containers/<name>.rootful.conf.d/ (only when UID == 0)

•   /usr/local/etc/containers/<name>.rootless.conf.d/ (only when UID > 0)

•   /usr/local/etc/containers/<name>.rootless.conf.d/<UID>/ (only when UID > 0)

User overrides:

•   $XDG_CONFIG_HOME/containers/<name>.conf or if $XDG_CONFIG_HOME is unset then $HOME/.config/containers/<name>.conf

•   $XDG_CONFIG_HOME/containers/<name>.conf.d/ or if $XDG_CONFIG_HOME is unset then $HOME/.config/containers/<name>.conf.d/

Windows
There is no location for system defaults.

Admin overrides:

•   %ProgramData%\containers\<name>.conf

•   %ProgramData%\containers\<name>.conf.d\

User overrides:

•   %APPDATA%\containers\<name>.conf

•   %APPDATA%\containers\<name>.conf.d\

Load Order
The search locations are split into two file categories, the main files and the drop-in directories.

Only one main file, <name>.conf, will be loaded: the highest-precedence file that exists. If no <name>.conf file exists, no main file is loaded, which is valid too.

After the main file, drop-in directories are loaded. Each file can override settings set in earlier files. Files within the directory must be suffixed with .conf, otherwise they get ignored.

All drop-in files will be sorted in the lexicographic order of the file name, if there are two or more drop-in files with the same file name only the one with the highest precedence will be used and thus replaces the prior one.

EXAMPLES

Example 1

•   ~~/usr/share/containers/containers.conf~~ (overridden by $XDG_CONFIG_HOME/containers/containers.conf and thus not read)

•   $XDG_CONFIG_HOME/containers/containers.conf

•   /usr/share/containers/containers.conf.d/00-vendor.conf

•   ~~/etc/containers/containers.conf.d/50-myconf.conf~~ (overridden by $XDG_CONFIG_HOME/containers/containers.conf.d/50-myconf.conf and thus not read)

•   $XDG_CONFIG_HOME/containers/containers.conf.d/50-myconf.conf

•   /usr/share/containers/containers.conf.d/99-conf.conf

Example 2
Consider the following files with their contents:

~~/usr/share/containers/containers.conf~~ (overridden by /etc/containers/containers.conf):
    field_1 = a

/etc/containers/containers.conf:
    field_2 = b

~~/usr/share/containers/containers.conf.d/10-vendor.conf~~ (overridden by $XDG_CONFIG_HOME/containers/containers.conf.d/10-vendor.conf):
    field_3 = c

/usr/share/containers/containers.conf.d/99-important.conf:
    field_4 = d

/usr/share/containers/containers.rootless.conf.d/50-my.conf:
    field_5 = e

$XDG_CONFIG_HOME/containers/containers.conf.d/10-vendor.conf:
    # empty

$XDG_CONFIG_HOME/containers/containers.conf.d/33-opt.conf (this is read but field_4 is overridden by /usr/share/containers/containers.conf.d/99-important.conf as 99-important.conf is sorted later):
    field_4 = user
    field_6 = f

Now parsing this as user with UID 1000 results in this final config:
    field_2 = b
    field_4 = d
    field_5 = e
    field_6 = f

SEE ALSO
containers.conf(5), containers-storage.conf(5), containers-registries.conf(5)