From 8bad5c5775a4a16221db61e01d2ed0cc4924f04c Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Tue, 24 Feb 2026 08:40:36 -0600 Subject: docs: reorganize README sections to follow logical user journey MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Eliminate Bare Metal Installation section by redistributing its content: - dd command → Building the ISO > Writing to USB - Secure Boot/boot steps → new Booting the ISO section - SSH/Avahi → SSH Access subsection under Booting the ISO - archangel invocation → Installation intro - ZFS/Btrfs first-boot → new Post-Reboot section Rename sections: Connecting via SSH Server → Booting the ISO, Arch Linux Install Walkthrough → Installation. --- README.org | 292 +++++++++++++++++++++++++++---------------------------------- 1 file changed, 131 insertions(+), 161 deletions(-) diff --git a/README.org b/README.org index 1e67afb..c82c3bd 100644 --- a/README.org +++ b/README.org @@ -9,7 +9,7 @@ Archangel is a custom Arch Linux ISO build system. ~make build~ will begin generating a live ISO with OpenZFS kernel modules and an installer that supports Arch Linux on ZFS root along with Btrfs, encrypted filesystems, and multi-disk RAID configurations. -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 making remote connections dead easy. +The ISO also doubles as a [[#rescue-disk][rescue disk]] with data recovery, boot repair, hardware diagnostics, and other tools pre-installed. An [[#ssh-access][SSH server]] starts automatically making remote connections dead easy. * Features @@ -17,7 +17,7 @@ The ISO also doubles as a [[#rescue-disk][rescue disk]] with data recovery, boot - *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 [[#post-installation][booting into snapshots]] -- *[[#ssh-server][SSH Ready]]* - Optional SSH with root login for headless servers +- *[[#ssh-access][SSH Ready]]* - Optional SSH with root login for headless servers - *EFI Boot Redundancy* - Bootloader installed on all disks for resilience. - *[[https://github.com/junegunn/fzf][fzf]]*-Based Interface - Fuzzy search for timezone, locale, keymap, disk, RAID, and WiFi. - *NetworkManager* - WiFi configuration copied to installed system @@ -37,25 +37,6 @@ Archangel currently uses linux-lts for stability. Choosing linux and linux-zen k | RAID support | mirror, raidz1/2/3, stripe | RAID0, RAID1, RAID10 | | EFI size | 512MB | 1GB | -* Quick Start - -#+BEGIN_SRC bash -# Build the ISO (requires sudo) -make build - -# Launch a VM for interactive testing -make test-vm # single disk -make test-multi # 2 disks (mirror/RAID) -make test-multi3 # 3 disks (raidz1) -make test-boot # boot from installed disk -make test-clean # remove VM disks, start fresh - -# Run automated install tests (all configs) -make test-install -#+END_SRC - -Boot the ISO and run ~archangel~ to start the installation. - * Prerequisites The build script will report if you're missing any of these in a preflight check. @@ -76,6 +57,8 @@ The build script will report if you're missing any of these in a preflight check ** Basic Build +The makefile is your primary entry point for building, [[#testing-with-vms][testing]], and cleaning the project ISO. + #+BEGIN_SRC bash make build #+END_SRC @@ -94,6 +77,14 @@ The build script will: - Example: ~archangel-2026-01-18-vmlinuz-6.12.65-lts-x86_64.iso~ - Build logs: visible in terminal output (not saved to disk) +** Writing to USB + +#+BEGIN_SRC bash +sudo dd if=out/archangel-*.iso of=/dev/sdX bs=4M status=progress oflag=sync +#+END_SRC + +Replace ~/dev/sdX~ with your USB drive (check with ~lsblk~). + ** Clean Rebuild #+BEGIN_SRC bash @@ -101,48 +92,63 @@ make clean make build #+END_SRC -* Project Structure +* Booting the ISO -#+BEGIN_EXAMPLE -archangel/ -├── build.sh # Main ISO build script -├── Makefile # Build, lint, test, and release targets -├── installer/ -│ ├── archangel # Interactive installation script -│ ├── archangel.conf.example # Example config for unattended install -│ ├── lib/ # Modular installer components -│ │ ├── common.sh # Shared utilities -│ │ ├── config.sh # Configuration handling -│ │ ├── disk.sh # Disk partitioning -│ │ ├── zfs.sh # ZFS-specific functions -│ │ └── btrfs.sh # Btrfs-specific functions -│ ├── zfssnapshot # ZFS snapshot utility -│ ├── zfsrollback # ZFS rollback utility -│ └── RESCUE-GUIDE.txt # Recovery tools documentation -├── scripts/ -│ ├── test-vm.sh # QEMU test VM launcher -│ ├── test-install.sh # Automated install tests -│ ├── test-configs/ # Test configuration files -│ ├── full-test.sh # Comprehensive test suite -│ ├── sanity-test.sh # Quick ISO verification -│ ├── boot-vm.sh # Boot VM from disk or ISO -│ └── build-release # Build and distribute ISO -├── vm/ # VM disk images (created by test-vm.sh) -├── work/ # Build working directory -└── out/ # Built ISO output -#+END_EXAMPLE +1. Secure Boot must be disabled — ZFS kernel modules are unsigned. Check your + BIOS/UEFI firmware documentation for how to disable it. +2. Boot from USB and wait for the live environment to load. -** Script Descriptions +** SSH Access -| 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 | +The live environment automatically starts an SSH server, allowing remote access +for headless installations, rescue operations, or VM testing. Avahi is +pre-configured so you can connect by hostname from any 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. + +** 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~. +View it with ~less /root/RESCUE-GUIDE.txt~ or any text viewer. + +~tealdeer~ (tldr) is also pre-installed with an offline cache, providing concise +command examples: + +#+BEGIN_SRC bash +tldr zfs # quick ZFS command reference +tldr cryptsetup # LUKS operations +tldr dd # disk imaging +#+END_SRC + +* Installation -* Installation Walkthrough +Run ~archangel~ to start the installer. It provides a guided installation with +fzf-based selection interfaces with helpful information displayed about the +choices. -The ~archangel~ script provides a guided installation with fzf-based selection interfaces with helpful information displayed about the choices. +*Note*: Archangel performs a minimal Arch Linux installation with root login +only. No additional user accounts are created — configure those after first boot. ** Phase 1: Configuration Gathering @@ -157,7 +163,7 @@ The ~archangel~ script provides a guided installation with fzf-based selection i 9. *Root Password* - System root password 10. *SSH* - Enable SSH with root login (default: yes) -** Phase 2: Unattended Installation +** Phase 2: Installation After configuration, the installation runs without intervention: - Disk partitioning (EFI + root on each disk) @@ -168,11 +174,11 @@ After configuration, the installation runs without intervention: - Bootloader installation (ZFSBootMenu or GRUB) - Genesis snapshot creation -* Unattended Installation +** Unattended Installation For automated or headless installations, you can specify a simple plain text config file containing the choices. -** Using a Config File +*** Using a Config File #+BEGIN_SRC bash # Copy and edit the example config @@ -187,7 +193,7 @@ 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 +*** Example Config File #+BEGIN_SRC bash # archangel.conf - Unattended Installation Configuration @@ -219,7 +225,7 @@ ENABLE_SSH=yes A complete example with all options is available at ~installer/archangel.conf.example~. -** Config File Reference +*** Config File Reference | Field | Required | Default | Description | |----------------+----------+-------------+--------------------------------------------| @@ -235,33 +241,14 @@ A complete example with all options is available at ~installer/archangel.conf.ex | ~ENABLE_SSH~ | No | yes | Enable SSH server | | ~NO_ENCRYPT~ | No | no | Skip encryption (testing only) | -* Bare Metal Installation - -** Preparing Installation Media - -#+BEGIN_SRC bash -# Write ISO to USB drive (replace /dev/sdX) -sudo dd if=out/archangel-*.iso of=/dev/sdX bs=4M status=progress oflag=sync -#+END_SRC - -** Booting +* Post-Reboot -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 +** ZFS Systems 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 +** Btrfs Systems 1. GRUB menu appears 2. If encryption is enabled, enter LUKS passphrase when prompted 3. Log in as root @@ -316,88 +303,71 @@ 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. - * 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. See -[[file:testing-strategy.org][testing-strategy.org]] for the full testing strategy, including how to add new -tests and technical details on encryption testing. - -** Basic VM Test - -#+BEGIN_SRC bash -make test-vm -#+END_SRC - -This creates a 50GB virtual disk and boots the ISO. - -** Multi-Disk RAID Test - -#+BEGIN_SRC bash -# Two 50GB disks (for mirror) -make test-multi - -# Three 50GB disks (for raidz1) -make test-multi3 -#+END_SRC - -** SSH Access to VM +QEMU VMs validate that the ISO boots correctly and that installations complete +successfully across all supported configurations (ZFS/Btrfs, single/multi-disk, +encrypted/unencrypted). Run these after modifying the installer or build scripts +to catch regressions. + +See [[file:testing-strategy.org][testing-strategy.org]] for the full testing strategy, +including how to add new tests and technical details on encryption testing. + +- ~make test-vm~ — Create a 50GB virtual disk and boot the ISO in a + single-disk QEMU VM. Opens a GTK window with the VM console. SSH in + with ~ssh -p 2222 root@localhost~ (password: ~archangel~). +- ~make test-multi~ — Same as ~test-vm~ but with two 50GB disks for + testing mirror and RAID configurations. +- ~make test-multi3~ — Same as ~test-vm~ but with three 50GB disks for + testing raidz1 configurations. +- ~make test-boot~ — Boot from an existing installed disk (no ISO). + Auto-detects multi-disk setups. Use after running an install in the + VM to verify the system boots from disk. +- ~make test-clean~ — Remove all VM disks and OVMF vars to start fresh. +- ~make test-install~ — Run the full automated test suite (builds ISO + first). Runs 12 unattended installs covering ZFS/Btrfs, + single/multi-disk, encrypted/unencrypted, and custom locale. Each + test installs, reboots from disk, verifies boot, and checks rollback. +- ~make lint~ — Run shellcheck on all scripts. -*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 -ssh -p 2222 root@localhost - -# Or with sshpass -sshpass -p archangel ssh -p 2222 root@localhost -#+END_SRC - -** Clean VM State +* Project Structure -#+BEGIN_SRC bash -make test-clean -#+END_SRC +#+BEGIN_EXAMPLE +archangel/ +├── build.sh # Main ISO build script +├── Makefile # Build, lint, test, and release targets +├── installer/ +│ ├── archangel # Interactive installation script +│ ├── archangel.conf.example # Example config for unattended install +│ ├── lib/ # Modular installer components +│ │ ├── common.sh # Shared utilities +│ │ ├── config.sh # Configuration handling +│ │ ├── disk.sh # Disk partitioning +│ │ ├── zfs.sh # ZFS-specific functions +│ │ └── btrfs.sh # Btrfs-specific functions +│ ├── zfssnapshot # ZFS snapshot utility +│ ├── zfsrollback # ZFS rollback utility +│ └── RESCUE-GUIDE.txt # Recovery tools documentation +├── scripts/ +│ ├── test-vm.sh # QEMU test VM launcher +│ ├── test-install.sh # Automated install tests +│ ├── test-configs/ # Test configuration files +│ ├── full-test.sh # Comprehensive test suite +│ ├── sanity-test.sh # Quick ISO verification +│ ├── boot-vm.sh # Boot VM from disk or ISO +│ └── build-release # Build and distribute ISO +├── vm/ # VM disk images (created by test-vm.sh) +├── work/ # Build working directory +└── out/ # Built ISO output +#+END_EXAMPLE -** Boot from Installed Disk +** Script Descriptions -#+BEGIN_SRC bash -make test-boot -#+END_SRC +| 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 | * Troubleshooting -- cgit v1.2.3