Cleanup Bootstrap Root

Cleanup Bootstrap Root is a standalone Btrfs maintenance utility for safely cleaning the retired bootstrap root subvolume (@) after a system has permanently transitioned to booting from a snapshot root.

It is intended for the one-time post-transition stage before creating additional root-level Btrfs subvolumes.

The utility does not perform the migration itself. It analyzes the retired @ subvolume, compares it with the active snapshot, protects retained paths and discovered Btrfs subvolumes, builds a cleanup plan, and executes that plan only when explicitly requested.

---

Project Status

Version 1.0.1

Cleanup of a root subvolume is inherently destructive. Always run the explicit dry run first and review its verification report before using execution mode.

---

Use Case

A typical Btrfs installation begins with @ as the active root subvolume.

After another workflow permanently moves the system into a snapshot such as:

@/.snapshots/<number>/snapshot

the original @ remains as the retired bootstrap root. Its ordinary files, links, and directories may duplicate the active system and prevent a clean root-level subvolume layout.

Cleanup Bootstrap Root reconciles that retired @ with the active snapshot.

It does not care which migration process created or selected the snapshot. It verifies the current Btrfs state before it builds any cleanup plan.

---

Safety Model

The utility refuses to proceed unless:

• It is running as root.
• The running root filesystem is Btrfs.
• The current root is not @.
• The current root matches @/.snapshots/*/snapshot.
• The running snapshot is also the Btrfs default subvolume.
• The backing source is a block device.
• The @ and @/.snapshots subvolumes exist.
• The retired @ subvolume mounts and verifies correctly.

The cleanup policy protects:

• /boot and everything beneath it.
• /.snapshots and everything beneath it.
• Every discovered Btrfs subvolume within the retired @ namespace.
• Every parent directory entry required to reach one of those subvolumes.
• Everything beneath a protected subvolume path.
• Objects that cannot be proven safe to remove by the active-snapshot comparison.

Unix-domain sockets are handled by a dedicated deletion queue. Other unexpected object types abort the execution plan instead of being removed.

The separate @home subvolume is a sibling of @ and lies outside the cleanup namespace. It is not mounted, traversed, mapped, or modified.

---

Requirements

• Bash
• Root privileges
• A Btrfs root filesystem
• A retired bootstrap root at @
• A snapshot root matching @/.snapshots/<number>/snapshot
• The running snapshot set as the Btrfs default subvolume
• Standard commands used by the script, including findmnt, mount, umount, mountpoint, btrfs, find, awk, sed, sort, grep, rm, and rmdir

Cleanup Bootstrap Root does not depend on BootPrep, GRUB, EFI, or Snapper commands. It operates from the discovered Btrfs filesystem state.

---

Usage

Make the script executable:

chmod +x cleanup-bootstrap-root.sh

The script requires an explicit operating mode. Running it without an argument prints the usage message and exits without beginning analysis.

Dry run

sudo ./cleanup-bootstrap-root.sh --dryrun

Dry-run mode performs discovery, comparison, classification, execution planning, queue processing, and final validation without deleting filesystem objects.

Review the complete policy summary and execution queues before continuing.

Execute

sudo ./cleanup-bootstrap-root.sh --execute

Execute mode remounts the retired @ subvolume read-write and removes only the objects placed in the verified deletion queues.

Any argument other than --dryrun or --execute is rejected.

---

Cleanup Policy

The script builds maps of:

• The running snapshot tree.
• The retired bootstrap-root tree.
• Every discovered Btrfs subvolume within the retired @ namespace.
• Every protected subvolume path and required parent directory entry.
• Objects retained because they cannot be proven safe to remove.

Every object in the retired @ is classified into one of five groups:

Classification	Result
Protected boot object	Retained
Protected snapshot object	Retained
Protected subvolume path	Retained
Unproven or abandoned-tree object	Retained
Verified delete candidate	Added to the execution plan

Delete candidates are then separated by object type.

Symbolic links are processed first, followed by regular files, Unix-domain sockets, and then directories sorted deepest-first. Directories are removed only with rmdir, so non-empty directories remain.

If another special object type, such as a FIFO or device node, is found, the script stops before cleanup execution.

---

Workflow

The utility runs twelve modules:

1. Environment Verification
2. Mount Bootstrap Root
3. Discover Btrfs Subvolumes
4. Discover Active Snapshot Tree
5. Build Snapshot Lookup Table
6. Build Bootstrap Lookup Table
7. Compare Bootstrap to Active Snapshot
8. Policy Classification
9. Cleanup Verification Report
10. Build Execution Plan
11. Execute Cleanup Plan
12. Final Validation

The retired @ is mounted read-only during discovery and analysis. In dry-run mode, it remains read-only while the execution queues are simulated. In execute mode, Module 11 remounts it read-write before processing the verified deletion queues.

Module 12 remounts @ read-only and verifies that:

• Non-directory delete candidates are gone in execution mode.
• Protected objects remain.
• Retained objects remain.

An exit trap unmounts the bootstrap root and removes its temporary mount directory beneath /run.

---

What It Does Not Do

Cleanup Bootstrap Root does not:

• Move the running system from @ into a snapshot.
• Create or delete snapshots.
• Set the Btrfs default subvolume.
• Delete Btrfs subvolumes.
• Cross discovered subvolume boundaries.
• Modify the separate @home filesystem.
• Manage Snapper.
• Modify GRUB or EFI configuration.
• Install or configure BootPrep.
• Remove unexpected object types.

Its single responsibility is cleaning verified ordinary filesystem content from the retired bootstrap root.

---

Compatibility

Tested on Debian, Ubuntu, Kubuntu, and CachyOS. The utility is designed for Debian/Ubuntu-based and Arch-based systems that have transitioned from @ to a nested Snapper snapshot root.

Verified test cases

Distribution	Test case	Result
Debian	Completed dry-run and execute modes; verified protected content and cleaned retired @	Passed
Ubuntu	Completed bootstrap-root analysis, cleanup, and final validation	Passed
Kubuntu	Completed bootstrap-root analysis, cleanup, and final validation	Passed
CachyOS	Classified and removed stale GnuPG Unix sockets while preserving boot, snapshots, and nested subvolume paths	Passed

Version 1.0.1 was regression-tested in both dry-run and execute modes on Debian and CachyOS after Unix-socket support was added. On CachyOS, the cleaned retired @ was independently mounted read-only and verified to contain only protected content and required subvolume parent paths.

---

Project Structure

cleanup-bootstrap-root/
├── ARCHITECTURE.md
├── README.md
└── cleanup-bootstrap-root.sh

See ARCHITECTURE.md for the internal analysis, classification, execution, and verification model.

---

License

The source file identifies the project as GNU General Public License v3.0 or later (GPL-3.0-or-later).