Setting up a snap's security
sandbox internals for snapd developers
The interface manager's tasks keep three records in step, the conns state, the in-memory repository and the files on disk. An install or refresh has two setup-profiles tasks, a prepare-mode one before link-snap that refreshes the repository and normally writes no files, and a full one injected by auto-connect after the connect tasks that regenerates the snap and every snap connected to it, backend by backend. A manual connect or disconnect sets up both snaps inside its own task, and only the prepare-mode task undoes.
On the map: sandbox internals district
▶ Watch this deck — 8 scenes, ~6 min
Part of journeys
- From interfaces to AppArmor and back, step 1 of 13 · next: Specifications and snippets
01 Two setup-profiles in one refresh
Two tasks of kind setup-profiles: "Prepare snap … for security profile setup" before link-snap, and "Setup snap … security profiles", injected by auto-connect after the connect tasks. Injected tasks are listed last, but hooks and services wait for them. A first install has the same pair, without the unlink.
You refresh the photo editor, then read the change. Security profiles come up twice. Why twice? The first task runs before revision 43 is made available, and it only prepares. It tells snapd's interface repository about the new revision, and normally it writes no files. The second task wasn't in the change at the start. The auto-connect task adds it, after any connections it makes, so the profiles are written once, with every connection in place. That's why it's listed last. The post-refresh hook and the services wait for it. Both share one kind, setup-profiles, so an older snapd could still run this change after a downgrade.
02 "Prepare mode: refresh the repository, write nothing" for snapd developers
Prepare mode: refreshAppSetConnections, Prepare on every backend, a baseline setupSecurityByBackend only with prepare-plug-*/prepare-slot-* hooks, then PendingSecurity. Dropped connections are saved as changed-or-dropped-connection-snapshot. In conns the system snap is still called core. photo-themes is invented.
The first task has one job: get the repository ready for revision 43. It reads the new snap.yaml, takes the photo editor out of the repository and puts revision 43 in. Then it reloads the editor's connections from snapd's state. Home and camera come back. Themes doesn't, because 43 dropped that plug, so that auto-connection is deleted from the state, and the old entry is saved for undo. Every backend may prepare, though only AppArmor acts, and only for core and snapd. Files are written now only for prepare-plug or prepare-slot hooks, which run before the second task. Last, 43 is recorded as pending.
03 "The full task: who else gets rewritten" for snapd developers
Affected snaps: the snap itself, then every snap from DisconnectSnap and from the reloaded connections, sorted by name, each with a SetupContext.Reason. Current behaviour: a refresh that drops a plug or slot does not regenerate the snap on the other end, because prepare mode discards disconnectedSnaps. photo-themes is invented.
The second task is where files get written, and not only the photo editor's. It refreshes the repository again and collects every snap the editor is connected to, or was a moment ago. The editor goes first, the rest in name order, each with a reason seen from its own side. snapd holds the home and camera slots, so it's redone because a snap plugged into it changed. Then all go through the backends, one backend at a time. Today, though, the first task dropped the themes connection and threw away the snaps it disconnected. So photo-themes isn't in this set, and keeps files for a connection that's gone.
04 snap connect sets up both snaps in one task for snapd developers
Manual connect: policy check, repo.Connect, setupSnapSecurity for the slot snap then the plug snap, then conns. disconnect: plug snap then slot snap; an auto-connection disconnected by hand stays in conns as undesired.
Compare the refresh with you connecting the camera by hand. There's no batch here. The connect task itself checks the connect policy, connects in the repository, and sets up both snaps right away: the slot snap first, then the plug snap. Only then does it write the connection into snapd's state. If setup fails after the repository connect, that connection is taken back out of the repository. Disconnect works the other way round, plug snap first. And if you disconnect an auto-connection like home, snapd keeps its entry, marked undesired, so the next refresh won't connect it again.
05 Three records that must agree for snapd developers
conns (state), interfaces.Repository (memory) and the backend files (disk) agree again only after the full setup-profiles. At startup the repository is rebuilt from conns; files are regenerated only on a system-key mismatch.
There are three records of the editor's connections, and they don't change at the same moment. The entry in snapd's state is what survives a restart. The repository is snapd's working copy in memory. The files are what the kernel and snap-confine actually use. During the refresh, the repository and the state move first, in the prepare task and in any connect task. The files catch up only in the full task. And when snapd starts, it rebuilds the repository from the state every time, but it rewrites the files only if the system key says they were made for a different system.
06 "Undo: the prepare task rewrites" for snapd developers
Only the prepare-profiles task undoes: restore the snapshot into conns, then setupProfilesForAppSet for the old revision (or removeProfilesForSnap). Current behaviour: the peer of an undone auto-connection keeps the connection in its files, and undo of remove-profiles uses the removal's snapsup.Flags, which are empty.
Now suppose the post-refresh hook fails. The change unwinds, right to left. The full setup task does nothing on undo. A connect task undoes only the repository and the state, not the files. Undoing link-snap makes 42 current again. Then the prepare task does the work: it puts back the entries it saved and regenerates 42's profiles with the snap's own flags. Two gaps today. A snap on the other end of an undone auto-connection keeps that connection in its files. And undoing remove-profiles reads the removal's setup data, which has no flags, so a classic snap comes back strict.
07 One interface task at a time for snapd developers
All ifacestate task kinds are in exclusiveTaskKinds: one runs at a time. auto-connect returns state.Retry on conflicting connect, disconnect, link-snap, unlink-snap, setup-profiles or discard-snap tasks of the other snap. The snap manager's own tasks are not exclusive, so another change can link a snap meanwhile; that change's own setup-profiles rewrites the files later. The snaps of changes B and C are examples.
While the backends run, the state lock is released. So what stops two changes from writing the same snap's files at once? First, a connect or disconnect that names a snap with a change in progress is refused when you ask for it. Second, every interface manager task kind is marked exclusive, and the task runner won't start one while another is running. The auto-connect task also looks for link, unlink, setup and discard tasks of the snap on the other end, and retries, logging that it's waiting.
08 Where to go from here
Roads: the security backends, hooks and their security, delayed security setup, the overlord, when snapd asks, the system key, snapd restart and re-exec, how interfaces are implemented.
Two setup tasks, three records, one interface task at a time. What each backend does when it's called is in the security backends. What a hook may do at each point of these changes is in hooks and the security they run under. Why the connect tasks leave setup to the full task is in delayed security setup. Changes, lanes and undo belong to the overlord, and the policy checks to when snapd asks. Regenerating at startup is the system key. For a snapd refresh, the two tasks run in different snapd processes; that's snapd restart and re-exec. And the repository itself is in how interfaces are implemented.
Read more
The tasks of an install or refresh
Read at snapd 880846b627. Since commit 630ab20c25 ("overlord: reduce the number of profile generation done", PR #16486) the profiles of a snap are no longer written before link-snap.
| Order | Task kind | Summary in snap change | Security work |
|---|---|---|---|
| refresh only | run-hook, stop-snap-services, remove-aliases, unlink-current-snap | Make current revision for snap "<name>" unavailable | PendingSecurity set to the current revision |
| 1 | copy-snap-data | Copy snap "<name>" data | none |
| 2 | setup-profiles, task data prepare-profiles: true | Prepare snap "<name>" (<rev>) for security profile setup | repository refreshed, Prepare on every backend, files only with prepare hooks |
| 3 | link-snap | Make snap "<name>" (<rev>) available to the system | none |
| 4 | auto-connect | Automatically connect eligible plugs and slots of snap "<name>" | adds the tasks below |
| 4a | connect, one per new connection, with delayed-setup-profiles: true | Connect <plug> to <slot> | repository and conns only |
| 4b | setup-profiles, injected | Setup snap "<name>" (<rev>) security profiles | files of the snap and every snap connected to it |
| 5 | set-auto-aliases, setup-aliases, run-hook (install or post-refresh), start-snap-services, … | wait for the injected tasks |
The injected tasks are added to the change last, so snap change lists them after the tasks that wait for them. auto-connect always injects the full setup-profiles, also when it makes no connection. The injected tasks join the lanes of auto-connect (snapstate InjectTasks), so with --transaction=all-snaps a failure in them undoes every snap of the transaction. A first install has the same pair of tasks without the refresh-only ones; its prepare task runs with no PendingSecurity written, because the snap is not installed yet.
Both tasks have the same kind so that an older snapd can still run the change after a downgrade.
for snapd developers
What each record holds
Refresh of a snap X from revision 1 to 2, X without prepare hooks.
| After task | Repository | conns | Files of X | PendingSecurity |
|---|---|---|---|---|
| before | revision 1 and its connections | as connected | revision 1 | none |
unlink-current-snap | unchanged | unchanged | revision 1 | revision 1 |
setup-profiles (prepare) | revision 2, connections reloaded from conns | auto-connections whose plug or slot is gone deleted; static attributes refreshed | revision 1 | revision 2 |
link-snap | unchanged | unchanged | revision 1 | none (snap active) |
connect (delayed) | plus the new connection | plus the new entry | revision 1 | none |
setup-profiles (full) | X removed, re-added, connections reloaded again | unchanged unless attributes changed | revision 2 with all connections; affected snaps rewritten | none |
With the CoreSnapdSystemMapper the implicit slots are on the snapd snap in memory and on core in conns.
At every snapd start InterfaceManager.StartUp adds the interfaces, the backends and the snaps to a new repository and calls reloadConnections(""). It regenerates every profile only when the system key does not match; see The system key.
for snapd developers
doSetupProfiles
1. Read snap-setup, prepare-profiles, new-connections; look for a process-delayed-security-backend-effects task in the change (delaying is possible only if it exists). 2. snap.ReadInfo for the new revision; buildConfinementOptions from snapsup.Flags; addImplicitInterfaces; appSetForTask. 3. Prepare mode: refreshAppSetConnections (DisconnectSnap, RemoveSnap, AddAppSet, reloadConnections, and on the do path snapshotChangedConnectionsForUndo into changed-or-dropped-connection-snapshot); backend.Prepare for every backend; setupSecurityByBackend for this snap alone if it has a prepare-plug-* or prepare-slot-* hook; setPendingProfilesSideInfo. 4. Full mode: setupProfilesForAppSet, setPendingProfilesSideInfo, and queue delayed effects on the delayed-effects task.
Prepare does something only in the apparmor backend, and there only for the core and snapd snaps.
The affected set in setupProfilesForAppSet is the snap itself, every snap from DisconnectSnap and both ends of every reloaded connection. The snap comes first, the others sorted by instance name. Each other snap gets its snapst.Flags, its PendingSecurity revision if set, and a SetupContext.Reason:
| Reason | The affected snap |
|---|---|
SnapSetupReasonOwnUpdate | is the snap being set up |
SnapSetupReasonConnectedSlotProviderUpdate | has a plug connected to this snap's slot |
SnapSetupReasonConnectedPlugConsumerUpdate | has a slot connected to this snap's plug |
SnapSetupReasonCyclicallyConnectedUpdate | both |
Effects may be delayed only for ConnectedSlotProviderUpdate, when the change has the delayed-effects task and the snap is not on a new connection. setupSecurityByBackend unlocks the state and runs each backend over all affected snaps before the next backend ("See LP: 1802581"); the first error of a backend stops the task.
for snapd developers
connect, disconnect and remove-profiles
| Handler | Order | conns |
|---|---|---|
doConnect | policy check (newAutoConnectChecker or newConnectChecker), repo.Connect, then unless delayed-setup-profiles: setupSnapSecurity for the slot snap, then the plug snap | entry written after the backends, with auto, by-gadget and attributes |
doDisconnect | repo.Disconnect, setupSnapSecurity for the plug snap, then the slot snap | forget: deleted; by-hotplug: hotplug-gone; an auto-connection not removed by auto-disconnect: undesired: true; otherwise deleted |
doRemoveProfiles | DisconnectSnap, setupAffectedSnaps (snap by snap), RemoveSnap, Remove on every backend | not touched |
setupSnapSecurity uses reason SnapSetupReasonOther and never delays effects. An error after repo.Connect in doConnect disconnects the repository again in a deferred call. A manual connect change is prepare-plug-<plug>, prepare-slot-<slot>, connect, connect-slot-<slot>, connect-plug-<plug>; hook tasks exist only if the snap has the hook.
for snapd developers
Undo
shouldUndoSetupProfiles: if asetup-profilestask of the change for the same snap hasprepare-profiles: true, only that task undoes; if none has it (older change,snap enable, component changes) everysetup-profilestask undoes.undoSetupProfiles:FinishRestart(default true only for the snapd snap),restoreConnectionsForSetupProfiles, thenremoveProfilesForSnapif the snap has no current revision, otherwisesetupProfilesForAppSetfor the current revision withsnapst.Flagsand no delaying.undoConnectwithdelayed-setup-profileschangesconnsand the repository only.auto-connecthas an undo handler that does nothing;auto-disconnecthas none.- The undo handler of
remove-profilesisdoSetupProfiles.
The spread test tests/main/connections-after-failed-refresh checks that a plug only the old revision had is connected again after a failed refresh; tests/main/op-install-failed-undone checks that a failed first install leaves no profile files.
Current behaviour, verified by reading only:
- A refresh that drops a plug or slot does not regenerate the snap on the other end: prepare mode discards
disconnectedSnaps, and the full task no longer sees the connection. - Undo of an auto-connection leaves the peer snap's files with the connection: the full task's undo is skipped,
undoConnectdoes not run the backends, and the prepare task's undo no longer finds the peer. - Undo of
remove-profilesreads the removal'sSnapSetup, which has no flags, so a classic or devmode snap is regenerated as strict.
for snapd developers
Conflicts
- Creation time:
Connect,DisconnectandForgetcallsnapstate.CheckChangeConflictManyfor both snaps, for examplesnap "photo-editor" has "refresh-snap" change in progress. - Runner: every kind registered through
addHandler, plusmark-preseeded, is inexclusiveTaskKinds;runner.AddBlockedkeeps such a task waiting while another one runs.hotplug-seq-waitis not in the set. checkAutoconnectConflicts: a not-readyconnectordisconnecton the same plug or slot snap outside this task's wait chain, or anunlink-snap,link-snap,setup-profilesordiscard-snapof either snap, givesstate.Retryafter 5 seconds and the task log lineWaiting for conflicting change in progress: <reason>.auto-connectalso waits 30 seconds at a time for default providers ofcontentplugs whoselink-snaporsetup-profilesin another change is not ready.- Snap manager tasks are not exclusive: another change can link a snap whose files a
setup-profilesis writing; that snap's ownsetup-profilesrewrites them.
for snapd developers for Ubuntu Core developers
Special cases
- snapd refresh:
auto-connectcallsFinishRestartwith default true, so the prepare task runs in the old snapd and the full task in the new one. See How snapd restarts and re-executes. snap enableand component installs and removals have one full-modesetup-profiles;link-snapofsnap enableinjects anauto-connect, which injects a second one.- Preseeding: when the injected set has interface hooks, it is moved after
mark-preseededand the snap'sinstallhook waits for it. discard-connsstill has handlers but no code creates the task. Asetup-profileswithcore-phase-2from old state is a no-op.transition-ubuntu-corerenamesubuntu-coreconnections tocorewithout rewriting files.
Not covered
photo-themes and its themes content plug, the snaps of changes B and C in the conflicts scene and change number 31 are examples. Whether the window between link-snap and the full setup-profiles, in which a refreshed snap can start under the previous revision's profiles, is accepted on purpose was not determined.
Further reading
No published page describes these tasks.
- Connect interfaces:
snap connect,snap disconnectandsnap connections. - Interface auto-connection: which connections
auto-connectmakes. - Interface hooks: the prepare and connect hooks around a
connecttask. - Security policies: where profiles live and when snapd generates them.
Roads from here
INTERFACES AND CONFINEMENT
- How interfaces are implemented — the repository and the connect task in overview
RUNNING SNAPS
- The overlord — changes tasks lanes and undo
POLICY · who may install and connect what
- When snapd asks — the policy checks in auto-connect and connect
SANDBOX INTERNALS · the mount namespace
- The security backends — what each backend does when it is called
- Hooks and the security they run under — which profile each hook runs under in these changes
- Delayed security setup — the connect tasks that leave setup to setup-profiles
- The system key — when every snap is regenerated at startup
INSIDE SNAPD · the daemon itself
- How snapd restarts and re-executes — the snapd restart between the two tasks of a snapd refresh