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

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.

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 and then directories sorted deepest-first. Directories are removed only with rmdir, so non-empty directories remain.

If an unexpected object type 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.

---

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).