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
01 Four hooks only the gadget and kernel run
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
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
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
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
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: 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
| Change | Kind | Tasks |
|---|---|---|
| Initialize device | become-operational | run-hook prepare-device, generate-device-key, request-serial (prepare-serial-request runs inside it) |
| Install the system | install-system | setup-run-system, setup-ubuntu-save, run-hook install-device, restart-system-to-run-mode |
| Factory reset | factory-reset | factory-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.
| Option | Meaning |
|---|---|
device-service.url | the serial vault to ask; without it, the store's |
device-service.headers | a JSON object of extra HTTP headers, such as an API key |
device-service.access | offline: no serial is requested |
registration.proposed-serial | the serial the device proposes |
registration.body | the body of the serial request; prepare-serial-request must set it as a JSON object |
registration.request-id | set 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
| Message | Meaning |
|---|---|
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 body | hardware-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 task | prepare-serial-request, fde-setup | |
|---|---|---|
| One hook per snap at a time | yes | no |
| Conflicts with other changes | yes | no |
| Undo | possible | none |
| Can be aborted | yes | no |
| Log | the task log | snapd's journal |
| Time limit | 10 minutes by default | 10 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
- Secure device onboarding: registration with a serial vault, and what prepare-device and prepare-serial-request are for.
- Gadget snap format: the prepare-device options and examples.
- How installation works: install mode, and where install-device runs.
- Full disk encryption hooks: the fde-setup and fde-reveal-key protocol.
Roads from here
RUNNING SNAPS
- The overlord — the device changes these tasks belong to
SNAPCTL · the snap's API into snapd
- snapctl: services, refresh and changes — snapctl reboot from install-device
- snapctl: device and system — the fde-setup request and result handshake
ASSERTIONS · signed statements snapd trusts
- Assertions: devices — the serial assertion that registration produces
HOOKS · code snapd runs inside a snap
- Hooks: how they work — how hooks run and fail in general
- Hooks: install, configure, refresh, remove — the configure hook that applies gadget defaults first
UBUNTU CORE · boot
- Ubuntu Core: how a device boots and recovers — install mode and factory reset and full disk encryption
UBUNTU CORE · install and recovery
- Model, gadget and kernel — the gadget and kernel snaps that carry these hooks
UBUNTU CORE · full disk encryption
- Encryption without a TPM — what an fde-setup hook protects and how