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

▶ Watch this deck — 8 scenes, ~6 min

01 Four commands, fixed hook points

WHERE THE HOOKS RUN snap installinstall hook: first install onlymake current…install…default-configurestart servicesconfigurecheck-health snap refreshpre-refreshstop services…make current…post-refreshstart services…configurecheck-health snap revertno refresh hooks, no install hookmake current…start services…configurecheck-health snap removeremove hook: only when the last revision goesstop servicesremovedisconnect…save snapshot…make inactivefailure ignored gate-auto-refresh: not runorange: a hook task · every one optional
For acme-agent, four strips of steps for snap install, refresh, revert and remove with the hook tasks highlighted; remove failure is ignored; gate-auto-refresh is struck out because nothing runs it

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

FIRST INSTALL link-snapauto-connectset-auto-aliasessetup-aliasesconnect hooks of new connections run heresee Interface hooks run-hook installfirst install only · the agent is not running run-hook default-configure# snapctl services, inside default-configureacme-agent.agent disabled inactive - gadget defaults arrive here, or in configure if there is no default-configure start-snap-servicesrun-hook configure# snapctl services, inside configureacme-agent.agent enabled active - run-hook check-healththe last task of the install
A vertical task chain for the first install of acme-agent: link-snap, auto-connect with the connect hooks, aliases, the install hook, default-configure seeing the service disabled and inactive, start-snap-services, configure seeing it enabled and active, and check-health last

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

REFRESH mount-snappre-refreshstop-snap-servicesremove-aliasesunlink-current-snapcopy-snap-datasetup-profiles41 current41 unlinked, 42 not yet linked # pre-refresh, from revision 41SNAP_REVISION=41writes $SNAP_DATA/export.json copy-snap-data/var/snap/acme-agent/41 → 42 link-snapauto-connectsetup-aliasespost-refreshstart-snap-services…configurecheck-health42 current; post-refresh runs before its services start # post-refresh, in revision 42SNAP_REVISION=42reads export.json, converts itruns before 42's services startthe install hook does not run again revert, component-only update: no refresh hooksgate-auto-refreshauto-refresh no longer asks the snap
A refresh of acme-agent from 41 to 42: pre-refresh runs from 41 while it is current, before its services stop, and writes a file to its data; copy-snap-data copies 41's data to 42; after link-snap, post-refresh runs in 42 before its services start and converts the file; revert runs neither; gate-auto-refresh is struck out

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

ROLLBACK link-snappost-refreshstart-snap-servicesconfigurecheck-health✗timeout 30sa failure in any orange task reverts the refresh undo, task by task41 current again link-snap saved the configuration of 41restoredvalues set with snapctl setkeptfiles written and other outside effectsafter a failed first install: configuration deleted in check-healthsnapctl set-health error "server unreachable"exit 0refresh kept · health: errorthe message is an exampleexit 1refresh undone · 41 current again
The tail of a refresh, link-snap, post-refresh, start-snap-services, configure and a failing check-health, is undone back to 41; the configuration saved at link-snap is restored but files stay; setting health error and exiting 0 keeps the refresh, exiting 1 undoes it

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 stop-snap-servicescomponent remove hooksrun-hook removefailure logged and ignoredservices stopped, interfaces still connected $ snap remove acme-agentacme-agent removed$ snap change --last=removeignoring failure in hook "remove": … auto-disconnectkill-snap-apps (--terminate)disconnect hooks of each connection run here save-snapshotremove-aliasesunlink-snapautomatic snapshot of an app snap · not with --purge… $ snap remove --revision=41 acme-agent# other revisions remain: no remove hook
The remove chain: stop-snap-services, component remove hooks, the remove hook whose failure is ignored, auto-disconnect with the disconnect hooks, save-snapshot, remove-aliases, unlink-snap; acme-agent is removed although its remove hook fails; removing one revision while others remain runs no remove hook

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

COMPONENTS components: diagnostics: type: standard hooks: install: plugs: [network] pre-refresh: {} post-refresh: {} upgrade: {} # refused acme-agent's snap.yaml, an example mount-component pre-refresh +diagnostics pre-refresh (snap) the component's pre-refresh first … link-snap post-refresh (snap) post-refresh +diagnostics component post-refresh and install hooks after the snap's # inside the component's hooks pre-refresh: SNAP_COMPONENT_REVISION=7 post-refresh: SNAP_COMPONENT_REVISION=8 before the refresh after it snap remove acme-agent+diagnostics, or the snap the component's remove hook runs; its failure is ignored
acme-agent's snap.yaml with hooks for the diagnostics component, where an unknown hook name is refused; in a refresh the component's pre-refresh hook runs before the snap's and the component's post-refresh after the snap's; the component hooks see component revision 7 before the refresh and 8 after; a component's remove hook runs on removal of the component or the snap, and its failure is ignored

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

AT THE COMMAND LINE $ snap install acme-agenterror: cannot perform the following tasks:- Run install hook of "acme-agent" snap ifpresent (run hook "install": …)not installed $ snap refresh acme-agenterror: cannot perform the following tasks:- Run health check of "acme-agent" snap (…)still on the revision you had $ snap revert acme-agentacme-agent reverted to 2.3# 2.3: an example versionno refresh hooks ran $ snap remove acme-agentacme-agent removedremoved, though its remove hook failed $ snap change <id># every task of the change, hooks included, with status and the end of a failed hook's output
Four terminal exchanges: a failing install hook leaves the snap not installed; a failing health check keeps the old revision; snap revert runs no refresh hooks; snap remove completes although the remove hook failed; snap change shows the hook tasks

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 Hooks: install, configure, refresh, removeHookshow every hook runs and fails snapctl: configuration and healthconfigure, defaults, healthsnapctl: services, refresh…start, stop and restart Interface hooksconnect hooks before install Refreshthe operation around the hooksRemove and revertand the snapshot on removal Servicesstarted between the two hooksThe overlordthe task chain
Roads from the lifecycle hooks: Hooks, the two snapctl decks, interface hooks, refresh, remove and revert, services, and the overlord

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.

OperationTasks
First installdownload 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
Refreshdownload 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
Revertthe switch of revision, start-snap-services, configure, check-health; no pre-refresh, post-refresh or install
Update of components onlyno pre-refresh or post-refresh of the snap
Removestop-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 remainno remove hook
snap set, snap unsetconfigure 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 failsResult
install, default-configurethe install is undone; the snap is not installed
pre-refreshthe refresh is undone before anything was unlinked
post-refresh, configure, check-health during a refreshthe refresh is undone back to the old revision
configure during snap setthe values are not applied
remove, a component's removelogged 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

HookLimitChange it with
configure, default-configure5 minutesSNAPD_CONFIGURE_HOOK_TIMEOUT in snapd's environment, a Go duration
check-health30 secondsSNAPD_CHECK_HEALTH_HOOK_TIMEOUT in snapd's environment
the others10 minutescannot be changed

for app developers for Ubuntu Core developers for snapd developers

Rules for snap.yaml

  • default-configure needs a configure hook: cannot specify "default-configure" hook without "configure" hook.
  • Base and snapd snaps may not ship configure or default-configure; the OS snap may not ship default-configure.
  • A component may declare only install, pre-refresh, post-refresh and remove; another name fails with unsupported component hook. A component hook may not have slots.
  • gate-auto-refresh is accepted in a snap and is not run. snapctl refresh --hold and --proceed fail; 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

HOOKS · code snapd runs inside a snap

UBUNTU CORE · install and recovery

ADMINISTRATION · managing a system of snaps

  • Components — installing and removing the components whose hooks run here