Hooks: interface hooks

hook group for app developers for snapd developers

Eight hook name patterns that run around one connection of a plug to a slot. The name ends with the snap's own plug or slot name. Connecting runs prepare-plug prepare-slot connect-slot and connect-plug around the connect task and can fail the change; disconnecting runs disconnect-slot and disconnect-plug and cannot be stopped by them; unprepare runs only to undo a failed connect.

On the map: hooks district

▶ Watch this deck — 7 scenes, ~5 min

01 Hooks at both ends of a connection

ONE CONNECTION, TWO SIDES acme-agentvpn-socketcontentsocketacme-vpnin the plug snapin the slot snap prepare-plug-vpn-socketprepare before the connectionprepare-slot-socket connect-plug-vpn-socketconnect after it is madeconnect-slot-socket disconnect-plug-vpn-socketdisconnect before it is removeddisconnect-slot-socket unprepare-plug-vpn-socketunprepare only to undo a failed connectunprepare-slot-socket the suffix is the snap's own plug or slot namenot the interface (content), not the other snap
The plug snap acme-agent with plug vpn-socket and the slot snap acme-vpn with slot socket, joined by a connection; under each, four hooks named after its own plug or slot: prepare, connect, disconnect and unprepare, with the phase each runs in

connect-plug-vpn-socket runs in acme-agent and connect-slot-socket in acme-vpn, for the connection acme-agent:vpn-socket to acme-vpn:socket. acme-vpn and its slot are examples.

Acme-agent talks to the gateway's VPN through a socket that acme-vpn shares. The agent's plug is called vpn-socket, and acme-vpn's slot is called socket. When the two are connected, both snaps may want a say. So each side can ship interface hooks of its own, named after its own end. There are four moments. Prepare runs before the connection exists. Connect runs once it's made. Disconnect runs before it's removed. And unprepare runs only to undo a connect that failed. Four moments on two sides make eight name patterns. The name ends with the snap's own plug or slot name: not the interface, and not the other snap.

02 Two plugs, two hooks, run one connection at a time for app developers for snapd developers

ONE HOOK PER PLUG plugs:vpn-socket:interface: contentdefault-provider: acme-vpnvpn-logs:interface: contentmeta/hooks/connect-plug-vpn-socketconnect-plug-vpn-logs hook name = "connect-plug-" + plug name $ snap install acme-agentacme-vpn offers the socket onlyconnect-plug-vpn-socketran connect-plug-vpn-logsnot runvpn-logs: not connected, nothing to run $ snap refresh acme-vpnits new revision adds slot logs: vpn-logs auto-connectsconnect-plug-vpn-logsraninside acme-vpn's refresh change connect-plug-vpn-socket at install · connect-plug-vpn-logs at the refresh
acme-agent's snap.yaml with content plugs vpn-socket and vpn-logs and one connect-plug hook file for each; at install acme-vpn offers only the socket, so only vpn-socket connects and only its hook runs; after acme-vpn's refresh adds slot logs, vpn-logs auto-connects and its hook runs inside that refresh change

One hook file per plug or slot: connect-plug-vpn-socket and connect-plug-vpn-logs. A connection runs only the hooks whose suffix is its own plug and slot. snapd's test layout-content-refresh-connect-hooks does the same with two content plugs.

Acme-agent has a second content plug, vpn-logs, and ships one connect-plug hook for each plug. Snapd builds the hook name from the plug being connected: connect-plug, then the plug name. When the agent is installed, acme-vpn offers only the socket, so only vpn-socket connects, and only its hook runs. Vpn-logs stays unconnected, and its hook doesn't run. Later, acme-vpn is refreshed, and its new revision offers logs too. Now vpn-logs auto-connects, and connect-plug-vpn-logs runs, inside acme-vpn's refresh change, not the agent's. A hook belongs to its plug, not to whichever change made the connection.

03 The connect chain: plug prepares first, slot is told first for app developers for snapd developers

THE CONNECT CHAIN $ snap connect acme-agent:vpn-socket acme-vpn:socketRun hook prepare-plug-vpn-socket of snap "acme-agent"plug snapRun hook prepare-slot-socket of snap "acme-vpn"slot snap Connect acme-agent:vpn-socket to acme-vpn:socketattributes: prepare hooks write, the connect task checks, connect hooks readsnapctl: configuration Run hook connect-slot-socket of snap "acme-vpn"slot snapRun hook connect-plug-vpn-socket of snap "acme-agent"plug snap no hook file → no taskthe chain only holds hooks the snap ships undo: unprepare-plug-vpn-socketundo: unprepare-slot-socketundo: remove the connectionundo: disconnect-slot-socketundo: disconnect-plug-vpn-socket exit ≠ 0 → snap connect failsearlier steps are undone with the hooks on the right
The connect-snap chain for acme-agent:vpn-socket to acme-vpn:socket: prepare-plug-vpn-socket, prepare-slot-socket, the connect task, connect-slot-socket, connect-plug-vpn-socket, each with the hook that undoes it; a missing hook file means no task, and a failing hook fails snap connect

Order: prepare-plug-, prepare-slot-, connect, connect-slot-, connect-plug-. All interface hooks use the default 10-minute limit.

Run snap connect for the agent's socket, and snapd builds one chain of tasks, run strictly in order. The plug side prepares first, then the slot side, which can already read what the plug side published. Then the connect task records the connection and checks the attributes the prepare hooks set. Then the slot side is told, and the plug side last. Each hook task exists only if the snap ships that hook. Every step also stores the hook that undoes it: unprepare for a prepare, disconnect for a connect. If any step fails, snap connect fails, and the earlier steps are undone with those hooks.

04 Auto-connect runs the same chain, before the install hook for app developers for snapd developers

AUTO-CONNECT link-snapsnap install acme-agentauto-connect injected: one chain per new connectionconnect vpn-socket setup-profilessecurity profilesconnect-slot-socketacme-vpnconnect-plug-vpn-socketacme-agent set-auto-aliases · setup-aliasesrun-hook installif any: plugs already connected beside it: chains of other new connectionsnot ordered among themselvesone hook of the same snap at a time snap refreshauto-connectexisting connection: kept, no hooksnew plug or slot: chain injectedlike vpn-logs earlier
Install change of acme-agent: link-snap, auto-connect, then an injected chain connect, setup-profiles, connect-slot-socket and connect-plug-vpn-socket, then the aliases and the install hook; other chains run beside it one hook per snap at a time; on refresh only new connections get a chain

On first install, connect hooks run before install. On refresh, connect hooks run only for connections that did not exist before.

Auto-connect runs the same connect code, so the same hooks run in the same order. When acme-agent is installed, link-snap makes it current, and the auto-connect task adds one chain for each new connection, vpn-socket among them. Its connect hooks wait until the security profiles are set up. All of this finishes before the agent's install hook, so the install hook can rely on its plugs being connected. Chains of different plugs have no order among themselves, but one snap still runs one hook at a time. On a refresh, only new connections get a chain. Existing ones keep their state and run no hooks.

05 Disconnect hooks cannot stop a disconnect for app developers for snapd developers

DISCONNECT $ snap disconnect acme-agent:vpn-socketRun hook disconnect-slot-socket of snap "acme-vpn"Run hook disconnect-plug-vpn-socket of snap "acme-agent"disconnectthe connection is removed only here # disconnect-plug-vpn-socket exits 1$ snap change --last=disconnect… ignoring failure in hook "disconnect-plug-vpn-socket" … $ snap connections acme-agent# vpn-socket: no longer connected $ snap remove acme-agentremove hook, if the snap has oneauto-disconnectdisconnect-slot-socketacme-vpndisconnect-plug-vpn-socketdisconnect-plug-vpn-logsone chain per connectionfailures ignored here tooInstall and refresh hooks
snap disconnect of acme-agent:vpn-socket runs disconnect-slot-socket in acme-vpn, then disconnect-plug-vpn-socket in acme-agent, then the disconnect task; when the plug hook fails the change logs ignoring failure in hook and the connection is gone; snap remove acme-agent runs the disconnect hooks of each connection after the remove hook, the slot hook inside acme-vpn

disconnect-slot- then disconnect-plug-, then the connection is removed. A disconnect hook reports a failure only in the change log. A disabled snap's disconnect hooks are skipped. Only a disconnect caused by hotplug removal fails on a hook error.

Suppose acme-agent's disconnect-plug-vpn-socket hook fails. Can it keep the connection? Start with the order. Disconnecting runs the slot side first, then the plug side, and removes the connection only after both, so each hook still sees the stored attributes. And the failure? For snap disconnect, disconnect --forget, and snap remove, it's only logged as ignoring failure in hook, and the connection goes anyway. And when you remove acme-agent, its own disconnect-plug hooks run after its remove hook, while acme-vpn's disconnect-slot hook runs inside the agent's removal.

06 unprepare runs only to undo a failed connect for app developers for snapd developers

UNPREPARE IS AN UNDO $ snap connect acme-agent:vpn-socket acme-vpn:socketprepare-plug-vpn-socketdoneprepare-slot-socketdoneconnectdoneconnect-slot-socketdoneconnect-plug-vpn-socket✗ exit 1 ① disconnect-slot-socketerrors ignored② connection removed ③ unprepare-slot-socketerrors ignored④ unprepare-plug-vpn-socketerrors ignored disconnect-plug-vpn-socketnot runa failed task is not undone: the hook cleans up itself $ snap connect acme-agent:vpn-socket acme-vpn:socketerror: cannot perform the following tasks:- Run hook connect-plug-vpn-socket of snap "acme-agent" (run hook "connect-plug-vpn-socket": …)# snap change shows the three undo hooks as Undone, the failed task as Error snap disconnect and snap remove do not run unprepare hooks
The connect chain of acme-agent:vpn-socket to acme-vpn:socket with connect-plug-vpn-socket failing; the undo runs in reverse: disconnect-slot-socket, the connection removed, unprepare-slot-socket, unprepare-plug-vpn-socket, errors ignored; disconnect-plug-vpn-socket is not run; snap connect reports the failed hook

unprepare-plug-<plug> pairs with a failed connect, not with disconnect. A connect hook that fails must undo its own partial work before exiting. snapd's test interfaces-hooks checks this order with a hook that fails on request.

Now suppose acme-agent's connect-plug-vpn-socket hook exits with an error. Snapd undoes the chain in reverse. Acme-vpn's connect-slot-socket is undone with its disconnect-slot-socket hook, and the connection is removed. Then unprepare-slot-socket and unprepare-plug-vpn-socket run, and their errors are ignored. The agent's own disconnect-plug-vpn-socket doesn't run, because snapd doesn't undo the task that failed. So a connect hook that fails has to clean up after itself. And unprepare isn't part of disconnect or remove: it runs only here, and it has to cope with whichever step failed.

07 Where to go from here

ROADS Hooks: interface hooksHooksone hook per snap at a time snapctl: configurationattributes in the hooks Interfacesplugs, slots, connectionsHow interfaces workthe connect task, checks The content interfaceused by the examplesInstall and refresh hooksinstall, remove, auto-connectThe overlordchanges and tasks
Roads from interface hooks: hooks, snapctl configuration, interfaces, how interfaces work, the content interface, install and refresh hooks, and the overlord

Roads: the mechanism, attributes, interfaces and their implementation, content, lifecycle hooks and the overlord.

Those are the hooks at both ends of a connection. The hooks deck covers the mechanism, and why one snap runs one hook at a time. The snapctl configuration deck shows the attributes that prepare hooks write and every interface hook reads. The interfaces deck covers plugs, slots and connections, and the implementation deck covers the connect task and the checks between the hooks. The content interface deck explains the interface of the examples. The lifecycle hooks deck shows the install hook after auto-connect, and the remove hook before auto-disconnect. And the overlord deck covers changes and tasks.

Read more

Which operations run which hooks

OperationHooks, in orderA hook failure
snap connectprepare-plug, prepare-slot, the connect task, connect-slot, connect-plugfails snap connect; the earlier steps are undone
auto-connect at installthe same chain per new connection, after setup-profiles, before the install hookfails the install
auto-connect at refreshthe same chain, only for connections that did not existfails the refresh
snap disconnectdisconnect-slot, disconnect-plug, the disconnect tasklogged and ignored
snap disconnect --forget of an active connectionthe samelogged and ignored
snap removeafter the remove hook, one chain per connection of the snaplogged and ignored
a hotplug device is removeddisconnect-slot, disconnect-plugfails the change
a connect chain failsin reverse: disconnect-slot for a done connect-slot, disconnect-plug for a done connect-plug, the connection is removed, unprepare-slot, unprepare-plugundo hooks: logged and ignored

The task that failed is not undone, so its own undo hook does not run. A disabled snap's disconnect hooks are skipped, and forgetting an inactive connection runs no hooks.

In snap change, these tasks read Run hook <name> of snap "<snap>"; the connection itself reads Connect <snap>:<plug> to <snap>:<slot> or Disconnect <snap>:<plug> from <snap>:<slot>.

Attributes from inside a hook

prepare hooksconnect, disconnect and unprepare hooks
snapctl get :<own-name> <attr>the static attributes, then the dynamic onesthe values stored with the connection
snapctl get --slot :<plug> <attr> or --plug :<slot> <attr>the other side; prepare-slot already sees what prepare-plug setthe other side
snapctl set :<own-name> <attr>=<value>sets a dynamic attributerefused

The interface may rewrite dynamic attributes in the connect task; connect hooks see the rewritten values. See snapctl: configuration and health.

MessageCause
attribute "<attr>" cannot be overwrittensetting an attribute that snap.yaml already sets
unknown plug or slot "<name>"a name that is not this hook's plug or slot
interface attributes can only be set during the execution of prepare hookssnapctl set :<name> in another hook
"snapctl set <snap>:<name>" not supported, use "snapctl set :<name>" insteadnaming a snap in the attribute call

Further reading

Roads from here

INTERFACES AND CONFINEMENT

RUNNING SNAPS

SNAPCTL · the snap's API into snapd

HOOKS · code snapd runs inside a snap