From 3a2445080c880544985f50fb0d916534698cc073 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 22 Feb 2026 23:20:56 -0600 Subject: chore: add docs/ to .gitignore and untrack personal files docs/ contains session history, personal workflows, and private protocols that shouldn't be in a public repository. --- docs/PLAN-archangel-btrfs.org | 227 ------------------------------------------ 1 file changed, 227 deletions(-) delete mode 100644 docs/PLAN-archangel-btrfs.org (limited to 'docs/PLAN-archangel-btrfs.org') diff --git a/docs/PLAN-archangel-btrfs.org b/docs/PLAN-archangel-btrfs.org deleted file mode 100644 index 20f1984..0000000 --- a/docs/PLAN-archangel-btrfs.org +++ /dev/null @@ -1,227 +0,0 @@ -#+TITLE: Implementation Plan: Archangel Btrfs Support -#+DATE: 2026-01-23 - -* Overview - -Add btrfs filesystem support to archangel (formerly archzfs) installer. -Users can choose ZFS or Btrfs during installation. - -See [[file:research-btrfs-expansion.org][research-btrfs-expansion.org]] for background research. - -* Key Decisions (Already Made) - -- Project rename: archzfs → archangel -- Snapshot tool: snapper + snap-pac + grub-btrfs -- Bootloader: ZFS uses ZFSBootMenu, Btrfs uses GRUB -- Encryption: ZFS native, Btrfs uses LUKS -- RAID: Btrfs raid1 only (raid5/6 unstable) -- Layout: Btrfs subvols mirror ZFS datasets - -* Phase 1: Refactor Current Installer - -Goal: Modularize install-archzfs before adding btrfs. - -** 1.1 Create lib/ directory structure -- [ ] Create custom/lib/ directory -- [ ] Move color/output functions → lib/common.sh -- [ ] Move fzf prompt functions → lib/common.sh -- [ ] Move config file handling → lib/config.sh - -** 1.2 Extract ZFS-specific code -- [ ] Create lib/zfs.sh -- [ ] Move pool creation → lib/zfs.sh -- [ ] Move dataset creation → lib/zfs.sh -- [ ] Move ZFS mount logic → lib/zfs.sh -- [ ] Move ZFSBootMenu install → lib/zfs.sh - -** 1.3 Extract shared disk operations -- [ ] Create lib/disk.sh -- [ ] Move partitioning logic (EFI + root) -- [ ] Move disk selection/validation -- [ ] Move RAID detection logic - -** 1.4 Add filesystem selection prompt -- [ ] Add fzf prompt: "Filesystem: ZFS / Btrfs" -- [ ] Store choice in config -- [ ] Gate ZFS vs Btrfs code paths - -** 1.5 Rename project -- [ ] Rename install-archzfs → archangel -- [ ] Update build.sh references -- [ ] Update README.org -- [ ] Update all internal references - -* Phase 2: Implement Btrfs Support - -Goal: Full btrfs installation path. - -** 2.1 Create lib/btrfs.sh -- [ ] Create btrfs volume function -- [ ] Create subvolume creation function -- [ ] Create mount function (with correct options) -- [ ] Create fstab generation (NO subvolid!) - -** 2.2 Subvolume layout -Create these subvolumes (matching ZFS datasets): -- [ ] @ → / -- [ ] @home → /home -- [ ] @snapshots → /.snapshots (snapper requirement) -- [ ] @var_log → /var/log -- [ ] @var_cache → /var/cache -- [ ] @tmp → /tmp -- [ ] @var_tmp → /var/tmp -- [ ] @media → /media (compress=off) -- [ ] @vms → /vms (nodatacow) -- [ ] @var_lib_docker → /var/lib/docker - -** 2.3 Mount options -#+BEGIN_SRC -BTRFS_OPTS="noatime,compress=zstd,space_cache=v2,discard=async" -#+END_SRC -- [ ] Apply to all subvols except @media (compress=off) and @vms (nodatacow) - -** 2.4 Snapper configuration -- [ ] Install snapper, snap-pac packages -- [ ] Create /etc/snapper/configs/root -- [ ] Set timeline policy (hourly=6, daily=7, weekly=2, monthly=1) -- [ ] Enable snapper-timeline.timer -- [ ] Enable snapper-cleanup.timer - -** 2.5 GRUB + grub-btrfs installation -- [ ] Install grub, grub-btrfs packages -- [ ] Configure GRUB for btrfs root -- [ ] Enable grub-btrfsd service (auto-update on snapshots) -- [ ] Test snapshot appears in GRUB menu - -** 2.6 Genesis snapshot -- [ ] Create initial snapshot: snapper create -d "genesis" -- [ ] Verify appears in snapper list -- [ ] Verify appears in GRUB menu - -** 2.7 Test basic btrfs (before encryption) -- [ ] VM test: single-disk btrfs install -- [ ] Verify subvolumes created correctly -- [ ] Verify GRUB boots and shows snapshots -- [ ] Verify snapper works -- [ ] Verify genesis snapshot exists - -** 2.8 LUKS encryption (after basic btrfs works) -- [ ] Add encryption prompt (yes/no) -- [ ] Create LUKS container on root partition -- [ ] Configure crypttab -- [ ] Add encrypt hook to mkinitcpio -- [ ] Test passphrase prompt at boot - -* Phase 3: Multi-disk Btrfs - -Goal: Full multi-disk support for btrfs (matching ZFS capabilities). - -** 3.1 RAID level support -- [ ] Stripe (raid0): mkfs.btrfs -d raid0 -m raid0 -- [ ] Mirror (raid1): mkfs.btrfs -d raid1 -m raid1 -- [ ] raid10: mkfs.btrfs -d raid10 -m raid10 (4+ disks) -- [ ] raid5: mkfs.btrfs -d raid5 -m raid5 (3+ disks, warn: unstable) -- [ ] raid6: mkfs.btrfs -d raid6 -m raid6 (4+ disks, warn: unstable) -- [ ] Detect multi-disk selection and offer appropriate levels -- [ ] Handle mixed disk sizes gracefully - -** 3.2 Encryption + multi-disk -- [ ] LUKS on each disk before btrfs -- [ ] crypttab entries for all disks -- [ ] Test unlock sequence at boot -- [ ] Single passphrase unlocks all (keyfile approach) - -** 3.3 EFI redundancy -- [ ] Create EFI partition on all disks -- [ ] Install GRUB to all EFI partitions -- [ ] Create boot entries for each disk - -** 3.4 Degraded boot support -- [ ] Add degraded mount option for emergency -- [ ] Kernel param: rootflags=degraded -- [ ] Document recovery procedure - -* Phase 4: Testing Infrastructure - -Goal: Automated tests for all configurations. - -** 4.1 Test configs -- [ ] Create test-configs/zfs-single.conf -- [ ] Create test-configs/zfs-mirror.conf -- [ ] Create test-configs/btrfs-single.conf -- [ ] Create test-configs/btrfs-mirror.conf -- [ ] Create test-configs/btrfs-encrypted.conf - -** 4.2 Test scripts -- [ ] Create test-btrfs-single.sh -- [ ] Create test-btrfs-mirror.sh -- [ ] Update test-vm.sh for btrfs option - -** 4.3 Validation checks (per research doc) -- [ ] Fresh install checks -- [ ] Reboot survival checks -- [ ] Snapshot operation checks -- [ ] Rollback + reboot checks -- [ ] Failure recovery checks (multi-disk) -- [ ] Encryption checks - -* Phase 5: CLI Tools - -Goal: Unified snapshot management wrappers. - -** 5.1 archangel-snapshot -- [ ] Detect filesystem (ZFS vs Btrfs) -- [ ] ZFS: call zfs snapshot -- [ ] Btrfs: call snapper create -- [ ] Consistent interface for both - -** 5.2 archangel-rollback -- [ ] Detect filesystem -- [ ] ZFS: call zfsrollback script -- [ ] Btrfs: call snapper rollback -- [ ] Include reboot prompt (required for full rollback) - -** 5.3 archangel-list -- [ ] List snapshots for either filesystem -- [ ] Consistent output format - -* Phase 6: Documentation - -Goal: Update all docs for dual-filesystem support. - -** 6.1 README.org -- [ ] Update project name to archangel -- [ ] Document filesystem choice -- [ ] Update feature list -- [ ] Update usage examples - -** 6.2 RESCUE-GUIDE.txt -- [ ] Add btrfs recovery procedures -- [ ] Add snapper commands -- [ ] Add GRUB recovery for btrfs - -** 6.3 New docs -- [ ] Create BTRFS.org with btrfs-specific details -- [ ] Update notes.org project context - -* Schedule (Suggested Order) - -1. Phase 1 (Refactor) - do first, enables everything else -2. Phase 2 (Btrfs single-disk) - core functionality -3. Phase 4.1-4.2 (Test infra) - validate as we go -4. Phase 3 (Multi-disk) - after single-disk works -5. Phase 5 (CLI tools) - polish -6. Phase 6 (Docs) - ongoing, finalize at end - -* Dependencies - -- Phase 2 depends on Phase 1 (refactored code) -- Phase 3 depends on Phase 2 (btrfs basics) -- Phase 4 can run in parallel with 2-3 -- Phase 5 depends on Phase 2 -- Phase 6 is ongoing - -* Open Items - -- [ ] File ZFSBootMenu rollback bug -- [ ] Decide: offer archsetup --chroot during install? (TODO exists) -- cgit v1.2.3