Hooks: install, configure, refresh, remove
hook group for app developers for Ubuntu Core developers for snapd developers for administrators for users
Eight snap hooks and four component hooks that snapd places at fixed points of install, refresh, revert and remove. install runs once after the snap is linked and connected; default-configure runs before services start and configure after; pre-refresh runs in the old revision and post-refresh in the new; check-health ends every install and refresh and can roll it back; remove cannot stop a removal. gate-auto-refresh is still accepted but does not run.
On the map: hooks district
01 Four commands, fixed hook points
Hook tasks in snap change read Run install hook of "acme-agent" snap if present. Only configure run by snap set is required; only remove may fail without effect.
You install acme-agent, refresh it, maybe revert it, and one day remove it. Where does its own code get a say? Snap install makes the snap current, runs the install hook and default-configure, starts the agent, then runs configure and the health check. The install hook runs on the first install only. Snap refresh puts pre-refresh and post-refresh around the switch of revision, and snap revert runs neither. Configure and the health check end all three. Snap remove runs the remove hook only when the whole snap goes, and ignores its failure. Each step is optional: no hook, nothing runs. And gate-auto-refresh is still accepted, but nothing runs it.
02 First install, in order for app developers for Ubuntu Core developers for snapd developers
install → default-configure → services start → configure → check-health. default-configure requires a configure hook and is not allowed in base, snapd or OS snaps.
It's the gateway's first boot, and acme-agent is being installed for the first time. In what order does its code run? Snapd links the new revision and makes its connections first, so the connect hooks of those connections have already run. Then comes the install hook, on this first install only, with the agent not running. Default-configure follows, if the snap has one, and the agent is still stopped: snapctl services shows it disabled and inactive. The gadget's defaults arrive there, or in configure if there's no default-configure. Then snapd starts the services, configure runs with the agent active, and the health check comes last.
03 pre-refresh runs in the old revision, post-refresh in the new for app developers for snapd developers for administrators
Which pre-refresh runs is decided by the revision being replaced, not the one arriving. Neither hook runs on snap revert. The file in the drawing is an example.
Now acme-agent goes from revision 41 to 42. Whose code runs where? Pre-refresh comes from 41, while 41 is still current and the agent still running. It's 41's last word: anything it writes to $SNAP_DATA, copy-snap-data carries over to 42's data a few steps later. Then the services stop, 41 is unlinked, and 42 is linked. Post-refresh runs in 42, before its services start, so it can convert that data first. The install hook doesn't run again. Snap revert runs neither refresh hook, and neither does an update that only changes components. And auto-refresh no longer asks a gate-auto-refresh hook.
04 A late hook failure rolls the refresh back for app developers for snapd developers for administrators
After link-snap, a failing post-refresh, configure or check-health reverts the refresh. Configuration is restored; files are not. snapctl set-health error with exit 0 keeps the refresh.
Revision 42 is linked and its post-refresh hook went fine. Then the health check, which has thirty seconds, finds the agent can't reach its server, and exits with an error. What now? A failure this late, in post-refresh, configure or the health check, fails the change, and snapd undoes it task by task, back to 41. Lifecycle hooks have no undo hooks of their own, so 41's pre-refresh isn't told. The configuration saved when 42 was linked comes back, so values 42's hooks set are dropped. Files they wrote stay. If you only want to report the problem and keep 42, set-health to error and exit zero.
05 The remove hook cannot stop a removal for app developers for administrators for snapd developers
remove errors are ignored and only logged. It runs before auto-disconnect and before the snapshot, and not when snap remove --revision leaves other revisions.
You remove acme-agent from the gateway. Its remove hook tries to tell the server the gateway is leaving, and the server doesn't answer. Does the removal stop? No. When the hook runs, the services are stopped but the interfaces are still connected, so it can still reach the network. If it fails, snapd logs ignoring failure in hook and carries on. Next, auto-disconnect runs the disconnect hooks of each connection. Then the automatic snapshot is taken, so anything the hook deletes from $SNAP_DATA isn't in it. And removing an older revision with the --revision flag runs no remove hook; only the last revision's removal does.
06 Components have the same four hooks for app developers for Ubuntu Core developers for snapd developers
Component hooks run as acme-agent+diagnostics with the SNAP_COMPONENT_* variables. Only install, pre-refresh, post-refresh and remove exist for components.
Acme-agent's diagnostics component can carry hooks of its own, but only four: install, pre-refresh, post-refresh and remove. Declare any other name for it in snap.yaml and the snap is refused. So what happens when a refresh takes diagnostics from revision 7 to 8? The component's pre-refresh runs first, then the snap's own. After the switch, the snap's post-refresh runs, then the component's, and component install hooks likewise follow the snap's. Each component hook sees $SNAP_COMPONENT_REVISION: 7 before, 8 after. A component's remove hook runs when you remove the component or the whole snap, and like the snap's, its failure is ignored.
07 What you see of a snap's lifecycle hooks for users for administrators
An error that names a hook comes from the snap, not from snapd. snap change <id> shows which hook failed and the end of its output.
Acme-agent's hooks are its own code, run by snapd in the middle of your command. So what does that look like from the shell? If the install hook fails, snap install says so, and the snap isn't installed. If a hook fails late in a refresh, say the health check, the snap goes back to the revision you had. Snap revert doesn't run the refresh hooks at all. Removal always completes: if the remove hook fails, the change just notes it. And when something goes wrong, snap change, with the change number, shows every hook that ran and the end of a failed hook's output.
08 Where to go from here
Roads: the mechanism, the two snapctl decks these hooks lean on, interface hooks, refresh, removal, services and the overlord.
Those are the fixed points where a snap's own code runs. The hooks deck shows what every hook shares: how it runs, its time limit, and what a failure does. Two snapctl decks cover what these hooks call: configuration, gadget defaults and health in one, starting and stopping services in the other. Interface hooks covers the connect hooks that run before install. The refresh deck and remove and revert cover the operations around these hooks, the snapshot included. And services and the overlord show what starts between default-configure and configure, and the chain of tasks itself.
Read more
Where the hooks sit
The tasks of one snap, in order. Hook tasks are in bold; each runs only if the snap ships the hook.
| Operation | Tasks |
|---|---|
| First install | download and mount, copy-snap-data, setup-profiles, link-snap, auto-connect (with the connect hooks of new connections), set-auto-aliases, setup-aliases, install, component install hooks, default-configure, start-snap-services, configure, check-health |
| Refresh | download and mount, component pre-refresh hooks, pre-refresh (old revision), stop-snap-services, remove-aliases, unlink-current-snap, copy-snap-data, setup-profiles, link-snap, auto-connect, aliases, post-refresh (new revision), component post-refresh and install hooks, start-snap-services, removal of old revisions, configure, check-health, check-rerefresh |
| Revert | the switch of revision, start-snap-services, configure, check-health; no pre-refresh, post-refresh or install |
| Update of components only | no pre-refresh or post-refresh of the snap |
| Remove | stop-snap-services, component remove hooks, remove, auto-disconnect (with the disconnect hooks), kill-snap-apps with --terminate, save-snapshot unless --purge, remove-aliases, unlink-snap, then the files |
| Remove a revision while others remain | no remove hook |
snap set, snap unset | configure alone, in a change of kind configure-snap |
A kernel with kernel-modules components and the essential snaps that need a reboot place some of these after the reboot; see Try, trying, done.
What a failure does
| Hook fails | Result |
|---|---|
| install, default-configure | the install is undone; the snap is not installed |
| pre-refresh | the refresh is undone before anything was unlinked |
| post-refresh, configure, check-health during a refresh | the refresh is undone back to the old revision |
configure during snap set | the values are not applied |
| remove, a component's remove | logged as ignoring failure in hook "remove"; the removal goes on |
When a refresh is undone, the configuration saved at link-snap is restored, so values the new revision's hooks set are dropped. Files the hooks wrote are not restored, and the old revision's pre-refresh hook is not called again.
for app developers for Ubuntu Core developers for snapd developers for administrators
Time limits
| Hook | Limit | Change it with |
|---|---|---|
| configure, default-configure | 5 minutes | SNAPD_CONFIGURE_HOOK_TIMEOUT in snapd's environment, a Go duration |
| check-health | 30 seconds | SNAPD_CHECK_HEALTH_HOOK_TIMEOUT in snapd's environment |
| the others | 10 minutes | cannot be changed |
for app developers for Ubuntu Core developers for snapd developers
Rules for snap.yaml
default-configureneeds aconfigurehook:cannot specify "default-configure" hook without "configure" hook.- Base and snapd snaps may not ship
configureordefault-configure; the OS snap may not shipdefault-configure. - A component may declare only
install,pre-refresh,post-refreshandremove; another name fails withunsupported component hook. A component hook may not have slots. gate-auto-refreshis accepted in a snap and is not run.snapctl refresh --holdand--proceedfail; see snapctl: services, refresh and changes.
Further reading
- Supported snap hooks: the published description of each lifecycle hook, with examples.
- Snap components: what a component is and how its hooks are declared.
- Use snapctl: the commands these hooks use for configuration, services and health.
- Manage updates: refresh and revert from the administrator's side.
Roads from here
RUNNING SNAPS
- Refresh — refresh and why no hook can hold it now
- Remove and revert — remove and revert and the snapshot taken on removal
- Services — the services that start between default-configure and configure
- The overlord — the task chain these hooks are placed in
SNAPCTL · the snap's API into snapd
- "snapctl: configuration and health" — the configure transaction and gadget defaults and health
- snapctl: services, refresh and changes — what snapctl start stop and restart do from these hooks
HOOKS · code snapd runs inside a snap
- Hooks: how they work — how every hook runs and fails
- Hooks: interface hooks — the connect hooks that run before the install hook
UBUNTU CORE · install and recovery
- A device set up before anyone logs in — the gadget defaults that default-configure and configure apply
ADMINISTRATION · managing a system of snaps
- Components — installing and removing the components whose hooks run here