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
01 One proxy address, three snaps
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
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
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
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
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
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
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 get | confdb | |
|---|---|---|
| Who owns the data | the snap | the account that signs the schema |
| Who validates a write | the snap's configure hook | the storage schema and the custodians |
| Who can read it | the snap itself, and authorised callers of snap get | snaps with a connected plug for a view, and authorised callers of snap get |
| Addressed as | snap get <snap> <key> | snap get <account>/<schema>/<view> <request> |
| Layout change | a new revision of the snap | a new revision of the schema |
| Status | stable | experimental (experimental.confdb) |
Access to a view
| Caller | Plain data: read | Plain data: write | Secret data |
|---|---|---|---|
| App of a connected snap run as root | yes | yes | read and write |
| App of a connected snap run as another user | yes | no | no (unauthorized access) |
snap get / snap set as root | yes | yes | read and write |
snap get / snap set as another user | no | no | no (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
| Word | Meaning |
|---|---|
| schema | a confdb-schema assertion: an account's storage schema and its views |
| view | a named set of rules; each maps a request path to a storage path with an access mode |
| custodian | a snap whose confdb plug has role: custodian; it can change, reject and persist writes |
| observer | a snap with a plug and no role; it is told after a write |
| ephemeral data | data whose authoritative copy is outside snapd; snapd keeps a cache |
| operator | an account a device has delegated views to in confdb-control |
Messages you may meet
| Message | Meaning |
|---|---|
the "confdb" feature is disabled: set 'experimental.confdb' to true | the flag is off |
cannot write confdb view <view>: no custodian snap connected | no custodian for a non-system view |
cannot read confdb view <view>: no custodian snap connected | the same for a read |
snaps cannot be custodians of "system" confdb schemas | a plug asked for the role on a system schema |
Further reading
- Confdb configuration mechanism: the published explanation of views, custodians, ephemeral data and hooks
- Configure snaps with confdb: a worked example with a schema and two snaps
- confdb-schema assertion: the fields and the storage schema types
- confdb-control assertion: how a device delegates views to operators
- Configure snaps: the per-snap mechanism confdb sits beside
Roads from here
INTERFACES AND CONFINEMENT
- Interfaces — plugs and connections in general
RUNNING SNAPS
- Configuration — configuration that belongs to one snap
SNAPCTL · the snap's API into snapd
- "snapctl: configuration and health" — snapctl get and set with a view inside a snap
ASSERTIONS · signed statements snapd trusts
- Assertions: confdb and messages — the schema and control assertions and the exchange with the store
HOOKS · code snapd runs inside a snap
- Hooks: confdb hooks — the hooks a custodian and an observer run
UBUNTU CORE · install and recovery
- A device set up before anyone logs in — first values set by the gadget instead