Hooks: device setup

hook group for Ubuntu Core developers for snapd developers

Four hooks that only the model's gadget or kernel can run, scheduled by the device manager instead of snapstate. install-device ends install mode and factory reset; prepare-device configures registration before the device key and the serial request; prepare-serial-request and fde-setup run synchronously inside snapd's own code with no task of their own.

On the map: hooks district

▶ Watch this deck — 6 scenes, ~5 min

01 Four hooks only the gadget and kernel run

FOUR DEVICE HOOKS install mode reboot run mode, after seeding registered install-deviceacme-gadget task in install-systemor factory-reset fde-setupacme-kernel no task: calledwhile installing prepare-deviceacme-gadget task in become-operational request-serial prepare-serial-requestacme-gadget no task: inside request-serial run-hook task ephemeral: run from snapd's code, no task no plug name: four fixed names, only from the model's gadget or kernel none optional, none ignore errors: scheduled only when the file exists
A device timeline from install mode through a reboot to run mode after seeding and then registered; install-device and fde-setup sit in install mode, prepare-device and prepare-serial-request in run mode; two are run-hook tasks, the dashed two run from snapd's code with no task

Gadget: install-device, prepare-device, prepare-serial-request. Kernel: fde-setup. The dashed two have no task in snap change. acme-gadget and acme-kernel are examples.

Some hooks don't belong to an app at all. They belong to the gateway itself. The device manager runs them, and only from the model's gadget, acme-gadget, or for fde-setup, its kernel. In install mode, install-device is the gadget's last step, and fde-setup answers the installer's questions while the disk is being encrypted. Back in run mode, prepare-device starts registration, and prepare-serial-request runs in the middle of asking for a serial. Two are ordinary run-hook tasks. The other two run straight from snapd's code, with no task at all. None has a plug name, and snapd schedules each only when the gadget or kernel ships it.

02 Registration: one hook, then key and serial for Ubuntu Core developers for snapd developers

REGISTRATION become-operational "Initialize device" run-hookRun prepare-device hook generate-device-keyGenerate device key request-serialRequest device serial acme-gadget prepare-device (example) snapctl set registration.proposed-serial=\ "\"${product_serial}\"" snapctl set device-service.url=\ "https://serial-vault.acme.example/v1/" snapctl set device-service.headers=…api-key… gadget config read by request-serial device-service.url device-service.headers registration.body registration.proposed-serial device-service.access ✗ change fails → new attempt after 5 min, doubling, up to 24 h → prepare-device runs again no device-service.url: the store's serial vault a remodel's re-registration does not run prepare-device
The become-operational change runs the prepare-device hook, then generate-device-key, then request-serial; the hook sets gadget configuration such as device-service.url and headers, which request-serial reads; on failure the whole change is retried later with backoff, running the hook again

prepare-device configures registration; it does not register. The values stay in the gadget's configuration, visible with snap get acme-gadget. A re-registration during a remodel does not run this hook. The URL and key are examples.

The gateway has booted into run mode and finished seeding, but it has no serial yet, so the store has no name for it. Snapd starts the become-operational change. If acme-gadget ships prepare-device, that hook is the first task. It doesn't register anything. It only sets gadget configuration: the serial vault URL, headers such as an API key, a proposed serial, a request body. generate-device-key waits for it, and request-serial reads those values. If anything fails, the change fails, and snapd tries again after five minutes, doubling, up to a day, running the hook again. With no URL set, the store's own serial vault is used.

03 prepare-serial-request: a hook inside a task for Ubuntu Core developers for snapd developers

A HOOK INSIDE A TASK request-serial GET request-id set registration.request-id prepare-serial-request REQUEST_ID=$(snapctl get registration.request-id)SIG: the id signed with the hardware key snapctl set registration.body="{\"hardware-id-key\": \"$KEY\", \"hardware-id-key-sha3-384\": \"$HASH\", \"request-id-signature\": \"$SIG\"}" readregistration.body sign serial-request, POST failed to run prepare serial request hook: 'prepare-serial-request' hook did not set mandatory field "request-id-signature" in registration body runs inside request-serial, not as a task of its own not listed in snap change; its failure is the failure of request-serial
Inside the request-serial task: get a request-id, set registration.request-id, run the prepare-serial-request hook, read registration.body, then sign and post the serial request; the hook script writes two mandatory fields; the hook runs inside the task, not as a task of its own

prepare-serial-request does not appear in snap change; its failure appears as the failure of request-serial, with failed to run prepare serial request hook. A gadget using it also needs prepare-device for the URL.

Acme's serial vault wants proof that a request comes from real acme hardware. That's what prepare-serial-request is for. First, snapd asks the device service for a fresh request-id and stores it as registration.request-id. Then it runs the gadget's hook right there, inside the request-serial task. The hook reads the id, signs it with the hardware key, and writes registration.body as a JSON object. Snapd refuses a body without hardware-id-key-sha3-384 and request-id-signature, and either error fails request-serial. It runs inside the task, not as one.

04 install-device: the gadget's last step in install mode for Ubuntu Core developers for snapd developers

HOW THE GADGET ENDS INSTALL MODE install-system "Install the system" setup-run-system setup-ubuntu-saveonly when the hook exists run-hookinstall-device restart-system-to-run-mode what the hook can do (examples) hostnamectl set-hostname acme-gw-0042 write to $SNAP_SAVE_DATA snapctl reboot --poweroffroad: snapctl lifecycle exit 0 → reboot into run mode (or halt, poweroff; run mode on next boot) exit ≠ 0 → install-system fails, no run mode factory-reset factory-reset-run-system install-device restart-system-to-run-mode a gadget with install-device: snap-bootstrap does not install and run from the initramfs in one boot
The install-system change runs setup-run-system, setup-ubuntu-save, the install-device hook and restart-system-to-run-mode; the hook can set the hostname, write to ubuntu-save or choose poweroff; success reboots into run mode, failure leaves the device in install mode; factory-reset runs the same hook before the same restart

install-device runs once per install or factory reset, with the default ten-minute limit. It is not optional and its failure is not ignored. snapctl reboot --halt or --poweroff works only here.

In the factory, install mode ends with the install-system change, and acme-gadget gets the last word before the first boot into run mode. Because the gadget ships install-device, snapd first sets up ubuntu-save, then runs the hook, then the task that makes the next boot run mode. The hook can set the hostname, write files to the save partition, or ask to halt or power off instead of rebooting. If it fails, the change fails and the device doesn't boot into run mode. factory-reset runs the same hook before the same restart. And a gadget with this hook turns off installing straight from the initramfs.

05 fde-setup: called by the installer, not scheduled for Ubuntu Core developers for snapd developers

FDE-SETUP: CALLED, NOT SCHEDULED install mode decide encryption create partitions seal keys restart-system-to-run-mode fde-setup (acme-kernel)op: "features" 5 min, no task {"features":[…]} → encrypt error → not encrypting device storage as querying kernel fde-setup hook did not succeed unless the model requires encryption fde-setup (acme-kernel)op: "initial-setup" 5 min, no task boot, initramfs: fde-reveal-key unlocks, not this hook the handshake:snapctl: device and system
Install mode decides encryption, creates partitions, seals keys and restarts; the kernel fde-setup hook is called with no task twice, with op features while deciding encryption and op initial-setup while sealing keys; a failed features query means no encryption unless the model requires it; at boot fde-reveal-key unlocks, not this hook

Two ops, features and initial-setup, each a synchronous call with a fixed 5-minute limit. A failed features query means an unencrypted install unless the model requires encryption.

Acme's board has no TPM, but its disk should still be encrypted. So its kernel snap, acme-kernel, ships an fde-setup hook to protect the keys. Snapd runs it with no task, straight from the install code, with a fixed five minute limit. The first call asks which features the hardware supports. If that call fails, snapd installs without encryption and warns, unless the model requires encryption. Later, to seal the disk key, snapd calls the hook again with initial-setup. At boot, the initramfs unlocks the disk with fde-reveal-key, not with this hook.

06 Where to go from here

ROADS Hooks: device setup Hooks: how they workthe shared mechanism snapctl: services, refresh…reboot from install-device snapctl: device and systemthe fde-setup request and answer Encryption without a TPMwhat fde-setup protects Model, gadget and kernelwhere these hooks live Ubuntu Core: boot and recoveryinstall mode, factory reset Assertions: devicesthe serial registration ends with Install and refresh hooksthe gadget's configure The overlorddevice changes and tasks
Roads from Hooks: device setup: how hooks work, snapctl services refresh and changes, snapctl device and system, encryption without a TPM, model gadget and kernel, Ubuntu Core boot and recovery, device assertions, install and refresh hooks, and the overlord

Roads: the mechanism, two snapctl decks, encryption without a TPM, model, boot and recovery, device assertions, lifecycle hooks and the overlord.

Those are the device's own hooks. The hooks deck covers what every hook shares. Two snapctl decks cover snapctl reboot from install-device, and the fde-setup request and answer. Encryption without a TPM shows what an fde-setup hook protects, and how. The model deck covers the gadget and kernel that carry these hooks, and the Ubuntu Core deck covers install mode and factory-reset. The device assertions cover the serial that registration ends with. The lifecycle hooks deck covers the gadget's configure hook, which applies its defaults before registration. And the overlord covers device changes.

Read more

The changes these hooks run in

ChangeKindTasks
Initialize devicebecome-operationalrun-hook prepare-device, generate-device-key, request-serial (prepare-serial-request runs inside it)
Install the systeminstall-systemsetup-run-system, setup-ubuntu-save, run-hook install-device, restart-system-to-run-mode
Factory resetfactory-resetfactory-reset-run-system, run-hook install-device, restart-system-to-run-mode

setup-ubuntu-save is added only when the gadget ships install-device. fde-setup runs from the install code, during the encryption decision and when keys are sealed, outside any task.

become-operational starts in run mode after seeding, when the device has no serial. When it fails, the next attempt waits 5 minutes, then twice as long each time; once the wait would pass 12 hours it becomes 24 hours. Every attempt runs prepare-device again. A re-registration during a remodel runs request-serial without prepare-device.

Gadget options read by registration

prepare-device sets these with snapctl set; they stay in the gadget's configuration.

OptionMeaning
device-service.urlthe serial vault to ask; without it, the store's
device-service.headersa JSON object of extra HTTP headers, such as an API key
device-service.accessoffline: no serial is requested
registration.proposed-serialthe serial the device proposes
registration.bodythe body of the serial request; prepare-serial-request must set it as a JSON object
registration.request-idset by snapd for prepare-serial-request to read

With prepare-serial-request, a retry of request-serial currently fails to read registration.body, because the hook stores an object and the retry reads a string (snapd bug, fix pending).

Messages

MessageMeaning
failed to run prepare serial request hook: ...prepare-serial-request failed, or its body was incomplete; request-serial fails
'prepare-serial-request' hook did not set mandatory field "<field>" in registration bodyhardware-id-key-sha3-384 or request-id-signature is missing
cannot run hook for "<op>": ...fde-setup failed for the op features or initial-setup
cannot get result from fde-setup hook "<op>": ...fde-setup exited without calling snapctl fde-setup-result
not encrypting device storage as querying kernel fde-setup hook did not succeed: ...the features query failed and the model does not require encryption

Two hooks without a task

run-hook taskprepare-serial-request, fde-setup
One hook per snap at a timeyesno
Conflicts with other changesyesno
Undopossiblenone
Can be abortedyesno
Logthe task logsnapd's journal
Time limit10 minutes by default10 minutes; fde-setup a fixed 5 minutes

A gadget with an install-device hook makes snap-bootstrap skip installing and running from the initramfs in one boot, because the hook cannot run there.

Further reading

Roads from here

RUNNING SNAPS

SNAPCTL · the snap's API into snapd

ASSERTIONS · signed statements snapd trusts

HOOKS · code snapd runs inside a snap

UBUNTU CORE · boot

UBUNTU CORE · install and recovery

UBUNTU CORE · full disk encryption