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
01 snapd keeps the settings, the snap decides
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
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
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
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
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"
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 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: 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
| Command | Effect |
|---|---|
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
| Message | Meaning |
|---|---|
snap "<name>" has no configuration | nothing is stored for the snap; with -d the output is {} |
snap "<name>" has no "<key>" configuration option | that key is not set |
snap "<name>" has no "configure" hook | snap set on a snap without a configure hook |
snap "<name>" option "<key>" is not a map | a 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 dash | key 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 option | unknown system option |
cannot use default-configure hook for snap "<name>", no configure hook | |
cannot apply gadget config defaults for snap "<name>", no configure hook | not reached in practice: a snap without a configure hook gets the defaults dropped silently (snapd bug) |
When the hooks run
| Moment | default-configure | configure | Given |
|---|---|---|---|
| First install | yes, before services start | yes, after services start | gadget defaults, if any |
| Refresh | no | yes, after services start | nothing |
snap set, snap unset | no | yes | the proposed changes |
| Restore of a snapshot | no | no | |
| Revert | no | yes | nothing; 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.
| Family | Keys | Where |
|---|---|---|
| refresh | refresh.hold, refresh.schedule, refresh.timer, refresh.metered, refresh.retain, refresh.rate-limit, refresh.max-inhibition-days | all |
| snapshots | snapshots.automatic.retention | all |
| proxy | proxy.http, proxy.https, proxy.ftp, proxy.no-proxy; proxy.store | Core; proxy.store all |
| store | store.access, store-certs.<name> | store.access Core |
| experimental | experimental.<feature> | all |
| service | service.ssh.disable, service.ssh.listen-address, service.rsyslog.disable, service.console-conf.disable, service.systemd-resolved.disable | Core |
| system | system.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.netplan | Core |
| network | network.disable-ipv6 | Core |
| watchdog | watchdog.runtime-timeout, watchdog.shutdown-timeout | Core |
| swap, tmp | swap.size, tmp.size | Core |
| journal | journal.persistent | Core |
| pi-config | pi-config.<key> | Core |
| users | users.create.automatic, users.lockout | users.lockout Core |
| homedirs | homedirs | all |
| resilience | resilience.vitality-hint | all |
| disk-reservation | disk-reservation.size | all |
| debug | debug.snapd.log, debug.systemd.log-level | the systemd level Core |
| pki | pki.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.
systemholds 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
- Configure snaps: get, set and unset with nested keys.
- Set system options:
snap set systemand the doubledsystem.prefix. - System options: one section per system option.
- Supported snap hooks: when
configureanddefault-configurerun. - Use snapctl:
snapctl get,setandunsetinside the snap. - Confdb configuration mechanism: the cross-snap configuration mechanism.
Roads from here
RUNNING SNAPS
- Services — restarting a service to apply a setting
- Refresh — the refresh options among the system options
- Confdb: configuration that does not belong to one snap — why shared configuration exists
SNAPCTL · the snap's API into snapd
- "snapctl: configuration and health" — snapctl get and set inside the configure hook
ASSERTIONS · signed statements snapd trusts
- Assertions: confdb and messages — the assertions that define a confdb schema
HOOKS · code snapd runs inside a snap
- Hooks: install, configure, refresh, remove — where configure and default-configure sit in an install
- Hooks: confdb hooks — the hooks behind a confdb view
UBUNTU CORE · install and recovery
- Model, gadget and kernel — gadget.yaml where the defaults live
- A device set up before anyone logs in — settings a device ships with