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

Mutable state: /var, /home, and /etc

For a system to function, it must accommodate changes to configuration, logs, and user data. OSTree designates specific directories as mutable, but not all mutable directories behave the same way in AutoSD.

Persistent state: /var and /home

The /var (variable runtime data) and /home (user data) directories hold persistent state. Changes made during runtime are preserved across reboots, system upgrades, and rollbacks. The OSTree core does not modify content in /var, making it a safe location for application data, logs, container storage, and any other runtime state that must survive updates.

Transient configuration: /etc

In standard OSTree deployments, /etc is persistent and a three-way merge preserves local configuration changes across upgrades. AutoSD does not use that model.

AutoSD enables transient /etc by setting transient = true in the [etc] section of /usr/lib/ostree/prepare-root.conf. With transient /etc enabled:

• The /etc directory is writable at runtime, so services can generate host-specific files such as machine IDs, SSH host keys, and network leases during normal operation.
• All changes to /etc are discarded on reboot. The next boot regenerates /etc from the contents baked into the OS image.
• Unlike standard OSTree deployments, no three-way merge takes place during upgrades. The new image’s /etc replaces the previous one entirely.

This behavior eliminates configuration drift between the deployed image and the running system, which is a key requirement for security and reliability for automotive platforms where vehicles must boot into a known, reproducible state.

To apply persistent configuration in AutoSD, use one of the following approaches:

• Build configuration into the image: Add files to /etc in the AIB manifest so that they are part of every deployment.
• Apply configuration at boot time: Use systemd units, tmpfiles.d snippets, or other boot-time mechanisms to generate or overlay configuration on each startup.
• Store machine-specific state in /var: For data that must persist across reboots but does not belong in the image, write to /var and configure services to read from that location.