Assertions: confdb and messages

assertion group for Ubuntu Core developers for snapd developers

confdb-schema is an account's storage schema and views; confdb-control is signed by the device key and delegates views to operators; request-message carries an operator's request through the store and response-message carries the device-signed answer back. All of it is experimental and behind experimental.confdb and experimental.remote-device-management.

On the map: assertions district

▶ Watch this deck — 7 scenes, ~6 min

01 Schema, control, message: three signers

CONFDB AND MESSAGES · EXPERIMENTAL account acmethe schema ownerconfdb-schemastorage schema + views gateway device keyconfdb-controlwhich operators may usewhich views operatorrequest-messagestore message queue deviceresponse-message · signed by the device key → store → operator experimental.confdb · experimental.remote-device-management
Three signers: an account signs confdb-schema, the device key signs confdb-control, an operator signs request-message which travels through the store to the device, which answers with a response-message signed by the device key; all experimental

confdb-schema by its account, confdb-control and response-message by the device key, request-message by an operator. Experimental: experimental.confdb and experimental.remote-device-management.

Acme keeps the gateway's proxy address in confdb. Now it wants to change that address on a gateway nobody can reach. Four assertion types make this work, with three signers. Acme, as an account, publishes the confdb-schema and its views. The gateway signs a confdb-control assertion, which says which operators may use which views. An operator sends a request-message, and it travels through the store. The gateway checks it, applies it, and answers with a response-message signed by its own key. All of this is experimental. It needs experimental.confdb, and remote management also needs experimental.remote-device-management.

02 A confdb-schema for Ubuntu Core developers for snapd developers

CONFDB-SCHEMA · EXPERIMENTAL illustrative, signature cut type: confdb-schema authority-id: acme account-id: acme name: gateway views: proxy: rules: - access: read request: host storage: proxy.host proxy-admin: rules: - request: host storage: proxy.host { "storage": { "schema": … } } authority-id = account-id account-id system: signed by canonical views: rulesrequest name → storage pathaccess: read-write (default) | read | write the JSON body: storage schemathe only type that must have a JSON body acme/gateway/proxyacme/gateway/proxy-adminaccount/schema/view not acked? fetched from the store when a snap first needs it · newer revisions replace it on refresh
An illustrative confdb-schema acme/gateway signed by acme, with a read-only view proxy and a writable view proxy-admin whose rules map the request host to the storage path proxy.host, and a JSON storage schema body; views are addressed as account/schema/view, and a missing schema is fetched from the store when first needed

Illustrative. Signed by its account-id; views map request names to storage paths with an access mode; the JSON body holds the storage schema. Acked, or fetched when first needed; addressed as acme/gateway/proxy. Experimental.

Here's acme's gateway schema, cut down. A schema belongs to one account, and that account signs it. System schemas are the exception: Canonical signs those. The views are headers. Each rule maps a request name, such as host, to a storage path, with an access mode. Here one view only reads, and the other may write. The storage schema is the body, and confdb-schema is the only type whose body must be JSON. Snaps and commands address a view as account, schema and view. If a snap uses a view snapd doesn't have yet, snapd fetches the schema from the store, and newer revisions replace it on refresh.

03 Delegating views to operators for Ubuntu Core developers for snapd developers

CONFDB-CONTROL · EXPERIMENTAL illustrative, signature cut type: confdb-control brand-id: acme model: acme-gateway serial: gw-000600 groups: - operators: - acme-ops authentications: - operator-key views: - acme/gateway/proxy-admin revision: 2 no authority-id keyed by brand-id, model, serialsigned by the device key in that serial groups: operators · viewsauthentications: operator-key | store POST /v2/confdb{"action": "delegate","operator-id": "acme-ops","views": ["acme/gateway/proxy-admin"],"authentications": ["operator-key"]}no snap command · needs both flags re-signed by the device key, revision + 1 needs a serial in the strict formatno confdb-control: every message is unauthorized
An illustrative confdb-control assertion for the acme-gateway with serial gw-000600, with no authority-id, keyed by brand-id, model and serial, delegating the view acme/gateway/proxy-admin to the invented operator account acme-ops with operator-key authentication; it is changed through POST /v2/confdb with delegate or undelegate and re-signed by the device key; without one every message is unauthorized

Illustrative; acme-ops is invented. confdb-control is keyed by brand-id, model and serial and signed by the device key. POST /v2/confdb with delegate or undelegate re-signs it. Without one, messages are unauthorized. Experimental.

So who decides that acme's operations account may change the proxy? The gateway does. A confdb-control assertion has no authority-id. It's keyed by brand, model and serial, and signed by the key in that gateway's serial. It lists groups: operators, the views they may use, and how they must authenticate, with an operator-key or through the store. There's no snap command for it. It changes only on the device, through the confdb endpoint with delegate or undelegate, and each change is signed again at a higher revision. Signing one needs a serial in the strict format. Without a confdb-control, every incoming message is answered unauthorized.

04 The exchange with the store for snapd developers for Ubuntu Core developers

DEVICE-MANAGEMENT-EXCHANGE · EXPERIMENTAL storev2/messagesevery 6 hexchange-mgmt-messagessend ready responses · fetch requests · ack with the after token dispatch-mgmt-messages acme7-1validate-mgmt-messageapply-mgmt-messagequeue-mgmt-responseacme7-2validate-mgmt-messageapply-mgmt-messagequeue-mgmt-response other sequencevalidate → apply → queue-responseunsequencedvalidate → apply → queue-response a gap in a sequence stops the chain until the missing message arrives a refused or failed message still gets its answer, and the next one runs queued responses go out on the next exchange
Every six hours exchange-mgmt-messages talks to the store's v2/messages endpoint; dispatch-mgmt-messages builds one chain per sequence of validate, apply and queue-response tasks, with the next message in a sequence after the previous one and other sequences in parallel

Experimental. Change device-management-exchange: exchange-mgmt-messages, dispatch-mgmt-messages, then per message validate-mgmt-message, apply-mgmt-message, queue-mgmt-response. Messages <id>-<n> run in order; a gap stops the sequence.

How does acme's request reach the gateway? The gateway asks for it. Every six hours the device management manager starts a change, device-management-exchange. Its first task sends any responses that are ready and fetches new requests from the store. The dispatch task then builds a chain for each message: validate, apply, queue the response. The next message in a sequence waits for the one before it, while other sequences run side by side. A gap in the numbering stops the chain until the missing message arrives. A message that's refused or fails still gets its answer, and the next one runs. Answers go back on the next exchange.

05 A request-message for snapd developers for Ubuntu Core developers

REQUEST-MESSAGE · EXPERIMENTAL illustrative, signature cut type: request-message authority-id: acme-ops account-id: acme-ops message-id: acme7-1 message-kind: confdb devices: - gw-000600.acme-gateway.acme valid-since: 2026-11-13T09:00:00Z valid-until: 2026-11-14T09:00:00Z {"action": "set", "account": "acme", "view": "gateway/proxy-admin", "values": {"host": "10.0.0.9"}} keyed by account-id · message-id kind, target devices, validity window fetch the signer's account-keycheck the signaturefor this device? within the window?otherwise: rejected confdb: the only registered handlerthe signer must be the operator itselfholding an operator-key delegationin confdb-control signed by the store for an operator:answered unauthorized today assumes is parsed, not yet checked · request-messages are not stored in the assertion database
An illustrative request-message from the invented operator account acme-ops, keyed by account-id and message-id, of kind confdb, targeting the gateway by serial, model and brand within a validity window, with a body that sets host through acme/gateway/proxy-admin; snapd checks its signature, target and window, and the confdb handler requires the operator to sign it and hold an operator-key delegation, so a store-signed message is unauthorized today

Illustrative. devices, valid-since and valid-until decide whether the message is for this device now. The confdb handler requires authority-id = account-id and an operator-key delegation; assumes is not checked yet. Experimental.

Here's a request from acme's operations account. It's keyed by account and message-id. It names its kind, confdb, the devices it's for, by serial, model and brand, and the window when it's valid. Snapd fetches the signer's key and checks the signature as usual. A message for another device, or outside its window, is rejected. Confdb is the only kind with a handler, and it asks for more. The signer must be the operator itself, and confdb-control must delegate the view to it with an operator-key. So a message the store signs for an operator is unauthorized today. The assumes header is read, but not checked yet.

06 Four answers for snapd developers for Ubuntu Core developers

RESPONSE-MESSAGE · EXPERIMENTAL validate-mgmt-messageapply-mgmt-messagequeue-mgmt-response rejectedcannot decode · wrong deviceoutside its validity windowits sequence was dropped unauthorizedoperator not delegatedor no confdb-control errorapply failedor its change failedsuccessthe result in the body response-messageaccount-idmessage-iddevicestatusbody: JSONno authority-id:signed by the device keysent on the next exchange handler error text reaches the operator verbatim: write it as "cannot …"
Validation gives rejected or unauthorized, applying gives error or success, and queue-mgmt-response builds a response-message keyed by account-id, message-id and device, signed by the device key and sent on the next exchange

Experimental. rejected and unauthorized come from validation, error and success from applying. The response-message is signed by the device key and sent on the next exchange.

Acme's operator needs to know what happened to the request, so snapd answers every message it processes. Validation can give two answers. Rejected means the message failed a check: wrong device, outside its window, or in a sequence that was dropped. Unauthorized means the handler found no delegation. Applying gives the other two: error if applying or its change failed, and success otherwise. The response-message is keyed by account, message-id and device, carries a JSON body, and is signed by the gateway's key. It's queued and sent on the next exchange. A note for handler writers: error text reaches the operator exactly as written.

07 Where to go from here

ROADS Assertions: confdb and messagesConfdbwhy it exists Configurationsnap get and snap setconfdb hooksrun when a view changes How assertions workchecked and stored Assertions: devicesthe serial and the device key Identity and storeaccounts and keys The overlordchanges, tasks and lanes
Roads from the confdb and messages deck: why confdb exists, configuration, confdb hooks, how assertions work, devices, identity and store, and the overlord

Roads: why confdb exists, configuration, confdb hooks, how assertions work, devices and the device key, identity and store, and the overlord.

So a proxy address on a gateway nobody can reach changes through three signed statements: acme's schema, the gateway's delegation, and an operator's request, with the gateway's answer going back. Confdb: configuration that does not belong to one snap explains why confdb exists at all. Configuration shows views next to snap get and snap set, and the confdb hooks deck covers what runs when a view changes. Assertions: how they work shows how any statement is checked. The devices deck covers the serial and the device key. Identity and store covers the accounts and keys of owners and operators. And the overlord explains changes, tasks and lanes.

Read more

Where each type is kept

TypeStored in the assertion database
confdb-schemayes
confdb-controlyes, created on the device
request-messageno
response-messageno

The confdb message handler accepts a request-message only when its authority-id equals its account-id.

Flags

FlagNeeded for
experimental.confdbconfdb views, snap get and snap set on views, the confdb message handler and POST /v2/confdb
experimental.remote-device-managementfetching request messages and POST /v2/confdb

Set them with snap set system experimental.<flag>=true. With remote device management off, the exchange still runs to send responses that are already queued.

Delegating views

POST /v2/confdb with a JSON body; there is no snap command.

FieldValue
actiondelegate or undelegate
operator-idthe operator's account ID
viewsa list of <account>/<schema>/<view>
authenticationsa list of operator-key and store

Each change re-signs confdb-control with the device key at the next revision. The device needs a serial whose serial number matches ^[a-zA-Z0-9](?:[:+-]?[a-zA-Z0-9])*$; otherwise invalid serial: <serial>.

The exchange

ItemValue
Changedevice-management-exchange, summary Process device management messages
Interval6 hours after the last exchange
Endpointthe store's v2/messages
Requestthe queued responses, the token of the last received message (after), and a limit of 10 new messages
Acknowledgementa message stays queued at the store until a later exchange acknowledges it with after
Tasksexchange-mgmt-messages, dispatch-mgmt-messages, then per message validate-mgmt-message, apply-mgmt-message, queue-mgmt-response
Ordera message-id of <id>-<n> is message n of sequence <id>; each waits for the one before; sequences and unsequenced messages run in parallel lanes
Gapthe sequence stops until the missing message arrives
More than 8 messages waiting behind a gapthe earliest is answered rejected (too many messages waiting on missing predecessors in sequence) and the rest are dropped
More than 256 sequencesthe least recently used are answered rejected (sequence evicted due to capacity limits)
Waiting for the applied changequeue-mgmt-response retries every 30 seconds until the change is ready

Answers

StatusFromExample reasons
rejectedvalidate-mgmt-messagecannot decode message, cannot verify message signature, not intended for device <id>, not valid at <time>, cannot find handler for message kind "<kind>", an invalid confdb action
unauthorizedvalidate-mgmt-messageno confdb-control; authority-id differs from account-id; the view is not delegated to the operator with operator-key
errorapply-mgmt-messagethe handler or the change it started failed; the text reaches the operator as written
successapply-mgmt-messagethe result is in the body

A message's devices entries have the form <serial>.<model>.<brand-id>. assumes is parsed but not checked yet.

The confdb message body

FieldMeaning
actionget or set
accountthe schema's account
view<schema>/<view>
keysthe request names to read
constraintsoptional constraints for a read
valuesthe values to write

Further reading

Roads from here

RUNNING SNAPS

ASSERTIONS · signed statements snapd trusts

HOOKS · code snapd runs inside a snap