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

▶ Watch this deck — 8 scenes, ~6 min

01 Assembled from every interface at start for app developers for snapd developers

THE BASE DECLARATION acme-agent plugs: network · snapd-control network.go · slotsnetwork:allow-installation:slot-snap-type:- core snapd_control.go · plugssnapd-control:allow-installation: falsedeny-auto-connection: true... 222 interfaces joined at snapd startsorted by interface name the resulttype: base-declarationauthority-id: canonicalseries: 16revision: 0plugs:snapd-control: ...slots:network: ... compiled with the snap-declaration compilera malformed rule: snapd panics at start $ snap debug base-declarationthe store cannot add another: built-in primary key
Rule fragments from network.go and snapd_control.go are joined at snapd start into one built-in base-declaration assertion with plugs and slots sections; it is compiled at start, a malformed rule makes snapd panic, and snap debug base-declaration prints it

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

READING A RULE slots:network:allow-installation:slot-snap-type:- core denyallowdeny-installation:allow-installation:slot-snap-type: [core]deny-connection:allow-connection:deny-auto-connection:allow-auto-connection: falsedefaultfalsedefaulttruedefaultfalsedefaulttruedefault acme-agent's network plug installs, connects and auto-connects;only the system snap may carry the slot a whole rule may also be true or false; no base rule uses that form
network's slot rule states only allow-installation for slot-snap-type core; the other five sub-rules of installation, connection and auto-connection take defaults: allow true, deny false

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 system snap only[core]157network · home · camera an app or the system[app, core]22x11 · pulseaudio · network-manager an app only[app]15mir · dbus · cups system or gadget[core, gadget]12gpio · serial-port[gadget] 1: gpio-chardev no snap without a store rulefalse13lxd · custom-devicethe seven *-driver-libs special: content [app, gadget, kernel] · shared-memory [app, gadget, core]core matches the core snap and the snapd snap
Five bands sorting the 222 slot rules by who may carry the slot: system snap only 157, an app or the system 22, an app only 15, system or gadget 12 plus gpio-chardev gadget only, and false 13; content and shared-memory are special cases; core also matches the snapd snap

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

AUTO-CONNECTION deny-auto-connection: true · 194conditional 8 · absent 20 network-control:allow-installation:slot-snap-type:- coredeny-auto-connection: trueclassicsnap connectCoresnap connect x11:allow-installation:slot-snap-type:- app- coredeny-connection:on-classic: falsedeny-auto-connection:on-classic: false classicauto-connectsCoreapp slot: store rule needed network:allow-installation:slot-snap-type:- coreclassicauto-connectsCoreauto-connects deny-connection alone does not stop auto-connection: each kind reads only its own sub-rules(mir: see Implementation)
A bar splits the 222 slot rules into 194 with deny-auto-connection true, 8 conditional and 20 without it; three rules side by side, network-control, x11 and network, with their outcomes on classic and on Ubuntu Core

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

SUPER-PRIVILEGED plug rulesnapd-control:allow-installation: falsedeny-auto-connection: true51 plug rulesslot rulelxd:allow-installation: falsedeny-connection: truedeny-auto-connection: true13 slot rules acme-agent, no store ruleinstallation not allowed by "snapd-control" plug rule ... acme-agent with a store ruleinstalls; the store rule decides the rest --dangerousinstalls: plugs are not checked 50 of the 51 plug rules add deny-auto-connection: true; that sub-rule keeps them manual unity8: allow-installation: false only, and it auto-connects
The snapd-control plug rule and the lxd slot rule both say allow-installation false; a store snap plugging snapd-control without a store rule is not allowed to install, with a store rule it installs, and a dangerous install goes through; 50 of 51 such plug rules also deny auto-connection, unity8 does not

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

MIXED slots:docker:allow-installation:slot-snap-type:- app- coredeny-installation:slot-snap-type:- appdeny-connection:on-classic: falsedeny-auto-connection: true deny is checked first core or snapd snapdeny [app]: no matchallow [app, core]: matchinstalls acme-agent from the storedeny [app]: matchinstallation denied by "docker" slot rule ... with its own store rule for docker: installs same shape: desktop denies [app], shared-memory denies [app, gadget]
docker's slot rule allows app and core but denies app; a core or snapd snap passes the deny and matches the allow, so it installs; an app snap from the store matches the deny and its installation is denied unless its own store rule replaces the base rule

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

NEW INTERFACE const fooBaseDeclarationSlots = `foo:allow-installation:slot-snap-type:- coredeny-auto-connection: true` TestValiditya rule for every interfaceboth sides: list in bothSides TestSlotInstallationsnap types per slotdefault: core onlyTestPlugInstallationrestricted plugsallow-installation: falseTestAutoConnectionauto-connects or notautoconnect · snowflakes base plug ruleconnection and auto-connectionread the plug rule first base slot ruleread only for installation of the slot mount-control: slot deny-connection: true is not readsee Implementation65 interfaces have both rules; TestValidity calls this delicate
A new interface's base slot rule as a Go string constant, the four tests that guard base rules, and the shadowing rule: when a base plug rule exists it answers connection and auto-connection, and the base slot rule is read only for installing the slot

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 base declaration Interface policythe three questions Evaluationhow a base rule is evaluated Snap declarationwhat a store rule changes Interface classessuper-privileged and more For developersplugs and slots in snap.yamlImplementationthe policy package Interfacesthe overview
Roads from the base declaration: the policy overview, rule evaluation and store rules as main roads; Interfaces by classification, Interfaces for snap developers, the implementation topic and the interfaces overview as neighbours

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), then plugs: with every plug string and slots: 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

PartDefault when absent
allow-installation, allow-connection, allow-auto-connectiontrue
deny-installation, deny-connection, deny-auto-connectionfalse
a constraint inside an alternativematches anything
a whole rule written as true or falsepossible in the grammar; no base rule uses it

Who may carry the slot

Slot allow-installationRulesExamples
slot-snap-type: [core]157the implicit system slots, such as network, home, camera
slot-snap-type: [app, core]22x11, pulseaudio, network-manager, bluez, cups-control, docker, desktop
slot-snap-type: [app]15mir, dbus, cups, unity8, mpris
slot-snap-type: [core, gadget]12hardware: gpio, i2c, spi, serial-port, pwm, iio, hidraw
slot-snap-type: [gadget]1gpio-chardev
slot-snap-type: [app, gadget, kernel]1content
slot-snap-type: [app, gadget, core]1shared-memory
false13lxd, 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 ruleRulesExamples
deny-auto-connection: true194network-control, camera, removable-media
conditional deny-auto-connection8home, wayland, x11 (on-classic: false); screen-inhibit-control, upower-observe; browser-support, optical-drive, qualcomm-ipc-router (attributes)
no deny-auto-connection20network, 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 ruleRules
allow-installation: false and deny-auto-connection: true50, among them snapd-control, lxd-support, docker-support, kernel-module-control, mount-control, system-files, personal-files
allow-installation: false only1, unity8, which auto-connects
allow-installation: plug-snap-type: [core]8: the seven *-driver-libs and core-support
other shapesdesktop, 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.goWhat it pins
TestValidityevery interface has a rule; interfaces with both sides are listed in bothSides (seven stale entries pass, because only one direction is checked)
TestSlotInstallationthe snap types that may carry each slot; the default is core only
TestPlugInstallationthe restricted plugs
TestAutoConnectionwhich interfaces auto-connect (autoconnect) and the special cases (snowflakes)
TestConnection, TestConnectionOnClassic and othersconnection outcomes on classic and Ubuntu Core

Further reading

Roads from here

INTERFACES AND CONFINEMENT

POLICY · who may install and connect what