System protection

LuxOS keeps its system files read-only, like the protected system volume of macOS: programs, libraries, kernel modules and app data in /usr can only be changed by package changes made with lux, LuxOS Care (Software Update), the Store or lux system apply. A weekly check compares every system file with the package database and repairs changed files by reinstalling the packages from the signed repositories. Part of LuxOS Care (luxos-care), see care-updates.md.

What is protected

/usr is a read-only bind mount (/bin, /lib, /sbin are links into /usr, so all programs and libraries are covered). Read-only is a flag of this one mount, not of the file system: snapshots, /home and the other Btrfs subvolumes are not affected.

Writable as before: /etc (settings), /var (data, logs, caches, Flatpak apps), /home, /root, /srv, /opt (some third-party apps update themselves there), /usr/local (own programs, make install, .lux apps) and /boot.

The protection stops accidents and careless scripts (sudo make install with prefix /usr, sudo pip install, an installer that overwrites a system library) and makes changed system files visible. It is not a barrier against an attacker who already has root: root can remount /usr. That is what the integrity check and, later, cryptographic verification are for.

How updates write to /usr

Only for the duration of a package transaction:

  1. lux (and everything built on it: Software Update, Store, lux system apply) makes /usr writable right before the transaction is committed and read-only again right after it.
  2. For transactions that do not go through lux (for example lux-engine directly), the package manager hook 00-0-luxos-protect.hook (first of all pre-transaction hooks) opens /usr and zz-luxos-protect.hook (last of all post-transaction hooks, after mkinitcpio, DKMS and the kernel fallback) protects it again. If /usr cannot be opened, the transaction stops before it changes anything; it never ends half-installed.
  3. Every user of the writable state holds a shared lock (/run/luxos-protect/lock); /usr becomes read-only again only when nobody holds it and no transaction is running.
  4. If a transaction is killed and nothing protects /usr again, the periodic LuxOS Care check (luxos-care check, every 6 hours) does it, at the latest the next start.

Updates still apply without a restart (apps, libraries, services); only a new kernel needs a restart, as before. The snapshot before every update (see care-updates.md) stays the way back.

Other things that write to /usr and are handled: locale-gen (lux system apply, OEM setup), DKMS rebuilds by Care self-repair, the kept previous kernel in /usr/lib/modules. For your own one-off command use sudo luxos-care protect exec -- COMMAND.

Integrity verification

luxos-care verify reads the file list of every installed package from the local package database (/var/lib/lux/local/*/mtree: type, size, link target, SHA-256, permissions) and compares it with the files in /usr and /opt:

Finding Meaning
changed different content (SHA-256) or size
missing the file was deleted
replaced a directory or something else instead of a file
link changed a symbolic link points elsewhere
permissions changed the file gained setuid, setgid or world-write permission

Not reported: configuration files the package marks as backup (they are meant to be edited), files no package owns (caches generated by hooks), and files LuxOS itself changes on purpose (/usr/lib/os-release from branding, the removed Xfce session file). Own exceptions: one path or glob per line in /etc/luxos/verify-ignore.

Weekly run: the Care check starts luxos-care-verify.service once a week, only while the computer is charging (or has no battery), with idle CPU and disk priority; when the charger is unplugged the check stops and runs again later. A full check of ~225 000 files reads all of /usr once (a few minutes on an SSD). A notification appears only when something was found: a critical notification "System files were changed" that stays in the notification history, with Details opening Software Update. luxos-care verify --quick compares size and time only and hashes just files with a different time (seconds instead of minutes).

Repair reinstalls the affected packages from the signed repositories (or the package cache with the same version) and checks them again. Packages that are not in the repositories (AUR, own builds) cannot be repaired this way and are listed separately.

Software Update app

Section System protection in Software Update (luxos-update):

  • "System protection: On" (or Off with a Turn On button, which asks for the administrator password),
  • "System files verified on DATE" / "N system files were changed or are missing" with a Repair button, "Verifying system files… N %" while the check runs,
  • Verify Now starts the check at once (also on battery). Verify Now and Repair need no password for administrators (polkit, like Update Now).

Command line

luxos-care protect [status] [--json]   state of the protection and the last check (anyone)
luxos-care protect enable|disable      (root) on/off now and permanently (PROTECT= in care.conf)
luxos-care protect exec -- COMMAND     (root) run one command with a writable /usr
luxos-care protect relock              (root) read-only again if no package change is running
luxos-care verify [--quick] [--json] [PACKAGE...]   check files (root stores the result)
luxos-care verify --repair [PACKAGE...]             (root) reinstall packages with changed files

Exit codes of verify: 0 no changes, 1 changes found (or repair failed).

Configuration

Setting Meaning
PROTECT=yes in /etc/luxos/care.conf protection on (new installations; missing = off)
PROTECT=no protection off (applied at once with luxos-care protect disable)
VERIFY=no no weekly check (manual check still works)
care.protect, care.verify in /etc/luxos/system.lsl the same through lux system apply
kernel parameter luxos.protect=0 off for one start (press e in the boot menu)
PROTECT=0 in the installer configuration install without protection

Defaults

New installations have the protection on from the first start: the installer writes PROTECT=yes unless PROTECT=0 is set in its configuration, and a computer prepared for another person (OEM) keeps the installer's choice. Updates on such a system are unaffected (every package transaction makes /usr writable for its duration), so there is nothing to click. Check the state with luxos-care protect status.

Existing installations

Installations from before LuxOS 1.0 keep working as they were: the protection is off until you turn it on (Software Update › System protection › Turn On, or sudo luxos-care protect enable). It is not switched on automatically by an update, because some setups write to /usr outside the package manager (own scripts, sudo pip install, manually installed drivers) and would break silently. Run Verify Now first: it shows such changes. Turning it on takes effect at once, without a restart. The weekly check runs on all installations.

If something goes wrong

  • The protection never stops the system from starting: luxos-protect.service only mounts /usr read-only when everything else is mounted, and on any error leaves it writable. It does not run when starting from a snapshot or in LuxOS Recovery.
  • A program fails with "Read-only file system" in /usr: install it with lux (or into /usr/local, /opt, your home), run one command with sudo luxos-care protect exec -- ..., or turn the protection off.
  • /usr stays writable after a crashed update: sudo luxos-care protect relock.

Design decisions

Two ways of a protected system were considered:

  • Atomic updates into a new snapshot (like ostree or transactional-update): the transaction runs in a writable copy of the system, the copy becomes the system at the next start. The running system never changes, but every app update would need a restart; /etc and /var live in the same Btrfs subvolume as /usr (so that a snapshot is a consistent state for rollback), so changes made between the update and the restart would be lost; package hooks, DKMS and the kernel on the shared boot partition would run against a system that is not running.
  • Read-only /usr, writable only during a transaction (chosen): updates apply at once as desktop users expect, all package hooks and DKMS work unchanged, and the existing snapshot before every transaction plus the boot menu entries and LuxOS Recovery remain the way back. A failure in the protection can only leave /usr writable, never unbootable.

The atomic variant is still possible later on top of this (separate @etc/@var subvolumes, transaction into a new snapshot, switch at restart) for managed computers.

Later: cryptographic verification

The weekly check trusts the package database on the same disk. Planned next step: verify /usr at every start and on every read, with a signature from LuxOS:

  • composefs (EROFS image with the file metadata and fs-verity digests, signed): files stay shared in the Btrfs store, the kernel refuses any file whose content does not match; updates build a new image.
  • dm-verity for a separate read-only /usr partition (A/B image updates, like the macOS Signed System Volume), with the root hash in a signed unified kernel image (UKI) and Secure Boot.

Both need an image-based /usr and signed boot images, so they come after the switch to UKI and Secure Boot keys of LuxOS.

Files

Path Content
/usr/lib/luxos/python/luxos_protect.py protection and verification
/usr/lib/luxos/care/luxos-protect-boot protection at start (luxos-protect.service)
/usr/share/libalpm/hooks/00-0-luxos-protect.hook, zz-luxos-protect.hook open/close around transactions
/var/lib/luxos-care/verify.json result of the last check (readable by everyone)
/run/luxos-care/verify-progress.json progress of the running check
/etc/luxos/verify-ignore own exceptions (optional)
luxos-care-verify.service, luxos-care-verify-now.service, luxos-care-repair-now.service weekly check, Verify Now, Repair