Hooks and the security they run under
sandbox internals for snapd developers for Ubuntu Core developers
A hook runs confined under its own security tag and may do whatever the profile files hold at the moment its task runs. In an install the install hook runs after the full setup-profiles so it has every auto-connection. Prepare hooks run before it under a baseline written only for them; connect hooks run after it; disconnect and undo hooks run while the connection is still in the files. snapctl reads the state which can be ahead of the files.
On the map: sandbox internals district
01 Where a hook sits decides what it may do
A hook runs under its own security tag, snap.<snap>.hook.<name>. Connections reach the state and the repository at connect, the files at the injected setup-profiles. install, configure and the connect hooks run after it; prepare hooks run before it.
The agent's install hook wants to call home. Will it be allowed to? A hook feels like part of the snap, but it runs confined, under a profile of its own, and that profile holds whatever the files hold at the moment the hook's task runs. During the install, the two connections reach snapd's state and its repository at the connect tasks. They reach the files only at the one setup-profiles task after them. So the connect hooks, install and configure run with the network and the VPN socket. A prepare hook runs before that line, and it doesn't. Keep an eye on that one.
02 A baseline profile for prepare hooks for snapd developers for Ubuntu Core developers
In prepare mode, setup-profiles runs every backend for the snap alone, and only when it has a prepare-plug-* or prepare-slot-* hook. On first install that baseline has no connection. With preseeding, connect chains with hooks and the full setup-profiles wait for mark-preseeded.
That prepare hook runs before its connection exists, and before the task that writes the snap's real profiles. Yet it runs confined, so it needs some profile. So the first setup-profiles task, in prepare mode, asks: does this snap ship a prepare-plug or prepare-slot hook? If not, it writes nothing. The agent does ship one, so snapd writes a baseline for the agent alone, with a profile for every app and hook. On a first install it holds no connections, so the hook can't use the socket it's preparing, or even the network. And on a preseeded image, those connect chains wait for first boot.
03 Connected in the state, not yet in the profile for snapd developers
connect with delayed-setup-profiles writes conns and the repository, not the files. snapctl is-connected reads conns. Between a connect and the batch setup-profiles, a hook can be told a plug is connected while its profile lacks it.
Here's the answer. During install, auto-connect adds one chain per connection. The connect tasks in them don't touch the backends: they record the connection and move on. The chains aren't ordered against each other, so the network connection can be done while the agent's prepare hook for the VPN socket is still to run. That hook asks snapctl whether network is connected. snapctl reads the state, and the state says yes. But the hook runs under the baseline profile, which has no network. The files catch up at the one setup-profiles task after all the connects. The connect hooks run after that, so they see everything.
04 A manual connect changes everything in one task for snapd developers
Manual connect: repo.Connect, setupSnapSecurity for the slot snap then the plug snap, then conns, all in one task. Prepare hooks see none of it; connect hooks see all of it.
Now say you disconnected the socket, and you connect it again by hand. The chain is the one from the interface hooks deck, but this time nothing is delayed. The connect task does all the work itself, in this order: the repository, then the provider's files, then the agent's files, and last the state. So both prepare hooks run with nothing changed anywhere, and both connect hooks run with everything in place. Notice what that means for the provider's connect-slot hook. By the time it runs, the agent's apps already have the socket in their profiles, and a running app can use it before acme-vpn's hook has finished.
05 Proposed and committed attributes for snapd developers
snapctl get :<plug> reads plug-static, plug-dynamic and the slot equivalents from the task named by attrs-task. Prepare hooks set the proposal; doConnect commits it after BeforeConnectPlug and BeforeConnectSlot. The snaps are snapd's tests/main/interfaces-hooks.
Interface hooks don't read attributes from the state. Every hook in a chain reads them from the connect task its chain belongs to. snapd's own test snaps show it best. The consumer's prepare hook sets a dynamic attribute on its plug. That's only a proposal. The connect task hands it to the interface, which may rewrite it, and snapd's test interface does. The result goes into the state and back onto the task. So the connect hooks read the committed values, the same ones the state holds, and they can't change them. And on a refresh nobody asks again: existing connections keep the dynamic attributes they were made with.
06 "Refresh and snap set: old files before, new files after" for snapd developers for Ubuntu Core developers
pre-refresh: old revision, old files. post-refresh, configure and check-health: new revision, after the full setup-profiles. snap set runs only the configure hook and conflicts with a pending connect or disconnect of the snap.
The agent refreshes from 41 to 42. Its pre-refresh hook runs first, still as 41, under 41's files. Because the agent ships a prepare hook, the prepare task writes a baseline for 42 with the connections it already has. The full profiles for 42 come from the setup-profiles task after link-snap and auto-connect. post-refresh and configure run after that, as 42, with every connection. Only connections that are new in 42 get chains and hooks. And snap set runs the configure hook alone, with no interface task. While a connect or disconnect of the agent is in progress, snap set is refused.
07 On the way out, the connection is still there for snapd developers
Disconnect, remove and undo hooks run before the files lose the connection; disconnect and remove hook errors are ignored. In an auto-connect undo, only the prepare-mode setup-profiles touches the files.
On the way out, the order flips. Disconnect hooks run before the disconnect task, so they still have the connection, and one that fails doesn't stop the disconnect. Removing the agent runs its remove hook with everything connected, then one disconnect chain per connection, in no set order, and only then do the profiles go. And when an install fails after its connections were made, the undo hooks run in reverse while the files still contain the connection. By the time the unprepare hooks run, the connection has left the state and the repository. The files change only when the prepare task's undo removes the agent's profiles.
08 Where to go from here
Roads: interface hooks, how hooks work, setting up a snap's security, delayed security setup, images and preseeding, the content interface, specifications and snippets.
So a hook can do what its profile allows at the moment its task runs, and the line to watch is the one setup-profiles task after the connects. The hooks themselves are in the interface hooks deck, and how a hook becomes a confined process is in how hooks work. The two setup tasks are in setting up a snap's security, and why the connects leave the files to one of them is in delayed security setup. Preseeded images have their own deck. The socket in the examples is a content connection. And how a hook's profile is put together is in specifications and snippets.
Read more
The security a hook runs under
A hook runs as the security tag snap.<snap>.hook.<name>, with its own AppArmor profile, seccomp filter and other backend files. A hook without its own plugs: is bound to every plug and slot of the snap that no app or hook claims explicitly, so its profile gets the same connected snippets as the apps. A hook with plugs: [x] gets only x.
What a hook may do is what its files hold when its task runs. Three things can disagree for a while:
| Holder | Written by |
|---|---|
| the repository (in memory: plugs, slots, connections) | the prepare-mode setup-profiles (the snap), connect (the connection) |
the state (conns) | connect |
| the profile files | the full setup-profiles in auto-connect; the connect task itself in a manual snap connect |
snapctl is-connected reads conns. snapctl get :<plug> reads the connect or disconnect task named by the hook context key attrs-task, not conns.
Install
The task order is: copy-snap-data, setup-profiles (prepare mode), link-snap, auto-connect, then the tasks that auto-connect injects (per connection: prepare-plug-<plug> and prepare-slot-<slot> hooks and connect; one setup-profiles waiting for every connect; then per connection connect-slot-<slot> and connect-plug-<plug>), set-auto-aliases, setup-aliases, the install hook, default-configure, start-snap-services, configure, check-health.
| Hook | Repository | conns | Files of the snap | Attributes |
|---|---|---|---|---|
prepare-plug-<plug> | the snap present, the plug not connected | no entry | the baseline without the connection | proposed: static from snap.yaml, dynamic as set so far |
prepare-slot-<slot> (provider) | same | no entry | the provider's existing files | sees the plug side's proposal |
connect-slot-<slot>, connect-plug-<plug> | connected | entry | both snaps with the connection | committed |
install, default-configure, configure, check-health | connected | entry | with every auto-connection | not readable |
The prepare-mode setup-profiles writes files only when the snap has a prepare-plug-* or prepare-slot-* hook; then every backend runs for that snap alone. A snap without prepare hooks gets no files for the new revision between link-snap and the full setup-profiles (none on a first install, the previous revision's on a refresh), and none of its hooks runs in that window.
The install hook waits only for the snap's own auto-connect. A connection to a provider installed later, in another change or later in the seed, is made by the provider's auto-connect; the plug snap's connect-plug-<plug> hook then runs after its own install and configure hooks.
With preseeding, a snap with any interface hook on an auto-connected plug or slot has its connect chains and the full setup-profiles wait for mark-preseeded, so its full profile files are written at first boot. Without interface hooks they run during preseeding.
Refresh
pre-refresh runs first, as the old revision under the old files. Then stop-snap-services, remove-aliases, unlink-current-snap, copy-snap-data, the prepare-mode setup-profiles, link-snap and auto-connect. Only connections not yet in conns get connect tasks and hooks. post-refresh, configure and check-health run as the new revision after the full setup-profiles, with every connection.
| Hook | Revision | Files |
|---|---|---|
pre-refresh | old | old revision, all connections |
| prepare hooks of a new connection | new | baseline for the new revision with the existing connections (only if the snap has a prepare hook) |
| connect hooks of a new connection | new | new revision, all connections |
post-refresh, configure, check-health | new | new revision, all connections |
Existing connections run no hooks. Their dynamic attributes stay as set when the connection was made; their static attributes are replaced from the new snap.yaml when the policy still allows the connection.
snap set
snap set and snap unset create one run-hook task for configure, with no interface task. The change conflicts with a pending install, refresh, connect or disconnect of the same snap, so the configure hook does not see a half-made connection. Interface attributes cannot be read from a configure hook.
Manual snap connect and snap disconnect
snap connect runs prepare-plug-<plug>, prepare-slot-<slot>, connect, connect-slot-<slot>, connect-plug-<plug>; each hook task exists only if the snap ships the hook. The connect task updates the repository, sets up the slot snap, then the plug snap, then writes conns. Prepare hooks see none of it. Connect hooks see all of it, and while connect-slot-<slot> runs, the plug snap's apps can already use the slot.
snap disconnect runs disconnect-slot-<slot> (if the slot snap is active and ships it), disconnect-plug-<plug> likewise, then disconnect. Both hooks still have the connection everywhere. Their errors are logged as ignoring failure in hook "<hook>" and the disconnect goes on.
Remove
stop-snap-services, the remove hook (only when every revision is removed), auto-disconnect, remove-aliases, unlink-snap, remove-profiles. The remove hook runs with every connection. auto-disconnect adds one disconnect chain per connection, unordered among themselves; each disconnect regenerates both snaps' files at once. A disconnect hook of the removed snap may find another of its connections already gone. Remove and disconnect hook errors are ignored.
Attributes
| Command | prepare hooks | connect, disconnect and undo hooks |
|---|---|---|
snapctl get :<own> <attr> | static, then the dynamic proposal | the committed values, equal to conns |
snapctl get --slot :<plug> <attr> or --plug :<slot> <attr> | the other side; prepare-slot sees what prepare-plug set | the other side, committed |
snapctl set :<own> <attr>=<value> | sets a dynamic attribute of its own side | interface attributes can only be set during the execution of prepare hooks |
Setting a key that exists as a static attribute fails with attribute "<attr>" cannot be overwritten. snapd's test snaps basic-iface-hooks-consumer and basic-iface-hooks-producer (tests/main/interfaces-hooks) use the test interface empty, which rewrites before-connect to plug-changed(<value>) and slot-changed(<value>).
for snapd developers
Undo, for snapd developers
- A failed hook task is not undone, so its own undo hook does not run.
- Undo hooks:
unprepare-*for prepare hooks,disconnect-*for connect hooks,connect-*for disconnect hooks. In the connect chain they haveIgnoreError: true. - Manual connect:
undoConnectregenerates both snaps' files without the connection. - Auto-connect:
undoConnectskips the backends whendelayed-setup-profilesis set; the batchsetup-profilesundo is skipped byshouldUndoSetupProfileswhen the change has a prepare-modesetup-profilesfor the snap. Only the prepare-mode task's undo touches the files:removeProfilesForSnapon first install,setupProfilesForAppSetfor the old revision on refresh, after the savedconnsentries are restored. - Order when the install hook fails after one auto-connection with all four hooks:
disconnect-plug-<plug>,disconnect-slot-<slot>, batchsetup-profiles(skipped),connect(repository andconnsonly),unprepare-slot-<slot>,unprepare-plug-<plug>,auto-connect(nothing),link-snap, prepare-modesetup-profiles. undoAutoConnectstill carries the comment "TODO Introduce disconnection hooks, and run them here as well"; the hooks already run as the undo hooks of the injected tasks.- Hooks of one snap do not overlap (
snapIsRunningHook), but chains of different connections in one batch are unordered:connectof one plug may finish while another plug's prepare hook is still to run.
Other operations
snap enable runs prepare-snap, the full setup-profiles, link-snap and start-snap-services; snap disable runs stop-snap-services, remove-aliases, unlink-snap and remove-profiles. No hook runs in either.
Not covered
acme-agent, acme-vpn and their hooks are examples, as in Hooks: interface hooks; prepare-plug-vpn-socket was added for this deck. Hotplug connections inject plain connect chains and by reading behave like a manual connect; they were not traced. What snap run does when no profile exists yet for a hook's security tag was not determined. The research found suspected snapd bugs in the undo of auto-connections and in refreshes that drop a plug or slot; they are tracked in the project's bug list, not shown here.
Further reading
- Supported snap hooks: the lifecycle hooks and when they run.
- Interface hooks: the published description of the connect and disconnect hooks.
- Interface auto-connection: which connections snapd makes at install, and so which hooks run before the install hook.
- Use snapctl:
is-connectedand the attribute forms ofgetandset. - Security policies: where profiles live and when snapd generates them.
Roads from here
INTERFACES AND CONFINEMENT
- The content interface — the content interface of the examples
HOOKS · code snapd runs inside a snap
- Hooks: interface hooks — the eight interface hooks and their chains
- Hooks: how they work — how a hook becomes a confined process
SANDBOX INTERNALS · the mount namespace
- Setting up a snap's security — the two setup-profiles tasks in detail
- Delayed security setup — why connect tasks leave the profiles to one later task
- Specifications and snippets — how a hook's own profile is assembled
INSIDE SNAPD · the daemon itself
- Preparing images and preseeding — connect hooks that wait for first boot