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

▶ Watch this deck — 8 scenes, ~6 min

01 Where a hook sits decides what it may do

INSTALL ACME-AGENT link-snapauto-connectconnectconnectsetup-profiles each hook: its own profile, snap.acme-agent.hook.<name> state (conns)network, vpn-socketrepositorynetwork, vpn-socket profile filesbaseline, no connectionsboth connections connect-slot-socketacme-vpnconnect-plug-vpn-socketinstallconfigurewith network and vpn-socket prepare-plug-vpn-socketwithout network or vpn-socketwhat does snapctl is-connected network say here?
The install of acme-agent as a row of tasks: link-snap, auto-connect, two connect tasks, setup-profiles, then hooks. Each hook runs under its own profile, snap.acme-agent.hook.name. Under the row three tracks: the state and the repository get network and vpn-socket at the connect tasks; the profile files get them only at setup-profiles. The connect hooks, install and configure run after that line with network and vpn-socket; prepare-plug-vpn-socket runs before it, without them. What does snapctl is-connected network say there?

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

PREPARE-PROFILES: TRUE setup-profilesprepare mode, before link-snap prepare-plug-* orprepare-slot-* hook?hasPrepareConnectionHook(snapInfo) nono files until the full setup-profilesyessetupSecurityByBackendacme-agent alone, every backend, every app and hooksnap.acme-agent.agentsnap.acme-agent.hook.installsnap.acme-agent.hook.prepare-plug-vpn-socket… connections: none yet (first install) prepare-plug-vpn-socketcan run confinedcannot use vpn-socket or network preseeding: with interface hooks, the connect chains and the full setup-profileswait for mark-preseeded and run at first boot; the baseline is written in the image
The prepare-mode setup-profiles task asks whether the snap has a prepare-plug or prepare-slot hook. No: no files until the full setup-profiles. Yes, as for acme-agent: every backend runs for acme-agent alone and writes a profile for every app and hook, including the prepare hook, with no connections on first install. The prepare hook can run confined but cannot use vpn-socket or network. With preseeding and interface hooks, the connect chains and the full setup-profiles wait for first boot

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

THE AUTO-CONNECT BATCH auto-connectconnect · networkprepare-plug-vpn-socketprepare-slot-socketconnect · vpn-socketsetup-profilesconnect-slot-socketconnect-plug-vpn-socket delayed-setup-profiles: truedelayed-setup-profiles: true done: conns has network, files unchanged $ snapctl is-connected networkexit status 0: connected profile: the baseline, no networksnapctl reads conns; the files have not caught up both connections now in the filesrun with both
auto-connect adds two unordered chains: connect network, and prepare-plug-vpn-socket, prepare-slot-socket, connect vpn-socket. Each connect task has delayed-setup-profiles: true. Both lead to one setup-profiles task, then the connect hooks. The network connect is done first: conns has network, the files are unchanged. The prepare hook then runs snapctl is-connected network and gets exit status 0, while its profile is the baseline without network. At setup-profiles both connections reach the files, and the connect hooks run with both

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

SNAP CONNECT $ snap connect acme-agent:vpn-socket acme-vpn:socketprepare-plug-vpn-socketprepare-slot-socketconnectconnect-slot-socketconnect-plug-vpn-socket 1 · repository2 · acme-vpn files3 · acme-agent files4 · conns repositoryacme-vpn filesacme-agent filesconnsrepositoryacme-vpn filesacme-agent filesconnsnot connected anywhere repositoryacme-vpn filesacme-agent filesconnsrepositoryacme-vpn filesacme-agent filesconns while acme-vpn's connect-slot hook runs,the agent's apps can already use the socket
snap connect acme-agent:vpn-socket acme-vpn:socket runs five tasks: prepare-plug-vpn-socket, prepare-slot-socket, connect, connect-slot-socket, connect-plug-vpn-socket. Under each, four cells: repository, acme-vpn files, acme-agent files, conns. Under the prepare hooks all are unchanged. The connect task fills them in order: repository, acme-vpn files, acme-agent files, conns. Under the connect hooks all are filled, so the agent's apps can already use the socket while acme-vpn's connect-slot hook runs

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

ATTRS-TASK every hook in the chain has attrs-task = this taskconnect taskplug-staticplug-dynamicslot-staticslot-dynamic prepare-plug-consumer$ snapctl set :consumerbefore-connect=consumer-valueconsumer-valueproposed plug-changed(consumer-value)slot-changed(producer-value)BeforeConnectPlug · BeforeConnectSlot connscommitted: same values connect-plug-consumer$ snapctl get --slot :consumerbefore-connectslot-changed(producer-value) $ snapctl set :consumer …interface attributes can only be setduring the execution of prepare hooksrefresh: no hooks for existing connections,dynamic attributes are not recomputed
The connect task holds plug-static, plug-dynamic, slot-static and slot-dynamic, and every hook in the chain reads it as attrs-task. The prepare-plug-consumer hook runs snapctl set :consumer before-connect=consumer-value, a proposal in plug-dynamic. The interface's BeforeConnectPlug and BeforeConnectSlot rewrite it to plug-changed(consumer-value) and slot-changed(producer-value), which go to conns and back onto the task. The connect-plug-consumer hook reads slot-changed(producer-value) with snapctl get --slot :consumer before-connect; setting attributes there fails. On refresh dynamic attributes are not recomputed

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

SNAP REFRESH ACME-AGENT pre-refreshunlink-current-snapcopy-snap-datasetup-profilesprepare modelink-snapauto-connectsetup-profilesfullpost-refreshstart-snap-servicesconfigurefiles: revision 41, all connections pre-refresh: revision 41, old files baseline for 42the agent has a prepare hook baseline for 42files: revision 42, kept and new connectionspost-refresh, configure: revision 42, new files, every connection auto-connect: only connections not yet in conns get a chain and hooks $ snap set acme-agent …configurealone, no interface taskrefused while a connect or disconnect of acme-agent is in progress
snap refresh acme-agent from 41 to 42: pre-refresh, unlink-current-snap, copy-snap-data, setup-profiles in prepare mode, link-snap, then auto-connect, the full setup-profiles, post-refresh, start-snap-services, configure. pre-refresh runs as 41 under 41's files. Because the agent has a prepare hook, the prepare task writes a baseline for 42. The full setup-profiles writes 42's files with kept and new connections; post-refresh and configure run after it. Only new connections get chains and hooks. snap set runs only the configure hook and is refused while a connect or disconnect of the agent is in progress

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 · UNDO $ snap disconnect acme-agent:vpn-socketdisconnect-slot-socketdisconnect-plug-vpn-socketdisconnect files contain vpn-sockethook errors are ignored:ignoring failure in hook … $ snap remove acme-agentremoveauto-disconnectone chain per connection, unorderedremove-profileseach connection until its own disconnect install fails (example: the install hook exits 1), undone in this order:disconnect-plug-vpn-socketdisconnect-slot-socketsetup-profilesundo skippedconnectstate, repository only unprepare-slot-socketunprepare-plug-vpn-socketgone from state and repository, still in the files setup-profiles (prepare)undo removes the agent's filesfiles contain vpn-socket until hereon the way out, the files change last
Three ways out. snap disconnect acme-agent:vpn-socket: disconnect-slot-socket and disconnect-plug-vpn-socket run before the disconnect task, while the files contain vpn-socket; hook errors are ignored. snap remove acme-agent: the remove hook, auto-disconnect with one unordered chain per connection, then remove-profiles. A failed install is undone in this order: disconnect-plug-vpn-socket, disconnect-slot-socket, setup-profiles with its undo skipped, connect which touches only the state and repository, unprepare-slot-socket and unprepare-plug-vpn-socket, then the prepare-mode setup-profiles whose undo removes the agent's files. The files change last

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

WHERE NEXT connect · connect · setup-profiles · hooksHooks and the securitythey run under Hooks: interface hooksthe hooks and their chainsHooks: how they worka hook as a confined process Setting up a snap's securitythe two setup-profiles tasksDelayed security setupwhy connects leave the files Preparing images and preseedingconnect hooks at first bootThe content interfacethe socket of the examples Specifications and snippetshow a hook's profile is built
Roads from Hooks and the security they run under: Hooks: interface hooks, Hooks: how they work, Setting up a snap's security, Delayed security setup, Preparing images and preseeding, The content interface, and Specifications and snippets

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:

HolderWritten by
the repository (in memory: plugs, slots, connections)the prepare-mode setup-profiles (the snap), connect (the connection)
the state (conns)connect
the profile filesthe 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.

HookRepositoryconnsFiles of the snapAttributes
prepare-plug-<plug>the snap present, the plug not connectedno entrythe baseline without the connectionproposed: static from snap.yaml, dynamic as set so far
prepare-slot-<slot> (provider)sameno entrythe provider's existing filessees the plug side's proposal
connect-slot-<slot>, connect-plug-<plug>connectedentryboth snaps with the connectioncommitted
install, default-configure, configure, check-healthconnectedentrywith every auto-connectionnot 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.

HookRevisionFiles
pre-refresholdold revision, all connections
prepare hooks of a new connectionnewbaseline for the new revision with the existing connections (only if the snap has a prepare hook)
connect hooks of a new connectionnewnew revision, all connections
post-refresh, configure, check-healthnewnew 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

Commandprepare hooksconnect, disconnect and undo hooks
snapctl get :<own> <attr>static, then the dynamic proposalthe committed values, equal to conns
snapctl get --slot :<plug> <attr> or --plug :<slot> <attr>the other side; prepare-slot sees what prepare-plug setthe other side, committed
snapctl set :<own> <attr>=<value>sets a dynamic attribute of its own sideinterface 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 have IgnoreError: true.
  • Manual connect: undoConnect regenerates both snaps' files without the connection.
  • Auto-connect: undoConnect skips the backends when delayed-setup-profiles is set; the batch setup-profiles undo is skipped by shouldUndoSetupProfiles when the change has a prepare-mode setup-profiles for the snap. Only the prepare-mode task's undo touches the files: removeProfilesForSnap on first install, setupProfilesForAppSet for the old revision on refresh, after the saved conns entries are restored.
  • Order when the install hook fails after one auto-connection with all four hooks: disconnect-plug-<plug>, disconnect-slot-<slot>, batch setup-profiles (skipped), connect (repository and conns only), unprepare-slot-<slot>, unprepare-plug-<plug>, auto-connect (nothing), link-snap, prepare-mode setup-profiles.
  • undoAutoConnect still 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: connect of 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

Roads from here

INTERFACES AND CONFINEMENT

HOOKS · code snapd runs inside a snap

SANDBOX INTERNALS · the mount namespace

INSIDE SNAPD · the daemon itself