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

▶ Watch this deck — 7 scenes, ~5 min

01 A thousand gateways, nobody at the keyboard

DEVICE PRESETS $ snap set acme-agent server=https://telemetry.example$ snap connect acme-vpn:network-controlfine for the gateway on your desk × 1000first boot, in a cabinet, nobody logged in acme-gadgetdefaultsconnections the same two decisions,written down in advance by snap idby snap ida snap id is assigned by the store, so a preset does not reacha snap that only has the same name acme-agent and acme-vpn are invented for this deck
On the left, a terminal with snap set acme-agent server=https://telemetry.example and snap connect acme-vpn:network-control, fine for one gateway on a desk; below it a grid of a thousand gateways booting with no terminal. On the right the acme-gadget with two cards, defaults and connections, each fed by one of the two commands and each naming snaps by snap id

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 gadget.yamldefaults:<acme-agent's snap id>:server: https://telemetry.exampleinterval: 60 snapdacme-agent, first installconfigure hookproposed,like snap set exit 0stored optionsserver, interval no configure hook: dropped silently (a bug)default-configure, if present, gets them system:service.ssh.disable: truethe device's own options: snapd applies them, no hook $ snap get acme-agent serverhttps://telemetry.examplewhat you can check on any gateway
gadget.yaml lists defaults for acme-agent's snap id: server https://telemetry.example and interval 60. snapd proposes them to acme-agent's configure hook at first install, like snap set; the hook exits 0 and the options are stored. Without a configure hook the defaults are dropped silently, a known snapd bug. A system entry, service.ssh.disable true, goes to snapd itself with no hook. snap get acme-agent server prints the value

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 acme-vpnnetwork-control:network-controlauto-connection: denied by the base declaration $ snap connect acme-vpn:network-controlfirst boot: nobody is there to type it gadget.yamlconnections:- plug: <acme-vpn's snap id>:network-control no slot given: the system'sslot of the same name network-controlconnected during seeding$ snap connections acme-vpnInterface Plug Slot Notesnetwork-control acme-vpn:network-control :network-control gadget
acme-vpn's network-control plug and the system's network-control slot, unconnected because the base declaration denies auto-connection. snap connect acme-vpn:network-control is struck out: nobody is there to type it. gadget.yaml lists connections with a plug for acme-vpn's snap id and no slot, meaning the system slot of the same name. The plug is connected during seeding, and snap connections acme-vpn shows the connection with the note gadget

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

LIMITS OF A PRESET may it connect automatically?may it connect at all? acme-vpn:network-controlskipped for gadget connections connection rules of the declarationsallowed: connected some-plug → some-slotrefused: the connect task fails,and seeding with it <id>:missing-plugnot theregadget connections: ignoringmissing plug <id>:missing-pluglogged and skipped; the boot goes on the docs: for store deployment the gadget comes from the brand, or is a reference gadget
Two gates for a connection. Gate one, may this connect automatically, is not asked for gadget connections. Gate two, may this connect at all, applies the connection rules of the declarations. The network-control entry passes and is connected. A second entry is refused at gate two: the connect task fails and seeding with it. A third entry names a missing plug: it is logged as gadget connections: ignoring missing plug, and skipped. Footer: the docs say that for store deployment the gadget comes from the brand or is a reference gadget

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

ONCE defaultsconnectionsfirst boot(seeding)acme-agentrefreshesgadgetrefreshesa snap installedlaterremodel✓✓ ––a new value in the gadgetdoes not reach the field ––a refresh runs the configure hook with nothing proposed: a value changed in the field stays changed ✓–its own defaults,at its first install as any firstinstall✓from thenew gadget the gadget reference says defaults apply only at first boot; the code uses them at any first install of a snap
A timeline of the gateway's life with five stops and two rows, defaults and connections. First boot: both applied. acme-agent refreshes: neither, its configure hook runs with nothing proposed. The gadget refreshes with a changed list: neither, a new value does not reach devices in the field. A snap installed later for the first time: its own defaults, no connections. Remodel: connections from the new gadget, defaults as for any first install

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

WHEN NOT the same first value on every device of a modelgadget defaults a value that changes after shipping$ snap set acme-agent server=...or confdb, which is experimental a value that differs per devicenot in the gadget: one per modelset it on the device a snap built locally, with no snap idtakes no part: no defaults,no gadget connections a plug that already connects by itselfneeds no entry
Five needs and the tool for each. The same first value on every device of the model: gadget defaults. A value that changes after shipping: snap set, or the experimental confdb. A value that differs per device: not in the gadget, set it on the device. A snap built locally with no snap id: takes no part, no defaults and no gadget connections. A plug that already connects by itself: needs no entry

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

ROADS device presetsdefaultsconnections Model, gadget and kernelthe gadget and who signs for it Configurationdefaults as first option values snapctl config · Hooksthe hooks that receive them When snapd askshow a gadget connection is judged ubuntu-seed and first bootthe first boot that applies it all Confdbsettings that keep changing
Roads from device presets: the model, gadget and kernel deck; configuration; snapctl configuration and the hooks deck; when snapd asks; ubuntu-seed and first boot; and confdb

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

defaultsconnections
Holdsoption values per snapplug and slot pairs
Snaps named bysnap id; system for the device's own optionssnap id; system for the system snap
Appliedat the first install of that snapwhile the device is seeded and during a remodel
Applied throughthe snap's default-configure or configure hooka connect task marked as made by the gadget
Checked bythe snap's hookthe connection rules of the declarations
If refusedthe snap's install failsthe connect task fails and with it seeding or the remodel
If the target is missingno defaults for a snap that is not installedlogged and skipped
On a gadget refreshnot applied againnot applied again
Seen afterwards withsnap get <snap>snap connections <snap> with the note gadget

What to expect when

Eventdefaultsconnections
first bootapplied to each seeded snap that has an entryapplied
refresh of a snapnot applied; the configure hook runs with nothing proposednot applied
refresh of the gadgetnot appliednot applied
first install of a snap after first bootapplied for that snapnot applied
remodelas for any first installapplied from the new gadget to the snaps the remodel installs or refreshes
a snap with no snap idnonetakes 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

MessageMeaning
cannot apply gadget config defaults for snap "<snap>", no configure hookmeant 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

Roads from here

RUNNING SNAPS

SNAPCTL · the snap's API into snapd

HOOKS · code snapd runs inside a snap

POLICY · who may install and connect what

UBUNTU CORE · install and recovery