snapctl: device and system

snapctl command group for Ubuntu Core developers for app developers for snapd developers for administrators for users

Seven snapctl commands that read the device or act on the host for a snap. model and system-mode read the model and the boot mode; kmod loads kernel modules and mount and umount manage systemd mount units within what the snap's plugs allow; fde-setup-request and fde-setup-result carry the full disk encryption handshake between snapd and the kernel snap's fde-setup hook. None of them creates a change.

On the map: snapctl district

▶ Watch this deck — 9 scenes, ~6 min

01 Seven commands and no change

SEVEN COMMANDS AND NO CHANGE acme-agenthook or appsnapctl …snapd reads the device · any usermodel · system-mode acts on the host · root · checks a plugkmod · mount · umount answers snapd · fde-setup hook onlyfde-setup-request · fde-setup-result $ snap changes(nothing from these seven)changeanswered inline: no change, no task
A hook or app inside acme-agent calls snapctl; snapd answers seven commands in three groups: model and system-mode read the device, kmod, mount and umount act on the host within a plug, fde-setup-request and fde-setup-result answer the fde-setup hook; none of them creates a change

Seven commands, three shapes: read the device (model, system-mode), act on the host within a plug (kmod, mount, umount), answer the FDE hook (fde-setup-request, fde-setup-result). None creates a change.

acme-agent sometimes needs to ask about the gateway it runs on, or to touch it. Which model is this? Am I being installed? Seven snapctl commands cover that, from a hook or an app. Model and system-mode read the device; they're the only two a non-root process may call. Kmod, mount and umount act on the host; they need root, and kmod and mount first check the snap's connected plug. fde-setup-request and fde-setup-result only work inside the kernel snap's fde-setup hook. snapd answers all seven on the spot, so none of them shows up in snap changes.

02 Who may read the model for Ubuntu Core developers for app developers for snapd developers

WHO MAY READ THE MODEL acme-agent: hook or app$ snapctl model snap type is gadget or kernelallowed store publisher account = model brand-idallowed installed --dangerousno snap-id: no publisher: cannot match a snapd-control connection for the snapallowedinsufficient permissions to get model assertion for snap "acme-agent" $ snapctl modelbrand-id: acmemodel: acme-gatewayserial: -- (device not registered yet)architecture: amd64base: core24gadget: pckernel: pc-kernelthe only flags--json --assertionno --verbose, no --serialoutput is always the full form
snapctl model from acme-agent passes three checks in order: gadget or kernel snap type, store publisher equal to the model brand, a snapd-control connection; a snap installed with --dangerous cannot pass the brand check; anything else is refused; the output shows brand, model, serial, architecture, base, gadget and kernel

Allowed: gadget or kernel snaps, snaps from the model's brand publisher, snaps with a snapd-control connection. A --dangerous snap has no snap-id and cannot be same-brand. Flags: --json, --assertion.

acme-agent wants to report which model and serial it's running on. Snapctl model prints both, and any user may call it, but snapd first checks which snap is asking. A gadget or kernel snap may always read it, so pc and pc-kernel can. Next, a snap whose store publisher is the model's brand: acme-agent comes from acme, so it passes. A copy installed with --dangerous has no snap-id, so it has no publisher and can't match. Last, a snap with a snapd-control connection. Everyone else gets insufficient permissions. The output is always the full form; json and assertion only change the format.

03 Which mode am I in for Ubuntu Core developers for app developers for snapd developers

WHICH MODE AM I IN $ snapctl system-modesystem-mode: installseed-loaded: truefactory: truestorage-encrypted: managed runinstallrecoverfactory-resetfactory-reset: missing from the helprun: also on classic and UC16/18 always printedonly for an image flagged factory · not a security signalonly when snapd manages the encryption key # pc gadget: meta/hooks/install-device (nested test)if snapctl system-mode | grep "factory-reset"; then# write the factory-reset udev ruleexit 0fi# write the install-mode modprobe.d and# modules-load.d files factory-reset: udev ruleinstall: two config files
snapctl system-mode output with system-mode, seed-loaded, factory and storage-encrypted lines; the four modes run, install, recover and factory-reset; a gadget install-device hook that branches on factory-reset versus install

system-mode is run, install, recover or factory-reset. factory: true is a convenience flag, not a security signal; storage-encrypted: managed appears only when snapd manages the key.

The gateway's gadget hook should do one thing on a fresh install and another during a factory-reset. How does it tell them apart? It asks snapctl system-mode, which needs no plug and no root. It prints the mode: run, install, recover or factory-reset. The help lists only three, but factory-reset is reported too, and systems without modes, like classic, report run. seed-loaded is always printed. Factory: true appears only for an image built with the factory flag, and the help warns against basing security decisions on it. storage-encrypted: managed appears only when snapd manages the key. snapd's own test hook branches exactly like that.

04 The fde-setup handshake for Ubuntu Core developers for snapd developers

THE FDE-SETUP HANDSHAKE snapd (device manager)kernel snap: fde-setup hookephemeral: no task · 5 minute timeout · kernel snap onlyrun fde-setupthe request is stored in the hook's context $ snapctl fde-setup-request{"op":"features"} $ echo '{"features":[]}' | snapctl fde-setup-resultthe only snapctl command that forwards stdin hook exits: snapd reads fde-setup-result, checks the features {"op":"initial-setup","key":…,"key-name":…}{"sealed-key":…,"handle":…}seals the install keysa later hook run
Sequence between snapd and the kernel snap's fde-setup hook: snapd runs the hook with a request in its context, the hook reads it with snapctl fde-setup-request, answers by piping JSON into snapctl fde-setup-result, snapd reads the result when the hook exits; a second round for initial-setup returns a sealed key and handle

snapd puts the request in the hook's context; the hook reads it with snapctl fde-setup-request and answers with … | snapctl fde-setup-result. Ops: features and initial-setup. The initramfs runs the fde-setup binary directly, without snapctl.

Some kernel snaps handle disk encryption themselves, through an fde-setup hook. How do snapd and that hook talk? snapd runs the hook for the model's kernel only, outside any task, with a five minute timeout, and puts a request in its context. The hook reads it with snapctl fde-setup-request: a JSON line whose op is features or initial-setup. It answers by piping JSON into snapctl fde-setup-result, the only snapctl command that reads standard input, and snapd reads the answer when the hook exits. Features asks what the hardware supports; initial-setup hands over a key and expects it back sealed, with a handle.

05 Declare first, load later for Ubuntu Core developers for app developers for snapd developers

DECLARE FIRST, LOAD LATER # meta/snap.yaml, trimmedplugs:kernel-module-load:modules:- name: arc4load: on-boot- name: xcbcload: dynamic- name: md4load: dynamicoptions: something=ok- name: wp512load: dynamicoptions: "*" $ snapctl kmod insert xcbcoksnapdmodprobe xcbc · root, on the hostnothing runs in the snap · no change, no task $ snapctl kmod insert md4 something=okrefused$ snapctl kmod insert wp512 opt1=v1 opt2=v2ok $ snapctl kmod insert arc4refusedcannot load module "arc4": required interface not connected $ snapctl kmod remove xcbcremove is gated the same way: only load: dynamic entries
The kernel-module-load plug of a test snap lists arc4 on-boot and xcbc, md4 and wp512 as load dynamic; snapctl kmod insert xcbc succeeds and snapd runs modprobe on the host; md4 with options is refused, wp512 with any options succeeds because its entry has options star; arc4 is refused; kmod remove follows the same entries

Only load: dynamic entries of the connected kernel-module-load plug can be inserted or removed; options need options: "*". snapd runs modprobe on the host. The snap and modules come from snapd's tests.

Say a snap on the gateway needs a kernel module now and then. Can it just run modprobe? Not from inside its sandbox. Instead its kernel-module-load plug, a super-privileged one, lists the modules up front, and snapctl kmod acts only on an entry with load: dynamic, the exact name, and the plug connected. snapd's own test snap shows the rules. Snapctl kmod insert xcbc makes snapd run modprobe on the host, as root. Passing options needs options: "*": md4 lists fixed options, so it can't take any, while wp512 takes whatever you pass. Arc4 is marked on-boot, so it's refused. Kmod remove follows the same entries.

06 snapctl mount is a systemd unit for Ubuntu Core developers for app developers for snapd developers

SNAPCTL MOUNT IS A SYSTEMD UNIT # plug of test-snapd-mount-controlmntctl:interface: mount-controlmount:- what: /var/tmp/**where: $SNAP_COMMON/target1options: [rw, bind]persistent: true $ snapctl mount --persistent -o bind,rw/var/tmp/test-snapd-mount-control/var/snap/test-snapd-mount-control/common/target1source → what · target → whereevery -o option listed · --persistent → persistent: trueno -t given: the entry must have no type snapd[Unit]Description=Mount unit for test-snapd-mount-control,revision x1 via mount-control[Mount]What=/var/tmp/test-snapd-mount-controlWhere=/var/snap/test-snapd-mount-control/common/target1Options=bind,rw[Install] …X-SnapdOrigin=mount-controlx1 is an example revision (a locally installed snap) /run/systemd/systemdefault: gone after reboot/etc/systemd/system--persistent: survives reboot enable and startmounted in the host namespace,visible to the snap $ snapctl umount /var/snap/…/target1removes the mount-control unit for that mount point
A mount-control plug entry and a snapctl mount command whose source, target, options and --persistent flag each match a line of the entry; snapd writes a systemd mount unit with X-SnapdOrigin=mount-control, into /run/systemd/system by default or /etc/systemd/system with --persistent, and starts it in the host namespace; snapctl umount removes the mount-control unit for that mount point

Every argument must match one mount-control plug entry. snapd then writes, enables and starts a .mount unit: /run/systemd/system by default, /etc/systemd/system with --persistent. snapctl umount removes the mount-control unit for that mount point. The snap comes from snapd's tests.

Say a snap needs a bind mount that's still there after a reboot. What does snapctl mount do? snapd checks every argument against one entry of the connected mount-control plug: the source against what, the target against where, each option against its options, and persistent only if the entry allows it. snapd writes a systemd mount unit marked as made by mount-control. Without persistent it goes in /run/systemd/system and is gone at reboot; with persistent it goes in /etc/systemd/system. It's enabled and started on the host, where the snap sees it too. Snapctl umount removes the unit for a mount point.

07 What the machine shows for users for administrators

WHAT THE MACHINE SHOWS a snap with mount-control or kernel-module-load connected mounts and loads modules while it runs; you run none of these commands $ systemctl list-units --type=mountvar-snap-…-target1.mount loaded active mountedMount unit for acme-agent,revision 42 via mount-controlcolumns shortened; the snap and revision are examplesa snap's mountan ordinary systemd mount unit,named in its description a loaded modulelisted by lsmod like any other $ snap changesnothing about the mount or the module:no change, no task $ sudo snap remove acme-agentsnap removethe snap's mount units are removed
What an administrator sees: a snap's mount listed by systemctl as a mount unit named for the snap, a loaded module like any other, nothing in snap changes, and snap remove removing the snap's mount units

snapctl mounts are systemd .mount units described as "Mount unit for <snap>, revision <rev> via mount-control"; they show in systemctl, not in snap changes. snap remove cleans them up. The snap name and revision are examples.

You list the mounts on the gateway and find one you didn't make. Where did it come from? A snap that holds the mount-control or kernel-module-load interface can mount filesystems and load kernel modules while it runs; you don't run these commands yourself. Its mounts show up as ordinary systemd mount units, and the description names the snap and its revision. Its modules look like any other loaded module. Neither leaves a change, so snap changes and snap tasks say nothing about them. And when you remove the snap, its mount units go with it.

08 Where to go from here

ROADS snapctl: device and system snapctl: how it workshow a call reaches snapdconfiguration and healththe other snapctl commandsservices, refresh, changesthe commands that create changes the deviceModel, gadget and kernelthe model assertionBoot and recoveryboot modes and encryptionHooksinstall-device and fde-setup interfacesfiles, data and snapdsnapd-controlsystem control, observekernel-module-load: modulesdevices and storagemount-control: mount
Roads from snapctl device and system: three snapctl decks at the top, the model, boot and recovery and hooks decks on the left, and three interface families on the right

Roads: how snapctl works, the configuration and health commands, the commands that create changes, the model and the gadget and kernel snaps, boot modes and encryption, the hooks, and the snapd-control, kernel-module-load and mount-control interfaces.

Two questions about the device, three ways to touch the host, and one handshake for encryption. Here's where the rest lives. The snapctl deck shows how a call reaches snapd and finds its context. The other two command groups cover configuration and health, and services, refresh and changes, the commands that do create changes. The model deck covers the model assertion and the gadget and kernel snaps; boot and recovery covers modes and full disk encryption; the hooks deck covers install-device and fde-setup. And three interface decks hold the plugs these commands check: snapd-control, kernel-module-load, and mount-control.

09 Every command at a glance

EVERY COMMAND AT A GLANCE commandwherewhoeffect fde-setup-requestonly in the fde-setup hookroot onlyreads only fde-setup-resultonly in the fde-setup hookroot onlychanges state directly kmodfrom apps and hooksroot onlychanges state directly modelfrom apps and hooksnon-root allowedreads only mountfrom apps and hooksroot onlychanges state directly system-modefrom apps and hooksnon-root allowedreads only umountfrom apps and hooksroot onlychanges state directly
Every snapctl command in this group with where it may run, who may run it, and what it does to state

7 commands: 2 non-root, 0 create or join a change, 0 saved when the hook or call ends, 2 hook-specific.

All 7 commands of this group at a glance. 2 may run as non-root: model, system-mode. 2 work only inside one particular hook: fde-setup-request in fde-setup, fde-setup-result in fde-setup. 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 checks and outputs that the slides only sketch.

for Ubuntu Core developers for app developers for snapd developers

Who may run what

CommanduidFurther check
modelanythe snap is a gadget or kernel, or its store publisher is the model's brand, or a snapd-control connection names it
system-modeanynone
kmod insert, kmod removerootan active kernel-module-load connection with a modules entry for that exact name and load: dynamic; options need options: "*"
mountrootan active mount-control connection with a mount entry that matches type, source, target, every option and --persistent
umountrootnone beyond the unit list; the mount point is compared as a string. The list matches unit descriptions by prefix, so for snap foo it also holds the mount-control units of foobar and foo_x (a snapd bug)
fde-setup-request, fde-setup-resultrootonly in the fde-setup hook, which snapd runs only for the model's kernel snap

A snap installed with --dangerous has no snap ID and so no publisher; it cannot pass the brand check of model.

for Ubuntu Core developers for app developers for snapd developers

snapctl model and snap model

snapctl modelsnap model
Outputalways the full formshort form; --verbose for the full form
Flags--json, --assertion--assertion, --verbose, --serial, --abs-time, --color
Serialprinted, -- (device not registered yet) before registrationwith --serial
In a remodel changea hook sees the new model

for Ubuntu Core developers for app developers for snapd developers

snapctl system-mode

LineWhen it appears
system-mode:always: run, install, recover or factory-reset; run on classic and on Ubuntu Core 16 and 18
seed-loaded:always
factory: trueonly when the image was built with the factory flag; not meant for security decisions
storage-encrypted: managedonly when snapd manages a primary encryption key

Before the model is acknowledged the command fails with cannot report system mode information before device model is acknowledged.

for app developers for Ubuntu Core developers for snapd developers for administrators

Mounts made with snapctl mount

ItemValue
Unit descriptionMount unit for <snap>, revision <rev> via mount-control
MarkerX-SnapdOrigin=mount-control
Without --persistentunit in /run/systemd/system, gone after a reboot
With --persistentunit in /etc/systemd/system, mounted again at boot
Namespacethe host's; the snap sees the mount too
Removalsnapctl umount <where>; snap remove removes the snap's units with its last revision, and through the same prefix match can also remove those of a snap whose name starts with this one

for Ubuntu Core developers for snapd developers

The fde-setup protocol

Request (snapctl fde-setup-request)Expected answer (to snapctl fde-setup-result)
{"op":"features"}{"features":[...]} or {"error":"..."}; inline-crypto-engine in the list selects LUKS with the inline crypto engine
{"op":"initial-setup","key":...,"key-name":...}{"sealed-key":...,"handle":...}

snapd asks for features when it checks encryption support at install, and for initial-setup when it seals keys during install, factory reset and reprovisioning. The result is stored unparsed and read when the hook exits; only the last call counts. In the initramfs, snap-bootstrap runs the kernel's fde-setup binary directly with the request on standard input; unlocking at boot uses fde-reveal-key.

Further reading

Roads from here

SNAPCTL · the snap's API into snapd

INTERFACE FAMILIES · every interface, grouped by what it touches

HOOKS · code snapd runs inside a snap

UBUNTU CORE · boot

UBUNTU CORE · install and recovery