How a rule is evaluated

policy · evaluation for app developers for snapd developers

The policy package builds a candidate, finds the one rule in force - plug snap-declaration then slot snap-declaration then base plug rule then base slot rule for a connection and the snap's own side for an installation - and evaluates only that rule's sub-rules of the asked kind with deny before allow. Constraints in a map must all hold and alternatives in a list need one. Snaps without a snap-id get a reduced installation check.

On the map: policy

▶ Watch this deck — 8 scenes, ~6 min

01 From candidate to answer for app developers for snapd developers

EVALUATION connect candidatephoto-editor:cameraplug · slotboth snap-declarationsbase declarationmodel · store 1 plug snap's snap-declarationno rule2 slot snap's snap-declarationno rule3 base plug ruleno rule4 base slot rulefoundfirst found decides · none of the four: allowed kind: connectiondeny-installationallow-installationdeny-connectionfirstallow-connectionthendeny-auto-connectionallow-auto-connection a deny alternative matchesdeniedno allow alternative matchesnot allowedconnection not allowed by slot rule of interface "camera" for "<snap>" snapthe error names the side and the interface; the orange suffix appears only when a snap-declaration decided camera states neitherallowed+ slots-per-plug for auto-connection
A connect candidate for photo-editor:camera flows into a four-step rule lookup that stops at the first rule found, here the base slot rule; the asked kind selects deny-connection then allow-connection from that rule's six sub-rules, giving denied, not allowed or allowed; camera is allowed

Candidate, first rule found, then the asked kind's deny-* and allow-*. "denied" means a deny matched; "not allowed" means no allow did. For an auto-connection an allowed answer also returns slots-per-plug. One rule decides.

You connect the photo editor's camera plug. What does snapd evaluate? It builds a candidate: the plug and the slot, both snaps' snap-declarations, the base declaration, the model and the store. Then it looks for a rule in a fixed order and takes the first one that exists. For camera, neither declaration has one and there's no base plug rule, so the base slot rule decides, and nothing else is read. The question asked picks two of its six sub-rules. deny-connection comes first: any matching alternative denies. Then allow-connection must match once, or the answer is not allowed. Camera states neither, so it's allowed.

02 Installation looks only at its own side for app developers for snapd developers

INSTALLATION photo-editornetwork plugnetwork slotsnapd-control plug 1 own snap-declaration2 base rule, same sideanswer no ruleno plug ruleallowedthe slot rule is not read no ruleslot-snap-type: [core]not allowedan app is not type coreinstallation not allowed by "network" slot rule of interface "network" no ruleallow-installation: falsenot allowedno alternative can match several failures: which one is reported is not fixed (Go map order)snap-id constraints in installation rules refer to the snap's own snap-id
A photo-editor build with a network plug, a network slot and a snapd-control plug; each is checked against its own side's rule only: the network plug is allowed, the network slot and the snapd-control plug are not

The install check runs per slot, then per plug, each with its own side's rule: snap-declaration, else base, else allow. A network plug installs; an app's network slot does not. Snap-id constraints in installation rules refer to the snap's own snap-id.

Installation is different: there's no other side yet. Picture an over-eager build of the photo editor with a network plug, a network slot and a snapd-control plug. The install check takes every slot, then every plug, and each looks up its own side only: its own declaration first, then the base rule on the same side, and with neither, it's allowed. The network plug passes, because network has no plug rule, and the slot rule isn't read. The network slot fails, because only snap type core may carry it. The snapd-control plug fails on allow-installation: false. With several failures, which one you see depends on map order.

03 Tracing home on classic and Ubuntu Core for app developers for Ubuntu Core developers for snapd developers

TRACE: HOME base-declaration, slots:home:allow-installation:slot-snap-type:- coredeny-connection:plug-attributes:read: alldeny-auto-connection:-on-classic: falseon-core-desktop: false-plug-attributes:read: allno store rules · no base plug rule → the base slot rule decides laptop (classic)Ubuntu Coresnap connectdeny-connectionread unset: no matchallowedread unset: no matchallowed auto-connectdeny-auto-connectionalt 1: both holdthe deny matchesdenied alt 1: on-classic failsalt 2: read unsetallowed plug withread: allconnection deniedauto-connection deniedconnection deniedauto-connection denied
home's base slot rule beside a trace table: for a plug without attributes, connection is allowed on classic and Ubuntu Core; auto-connection is denied on Ubuntu Core by the first alternative and allowed on classic; a plug with read: all is denied both ways

home: connection allowed unless read: all. Auto-connection denied on Ubuntu Core by alternative 1 (on-classic: false and on-core-desktop: false), allowed on classic. A plug with read: all is denied both ways.

On a laptop the photo editor's home plug connects by itself; on an Ubuntu Core device it doesn't. With no store rules and no base plug rule, home's base slot rule decides. For snap connect, the deny needs the plug to set read: all. This one leaves it unset, which fails, so the deny doesn't match and the default allows it. For auto-connect, the first alternative needs not classic and not Core desktop. On Ubuntu Core both hold, so it's denied there. On classic, alternative one fails on classic and alternative two on the unset attribute, so it's allowed. A plug with read: all is denied both ways.

04 Tracing content: attributes and publishers for app developers for snapd developers

TRACE: CONTENT base-declaration, slots:content:allow-installation: …allow-connection:plug-attributes:-content: $SLOT(content)-compatibility: $SLOT_COMPAT(compatibility)allow-auto-connection:plug-publisher-id:- $SLOT_PUBLISHER_IDplug-attributes:-content: $SLOT(content)-compatibility: $SLOT_COMPAT(compatibility) photo-editorcontent: presetsplug · publisher Apresets snapcontent: presetsslot · publisher A snap connectallowedno deny-connection; allow-connection, first map:content: presets = presets auto-connectallowedplug-publisher-id: A = Aand the first map again: presets = presetsreturns slots-per-plug 1 presets snap from publisher Bconnection: allowedauto-connection: not allowedcompatibility labels apply to content only when the content-compatibility-label feature flag is set
content's base slot rule beside photo-editor and a presets snap sharing the content tag presets: connection is allowed because the tags are equal; auto-connection also requires the same publisher, so a provider from another publisher connects only by hand

content's allow-connection compares the content tag with $SLOT(content). allow-auto-connection adds plug-publisher-id: [$SLOT_PUBLISHER_ID]: other publishers connect only by hand.

Now the photo editor gets presets from a content snap you also publish. Content has no base plug rule, so its slot rule decides. For snap connect there's no deny, and the allow has a list of alternatives in its plug-attributes. The plug's content attribute must equal the slot's, or its compatibility label must be compatible with the slot's. Both say presets, so the connection is allowed. For auto-connect, the plug's publisher must also be the slot's publisher, and both conditions must hold. They do, and the arity returned is one. A presets snap from another publisher connects by hand, but not automatically, without an error.

05 Deny wins only inside the rule for app developers for snapd developers

ONE RULE DECIDES inside the rule in force a matching deny wins, but only one rule is read two store rulesplug snap-declarationdeny-connection: falseslot snap-declarationdeny-connection: truenot readallowedsnap-slot-deny-snap-plug-allow store rule and base ruleplug snap-declarationrule: truebase slot rulerule: falsenot readallowedbase-deny-snap-plug-allow one rule, two kinds: mirauto-connection askeddeny-auto-connection: absentsame base slot ruledeny-connection: trueother kind: not readallowedalso in Implementation: rule order deny beats allow inside one rule; the first rule found beats every other rulewhen writing store rules, think in rules, not in allow and deny lines
Three cases where only the first rule found is read: a plug-side store allow over a slot-side store deny, a store allow over a base deny, and mir's deny-connection not read for auto-connection; all three are allowed

Deny beats allow within the rule in force. Between rules, the first found decides: plug snap-declaration over slot snap-declaration over base. Each kind reads only its own sub-rules.

It's tempting to think a deny anywhere beats an allow anywhere. It doesn't. Inside the rule in force, a matching deny wins, but only one rule is read. If the plug snap's store rule allows a connection and the slot snap's store rule denies it, the plug side is read first, and the connection is allowed. A store rule that allows beats a base rule that denies, because the base rule isn't read. And each question reads only its own sub-rules, so mir's deny-connection does nothing for auto-connection. When you ask the store for a photo editor rule, think in whole rules, not in allow and deny lines.

06 Matching one alternative for snapd developers for app developers

CONSTRAINTS a map: every constraint must hold (and) · a list of maps: one map must match (or)alternative 1 of a plug-side connection rule, in checking orderplug-namesslot-namesplug-attributesslot-attributesslot-snap-typeslot-snap-idslot-publisher-idon-classicon-core-desktopdevice scope absent: matchesabsent: matchesholdsabsent: matches slot-snap-typesnap type does not matchnot checkednot checkednot checkednot checkednot checked alternative 2: the same order, from the first constraintnone matches: not allowed snap type does not matchconnection not allowed by plug rule of interface "x"the reason is computed, then discarded: no error names the constraint snap type core matches the core and snapd snaps; a base snap matches no type listno snap-id: every *-snap-id constraint failsno model: device scope (on-store, on-brand, on-model) fails
The ten constraints of a plug-side connection alternative in checking order; absent ones match, the first failure at slot-snap-type ends the alternative, the next alternative is tried, and the failure reason is discarded before the error is built

Inside an alternative every constraint must hold, in a fixed order; absent ones match. Alternatives are tried in turn. The failing constraint's reason is computed and discarded, so errors do not say which one failed.

When a rule refuses the photo editor, you'll want to know which constraint failed. The error won't say. Here's why. A map of constraints is an and; a list of maps is an or. Each alternative is checked in a fixed order, and an absent constraint matches anything. The first constraint that fails ends that alternative, and the next one is tried. If none matches, the answer is not allowed. The helpers do return a reason, such as snap type does not match, but the policy package drops it. Also, snap type core matches the snapd snap too, and a snap without a snap-id fails every snap-id constraint.

07 A snap without a snap-id for app developers for snapd developers

MINIMAL CHECK the minimal checkno snap-id, so no snap-declarationplugsdeny-installation allow-installation of the base slot rule:keeps only alternatives that setslot-snap-type · on-classic · on-core-desktopand checks only those three constraintsother alternatives are skipped · none left: the slot passes network slot on an appslot-snap-type: [core]not allowedlxd slotallow-installation: falsesets none of the three: skippedinstalls snapd-control plugplugs are not checkedinstalls snap connect: ifacestate evaluates no connection rule when either snap has no snap-declarationauto-connect: the other side's store rule or the base; publisher constraints fail
For a local photo-editor build without a snap-id, the minimal check ignores plugs and deny-installation and keeps only allow-installation alternatives with snap type, on-classic or on-core-desktop; a network slot fails, an lxd slot and a snapd-control plug install; connection checks are skipped and auto-connect reads the other side's store rule or the base declaration, with no publisher to match

The minimal check: slots only, the base allow-installation only, only snap type, on-classic and on-core-desktop. No connection rule is evaluated for snap connect if either side lacks a snap-declaration.

Your local photo editor build, installed with --dangerous, has no snap-id and so no snap-declaration. A minimal check runs instead. It skips plugs and ignores deny-installation. From the base slot rule's allow-installation it keeps only alternatives that name a snap type, on-classic or on-core-desktop. So a network slot still fails, while an lxd slot passes, because allow-installation: false sets none of them. A snapd-control plug installs. Later, snap connect evaluates no rule when either side lacks a snap-declaration, and auto-connect reads the other side's store rule or the base declaration, with no publisher to match.

08 Where to go from here

ROADS How a rule is evaluated When snapd askswho asks, what happens next Interface policythe three questions Base declarationthe rules built into snapdSnap-declaration rulesper-snap rules from the store Implementationthe lookup order in code The home interfacein fullThe content interfacein full
Roads from rule evaluation: when snapd asks, the interface policy overview, the base declaration, snap-declaration rules, the implementation, the home interface and the content interface

Call sites next; the rules in the declaration decks; the lookup order in the implementation; home and content in their own decks.

You've followed the photo editor's camera, home and presets through the rules, one question at a time. Next, when snapd asks covers the call sites: who builds each candidate, and how an answer becomes a task error, or nothing at all. The overview returns to the three questions. The base declaration and snap-declaration decks hold the rules themselves and every constraint key. The implementation topic shows the lookup order inside the policy package, and the home and content decks cover those two interfaces in full.

Read more

The candidates

CandidateCarriesUsed for
install candidatethe snap, its snap-declaration, the base declaration, the model, the storeinstalling a snap that has a snap-id
minimal install candidatethe snap, the base declaration, the model, the storeinstalling a snap without a snap-id (--dangerous, snap try, unasserted --devmode)
connect candidatethe plug and the slot with their attributes, both snap-declarations, the base declaration, the model, the store, whether compatibility labels are onconnection and auto-connection

Lookup order

QuestionOrder; the first rule found is the only one read
installationfor each slot, then each plug: the snap's own snap-declaration rule on that side, the base rule on that side; with neither, allowed
connection, 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

Within the rule found, only the two sub-rules of the asked kind are read: the deny first, then the allow. A matching deny alternative gives "denied"; no matching allow alternative gives "not allowed". For auto-connection an allowed answer also returns the slots-per-plug of the allow alternative that matched.

Order of constraints in one alternative

Plug-side connection alternative: plug-names, slot-names, plug-attributes, slot-attributes, slot-snap-type, slot-snap-id, slot-publisher-id, on-classic, on-core-desktop, device scope. Absent constraints match. The first constraint that fails ends the alternative and the next one is tried. The failure reason is computed and then discarded, so no error names it.

InputMatching rule
snap type corematches the core snap and the snapd snap
a base snapmatches no snap type list
no snap-idfails every *-snap-id constraint
no snap-declarationfails every publisher constraint
no modelon-store, on-brand, on-model fail in an allow and do not apply in a deny
unset attributefails, except against $MISSING

Worked outcomes

Interface and caseConnectionAuto-connection
camera, any plugallowed (no connection sub-rules)denied (deny-auto-connection: true)
home, plug without read, classicallowedallowed
home, plug without read, Ubuntu Corealloweddenied (first alternative)
home, plug with read: alldenieddenied
content, same tag, same publisherallowedallowed, arity 1
content, same tag, other publisherallowednot allowed, no error
mir, app slotdenied (deny-connection: true)allowed (no auto-connection sub-rules)

The minimal check

  • Plugs are not checked, and deny-installation is ignored.
  • From the base slot rule's allow-installation only the alternatives that set slot-snap-type, on-classic or on-core-desktop are kept, and only those three constraints are checked. If none is left, the slot passes: allow-installation: false (as for lxd) sets none of them.
  • A network slot on an app fails; an lxd slot and a snapd-control plug install.
  • Afterwards snap connect evaluates no rule when either snap has no snap-declaration, and auto-connect reads the other snap's store rule or the base declaration with no publisher to match.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

POLICY · who may install and connect what