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

01 Two setup-profiles in one refresh

SNAP REFRESH PHOTO-EDITOR $ snap change 31Status SummaryDone Make current revision for snap "photo-editor" unavailableDone Copy snap "photo-editor" data Done Prepare snap "photo-editor" (43) for security profile setupDone Make snap "photo-editor" (43) available to the systemprepare modenormally writes no files43 is now current Done Automatically connect eligible plugs and slots of snap "photo-editor"…Done Run post-refresh hook of "photo-editor" snap if presentDone Start snap "photo-editor" (43) services… Done Setup snap "photo-editor" (43) security profilesadds the second taskafter any connect taskswrites the profilesof photo-editor and everysnap connected to it added after them,yet both wait for it Both tasks have the kind setup-profiles, so an older snapd could still run this change after a downgrade.
An abridged snap change listing for a refresh of photo-editor to revision 43. Before the line that makes revision 43 available, a task prepares the snap for security profile setup; it is in prepare mode and normally writes no files. Automatically connect adds a second task, Setup snap photo-editor (43) security profiles, which is listed last and writes the profiles of photo-editor and every snap connected to it. The post-refresh hook and the services wait for it. Both tasks have the kind setup-profiles

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 doSetupProfiles, prepare-profiles: truesnap.ReadInfo("photo-editor", 43)buildConfinementOptions · appSetForTaskrepositoryin memoryphoto-editor 42conns, in snapd's statephoto-editor:home core:homephoto-editor:camera core:cameraphoto-editor:themes photo-themes:themes refreshAppSetConnectionsDisconnectSnap → RemoveSnap → AddAppSet(43)→ reloadConnections("photo-editor")photo-editor 43 home · camera: backthemes: no plug in 43auto-connection, plug gone: deletedchanged-or-dropped-connection-snapshoton the task, kept for undo for each backend: Prepare(appSet)only apparmor acts, and only for core and snapd prepare-plug-* or prepare-slot-* hook?yes: setupSecurityByBackendthis snap only, for those hooksno: no filesthe usual case PendingSecurity = 43
The prepare-mode setup-profiles task, step by step. It reads photo-editor revision 43 and builds the confinement options and the app set. refreshAppSetConnections disconnects the snap in the repository, removes it, adds revision 43 and reloads its connections: home and camera come back, themes does not because revision 43 has no such plug, so that auto-connection is deleted from conns and saved on the task for undo. Every backend's Prepare runs; only apparmor acts, for core and snapd. Only if the snap has a prepare-plug or prepare-slot hook does setupSecurityByBackend write files for this snap; otherwise nothing is written. Finally PendingSecurity is set to 43

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

WHO ELSE GETS REWRITTEN refreshAppSetConnections, again, returnsdisconnectedSnaps: photo-editor, snapdreloadedConns: photo-editor:home snapd:homephoto-editor:camera snapd:camerathe repository is refreshed a second time,on purpose photo-editor (43)home · camerasnapd OwnUpdategoes firstOther reasons: ConnectedSlotProviderUpdate, when that snap has the plug; CyclicallyConnectedUpdate, both ConnectedPlugConsumerUpdatea snap plugged into it changedown flags, pending revision if set 1 · photo-editor2 · snapdsetupSecurityByBackendone backend at a time,over both snaps photo-themesdropped in prepare mode,and the list thrown away:not in this set, keeps theold connection's files
The full setup-profiles task. refreshAppSetConnections runs a second time, on purpose, and returns the disconnected snaps photo-editor and snapd and the reloaded connections home and camera. photo-editor goes first with reason OwnUpdate; snapd, which holds the home and camera slots, gets ConnectedPlugConsumerUpdate, its own flags and its pending revision if set. The other reasons are ConnectedSlotProviderUpdate and CyclicallyConnectedUpdate. The queue photo-editor then snapd goes to setupSecurityByBackend, one backend at a time over both snaps. photo-themes, whose connection was dropped in prepare mode, is not in the set and keeps the files of the old connection

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

SNAP CONNECT $ snap connect photo-editor:cameraprepare-plug-cameraconnectconnect-plug-camerahook tasks: only ifthe snap has the hook 1 newConnectChecker → repo.Connect(…)runs BeforeConnectPlug and BeforeConnectSlot 2 setupSnapSecurity(snapd) → setupSnapSecurity(photo-editor)slot snap first, then the plug snap; disconnect does the reverseSnapSetupReasonOther, no delaying 3 write the conns entry: interface, attributes, auto: false if setup fails after repo.Connect, a deferred repo.Disconnect takes it back $ snap disconnect photo-editor:homerepo.Disconnect → photo-editor → snapd → connsundesired: truean auto-connection disconnected by hand is remembered, so a refreshdoes not connect it again
snap connect photo-editor:camera creates a prepare-plug-camera hook task, a connect task and a connect-plug-camera hook task; the hook tasks exist only if the snap has the hooks. Inside the connect task: 1, the connect policy check and repo.Connect, which runs BeforeConnectPlug and BeforeConnectSlot; 2, setupSnapSecurity for snapd, the slot snap, then for photo-editor, the plug snap, with no delaying; 3, the conns entry with auto false. An error after repo.Connect disconnects in the repository again. Below, snap disconnect photo-editor:home: repo.Disconnect, then photo-editor, then snapd, then conns, where an auto-connection disconnected by hand stays with undesired: true

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

THREE RECORDS unlink-current-snapsetup-profilespreparelink-snapconnectif anysetup-profilesfullconnsrepositoryfilesas connected4242 themes entry dropped43, connections reloadedPendingSecurity: 43 + new entry+ new connection 43, all connectionsall three agree snapd restartsconnsreloadConnectionsrepositoryevery startfiles: rewritten only if the system key differsThe system key
Three lanes, conns in the state, the repository in memory and the files of photo-editor on disk, under the tasks unlink-current-snap, prepare setup-profiles, link-snap, connect if any, and full setup-profiles. All three start at revision 42. The prepare task moves the repository to 43 with reloaded connections and drops the themes entry from conns, while the files stay at 42 and PendingSecurity becomes 43. A connect task adds to the repository and conns only. The full setup-profiles writes the files for 43 with all connections, and all three agree. When snapd restarts, conns is reloaded into the repository every time, while the files are rewritten only if the system key differs

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

UNDO unlink-current-snapsetup-profilespreparelink-snapconnectif anysetup-profilesfullrun-hookpost-refreshexits 1 undo skippedonly the prepare task undoes conns and repository onlydelayed-setup-profiles 42 is current againrestoreConnectionsForSetupProfiles: themes backsetupProfilesForAppSet(42), snapst.Flags, no delayingafter a failed first install: removeProfilesForSnap instead Today: the snap on the other end of an undone auto-connection keeps that connection in its files. Undo of remove-profiles uses the removal's SnapSetup, which has no flags: a classic or devmode snap comes back strict.
The refresh tasks from unlink-current-snap to the post-refresh hook. The hook exits 1 and the change is undone from right to left. The undo of the full setup-profiles is skipped because only the prepare task undoes. A connect task's undo changes conns and the repository only, because of delayed-setup-profiles. link-snap makes 42 current again. The prepare setup-profiles restores its saved connections, themes included, and runs setupProfilesForAppSet for 42 with the snap's own flags and no delaying; after a failed first install it calls removeProfilesForSnap instead. Two current gaps: the snap on the other end of an undone auto-connection keeps that connection in its files, and the undo of remove-profiles uses the removal's SnapSetup, which has no flags, so a classic or devmode snap comes back strict

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

EXCLUSIVE TASK KINDS change Arefreshlink-snapauto-connectsetup-profilesbackends running · state unlockedtime $ snap disconnect photo-editor:homeerror: snap "photo-editor" has "refresh-snap" change in progress change Bsnap connectblocked by the runner until A's task endsrunner.AddBlocked · exclusiveTaskKindsconnect change Cinstallauto-connectC's snap has a slot photo-editor plugs into · retry in 5 sauto-connectWaiting for conflicting change in progress: conflicting snap photo-editor with task "link-snap"
Three changes on one time line. Change A refreshes photo-editor: link-snap, auto-connect, then setup-profiles, with the backends running and the state unlocked. A snap disconnect naming photo-editor is refused at once: snap photo-editor has refresh-snap change in progress. Change B, a snap connect of another snap, has its connect task blocked by the runner until A's task ends, because every interface task kind is exclusive. Change C installs a snap whose slot photo-editor auto-connects to; its auto-connect finds A's link-snap not ready, logs Waiting for conflicting change in progress, and retries every 5 seconds

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 setup-profiles · preparelink-snapauto-connectconnectsetup-profiles · fullrun-hook · servicessnapd starts The security backendswhat each backend writesHooks and the security they run underthe profile each hook runs under Delayed security setupwhy connect leaves setup to later The overlordchanges, tasks, lanes and undoWhen snapd askspolicy checks in auto-connect The system keyevery snap regenerated at startupHow snapd restarts and re-executesbetween the tasks of a snapd refresh How interfaces are implementedthe repository in overview
Roads from Setting up a snap's security, attached to the tasks of a refresh: The overlord and How interfaces are implemented at the prepare setup-profiles; When snapd asks at auto-connect; How snapd restarts and re-executes between link-snap and auto-connect; Delayed security setup at connect; The security backends at the full setup-profiles; Hooks and the security they run under at the hooks and services; The system key at snapd's start

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.

OrderTask kindSummary in snap changeSecurity work
refresh onlyrun-hook, stop-snap-services, remove-aliases, unlink-current-snapMake current revision for snap "<name>" unavailablePendingSecurity set to the current revision
1copy-snap-dataCopy snap "<name>" datanone
2setup-profiles, task data prepare-profiles: truePrepare snap "<name>" (<rev>) for security profile setuprepository refreshed, Prepare on every backend, files only with prepare hooks
3link-snapMake snap "<name>" (<rev>) available to the systemnone
4auto-connectAutomatically connect eligible plugs and slots of snap "<name>"adds the tasks below
4aconnect, one per new connection, with delayed-setup-profiles: trueConnect <plug> to <slot>repository and conns only
4bsetup-profiles, injectedSetup snap "<name>" (<rev>) security profilesfiles of the snap and every snap connected to it
5set-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 taskRepositoryconnsFiles of XPendingSecurity
beforerevision 1 and its connectionsas connectedrevision 1none
unlink-current-snapunchangedunchangedrevision 1revision 1
setup-profiles (prepare)revision 2, connections reloaded from connsauto-connections whose plug or slot is gone deleted; static attributes refreshedrevision 1revision 2
link-snapunchangedunchangedrevision 1none (snap active)
connect (delayed)plus the new connectionplus the new entryrevision 1none
setup-profiles (full)X removed, re-added, connections reloaded againunchanged unless attributes changedrevision 2 with all connections; affected snaps rewrittennone

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:

ReasonThe affected snap
SnapSetupReasonOwnUpdateis the snap being set up
SnapSetupReasonConnectedSlotProviderUpdatehas a plug connected to this snap's slot
SnapSetupReasonConnectedPlugConsumerUpdatehas a slot connected to this snap's plug
SnapSetupReasonCyclicallyConnectedUpdateboth

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

HandlerOrderconns
doConnectpolicy check (newAutoConnectChecker or newConnectChecker), repo.Connect, then unless delayed-setup-profiles: setupSnapSecurity for the slot snap, then the plug snapentry written after the backends, with auto, by-gadget and attributes
doDisconnectrepo.Disconnect, setupSnapSecurity for the plug snap, then the slot snapforget: deleted; by-hotplug: hotplug-gone; an auto-connection not removed by auto-disconnect: undesired: true; otherwise deleted
doRemoveProfilesDisconnectSnap, setupAffectedSnaps (snap by snap), RemoveSnap, Remove on every backendnot 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 a setup-profiles task of the change for the same snap has prepare-profiles: true, only that task undoes; if none has it (older change, snap enable, component changes) every setup-profiles task undoes.
  • undoSetupProfiles: FinishRestart (default true only for the snapd snap), restoreConnectionsForSetupProfiles, then removeProfilesForSnap if the snap has no current revision, otherwise setupProfilesForAppSet for the current revision with snapst.Flags and no delaying.
  • undoConnect with delayed-setup-profiles changes conns and the repository only.
  • auto-connect has an undo handler that does nothing; auto-disconnect has none.
  • The undo handler of remove-profiles is doSetupProfiles.

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, undoConnect does not run the backends, and the prepare task's undo no longer finds the peer.
  • Undo of remove-profiles reads the removal's SnapSetup, which has no flags, so a classic or devmode snap is regenerated as strict.

for snapd developers

Conflicts

  • Creation time: Connect, Disconnect and Forget call snapstate.CheckChangeConflictMany for both snaps, for example snap "photo-editor" has "refresh-snap" change in progress.
  • Runner: every kind registered through addHandler, plus mark-preseeded, is in exclusiveTaskKinds; runner.AddBlocked keeps such a task waiting while another one runs. hotplug-seq-wait is not in the set.
  • checkAutoconnectConflicts: a not-ready connect or disconnect on the same plug or slot snap outside this task's wait chain, or an unlink-snap, link-snap, setup-profiles or discard-snap of either snap, gives state.Retry after 5 seconds and the task log line Waiting for conflicting change in progress: <reason>.
  • auto-connect also waits 30 seconds at a time for default providers of content plugs whose link-snap or setup-profiles in another change is not ready.
  • Snap manager tasks are not exclusive: another change can link a snap whose files a setup-profiles is writing; that snap's own setup-profiles rewrites them.

for snapd developers for Ubuntu Core developers

Special cases

  • snapd refresh: auto-connect calls FinishRestart with 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 enable and component installs and removals have one full-mode setup-profiles; link-snap of snap enable injects an auto-connect, which injects a second one.
  • Preseeding: when the injected set has interface hooks, it is moved after mark-preseeded and the snap's install hook waits for it.
  • discard-conns still has handlers but no code creates the task. A setup-profiles with core-phase-2 from old state is a no-op. transition-ubuntu-core renames ubuntu-core connections to core without 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.

Roads from here

INTERFACES AND CONFINEMENT

RUNNING SNAPS

POLICY · who may install and connect what

SANDBOX INTERNALS · the mount namespace

INSIDE SNAPD · the daemon itself