"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

▶ Watch this deck — 9 scenes, ~7 min

01 Six commands, one context for app developers for Ubuntu Core developers for snapd developers for administrators

ONE CONTEXT acme-agentconfigure hook$ snapctl get server$ snapctl set interval=60$ snapctl set-health okay hook contextconfig transactionhealthheld here, no change Donesnapd stateconfighealth configurationget · set · unsethealthset-healthconnectionsget :plug · set :plug · is-connectedconfdbget/set/unset --view · fail no sudo: get · set-health · is-connectedroot: set · unset · failcannot use "set" with uid 1000, try with sudo
A configure hook in acme-agent runs snapctl get, set and set-health; the calls land in the hook context's config transaction and health record, which are saved to snapd state when the context is done; the six commands sort into configuration, health, connections and confdb, and set, unset and fail need root

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

ONE TRANSACTION $ sudo snap set acme-agent server=10.0.0.9 interval=30change configure-snapRun configure hook of "acme-agent" snap transactionserver=10.0.0.9interval=30$ snapctl get server10.0.0.9 $ snapctl set checked=truechecked=true exit 0: all savedstate: server=10.0.0.9interval=30 checked=true exit 1: nothing stored, snap set failserror: cannot perform the following tasks:- Run configure hook of "acme-agent" snap(run hook "configure": ...) from an app# in acme-agent.agentsnapctl set interval=60state: interval=60saved when the call returnsno configure hook runs
snap set acme-agent creates a configure-snap change whose configure hook task preloads the values into a transaction; the hook reads and adds to it; exit 0 commits everything, exit 1 discards everything and snap set fails; from an app each snapctl set is saved when the call returns

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

GADGET DEFAULTS # gadget.yamldefaults:<snap-id of acme-agent>:server: 10.0.0.9system:service.ssh.disable: true first install of acme-agentlink-snap …Run default-configure hook (if present)start-snap-servicesRun configure hookRun health check Run configure hookuse-defaults: patch server=10.0.0.9 with a default-configure hook the defaults go there instead:it runs before services start and needs a configure hook too no configure hook: defaults skipped, no error system → configcoresnapd applies them itself, no hook
Gadget defaults keyed by the snap ID of acme-agent flow into the configure hook of the install chain as a use-defaults patch, or into the default-configure hook if the snap has one; without a configure hook the defaults are skipped without an error; system defaults go to configcore

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

HEALTH link-snap …start-snap-servicesRun configure hookRun health check of "acme-agent" snaphook check-health · timeout 30s $ snapctl set-health error"server not reachable"exit 0task Done · change Donehealth: error # no set-health callexit 0health: unknownsnapd-hook-no-health-set # the hook failsexit 1health: unknownsnapd-hook-failedtask Error: install or refresh fails a snap may setokay · waiting · blocked · errorfrom any hook or app · one status per snap, not per app · message 7 to 70 characters · --code like db-downstatus cannot be manually set to "unknown"
An install or refresh ends with the check-health hook; setting error and exiting 0 records the status and the change succeeds; exiting 0 without a status records unknown; exiting 1 records unknown and fails the change; a snap may set okay, waiting, blocked or error

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

WHAT YOU SEE $ sudo snap set acme-agent interval=0error: cannot perform the following tasks:- Run configure hook of "acme-agent" snap (run hook "configure": interval must be at least 10)↑ the snap's own text (an example) $ snap get acme-agent interval30the old value stays $ snap list acme-agentName Version Rev Tracking Publisher Notesacme-agent 1.4 42 latest/stable acme blockedNotes shows any status other than okay $ snap info acme-agent…health:status: blockedmessage: server not reachablecode: server-downchecked: today at 10:02 UTCrevision: 42 okay is shown only by snap info --verbose
snap set acme-agent interval=0 fails with a reason written by the snap and snap get still shows 30; snap list shows blocked in the Notes column; snap info shows a health block with status blocked, a message, a code and when it was checked

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

INTERFACE ATTRIBUTES prepare-plug-vpn-socketprepare-slot-socketconnectconnect-slot-socketconnect-plug-vpn-socketattributes on the connect taskplug-dynamicslot-dynamic # in acme-vpn: prepare-slot-socket$ snapctl set :socket path=$SNAP_DATA/vpn.sockpathwritten at once prepare-plug-vpn-socket ran earlier and could not see path # in acme-agent: connect-plug-vpn-socket$ snapctl get --slot :vpn-socket path/var/snap/acme-vpn/12/vpn.sock--slot or --plug reads the other side ✓ get works in prepare-, connect-,unprepare- and disconnect- hooks set in connect-plug:interface attributes can only be set during the execution of prepare hooksset over a static one:cannot set attribute: attribute "content" cannot be overwritten
Connecting acme-agent:vpn-socket to acme-vpn:socket runs prepare-plug-vpn-socket, prepare-slot-socket, connect, connect-slot-socket and connect-plug-vpn-socket; prepare-slot-socket sets path into slot-dynamic on the connect task at once; prepare-plug-vpn-socket ran earlier and saw no path; connect-plug-vpn-socket reads it with snapctl get --slot; setting outside prepare hooks or over a static attribute is refused

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

CONFDB CUSTODIAN $ sudo snap set acme/gateway/proxy-admin host=proxy9.exampleor, from acme-settings' app$ snapctl set --view :proxy-admin host=proxy9.example set-confdb: Set confdb through "acme/gateway/proxy-admin"clear-confdb-tx-on-errorchange-view-proxy-adminsave-view-*commit-confdb-txobserve-view-*clear-confdb-tx change-view-proxy-admin in acme-settings$ snapctl get --view:proxy-admin hostproxy9.example$ snapctl fail"host is not an acme proxy" clear-confdb-tx-on-errorcannot change confdb acme/gateway:acme-settings rejected changes:host is not an acme proxythe writer sees the change fail fail is hidden, works only in change-view-<plug> hooks and needs experimental.confdb; it is not related to refresh gating
snap set or snapctl set --view on acme/gateway/proxy-admin starts a set-confdb change; acme-settings' change-view hook reads the value and calls snapctl fail; the hook task errors, commit-confdb-tx never runs and clear-confdb-tx-on-error clears the transaction

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 snapctl: configuration and health snapctl: how it workshow a call finds its contextThe overlordchanges and tasks snapctl: services, refresh…services, refreshes, changessnapctl: device and systemquestions about the device Configuration and confdbwhat snap set and snapctl set shareModel, gadget and kernelwhere defaults come from Hookswhere these commands runInterfacesplugs, slots and attributes
Roads from snapctl configuration and health: snapctl, the overlord, the two other snapctl command groups, configuration and confdb, model and gadget, hooks, and interfaces

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

EVERY COMMAND AT A GLANCE commandwherewhoeffect failonly in change-view hooks (confdb)root onlychanges state directly getfrom apps and hooksnon-root allowedreads only is-connectedfrom apps and hooksnon-root allowedreads only setfrom apps and hooksroot onlysaved when the hook or call ends set-healthfrom apps and hooksnon-root allowedsaved when the hook or call ends unsetfrom apps and hooksroot onlysaved when the hook or call ends
Every snapctl command in this group with where it may run, who may run it, and what it does to state

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

WriteFrom a hookFrom an app or service
snapctl set, unset (configuration)committed when the hook exits 0; dropped if it failscommitted when the call returns; no configure hook runs
snapctl set-healthsaved when the hook exits 0saved when the call returns
snapctl set :<plug> (attribute)written into the connect task at oncerefused
snapctl set --viewinside a confdb hook: saved with that hook; in another hook: tasks added to the hook's changea 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

FieldRule
statusokay, waiting, blocked or error; unknown cannot be set by hand
messagerequired unless okay; at least 7 characters; longer than 70 is cut to 69 and …
--code3 to 30 characters, lowercase letters, digits and single hyphens
okaymust have no message and no code
scopeone status per snap
check-health outcomeStatus recordedChange
hook calls set-health and exits 0that statussucceeds
hook exits 0 without set-healthunknown, code snapd-hook-no-health-setsucceeds
hook fails or overruns its 30 secondsunknown, code snapd-hook-failedfails

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

EventHookWhat it sees
snap set <snap> k=vconfigure, in a configure-snap changethe new values, before they are saved
snap set with values, snap without a configure hooknonefails: snap "<snap>" has no "configure" hook
first install of a snap with a snap ID and gadget defaultsconfigure with use-defaults, after the services startthe defaults as its patch
the same, with a default-configure hookdefault-configure gets the defaults, before the services starta configure hook is still required
defaults for systemnone; snapd applies them
defaults but no configure hookthe 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.

Hooksnapctl get :<name>snapctl set :<name>
prepare-plug-*, prepare-slot-*yesyes, own side, not over a static attribute
connect-*, unprepare-*, disconnect-*yes, --plug or --slot for the other sideno
any other hook, or an appnono

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

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

HOOKS · code snapd runs inside a snap

UBUNTU CORE · install and recovery