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
01 A rule per interface, per snap for app developers for snapd developers
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
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
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
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
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
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
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: 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-rule | In a plugs rule | In a slots rule |
|---|---|---|
allow-installation, deny-installation | plug-names, plug-attributes, plug-snap-type, plug-snap-id | slot-names, slot-attributes, slot-snap-type, slot-snap-id |
allow-connection, allow-auto-connection | plug-names, slot-names, plug-attributes, slot-attributes, slot-snap-type, slot-snap-id, slot-publisher-id, slots-per-plug, plugs-per-slot | plug-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-connection | as the allow forms, without the arity keys | as the allow forms, without the arity keys |
| every sub-rule | on-classic, on-core-desktop, on-store, on-brand, on-model | the 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, absentdeny-*is false. A grant of onlyallow-installation: trueforsnapd-controlalso allows auto-connection; a grant of onlyallow-auto-connection: truealso 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
| Value | Matches when |
|---|---|
| a string | the attribute is set and the whole value matches it as a regular expression |
| a string, against a list attribute | every element matches |
| a map | each listed key matches; attributes not listed are ignored |
| a list of maps | any one map matches |
$MISSING | the 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_ID | the 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
| Key | Holds when |
|---|---|
on-store | the model's store is listed, or the store assertion of the model's store lists a listed store in friendly-stores |
on-brand | the 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
| Where | slots-per-plug | plugs-per-slot |
|---|---|---|
allow-auto-connection | * means any number; every other value, also 2, means one | parsed, no effect |
allow-connection | always any | parsed, no effect |
The value comes from the rule in force; the plug snap's rule is read first.
Formats
| Format | First feature that needs it |
|---|---|
| 1 | plugs or slots present |
| 2 | $SLOT(), $PLUG() and $MISSING in attribute constraints |
| 3 | on-store, on-brand, on-model |
| 4 | plug-names, slot-names |
| 5 | alternatives 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 |
| 7 | on-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 grantingallow-auto-connectionis often all that is needed; a store rule replaces the whole base rule, so any base constraint it omits is lost. - Store scoping:
on-storefor a dedicated store, with before and after examples. Its examples keepformat: 1; snapd computes format 3 for a rule withon-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
- A store of your own — a dedicated store that grants rules for its own devices
ASSERTIONS · signed statements snapd trusts
- Assertions: snaps and validation — the snap-declaration assertion itself
- Assertions: how they work — how snapd fetches and trusts assertions
POLICY · who may install and connect what
- Interface policy: the questions snapd asks — back to the three questions
- The base declaration — the base rules a store rule replaces
- How a rule is evaluated — how the rule in force is found and matched
- When snapd asks — when a new snap-declaration takes effect
UBUNTU CORE · install and recovery
- Model, gadget and kernel — brand and model and store behind on-brand and on-store