Skip to content

Understanding OSTree file system

Understanding OSTree file system

A fundamental concept in OSTree is the distinction between immutable and mutable parts of the filesystem. This architectural model is designed to provide system robustness and support for atomic upgrades by separating the read-only core OS from the writable system and user data.

The immutable core: /usr

The core operating system, primarily residing in the /usr directory, is treated as an immutable artifact. This immutability is established and enforced in two key stages:

  • Build-Time: The operating system is assembled into a fixed, read-only image. This image is version-controlled, much like a commit in a source code repository, creating a verifiable and reproducible unit.
  • Run-Time: When the system is operational, the immutability of the build is enforced by mounting the /usr directory as read-only. A read-only /usr directory prevents direct modification of core system files, ensuring the integrity and stability of the base operating system.

Because its contents are managed by the system's package manager, dnf, any changes, such as updates or security patches, result in a new OSTree commit rather than modifying the live system. This immutability ensures system integrity and allows for atomic updates and rollbacks.

The following directories are typically symbolic links to their counterparts within /usr, effectively making them immutable as well:

  • /bin → /usr/bin
  • /sbin → /usr/sbin
  • /lib → /usr/lib
  • /lib64 → /usr/lib64
Persistent mutable state: /etc, /var, /home

For a system to function, it must accommodate changes to configuration, logs, and user data. OSTree designates specific directories like /etc (system configuration), /var (variable runtime data), and /home (user data) as mutable.

A critical feature of this design is that the state within these directories is persistent. Changes made during runtime are preserved across reboots, system upgrades, and rollbacks. During an OS update, OSTree intelligently handles changes to /etc to ensure local modifications are preserved. It performs a three-way merge between:

  1. The default configuration from the new OS version in /usr/etc
  2. The default configuration from the old OS version
  3. The currently active (modified) configuration in /etc

This separation allows the underlying immutable OS to be atomically replaced while ensuring that critical system configurations and data persist.

Examples of mutable directories you can find under /etc include:

  • /etc/containers
  • /etc/hostname
  • /etc/systemd
  • /etc/fstab
  • /etc/ssh

This process ensures that local modifications to configuration files are preserved across updates. Therefore, all directories and files directly within /etc are mutable by design to permit system configuration.