This wiki was updated to MediaWiki 1.37. If you notice any issues, please report them to admin[at]

openSUSE:Packaging UsrEtc

Jump to: navigation, search

This document describes how openSUSE wants to handle the configuration file split between /etc and /usr/etc


The handling of RPM for configuration file updates is not good. While it was acceptable for standard distributions (but even there led to many bug reports, as users had to manually merge their changes, seldom did that, and then wondered why their service didn't work anymore), for transactional-updates this doesn't work anymore at all. The goal is, to separate the distribution provided configuration files from the changes the admin makes.

What do we want to do?

Longterm, /etc will only contain configuration files that are host specific or have been modified by the admin. All distribution provided configuration files are located below /usr/etc and are not modifiable by the admin (with a read-only root filesystem, this wouldn't even be possible). Instead, the applications need to be enhanced, as far as possible and necessary, to read the configuration files from several locations. Additionally, the distribution provided configuration files should be moved from /usr/lib and consolidated in /usr/etc as far as possible.

What does this mean for the system administrator?


Check for *.rpmnew and *.rpmsave files! It's even more important now, that distribution made changes and administrator made changes get merged in a timely manner. Make sure, libnss_usrfiles2 is installed and /etc/nsswitch.conf contains:

 services:       files usrfiles
 protocols:      files usrfiles
 rpc:            files usrfiles
 ethers:         files usrfiles

Variant 1 (ideal case)

In the ideal case, an application reads the configuration files from four places:

  1. /usr/etc/example.conf
  2. /usr/etc/example.conf.d/*.conf
  3. /etc/example.conf
  4. /etc/example.conf.d/*.conf

/usr/etc/example.conf or /usr/etc/example.conf.d always exists and will be provided by the distributor. This file must never be touched by an administrator. If /etc/example.conf exists, /usr/etc/example.conf and /usr/etc/example.conf.d will be ignored and only /etc/example.conf will be used. Which means, this file needs to be a full copy. Additionally, all files from /etc/example.conf.d/*.conf will be read in alphabetical order and applied to the entries of the full configuration file; so overlapping changes from the most recently read files win.

If a system administrator wants to change a configuration variable, he has to drop a file with that change into /etc/example.conf.d/, e.g. /etc/example.conf.d/override.conf.

Variant 2

If there is no support for /etc/example.conf.d/*.conf, /usr/etc/example.conf will always be used and /etc/example.conf contains only the overrides. An example for this is transactional_update.

Variant 3

If the configuration file is something complex which does not allow overrides of single entries, /etc/example.conf must be a full copy of /usr/etc/example.conf and will be the only file read.

What does this mean for the developer/packager?

The developer/packager has to modify the package to fit into one of the three above variants. Files in /usr/etc must not be marked as configuration file (%config).

RPM Macros

There will be a new RPM macro for this directory:

%_distconfdir  /usr/etc

This allows distributions to change the directory for their need if necessary.

Moving of configuration files

If configuration files marked as %config(noreplace) are moved from /etc to /usr/etc, and the admin did modify them, RPM will save the modified configuration files as *.rpmsave files at the end of the update process. This files need to be renamed back to the original file name. To make sure, that not old, outdated *.rpmsave configuration files are suddently active again after an update, this files should be moved away at the beginning of the update process. For pam the following two sections, %pre and %posttrans, solved this:

 for i in securetty pam.d/other pam.d/common-account pam.d/common-auth pam.d/common-password pam.d/common-session ; do
   test -f /etc/${i}.rpmsave && mv -v /etc/${i}.rpmsave /etc/${i}.rpmsave.old ||:
 # Migration to /usr/etc.
 for i in securetty pam.d/other pam.d/common-account pam.d/common-auth pam.d/common-password pam.d/common-session ; do
   test -f /etc/${i}.rpmsave && mv -v /etc/${i}.rpmsave /etc/${i} ||:

Be aware, that during the time of package got updated until all updates are applied, when the %posttrans section gets executed, the package could be broken and not be useable in pre/post install sections of other RPMs!

Additional helper tools

We are currently developing libeconf, a library which can read nearly all kinds of key/value configuration files and automatically combines all configuration files in the correct order to present them to the application. This could help in many cases to adjust the applications.



PAM configuration file for vlock was moved to /usr/etc/pam.d, see pam for configuration.


The default configuration file are stored in /usr/etc/kubicd/, the overrides are stored in /etc/kubicd/ (Variant 2).


/etc/lesskey and the corresponding /etc/lesskey.bin were moved to /usr/etc, aaa_base prefers the /etc version over the /usr/etc version (Variant 3).


The files ethers, networks, protocols and services where moved to /usr/etc. /etc/nsswitch.conf was adjusted to read at first the files in /etc, and if there is no file or the file does not contain the searched entry, it will read the file in /usr/etc (Variant 2).


/etc/ssh/sshd_config was moved to /usr/etc/ssh/sshd_config, /etc/ssh/sshd_config and /etc/ssh/sshd_config.d/*.conf will be additional looked at (Variant 1). The /etc/ssh/sshd_config.d method should be preferred, but is not useable for all config options. The same applies for /etc/ssh/ssh_config.


/etc/permissions and /etc/permissions.* except permissions.local are no configuration files nor templates and no admin should modify them. For this reasons they were moved to /usr/share/permissions. The distribution specific snippets in /etc/permissions.d will be moved to /usr/etc/permissions.d.


PAM reads the configuration files from two places:

  1. /usr/etc/pam.d
  2. /etc/pam.d

pam-config reads the configuration files from this two places, too. But it only writes into /etc/pam.d.

If a file in /etc/pam.d exists, a file with the same name in /usr/etc/pam.d will be ignored. A system administrator has, to make manual changes, copy the PAM config file from /usr/etc/pam.d/ to /etc/pam.d/ and modify that.

Some PAM modules are using variables from login.defs. Variant 1 is used for this, means /usr/etc/login.defs, /etc/login.defs and /etc/login.defs.d/*.defs will be looked at. is reading the securetty file. It will look at first if /etc/securetty exists, if not, and only in this case, /usr/etc/securetty is used (Variant 3).

Accepted upstream: pull request.


The distribution provided configuration file is /usr/etc/rebootmgr.conf. Changes are written into /etc/rebootmgr.conf and are merged during start of rebootmgrd (Variant 2).


/etc/login.defs was moved to /usr/etc/login.defs, /etc/login.defs and /etc/login.defs.d/*.defs will be additional looked at (Variant 1).

PAM configuration files were moved to /usr/etc/pam.d, see pam for configuration.

Accepted upstream pull request.


PAM configuration files were moved to /usr/etc/pam.d, see pam for configuration.


  • /etc/sudoers needs to be moved to /usr/etc
  • /etc/sudoers.d needs a /usr/etc/sudoers.d fallback directory for distribution config snippets
  • /etc/openldap/schema needs to be moved to /usr/etc/openldap/schema, needs openldap adjustments.


transactional-update reads at first /usr/etc/transactional-update.conf and merges it afterwards with /etc/transactional-update.conf (Variant 2).


/etc/login.defs are read through libeconf from /etc and /usr/etc (Variant 1). If /etc/default/su does not exist /usr/etc/default/su is read (Variant 3).

PAM configuration files were moved to /usr/etc/pam.d, see pam for configuration.

Upstream pull request.


Files in

  1. /usr/etc/profile.d
  2. /etc/profile.d

are read, prefering the ones in /etc/profile.d.


The host admin has to maintain /etc/slp.reg.d, it should not be packaged, may become %doc. The host may announce unwanted or wrong data, depending on how the service is configured. (comment by Olaf Hering on


/usr/etc/xdg/autostart can also be used now in addition to /etc/xdg/autostart directory. See boo#1173316


Somebody needs to rewrite logrotate first. boo#1173319


/usr/etc/skel is now read in addition to /etc/skel. Files and directories in /etc/skel are preferred. More details in boo#1173321

/etc/rpm/* macros

Use /usr/lib/rpm/macros.d instead, i.e. %{_rpmmacrodir}.