From 6505511f2e6b43a37570fc840f6d2851c7cc170c Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 18 Jan 2026 10:55:18 -0600
Subject: Add grub-zfs-snap for ZFS snapshot boot entries

Add ability to boot into ZFS snapshots directly from GRUB menu:
- grub-zfs-snap: generates GRUB submenu entries for recent snapshots
- 40_zfs_snapshots: GRUB generator script installed to /etc/grub.d/
- zz-grub-zfs-snap.hook: pacman hook for automatic GRUB regeneration

The GRUB menu automatically updates after kernel/ZFS package changes.
Up to 10 most recent snapshots appear in a "ZFS Snapshots" submenu.
---
 README.org | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

(limited to 'README.org')

diff --git a/README.org b/README.org
index 16fb406..6306090 100644
--- a/README.org
+++ b/README.org
@@ -21,6 +21,7 @@ manual module loading or package installation during the install process.
 - *Genesis Snapshot* - Automatic pristine-state snapshot after installation
 - *Rollback Script* - One-command factory reset via ~/root/rollback-to-genesis~
 - *Pre-Pacman Snapshots* - Automatic snapshots before package operations
+- *GRUB Snapshot Boot* - Boot into any ZFS snapshot directly from GRUB menu
 - *NetworkManager* - WiFi configuration copied to installed system
 - *SSH Ready* - Optional SSH with root login for headless servers
 - *LTS Kernel* - Uses linux-lts for stability with ZFS
@@ -91,7 +92,10 @@ archzfs/
 ├── build.sh                       # Main ISO build script
 ├── custom/
 │   ├── install-archzfs            # Interactive installation script
-│   └── install-archzfs.conf.example  # Example config for unattended install
+│   ├── install-archzfs.conf.example  # Example config for unattended install
+│   ├── grub-zfs-snap              # ZFS snapshot GRUB menu generator
+│   ├── 40_zfs_snapshots           # GRUB generator script (for /etc/grub.d/)
+│   └── zz-grub-zfs-snap.hook      # Pacman hook for auto-regeneration
 ├── scripts/
 │   └── test-vm.sh                 # QEMU test VM launcher
 ├── profile/                       # archiso profile (generated during build)
@@ -408,6 +412,62 @@ If you enabled SSH during installation:
 
 * Post-Installation
 
+** ZFS Snapshot Boot Entries (grub-zfs-snap)
+
+The installer configures GRUB to display bootable ZFS snapshots in the boot menu.
+This allows you to boot directly into a previous system state without manually
+rolling back.
+
+*** How It Works
+
+- A GRUB submenu "ZFS Snapshots" appears in the boot menu
+- Shows up to 10 most recent snapshots of the root dataset
+- Selecting a snapshot boots the system in read-only mode from that snapshot
+- The running system sees the snapshot's files, but changes go to a temporary overlay
+
+*** When Snapshots Appear in GRUB
+
+The GRUB menu is automatically updated:
+- After kernel updates (~linux-lts~)
+- After ZFS package updates (~zfs-dkms~, ~zfs-utils~)
+- After GRUB updates
+- After any kernel module installation
+
+*** Manual Snapshot Management
+
+#+BEGIN_SRC bash
+# Create a snapshot before making changes
+zfs snapshot zroot/ROOT/default@before-experiment
+
+# Regenerate GRUB menu to include new snapshot
+grub-zfs-snap
+
+# List snapshots that will appear in GRUB
+grub-zfs-snap --list
+#+END_SRC
+
+*** Customization
+
+Environment variables control behavior:
+
+#+BEGIN_SRC bash
+# Change pool name (default: zroot)
+POOL_NAME=mypool grub-zfs-snap
+
+# Change root dataset (default: ROOT/default)
+ROOT_DATASET=ROOT/arch grub-zfs-snap
+
+# Show more snapshots in menu (default: 10)
+MAX_SNAPSHOTS=20 grub-zfs-snap
+#+END_SRC
+
+*** Booting from a Snapshot
+
+1. Reboot and select "ZFS Snapshots" from GRUB menu
+2. Choose the desired snapshot by date/name
+3. System boots with that snapshot's root filesystem
+4. Files are read-only - to make permanent, rollback from normal boot
+
 ** Genesis Snapshot
 
 The installer creates a recursive snapshot of the entire pool named ~genesis~.
-- 
cgit v1.2.3