Laptop from a USB stick
Build an unattended installer for a blank machine, write it to a USB drive, and boot it.
The USB installer is the Ubuntu Server 26.04 ISO with the host's profile built in. It installs Ubuntu without questions and powers off. The rest of the host is set up on first boot.
Booting the installer erases the selected disk
The installer chooses the target disk on the machine itself. It skips mounted, removable, USB and read-only disks and stops when the choice is ambiguous, but whatever disk it selects is wiped. Test the disk policy in QEMU before booting real hardware.
What you need
python3andxorrisoon your machine- A USB drive large enough for the image
- An official Ubuntu 26.04 Server amd64 ISO, or let Rookery download it
Build and write
Create the host
rookery garage-laptopIt opens on Install. Choose USB installer under How To Install, and keep Target at laptop. Hostname is the name the machine gets. F4 generates one.
Optionally, join the tailnet
Tailscale is on Install too. With it on, Rookery makes a one-use key through the control server's API each time it builds the installer, from the secret tailnet_api_key (joining the tailnet). Tailnets that require tags take them from rookery config set tailnet_tags tag:rookery. For a Headscale server, see Headscale.
The key lasts 24 hours. When Rookery builds the image, it says until when the image can join the tailnet. A machine installed later is set up without the tailnet, and the next apply from Rookery joins it.
Set up the accounts
On Settings, fill in the operator's SSH public key and a password under Operator Account.
Choose the disk
Under Installer on Settings, set Disk selection. auto, the default, takes the only eligible internal disk. The other modes are in the table below.
Set up the network
Wired DHCP is always configured. To add Wi-Fi, switch Wi-Fi on under Installer and give the SSID and password. Leave the interface blank: the installer finds the wireless interface on the target and falls back to wired networking when there is none.
Choose the ISO
Source ISO on Run is the Ubuntu Server ISO to build from, a path on the machine the server runs on. Left empty, the build downloads the current one and checks it against Ubuntu's SHA256SUMS. For a file you already have, put the SHA-256 from Ubuntu's signed SHA256SUMS in ISO SHA256. The build checks the file against it.
Build and write
Press Enter on Run · USB installer. Rookery saves the profile and opens the host's overview with its action Build the USB installer. Its dialog takes the drive to write and your sudo password for writing it. The help of the drive lists the USB drives connected now. When one drive is connected, it's filled in. Leave the drive empty to build the ISO alone. The build and the writing run as a job, whose output fills a panel.
The installer is built on the machine the server runs on, which writes one of its own drives. Rookery on your machine does it with the server inside Rookery, or with a rookery serve of yours there. From another machine the action is listed as unavailable, with that reason.
The same from the command line:
rookery host iso garage-laptop # downloads the ISO when none is set
rookery host iso garage-laptop --write /dev/sdX # and writes it, after askingThe image is ~/.local/share/rookery/build/HOSTNAME-autoinstall.iso. To write it by hand, use the script from the provisioning source. It accepts only a whole USB disk that is large enough and has no system mount on it, and unmounts anything else first:
sudo provision/bin/write-usb.sh HOSTNAME-autoinstall.iso /dev/sdXBoot it
- Boot the target from the USB drive. The installer runs without input and powers off.
- Remove the drive and power on. The first-boot service installs the desktop and applications and retries failures that pass. It needs network access.
- Follow progress over SSH, or on the console:
sudo journalctl -u rookery-provision -f
cat /var/lib/rookery/provision-state
sudo systemctl start rookery-provision.service # start it again after a failureconfigured means the role finished. The ready marker means Ansible converged, not that every acceptance test passed. If a dependency fails, the state is failed and a timer retries. The success marker is only written after a successful run.
Without a tailnet or recovery CIDR
The installed machine accepts SSH only from the tailnet, unless you set a Recovery SSH CIDR. Keep Tailscale on with the secret tailnet_api_key set, set the CIDR, or be ready to use the console.
Disk selection
target_disk_mode sets how the installer picks the disk:
| Mode | Selects |
|---|---|
auto | The only eligible disk. The default for new profiles |
serial | The disk whose udev ID_SERIAL is exactly target_disk_serial |
model | target_disk_model matched against udev ID_MODEL, with globs such as Samsung* |
path | target_disk_path, with globs; exact /dev/disk/by-id links are resolved |
largest / smallest | By capacity among eligible disks |
ssd / hdd | The only eligible non-rotating or rotating disk |
For auto, model, path, largest and smallest, target_disk_ssd narrows the candidates to any, ssd or hdd. Each mode needs exactly one final candidate, including when capacities tie. The Settings tab shows the fields of the chosen mode.
{
"target_disk_mode": "auto",
"target_disk_ssd": "ssd"
}A serial comes from udevadm info --query=property --name=/dev/nvme0n1. The disk is selected during the installer's early commands and the storage configuration is then pinned to its path. Disk selection applies only to the USB installer. Cloud seeds and installs over SSH keep the existing disk layout.
Image contents
The ISO keeps the source image's boot configuration through xorriso replay and patches GRUB to install automatically. It embeds the seed and the release archive. The bootstrap checks the archive against the digest in the seed.
The USB drive and its seed can still hold credentials after the installed copies have been used. The enrollment key Rookery puts in it works once and for 24 hours. Secure Boot with the remastered image has not been qualified.
Without Rookery
From a source checkout, copy provision/config/example.json to provision/config/local.json (ignored by git), fill it in, and run the builder directly:
python3 provision/bin/rookery.py render --config provision/config/local.json
python3 provision/bin/rookery.py iso --config provision/config/local.json \
--iso /path/to/ubuntu-26.04-live-server-amd64.iso \
--sha256 THE_VERIFIED_SHA256 # optional: fail if the ISO differsThe output is build/HOSTNAME-autoinstall.iso. The builder refuses to replace an existing image without --overwrite. Rookery always rebuilds it. Password hashes for a hand-written profile come from mkpasswd -m sha-512. In JSON, Wi-Fi is wifi_enabled: true and a wifi object with ssid, password and optionally interface.
Last updated on