Provision the stick

With the files filled in, plug in the stick you wrote earlier and copy them onto it:

just provision

just provision finds the stick by its BOOMSTICK partition label, mounts it if it has to, writes boomstick/, and unmounts it again so it is ready to pull.

Before copying anything, it checks the files for the mistakes that would leave a headless machine unreachable, and fails here, at your desk, instead of later on the other side of the room. An authorized_keys with no keys in it is refused outright, since nobody could log in. A wg0.conf that is filled in but missing its PrivateKey or PersistentKeepalive is refused too. A wg0.conf left untouched is fine – that is just a stick without WireGuard, and it says so.

Editing the stick by hand instead

If you would rather skip secrets/ and edit the stick directly, mount its partition with udisksctl rather than sudo mount:

udisksctl mount -b /dev/sdX1

FAT stores no file ownership, so a plain sudo mount makes every file look like it belongs to root, and you cannot edit them as yourself. udisksctl mounts it as your own user, at /run/media/$USER/BOOMSTICK.

Changing it later

Everything that makes the stick yours lives in a handful of plain files. When you move to a new WiFi network, rotate a WireGuard key, or add someone’s SSH key, you edit a file on the stick – or in secrets/, then run just provision again – and you are done, with nothing to rebuild.

boomstick-config re-reads all of it on every boot, which is what makes that true. The same mechanism updates setup itself: just provision copies the current installer to boomstick/bin/setup, and the live system installs that copy over its own at boot. So a fix to setup reaches a stick without a rebuild.

What a stick cannot grow into is anything that lives in the live system itself – the squashfs the image was built from:

• the package set: the live system’s own git, cryptsetup, archlinuxarm-keyring and the rest,
• the kernel and initramfs, and
• boomstick-config, boomstick-webhook and boomstick-motd, the boot-time logic itself.

Those are frozen at build time, and the way to move them forward is to build a new image and write it to the stick again – then just provision to put your configuration back, since a fresh image carries only the templates.

Updating from the stick itself

just provision needs your workstation and a checkout of the repository. boomstick-update, on the live system, does the same job over the network when you have neither – which, for a tool meant for installing machines in other rooms and other buildings, is a situation that comes up.

boomstick-update

It clones the repository, says where from and which commit it resolved to, shows a diff of every helper that would change, and asks. Enter declines. What you accept is written to boomstick/bin/ on the stick, so the next boot has it, and to /usr/local/bin in the running system, so this boot has it too – no reboot in between. Each run appends a line to boomstick/UPDATES.txt, so the stick carries a record of what it has been given.

It updates BOOMSTICK, not Arch. The live system stays the one the image was built with – the same pacman, the same keyring, the same kernel – so this is no answer to an image going stale on a rolling release. Its reach is exactly just provision’s: the helpers, and nothing else. boomstick-config is deliberately left out too, since it is what installs the others at boot and a broken copy would take configuration down with it on every later boot. For the package set, the kernel, or that, rebuild.

It refuses to run while something is mounted at /mnt, since replacing setup under a running install is nobody’s idea of a good afternoon, and when the stick is not plugged in – copytoram means the live system keeps going without it, but then there is nothing to write to.

--ref takes a branch or a tag, and defaults to the repository’s default branch, which is not necessarily where your stick came from. A stick built from a topic branch will find the default branch has none of its helpers, and boomstick-update says so rather than reporting everything up to date.

Upgrading a stick you already have

Writing a new image to a stick erases the only copy of some of its secrets. The WireGuard key and the SSH host keys it made on its first boot exist nowhere else: secrets/ on your workstation may be long gone, or may never have been on this workstation at all. So take them off the stick before you write anything to it.

git clone https://github.com/EnigmaCurry/boomstick
cd boomstick
just adopt

just adopt finds the stick by its BOOMSTICK label and copies back what the repository cannot regenerate – the WiFi PSKs, wg0.conf, authorized_keys, webhook.env and ssh/host/ – into secrets/, owned by you and readable by nobody else. README.txt and bin/ are left alone: those come from the repository, not from the stick.

It refuses to overwrite a secrets/ that already has files in it, and says which ones clashed, so aiming it at the wrong stick cannot quietly replace a working configuration with somebody else’s. just adopt --force when the stick really is the one to keep.

With the secrets safe, the rest is the ordinary path: build a new image, write it to the stick, and just provision to put the configuration back.

Where to go next

The stick is now ready. Go to Boot the stick and connect to use it – or, if you would rather know what the stick does at boot before you trust it with a machine, read How it works under the hood first.