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
01 Hooks at both ends of a connection
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 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
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
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-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-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: 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
| Operation | Hooks, in order | A hook failure |
|---|---|---|
snap connect | prepare-plug, prepare-slot, the connect task, connect-slot, connect-plug | fails snap connect; the earlier steps are undone |
| auto-connect at install | the same chain per new connection, after setup-profiles, before the install hook | fails the install |
| auto-connect at refresh | the same chain, only for connections that did not exist | fails the refresh |
snap disconnect | disconnect-slot, disconnect-plug, the disconnect task | logged and ignored |
snap disconnect --forget of an active connection | the same | logged and ignored |
snap remove | after the remove hook, one chain per connection of the snap | logged and ignored |
| a hotplug device is removed | disconnect-slot, disconnect-plug | fails the change |
| a connect chain fails | in reverse: disconnect-slot for a done connect-slot, disconnect-plug for a done connect-plug, the connection is removed, unprepare-slot, unprepare-plug | undo 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 hooks | connect, disconnect and unprepare hooks | |
|---|---|---|
snapctl get :<own-name> <attr> | the static attributes, then the dynamic ones | the values stored with the connection |
snapctl get --slot :<plug> <attr> or --plug :<slot> <attr> | the other side; prepare-slot already sees what prepare-plug set | the other side |
snapctl set :<own-name> <attr>=<value> | sets a dynamic attribute | refused |
The interface may rewrite dynamic attributes in the connect task; connect hooks see the rewritten values. See snapctl: configuration and health.
| Message | Cause |
|---|---|
attribute "<attr>" cannot be overwritten | setting 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 hooks | snapctl set :<name> in another hook |
"snapctl set <snap>:<name>" not supported, use "snapctl set :<name>" instead | naming a snap in the attribute call |
Further reading
- Interface hooks: the published description of the eight hooks and the attribute commands.
- Interface auto-connection: which connections snapd makes by itself, and so which hooks run at install.
- The content interface: the interface used by the examples.
- Use snapctl: the get and set commands with the plug and slot forms.
Roads from here
INTERFACES AND CONFINEMENT
- Interfaces — plugs slots and connections
- How interfaces are implemented — the connect task and the interface checks between the hooks
- The content interface — the content interface used by the real examples
RUNNING SNAPS
- The overlord — the task chains these hooks are part of
SNAPCTL · the snap's API into snapd
- "snapctl: configuration and health" — the attributes prepare hooks write and every interface hook reads
HOOKS · code snapd runs inside a snap
- Hooks: how they work — how hooks run and why one snap runs one hook at a time
- Hooks: install, configure, refresh, remove — the install hook that runs after auto-connect and the remove hook before auto-disconnect