The base declaration
policy · built-in rules for app developers for snapd developers
The base declaration is the set of default interface rules built into snapd. Each interface contributes a slot rule and sometimes a plug rule; snapd joins them at start. Most slots may be carried only by the system snap and connect by hand; a few auto-connect; super-privileged plugs and slots do not install from the store without a store rule.
On the map: policy
01 Assembled from every interface at start for app developers for snapd developers
Every interface supplies a plug rule string, a slot rule string, or both; snapd joins them under plugs: and slots: at start and compiles the result, or panics. The store cannot replace it; only a new snapd changes it.
The acme-agent on the gateway plugs network and snapd-control. Where do their default rules live? Not in a file. Each interface in snapd carries two optional strings, one with its plug rule and one with its slot rule. Network has only a slot rule; snapd-control has a plug rule too. When snapd starts, it writes a header, then plugs and every plug string, then slots and every slot string, and compiles the result into a built-in assertion with the same code that reads a snap-declaration. A rule that doesn't compile makes snapd panic at start, so unit tests catch it. snap debug base-declaration prints it.
02 Reading a rule: six sub-rules, two defaults for app developers for snapd developers
Six sub-rules; an absent allow-* is true, an absent deny-* is false. network states only allow-installation: slot-snap-type: [core], so the agent's network plug auto-connects.
Let's read network's slot rule and see what it says about the acme-agent. A rule can have six sub-rules: allow and deny, each for installation, connection and auto-connection. Network's rule states just one: allow-installation, when the slot's snap type is core. The other five take defaults. A missing allow counts as true, and a missing deny as false. So the agent's network plug installs, connects and auto-connects, while only the system snap may carry the network slot. A sub-rule that isn't written doesn't deny anything. A whole rule could also be a plain true or false, but no base rule uses that form.
03 Who may carry the slot
Slot allow-installation sorts the interfaces: 157 system only, 22 app or system, 15 app only, 12 system or gadget, 13 false. core matches the core and snapd snaps.
Now suppose the acme-agent wants to offer a slot of its own. Could it? Every one of the two hundred and twenty two slot rules answers that first. A hundred and fifty seven allow only the system snap; that's where implicit slots like network and home live. Twenty two also allow an app, for services like x11 or pulseaudio that can come from the host or from a snap. Fifteen allow only apps, like mir. Twelve hardware slots allow the system or the gadget. And thirteen say false, so no snap carries that slot without a store rule. One detail: core here also matches the snapd snap.
04 Manual unless the rule says otherwise for app developers for snapd developers
194 slot rules say deny-auto-connection: true; 8 are conditional, such as x11's on-classic: false; 20 do not deny it. Each question reads only its own sub-rules.
The acme-agent also plugs network-control, and after install it sits unconnected. That's the common case. A hundred and ninety four slot rules say deny-auto-connection: true, network-control among them, so you connect by hand. Eight deny it only under a condition. x11 denies connection and auto-connection with on-classic: false, which matches on Ubuntu Core: on a laptop an app's x11 plug connects itself to the system slot, while on the gateway an app's x11 slot needs a store rule. Twenty, network's included, have no such sub-rule. And a deny-connection alone doesn't stop auto-connection: each question reads only its own sub-rules.
05 Super-privileged plugs and slots for app developers for snapd developers
allow-installation: false on 51 plug rules and 13 slot rules: no store install without a store rule. Staying manual comes from the accompanying deny-auto-connection: true; unity8 lacks it.
Then there's the agent's snapd-control plug. Uploaded as it is, the acme-agent won't install. Fifty one plug rules and thirteen slot rules say allow-installation: false, which makes an interface super-privileged. A store snap with such a plug fails with installation not allowed. If the agent's snap-declaration has a rule for snapd-control, that rule decides instead. A development build installed with --dangerous goes through, because the reduced check for snaps without a snap-id reads no plug rules. Fifty of those plug rules also say deny-auto-connection: true, which keeps them manual. unity8 lacks that line, and it does auto-connect.
06 The system may, an app may not for app developers for snapd developers
docker allows app and core but denies app. Deny is checked first: the system snap may carry the slot, an app needs a store rule. desktop and shared-memory follow the same shape.
Three slot rules allow something and then deny part of it. Docker is one. Its slot rule allows snap types app and core, then denies app. Deny is checked first. A core or snapd snap doesn't match the deny, does match the allow, and may carry the slot. Now picture the acme-agent shipping a docker slot. It's an app, so it matches the deny and installation is denied. The error says denied rather than not allowed, because a deny matched. The agent could install only if its own snap-declaration had a rule that replaces this one. Desktop and shared-memory use the same shape.
07 Writing the rules for a new interface for snapd developers
Base rules are string constants checked by TestValidity, TestSlotInstallation, TestPlugInstallation, TestAutoConnection and the connection tests. A base plug rule shadows the base slot rule for connection and auto-connection.
Say you're adding an interface to snapd. Its rules are Go string constants, and the tests in basedeclaration_test.go hold you to them. TestValidity wants a rule for every interface. TestSlotInstallation pins which snap types may carry each slot, TestPlugInstallation the restricted plugs, and TestAutoConnection which interfaces connect by themselves. Write a plug rule only when the plug itself needs limits. Once a base plug rule exists, it answers every connection question, and the slot rule is read only when a slot is installed. mount-control's slot rule says deny-connection: true, and it's never read.
08 Where to go from here
Roads: the policy overview, evaluation and store rules; interface classes, plugs and slots in snap.yaml, the implementation and the interfaces overview.
So the acme-agent's network plug connects itself, network-control waits for you, and snapd-control needs the store. The policy overview leads back to the three questions. The evaluation deck shows how one base rule is found and checked, step by step. The snap-declaration deck shows what a store rule changes on top of these defaults, and why it has to restate them. Interfaces by classification uses the super-privileged label across the whole map. Interfaces for snap developers covers declaring plugs and slots in snap.yaml, the implementation topic the policy package that reads these rules, and another road leads back to the interfaces overview.
Read more
How it is built
- Each interface may supply a plug rule string and a slot rule string. All 222 interfaces supply a slot rule; 65 also supply a plug rule.
- At start snapd writes a header (
type: base-declaration,authority-id: canonical,series: 16,revision: 0), thenplugs:with every plug string andslots:with every slot string, sorted by interface name, and compiles the result as a built-in assertion. A rule that does not compile makes snapd panic at start. - The store cannot add another base declaration: its primary key clashes with the predefined one. It changes only with the snapd version.
snap debug base-declaration(a hidden debug command) prints it.
Defaults for absent parts
| Part | Default when absent |
|---|---|
allow-installation, allow-connection, allow-auto-connection | true |
deny-installation, deny-connection, deny-auto-connection | false |
| a constraint inside an alternative | matches anything |
a whole rule written as true or false | possible in the grammar; no base rule uses it |
Who may carry the slot
Slot allow-installation | Rules | Examples |
|---|---|---|
slot-snap-type: [core] | 157 | the implicit system slots, such as network, home, camera |
slot-snap-type: [app, core] | 22 | x11, pulseaudio, network-manager, bluez, cups-control, docker, desktop |
slot-snap-type: [app] | 15 | mir, dbus, cups, unity8, mpris |
slot-snap-type: [core, gadget] | 12 | hardware: gpio, i2c, spi, serial-port, pwm, iio, hidraw |
slot-snap-type: [gadget] | 1 | gpio-chardev |
slot-snap-type: [app, gadget, kernel] | 1 | content |
slot-snap-type: [app, gadget, core] | 1 | shared-memory |
false | 13 | lxd, custom-device, pkcs11, posix-mq, microceph, microovn and the seven *-driver-libs |
core matches both the core snap and the snapd snap. A base snap matches no type list. desktop and docker also deny [app], and shared-memory denies [app, gadget], so only the system snap carries those slots without a store rule. udisks2 also requires udev-file: $MISSING on an app's slot.
Auto-connection in slot rules
| Slot rule | Rules | Examples |
|---|---|---|
deny-auto-connection: true | 194 | network-control, camera, removable-media |
conditional deny-auto-connection | 8 | home, wayland, x11 (on-classic: false); screen-inhibit-control, upower-observe; browser-support, optical-drive, qualcomm-ipc-router (attributes) |
no deny-auto-connection | 20 | network, network-bind, opengl, content, confdb, desktop, mir, unity7 |
Each question reads only its own sub-rules: a slot rule with deny-connection: true and no deny-auto-connection, such as mir, still allows auto-connection.
Plug rules
| Plug rule | Rules |
|---|---|
allow-installation: false and deny-auto-connection: true | 50, among them snapd-control, lxd-support, docker-support, kernel-module-control, mount-control, system-files, personal-files |
allow-installation: false only | 1, unity8, which auto-connects |
allow-installation: plug-snap-type: [core] | 8: the seven *-driver-libs and core-support |
| other shapes | desktop, usb-gadget (top-level name, where, persistent must be absent; the interface reads them inside ffs-mounts, so the rule constrains nothing: a snapd bug, findings/review/BUGS.md #2), mediatek-accel, publisher-matched confdb, posix-mq, shared-memory |
When a base plug rule exists, it answers connection and auto-connection, and the base slot rule is read only to install the slot. The slot deny-connection: true of mount-control, kernel-module-load and unity8 is therefore not read.
for snapd developers
Tests that guard base rules
Test in interfaces/policy/basedeclaration_test.go | What it pins |
|---|---|
TestValidity | every interface has a rule; interfaces with both sides are listed in bothSides (seven stale entries pass, because only one direction is checked) |
TestSlotInstallation | the snap types that may carry each slot; the default is core only |
TestPlugInstallation | the restricted plugs |
TestAutoConnection | which interfaces auto-connect (autoconnect) and the special cases (snowflakes) |
TestConnection, TestConnectionOnClassic and others | connection outcomes on classic and Ubuntu Core |
Further reading
- Super-privileged interfaces: the plugs that need store approval, as the docs list them.
- Interface auto-connection: why some interfaces connect by themselves and how built-in and store rules are ordered.
- All about interfaces: plugs, slots and implicit system slots.
- snap-declaration: quotes base declaration rules such as
snapd-controlandcontentwhile explaining store rules.
Roads from here
INTERFACES AND CONFINEMENT
- Interfaces by classification — super-privileged and the other classes across the map
- Interfaces for snap developers — declaring plugs and slots in snap yaml
- How interfaces are implemented — lookup order and the policy package
- Interfaces — back to the interfaces overview
POLICY · who may install and connect what
- Interface policy: the questions snapd asks — back to the three questions
- How a rule is evaluated — how a base rule is looked up and evaluated
- Snap-declaration rules — what a store rule changes on top of these