When snapd asks

policy · call sites for app developers for snapd developers

Only the interface manager asks the policy questions and always inside a task - mount-snap asks about installation, connect about a manual or gadget connection, auto-connect about every candidate pair. A snap without a snap-id is treated differently at each site. Answers are not revisited when a snap-declaration or the model changes later.

On the map: policy

▶ Watch this deck — 8 scenes, ~6 min

01 Three questions in the task graph

WHERE IT IS ASKED snap install acme-agent prerequisites download-snap validate-snap prerequisites mount-snap fetches the snap-declaration copy-snap-data setup-profiles link-snap auto-connect … install? auto-connect? injected after auto-connect, per connection: run-hookprepare-plug connect run-hookconnect-plug setup-profiles auto-connect? again · auto=true one for the batch snap connect acme-agent:network-control · its own change run-hookprepare-plug run-hookprepare-slot connect run-hookconnect-slot run-hookconnect-plug connect? the only importer of the policy package: overlord/ifacestate also hotplug-connect and, for attributes only, at start-up
An install change as a row of tasks: mount-snap asks the install question, auto-connect asks the auto-connect question and injects connect tasks that ask again; a snap connect change whose connect task asks the connect question

install? in mount-snap; auto-connect? in auto-connect and again in each injected connect; connect? in the connect task of a snap connect change. Only overlord/ifacestate asks.

You install the acme-agent on the gateway. When does snapd ask its three questions? Always from a task, and always in the interface manager. In the install change, validate-snap fetches the snap-declaration, and mount-snap asks whether the snap may be installed, before anything is mounted. Once the snap is linked, the auto-connect task asks about every candidate pair and injects a connect task for each connection it makes; that task asks again, after the prepare hooks. Later you run snap connect for network-control. That's its own change, and its connect task asks whether the pair may be connected. A hotplug-connect task asks too.

02 Which operations are judged for installation

INSTALLATION CHECK mount-snap only when a revision is mounted judged · full check snap install acme-agent snap refresh acme-agent · auto-refreshnew snap-declaration snap ack, then snap install ./acme-agent.snap seeding · remodel install or refreshnew model reduced check · no snap-id snap install --dangerous ./acme-agent.snap snap try ./acme-agent snap install --devmode ./acme-agent.snapno assertions not judged snap revert acme-agent refresh to an installed revision snap enable acme-agent snap install acme-agent+comp remodel relink refused: change undone · nothing mounted · on refresh the old revision stays error: cannot perform the following tasks: - Mount snap "acme-agent" (42) (installation not allowed by ...) --devmode and --classic flags are ignored by the check
Commands that mount a new revision lead into mount-snap and are judged, fully or with the reduced check; revert, enable, component installs and remodel relinks skip it; a refusal undoes the change

Every new revision is judged in mount-snap against the current snap-declaration; --dangerous, snap try and unasserted --devmode get the reduced check. Reverts and snap enable are not judged.

Which operations on the gateway get judged for installation? Only those that mount a new revision. Store installs, refreshes including auto-refresh, sideloads with acknowledged assertions, seeding, and installs or refreshes in a remodel get the full check, and a refresh is judged against the snap-declaration fetched just before it. A dangerous install, snap try and a devmode sideload without assertions get a reduced check of the base declaration's slot rules. Snap revert, snap enable and component installs mount no new revision and aren't judged. A refusal fails mount-snap before anything is mounted, and a refresh keeps the old revision. The devmode and classic flags change nothing.

03 A manual connect for app developers for snapd developers

SNAP CONNECT $ snap connect acme-agent:network-control daemon: resolve the plug and the slot snap "acme-agent" has no plug named "network-contrl" a typo fails here at once: no policy consulted yet run-hookprepare-plug run-hookprepare-slot connect attributes set by the hooks count the interface's own checks (BeforeConnectPlug / Slot) both snaps have a snap-declaration? yes connection rules: network-control allowed no no rule evaluated: connected a --dangerous snap on either side error: cannot perform the following tasks: - Connect acme-agent:home to snapd:home (connection denied by slot rule of interface "home") a refusal, for example a home plug with read: all · the change is undone
snap connect acme-agent:network-control: the daemon resolves the plug and the slot, then a change runs prepare hooks and a connect task; inside it the interface's own checks run, then the connection rules only if both snaps have snap-declarations; network-control has no connection deny and connects; a denial is printed as a task error

The connect task evaluates connection rules after the prepare-* hooks and the interface's own checks, and only when both snaps have snap-declarations. With a --dangerous snap on either side, no rule is evaluated.

The agent's network-control plug waits, so you run snap connect. The daemon resolves the plug and the slot. Mistype the plug name and that fails at once, with no policy involved. Otherwise you get a change. Its connect task runs after the prepare hooks, so the attributes they set count, and after the interface's own checks, whose errors can come first. Only then, and only if both snaps have a snap-declaration, are the connection rules evaluated. network-control has no connection deny, so this one goes through. With a dangerous install on either side no rule is evaluated. A refusal fails the task and undoes the change.

04 Choosing auto-connect candidates for app developers for snapd developers

CANDIDATES plug acme-agent:certs every slot of the same interface, in every snapcert1cert2cert3cert4cert1_x the auto-connection rulescert1cert2cert1_xcert3, cert4 dropped: no error, no log the interface's own checkcert1cert2cert1_xdrop ubuntu-core duplicates, parallel instancescert1cert2 arity: a rule not * and more than one left→ none connectedcannot auto-connect plug acme-agent:certs, candidates found: cert1:certs, cert2:certs x11 only: interface.x11.allow-auto-connectionotherwise: a connect task per slotauto=true no snap-id: no snap-declaration of its own;the other side's or the base declaration decides
A funnel for one plug acme-agent:certs: five slots of the same interface, two dropped by the auto-connection rules, one parallel instance dropped, two left, so the arity rule connects none and the task logs the candidates

Candidates must pass the auto-connection rules and the interface's own check; failures are dropped silently. With more than one candidate and any arity other than *, nothing connects and the task logs the candidates. An administrator option filters x11 too.

The acme-agent's content plug, certs, has several possible providers on the gateway. For each plug, the auto-connect task looks at every slot of the same interface in every snap. A pair that fails the auto-connection rules drops out, with no error or log. The interface's own code may refuse too. Duplicates from ubuntu-core and slots of parallel instances go next. Then arity: unless every candidate's rule says slots-per-plug: *, more than one candidate means none, and the task logs them. Otherwise each survivor gets a connect task. A dangerous install brings no snap-declaration, so the other side's or the base declaration decides.

05 Two providers, no connection for app developers for snapd developers

ARITY IN PRACTICE content: certs · publisher acme defaultslots-per-plug: 1acme-agentcert1cert2neither connected cannot auto-connect plug acme-agent:certs, candidates found: cert1:certs, cert2:certs acme-agent store rulebase rule + slots-per-plug: *acme-agentcert1cert2both connected provider store rules* and 1acme-agentcert1cert2one not * is enough later acme-agent cert1 connected first: the connection stays cert2 installed later: two candidates, nothing new cannot auto-connect slot cert2:certs to plug acme-agent:certs, candidates found: cert1:certs, cert2:certs
One consumer plug and two content providers: with default arity neither connects; with slots-per-plug * on the consumer both connect; with * and 1 on the providers neither connects; a provider installed later is not connected and the first connection stays

Default arity: two candidates, no connection, a log line. A plug rule for the consumer that restates the base constraints and adds slots-per-plug: * connects both. A second provider installed later is not connected; the existing connection stays.

Here's how that surprises people. Acme ships two certificate snaps, both with a certs slot, and both pass content's rule for the agent's plug. With the default arity of one, neither is connected, and the task log lists both. A store rule on the agent that restates the content and publisher constraints and adds slots-per-plug: * connects both. If one provider's rule says star and the other's doesn't, nothing connects. And if the second provider arrives later, its auto-connect task recomputes every candidate for the plug, finds two, and connects nothing new. The first connection stays.

06 Gadget connections for Ubuntu Core developers for snapd developers

GADGET CONNECTIONS acme-gateway gadget.yamlconnections: - plug: <agent snap-id>:network-control # no slot: the system slot of that name system not yet seeded, or remodelling? no: not applied yes auto-connect: no policy consulted, pair added connect · auto=true · by-gadget=true the connection rules network-control deny-auto-connection: true, no connection deny connected · snap connections notes gadget a connection rule denies connect fails seeding or the remodel fails snaps without a snap-id are skipped
A gadget.yaml connections entry is applied only before seeding or in a remodel, skips the auto-connection rules and is checked by the connection rules in a connect task marked by-gadget; network-control connects, a denial fails seeding or the remodel

Gadget connections: apply only before seeding completes or in a remodel. They bypass auto-connection rules and are checked against connection rules. Snaps without a snap-id are skipped. snap connections shows them with the note gadget.

On a fleet of gateways nobody will type snap connect. So the acme-gateway's gadget lists the connection, naming the agent by snap-id. Each snap's auto-connect task applies such entries, but only before the system is seeded or during a remodel. No auto-connection rule is consulted. The connect task is marked by-gadget, and judged by the connection rules instead. That's how the agent's network-control plug gets connected, although its base rule denies auto-connection. A refusal by the connection rules fails the connect task, and with it seeding or the remodel. Snaps without a snap-id take no part.

07 Declarations change, connections stay for app developers for snapd developers

LATER fetch snap-declarationsbefore every refresh and auto-refresh snap-declaration, revision 2stored · no task · connections untouched acme-agent:certs cert1:certs restore connections daemon start · every setup-profiles · policy: nil new static attributes after a refresh?re-checked: if refused, old attributes kept and logged next refresh mount-snap stricter install rule: refused, old revision stays auto-refresh retries and fails the same way next install, refresh auto-connect looser: new auto-connections, either snap a disconnected auto-connection is remembered as undesired and not brought back a remodel judges what it installs or refreshes against the new model
A new snap-declaration is stored without touching connections; restoring connections at start puts them back connections without a policy check; the next refresh is judged in mount-snap and may fail, keeping the old revision; looser rules act at the next auto-connect

New snap-declarations are only stored. Restoring connections at start and in setup-profiles runs no policy check. The next refresh is judged in mount-snap; new auto-connections wait for the next auto-connect, and connections the user disconnected stay disconnected.

Months later the store revises the acme-agent's snap-declaration. What happens on the gateway? Before every refresh, snapd fetches new declarations and stores them; nothing more. Stored connections are restored at start and in every setup-profiles task, unchecked. The rules only decide whether a refreshed snap's new static attributes are adopted. A stricter installation rule takes effect at the next refresh, which fails in mount-snap, keeping the old revision; a stricter connection rule removes nothing. A looser one adds connections at the next auto-connect of either snap, unless someone disconnected them. A remodel judges what it installs or refreshes against the new model.

08 Where to go from here

ROADS When snapd asks Interface policyback to the three questionsHow a rule is evaluatedwhat happens inside each check elsewhere on the mapThe overlordchanges, tasks, undo Interfaces for userssnap connect, snap connections Model, gadget and kernelremodel, gadget connectionsDevice presetswhy a gadget connects Assertions: snapswhen declarations are fetchedHow interfaces workinterface manager, repository
Roads from this deck: the policy overview and rule evaluation in this district; the overlord, interfaces for users, the model, device presets, snap assertions and the interface implementation elsewhere

Evaluation and the overview in this district; changes, users, models, device presets, assertions and the implementation in theirs.

You've followed the acme-agent from mount-snap to a gadget connection and beyond. In this district, the overview returns to the three questions, and the evaluation deck shows what each check does once it's asked. The overlord's deck covers changes, tasks, and how a failed task undoes a change. The users' deck covers snap connect and snap connections from the command line. The model deck covers remodelling and the gadget behind gadget connections, and device presets explains why a gadget carries them. The assertions deck shows when snap-declarations are fetched, and the implementation topic shows the interface manager and its repository.

Read more

Call sites

WhereQuestionRulesInputsOn refusal
mount-snap in an install, refresh, seeding or remodelinstallationinstallation, per plug and slotthe snap-declaration fetched by validate-snap, the base declaration, the device context of the taskthe task fails before the snap is mounted; the change is undone
connect task of a snap connect changeconnectionconnectionboth snap-declarations, the base declaration, the device contextthe task fails and the change is undone
auto-connect task after link-snapauto-connectionauto-connection, per candidate pairas abovethe pair is dropped without an error
connect task injected by auto-connect (auto=true)auto-connection, again, after the prepare-* hooksauto-connectionas above, with the attributes the hooks setthe task ends without a connection and without a log line (suspected snapd bug, findings/review/BUGS.md #31)
connect task with by-gadget=trueconnectionconnectionas abovethe task fails, and with it seeding or the remodel
hotplug-connectauto-connection for a new hotplug slotauto-connectionas abovethe pair is dropped
start-up and setup-profilesnone for existing connections; new static attributes after a refresh are re-checkedconnection or auto-connectionthe current modelthe old static attributes are kept and a notice is logged

Only overlord/ifacestate imports the policy package.

Which operations are judged for installation

OperationInstall check
snap install, snap refresh, auto-refreshfull, against the snap-declaration fetched just before
snap ack then snap install ./file.snapfull
seedingfull, with assertions from the seed
install or refresh in a remodelfull, against the new model
snap install --dangerous, snap try, snap install --devmode without assertionsminimal: base slot rules only
snap revert, refresh to an installed revision, snap enable, component install, remodel relinknot judged

Auto-connect candidates

1. Every slot of the plug's interface in every snap, including implicit system slots. 2. Pairs that fail the auto-connection rules drop out, without an error or a log line. 3. Pairs the interface's own code refuses drop out. 4. Slots of the old ubuntu-core snap are dropped when core provides the same, and slots of parallel instances are dropped. 5. Arity: unless every remaining candidate's rule says slots-per-plug: *, more than one candidate means none. The task then logs cannot auto-connect plug <snap>:<plug>, candidates found: .... 6. For x11 only, the system option interface.x11.allow-auto-connection filters the result. It is applied when the plug's snap is installed, not when a new x11 slot appears (a snapd bug). 7. Each remaining pair gets a connect task with auto=true.

When a slot's snap arrives later, its auto-connect recomputes every candidate of each plug. With two candidates and arity one nothing new connects, and an existing connection stays.

Gadget connections

  • The gadget's connections: name the plug and the slot by snap-id or system. Without a slot: the system slot of the plug's name is used.
  • They are applied only before the system is seeded, or during a remodel with the new gadget.
  • No auto-connection rule is consulted. The connect task is marked by-gadget and checked against the connection rules, unless either snap has no snap-declaration.
  • Snaps without a snap-id are skipped. snap connections shows the note gadget.

After a snap-declaration changes

SituationEffect
New snap-declarationsfetched before every refresh and auto-refresh; stored without a task
Existing connectionsrestored at start and in every setup-profiles without a policy check
Stricter installation rulethe next refresh fails in mount-snap; auto-refresh fails the same way
Stricter connection ruleno connection is removed
Looser auto-connection rulenew connections at the next auto-connect of either snap
Auto-connection the user disconnectedstored as undesired and not brought back, unless disconnected with --forget
Remodelsnaps installed or refreshed in it are judged against the new model; untouched snaps are not

Further reading

  • Interface auto-connection: when snapd reviews unconnected plugs, and how a disconnect stops a later refresh from reconnecting.
  • Connect interfaces: snap connect, snap disconnect and snap connections in practice.
  • Gadget snap format: the connections: section. It says connections are made on first boot only; the code also applies them in a remodel.
  • Remodeling: what a remodel installs and refreshes.

Roads from here

INTERFACES AND CONFINEMENT

RUNNING SNAPS

  • The overlord — changes and tasks and how a failed task undoes a change

ASSERTIONS · signed statements snapd trusts

POLICY · who may install and connect what

UBUNTU CORE · install and recovery