"Interfaces: devices and storage"
interface family for users for app developers for Ubuntu Core developers for snapd developers for administrators
Thirty-five interfaces for device nodes and storage. Nearly all are implicit system slots that need snap connect by hand; access is an AppArmor path rule plus a udev tag into the snap's device cgroup. Eight plugs need a store-vetted publisher to install at all.
On the map: interfaces district, family row
01 Devices are mediated twice general version
Implicit system slot plus deny-auto-connection: connect by hand or by store rule. Access is an AppArmor path rule plus a udev TAG+= rule into the snap's device cgroup, with a RUN+=snap-device-helper rule. 26 of 35 use udev; none implements hotplug.
acme-agent on the gateway takes pictures with a USB camera. How does it reach the camera? Thirty five interfaces in this family cover device nodes and storage, and nearly all share one shape. The slot is implicit on the system, and the base declaration denies auto-connection, so the connection is made by hand or granted by a store rule. Then access is granted twice. AppArmor gets a path rule for the device node. udev gets a rule that tags matching nodes into the snap's device-cgroup, and runs snap-device-helper when a device appears or goes. Twenty six of the thirty five tag devices this way.
02 What you connect by hand for users in place of the general version
camera, joystick and removable-media stay disconnected until you run snap connect; snap connections shows the state. Only optical-drive connects on its own, read-only, on classic. A few interfaces need the store's approval before the snap can be installed at all.
You've installed acme-agent on the gateway, and it can't see the camera yet. That's expected. Nearly every interface in this family stays disconnected after install: the camera, game controllers, drives the system has already mounted. The snap lists the plug, and you decide. snap connections acme-agent shows what it asks for and what's connected; snap connect, naming the snap and the plug, grants one. The exception is optical-drive, which connects on its own on a classic system, for reading only. And a few of these interfaces are privileged enough that a snap using them can't be installed from the store until the store has approved it.
03 device-buttons, a wide glob and a narrow tag for app developers for Ubuntu Core developers for snapd developers for administrators
AppArmor allows /dev/input/event[0-9]* rw for every evdev node; udev tags only devices with ENV{ID_INPUT_KEY}=="1" that are not keyboards, so keyboards and mice stay out of the cgroup. /dev/full is tagged so the cgroup is in effect with no button present. joystick does the same with ID_INPUT_JOYSTICK.
The gateway's front-panel button is wired to a GPIO and reported as input events. acme-agent plugs device-buttons to watch it. The AppArmor rule allows every evdev node, because those nodes aren't namespaced and nothing finer is available, so keyboards and mice match it too. What keeps them out is udev. Only event devices with ID_INPUT_KEY set to one, and not marked as a keyboard, are tagged into the snap's device-cgroup. The cgroup only takes effect once some device is tagged, so the interface also tags /dev/full, a harmless device. joystick uses the same guard, with ID_INPUT_JOYSTICK.
04 Observe and control differ by one w for app developers for Ubuntu Core developers for snapd developers for administrators
hardware-random-observe: /dev/hwrng r and read of rng_available and rng_current. hardware-random-control adds rw on /dev/hwrng and w on rng_current. Same udev tag, both manual connect; prefer observe.
acme-agent would like entropy from the gateway's hardware random generator. Which plug? Many interfaces come as an observe and control pair, and this pair shows how small the step can be. hardware-random-observe allows reading /dev/hwrng and two sysfs files that list the available generators and the current one. hardware-random-control is the same, with two changes: /dev/hwrng becomes read write, and rng_current gains write, so the snap can switch the generator the kernel uses. Both tag the same hw_random device, and both are connected by hand. Pick observe unless you ship an rng-tools style daemon.
05 Eight plugs the store must vet for app developers for Ubuntu Core developers for snapd developers for administrators
Plug-side allow-installation: false: block-devices, dm-crypt, dm-multipath, iscsi-initiator, mount-control, nvme-control, scsi-generic, uinput. A snap-declaration rule lifts it, and must restate deny-auto-connection to keep it manual. uinput is listed to vet publishers, because third-party udev rules make /dev/uinput world-writable.
Next, acme-agent should mount USB sticks to collect logs, and that takes mount-control. It's one of eight interfaces here with a plug-side rule of allow-installation: false: block-devices, dm-crypt, dm-multipath, iscsi-initiator, mount-control, nvme-control, scsi-generic and uinput. A store snap with one of these plugs won't install until its snap-declaration lifts the rule. That rule must also restate deny-auto-connection, or the plug auto-connects. uinput is the odd one. It's listed because some popular software installs udev rules that make /dev/uinput world writable, and snapd won't change device permissions, so publishers are vetted instead.
06 A hidraw slot in the gadget for app developers for Ubuntu Core developers for snapd developers
No implicit slot: the gadget or core snap declares it with path. With usb-vendor and usb-product, a permanent udev rule adds SYMLINK+=, the plug gets the glob /dev/hidraw[0-9]{,[0-9],[0-9][0-9]} rw, and the udev tag narrows it to one device. Path-only slots must name /dev/hidrawN.
The gateway also has a USB badge reader. hidraw has no implicit slot, so the gadget declares one with a path attribute. Give it usb-vendor and usb-product, and the path names a symlink, /dev/hidraw-<name>. A permanent udev rule on the slot creates that symlink for the matching device. When acme-agent connects, it gets a read write glob over every hidraw node, plus a udev tag for that vendor and product, which narrows it to the one reader. Without the USB attributes, the path must be a real node, /dev/hidrawN, and both rules name it exactly.
07 mount-control, rules written from attributes for app developers for snapd developers for administrators
Each mount entry becomes mount fstype=(...) options=(...) "what" -> "where{,/}", plus umount; only the 23 vetted kernel options reach the rule; " and @ are rejected. Validated in BeforeConnectPlug (systemd 209). The slot's deny-connection is shadowed by the plug rule.
Back to those USB sticks. mount-control is the one interface here whose policy is written from the plug's attributes. acme-agent's mount attribute is a list; each entry names what and where, and optionally type, options and persistent. Each entry becomes one AppArmor mount rule with its file system types and the vetted kernel options, plus an umount rule. Quotes and at signs are rejected in what and where, because the values are pasted into the rule. Validation runs when you connect, and needs systemd two hundred nine. The slot's deny-connection is never consulted, because a plug rule exists. So: install needs a declaration, connect is manual.
08 Roads from here
Roads: gatehouse (overview), gatekeepers' hall (backends), buses and boards (the sibling family), walls (the device cgroup in the sandbox), archive (snapshots).
A camera, a button, a badge reader and a USB stick, each reached through a path rule and a udev tag. Here's where to go next. The gatehouse is the interfaces overview. The gatekeepers' hall shows how the backends write the AppArmor and udev files you've seen into place. Buses and boards is the sibling family, where the gadget declares most of the slots. The walls show the device-cgroup among the other layers of the sandbox. And the archive covers snapshots, the saved data you might carry on removable-media.
09 All 35 interfaces at a glance
Every interface in the family by connection class: 0 auto-connect, 1 conditionally, 32 by hand, 2 need a store rule to connect; 8 are super-privileged.
All 35 interfaces of the devices and storage family at a glance, sorted by how they get connected. 1 auto-connect under conditions: optical-drive. 32 connect by hand with snap connect, which is most of the family. 2 need a store rule even to connect: mount-control, raw-volume. 8, marked with a star, are super-privileged and need a store rule to install. Every one of them is in the catalogue below this deck, with what it grants and its rule.
Read more
The pattern and its exceptions
| Most of the family | Exceptions | |
|---|---|---|
| Slot | implicit on the system, on classic and on Ubuntu Core | dm-multipath, iscsi-initiator, nvme-control and optical-drive: classic only. hidraw and raw-volume: declared by the gadget or the system snap with path |
| Connection | by hand, or a store rule | optical-drive auto-connects on classic unless the plug sets write: true; raw-volume needs a store rule even to connect by hand |
| Installation | free | block-devices, dm-crypt, dm-multipath, iscsi-initiator, mount-control, nvme-control, scsi-generic and uinput need a snap-declaration |
| Device access | an AppArmor path rule plus a udev tag into the device cgroup | cifs-mount, display-control, hardware-observe, iscsi-initiator, mount-control, mount-observe, nfs-mount, removable-media and uhid have no udev rules |
A wide AppArmor rule narrowed by udev
Several interfaces allow more in AppArmor than they mean to grant and rely on the udev tag to limit what the device cgroup lets through:
| Interface | AppArmor allows | udev tags only |
|---|---|---|
| joystick | every /dev/input/event* | ENV{ID_INPUT_JOYSTICK}=="1" |
| device-buttons | every /dev/input/event* | ENV{ID_INPUT_KEY}=="1" and not a keyboard |
| hidraw with USB ids | every /dev/hidraw* | the slot's vendor and product |
| u2f-devices | every hidraw node | security tokens: ENV{ID_SECURITY_TOKEN}=="1" with systemd 244 or newer, otherwise a fixed list of vendor and product ids |
joystick and device-buttons also tag /dev/full, so the device cgroup is in force when no matching device is plugged in.
Gotchas
- A snap-declaration that lifts
allow-installation: falsereplaces the whole base rule for that snap. Unless it restatesdeny-auto-connection, the plug auto-connects. - mount-control's slot rule says
deny-connection: true, but a plug rule exists, so the slot rule is not consulted and a manual connection works. - mount-control checks its
mountentries only when the plug is connected, and refuses on systems with systemd older than 209. Only 23 kernel mount options reach the generated rule. - kvm, dm-crypt, dm-multipath, iscsi-initiator and nvme-control load kernel modules, so the kernel snap has to ship them. kvm chooses
kvm_intelorkvm_amdfrom/proc/cpuinfo. - cifs-mount, nfs-mount, fuse-support and mount-control grant
capability sys_admin; only their AppArmor mount rules bound what may be mounted. dm-crypt has mount rules for mapped devices onto/mediaand/run/media. - No interface in this family takes part in hotplug; only serial-port does.
Further reading
- Hardware interfaces: how device access is granted and which interfaces need a gadget slot.
- The mount-control interface: the
mountattribute with examples. - The hidraw interface: gadget slot examples with USB ids.
- The device-buttons interface: what counts as a device button.
- Connect interfaces:
snap connections,snap connectandsnap disconnect.
Roads from here
INTERFACES AND CONFINEMENT
- Interfaces — back to the interfaces overview
- How interfaces are implemented — how the backends write the udev and AppArmor files
- Confinement — the device cgroup among the other layers of the sandbox
RUNNING SNAPS
- Snapshots — snapshots and the data you carry on removable media
INTERFACE FAMILIES · every interface, grouped by what it touches
- Interfaces: buses and boards — the sibling family where the gadget declares most slots