Confdb: configuration that does not belong to one snap

purpose for app developers for Ubuntu Core developers for administrators for snapd developers

A snap's options belong to that one snap so a value several snaps need has no owner. Confdb moves such data into a schema signed by an account and reached through views. That gives shared configuration with per-rule access and a storage layout that can change without changing the snaps and a way to delegate management of a device. It is experimental and off unless experimental.confdb is set.

On the map: running snaps district

▶ Watch this deck — 7 scenes, ~5 min

01 One proxy address, three snaps

CONFDB EXPERIMENTAL today with confdb acme-agentproxy.hostacme-updaterproxy.hostacme-vpnproxy.host $ snap set acme-agent proxy.host=10.0.0.1$ snap set acme-updater proxy.host=10.0.0.1$ snap set acme-vpn proxy.host=10.0.0.1three copies, three configure hooks $ snap set acme-vpn proxy.host=10.0.0.7nothing says the copies must agree acme/gatewayschema, signed by the account acmeproxy.hostacme-agentacme-updateracme-vpneach through a view $ snap set acme/gateway/proxy-admin host=10.0.0.1once the docs: cross-snap configuration · precise access control · device onboarding and management · evolving settings
Today: acme-agent, acme-updater and acme-vpn each hold their own proxy.host, set with three snap set commands, and a later command changes only acme-vpn's copy to 10.0.0.7. With confdb: one proxy.host inside the schema acme/gateway, signed by the account acme, joined to all three snaps; one snap set acme/gateway/proxy-admin command sets it. The docs list four uses: cross-snap configuration, precise access control, device onboarding and management, evolving settings

Per-snap options have one owner each. Confdb keeps shared data under a schema signed by an account, "to separate the configuration data from the snap installation", and snaps reach it through views. Experimental, behind experimental.confdb. acme-updater and acme-vpn are invented for this map.

The gateway's proxy moved to a new address, so you type snap set. Then you type it again. And again. Acme-agent, acme-updater and acme-vpn each keep their own copy, because a snap's options belong to that one snap, and only its own configure hook checks them. Later someone updates one and forgets the rest, and nothing says the copies must agree. Confdb takes the value out of the snaps. It lives under a schema that the acme account signs, and the snaps reach it through views. Now you set it once. The docs list four things this buys, and this deck takes them in turn. It's experimental.

02 A view is a contract

REQUEST · STORAGE EXPERIMENTAL the snap the view storage acme-agent$ snapctl get --view :proxy host view: proxyrequest: hoststorage: v1.proxy.host todayv1proxyhost: 10.0.0.1 storage: v2.network.egress.hostafter the schema changesv2networkegresshost: 10.0.0.1unchanged: the snap is not rebuilt removing or renaming host breaks snaps already in the fieldchoose request paths as carefully as an API
acme-agent runs snapctl get --view :proxy host. The proxy view has one rule, request host, storage v1.proxy.host, which leads to the leaf v1, proxy, host 10.0.0.1. Later the rule says storage v2.network.egress.host and the storage tree is reorganised; the snap is not rebuilt. Removing or renaming host would break snaps already in the field

A view rule maps a request path to a storage path. The layout can change by changing the schema alone. Request paths that snaps depend on are hard to remove later. The schema and the view names here are invented.

Say acme wants to tidy up how the proxy settings are stored. With snap set, the key a snap reads is the key that's stored, so that means a new release of every snap. A view puts a mapping in between. Acme-agent asks its proxy view for host: the request path. The view's rule maps it to a storage path, where the value lives. The docs call this a configuration contract. Later, acme moves the value and changes only the rule. The snap isn't rebuilt. The catch: older snaps in the field still ask for host, so request paths are hard to retire. Pick them like an API.

03 Not every snap sees everything

ACCESS EXPERIMENTAL acme/gatewayproxyproxy-adminaccess: readaccess: read-writeno access key: read-write acme-agent$ snapctl set --view :proxy ...read only: the write is refused acme-settingsreads and writes some-other-snappublisher is not acme: not connected automatically proxy.passwordmarked secretsnap app run as root: reads and writes itsnap app run as another user: unauthorized accessfrom outside a snap: snap get and snap set on a view need root or polkit
The schema acme/gateway with two views: proxy with access read and proxy-admin with access read-write; a rule without an access key is read-write. acme-agent is plugged into proxy and its snapctl set is refused. acme-settings is plugged into proxy-admin and reads and writes. some-other-snap has an unconnected plug because its publisher is not acme. proxy.password is marked secret: a snap app run as root can use it, an app run as another user gets unauthorized access, and snap get and snap set on a view need root or polkit

Rules carry read, write or read-write (the default). A snap needs a connected confdb plug for the view; it connects automatically only when the schema's account is the snap's publisher. Secret data is refused to a snap's non-root processes.

Sharing the proxy address is one thing. The proxy password is another. So who gets to read what? First, each rule in a view says read, write or read-write, and read-write is the default. Acme-agent's proxy view is read only, so its write is refused. Acme-settings, on proxy-admin, can do both. Second, a snap reaches a view only through a connected confdb plug. Acme's own snaps auto-connect. Another publisher's snap waits for you to connect it. Third, data can be secret. An app run as an ordinary user reads the plain value but not the secret. From outside, snap get and snap set on a view are for administrators.

04 Someone has to answer for the data

CUSTODIAN EXPERIMENTAL $ snap set acme/gateway/proxy-admin host=10.0.0.9proxy-adminno custodian cannot write confdb view acme/gateway/proxy-admin:no custodian snap connected acme-settingsrole: custodianchangerejectpersistwhat a custodian may do with others' writes $ snap set acme/gateway/proxy-admin host=10.0.0.9accepted storage outside snapdephemeral data: the authoritative copy lives here,loaded and stored by the custodian; snapd keeps a cache
snap set acme/gateway/proxy-admin host=10.0.0.9 fails with cannot write confdb view acme/gateway/proxy-admin: no custodian snap connected. acme-settings connects with a plug that has role: custodian and can change, reject and persist writes; the same command is accepted. For ephemeral data the authoritative copy is in storage outside snapd and snapd keeps only a cache

A plug with role: custodian makes its snap responsible for a view: it can change, reject and persist others' writes. With no custodian connected, reads and writes of a non-system view fail. For ephemeral data the custodian holds the authoritative copy.

With snap set, there was always one snap whose job it was to say yes or no. Now the proxy address belongs to no snap. So who says no to a bad value? Try a write and snapd refuses: no custodian snap connected. A custodian is a snap whose confdb plug has role: custodian. In the code's words, that role lets a snap change, reject and persist changes made by others. Outside the system schemas, every view needs one connected before it can be read or written. Connect acme-settings, and the same command goes through. For ephemeral data, the real copy lives outside snapd, and snapd keeps only a cache.

05 Managing a device you cannot reach for Ubuntu Core developers for administrators for snapd developers

REMOTE MANAGEMENT needs a second flag EXPERIMENTAL a gateway · serial 7f3aproxy-admin operatoran accountno route in: no ssh confdb-controlsigned by this device's keyproxy-admin → operatorthe device decides who the storerequeststhe gateway asks the store;nothing dials in experimental.confdb + experimental.remote-device-management
A gateway with serial 7f3a holds the view proxy-admin. An operator account has no direct route to it. On the gateway a confdb-control assertion, signed by this device's key, delegates proxy-admin to the operator. Requests go from the operator to the store, and the gateway fetches them from the store and returns answers; nothing dials in. Both flags are needed: experimental.confdb and experimental.remote-device-management

A device delegates views to operators in a confdb-control assertion signed by its own key. Operator requests reach it through the store. Both need experimental flags.

Your gateways are in other people's buildings, behind other people's routers. You can't ssh in. How do you change that proxy address on a thousand of them? Device onboarding and management is one of the uses the docs list for confdb. Who may do that is decided on the device. A confdb-control assertion, in the code's words, holds lists of views delegated by the device to operators, and it's signed with the device's own key. Requests travel through the store, which the gateway already talks to. Both parts are experimental, with a flag each.

06 When not to use it

WHEN NOT EXPERIMENTAL Does only one snap read this setting?yes: snap set acme-agent interval=60and its configure hook noIs it a first value fixed at the factory?yes: gadget defaults noshared between snaps, per-snap accessor managed by an operator: confdb $ snap get acme/gateway/proxyerror: the "confdb" feature is disabled:set 'experimental.confdb' to true know first:implementation details may changeno snap custodians for system schemasrequest paths are hard to retire
A decision path: does only one snap read this setting? Yes: snap set acme-agent interval=60 and its configure hook. Is it a first value fixed at the factory? Yes: gadget defaults. Shared between snaps or managed from outside: confdb. snap get acme/gateway/proxy fails with the confdb feature is disabled: set experimental.confdb to true. Know first: implementation details may change, no snap custodians for system schemas, request paths are hard to retire

Keep single-snap settings on snap set and the configure hook, and factory first values in the gadget. Confdb is experimental: it needs experimental.confdb, and its details may change.

So should acme-agent's reporting interval move into confdb too? No. Here's the test. If one snap reads a setting and one snap checks it, snap set and that snap's configure hook are simpler, and every snap supports them. If it's a first value for a new device, that's the gadget's job. Confdb earns its cost when several snaps share the data, when access must differ per snap, or when an operator manages the device. And know the limits. It's off unless you set experimental.confdb. The docs say its details may change. Snaps can't be custodians of system schemas. And request paths, once published, are hard to retire.

07 Where to go from here

ROADS Confdbthe purpose Configurationone snap's settings Hooks: confdb hookswhat a custodian's hooks do Assertions: confdbschema, delegation, messages snapctl: configurationget and set with a view Interfacesplugs and connections Device presetsfirst values from the gadget
Roads from confdb: configuration for one snap's settings, confdb hooks for what a custodian's hooks do, confdb assertions for the schema, the delegation and the messages, snapctl for get and set with a view, interfaces for plugs and connections, and device presets for first values from the gadget

The mechanism is in the configuration, confdb hooks, confdb assertions and snapctl decks. Plugs and connections are in Interfaces; first values from the gadget are in device presets.

That's why confdb exists: shared data under a signed schema, reached through views, with a custodian to answer for it. How it works is spread over a few decks. Configuration covers the settings that belong to one snap. The confdb hooks deck shows what a custodian's hooks do when a value changes. The confdb assertions deck has the schema, the delegation to operators, and the messages through the store. The snapctl deck shows get and set with a view, from inside a snap. Interfaces covers plugs and connections in general. And device presets shows first values that come from the gadget.

Read more

What the documentation says confdb is for

  • device onboarding and management
  • cross-snap configuration
  • precise access control
  • evolving configuration settings without changing the affected snaps

Confdb "uses an external confdb-schema assertion to separate the configuration data from the snap installation". It is experimental and its implementation details may change. The schema acme/gateway, its views proxy and proxy-admin and the snap acme-settings in this deck are invented examples.

Per-snap configuration and confdb compared

snap set / snap getconfdb
Who owns the datathe snapthe account that signs the schema
Who validates a writethe snap's configure hookthe storage schema and the custodians
Who can read itthe snap itself, and authorised callers of snap getsnaps with a connected plug for a view, and authorised callers of snap get
Addressed assnap get <snap> <key>snap get <account>/<schema>/<view> <request>
Layout changea new revision of the snapa new revision of the schema
Statusstableexperimental (experimental.confdb)

Access to a view

CallerPlain data: readPlain data: writeSecret data
App of a connected snap run as rootyesyesread and write
App of a connected snap run as another useryesnono (unauthorized access)
snap get / snap set as rootyesyesread and write
snap get / snap set as another usernonono (access denied (try with sudo))

The table is the one in snapd's test tests/main/confdb-secrets. A rule without an access key is read-write. A confdb plug connects automatically only when its account is the snap's publisher; otherwise it is connected by hand.

Words used here

WordMeaning
schemaa confdb-schema assertion: an account's storage schema and its views
viewa named set of rules; each maps a request path to a storage path with an access mode
custodiana snap whose confdb plug has role: custodian; it can change, reject and persist writes
observera snap with a plug and no role; it is told after a write
ephemeral datadata whose authoritative copy is outside snapd; snapd keeps a cache
operatoran account a device has delegated views to in confdb-control

Messages you may meet

MessageMeaning
the "confdb" feature is disabled: set 'experimental.confdb' to truethe flag is off
cannot write confdb view <view>: no custodian snap connectedno custodian for a non-system view
cannot read confdb view <view>: no custodian snap connectedthe same for a read
snaps cannot be custodians of "system" confdb schemasa plug asked for the role on a system schema

Further reading

Roads from here

INTERFACES AND CONFINEMENT

RUNNING SNAPS

SNAPCTL · the snap's API into snapd

ASSERTIONS · signed statements snapd trusts

HOOKS · code snapd runs inside a snap

UBUNTU CORE · install and recovery