alpine-qemu-install
===================
Unattended install of Alpine Linux onto a disk image, driven entirely over the
serial console. No keypresses, no graphics, no interaction.


What it does
------------
Given an Alpine virt ISO and a disk image you created beforehand, the script:

  - extracts the kernel, initramfs, and modloop from the ISO
  - builds an apkovl overlay containing the kernel modules and a first-boot
    script
  - boots that kernel under QEMU with the disk attached as /dev/vda
  - runs setup-alpine non-interactively against a pre-baked answer file
  - patches the installed root password, SSH key, and serial getty
  - powers the guest off when finished

The disk image is the target. It appears as /dev/vda inside the guest and is
erased. After install the layout is vda1=boot, vda2=swap, vda3=root.


Requirements
------------
On the host:

  - 7z (7zip or p7zip-full; extracting the modloop squashfs needs it)
  - GNU tar
  - openssl
  - qemu-system-x86_64

KVM is used automatically when /dev/kvm is writable, otherwise the install
runs under plain emulation (slower, but works). You also need an x86_64
Alpine virt ISO and a disk image created up front with qemu-img. qcow2 is
recommended: it allocates sparsely and supports snapshots. Any other format
qemu-img writes also works, since QEMU detects it.


Usage
-----
Create a disk, then run the install:

    qemu-img create -f qcow2 disk.qcow2 2G
    ROOT_PASSWORD=changeme \
        ./alpine-qemu-install alpine-virt-3.20.0-x86_64.iso disk.qcow2

The install log streams to your terminal. When it reaches the end the guest
powers off and the script exits. Boot the resulting image however you like,
for example:

    qemu-system-x86_64 -m 1024 -nographic -drive file=disk.qcow2,if=virtio


Configuration
-------------
Configuration is by environment variable. Only ROOT_PASSWORD is required.

  - ROOT_PASSWORD  root password for the installed system (required)
  - ROOT_PUBKEY    an authorized_keys line; enables root SSH login
  - SSHD           openssh, dropbear, or none (default openssh)
  - VM_HOSTNAME    installed hostname (default alpine)
  - APK_MIRROR     apk mirror base URL
                   (default https://dl-cdn.alpinelinux.org/alpine)
  - RAM_MB         guest memory in MB during install (default 1024)
  - SMP            guest CPU count during install (default 2)

The mirror must be reachable during install: setup-alpine fetches packages
before the disk is even partitioned.


How it works
------------
QEMU's vvfat is unreliable for the ~150 MB modloop file, and a failed
modloop mount leaves the initramfs without /lib/modules, so setup-alpine
cannot modprobe, partition, or run post-install scripts. To avoid that path,
the script unpacks the modloop squashfs on the host and ships the modules
inside the apkovl overlay instead. Only one small file goes on the vvfat
drive: the apkovl tarball itself.

The first-boot work runs from /etc/local.d/autoinstall.start via the default
runlevel's local service. It removes itself before setup-disk copies the
overlay onto the target, so the trigger never fires on the installed system.


Debugging
---------
The install is fully visible. QEMU runs with -nographic, so everything the
first-boot script does is logged to ttyS0, which is your terminal. The script
runs under set -x, so each command is printed before it runs.

QEMU runs with -no-reboot, so on success or failure the guest stays down and
the full log remains on screen. To leave QEMU manually, press Ctrl-a then x.

The guest reports distinct success and failure values through qemu's
isa-debug-exit device. The script exits 0 only when the guest reported
completion, 3 when the first-boot script failed, and 1 when qemu stopped
without any result, including a manual Ctrl-a x.

Common failures:

  - "need 7z" or "need qemu-system-x86_64": install the missing host tool.
  - "modloop layout changed": install 7zip or p7zip-full, or the ISO changed
    and the modloop extraction needs updating.
  - "/dev/vda did not appear": the disk image was not attached or is missing.
  - apk fetch errors: the mirror is unreachable or APK_MIRROR is wrong.


Security
--------
ROOT_PASSWORD is hashed on the host; openssl reads it on stdin, so the
plaintext never reaches the guest, the apkovl, the set -x install log, or
a process listing. The hash is kept out of the log too, but any crypt hash
can be attacked offline, so pick a real password for images you keep. Root
SSH login is key-only: ROOT_PUBKEY installs the key, and Alpine's default
PermitRootLogin prohibit-password refuses password logins over SSH.