Snap-declaration rules

policy · store rules for app developers for snapd developers

A snap-declaration from the store may carry plugs and slots rules for one snap. A rule for an interface replaces the whole base rule for that snap's side and its unstated sub-rules default to allow. Constraints on attributes, names, snap types, ids, publishers, the device and arity narrow what each sub-rule matches.

On the map: policy

▶ Watch this deck — 8 scenes, ~6 min

01 A rule per interface, per snap for app developers for snapd developers

SNAP-DECLARATION type: snap-declarationseries: 16snap-id: <snap-id>snap-name: acme-agentpublisher-id: acmeformat: 1plugs:snapd-control:allow-installation: truedeny-auto-connection: trueillustrative; the rule grammar is the base declaration's plugs:rules for this snap's plugsconnection constraints name the slot side slots:rules for this snap's slotsconnection constraints name the plug side interface names are not checked: a rule for anunknown interface is accepted and never read format 1 to 7 by the features used; this snapd reads up to 7 and tells the store so
A snap-declaration excerpt with a plugs header holding a snapd-control rule, beside two panels: plugs rules govern the snap's plugs and constrain the slot side, slots rules govern its slots and constrain the plug side

plugs and slots headers keyed by interface, in the base declaration's grammar, for one snap. Plug rules constrain the slot side, slot rules the plug side. Formats 1 to 7 mark the features used; snapd tells the store the highest it reads.

The acme-agent needs snapd-control, and the base declaration says no. So Acme asks the store. A snap-declaration is the store's signed statement about one snap, and after review the store can add two optional headers to it: plugs and slots, keyed by interface name. Each entry is a rule in the base declaration's grammar, but for this snap only. A plugs rule governs the agent's plugs, so its connection constraints describe the slot side; a slots rule governs its slots and describes the plug side. Interface names aren't checked. The format number grows with the features a rule uses, up to seven in this snapd.

02 Replaced, not merged for app developers for snapd developers

REPLACED WHOLE base declaration, plug rulesnapd-control:allow-installation: falsedeny-auto-connection: trueinstall: noconnect: yesauto: denied store rule, in acme-agent's snap-declarationplugs:snapd-control:allow-installation: true base rule: not read for this snap allow-connection: true defaultallow-auto-connection: true defaultdeny-auto-connection: false defaultinstall: yesconnect: yesauto: yes the reverse: allow-auto-connection: true alone would also allow installation to keep a base limit, the store rule must restate it
The base snapd-control plug rule refuses installation and denies auto-connection; a store rule for acme-agent with only allow-installation true replaces it whole, its unstated sub-rules default to allow, so installation, connection and auto-connection are all allowed

One store key, allow-installation: true, also grants auto-connection: the base rule is not read, and unstated sub-rules default to allow. Restate any base limit you want to keep, such as deny-auto-connection: true.

Here's the trap in that request. The base plug rule for snapd-control refuses installation and denies auto-connection. Suppose the store grants the acme-agent a rule that says only allow-installation: true. That's now the whole rule for the agent's snapd-control plug, and the base rule isn't read. The sub-rules the store didn't state take their defaults: allow-connection: true, and deny-auto-connection: false. So that one line also lets the agent's plug connect itself. The reverse holds too: a grant of only allow-auto-connection would also let a snap install. To keep a base limit, the store rule has to restate it.

03 A grant with limits for app developers for snapd developers

CUSTOM-DEVICE slots:custom-device:allow-installation:slot-attributes:files: $MISSINGdevices:- /dev/video\[0-9\]slot-names:- custom-v4l-devallow-connection:plug-attributes:custom-device: $SLOT(custom-device)allow-auto-connection:slot-attributes: ...plug-attributes: ...plug-snap-id:- <device-app snap-id>store rule for device-app, from the spread test(written there as JSON for the fake store)base rule: allow-installation: false allow-installationslot named custom-v4l-devno files attributedevices: only /dev/video[0-9] allow-connectionrestated from the base rule:plug and slot name the same device allow-auto-connectiononly plugs of this snap-idthat name this device format 5: $MISSING (2), slot-names (4), a list in slot-attributes (5)
A custom-device slot rule from a spread test: allow-installation pins the slot name custom-v4l-dev, no files attribute and the video devices pattern; allow-connection restates the base rule; allow-auto-connection is limited to one snap-id; the features make it format 5

The store rule pins the slot's name and attributes, restates the base allow-connection, and allows auto-connection only for one snap-id. Its features put it at format 5.

A good grant is narrow, and Acme should expect one. A snapd spread test for an app that provides a custom-device slot shows one. The base rule refuses custom-device to every snap, so the store gives the app a slot rule. allow-installation holds only when the slot is named custom-v4l-dev, sets no files attribute, and lists only the video device pattern. allow-connection repeats the base rule, plug and slot naming the same device, because leaving it out would allow any plug. allow-auto-connection is limited to plugs from the app's own snap-id that name this device. Its features make it format five.

04 The attribute language for app developers for snapd developers

ATTRIBUTES plug-attributes, slot-attributes: a map; every listed key must match, other attributes are ignored read: allanchored regexp on the whole value; unset failswrite: /path1a?a list attribute: every element must match udev-file: $MISSINGthe attribute must be absent content: $SLOT(content)equal to the slot's content attributealso $PLUG(name), $SLOT_COMPAT(name), $PLUG_COMPAT(name) my-attr: $PLUG_PUBLISHER_IDequal to the plug snap's publisher-idand $SLOT_PUBLISHER_ID for the slot snap's - content: $SLOT(content)- compatibility: $SLOT_COMPAT(...)a list of maps: any one may match at installation there is no other side: $SLOT, $PLUG and publisher forms never match
Attribute constraint forms and their meanings: anchored regular expressions, $MISSING for absence, $SLOT and $PLUG to compare with the other side, publisher references, and lists of maps as alternatives; the comparing forms never match at installation

Values are anchored regexps; $MISSING requires absence; $SLOT(), $PLUG(), the _COMPAT forms and publisher references compare with the other side and never match at installation.

Most narrowing happens in attributes, so read them precisely. plug-attributes and slot-attributes hold a map: every key listed must match, and other attributes are ignored. A plain value is a regular expression matched against the whole value, and an attribute that isn't set fails. Against a list attribute, every element must match. $MISSING requires the attribute to be absent. $SLOT() and $PLUG() compare with the other side's attribute, and publisher references compare with that side's publisher. A list of maps gives alternatives. At installation there's no other side, so in allow-installation those comparisons refuse, and in deny-installation they don't deny.

05 Which keys each side uses for snapd developers for app developers

KEYS BY SIDE AND KIND plugs ruleslots rule installationconnection andauto-connection plug-names plug-attributesplug-snap-type plug-snap-idslot-names slot-attributesslot-snap-type slot-snap-id plug-names slot-namesplug-attributes slot-attributesplug-snap-type plug-snap-idplug-publisher-id slot-snap-typeslots-per-plug plugs-per-slotevery sub-rule: on-classic on-core-desktop on-store on-brand on-model plug-names slot-namesplug-attributes slot-attributesslot-snap-type slot-snap-idslot-publisher-idslots-per-plug plugs-per-slot plug-snap-type beside a known key in a plugs connection rule: ignored, no error arity keys: only in allow-connection and allow-auto-connection every key with its value forms: the catalogue scene
A grid of accepted constraint keys: installation sub-rules take the snap's own names, attributes, snap type and snap-id; connection sub-rules add the other side's snap type, snap-id and publisher and the arity keys; on-classic, on-core-desktop and device scope keys work everywhere; unknown keys are ignored

Installation keys describe the snap's own plug or slot; connection keys describe the other side. on-* keys work in every sub-rule. Keys outside their list are ignored; a connection sub-rule with no known key is rejected, an installation sub-rule is not, and then matches everything (a snapd bug). The catalogue lists every key.

Where may each constraint key go? That depends on side and kind, and the drawing lists every key. Here's the mistake that list prevents. The acme-agent's plugs rule describes the other side in its connection sub-rules, so it takes slot-snap-type. Put plug-snap-type beside it, meaning to restrict the agent itself, and snapd drops it without an error: a plugs connection sub-rule doesn't read that key. The rule loads and matches more than you meant. slots-per-plug and plugs-per-slot belong only in allow-connection and allow-auto-connection. So check rules against the catalogue below.

06 Rules for one store, brand or model for app developers for Ubuntu Core developers for snapd developers

DEVICE SCOPE snapd-control:allow-auto-connection:on-store:- acmea plug rule for acme-agent (illustrative) model store: acmeauto-connects model store: otherits friendly-stores list acmeauto-connectsmodel store: othernot allowed on-brand: the model's brand-id · on-model: brand-id/modelkeys present must all hold; each list gives alternatives · format 3 no model yeta scoped allow does not match; a scoped deny does not apply
A plug rule for acme-agent with on-store acme auto-connects on a device whose model names the acme store or whose store lists acme as a friendly store, is not allowed on another store's device, and without a model a scoped allow fails and a scoped deny does not apply

on-store, on-brand and on-model are checked against the device's model and its store's friendly-stores. Without a model a scoped allow fails and a scoped deny does not apply.

Acme's grant should hold on Acme's gateways, not wherever the agent gets copied. The device scope keys do that. on-store matches when the device's model names a listed store, or when the store assertion for the model's store lists it among its friendly stores. on-brand compares the model's brand, and on-model compares brand slash model. When several keys are present they must all hold, and each list gives alternatives. So a rule scoped to Acme's store auto-connects on the gateway and isn't allowed elsewhere. And without a model, an allow with device scope doesn't match, while a deny with device scope doesn't apply.

07 One slot per plug, unless the rule says * for app developers for snapd developers

ARITY slots-arity-plug-any:allow-auto-connection:slots-per-plug: *a plug rule from the policy tests written in allow-auto-connection, and what it means*any1one2one: 2 means 1absentone in allow-connection: always any plugs-per-slot: parsed, always any, no effect two snap-declarations disagreeacme-agent plug * slot 1anyacme-agent plug 1 slot *onethe plug snap's declaration is read first what one means for candidate selection: when snapd asks
slots-per-plug star in allow-auto-connection means any number of slots; 1, 2 or no value mean one; allow-connection and plugs-per-slot are always any; when plug and slot snap-declarations disagree the plug side wins

In allow-auto-connection, slots-per-plug: * means any and every other value means 1. plugs-per-slot has no effect. The plug snap's rule is read before the slot snap's.

How many slots may one plug auto-connect to? slots-per-plug is accepted only in allow-connection and allow-auto-connection. In allow-connection it always means any. In allow-auto-connection, a star means any number of slots, and every other value, two included, means one. plugs-per-slot is parsed and has no effect. The value comes from the rule in force, and the plug snap's declaration is read before the slot snap's. So when the agent's plug rule says star and a provider's slot rule says one, the answer is any; swapped, it's one. When snapd asks shows what one means with several candidates.

08 Where to go from here

ROADS Snap-declaration rules Evaluationhow the rule in force matches When snapd askswhen a new rule takes effect Base declarationthe rules a store rule replacesInterface policythe three questions elsewhere on the mapSnaps and validationthe assertion itselfAssertionsfetched and trusted Model, gadget, kernelbrands and modelsA store of your owna brand's storeevery key with its value forms: the catalogue below this deck
Roads from snap-declaration rules: evaluation, when snapd asks, the base declaration and the policy overview, and in other districts snaps and validation, assertions, the model and a store of your own

Roads: evaluation, when snapd asks, the base declaration and the overview; the snap-declaration assertion, how assertions are trusted, models and brand stores.

The acme-agent got its grant: narrow, restated, and scoped to Acme's store. Where next? Evaluation shows how the rule in force is found and matched for each question. When snapd asks covers when a new snap-declaration takes effect, and what auto-connect does with one slot per plug. The base declaration deck shows the rules a store rule replaces, and the policy overview returns to the three questions. In the assertions district, snaps and validation covers the snap-declaration itself, and the overview how snapd fetches and trusts it. The model deck and a store of your own cover the models and stores behind device scope.

Read more

Every rule key and constraint key, with its value forms, is in the catalogue below this deck. This page adds where each key is accepted, how values match, and the formats.

Where constraint keys are accepted

Sub-ruleIn a plugs ruleIn a slots rule
allow-installation, deny-installationplug-names, plug-attributes, plug-snap-type, plug-snap-idslot-names, slot-attributes, slot-snap-type, slot-snap-id
allow-connection, allow-auto-connectionplug-names, slot-names, plug-attributes, slot-attributes, slot-snap-type, slot-snap-id, slot-publisher-id, slots-per-plug, plugs-per-slotplug-names, slot-names, plug-attributes, slot-attributes, slot-snap-type, plug-snap-type, plug-snap-id, plug-publisher-id, slots-per-plug, plugs-per-slot
deny-connection, deny-auto-connectionas the allow forms, without the arity keysas the allow forms, without the arity keys
every sub-ruleon-classic, on-core-desktop, on-store, on-brand, on-modelthe same

A key outside its list is ignored when a known key sits beside it. A connection sub-rule with no known key is rejected. An installation sub-rule with no known key compiles and matches every snap: in deny-installation it denies every installation. That is a snapd bug (asserts/ifacedecls.go:520 compares against the wrong list).

How a rule is replaced

  • A rule in the snap-declaration for an interface replaces the base rule for that interface on that side, for that snap. Nothing is merged.
  • Sub-rules it does not state take the defaults: absent allow-* is true, absent deny-* is false. A grant of only allow-installation: true for snapd-control also allows auto-connection; a grant of only allow-auto-connection: true also allows installation.
  • For connection questions the plug snap's rule is read before the slot snap's, and either is read before any base rule.

How attribute values match

ValueMatches when
a stringthe attribute is set and the whole value matches it as a regular expression
a string, against a list attributeevery element matches
a mapeach listed key matches; attributes not listed are ignored
a list of mapsany one map matches
$MISSINGthe attribute is not set
$SLOT(name), $PLUG(name)the value equals the other side's attribute; fails at installation
$SLOT_COMPAT(name), $PLUG_COMPAT(name)the compatibility labels are compatible; only when the content compatibility feature is on; fails at installation
$PLUG_PUBLISHER_ID, $SLOT_PUBLISHER_IDthe value equals that side's publisher; a snap without a snap-declaration has none; fails at installation

At installation a failing comparison means: an allow-installation alternative does not match, and a deny-installation alternative does not deny.

Device scope

KeyHolds when
on-storethe model's store is listed, or the store assertion of the model's store lists a listed store in friendly-stores
on-brandthe model's brand-id is listed
on-model<brand-id>/<model> is listed

Keys present together must all hold; each list gives alternatives. Without a model, an allow with device scope does not match and a deny with device scope does not apply.

Arity

Whereslots-per-plugplugs-per-slot
allow-auto-connection* means any number; every other value, also 2, means oneparsed, no effect
allow-connectionalways anyparsed, no effect

The value comes from the rule in force; the plug snap's rule is read first.

Formats

FormatFirst feature that needs it
1plugs or slots present
2$SLOT(), $PLUG() and $MISSING in attribute constraints
3on-store, on-brand, on-model
4plug-names, slot-names
5alternatives inside attribute constraints
6$PLUG_PUBLISHER_ID or $SLOT_PUBLISHER_ID inside plug-attributes or slot-attributes; the plug-publisher-id and slot-publisher-id keys need no higher format
7on-classic with a distro/variant entry, such as ubuntu/server or ubuntu/*; a plain distro list does not need it

This snapd reads formats up to 7 and tells the store so. Interface names in the headers are not checked.

Further reading

  • snap-declaration: every header of the assertion and the six rule keys. It covers only allow-* keys, and says that granting allow-auto-connection is often all that is needed; a store rule replaces the whole base rule, so any base constraint it omits is lost.
  • Store scoping: on-store for a dedicated store, with before and after examples. Its examples keep format: 1; snapd computes format 3 for a rule with on-store (asserts/snap_asserts.go:191-193).
  • Process for aliases, auto-connections and tracks: how a publisher requests a rule and what reviewers consider.
  • Interface auto-connection: the order in which snap and built-in rules are consulted.

Roads from here

GETTING SNAPS

ASSERTIONS · signed statements snapd trusts

POLICY · who may install and connect what

UBUNTU CORE · install and recovery