No description
  • C++ 81.9%
  • Shell 13.9%
  • CMake 2.9%
  • Python 0.8%
  • Awk 0.5%
Find a file
2026-11-19 21:40:16 -08:00
cli add cli 2026-09-22 13:20:11 -07:00
config add rpm spec, polkit policy and default config 2026-09-22 22:30:19 -07:00
daemon add daemon and systemd units 2026-09-22 16:05:48 -07:00
dracut/90root-protection add dracut module for snapshot boot 2026-10-08 18:50:13 -07:00
engine snapshot engine 2026-09-22 00:52:33 -07:00
grub grub entries for booting snapshots 2026-09-23 15:47:24 -07:00
guard guard important dirs under root from removal 2026-10-08 14:22:40 -07:00
gui add qt6 gui 2026-09-22 19:41:02 -07:00
hooks add dnf and dnf5 snapshot hooks 2026-09-23 11:12:56 -07:00
packaging add rpm spec, polkit policy and default config 2026-09-22 22:30:19 -07:00
polkit add rpm spec, polkit policy and default config 2026-09-22 22:30:19 -07:00
scripts grub entries for booting snapshots 2026-09-23 15:47:24 -07:00
systemd add daemon and systemd units 2026-09-22 16:05:48 -07:00
tests add tests and source tarball script 2026-10-08 21:10:37 -07:00
.gitignore initial commit 2026-09-21 21:14:07 -07:00
buildsrc.sh add tests and source tarball script 2026-10-08 21:10:37 -07:00
CMakeLists.txt initial commit 2026-09-21 21:14:07 -07:00
LICENSE initial commit 2026-09-21 21:14:07 -07:00
README.md Update README.md 2026-11-19 21:40:16 -08:00

Oreon Root Protection

IMPORTANT NOTICE: This project is partly AI-assisted. Read our AI policy for more information. This disclosure is here for transparency of how the code was written.

Protect root without making it immutable. Space-efficient snapshots, external backups, GRUB overlay rollback, and a soft guard against catastrophic interactive root mistakes.

Works on any filesystem with hardlinks (Oreon default: ext4). No thin LVM required. Native btrfs subvolume snapshots when / is btrfs.

What you get

  • Hardlink incremental snapshots via rsync -aAXH --link-dest into /var/lib/root-protection/snaps
  • Btrfs path when available, same CLI/GUI
  • External backups (tar+zstd) to USB, network mount, or any path, with checksum verify
  • Restore modes: temporary GRUB overlay boot, permanent merge onto /, file-level restore, full backup restore
  • Deletion guard: refuses rm -rf /usr, /boot, etc. (and mv/shred/find -delete/rsync --delete/chmod -R/chown -R on protected dirs) through PATH-first wrapper shims and sudo secure_path — never touches /usr/bin/rm and never blocks dnf/rpm
  • dnf/dnf5 hooks: automatic pre/post transaction snapshots
  • Health gate: refuses new snaps when the snap filesystem is critically full
  • Retention: daily / weekly / dnf counts, prefers deleting oldest non-pinned

Build

cmake -B build -DORP_BUILD_GUI=ON
cmake --build build -j$(nproc)
# binaries: build/root-protection  build/orpd  build/oreon-root-protection
ctest --test-dir build

Dependencies: CMake 3.16+, C++20 compiler, rsync, Qt6 Widgets (for GUI).

RPM BuildRequires are listed in packaging/root-protection.spec.

Install (RPM)

# from a built SRPM/RPM, or:
cmake --install build
# then enable (also done by %post):
sudo root-protection enable

%post enables root-protection-snapshot.timer, root-protection-health.timer, and orpd.service, creates store dirs, and runs root-protection enable so install = protected.

Quick start

sudo root-protection doctor      # layout + deps
sudo root-protection enable      # timers + baseline snap + guard
root-protection status
root-protection list
sudo root-protection snap manual
sudo root-protection rollback 3          # GRUB overlay (temporary)
sudo root-protection rollback 3 --merge  # permanent restore onto /, then reboot
sudo root-protection backup --dest /mnt/usb
sudo root-protection restore-backup bak-... --target /mnt/restore
sudo root-protection prune
sudo root-protection pin 3

GUI: open Root Protection from the app menu (oreon-root-protection), or run it from a terminal. Privileged actions use polkit (pkexec).

dnf snapshots

  • dnf5: /etc/dnf/libdnf5-plugins/actions.d/root-protection.actions, run by libdnf5-plugin-actions (pulled in by the RPM when dnf5 is installed; must stay enabled in /etc/dnf/libdnf5-plugins/actions.conf)
  • dnf4: dnf-plugins/root_protection.py (+ /etc/dnf/plugins/root_protection.conf)

Both call /usr/libexec/root-protection/dnf-hook pre|post, which takes a pre snapshot before and a linked post snapshot after each transaction when general.enabled and dnf.pre_post_snapshots are true. Results go to the journal: journalctl -t root-protection.

Deletion guard (protecting /usr, /boot, ...)

Goal: make it very hard to wipe an important top-level directory while keeping root non-immutable so dnf/rpm updates work normally. The guard never replaces coreutils and never uses chattr +i.

Layers (all point at one checker, root-protection guard-check):

  1. Wrapper shims in /usr/libexec/root-protection/bin (rm, rmdir, mv, cp, shred, find, rsync, chmod, chown, chgrp). Each asks the checker, then execs the real binary unchanged. They fail open if the checker/real binary is missing.
  2. PATH first for interactive and login shells via /etc/profile.d/root-protection-guard.sh (covers sudo -i, su -).
  3. sudo secure_path via /etc/sudoers.d/root-protection, so sudo rm -rf /usr resolves to the shim (plain sudo execs /usr/bin/rm directly, which a profile.d PATH cannot reach).
  4. Interactive DEBUG-trap guard (existing) as defence-in-depth, which also catches absolute paths like /usr/bin/rm -rf /usr typed in a root shell.
  5. Snapshot/overlay recovery is the real backstop (see below).

The checker normalizes each operand (//usr, /./usr, /usr/, /usr/., /usr/../usr, relative paths vs. the cwd, symlinks via realpath, quoted '/usr/*', --no-preserve-root) and blocks when it resolves to a protected path, or when the operands enumerate a protected dir's entire contents (catches shell-expanded rm -rf /usr/* / /*). Operations inside protected dirs (rm -rf /usr/local/foo, mv /etc/a /etc/a.bak, every dnf/rpm unlink) are untouched.

Protected paths are configurable: [guard] protected_paths in /etc/root-protection/config.toml. Toggle with [guard] enabled (or the GUI Settings "Soft root guard" switch). Blocks are logged to the journal under tag root-protection and to [guard] log_path.

Overrides (for real admin work):

root-protection guard off --for 10m   # open a bypass window, then: guard on
sudo RP_GUARD_FORCE=1 rm -rf /usr/old  # one-shot env override
# on a TTY the guard also offers: retype the exact path to proceed

Honest limits: the guard is userspace. A root process that calls an absolute path (/usr/bin/rm), pkexec/run0 (fixed PATH), a raw unlink(2), busybox, or its own script with a hardcoded PATH is not intercepted. There is no package-safe kernel backstop: fanotify has no pre-unlink permission event; a BPF-LSM or SELinux rule that allowed dnf to delete files in /usr but blocked rm -rf /usr cannot distinguish them by path (both delete files under /usr) and would either break updates/admin edits or need a kernel cmdline change — so we rely on snapshots for recovery instead. root-protection doctor prints the guard status and these coverage gaps.

Booting a snapshot (BIOS and UEFI)

Snapshot entries live in /boot/root-protection/bls and are rendered by /etc/grub.d/42_root-protection into a root-protection snapshots submenu. Each entry sets up the /boot filesystem itself (insmod + search --fs-uuid), uses plain linux/initrd, and resolves kernel paths with grub2-mkrelpath, so it works on i386-pc (legacy BIOS) and EFI GRUB, with /boot separate or on /. fix-grub-layout regenerates whichever grub.cfg GRUB really reads (never the EFI stub). The kernel boots with init=/usr/libexec/root-protection/overlay-init, which mounts the snapshot under a tmpfs overlay after the initramfs hands over.

For the case where the live /usr has been destroyed (so overlay-init itself can't run), entries also carry rd.orp.snapshot=<id> and a dracut module (/usr/lib/dracut/modules.d/90root-protection) builds the snapshot overlay from the initramfs, using the on-disk live root read-only as the lower layer. New kernels include the module automatically; existing initramfs are regenerated once by the stamp-guarded root-protection-initramfs.service (not in %post, since dracut --regenerate-all is slow). overlay-init stays as the fallback and hands straight off if the initramfs already built the overlay.

CLI reference

Command Purpose
doctor Check root layout, rsync, overlayfs
enable / disable / status Lifecycle
snap [reason] Create snapshot
list List snapshots
rollback <id> [--merge] Overlay boot or permanent merge
backup [--dest PATH] External backup
restore-backup <id> [--target PATH] Restore backup
prune Apply retention
verify <id> Check snapshot metadata/tree
pin / unpin <id> Keep across prune
guard status Guard state, protected count, bypass window
guard off [--for D] / guard on Open/close an admin bypass window

Layout

engine/   shared C++ library
cli/      root-protection
daemon/   orpd (critical-path inotify watch)
gui/      oreon-root-protection (Qt6 + Breeze)
hooks/    dnf + dnf5
guard/    deletion guard (shims + checker)
dracut/   90root-protection initramfs overlay module
grub/     overlay-init + grub.d submenu
systemd/  timers + orpd
packaging/root-protection.spec + desktop file

License

Copyright (C) 2026 Oreon HQ. GPL-3.0. See LICENSE.