The security backends
sandbox internals for snapd developers for Ubuntu Core developers
snapd turns a snap's plugs, slots and connections into policy through eleven security backends run in a fixed order, from systemd first to AppArmor last. Each asks the interface repository for its specification of the snap, synchronises the snap's generated files and applies only what changed, with apparmor_parser, snap-seccomp, udevadm, snap-update-ns, modprobe or systemctl. Remove deletes the files but leaves AppArmor profiles and kernel modules loaded.
On the map: sandbox internals district
▶ Watch this deck — 8 scenes, ~6 min
Part of journeys
- From interfaces to AppArmor and back, step 3 of 13 · previous: Specifications and snippets · next: From profile text to kernel
01 One connection, eleven writers
Setting up a snap's security runs every backend in a fixed order: systemd, seccomp, dbus, udev, mount, kmod, polkit, ldconfig, configfiles, symlinks, then apparmor when the kernel supports AppArmor. Each writes one kind of policy and applies only what changed.
You've just connected the agent's meter plug to the gadget's meter slot. Which parts of snapd wake up? snapd sets up the security of both snaps again, the gadget first, then the agent. For each, that means running all its security backends, always in the same order. There are eleven, from systemd first to AppArmor last. Or ten, when the kernel has no AppArmor, because then that backend isn't there. Each one asks for its part of the policy, writes its files, and runs a command only for what changed. For the agent, udev and AppArmor have work. The other nine find their files as they were, and do nothing.
02 A backend's life for snapd developers
Initialize, Name, Prepare, Setup, Remove, NewSpecification, SandboxFeatures. Optional: SetupMany, RemoveLate, Reinitialize (apparmor) and ApplyDelayedEffects (mount). Setup receives the repository and builds its own specification.
Say you're adding a backend: here's the contract you sign. When snapd starts, it calls Initialize, and the repository registers the backend by its name. A duplicate name is refused. Prepare runs before link-snap, and only AppArmor does anything there. Setup runs whenever a snap's security is set up. Notice what it gets: the repository, not a specification. It builds its own. Remove gets the instance name, no snap info, no repository. Snap debug sandbox-features prints its feature list. There's no transaction here; undo is the caller's job. Four optional interfaces add the rest: three only AppArmor uses, one the mount backend uses for delayed effects.
03 The shape of every Setup for snapd developers for Ubuntu Core developers
Specification → content map → files synchronised by per-snap name (EnsureDirState on a glob; udev's single file with EnsureFileState) → a command for changed files only. Only apparmor reloads unchanged profiles. Current behaviour: after a failed seccomp compile the .src is new but the .bin2 is gone, and an unchanged .src is not recompiled.
Squint, and every backend's Setup looks the same. Here's udev, for the agent. First, ask the repository for udev's specification of the snap. Second, map file names to contents. Third, sync the disk, touching only this snap's files; udev has one. That says what changed or went away. Fourth, act only on those: udevadm reloads rules and re-triggers devices. The catch: changed means the file changed, not that the last apply worked. AppArmor reloads unchanged profiles too, so retries repair it. seccomp doesn't. Today a failed compile deletes the binary filter; the next Setup sees the same source, compiles nothing, and snap-confine waits for a filter that doesn't come.
04 Where it lands, and what applies it for Ubuntu Core developers for snapd developers
apparmor: /var/lib/snapd/apparmor/profiles, loaded now. seccomp: /var/lib/snapd/seccomp/bpf/*.src compiled to .bin2, used at the next start. udev: /etc/udev/rules.d/70-snap.*.rules. mount: /var/lib/snapd/mount/*.fstab. kmod: /etc/modules-load.d, /etc/modprobe.d. systemd: /etc/systemd/system. dbus and polkit: files only.
On the gateway, where does each backend's work land, and when? AppArmor writes one profile per app and hook, plus one for snap-update-ns, and loads them into the kernel at once. seccomp compiles a source per app and hook into a binary filter. snap-confine reads it at the next start, so the running agent keeps the filter it started with. udev writes rules and a device-cgroup file, then re-tags devices. Mount writes an fstab, and snap-update-ns changes the running namespace, or throws it away. Modules get modprobe, helper units get systemctl, both best effort. D-Bus and polkit files are only written.
05 Backend by backend, not snap by snap for snapd developers for Ubuntu Core developers
setupSecurityByBackend runs each backend over all affected snaps, in list order. The documented constraint: systemd before apparmor, so the gpio unit exports the pin before the apparmor rule resolves it. The first error stops the loop. Pin 17 and the relay plug are examples.
One task, several snaps: in which order? Refresh the agent, and setup-profiles sets up the agent and the gadget it's connected to. It goes backend by backend, each over all the snaps. Here's why. Say the gadget has a gpio slot for pin 17, and the agent a relay plug. The gadget gets a systemd unit that exports the pin. The agent's AppArmor rule must resolve the pin's link in sysfs, which exists only after the export. So systemd runs for everyone before AppArmor runs for anyone. It's the one ordering rule the code documents. If a backend fails, the loop stops there, and the earlier backends stay applied.
06 "Strict, devmode, classic: the same snap three times" for Ubuntu Core developers for snapd developers
(DevMode || Classic) && !JailMode gives AppArmor complain and udev rules commented out; Classic && !JailMode gives classicTemplate (snippets ignored) and seccomp @unrestricted; DevMode && !JailMode gives seccomp @complain.
Picture the agent three times: strict, in devmode, and as a classic snap. What changes in its generated files? Only three backends care. AppArmor adds the complain flag for devmode and classic, so violations are logged, not denied. For classic it also swaps in a separate template that ignores every interface snippet. seccomp puts complain, or unrestricted, right after the version header. udev keeps the rules file but comments every rule out. Jailmode turns all of that back to strict. The other eight backends ignore the confinement flags and write the same files either way.
07 "Remove: the files go, the kernel keeps some" for snapd developers for Ubuntu Core developers
removeSnapSecurity calls Remove in list order. AppArmor profiles and kernel modules stay loaded; ldconfig, configfiles and symlinks are no-ops. Current behaviour: the first failing backend stops the loop and is logged as "cannot setup".
Now remove the agent. The remove-profiles task calls Remove on every backend, in the same order. Files go by name, and the mount backend throws the namespace away. Two things stay in the kernel on purpose. AppArmor profiles stay loaded, because snapd can't be sure every process of the snap has stopped. And kernel modules stay loaded, by design. ldconfig, configfiles and symlinks do nothing here, since their files belong to the system snap. One catch, today: the loop stops at the first backend that fails. AppArmor comes last, so it keeps its files, and the log says cannot setup, though it was a removal.
08 Where to go from here
Roads: specifications and snippets, setting up a snap's security, delayed security setup, how interfaces are implemented, confinement, snap-update-ns, the system key, buses and boards.
Eleven backends, one order, and each applies only what changed, except AppArmor, which reloads all of a snap's profiles. How each one's specification gets filled is next door, in specifications and snippets. Which tasks call the backends, and for which snaps, is in setting up a snap's security. The mount update that can wait is in delayed security setup. The repository they all read is in how interfaces are implemented. Where the profiles take effect is confinement, and what becomes of the fstab files is in snap-update-ns. When they all run again is the system key. And the gadget's slots live in buses and boards.
Read more
The backends in order
snapd runs the backends in this order when it sets up a snap, and in the same order when it removes one. The apparmor backend exists only when the kernel's AppArmor support is partial or full; without it there are ten backends.
| # | Backend | Files it writes | What applies them | On remove |
|---|---|---|---|---|
| 1 | systemd | /etc/systemd/system/snap.<snap>.interface.<suffix>.service, drop-ins <unit>.d/snap.<name>.conf | systemctl daemon-reload, enable, then stop and start; errors are only logged | files removed, units disabled and stopped, daemon-reload |
| 2 | seccomp | /var/lib/snapd/seccomp/bpf/<tag>.src, compiled to <tag>.bin2 | snap-seccomp compile for changed sources; snap-confine loads the .bin2 at the next start | files removed |
| 3 | dbus | /etc/dbus-1/system.d/<tag>.conf | none | files removed |
| 4 | udev | /etc/udev/rules.d/70-snap.<snap>.rules, /var/lib/snapd/cgroup/snap.<snap>.device | udevadm control --reload-rules, udevadm trigger, udevadm settle --timeout=10 when the rules changed | files removed, udev reloaded if the rules file existed |
| 5 | mount | /var/lib/snapd/mount/snap.<snap>.fstab, .user-fstab | snap-update-ns, or the namespace is discarded; the update can be delayed | files removed, namespace discarded |
| 6 | kmod | /etc/modules-load.d/snap.<snap>.conf, /etc/modprobe.d/snap.<snap>.conf | modprobe for each module when the modules file changed; errors are ignored | files removed; no module is unloaded |
| 7 | polkit | /usr/share/polkit-1/actions/snap.<snap>.interface.<suffix>.policy, /etc/polkit-1/rules.d/70-snap.<snap>.<suffix>.rules | none | files removed |
| 8 | ldconfig | /etc/ld.so.conf.d/snap.system.conf, for the system snap only | ldconfig when the file changed | nothing |
| 9 | configfiles | host files that interfaces register, for the system snap only | none | nothing |
| 10 | symlinks | symlinks in host directories that interfaces register, for the system snap only | none | nothing |
| 11 | apparmor | /var/lib/snapd/apparmor/profiles/<tag> and snap-update-ns.<snap>; cache in /var/cache/apparmor | apparmor_parser --replace --write-cache for changed and unchanged profiles | files and cache removed; profiles stay loaded in the kernel |
<tag> is a security tag such as snap.acme-agent.agent. Generated files are written atomically with mode 0644, and directories are created with mode 0755.
The code documents one reason for the order: the systemd backend must run before the apparmor backend, because the gpio interface's systemd unit exports the pin that the AppArmor rule then resolves. The code says the other constraints are "implicit and not well-known".
Effects of confinement
| Backend | strict | devmode | classic |
|---|---|---|---|
| apparmor | flags=(attach_disconnected,mediate_deleted) | adds complain | classicTemplate, interface snippets ignored, adds complain |
| seccomp | template and snippets | @complain first | @unrestricted first |
| udev | rules active | the file starts # udev tagging/device cgroups disabled with non-strict mode snaps and every rule is commented out | as devmode |
Jailmode gives strict output for devmode and classic snaps. A classic snap in jailmode gets an extra AppArmor snippet that gives access to the core snap, for the dynamic linker and shared libraries. The other eight backends ignore the confinement flags; the mount backend reads only the extra layouts.
for snapd developers for Ubuntu Core developers for administrators
Sandbox features
snap debug sandbox-features prints the features that each backend reports.
| Backend | Features |
|---|---|
| apparmor | kernel:<feature>, parser:<feature>, support-level:full or support-level:partial, policy:default |
| seccomp | kernel:<action> for each action the kernel supports, bpf-argument-filtering, bpf-actlog when the compiler supports it |
| udev | tagging, device-filtering, device-cgroup-v2 or device-cgroup-v1 |
| mount | layouts, mount-namespace, per-snap-persistency, per-snap-profiles, per-snap-updates, per-snap-user-profiles, stale-base-invalidation, and freezer-cgroup-v1 when cgroups are not unified |
| kmod | mediated-modprobe |
| dbus | mediated-bus-access |
| ldconfig | mediated-ldconfig |
| configfiles | mediated-configfiles |
| symlinks | mediated-symlinks |
| systemd, polkit | none |
for snapd developers
The interface
interfaces.SecurityBackend has seven methods:
| Method | When snapd calls it |
|---|---|
Initialize(opts) | at startup, before repo.AddBackend; an error stops the interface manager from starting |
Name() | when the backend is added; a second backend with the same name is refused with cannot add backend %q, security system name is in use |
Prepare(appSet) | before link-snap, from the setup-profiles task in prepare mode; only apparmor does any work |
Setup(appSet, opts, sctx, repo, tm) | on install, refresh, connect, disconnect and regeneration |
Remove(instanceName) | from remove-profiles |
NewSpecification(appSet, opts) | from repo.SnapSpecification, which Setup calls |
SandboxFeatures() | from snap debug sandbox-features |
Optional interfaces:
| Interface | Implemented by | Purpose |
|---|---|---|
SecurityBackendSetupMany | apparmor | loads the changed and the unchanged profiles of many snaps in two batch calls of apparmor_parser; on failure it falls back to Setup for each snap |
SecurityBackendDiscardingLate | apparmor | RemoveLate removes the snap-confine.snapd.<rev> profile of a removed snapd snap revision |
ReinitializableSecurityBackend | apparmor | Reinitialize rewrites the snap-confine policy snippets and reloads the snap-confine profile if they changed |
DelayedSideEffectsBackend | mount | ApplyDelayedEffects updates a consumer's mount namespace later in the change |
A backend without SetupMany is called through interfaces.SetupMany, which calls Setup for each snap and collects the errors.
for snapd developers
Errors and retries
setupSecurityByBackendruns each backend over every affected snap and returns the first error. Backends that ran before keep their changes; undo is the job of the task's undo handler.removeSnapSecuritycallsRemovein list order and returns at the first error, logged ascannot setup <backend> for snap "<snap>": <error>. The later backends, apparmor among them, keep their files.- Only apparmor reloads unchanged profiles on every
Setup. The other backends run their command only when a file changed, so a retry with the same content does not repeat a command that failed. - seccomp removes the old
.bin2before compiling, and removes every.bin2of the batch when one compilation fails. The nextSetupwith the same.srccompiles nothing.snap-confinewaits for a missing.bin2for 120 seconds by default (SNAP_CONFINE_MAX_PROFILE_WAIT, at most 3600), then fails. - The systemd backend only logs
systemctlerrors and returns success. The kmod backend ignoresmodprobeerrors on purpose. - A failed mount namespace update is followed by a discard, unless the snap has a daemon with
refresh-mode: endure; thenSetupfails withcannot update mount namespace of snap %q, and cannot discard it because it contains an enduring daemon.
for snapd developers for Ubuntu Core developers
Preseeding
When an image is preseeded, apparmor adds --skip-kernel-load to every apparmor_parser call, udev does not run udevadm, kmod does not run modprobe, and systemd works in emulation mode: no daemon-reload and no stop or start, with enable and disable run as systemctl --root <dir>. In a container the udev backend still writes its files but does not run udevadm. See Preparing images and preseeding.
Not covered
The examples use invented snaps: acme-agent with the daemon agent, and the gadget acme-gadget. The gpio slot with number: 17 and the plug relay are examples. How the bus daemon and polkitd pick up new files was not determined from the snapd code; snapd runs no command for them. The reasons for the positions of the backends other than systemd and apparmor were not determined.
Further reading
No published page describes the security backends. These are the nearest.
- Security policies: where profiles live and how AppArmor, seccomp and the device cgroup fit together.
- Snap confinement: strict, classic and devmode from the user's side.
- Install modes:
--classic,--devmodeand--jailmode. - Debug snaps: finding denials in a confined app.
Roads from here
INTERFACES AND CONFINEMENT
- How interfaces are implemented — the interface repository the backends read
- Confinement — where snap-confine applies the generated profiles
INTERFACE FAMILIES · every interface, grouped by what it touches
- Interfaces: buses and boards — the gadget's serial-port and gpio slots used here
SANDBOX INTERNALS · the mount namespace
- Specifications and snippets — how each backend's specification is filled with snippets
- Setting up a snap's security — the tasks that call the backends and decide which snaps
- Delayed security setup — the mount backend's namespace update that can wait
- snap-update-ns and the mount profiles — what happens to the fstab files the mount backend writes
- The system key — when every backend regenerates every snap
AppArmor map ↗
- Kernel features and the policy ABI — which rules the kernel can enforce, and how the parser picks them
- Loading policy into the kernel — how a compiled profile is loaded into the kernel