A device set up before anyone logs in
purpose for Ubuntu Core developers for administrators
A device leaves the factory with nobody to type snap set or snap connect. The gadget snap carries two lists for that moment. Defaults give snaps their first option values and connections join plugs and slots that the policy would leave for a person to connect. Both name snaps by snap id and both are applied once and later changes to the gadget do not replay them.
On the map: ubuntu core install and recovery
01 A thousand gateways, nobody at the keyboard
A gadget carries defaults, the first option values for snaps, and connections, interface connections to make. Both identify snaps by snap id. The acme snaps are invented for this deck. The model deck shows the reference pc gadget; a brand that presets values ships its own.
Setting up the gateway on your desk takes two commands. Snap set tells acme-agent where its telemetry server is. Snap connect joins acme-vpn's network-control plug, which doesn't connect by itself. Now there are a thousand gateways, booting for the first time in a cabinet, with nobody logged in. Who types? Nobody. The answers travel with the device, in its gadget snap: default configuration options for snaps as they're installed, and interface connections. This deck calls the pair presets. Both lists name snaps by snap-id, so a preset reaches the snap the store gave that id, not just anything with the same name.
02 First values arrive through the snap's own hook
Defaults reach a snap through its configure or default-configure hook at installation. A snap with defaults and no configure hook gets none of them, with no message (a snapd bug). system: defaults set the device's own options.
The gadget says acme-agent's server is telemetry.example. How does that become a setting of a snap that's a read-only file? When the snap is installed, snapd proposes the values to its configure hook, as if you'd typed snap set. The hook checks them, and only then are they stored. If the snap also has a default-configure hook, that one gets them instead. With no configure hook it gets nothing, silently: a known bug. The gadget can also preset the device's own options, under the name system. Snapd applies those itself, with no hook. Afterwards, snap get shows a preset value like any other.
03 Connections nobody typed
connections in the gadget connects plugs and slots during seeding, including ones the policy does not connect automatically. snap connections marks them gadget.
acme-vpn has to reconfigure networking, and its network-control plug is one the policy doesn't connect by itself. Somebody with authority over the machine is meant to say yes. On your desk, that's you, with snap connect. On an unattended first boot, there's no you. So who says yes? The gadget's connections list is written in advance, in the brand's gadget for its own device. Each entry names a plug by snap-id, and a slot; leave the slot out, and it means the system's slot of the same name. Snapd makes these connections while the device is seeded, and snap connections marks each one with the note gadget.
04 What the gadget cannot grant
Gadget connections are judged by the connection rules, not the auto-connection rules. A refusal fails seeding; a missing plug or slot is logged and skipped.
This sounds like a gadget could grant any permission it likes. It isn't. Snapd asks two things about a connection: may it be made automatically, and may it be made at all? For a gadget connection, only the first is skipped, so a denied auto-connection can still be made. The connection rules of the declarations still apply, as they do for snap connect. If they refuse, the connect task fails, and the first boot fails with it. Test the image. A missing plug or slot is only logged and skipped. The docs add a store rule: a store-deployed gadget comes from the device's brand, or is a reference gadget.
05 Applied once
Defaults apply at a snap's first install; connections apply during seeding and remodel. Refreshing the gadget does not apply either again. The gadget reference says defaults apply only at first boot; the code uses them at any first install of a snap.
Six months on, the telemetry server moves. You change it in the gadget and release it. What changes on the gateways in the field? Nothing. A preset is a first value, not a rule kept in force. The docs say gadget connections are made on first boot, not on a gadget refresh. Defaults are used at a snap's first install. When acme-agent refreshes, its configure hook runs with nothing proposed, so a setting changed in the field stays changed. Two fine points from the code: a snap first installed later still gets its defaults, and a remodel applies the new gadget's connections to the snaps it installs or refreshes.
06 When a preset is the wrong tool
Use gadget presets for first values and connections common to a model. Use snap set for what changes later. Snaps without a snap id are not affected by either list.
Presets are a narrow tool, so it helps to know where they stop. They suit what's the same on every device of a model and known at the factory. A value that changes after shipping needs something that reaches a running device: snap set, or confdb, which is experimental. A value that differs from one device to the next doesn't belong in a gadget, because every device of the model carries the same one. Set it on the device. A snap you built locally has no snap-id, so it takes no part in either list. And a plug that auto-connects anyway needs no entry.
07 Where to go from here
Defaults are explained in the configuration deck; gadget connections in "When snapd asks"; first boot in the seed deck.
Two lists in the gadget, keyed by snap-id and used once, still checked by the snap's hook and by the connection rules. Each piece has a deck that shows the mechanism. The model deck covers the gadget and who signs for the device. The configuration deck shows defaults as a snap's first option values. The snapctl configuration deck and the hooks deck show the hooks that receive them. When snapd asks covers how a gadget connection is judged. The seed deck walks through the first boot that applies it all. And confdb is for settings that keep changing.
Read more
The two lists
defaults | connections | |
|---|---|---|
| Holds | option values per snap | plug and slot pairs |
| Snaps named by | snap id; system for the device's own options | snap id; system for the system snap |
| Applied | at the first install of that snap | while the device is seeded and during a remodel |
| Applied through | the snap's default-configure or configure hook | a connect task marked as made by the gadget |
| Checked by | the snap's hook | the connection rules of the declarations |
| If refused | the snap's install fails | the connect task fails and with it seeding or the remodel |
| If the target is missing | no defaults for a snap that is not installed | logged and skipped |
| On a gadget refresh | not applied again | not applied again |
| Seen afterwards with | snap get <snap> | snap connections <snap> with the note gadget |
What to expect when
| Event | defaults | connections |
|---|---|---|
| first boot | applied to each seeded snap that has an entry | applied |
| refresh of a snap | not applied; the configure hook runs with nothing proposed | not applied |
| refresh of the gadget | not applied | not applied |
| first install of a snap after first boot | applied for that snap | not applied |
| remodel | as for any first install | applied from the new gadget to the snaps the remodel installs or refreshes |
| a snap with no snap id | none | takes no part |
The published gadget reference says defaults are applied only during the first boot. In the code read, a snap's defaults are used at its first install whenever that happens. system defaults are applied only during seeding.
Messages
| Message | Meaning |
|---|---|
cannot apply gadget config defaults for snap "<snap>", no configure hook | meant for defaults that a snap cannot receive; not reached in practice, the defaults are dropped silently (snapd bug) |
gadget connections: ignoring missing plug <id>:<plug> | logged in the task; the connection is skipped |
gadget connections: ignoring missing slot <id>:<slot> | the same for a slot |
for Ubuntu Core developers
The form in gadget.yaml
defaults:
<snap id>:
<key>: <value>
system:
<key>: <value>
connections:
- plug: <plug snap id>:<plug>
slot: <slot snap id>:<slot>
Leaving out slot means the system's slot with the same name as the plug.
Further reading
- Gadget snap format:
defaultsandconnectionsin gadget.yaml and when they apply - Model assertion: the snaps of a device and their ids
- Set system options: the options a
system:default can set - Configure snaps:
snap setandsnap getfor what changes after the factory
Roads from here
RUNNING SNAPS
- Configuration — defaults as the first values of a snap's configuration
- Confdb: configuration that does not belong to one snap — configuration that keeps changing after the factory
SNAPCTL · the snap's API into snapd
- "snapctl: configuration and health" — how the configure hook receives gadget defaults
HOOKS · code snapd runs inside a snap
- Hooks: install, configure, refresh, remove — where configure and default-configure run in a first install
POLICY · who may install and connect what
- When snapd asks — how gadget connections are judged
UBUNTU CORE · install and recovery
- Model, gadget and kernel — the gadget snap and who signs for the device
- ubuntu-seed and first boot — the seeding change that applies all of this