Interface policy: the questions snapd asks

policy overview for app developers for Ubuntu Core developers for snapd developers

snapd asks three policy questions about interfaces - may a snap be installed with its plugs and slots, may a plug be connected to a slot, and should it be connected automatically. One rule answers each, taken from the store's snap-declaration if it has one for that interface or else from the base declaration built into snapd. Only the interface manager asks, inside the tasks of a change.

On the map: policy

▶ Watch this deck — 7 scenes, ~5 min

01 Three questions, two layers

INTERFACE POLICY photo-editor plugs: network · home · camera may it be installed?snap install · snap refreshmay it be connected?snap connect photo-editor:camerashould it be connected automatically?after every install and refresh one rule for this interface snap-declarationfrom the storefor photo-editor onlyif it has a rulebase declarationbuilt into snapdevery interfaceotherwise alloweddeniednot allowed asked only by the interface manager, inside the tasks of a change
The photo-editor snap plugs network, home and camera. Three questions, install, connect and auto-connect, are each answered by one rule for the interface, taken from the snap-declaration if it has one and otherwise from the base declaration; the answer is allowed, denied or not allowed

Install, connect and auto-connect are three separate questions. One rule answers each: the snap-declaration's rule for that interface if the store issued one, otherwise the base declaration's. Only the interface manager asks, from the tasks of a change.

You've put the photo editor in the store. It plugs network, home and camera. Network connects by itself; camera waits for you to say yes. Who decides? Snapd asks three questions: may the snap be installed with these plugs and slots, may a plug be connected to a slot, and should that happen automatically? One rule answers each. It comes from the photo editor's snap-declaration, if the store put a rule there, and otherwise from the base declaration built into snapd. The answer is allowed, denied or not allowed, and only the interface manager asks, inside a change.

02 Where the two layers come from

TWO LAYERS base declaration snap-declaration 222 interfaces222 slot rules · 65 plug rulesassembled at snapd startbuilt-in assertion $ snap debug base-declaration storecannot replace itchanges only with the snapd version store review, outside snapdsigned for one snap-idplugs · slots fetched with the snap (validate-snap)fetched again before every refresh a store rule replaces the base rule for that interface; nothing is merged
Two lanes: the base declaration assembled from 222 interfaces at snapd start into a built-in assertion that the store cannot replace, and the snap-declaration issued by the store for one snap, fetched with the snap and again before every refresh; a store rule replaces the base rule

The base declaration is assembled from every interface when snapd starts, and only a new snapd changes it. The snap-declaration comes with the snap and is fetched again before each refresh. A store rule replaces the base rule for that interface; nothing is merged.

So where do those two layers live? The base declaration isn't a file you can edit. Each of snapd's two hundred and twenty two interfaces carries its own rule text, and when snapd starts it joins them all into one built-in assertion. snap debug base-declaration prints it. The store can't replace it, so it changes only when snapd does. The photo editor's snap-declaration is the store's part. It's signed for that one snap, fetched with the snap, and fetched again before every refresh. If it has a rule for camera, that rule replaces the base rule for camera, for this snap, whole. Nothing is merged.

03 What each answer looks like

WHAT YOU SEE $ snap refresh photo-editorerror: cannot perform the following tasks:- Mount snap "photo-editor" (43) (installation not allowed by"snapd-control" plug rule of interface "snapd-control")change fails and is undone:snap absent or at itsold revision (42) $ snap connect photo-editor:homeerror: cannot perform the following tasks:- Connect photo-editor:home to snapd:home (connection deniedby slot rule of interface "home")accepted, then the connecttask fails: no connectiona plug with read: all $ snap connections photo-editorInterface Plug Slot Notescamera photo-editor:camera - -no error; the plug waits for snap connectno error: the plugstays disconnectedtask log only if candidateswere found but none used denied: a deny rule matched · not allowed: no allow rule matched the message names the rule, side and interface; not which constraint failed
Three terminal panels for photo-editor: a refresh to a build with a snapd-control plug fails its mount-snap task, a refused snap connect of a home plug with read: all fails its connect task, and the camera plug that may not auto-connect stays disconnected without an error; no message names the constraint that failed

Install and connect refusals fail the change with installation not allowed by ... or connection denied by .... An auto-connection that is not allowed leaves the plug disconnected without an error. No message names the constraint that failed.

What does a no look like from your side? Say a build of the photo editor adds a snapd-control plug. Its mount-snap task fails and the change is undone: the snap stays absent, or at its old revision. A refused snap connect is accepted at first; then its connect task fails and no connection is made. A refused auto-connection isn't an error at all. Camera just stays disconnected; at most, the task log mentions it. Denied means a deny rule matched; not allowed means no allow rule did. The message names the rule, the side and the interface, but not the constraint that failed.

04 Predicting what happens to your snap for app developers for Ubuntu Core developers

PREDICT pluginstallssnap connectauto-connectsask the store for networkyesyesyes, everywherenothing camerayesyesnoauto-connect, if justified homeyesyesnot with read: allon classic: yeson Ubuntu Core: nonothing; read: allneeds a store rule contentyeswhen contenttags matchsame publisher,one provider onlythe base rule plusslots-per-plug: * snapd-controlno, fromthe store--a store rule a store rule replaces the whole base rule; any sub-rule it leaves out is allowed
A grid of five plugs of photo-editor, network, camera, home, content and snapd-control, with whether each installs, connects with snap connect, auto-connects, and what to ask the store for

The base rule predicts the three answers: network auto-connects, camera is manual, home is manual on Ubuntu Core, content auto-connects only within one publisher, and snapd-control needs a store rule to install. A store rule replaces the whole base rule.

Before you upload, read the base rule of each interface the photo editor plugs; it predicts all three answers. Network installs and auto-connects everywhere. Camera installs and connects, but waits for snap connect. Home auto-connects on classic and not on Ubuntu Core, and a plug with read: all needs a store rule even to connect. Content connects when the content tags match, and auto-connects only within one publisher, to a single provider. A snapd-control plug wouldn't even install from the store. If you ask the store for more, remember that its rule replaces the whole base rule, and anything it leaves out is allowed.

05 A store snap and a local build

--DANGEROUS photo-editor from the store a local build, --dangerous no snap-id, no snap-declarationsnap-id and snap-declaration installevery plug and slot:store rule or base ruleslots only: base rule's snap type,classic or Ubuntu Core snap connectthe rule in forceno rule evaluated if either sidehas no snap-declaration auto-connectthe rule in forceother side's store rule or base;publisher constraints fail gadget connectionsapplied at seeding or remodelskipped same for snap try and an unasserted --devmode sideload--devmode and --classic confinement do not change the questions
Two columns compare a snap from the store with one installed with --dangerous for install, connect, auto-connect and gadget connections

With --dangerous: the install check covers slots only, snap connect evaluates no rule if either side has no snap-declaration, auto-connect follows the other side's store rule or the base declaration but publisher constraints never match, and gadget connections are skipped.

You're testing your own build of the photo editor, installed with --dangerous. With no snap-id it has no snap-declaration, and each question changes. The install check looks only at its slots, against the base rule's snap types and whether this is classic or Ubuntu Core. Plugs aren't checked, so even a snapd-control plug installs. Snap connect evaluates no rule when either snap lacks a snap-declaration. For auto-connect there's no publisher to compare, so the content plug won't auto-connect to your own plugin pack. Gadget connections skip the snap. Snap try and an unasserted devmode sideload are treated the same.

06 Answers are kept, not revisited

LATER CHANGES installcamera connectedphoto-editor:camerasnapd:camera stricter snap-declarationfetched before a refresh kept · checked only to adopt new attribute values $ snap refresh photo-editorto a new revisionmount-snap: install checkrefused: revision 42 stays snap revert: no install check a newly allowed auto-connection appears at the next install, refresh or revertof either snap, unless the user disconnected it
A timeline: photo-editor is installed and its camera plug connected; the store issues a stricter snap-declaration; the connection is kept and checked only to decide whether new attribute values are adopted; the next refresh to a new revision is checked and refused so the old revision stays; a revert is not checked

Existing connections are not re-judged when a snap-declaration changes; the rules only decide whether new attribute values from a refresh are adopted. The next refresh to a new revision is checked against the new declaration; a revert is not. A newly allowed auto-connection is made at the next install, refresh or revert of either snap, unless the user disconnected it.

Snapd answers a policy question once. Say the store later issues a stricter snap-declaration for the photo editor. Snapd fetches it before the next refresh and stores it. Existing connections are restored at every start and setup-profiles without a policy check, except to decide whether a refresh's new attribute values are adopted. A stricter installation rule applies at the next refresh to a new revision: if the install check refuses it, revision 42 stays. A stricter connection rule removes no connection, and a revert isn't checked again. A newly allowed auto-connection appears at the next install, refresh or revert of either snap, unless you disconnected it.

07 Where to go from here

ROADS Interface policy The base declarationthe rule it starts with Snap-declaration ruleswhat the store grants How a rule is evaluatedfound and matched When snapd asksin the tasks of a change next doorHow interfaces workthe policy packageInterfacesthe overview Assertionshow the store is trustedInterface classessuper-privileged and more
Roads from interface policy: the base declaration, snap-declaration rules, how a rule is evaluated and when snapd asks; neighbours: how interfaces work, interfaces, assertions and interface classes

Roads: the base declaration, snap-declaration rules, evaluation and when snapd asks; next door, the implementation, the interfaces overview, assertions and interface classes.

Three questions, two layers, and answers that stay put. Four decks in this district take each piece apart. The base declaration shows the rule every interface starts with and the shapes those rules take. The snap-declaration rules deck covers what the store can grant one snap, and its constraints. How a rule is evaluated follows one question from candidate to answer. When snapd asks places each question in the tasks of a change. Next door, the implementation deck shows the policy package in code, the interfaces overview introduces plugs and slots, the assertions deck explains how a snap-declaration is trusted, and interface classes says what super-privileged means.

Read more

The three questions

QuestionAsked inSub-rules readA refusal shows as
May the snap be installed with its plugs and slots?mount-snap, before the snap is mounteddeny-installation, then allow-installation, per plug and slotthe change fails: installation denied by ... or installation not allowed by ...; the snap stays absent or at its old revision
May this plug be connected to this slot?the connect task of a snap connect change, and gadget connectionsdeny-connection, then allow-connectionthe connect task fails: connection denied by ... or connection not allowed by ...
Should this pair be connected automatically?the auto-connect task of an install, refresh or revert, again in each injected connect task, and hotplug-connectdeny-auto-connection, then allow-auto-connectionnothing: the plug stays disconnected; the task log names the candidates only when several were found and none was used

Only the interface manager asks these questions, always from a task. The answer is allowed, denied (a deny sub-rule matched) or not allowed (no allow sub-rule matched). No message names the constraint that failed.

Which rule answers

QuestionRules looked up, first found decides
installation of a plugthe snap's own snap-declaration plug rule, then the base plug rule; with neither, allowed
installation of a slotthe snap's own snap-declaration slot rule, then the base slot rule; with neither, allowed
connection and auto-connectionthe plug snap's snap-declaration plug rule, the slot snap's snap-declaration slot rule, the base plug rule, the base slot rule; with none, allowed

A store rule replaces the base rule for that interface on that side, whole. Sub-rules it does not state take the defaults: an absent allow-* is true and an absent deny-* is false.

Error messages

FormMeaning
installation denied by "<name>" plug rule of interface "<iface>" (or slot rule)a deny-installation alternative matched for the plug or slot named
installation not allowed by "<name>" slot rule of interface "<iface>" (or plug rule)no allow-installation alternative matched
connection denied by plug rule of interface "<iface>" (or slot rule; not allowed likewise)a deny-connection alternative matched
auto-connection not allowed by ..., auto-connection denied by ...not shown; the pair is dropped
suffix for "<snap>" snapthe rule came from that snap's snap-declaration

A store snap and a local build

From the store--dangerous, snap try, unasserted --devmode
snap-id, snap-declarationyesno
Install checkevery plug and slot, store rule or base ruleslots only, the base allow-installation only, and only its snap type, on-classic and on-core-desktop constraints
snap connectthe rule in forceno rule evaluated if either snap has no snap-declaration
Auto-connectthe rule in forcethe other snap's store rule or the base declaration; publisher constraints never match
Gadget connectionsapplied at seeding or in a remodelskipped

The --devmode and --classic flags do not change any of the questions.

When a snap-declaration changes later

SituationEffect
New snap-declaration fetchedbefore every refresh and auto-refresh; stored, nothing else happens
Existing connectionsrestored at every start and in every setup-profiles without a policy check
Stricter installation rulethe next refresh to a new revision fails in mount-snap; the old revision stays
Stricter connection or auto-connection ruleno existing connection is removed
snap revertnot checked again
Newly allowed auto-connectionmade at the next install, refresh or revert of either snap, unless the user disconnected it

Further reading

Roads from here

INTERFACES AND CONFINEMENT

ASSERTIONS · signed statements snapd trusts

POLICY · who may install and connect what