snapctl: how it works
the shared mechanism for app developers for Ubuntu Core developers for snapd developers for administrators for users
snapctl is the command a snap runs from its hooks, apps and services to talk to snapd without the snapd-control interface that the full REST API needs. Each call is one POST to /v2/snapctl on /run/snapd-snap.socket carrying a cookie that names the snap; snapd checks the uid, the context and the command's own rules, then runs the command inside snapd.
On the map: snapctl district
01 Why snapctl and not the REST API for app developers for Ubuntu Core developers for snapd developers for administrators
The full REST API on /run/snapd.socket is open to a confined snap only through snapd-control, which grants what the snap command can do. /run/snapd-snap.socket is open to every confined snap, and /v2/snapctl on it needs no interface: the cookie in each call names the snap.
acme-agent's configure hook needs the server address you've just set. The snap command asks snapd's REST API for things like that, so why can't the hook? That API listens on snapd's main socket, and a confined snap reaches it only through the snapd-control interface. Connect that, and root in the snap can install, remove and connect anything, which is a lot to hand over for reading one setting. There is a second socket that every confined snap can reach, and one endpoint there needs no interface at all: /v2/snapctl. The cookie in each call names the snap, and the commands act for that snap.
02 One call, one request for app developers for Ubuntu Core developers for snapd developers for administrators
snapctl is a thin client: each call is one POST /v2/snapctl on /run/snapd-snap.socket with the cookie and the arguments. The command runs inside snapd, and the reply carries its output. The address in the drawing is an example.
So what actually happens when the configure hook runs snapctl get server? Less than you might expect on the snap's side. The snapctl binary reads SNAP_COOKIE from its environment and sends one POST to /v2/snapctl on the snapd-snap.socket: the cookie and the arguments, nothing more. Inside snapd, the cookie becomes a context, the caller's uid is checked, the arguments are parsed, and get runs in the daemon. The reply carries stdout and stderr, and snapctl prints them and exits. So every snapctl command is really code in snapd. The client is the same thin messenger for all of them.
03 The cookie names the snap for app developers for Ubuntu Core developers for snapd developers for administrators
Hooks get a SNAP_COOKIE that lives for one hook run; apps and services get the snap's cookie from /var/lib/snapd/cookie/snap.acme-agent, which lives from first install to the removal of the last revision. The socket's peer credentials supply only the uid.
How does snapd know it's acme-agent calling, not another snap? From the cookie, and nothing else. When snapd runs a hook, it makes a random context id for that one run, puts it in SNAP_COOKIE, and forgets it when the hook ends. When the agent service starts, snap-confine reads the snap's cookie file, which only root can read, and sets SNAP_COOKIE; it leaves a hook's value alone. snapd looks a cookie up among running hooks first, then among snap cookies. The socket's peer credentials only supply the uid. The snap cookie is made at first install, survives refreshes, and goes with the last revision.
04 Changes land when the hook succeeds for app developers for Ubuntu Core developers for snapd developers
In a hook, snapctl set, snapctl set-health and confdb writes take effect only if the hook exits 0; snapd commits them anyway for hooks whose failure it ignores, such as remove. From an app or service they take effect when the snapctl call returns.
The configure hook sets interval to 60, then trips over a bad server address. Should the interval stick? No. snapctl set in a hook writes to a transaction and registers its commit for when the hook is done. Exit zero, and the commit runs. Fail or time out, and none of that work runs, unless snapd ignores the hook's failure, as it does for remove. set-health, and confdb writes made in a confdb hook, follow the same rule. From the agent service there's no hook to wait for: each call gets its own context, which is done when the call ends, so the value is stored at once.
05 What snap users see of snapctl for users for administrators
A service the snap disabled, a health status in the Notes column of snap list, and a restart inside the snap set change all come from the snap's own snapctl calls. The revision, publisher and "blocked" status are examples.
You won't run snapctl yourself. Snaps run it from their hooks and services, and you see the results through your own commands. Here are three you might meet on the gateway. Snap services shows the uploader as disabled because acme-agent switched it off while it was being installed, and a refresh keeps it that way. Snap list shows blocked in the Notes column, because the agent reported its health and the status isn't okay. And after snap set, the agent's service restarts: its configure hook asked for that, and the restart runs once the hook has succeeded.
06 The hook decides what a command does for app developers for Ubuntu Core developers for snapd developers
From configure, snapctl restart queues into the hook's change; from default-configure it runs right after start-snap-services; elsewhere it creates a service-control change and waits. reboot, fde-setup-request and get --previous work only in particular hooks.
The same command can do different things depending on where you call it. Take snapctl restart acme-agent.agent. From the configure hook, it adds its tasks to the hook's own change, so the restart runs after the hook, and only if the hook succeeds. From default-configure, the tasks go right after the step that starts the snap's services on first install. From the service itself, or any other hook, it creates a service-control change and waits for it. And some commands only work in one hook: reboot in the gadget's install-device hook, fde-setup-request in fde-setup, and get --previous in three confdb hooks.
07 Four checks before a command runs for app developers for Ubuntu Core developers for snapd developers for administrators
Socket, uid, context, then the command's own rules. Non-root callers may use get services set-health is-connected system-mode refresh model version is-ready tasks change; refresh then accepts only --tracking. The uid 1000 in the refusal is an example.
An open socket doesn't mean anything goes. Every call passes four checks. First the socket: /v2/snapctl is served only on the snapd-snap.socket, which every snap can reach; other endpoints there need a connected interface. Second the uid, from the socket's peer credentials. A non-root caller may use eleven commands, and refresh then allows only tracking. Hooks run as root, so this limits apps that users start. Third the context: without a known cookie, only version and help work. Fourth the command's own rules: some need a particular hook, some an interface such as mount-control, and model needs the right snap or brand.
08 Hooks run under a timeout for app developers for Ubuntu Core developers for snapd developers for administrators
Hooks are run-hook tasks with a timeout: 10 minutes by default, 5 for configure, 30 seconds for check-health, 5 minutes for fde-setup. A hook that overruns is killed and its task fails with <exceeded maximum runtime of …>. Revision 42 in the drawing is an example.
What if acme-agent's configure hook hangs, waiting for a server that never answers? snapd won't wait forever. A hook runs as a run-hook task that starts snap run --hook, one hook per snap at a time, and each hook has a time limit: ten minutes by default, five for configure and default-configure, thirty seconds for check-health, and five minutes for fde-setup. When time runs out, snapd kills the process group and adds exceeded maximum runtime to the output. The task fails, and the change undoes what it had done. Unless snapd ignores that hook's failure, as for remove, the hook's snapctl work is dropped too.
09 Where to go from here
Roads: the three snapctl groups, hooks, the overlord and the snapd-control interface.
One socket, one cookie, and a context that decides when work lands. That's the machinery under every snapctl command. Three decks take the commands in groups. Configuration and health covers get, set, unset and set-health, and when their changes land. Services, refresh and changes covers start, stop, restart, components, refresh, reboot and the changes a snap starts itself. Device and system covers model, system-mode, mount, kmod and fde-setup. The hooks deck explains when snapd runs each hook, the overlord covers changes and the run-hook task, and snapd-control has its own scene with the interfaces.
10 Every command at a glance
25 commands: 11 non-root, 5 create or join a change, 3 saved when the hook or call ends, 4 hook-specific.
Every snapctl command, 25 in one table at a glance. 11 may run as non-root: change, get, is-connected, is-ready and 7 others. 5 create a change or add tasks to the running one: install, remove, restart, start and one other. 3 commands, set, set-health, unset, are saved only when the hook succeeds or the call ends. 4 work only inside one particular hook: fail in change-view, fde-setup-request in fde-setup, fde-setup-result in fde-setup, reboot in install-device. The refresh command now works only from apps. 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 lists every snapctl command. This page collects the parts of the mechanism that the commands share.
for app developers for Ubuntu Core developers for snapd developers for administrators
Two sockets
/run/snapd.socket | /run/snapd-snap.socket | |
|---|---|---|
| Used by | the snap command | snapctl |
| Open to a confined snap | only with snapd-control connected | always (base AppArmor template) |
/v2/snapctl | not served | served, no interface needed, no login |
| Other endpoints | the full REST API | a few, each only with a connected interface such as snap-refresh-observe; otherwise 403 Forbidden |
| Identity of the caller | the logged-in user or root | the cookie in the request body |
snapctl never reads ~/.snap/auth.json.
for app developers for Ubuntu Core developers for snapd developers for administrators
The request
| Part | Content |
|---|---|
| Method and path | POST /v2/snapctl |
| Body | context-id (the cookie), args, and stdin only for fde-setup-result (at most 4,000,000 bytes) |
| Header | X-Snapctl-Features: async |
| Reply | stdout, stderr, and change-id when an install or remove runs asynchronously |
| Environment read by the client | SNAP_COOKIE, then SNAP_CONTEXT for compatibility |
Two arguments are handled in the client and do not reach snapd: user-open <url> and the retired internal configure-core. snapctl and snap-exec are one binary that picks its role from the name it was started as.
for app developers for snapd developers
Errors and exit codes
| snapd returns | Client does |
|---|---|
| success | prints stdout and stderr, exits 0 |
kind unsuccessful with an exit code (HTTP 200) | prints stdout and stderr, exits with that code |
403 Forbidden (uid check, or refresh by non-root) | prints error: <message>, exits 1 |
| any other error | prints error: snapctl: <message>, exits 1 |
Commands that use the exit code: is-ready (0 done, 2 finished without success, 3 not ready) and is-connected (1 not connected; with --pid or --apparmor-label, 10 for an unconnected classic snap and 11 for a process that is not a snap).
Cookies and contexts
| Hook | App or service | |
|---|---|---|
Who sets SNAP_COOKIE | snapd, when it starts the hook | snap-confine, from /var/lib/snapd/cookie/snap.<instance> (mode 0600) |
| Value | a new 32-byte token for each hook run | a 39-byte token for the snap |
| Lifetime | while the hook runs | from the first install of the instance to the removal of its last revision; kept across refreshes |
| Context | the hook's context, shared by all calls in that run | a new ephemeral context for every call |
| When buffered work is committed | when the hook exits 0, or when its failure is ignored (for example remove) | when the call returns |
At start-up snapd creates missing cookies and rebuilds them all if it finds a stale or duplicate one. The fde-setup and prepare-serial-request hooks run without a task; they have a hook name but behave as ephemeral contexts.
Who may call what
| Check | Rule | Refusal |
|---|---|---|
| uid | root may run every command; others only get, services, set-health, is-connected, system-mode, refresh (with --tracking only), model, version, is-ready, tasks, change, and any -h/--help | cannot use "set" with uid 1000, try with sudo |
| context | every command except version needs a known cookie | cannot invoke snapctl operation commands (here "get") from outside of a snap |
| hook | reboot in install-device; fde-setup-request and -result in fde-setup; fail in change-view-*; set :<plug> in prepare-*; get :<plug> in interface hooks; get --previous in save-view-*, change-view-*, observe-view-* | per command |
| interface | mount needs mount-control; kmod needs kernel-module-load; model needs snapd-control unless the snap is a gadget or kernel or from the model's brand | per command |
for app developers for Ubuntu Core developers for snapd developers for administrators
Hook time limits
| Hook | Limit | Override |
|---|---|---|
| any hook not listed | 10 minutes | none |
configure, default-configure | 5 minutes | SNAPD_CONFIGURE_HOOK_TIMEOUT |
check-health | 30 seconds | SNAPD_CHECK_HEALTH_HOOK_TIMEOUT |
fde-setup | 5 minutes | none |
A hook that overruns has its process group killed; the output ends in <exceeded maximum runtime of …> and the task fails with run hook "<hook>": …. Only one hook of a snap runs at a time.
Further reading
- Use snapctl: the commands with examples, described as a limited set of controls from within a snap.
- Supported snap hooks: every hook and when snapd runs it.
- The snapd-control interface: the interface that opens the full REST API to a snap.
- System architecture: snapctl and
/run/snapd-snap.socketamong the other parts of snapd. - Error responses: the
unsuccessfulerror kind that carries a snapctl exit code.
Roads from here
RUNNING SNAPS
- The overlord — changes tasks and the run-hook task in the overlord
SNAPCTL · the snap's API into snapd
- "snapctl: configuration and health" — get set unset and set-health and when their changes land
- snapctl: services, refresh and changes — services refresh components reboot and snap-initiated changes
- snapctl: device and system — model system-mode mount umount kmod and fde-setup
INTERFACE FAMILIES · every interface, grouped by what it touches
- "Interfaces: files, data and snapd's own API" — snapd-control and the full API it opens to a snap
HOOKS · code snapd runs inside a snap
- Hooks: how they work — hooks themselves and when snapd runs each one
DESKTOP · snaps in a user session
- snap userd: opening links and files — snapctl user-open and opening links