Arch Linux ISO and installer with ZFS and Btrfs support.

Overview

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 with data recovery, boot repair, hardware diagnostics, and other tools pre-installed. An SSH server starts automatically making remote connections dead easy.

Features

• Dual Filesystem Support - Choose ZFS or Btrfs during installation (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 into snapshots
• 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.
• NetworkManager - WiFi configuration copied to installed system
• Unattended Install - Headless installation via a single plain text config file
• Rescue Disk - Data recovery, boot repair, hardware diagnostics, and more

Archangel currently uses linux-lts for stability. Choosing linux and linux-zen kernel varieties coming shortly.

Filesystem Comparison

Prerequisites

The build script will report if you're missing any of these in a preflight check.

Build Host Requirements

• Arch Linux (or Arch-based distribution)
• Root/sudo access
• archiso package (pacman -S archiso) — auto-installed if missing
• ~10GB free disk space for build

Runtime Dependencies (included in ISO)

• ZFS kernel modules (via zfs-dkms)
• Btrfs tools
• NetworkManager
• fzf for interactive selection

Building the ISO

Basic Build

The makefile is your primary entry point for building, testing, and cleaning the project ISO.

make build

The build script will:

1. Copy the base Arch releng profile
2. Switch to linux-lts kernel
3. Add the archzfs repository (for ZFS packages)
4. Add custom packages (ZFS, Btrfs, NetworkManager, fzf, etc.)
5. Copy the archangel installer script
6. Build the ISO using mkarchiso

Build Output

• ISO location: out/archangel-YYYY-MM-DD-vmlinuz-{version}-lts-x86_64.iso
• 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

sudo dd if=out/archangel-*.iso of=/dev/sdX bs=4M status=progress oflag=sync

Replace /dev/sdX with your USB drive (check with lsblk).

Clean Rebuild

make clean
make build

Booting the ISO

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.

SSH Access

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:

ssh root@archangel.local     # via mDNS (avahi)

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:

tldr zfs                     # quick ZFS command reference
tldr cryptsetup              # LUKS operations
tldr dd                      # disk imaging

Installation

Run archangel to start the installer. It 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

1. Filesystem - Choose ZFS or Btrfs
2. Hostname - System hostname
3. Timezone - Fuzzy search through all timezones
4. Locale - All locales available
5. Keymap - Console keyboard layout
6. Disk Selection - Multi-select with TAB (preview shows disk details)
7. RAID Level - For multi-disk: mirror, stripe, raidz1/2/3 (ZFS) or RAID0/1/10 (Btrfs)
8. Encryption - Encryption passphrase (ZFS native or LUKS2)
9. Root Password - System root password
10. SSH - Enable SSH with root login (default: yes)

Phase 2: Installation

After configuration, the installation runs without intervention:

• Disk partitioning (EFI + root on each disk)
• Filesystem creation with encryption
• Dataset/subvolume creation
• Base system installation via pacstrap
• System configuration (locale, timezone, hostname)
• Bootloader installation (ZFSBootMenu or GRUB)
• Genesis snapshot creation

Unattended Installation

For automated or headless installations, you can specify a simple plain text config file containing the choices.

Using a Config File

# Copy and edit the example config
cp /root/archangel.conf.example /root/my-install.conf
$EDITOR /root/my-install.conf

# Run with config file
archangel --config-file /root/my-install.conf

Important: The config file is ONLY used when explicitly specified with --config-file. The installer will never automatically read a config file to prevent accidental disk destruction.

Example Config File

# 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

A complete example with all options is available at installer/archangel.conf.example.

Config File Reference

Post-Reboot

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

1. GRUB menu appears
2. If encryption is enabled, enter LUKS passphrase when prompted
3. Log in as root

Post-Installation

ZFS Snapshot Management

# Create a snapshot
zfssnapshot "before-experiment"

# Interactive rollback with fzf
zfsrollback

# List snapshots
zfs list -t snapshot

Btrfs Snapshot Management

# Create a snapshot (via snapper)
snapper -c root create -d "before-experiment"

# List snapshots
snapper -c root list

# Rollback (requires reboot)
snapper -c root rollback <number>

Genesis Snapshot

Both filesystems create a "genesis" snapshot after installation, representing the pristine post-install state.

# ZFS: View genesis snapshot
zfs list -t snapshot | grep genesis

# Btrfs: View genesis snapshot
snapper -c root list | grep genesis

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.

Testing

Two test layers: make test runs shellcheck + bats unit tests for the pure logic in installer/lib/*.sh (fast, no VMs). make test-install runs the full VM integration suite against a freshly built ISO. Use the former every commit; the latter before releases or when touching install paths.

See testing-strategy.org for the full testing strategy, unit-test coverage, how to add new tests, and technical details on encryption testing.

• make test — Run shellcheck + bats unit tests (~1s, no VMs needed).
• make bats — Run bats unit tests only.
• make lint — Run shellcheck on all scripts.
• 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.

Project Structure

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, password prompt, pacstrap list
│   │   ├── config.sh              # Argument parsing + config-file loading + validation
│   │   ├── disk.sh                # Disk partitioning and EFI formatting
│   │   ├── btrfs.sh               # Btrfs-specific functions (LUKS, subvolumes, GRUB)
│   │   └── raid.sh                # Pure RAID-level logic (levels, validation, usable space)
│   ├── zfssnapshot                # ZFS snapshot utility
│   ├── zfsrollback                # ZFS rollback utility
│   └── RESCUE-GUIDE.txt           # Recovery tools documentation
├── tests/
│   └── unit/                      # Bats unit tests for installer/lib/*.sh
├── 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

Script Descriptions

Troubleshooting

Build Fails with Package Conflicts

Clean the work directory and rebuild:

make clean
make build

ZFS Module Not Loading

The ISO includes DKMS-built ZFS modules. If modules fail to load:

• Check dmesg | grep -i zfs for errors
• Ensure you're using the LTS kernel

Disk Not Showing in Selection

• Ensure the disk is not mounted
• Check lsblk to verify disk visibility
• USB drives may need a moment to be detected

Boot Fails After Installation

ZFS

• Check ZFSBootMenu appears (if not, check EFI boot order with efibootmgr)
• Verify pool can import: boot ISO, zpool import -f zroot

Btrfs

• Verify EFI boot entries: efibootmgr -v
• Check GRUB config: /boot/grub/grub.cfg

Links

• archzfs Repository - ZFS packages for Arch Linux (GitHub Releases; archzfs.com was abandoned mid-2025)
• OpenZFS Documentation - Official ZFS documentation
• ZFSBootMenu - ZFS boot manager
• Arch Wiki - Btrfs - Btrfs information
• Arch Wiki - Snapper - Btrfs snapshot management
• grub-btrfs - Boot Btrfs snapshots from GRUB

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See LICENSE file for the full license text.

Note: OpenZFS is licensed separately under the CDDL license. ZFS packages are provided by the archzfs third-party repository and are not part of this project.