Managing Software on openSUSE MicroOS: Transactional Updates and the Read-Only Root

Why MicroOS Updates Differ from Traditional Distributions

openSUSE MicroOS does not apply package changes to the running filesystem. Instead, every update or package installation creates a new Btrfs snapshot, installs into that snapshot, and makes it the default boot target. The active root filesystem remains read-only until the next reboot, at which point the system atomically switches to the new snapshot. This design eliminates partial-update states and allows instant rollback by selecting a previous snapshot in the bootloader.

If you are accustomed to zypper install or dnf upgrade taking effect immediately, the workflow shift is the first hurdle: you must use the transactional-update wrapper, and changes only appear after a reboot.

Core Mechanism: Snapshots, Not In-Place Writes

The transactional-update tool orchestrates three steps:

1. Create a new read-write Btrfs snapshot of the current root subvolume.
2. Run zypper inside that snapshot to install, update, or remove packages.
3. Mark the snapshot as the default boot entry via grub2-editenv.

The running system continues on the old snapshot. Only a reboot activates the new one. This is atomic: either the new snapshot boots cleanly, or you select the previous entry in GRUB and you are back to the exact prior state.

Worked Example: Installing a Package

Suppose you need vim on a fresh MicroOS installation. Running zypper install vim fails with a read-only filesystem error. Instead:

# Run as root or via sudo
transactional-update pkg install vim

Output shows the snapshot creation and zypper transaction:

Creating new snapshot...
Snapshot 12 created.
Mounting snapshot...
Executing zypper install vim...
Loading repository data...
Reading installed packages...
Resolving package dependencies...

The following 5 NEW packages are going to be installed:
  vim vim-data vim-lang gpm-libs libperl5_38

5 new packages to install.
Overall download size: 3.2 MiB. Already cached: 0 B.
After the operation, additional 12.4 MiB will be used.
Continue? [y/n/v/...? shows all options] (y): y
...
Unmounting snapshot...
Setting default boot entry to snapshot 12.
Run 'systemctl reboot' to activate the new snapshot.

Verify the new snapshot exists:

snapper list

You will see snapshot 12 with type post and a description like transactional-update pkg install vim. The current root remains snapshot 11 (or whatever was active). Reboot to switch:

systemctl reboot

After reboot, vim --version confirms the package is present. The root filesystem is again read-only; touch /usr/test fails with Read-only file system.

Configuration Handling: /etc Overlays

Because the root is read-only, /etc cannot be written directly. MicroOS uses an overlayfs mount: the lower layer is the snapshot's /etc, the upper layer is a persistent writable directory under /var/overlay. When you edit a file in /etc, the change lands in the upper layer and persists across reboots and snapshot switches.

This means:

• Configuration changes survive updates and rollbacks.
• Package-provided config updates in /etc do not automatically merge; you must manage .rpmnew files manually or use transactional-update hooks.
• Direct writes to /etc on the snapshot (e.g., via a bind mount into a container) affect only the upper layer, not the snapshot itself.

To inspect the overlay layout:

mount | grep overlay

Typical output shows overlay on /etc type overlay (rw,relatime,lowerdir=/.snapshots/12/snapshot/etc,upperdir=/var/overlay/12/etc,workdir=/var/overlay/12/work).

Rollback Procedure

If an update breaks the system, reboot and hold Shift (or Esc on UEFI) to show the GRUB menu. Select Start bootloader from a read-only snapshot or a specific snapshot entry labeled openSUSE MicroOS (snapshot 11). The system boots the previous snapshot with its own /etc overlay. The faulty snapshot remains on disk; you can later delete it with snapper delete 12.

Rollback is instantaneous—no package downgrade, no database rebuild. The only state lost is any data written to non-persistent paths (e.g., /tmp, /var/tmp) after the snapshot was created.

Disk Space Management: The Hidden Cost

Each snapshot consumes space for changed blocks. Frequent updates without cleanup exhaust the Btrfs pool. MicroOS includes a systemd timer snapper-cleanup.timer that runs daily and removes old snapshots based on /etc/snapper/configs/root policies (default: keep 10 numbered snapshots, 5 timeline snapshots).

Check current usage:

btrfs filesystem usage /

If Used approaches Total, manually prune:

snapper list
snapper delete 5-10

Adjust retention in /etc/snapper/configs/root (requires transactional update to modify, since /etc is on the overlay). Example change:

NUMBER_LIMIT="20"
NUMBER_LIMIT_IMPORTANT="10"
TIMELINE_LIMIT="7"

Apply with transactional-update pkg install snapper (triggers a snapshot) and reboot.

Common Mistakes and How to Avoid Them

Mistake	Symptom	Fix
Running zypper install directly	Read-only file system error	Use transactional-update pkg install
Expecting immediate effect	Package not found after install	Reboot to activate snapshot
Editing /etc/fstab on snapshot	Changes lost after reboot	Edit the live /etc/fstab (overlay upper layer) or use transactional-update shell for snapshot-scoped edits
Ignoring snapshot accumulation	No space left on device on Btrfs	Monitor btrfs filesystem usage /; tune snapper config
Treating /var as immutable	Logs, databases work normally	/var is a separate subvolume, always writable

Verification Checklist

1. Run transactional-update pkg install <package> and confirm snapshot creation with snapper list.
2. Reboot and verify rpm -q <package> returns the installed version.
3. Attempt touch /usr/testfile; expect Read-only file system.
4. Check mount | grep ' / ' | grep ro shows root mounted read-only.
5. Verify /etc overlay with mount | grep overlay.

Limitations to Consider

• No live patching: Kernel updates require reboot. For zero-downtime environments, plan maintenance windows.
• Container workflows differ: Podman/Containerd images are pulled to /var/lib/containers (writable), but host package dependencies for container runtimes still follow transactional updates.
• Third-party kernel modules: DKMS or manual module builds must run inside a transactional-update shell or be packaged as RPMs installed via transactional-update.
• Snapshot count affects boot menu: GRUB entries grow with each snapshot; the cleanup timer limits this, but very large retention policies clutter the menu.

When This Model Shines

MicroOS transactional updates excel for:

• Edge devices and IoT gateways where unattended updates must not brick the device.
• Kubernetes nodes (via Kubic/MicroOS) where node OS consistency across the cluster is critical.
• Developers who want a reproducible, versioned OS state they can pin or roll back per project.

It is less suited for workstations where users expect immediate application installation without reboot, or for systems requiring live kernel patching without downtime.