Configuration

running snaps for app developers for administrators for Ubuntu Core developers

snapd stores each snap's options as a JSON document and the snap's configure hook decides whether a change is accepted. snap set applies a change in a transaction that is saved only when the hook succeeds. The same hook runs at install with gadget defaults and at every refresh. System options are the options of the system itself and are handled inside snapd. Confdb is a separate schema-based mechanism for configuration shared between snaps.

On the map: the rolls office

▶ Watch this deck — 8 scenes, ~6 min

01 snapd keeps the settings, the snap decides

CONFIGURATION you$ snap set acme-agent interval=60snapdstored optionsserver: "https://…"interval: 300acme-agentconfigure hook proposedinterval=60not stored yet runs itreads the proposal,checks it, applies it exit 060 $ snap get acme-agent interval60 exit 1: nothing is storedand the command fails
snap set acme-agent interval=60 goes to snapd, which holds interval=60 as a proposal that is not stored yet and runs the configure hook of acme-agent; the hook exits 0 and the stored interval changes from 300 to 60, which snap get then prints; if the hook exits 1 nothing is stored and the command fails

snap set proposes option values. snapd runs the snap's configure hook and stores the values only if the hook exits successfully. snap get reads the stored values.

acme-agent phones home every five minutes, and you'd like every minute. There's no config file for you to edit. So who do you tell? You type snap set, and snapd holds the new value as a proposal. It doesn't know what an interval is. Think of snapd as the registrar: it keeps the record, but the snap says whether an entry is valid. So snapd runs the snap's configure hook, which reads the proposal, checks it and applies it. If the hook exits successfully, snapd stores the value, and snap get reads it back. If the hook fails, nothing is stored and the command fails.

02 Keys, values and nested documents

GET · SET · UNSET acme-agent's options, one JSON document $ snap set acme-agent interval=60 \server=https://telemetry.exampleinterval: 60server: "https://telemetry.example"60 is a number,the address is a string $ snap set acme-agent proxy.host=10.0.0.1 proxy.port=3128proxy:host: "10.0.0.1"port: 3128 $ snap get acme-agentKey Valueinterval 60proxy {...}server https://telemetry.example $ snap get acme-agent proxy.port3128 $ snap unset acme-agent proxy.portor: snap set acme-agent proxy.port!-s forces a string · -t requires valid JSON · snap get -d prints the document as JSON a value that comes back afteran unset was put back bythe configure hook
snap set acme-agent interval=60 server=https://telemetry.example stores a number and a string; snap set proxy.host and proxy.port adds a nested proxy map; snap get lists interval, proxy as {...} and server; snap get acme-agent proxy.port prints 3128; snap unset acme-agent proxy.port removes port, as does snap set acme-agent proxy.port!; a value that returns after unset was put back by the configure hook

Options are a JSON document per snap. Values are parsed as JSON and fall back to strings; a dotted key addresses a nested map. snap unset key or snap set key! removes a key.

Server and interval are the simple case. What about a proxy, with a host and a port? Snapd keeps one JSON document per snap. What you type is read as JSON if it parses, so sixty is a number; anything else stays a string. A dot in the key goes one level down. Snap get lists the top level, with the proxy folded into braces. Ask for proxy.port to look inside, or add -d for the whole document. Snap unset removes a key, and so does an exclamation mark. Snapd has no defaults: if a value returns after an unset, the configure hook put it back.

03 The hook has the last word

ONE CHANGE, ONE HOOK configure-snap · Change configuration of "acme-agent" snaprun-hook · Run configure hook of "acme-agent" snap meta/hooks/configureinterval="$(snapctl get interval)"if [ "$interval" -lt 10 ]; thenecho "interval must be at least 10" >&2; exit 1fisnapctl restart acme-agent.agent sees the proposed value,not the stored onesnapctl set writes into it too exit 0 → the transaction is committedthe restart runs after the hook, in the same change $ snap set acme-agent interval=5exit 1 → the change failssnap get acme-agent interval still prints 60 limit: 5 minutes · no configure hook: snap "<name>" has no "configure" hook
snap set creates a configure-snap change with one run-hook task. The configure hook script reads interval with snapctl get, exits 1 if it is below 10, and otherwise asks snapctl restart acme-agent.agent. snapctl get sees the proposed value and snapctl set writes into the same transaction. Exit 0 commits the transaction and the restart runs after the hook in the same change; snap set acme-agent interval=5 makes the hook exit 1, the change fails and snap get still prints 60. The hook has 5 minutes; a snap with no configure hook cannot be set

snap set creates a configure-snap change with one run-hook task. The values sit in a transaction that the hook reads with snapctl get and writes with snapctl set; it is committed only if the hook succeeds within 5 minutes.

You type interval=5 by mistake, and the agent can't cope with five seconds. Where does it stop? Snap set creates a configure-snap change with one task: run the configure hook. First, snapd puts your values in a transaction for the hook. The hook's snapctl get reads that transaction, so it sees the proposal; snapctl set writes into it. If it exits cleanly, the transaction is committed, and any restart it asked for runs afterwards, in the same change. This one exits with an error: the change fails and the interval stays sixty. The hook gets five minutes, and a snap without one can't be set at all.

04 Three moments, one hook

WHEN IT RUNS configure hook first installinstall hookdefault-configureservices startgadget defaults, if any default-configure runs before the services start; configure after refresh 41 → 42post-refresh hookservices startnothing new: a chance to migrate options snap set$ snap set acme-agent interval=60the proposed values a failing configure hook fails the install or refresh toosnap revert puts back the options saved for that revision
Three lanes lead to one configure hook. First install: install hook, default-configure, services start, then configure with the gadget defaults if any; default-configure runs before the services start and configure after. Refresh 41 to 42: post-refresh hook, services start, then configure with nothing new, a chance to migrate options. snap set: configure gets the proposed values. A failing configure hook fails the install or refresh; snap revert puts back the options saved for that revision

The configure hook runs on first install (with gadget defaults), on every refresh (with no changes) and on snap set. default-configure runs once, before services start. A failing hook fails the install or refresh.

That configure hook doesn't only run when someone types snap set. It runs at two other moments, and each time it's handed something different. On first install it runs after the services start, with the gadget's defaults for this snap, if any. That's too late for a daemon that needs settings before its first start, so there's the default-configure hook: it runs before the services, only on first install. On every refresh, configure runs with nothing proposed, so the new revision can migrate its options. On snap set, it gets your values. A failure fails the install or refresh, and a revert restores that revision's saved options.

05 Defaults from the gadget for Ubuntu Core developers for app developers

GADGET DEFAULTS gadget.yamldefaults:<snap id of acme-agent>:server: https://telemetry.exampleinterval: 300 system:service:ssh:disable: truesystem options use the key system first installif the snap has onedefault-configureservices startconfigure otherwise here no configure hook: defaults droppedsilently (a known snapd bug) used once, at first install · a snap without a snap id gets none
gadget.yaml defaults: maps the snap id of acme-agent to server and interval 300, and the key system to service.ssh.disable true. At first install the defaults go to default-configure, before services start, if the snap has that hook, and otherwise to configure. Without a configure hook the defaults are dropped silently, a known snapd bug. Defaults are used once, at first install; a snap without a snap id gets none

defaults: in gadget.yaml maps a snap id to option values. They are applied once at first install, by default-configure if the snap has it and otherwise by configure. The key system holds system options. A snap with no configure hook gets no defaults and no message (a snapd bug: the check meant to report it is never reached).

snap set works for one gateway. You're building a thousand. Where do the first values come from, before anyone has logged in? gadget.yaml has a defaults section that maps a snap-id to options. The id, not the name, so only the store snap with that identity gets them. System options sit under the key system. At first install, if the snap has a default-configure hook, the defaults are loaded there, before the services start. If not, the configure hook gets them. Without a configure hook a snap simply doesn't get them, and snapd doesn't say so: a known bug. They're applied once; a refresh doesn't repeat them.

06 "snap set system: the options of the system itself"

SYSTEM OPTIONS $ snap set system service.ssh.disable=true snapd (configcore), no hook script1. is each changed key supported?cannot set "core.colour": unsupported system option 2. every handler validates the result3. apply every changed option the devicessh stopped and disabled $ snap get system system.hostnameacme-gw-01some options are readfrom the system,not from snapd's state stored under the snap name core · many options apply on Ubuntu Core only
snap set system service.ssh.disable=true goes to snapd's configcore code, which checks that each changed key is supported (an unknown key gives cannot set core.colour: unsupported system option), has every handler validate the result and then applies every changed option; ssh is stopped and disabled on the device. snap get system system.hostname reads the hostname from the system. Options are stored under the snap name core and many apply on Ubuntu Core only

snap set system stores options under core. snapd runs no hook script: it rejects unsupported keys, validates all changed options, then applies them. Some, such as system.hostname, are read from the system.

Not every setting belongs to a snap. Whether ssh runs, what it's called on the network: whose configure hook handles those? Snapd's own. You use the same commands with the name system, and there's no hook script; snapd runs the configure task in its own code. First every changed key is checked against the supported list; one unknown key stops the whole command. Then every handler validates the result, and only then does each apply its part. A few, like the hostname, are read back from the system, so snap get shows the truth. They're stored under the name core, and many apply only on Ubuntu Core.

07 Confdb, in one picture

CONFDB $ snap get acme-agent intervalacme-agent's own optionseverything so far in this deck confdbproxy schema · signed assertionviewview acme-agentacme-vpnacme-updaterthrough confdb plugs; their hooks can check,save and observe changes $ snap get <account-id>/<confdb-schema>/<view> … with the experimental flag off:the "confdb" feature is disabled:set 'experimental.confdb' to true its own flags: --wait-for, --with, --default
snap get acme-agent interval reaches acme-agent's own options, everything so far in this deck. Confdb is separate: a schema, a signed assertion, defines views; acme-agent, acme-vpn and acme-updater attach to the views through confdb plugs, sharing one proxy address, and take part through hooks. snap get account-id/confdb-schema/view reaches confdb. With the feature off: the confdb feature is disabled: set experimental.confdb to true. Its own flags are --wait-for, --with and --default

Confdb is a separate, schema-based mechanism for configuration shared between snaps, such as one proxy address for three snaps, behind experimental.confdb. snap get, set and unset use it when the first argument is <account-id>/<confdb-schema>/<view>.

Every setting so far has belonged to exactly one snap, and no other snap could read it. But on the gateway, acme-agent, acme-updater and acme-vpn all need the same proxy address. That's what confdb is for. A schema, published as a signed assertion under an account, defines the proxy data and views onto it. Each of the three snaps reaches a view through a plug and takes part through hooks. You reach it with the commands you know: when the first argument has three parts, account, schema and view, snap get talks to confdb. It's still experimental, behind a feature flag, with a few flags of its own.

08 Where to go from here

ROADS Configuration snapctl: configuration and healthinside the configure hook Hooks: install, configure, refresh, removewhere the hooks sit Servicesrestarting to apply a setting Refreshthe refresh options Hooks: confdb hooksconfdb in depth: the hooksAssertions: confdb and messagesconfdb in depth: the schema
Roads from configuration: snapctl configuration and health, lifecycle hooks, services, refresh, and the pair of confdb hooks and confdb assertions

Roads: snapctl configuration commands, lifecycle hooks, services, refresh options and the two confdb decks.

Snapd keeps the record and the snap decides what's valid. Here's where to follow each thread. If you write the configure hook, the snapctl deck covers get, set and unset from the inside. The lifecycle hooks deck places configure and default-configure among the other hooks of an install. The services deck shows how a restart applies a new setting. The refresh deck's reference lists the refresh options. And for confdb, there are two decks side by side: one for its hooks, and one for the assertions that define a schema.

Read more

Commands

CommandEffect
snap get <snap>list top-level options as a Key Value table; nested maps show as {...}
snap get <snap> <key>...one scalar key prints the bare value; several keys print a table
snap get -d <snap> [<key>]print a JSON document
snap get -l <snap>force the table form
snap get -t <snap> <key>strict typing: strings are printed quoted
snap set <snap> <key>=<value>...propose values; parsed as JSON, else kept as a string
snap set -s <snap> <key>=<value>treat the value as a string
snap set -t <snap> <key>=<value>require valid JSON
snap set <snap> <key>!remove the key
snap unset <snap> <key>...remove keys
snap set system <key>=<value>set a system option

When standard output is not a terminal, a map is printed as JSON with a warning; use -d or -l to choose.

Messages

MessageMeaning
snap "<name>" has no configurationnothing is stored for the snap; with -d the output is {}
snap "<name>" has no "<key>" configuration optionthat key is not set
snap "<name>" has no "configure" hooksnap set on a snap without a configure hook
snap "<name>" option "<key>" is not a mapa dotted key goes through a value that is not a map
invalid option name "<key>": must only contain dashes and lowercase alphanumerics and may not begin nor end with a dashkey syntax
cannot configure the "snapd" snap, please use "system" instead
cannot configure snap "<name>" because it is of type 'base'
cannot use -t and -s together
cannot set "core.<key>": unsupported system optionunknown system option
cannot use default-configure hook for snap "<name>", no configure hook
cannot apply gadget config defaults for snap "<name>", no configure hooknot reached in practice: a snap without a configure hook gets the defaults dropped silently (snapd bug)

When the hooks run

Momentdefault-configureconfigureGiven
First installyes, before services startyes, after services startgadget defaults, if any
Refreshnoyes, after services startnothing
snap set, snap unsetnoyesthe proposed changes
Restore of a snapshotnono
Revertnoyesnothing; the options saved for the target revision are restored first

Neither hook runs for base snaps or the snapd snap. The configure hook has 5 minutes. Inside a base older than core26 a bad field name in a JSON value is a warning; from core26 and for system options it is an error.

Inside the hook, snapctl get reads the proposed values and snapctl set and snapctl unset write into the same transaction; they are committed with the hook's success. See snapctl: configuration and health.

Options and revisions

  • At each refresh the current options are saved under the old revision's number.
  • A revert restores the options saved for the target revision; a refresh does not.
  • Removing the last revision deletes the options; discarding a revision discards its saved copy.
  • A snapshot carries the options and a restore replaces them.

System options

Keys as typed after snap set system. "Core" means the option applies on Ubuntu Core only.

FamilyKeysWhere
refreshrefresh.hold, refresh.schedule, refresh.timer, refresh.metered, refresh.retain, refresh.rate-limit, refresh.max-inhibition-daysall
snapshotssnapshots.automatic.retentionall
proxyproxy.http, proxy.https, proxy.ftp, proxy.no-proxy; proxy.storeCore; proxy.store all
storestore.access, store-certs.<name>store.access Core
experimentalexperimental.<feature>all
serviceservice.ssh.disable, service.ssh.listen-address, service.rsyslog.disable, service.console-conf.disable, service.systemd-resolved.disableCore
systemsystem.hostname, system.timezone, system.motd, system.power-key-action, system.ctrl-alt-del-action, system.disable-backlight-service, system.kernel.printk.console-loglevel, system.kernel.cmdline-append, system.kernel.dangerous-cmdline-append, system.coredump.enable, system.coredump.maxuse, system.network.netplanCore
networknetwork.disable-ipv6Core
watchdogwatchdog.runtime-timeout, watchdog.shutdown-timeoutCore
swap, tmpswap.size, tmp.sizeCore
journaljournal.persistentCore
pi-configpi-config.<key>Core
usersusers.create.automatic, users.lockoutusers.lockout Core
homedirshomedirsall
resilienceresilience.vitality-hintall
disk-reservationdisk-reservation.sizeall
debugdebug.snapd.log, debug.systemd.log-levelthe systemd level Core
pkipki.certs.custom.<...>Core

Read from the system rather than from snapd's state: system.hostname, system.timezone, system.network.netplan, system.motd, pki.certs.custom.

for Ubuntu Core developers for app developers

Gadget defaults

defaults:
  <snap-id>:
    server: https://telemetry.example
    interval: 300
  system:
    service:
      ssh:
        disable: true
  • Keyed by snap id; a snap without a snap id gets none.
  • Applied once, at first install.
  • system holds system options and is preferred over the core snap's id. A subset (experimental flags and users settings) is applied early, before seeding.

Confdb

A separate mechanism behind experimental.confdb. snap get, snap set and snap unset use it when the first argument is <account-id>/<confdb-schema>/<view>; the flags --wait-for, --with and --default apply only there. See Hooks: confdb hooks and Assertions: confdb and messages.

Further reading

Roads from here

RUNNING SNAPS

SNAPCTL · the snap's API into snapd

ASSERTIONS · signed statements snapd trusts

HOOKS · code snapd runs inside a snap

UBUNTU CORE · install and recovery