containers-config(5)

File Formats Manual

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