Mastodon Skip to content
BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak. BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak. BlueBuild

Place your system configuration files in /etc/

Hello BlueBuilders!

In this blog post, I will explain why the usage of /etc/ is now recommended over /usr/etc/ when building custom images of atomic Fedora.

We, and many others in the community have recommended previously that the system configuration files in custom images should be placed in /usr/etc/, while files in /etc/ are reserved for local-users. While it is true that in run-time the /usr/etc/ directory contains the original configuration of the image, this is technically undefined behavior build-time.

Technically, files written to /etc/ in the custom image are what populates /usr/etc/ on a system rebased to that image.

It is thanks to a recent discovery by the Universal Blue folks & the Rechunk developer Antheas that ostree has different behavior regarding /usr/etc/ & /etc/ in build-time vs in run-time.
Thanks to the RedHat employee & ostree maintainer Colin Walters who directly notified Universal Blue folks of this.

Why to transition

When files are placed to /usr/etc/ in build-time, currently there are no issues & everything works as expected for now.

However, it is still not the ideal thing to do, since we are relying on undefined rpm-ostree behavior, which may stop working some time in the future. Quoting Antheas:

When OSTree commits get converted to OCI, /usr/etc/ becomes /etc/. Then during deployment, new /etc/ files are silently moved to /usr/etc/.

Relying on /usr/etc/ to place modified files in customized packages is a hack and relies on undefined behavior in the rpm-ostree source code that performs the path rewriting.

(Take a note that we are utilizing an OCI image, so this part can be ignored: When OSTree commits get converted to OCI, /usr/etc/ becomes /etc/.)

As can be seen from the 1st paragraph of the note above, this is how ostree functions & this is why it’s desired to transition to /etc/. /etc/ files in the image are copied to /usr/etc/ during deployment, so local-users will experience no changes.

How to transition

  1. It is highly recommended that you follow & complete The Caching Update & Updating the directory structure blog post updates
  2. If you’re working with a 1-to-1 filetree mapping structure, where you copy files & folders to the root (/) folder, then do the following (source-folder is the folder defined in source key inside files module recipe entry):
  • Move files from files/system/usr/etc/ to files/system/etc/ (or replace system with the name of the specific directory)
  1. If you copy files to the image in other ways, then any files that go to /usr/etc/ should be copied to go to /etc/ according, including files copied by custom scripts.
  2. You’re good to go! Commit your changes and wait to see that your custom image builds correctly.
Published on 2024-08-11.
Authors:
fiftydinar
@fiftydinar