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
01 Seven commands and no 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
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
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
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
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
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
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: 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
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
| Command | uid | Further check |
|---|---|---|
model | any | the snap is a gadget or kernel, or its store publisher is the model's brand, or a snapd-control connection names it |
system-mode | any | none |
kmod insert, kmod remove | root | an active kernel-module-load connection with a modules entry for that exact name and load: dynamic; options need options: "*" |
mount | root | an active mount-control connection with a mount entry that matches type, source, target, every option and --persistent |
umount | root | none 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-result | root | only 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 model | snap model | |
|---|---|---|
| Output | always the full form | short form; --verbose for the full form |
| Flags | --json, --assertion | --assertion, --verbose, --serial, --abs-time, --color |
| Serial | printed, -- (device not registered yet) before registration | with --serial |
| In a remodel change | a hook sees the new model |
for Ubuntu Core developers for app developers for snapd developers
snapctl system-mode
| Line | When 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: true | only when the image was built with the factory flag; not meant for security decisions |
storage-encrypted: managed | only 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
| Item | Value |
|---|---|
| Unit description | Mount unit for <snap>, revision <rev> via mount-control |
| Marker | X-SnapdOrigin=mount-control |
Without --persistent | unit in /run/systemd/system, gone after a reboot |
With --persistent | unit in /etc/systemd/system, mounted again at boot |
| Namespace | the host's; the snap sees the mount too |
| Removal | snapctl 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
- The kernel-module-load interface: the
modulesattribute and itsloadandoptionskeys. - The mount-control interface: the
mountattribute andsnapctl mountexamples. - Full disk encryption hooks: the fde-setup and fde-reveal-key hooks of a kernel snap.
- Model assertion: the headers
snapctl modelprints. - Recovery modes: what run, install, recover and factory reset mean.
Roads from here
SNAPCTL · the snap's API into snapd
- snapctl: how it works — how a snapctl call reaches snapd and finds its context
- "snapctl: configuration and health" — the configuration and health commands
- snapctl: services, refresh and changes — the commands that do create changes
INTERFACE FAMILIES · every interface, grouped by what it touches
- "Interfaces: files, data and snapd's own API" — the snapd-control interface
- "Interfaces: system control and observe" — the kernel-module-load interface and its modules attribute
- "Interfaces: devices and storage" — the mount-control interface and its mount attribute
HOOKS · code snapd runs inside a snap
- Hooks: how they work — the install-device and fde-setup hooks
UBUNTU CORE · boot
- Ubuntu Core: how a device boots and recovers — boot modes and full disk encryption
UBUNTU CORE · install and recovery
- Model, gadget and kernel — the model assertion and the gadget and kernel snaps