"snapctl: configuration and health"
snapctl command group for users for app developers for Ubuntu Core developers for snapd developers for administrators
Six snapctl commands that read and write snap configuration and interface attributes and report health. Configuration and health writes are buffered in the hook context and saved only when a hook exits successfully or right after a call from an app; get and set also reach confdb views.
On the map: snapctl district
01 Six commands, one context for app developers for Ubuntu Core developers for snapd developers for administrators
All six commands act on the caller's context. Writes are buffered and saved when the context is done. The exception is confdb: set --view from an app starts a set-confdb change, from another hook it adds tasks to that hook's change, get --view may start a get-confdb change, and snapctl waits for either.
acme-agent's configure hook reads the server address, fills in an interval, and reports that all is well. That takes three snapctl calls, and none of them starts a change. Each lands in the hook's context: get and set work on a configuration transaction kept there, and set-health on a pending health record. Nothing reaches snapd's state until the context is done. These six commands sort into four groups: configuration, health, connections and confdb. Confdb is the odd one out, because a write through a view can start a change of its own. Get, set-health and snapctl is-connected work without root; set, unset and fail need sudo.
02 A configure hook is one transaction for app developers for snapd developers for administrators
In a hook, snapctl set writes into one transaction that is committed only after the hook exits 0. From an app each call is committed at once and no configure hook runs. snap set with values on a snap without a configure hook fails with snap "acme-agent" has no "configure" hook.
You run snap set acme-agent with a new server and an interval of 30. What if the hook decides the server is wrong? snapd makes a configure-snap change with one task that runs the configure hook. Your values are already loaded into the hook's transaction, so snapctl get sees the new server before anything is saved. The hook's own snapctl set calls join the same transaction. Exit zero, and all of it is committed. Exit with anything else, and all of it is dropped, your values included, and snap set reports the error. From an app there's no hook: each snapctl set is saved when the call returns.
03 Gadget defaults need a configure hook for Ubuntu Core developers for app developers for snapd developers
Defaults from gadget.yaml are applied only as the patch of the configure hook, or of default-configure, which also needs a configure hook, on first install. Without a configure hook the defaults are not applied, and nothing reports it. The address is an example.
The gateway's gadget sets acme-agent's server before anyone logs in. How does it get there? Gadget defaults are keyed by snap-id, with system standing for core. On the first install, snapd links the snap, starts its services, then runs its configure hook with a use-defaults flag. They become the hook's patch, so it checks them like any snap set. A default-configure hook, if the snap has one, gets them instead, before the services start. No configure hook at all? The configure task finds nothing to run, and the defaults are skipped without a message. Core needs no hook: snapd applies system defaults itself.
04 A health status is not a failed check for app developers for Ubuntu Core developers for snapd developers for administrators
snapctl set-health error ... reports; a non-zero exit from check-health fails the change. Health is per snap. The help text promises periodic checks, but the hook is scheduled only at the end of install, refresh and revert.
acme-agent can't reach its server right after a refresh. Should the refresh fail? That's up to how the agent says so. Every install, refresh and revert ends with the optional check-health hook. If the hook calls snapctl set-health error with a message and exits zero, the status is recorded and the change succeeds. If it exits zero without setting anything, the status is unknown. If the hook itself fails, the status is unknown with the code snapd-hook-failed, and the change fails with it. A snap may set okay, waiting, blocked or error, from any hook or app, and the status belongs to the whole snap.
05 What you see of a snap's configuration and health for users
If a snap rejects a value, snap set fails and nothing is stored. The reason after run hook "configure": is written by the snap, not by snapd. Health other than okay shows in snap list Notes and as a health: block in snap info. The messages are examples.
You set acme-agent's interval to zero, and snap set fails. Who said no? The snap did. When you run snap set, the snap receives your values and can check them. If it refuses, snap set fails with the reason the snap itself wrote, and none of your values are kept: snap get still shows the old interval. A snap can also report its health. Any status other than okay appears in the Notes column of snap list, and snap info adds a health section with the status, the message, a code, and when it was checked. Okay is shown only by snap info with the --verbose option.
06 Prepare hooks write attributes, every interface hook reads them for app developers for snapd developers
snapctl get :<plug> works in prepare-, unprepare-, connect- and disconnect- hooks; snapctl set :<plug> only in prepare-plug- and prepare-slot- hooks, on the hook's own side, and not over static attributes. The long help of set says "prepare and connect hooks"; the code allows prepare only. acme-vpn, its slot and the path attribute are examples.
Acme-vpn picks its socket's path only when the agent connects, and the agent needs that path. How does it get across? Connecting runs five steps: prepare-plug, prepare-slot, connect, connect-slot and connect-plug. In its prepare-slot-socket hook, acme-vpn calls snapctl set on its own slot, and the value is written into the connect task at once. The agent's prepare-plug-vpn-socket hook ran before that, so it couldn't see it. Then connect-plug-vpn-socket reads it with snapctl get and the slot option. Unprepare and disconnect hooks read both sides too. Setting anywhere else is refused, and so is overwriting a static attribute.
07 A confdb custodian can refuse a write for Ubuntu Core developers for app developers for snapd developers
snapctl fail <reason> works only in a change-view-<plug> hook and rejects the pending confdb write; it has nothing to do with refresh gating. Requires experimental.confdb. The schema, view and snap names follow the confdb hooks deck; the host and the reason are examples.
Confdb holds configuration that no single snap owns, such as the gateway's proxy address. Who gets to say a value is wrong? The custodian snap, here acme-settings. Someone writes through the proxy-admin view, with snap set, or from an app with snapctl set and the view option. Either way that starts a set-confdb change, and the writer waits. Acme-settings' change-view-proxy-admin hook runs first. It can read the pending host and call snapctl fail with a reason. When the hook exits, the commit is skipped, the pending transaction is cleared, and the writer sees the change fail. Fail works only in change-view hooks, and confdb is experimental.
08 Where to go from here
Roads: the snapctl mechanism, changes and tasks, the other two command groups, configuration, the gadget, hooks and interfaces.
Settings and health wait in a context until the hook is done; attributes are written at once. Here's where the rest is explained. The snapctl deck shows how a call reaches snapd and finds that context, and the overlord shows the changes and tasks a configure hook runs inside. Two sibling decks cover the other snapctl commands: services, refreshes and changes, and questions about the device and the system. The configuration deck describes what snap set and snapctl set share, including confdb, and the gadget deck shows where defaults come from. Hooks and interfaces cover the hooks these commands run in and the plugs and slots they read.
09 Every command at a glance
6 commands: 3 non-root, 0 create or join a change, 3 saved when the hook or call ends, 1 hook-specific.
All 6 commands of this group at a glance. 3 may run as non-root: get, is-connected, set-health. 3 commands, set, set-health, unset, are saved only when the hook succeeds or the call ends. One works only inside one particular hook: fail in change-view. With the view option, get and set can also start a confdb change. The rest read state or change it directly. Each command is described in full in the list under this deck.
Read more
The catalogue below this deck describes each command. This page collects the rules that several of them share.
When a write takes effect
| Write | From a hook | From an app or service |
|---|---|---|
snapctl set, unset (configuration) | committed when the hook exits 0; dropped if it fails | committed when the call returns; no configure hook runs |
snapctl set-health | saved when the hook exits 0 | saved when the call returns |
snapctl set :<plug> (attribute) | written into the connect task at once | refused |
snapctl set --view | inside a confdb hook: saved with that hook; in another hook: tasks added to the hook's change | a set-confdb change; the call waits for it |
For a hook whose failure snapd ignores, such as remove, the buffered work is committed even when the hook fails.
Health
| Field | Rule |
|---|---|
| status | okay, waiting, blocked or error; unknown cannot be set by hand |
| message | required unless okay; at least 7 characters; longer than 70 is cut to 69 and … |
--code | 3 to 30 characters, lowercase letters, digits and single hyphens |
| okay | must have no message and no code |
| scope | one status per snap |
| check-health outcome | Status recorded | Change |
|---|---|---|
hook calls set-health and exits 0 | that status | succeeds |
hook exits 0 without set-health | unknown, code snapd-hook-no-health-set | succeeds |
| hook fails or overruns its 30 seconds | unknown, code snapd-hook-failed | fails |
snap list shows any status other than okay under Notes. snap info shows a health: block with status, message, code, checked and revision, and shows okay only with --verbose.
for app developers for Ubuntu Core developers for snapd developers for administrators
Configuration through hooks
| Event | Hook | What it sees |
|---|---|---|
snap set <snap> k=v | configure, in a configure-snap change | the new values, before they are saved |
snap set with values, snap without a configure hook | none | fails: snap "<snap>" has no "configure" hook |
| first install of a snap with a snap ID and gadget defaults | configure with use-defaults, after the services start | the defaults as its patch |
the same, with a default-configure hook | default-configure gets the defaults, before the services start | a configure hook is still required |
defaults for system | none; snapd applies them | |
| defaults but no configure hook | the defaults are skipped without a message (the check in snapd cannot be reached; snapd bug) |
for app developers for snapd developers
Interface attributes
Hooks run in this order when a plug is connected: prepare-plug-<plug>, prepare-slot-<slot>, connect-slot-<slot>, connect-plug-<plug>, with the connect task between the prepare and connect hooks.
| Hook | snapctl get :<name> | snapctl set :<name> |
|---|---|---|
prepare-plug-*, prepare-slot-* | yes | yes, own side, not over a static attribute |
connect-*, unprepare-*, disconnect-* | yes, --plug or --slot for the other side | no |
| any other hook, or an app | no | no |
for Ubuntu Core developers for app developers for snapd developers
A confdb write, task by task
snap set <account>/<confdb>/<view>, or snapctl set --view :<plug> from an app, creates a set-confdb change; from a hook that is not a confdb hook, the same tasks join that hook's change. The tasks are: clear-confdb-tx-on-error, the custodians' change-view-<plug> hooks, save-view-<plug> hooks, commit-confdb-tx, observe-view-<plug> hooks of other snaps (errors ignored) and clear-confdb-tx. A snapctl fail in a change-view hook fails that hook's task with cannot change confdb <account>/<confdb>: <snap> rejected changes: <reason>, and the commit does not run. Confdb needs snap set system experimental.confdb=true.
Further reading
- Configure snaps:
snap get,snap setandsnap unsetfrom the user's side. - Supported snap hooks: configure, default-configure, check-health and the interface hooks.
- Interface hooks: prepare and connect hooks and their attributes.
- The gadget snap: the
defaultssection of gadget.yaml. - Confdb configuration mechanism: views, custodians and their hooks.
Roads from here
INTERFACES AND CONFINEMENT
- Interfaces — the plugs and slots whose attributes prepare hooks write
RUNNING SNAPS
- Configuration — the configuration system that snap set and snapctl set share
- The overlord — the changes and tasks that a configure hook runs inside
SNAPCTL · the snap's API into snapd
- snapctl: how it works — how a snapctl call reaches snapd and finds its context
- snapctl: services, refresh and changes — the commands that act on services and refreshes and changes
- snapctl: device and system — the commands that ask about the device and the system
HOOKS · code snapd runs inside a snap
- Hooks: how they work — the hooks these commands run in
UBUNTU CORE · install and recovery
- Model, gadget and kernel — the gadget that supplies configuration defaults