Did You Know? How ostree update merges changes into etc and var

Bluefin
1

Did You Know? How ostree (rpm-ostree) update merges changes into etc and var

As I continued my deep dive into bluefin, I realized that changes being made to the bluefin bootc image did not appear to handle deletion of files other than to not include them in the image.

This made me wonder, what happens to the files in the read-write filesystems of an existing install?

ostree Filesystems

The /etc and /var directories are the only writeable dirs (according to Atomic transitions between parallel-installable read-only filesystem trees). Whereas /usr and peers are read only.

In addition, according to System layout (at the time of writing) the standard root filesystem has these symlinks.

  • /home → /var/home
  • /opt → /var/opt
  • /srv → /var/srv
  • /root → /var/roothome
  • /usr/local → /var/usrlocal
  • /mnt → /var/mnt
  • /tmp → /sysroot/tmp

3-way Merge of Changes to /etc; Creation of /var

The Assembling a new deployment directory section describes how the merge of /etc is performed. There is a dir - /usr/etc - delivered with the update that serves as the declaration of a desired target state.
If a file exists in /etc that no longer exists in /usr/etc AND has not been modified, it is removed.
Otherwise files in /usr/etc replace their counterpart in /etc if they have not been modified.
If a file in /etc has been modified or added it is not touched (propagated forever).

The last paragraph of the Assembling a new deployment directory section offers:

You can use ostree admin config-diff to see the differences between your booted deployment’s /etc and the OSTree defaults. A command like diff {/usr,}/etc will additional print line-level differences.

OSTree and /var handling covers the nuance involving the creation of /var.

And as mentioned in rpm-ostree Filesystem layout (at the time of writing):

Any data in /var is never touched, and is shared across upgrades.

Summary

In short, the /etc filesystem is maintained via a sophisticated 3-way merge mechanism. Tools are available to discover files that are different from the current booted version. To bring the contents of /etc in sync carefully copy specific files from /usr/etc and reboot.

I recommend that you maintain a log of any changes made to /etc to simplify the process. But, please be disciplined about minimizing changes. There are usually other ways to override what is in /etc.

The /var filesystem is much like a VOLUME /var Docker declaration. It is populated during the first install and not touched after that.

After all, the term var means variable, but persistent. Nothing in there is strictly required for the OS version to function. But it does hold local system state - /var/home. So again be careful what changes you make in there.

Hopefully this article highlights some of the reasons why we chose to use an Atomic desktop in the first place.

References

The documentation for both ostree and rpm-ostree are pretty thorough. And should be considered a must read for those who desire to dig deeper.

13 Likes