Hooks: confdb hooks
hook group for Ubuntu Core developers for app developers for snapd developers
Five hook name patterns that end with the name of a confdb plug. A write through a view runs change-view and save-view in every connected custodian then commits and runs observe-view in the other affected snaps; a read runs load-view and query-view in the custodians and commits nothing. Confdb is experimental and needs experimental.confdb.
On the map: hooks district
01 A write and a read through a view
Five patterns: change-view-, save-view-, observe-view- on writes; load-view-, query-view- on reads. The suffix is a confdb plug name. The schema acme/gateway and its views are examples.
The gateway's proxy address lives in confdb, under acme's gateway schema, and no single snap owns it. So when you change it, which snaps get a say, and when? A write first runs change-view in the custodians, where a custodian can check or adjust the value, then save-view, where it can store it somewhere else. Then snapd commits, and observe-view tells the other snaps. A read runs load-view and query-view in the custodians, and commits nothing. Every one of these hook names ends with the snap's own confdb plug name. And confdb is experimental: it's off until you set experimental.confdb.
02 Custodian or observer: the plug decides for Ubuntu Core developers for app developers for snapd developers
role: custodian on a connected confdb plug selects the custodian hooks for that one view. A write or read with no custodian connected fails with no custodian snap connected. System schemas have no custodians. Naming a plug after its view is a habit, not a rule.
Who counts as a custodian? It's written on the snap's confdb plug. Acme-settings has a plug called proxy-admin, for the proxy-admin view, with role: custodian. So for writes and reads through that view, it runs change-view-proxy-admin, save-view-proxy-admin and the rest, as long as the plug is connected. Acme-agent's plug, called proxy, has no role, so acme-agent is an observer: it only gets observe-view-proxy after a write. Every view needs a connected custodian, or reads and writes through it are refused. So acme-settings has a custodian plug for the proxy view too, which means one write can bring it two observe-view tasks, one per plug.
03 A write is a pipeline for Ubuntu Core developers for app developers for snapd developers
Order: all change-view-, all save-view-, commit, observe-view- of the affected snaps except the writer. Values set in change-view are what everyone after it sees. A snapctl set --view from an app waits for the change, up to 2 minutes.
You run snap set on the proxy-admin view, and type the host in capitals. Snapd starts a set-confdb change. First, change-view runs in every custodian, in snap name order, and acme-settings' hook lowercases the host. Next, save-view runs in each custodian and sees the final value. Then snapd commits. Then observe-view runs for every snap whose view the write touched: acme-agent, acme-settings, acme-updater and acme-vpn. Had acme-settings' own app made the write, it wouldn't be told. Snap get now returns the lowercase host. And change-view could have refused the write instead, with snapctl fail.
04 A failed save is rolled back, and save-view runs again for Ubuntu Core developers for snapd developers
A save-view failure rolls every custodian back by running its save-view- hook again with the committed data. Write save-view hooks so that they can run twice. acme-backup is an invented example; snapd's test confdb-cross-config checks this order.
Now another custodian is connected: acme-backup, which copies proxy settings to a backup server. You write a new host. Both change-view hooks run, acme-backup's first, by name. Then acme-backup's save-view stores the new host on its server, and acme-settings' save-view fails. What now? Snapd resets the transaction to the committed values and runs the save-view hooks again: the failed one first, then the earlier ones, with errors ignored. So acme-backup saves twice, the second time with the old host. The change fails, nothing is committed, and no observer is told. Write save-view so it gives the right result when it runs again.
05 A read can run hooks too for Ubuntu Core developers for app developers for snapd developers
load-view- fills a read transaction; query-view- adjusts it. Neither is saved. A failure fails the read.
Reads can involve custodians too. The proxy password is ephemeral: acme-settings keeps the real copy outside snapd, and snapd holds only a cached one. When snap get asks for it, snapd starts a get-confdb change. Load-view runs in acme-settings, sees the cached value, and loads the current one. Query-view runs next, sees what load-view set, and may adjust it. The reader gets the result. None of it is committed: snapd's copy still holds the old value. If no custodian has these hooks, none runs, and the answer comes from snapd's copy. But a view with ephemeral data can't be read without a load-view hook.
06 A slow custodian hook delays every access to its confdb for Ubuntu Core developers for snapd developers
Accesses to one confdb schema are serialised behind the running write; reads may run together. Keep custodian hooks short: every reader and writer waits for them. A waiting access gives up after 10 minutes by default, or after --wait-for.
Acme-settings' save-view hook pushes each new proxy address to acme's management server, and today that server is slow. Meanwhile, more reads and writes of the gateway schema arrive. They queue behind the open write. A reader that will only wait zero seconds gets timed out waiting for access. When the server answers and the hook ends, the queued requests run in the order they arrived. The first read sees the address the slow write saved, and a read queued behind a later write sees the later one. Confdb hooks are also held, not skipped, while their snap is being refreshed. So keep custodian hooks short: everyone waits for them.
07 Where to go from here
Roads: what confdb is for, the mechanism, configuration, the snapctl commands, assertions, interfaces, interface hooks and the overlord.
Those are the hooks around a view. The confdb deck explains why confdb exists at all: data that no single snap owns. The hooks deck covers the mechanism that runs every hook. The configuration deck explains schemas, views and databags. The snapctl configuration deck shows snapctl get and set with a view, and snapctl fail. The confdb assertions deck shows the schema that defines the views. The interfaces deck covers the confdb interface and its plugs, interface hooks the other hooks named after a plug, and the overlord the set-confdb and get-confdb changes.
Read more
The tasks of a write and a read
| Change | Kind and summary | Tasks, in order |
|---|---|---|
| A write | set-confdb, Set confdb through "<account>/<schema>/<view>" | clear-confdb-tx-on-error; change-view of each custodian that ships it, by snap name; save-view of each, in the same order; commit-confdb-tx; observe-view for each affected plug of each affected snap except the writer; clear-confdb-tx |
| A read | get-confdb, Get confdb through "<account>/<schema>/<view>" | clear-confdb-tx-on-error; load-view of each custodian that ships it; query-view of each; clear-confdb-tx; for snap get, load-confdb-change |
- Custodians are snaps with a connected
confdbplug for exactly this view withrole: custodian. A view of a non-system schema with none refuses reads and writes. - An affected snap has a connected
confdbplug for any view of the schema that the written paths reach, custodian or not. It gets an observe-view task per such plug, also when it ships no observe-view hook; that task then does nothing. snap sethas no writing snap, so every affected snap is told. A write from a snap's app withsnapctl set --viewskips that snap.- A read through
snap getalways creates a change; without load-view or query-view hooks it is complete at once.snapctl get --viewwithout those hooks reads snapd's copy directly.
What a failure does
| Hook fails | Result |
|---|---|
change-view, or it calls snapctl fail | the write is refused: cannot change confdb <account>/<schema>: <snap> rejected changes: <reason> |
| save-view | every custodian's save-view runs again with the committed data, the failed one first, errors ignored; the write fails |
| observe-view | ignored; the write has already been committed |
| load-view, query-view | the read fails |
Waiting
| Wait | Limit | Message |
|---|---|---|
| a read or write waits for an earlier write of the same schema | --wait-for, or 10 minutes | cannot read <view>: timed out waiting for access (or write) |
snapctl set --view or get --view from an app waits for its change | 2 minutes | cannot write confdb view <view>: timed out (2m0s) waiting for change <id> |
| a confdb hook while its snap is being refreshed | held until the snap is active again | none |
Reads may run together; a write waits for every earlier access and holds the schema until its change is done.
Messages
| Message | Cause |
|---|---|
cannot write confdb view <view>: no custodian snap connected | no connected custodian for the view; cannot read for a read |
cannot write confdb view <view>: write might change ephemeral data but no custodians has a save-view hook | an ephemeral path would be written with no save-view to store it |
cannot schedule tasks to read view <view>: read might cover ephemeral data but no custodian has a load-view hook | an ephemeral path would be read with no load-view to fetch it |
snaps cannot be custodians of "system" confdb schemas | role: custodian on a plug for a system schema |
The schema acme/gateway, its views and the snaps in this deck are examples.
Further reading
- Confdb configuration mechanism: views, custodians, observers and ephemeral data.
- Configure snaps with confdb: a worked example with a schema, plugs and the hooks.
- confdb-schema assertion: how views and ephemeral storage are declared.
- Experimental features: turning on
experimental.confdb.
Roads from here
INTERFACES AND CONFINEMENT
- Interfaces — the confdb interface and its plugs
RUNNING SNAPS
- Confdb: configuration that does not belong to one snap — what confdb is for and when to use it
- Configuration — confdb schemas views and databags
- The overlord — the set-confdb and get-confdb changes
SNAPCTL · the snap's API into snapd
- "snapctl: configuration and health" — snapctl get and set with a view and snapctl fail
ASSERTIONS · signed statements snapd trusts
- Assertions: confdb and messages — the confdb-schema assertion that defines the views
HOOKS · code snapd runs inside a snap
- Hooks: how they work — how hooks run and fail in general
- Hooks: interface hooks — the other hooks named after a plug