From 893d0df94091afb48102c199a787b48c4444cb3a Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Mon, 23 Feb 2026 15:12:28 -0600 Subject: docs: expand README with rescue disk, SSH, config example, and address review comments --- README.org | 178 ++++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 134 insertions(+), 44 deletions(-) diff --git a/README.org b/README.org index b06e071..548e5f3 100644 --- a/README.org +++ b/README.org @@ -1,4 +1,5 @@ -#+TITLE: archangel - Arch Linux ZFS/Btrfs Installation ISO +#+TITLE: Archangel +#+SUBTITLE: Arch Linux ZFS/Btrfs Installation ISO #+AUTHOR: Craig Jennings #+OPTIONS: toc:3 @@ -12,29 +13,35 @@ configurations, and automatic snapshot management. The ISO includes all necessary tools pre-loaded, eliminating the need for manual module loading or package installation during the install process. +The ISO also doubles as a [[*Rescue Disk][rescue disk]] with data recovery, boot repair, +hardware diagnostics, and other tools pre-installed. An [[*SSH Server][SSH server]] starts +automatically for remote access. + * Features -- *Dual Filesystem Support* - Choose ZFS or Btrfs during installation -- *SSH Ready* - Optional SSH with root login for headless servers +- *Dual Filesystem Support* - Choose ZFS or Btrfs during installation ([[*Filesystem Comparison][comparison]]) - *Native Encryption* - ZFS encryption or LUKS2 for Btrfs - *Multi-Disk RAID* - Mirror, stripe, raidz1/2/3 (ZFS) or RAID0/1/10 (Btrfs) -- *Snapshot Boot* - ZFSBootMenu (ZFS) or grub-btrfs (Btrfs) for booting snapshots +- *Snapshot Boot* - ZFSBootMenu (ZFS) or grub-btrfs (Btrfs) for [[*Post-Installation][booting snapshots]] +- *[[*SSH Server][SSH Ready]]* - Optional SSH with root login for headless servers - *EFI Boot Redundancy* - Bootloader installed on all disks for resilience -- *fzf-Based Interface* - Fuzzy search for timezone, locale, keymap, disk, RAID, and WiFi selection +- *fzf-Based Interface* - Fuzzy search for timezone, locale, keymap, disk, RAID, and WiFi ([[*Installation Walkthrough][walkthrough]]) - *NetworkManager* - WiFi configuration copied to installed system -- *Genesis Snapshot* - Automatic pristine-state snapshot after installation +- *[[*Unattended Installation][Unattended Install]]* - Headless installation via plaintext config file +- *[[*Genesis Snapshot][Genesis Snapshot]]* - Automatic pristine-state snapshot after installation. Convenient for testing machines. +- *[[*Rescue Disk][Rescue Disk]]* - Data recovery, boot repair, hardware diagnostics, and more - *LTS Kernel* - Uses linux-lts for stability ** Filesystem Comparison -| Feature | ZFS | Btrfs | -|---------------+--------------------------------------+----------------------| -| Bootloader | ZFSBootMenu | GRUB + grub-btrfs | -| Encryption | Native ZFS encryption | LUKS2 | -| Snapshots | cj: internal tool with custom script | snapper | -| Snapshot boot | Built into ZFSBootMenu | grub-btrfs menu | -| RAID support | mirror, raidz1/2/3, stripe | RAID0, RAID1, RAID10 | -| EFI size | 512MB | 1GB | +| Feature | ZFS | Btrfs | +|------------------+----------------------------+----------------------| +| Bootloader | ZFSBootMenu | GRUB + grub-btrfs | +| Encryption | Native ZFS encryption | LUKS2 | +| Snapshot utility | zfssnapshot helper scripts | snapper | +| Snapshot boot | Built into ZFSBootMenu | grub-btrfs menu | +| RAID support | mirror, raidz1/2/3, stripe | RAID0, RAID1, RAID10 | +| EFI size | 512MB | 1GB | * Quick Start @@ -56,7 +63,7 @@ Boot the ISO and run ~archangel~ to start the installation. ** Build Host Requirements - Arch Linux (or Arch-based distribution) - Root/sudo access -- ~archiso~ package installed (~pacman -S archiso~) +- ~archiso~ package (~pacman -S archiso~) — auto-installed if missing - ~10GB free disk space for build ** Runtime Dependencies (included in ISO) @@ -85,7 +92,7 @@ The build script will: - ISO location: ~out/archangel-vmlinuz-{version}-lts-YYYY-MM-DD-x86_64.iso~ - Example: ~archangel-vmlinuz-6.12.65-lts-2026-01-18-x86_64.iso~ -- Build logs: visible in terminal output +- Build logs: visible in terminal output (not saved to disk) ** Clean Rebuild @@ -127,14 +134,19 @@ archangel/ ** Script Descriptions -| Script | Description | -|--------+-------------| -| ~build.sh~ | Builds the ISO. Copies releng profile, adds packages, configures kernel, runs mkarchiso | +| Script | Description | +|---------------------+--------------------------------------------------------------------------------------------------------------| +| ~build.sh~ | Builds the ISO. Copies releng profile, adds packages, configures kernel, runs mkarchiso | | ~installer/archangel~ | Interactive installer. Handles disk partitioning, filesystem creation, base system install, bootloader setup | -| ~scripts/test-vm.sh~ | Launches QEMU VM for testing. Supports single and multi-disk configurations | +| ~scripts/test-vm.sh~ | Launches QEMU VM for testing. Supports single and multi-disk configurations | * Testing with VMs +The test suite launches QEMU VMs to validate that the ISO boots correctly and +that installations complete successfully across all supported configurations +(ZFS/Btrfs, single/multi-disk, encrypted/unencrypted). Run these tests after +modifying the installer or build scripts to catch regressions. + ** Basic VM Test #+BEGIN_SRC bash @@ -155,9 +167,7 @@ This creates a 50GB virtual disk and boots the ISO. ** SSH Access to VM -*Security Warning*: The live ISO has SSH root login enabled with the password -~archangel~. This is intended for testing and headless installations only. -Do not expose the live environment to untrusted networks. +*Security Warning*: The live ISO has SSH root login enabled with the password ~archangel~. This is intended for testing, headless installations, and rescue operations only. Do not expose the live environment to untrusted networks. #+BEGIN_SRC bash # Password: archangel @@ -181,8 +191,7 @@ sshpass -p archangel ssh -p 2222 root@localhost * Installation Walkthrough -The ~archangel~ script provides a guided installation with fzf-based -selection interfaces. +The ~archangel~ script provides a guided installation with fzf-based selection interfaces with helpful information displayed about the choices. ** Phase 1: Configuration Gathering @@ -210,14 +219,14 @@ After configuration, the installation runs without intervention: * Unattended Installation -For automated or headless installations, use a config file. +For automated or headless installations, you can specify a simple plain text config file containing the choices. ** Using a Config File #+BEGIN_SRC bash # Copy and edit the example config cp /root/archangel.conf.example /root/my-install.conf -vim /root/my-install.conf +$EDITOR /root/my-install.conf # Run with config file archangel --config-file /root/my-install.conf @@ -227,21 +236,53 @@ archangel --config-file /root/my-install.conf ~--config-file~. The installer will never automatically read a config file to prevent accidental disk destruction. +** Example Config File + +#+BEGIN_SRC bash +# archangel.conf - Unattended Installation Configuration +# +# Copy this file and edit values. +# Usage: archangel --config-file /path/to/your-config.conf +# +# Required fields: HOSTNAME, TIMEZONE, DISKS, ROOT_PASSWORD +# For ZFS: also need ZFS_PASSPHRASE or NO_ENCRYPT=yes +# For Btrfs: also need LUKS_PASSPHRASE or NO_ENCRYPT=yes +# All other fields have sensible defaults. + +FILESYSTEM=zfs +HOSTNAME=archangel +TIMEZONE=America/Los_Angeles +LOCALE=en_US.UTF-8 +KEYMAP=us + +DISKS=/dev/vda +RAID_LEVEL= + +ZFS_PASSPHRASE=changeme +#LUKS_PASSPHRASE=changeme +#NO_ENCRYPT=no + +ROOT_PASSWORD=changeme +ENABLE_SSH=yes +#+END_SRC + +A complete example with all options is available at ~installer/archangel.conf.example~. + ** Config File Reference -| Field | Required | Default | Description | -|-------+----------+---------+-------------| -| ~FILESYSTEM~ | No | zfs | Filesystem type (zfs or btrfs) | -| ~HOSTNAME~ | Yes | - | System hostname | -| ~TIMEZONE~ | Yes | - | Timezone (Region/City format) | -| ~DISKS~ | Yes | - | Comma-separated disk paths | -| ~ZFS_PASSPHRASE~ | Yes* | - | Encryption passphrase (*if not NO_ENCRYPT) | -| ~ROOT_PASSWORD~ | Yes | - | Root user password | -| ~LOCALE~ | No | en_US.UTF-8 | System locale | -| ~KEYMAP~ | No | us | Console keyboard layout | -| ~RAID_LEVEL~ | No | mirror | RAID type for multi-disk | -| ~ENABLE_SSH~ | No | yes | Enable SSH server | -| ~NO_ENCRYPT~ | No | no | Skip encryption (testing only) | +| Field | Required | Default | Description | +|----------------+----------+-------------+--------------------------------------------| +| ~FILESYSTEM~ | No | zfs | Filesystem type (zfs or btrfs) | +| ~HOSTNAME~ | Yes | - | System hostname | +| ~TIMEZONE~ | Yes | - | Timezone (Region/City format) | +| ~DISKS~ | Yes | - | Comma-separated disk paths | +| ~ZFS_PASSPHRASE~ | Yes* | - | Encryption passphrase (*if not NO_ENCRYPT) | +| ~ROOT_PASSWORD~ | Yes | - | Root user password | +| ~LOCALE~ | No | en_US.UTF-8 | System locale | +| ~KEYMAP~ | No | us | Console keyboard layout | +| ~RAID_LEVEL~ | No | mirror | RAID type for multi-disk | +| ~ENABLE_SSH~ | No | yes | Enable SSH server | +| ~NO_ENCRYPT~ | No | no | Skip encryption (testing only) | * Bare Metal Installation @@ -254,20 +295,24 @@ sudo dd if=out/archangel-vmlinuz-*.iso of=/dev/sdX bs=4M status=progress oflag=s ** Booting -1. Boot from USB (may need to disable Secure Boot) +1. Boot from USB — Secure Boot must be disabled since ZFS kernel modules are + unsigned. Check your BIOS/UEFI firmware documentation for how to disable it. 2. Wait for live environment to load 3. Run ~archangel~ +*Note*: Archangel performs a minimal Arch Linux installation with root login +only. No additional user accounts are created — configure those after first boot. + ** Post-Reboot *** ZFS Systems -1. Enter ZFS encryption passphrase at ZFSBootMenu prompt +1. If encryption is enabled, enter ZFS passphrase at ZFSBootMenu prompt 2. Select boot environment (or wait for default) 3. Log in as root *** Btrfs Systems 1. GRUB menu appears -2. Enter LUKS passphrase when prompted +2. If encryption is enabled, enter LUKS passphrase when prompted 3. Log in as root * Post-Installation @@ -311,6 +356,47 @@ zfs list -t snapshot | grep genesis snapper -c root list | grep genesis #+END_SRC +** SSH on the Installed System + +When ~ENABLE_SSH~ is ~yes~ (the default), the installer enables ~sshd~ on the +installed system and configures ~PermitRootLogin yes~. You are prompted during +installation and can decline, or set ~ENABLE_SSH=no~ in a config file. + +*Important*: Harden SSH after installation — switch to key-based authentication +and consider installing ~fail2ban~. + +* Rescue Disk + +The ISO serves as a general-purpose rescue disk with a comprehensive set of +recovery and diagnostic tools pre-installed: + +- *Data Recovery* - ~ddrescue~, ~testdisk~, ~photorec~, ~foremost~ +- *Boot Repair* - ~grub-install~, ~efibootmgr~, ~arch-chroot~, ~mkinitcpio~, ~syslinux~ +- *Windows Recovery* - ~chntpw~ (password reset), ~ntfs-3g~, ~hivex~ (registry editing) +- *Hardware Diagnostics* - ~smartctl~, ~memtester~, ~stress-ng~, ~lm_sensors~, ~hdparm~, ~iotop~ +- *Disk Operations* - ~partclone~, ~fsarchiver~, ~nwipe~ (secure erase), ~ncdu~ +- *Network Diagnostics* - ~nmap~, ~tcpdump~, ~wireshark-cli~ (tshark), ~mtr~, ~iperf3~, ~iftop~, ~nethogs~ +- *Encryption* - ~cryptsetup~ (LUKS), ~gpg~, ~dislocker~ (BitLocker) +- *System Tracing* - ~bpftrace~, ~bcc-tools~, ~perf~ + +A detailed rescue guide is included on the ISO at ~/root/RESCUE-GUIDE.txt~. + +* SSH Server + +The live environment automatically starts an SSH server, allowing remote access +for headless installations, rescue operations, or VM testing. Connect from +another machine on the same network: + +#+BEGIN_SRC bash +ssh root@archangel.local # via mDNS (avahi) +#+END_SRC + +The default root password is set in ~build.sh~ (variable ~LIVE_ROOT_PASSWORD~). + +*Security Warning*: The live ISO has SSH root login enabled with the password +~archangel~. This is intended for testing, headless installations, and rescue +operations only. Do not expose the live environment to untrusted networks. + * Troubleshooting ** Build Fails with Package Conflicts @@ -355,5 +441,9 @@ The ISO includes DKMS-built ZFS modules. If modules fail to load: * License This project is licensed under the GNU General Public License v3.0 (GPL-3.0). - See [[file:LICENSE][LICENSE]] file for the full license text. + +Note: [[https://github.com/openzfs/zfs][OpenZFS]] is licensed separately under the +[[https://github.com/openzfs/zfs/blob/master/LICENSE][CDDL license]]. ZFS packages +are provided by the [[https://archzfs.com][archzfs]] third-party repository and are +not part of this project. -- cgit v1.2.3