Configuration files in /etc and /usr/etc

By Thorsten Kukuk | Dec 5, 2019


As some may have already noticed, openSUSE MicroOS introduced a /usr/etc directory and some configuration files are already moved to this directory.

What’s behind this move? For a better understanding, let’s first look how configuration files are handled by RPM today:

RPM and Configuration Files

RPM has limited support for updating configuration files. In the end this consist of two simple choices:

  • modified configuration files are moved away during upgrade and the admin has to redo the changes (.rpmsave files).
  • modfied configuration files are kept and changes done by the distribution are ignored (.rpmnew files). In the end the service may not work or could even be insecure!

Both options are not really user friendly and will most likely lead to a broken or insecure service after an upgrade, which requires manual work by the admin. On desktop systems or a simple server this may be tolerable, but for big clusters this can lead to a huge amount of work.

There are several alternative solutions for this like Three-Way-Diff or doing the update interactively, but the first one does not solve the problem if conflicting changes are done, and the second one is no solution for fully automated updates.

Atomic Updates

For atomic systems another layer of complexity is added, because different states may contain different versions of a configuration file. So how can this happen? An atomic update is a kind of update that:

  • Is atomic
    • The update is either fully applied or not applied at all
    • The update does not influence your running system
  • Can be rolled back
    • If the update fails or if the update is not compatible, you can quickly restore the situation as it was before the update

The update will be activated by rebooting into the new state, so after an update, before the reboot, the changes done by the update are not visible. If an admin or configuration management software changes the configuration files in the runnung system during this time, this will create conflicts, and needs manual interaction again.


The goal is to provide a concept working for most packages and their configuration files, which makes automatic updates much easier and robust. For that a new way to store and manage configuration files is needed.

Requirements for a Solution

The new solution should make sure that:

  • It’s visible to the admin that something got updated
  • It’s visible which changes the admin made
  • Package and admin changes should be merged automatically
  • There should be only one directory to search for default configuration files


As a longterm solution no package should install anything into /etc any more, this directory should only contain host specific configuration files created during installation and changes made by the system administrator. Packages are supposed to install their default configuration files to another directory instead.

For SUSE/openSUSE the decision was made to use /usr/etc as the directory for the distribution provided configuration files.

For merging the package and admin configuration files there will have to be different strategies depending on the file type; the files can be categorized as follows:

  1. Configuration files for applications
  2. Configuration files for the system (network, hardware, …)
  3. “Databases” like files (/etc/rpc, /etc/services, /etc/protocols)
  4. System and user accounts (/etc/passwd, /etc/group, /etc/shadow)

Application Configuration Files

For application configuration files there is already a good solution used by systemd, which could be adopted for most applications:

  • /usr/etc/app.conf is the distribution provided configuration file.
  • If it exists, /etc/app.conf replaces /usr/etc/app.conf.
  • /etc/app.conf.d/*.conf contains snippets overiding single entries from /usr/etc/app.conf or /etc/app.conf.

The workflow for the application to load the configuration file would be:

  • Application looks for /etc/app.conf.
  • If this file does not exist, load /usr/etc/app.conf.
  • Look for overides in /etc/app.conf.d and merge them.

See, “Overriding vendor settings” for more details and examples. A C library which provides a simple interface and implements above loading mechanism transparently for the application is libeconf.

Depending on the configuration file format above patterns may not work for all applications. For those applications a solution following the above guidelines as closely as possible should be found.

System Configuration Files (network, hardware, …)

As these configuration files are system specific and only created during or after installation and not provided by the distribution, these files will stay in /etc.

System Databases (rpc, services, protocols)

There are files in /etc which, strictly speaking, are no configuration files, such as /etc/rpc, /etc/services and /etc/protocols. They are changed very rarely, but sometimes new system applications or third party software need to make additions. These files will be moved to /usr/etc; /etc/nsswitch.conf has to be changed to search in /etc first and in /usr/etc second. A glibc NSS plugin usrfiles will be used for this. /etc will contain only the changes done by the admin and third party software.

/etc/passwd, /etc/group and /etc/shadow

There is no solution yet for these configuration files which would really solve the problems. Ideas are welcome!

Further Documentation