/etc: transactional-update Documentation

/etc

transactional-update also supports write operations to /etc on an otherwise read-only file system. To do so /etc is created as a nested BTRFS subvolume of the root file system.

In versions prior to 5.0.0 /etc was handled via an overlay file system). Existing overlayfs based systems are converted automatically.

Sometimes files in /etc are modified after the snapshot has been taken, but before the system is rebooted, e.g. if a configuration management software is still changing files. These files will be copied to the new system on boot, but only if the file hasn't been modified in the new system, too.

To track the changes of both the old and the new snapshot a temporary third nested reference snapshot of /etc called etc.syncpoint is created in the new snapshot's /etc directory. This snapshot will be deleted again after synchronization. Due to the copy-on-write nature of BTRFS' snapshots this consumes only minimal space and and time.

Example 1. Snapshot layout

	> btrfs subvolume list / -uq
	ID 268 gen 39 top level 257 parent_uuid 256c1975-3b58-9540-b43e-788e32cb6d55 uuid 06388703-67ae-804f-92b0-0bf486df0a7e path @/.snapshots/2/snapshot
	ID 269 gen 55 top level 257 parent_uuid 06388703-67ae-804f-92b0-0bf486df0a7e uuid d3d13005-95b6-1849-a28e-ba250b465c19 path @/.snapshots/3/snapshot
	ID 270 gen 68 top level 269 parent_uuid -				    uuid f77f0c38-1b32-7744-b3fe-bc515099556f path @/.snapshots/3/snapshot/etc
	ID 275 gen 61 top level 257 parent_uuid d3d13005-95b6-1849-a28e-ba250b465c19 uuid a279eb7b-11b0-4749-a9fd-1f0ad7d65f30 path @/.snapshots/4/snapshot
	ID 276 gen 62 top level 275 parent_uuid f77f0c38-1b32-7744-b3fe-bc515099556f uuid 3e4d7e76-2207-6540-a54d-51f92ce9299a path @/.snapshots/4/snapshot/etc
	ID 277 gen 62 top level 276 parent_uuid 3e4d7e76-2207-6540-a54d-51f92ce9299a uuid c8d8ec58-eccd-7a4d-8818-cde7043ba029 path @/.snapshots/4/snapshot/etc/etc.syncpoint

Snapshot 2 is an old snapshot not using /etc subvolumes yet.

Snapshot 3 is a snapshot that has been used already. This is how it will usually look like.

Snapshot 4 is a snapshot that has been created, but hasn't been booted yet - the synchronization snapshot is still present.

When the new snapshot is booted for the first time the systemd service transactional-update-sync-etc-state will copy changed files from the old snapshot if required.

If a file has been modified both in the new snapshot and in the currently running system after the snapshot was created, then the changes done in the currently running system will be lost in the new snapshot.

/etc snapshot management is handled via a snapper plugin (/usr/lib/snapper/plugins/50-etc). This makes it possible to use snapper directly, e.g. to create a manual backup snapshot of the system.