"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

▶ Watch this deck — 9 scenes, ~7 min

01 Devices are mediated twice general version

THE FAMILY PATTERN acme-agent · plug camerasystem slot (implicit)deny-auto-connection: true → snap connect by hand, or a store rule AppArmor, the camera interface/dev/video[0-9]* rwk,udev, the same interfaceKERNEL=="video[0-9]*" generated into the snap's rules..., TAG+="snap_acme-agent_agent"TAG=="snap_acme-agent_agent",RUN+=".../snap-device-helper ..." device cgroup of snap.acme-agent.agent: only tagged nodes are visible 26 of 35 tag devices through udev · none implements hotplug
The family pattern: an app plug to an implicit system slot, then an AppArmor path rule and a udev tag rule that puts the device into the snap's device cgroup

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

DEVICES · FOR SNAP USERS cameraall cameras on the systemjoystickgame controllersremovable-mediadrives the system already mounted $ snap connections acme-agent$ snap connect acme-agent:camera$ snap connect acme-agent:removable-media optical-drive is the exception: connected on its own on a classic system, read-only a few of these need the store's approval before the snap can be installed at all
Three device interfaces a user connects by hand, the commands to check and connect them, and the optical-drive exception

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

GLOB PLUS TAG AppArmor, device-buttons/dev/input/event[0-9]* rw,every evdev node: keyboards and mice included udevKERNEL=="event[0-9]*", SUBSYSTEM=="input",ENV{ID_INPUT_KEY}=="1",ENV{ID_INPUT_KEYBOARD}!="1" device cgroupevent2 (front-panel button) inevent3 (keyboard) not tagged, not visible KERNEL=="full", SUBSYSTEM=="mem"tagged so the cgroup is in effecteven while no button is present joystick uses the same guard, filtering on ENV{ID_INPUT_JOYSTICK}=="1"
device-buttons' wide AppArmor glob over all evdev nodes, the udev rule that tags only non-keyboard key devices such as the gateway's button into the device cgroup, and the /dev/full guard

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

OBSERVE VS CONTROL hardware-random-observe/dev/hwrng r,/sys/devices/virtual/misc/hw_random/rng_available r,rng_current r, hardware-random-control/dev/hwrng rw,/sys/devices/virtual/misc/hw_random/rng_available r,rng_current r,rng_current w, both tag KERNEL=="hw_random" · both need snap connect by hand pick observe unless you ship an rng-tools style daemon
hardware-random-observe and hardware-random-control side by side: control adds write on /dev/hwrng and on rng_current

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

EIGHT SUPER-PRIVILEGED PLUGS base-declaration, plug sideallow-installation: falsedeny-auto-connection: true block-devicesdm-cryptdm-multipathiscsi-initiatormount-controlnvme-controlscsi-genericuinput a snap-declaration rule lifts itseven of the eight reach disks or mounts uinput grants only/dev/uinput rw,/dev/input/uinput rw, third-party udev rules make /dev/uinput world-writable;snapd will not change device permissions,so the publisher is vetted instead the declaration must restate deny-auto-connection, or the plug auto-connects
The eight plug-side allow-installation false interfaces, with uinput highlighted and the reason it is among them

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

A SLOT IN THE GADGET snap.yaml of the gadget snap (pc)slots:badge:interface: hidrawusb-vendor: 0x0001usb-product: 0x0001path: /dev/hidraw-badge permanent udev rule on the slotSUBSYSTEM=="hidraw", SUBSYSTEMS=="usb",ATTRS{idVendor}=="0001",ATTRS{idProduct}=="0001",SYMLINK+="hidraw-badge" on connection, the plug gets/dev/hidraw[0-9]{,[0-9],[0-9][0-9]} rw,+ the same ATTRS rule, TAG+="snap_..." path only, no USB attributes: path: /dev/hidraw3/dev/hidraw3 rw, KERNEL=="hidraw3" the device cgroup narrows the glob to the one tagged device
A hidraw slot declared in the gadget snap with usb-vendor, usb-product and a symlink path, the permanent SYMLINK udev rule, and the glob plus tag the plug receives

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

RULES FROM ATTRIBUTES acme-agent snap.yamlplugs:mount-control:mount:- what: /dev/sd*where: /media/**type: [ext2, ext3, ext4]options: [rw, sync] generated AppArmormount fstype=(ext2,ext3,ext4) options=(rw,sync)"/dev/sd*" -> "/media/**{,/}",umount "/media/**{,/}", rejected in what and where:where: $SNAP_DATA/foo", /** rw, #a quote or @ would end the rule early validated in BeforeConnectPlug, needs systemd 209 · only the 23 vetted kernel options reach the rule the plug rule shadows the slot's deny-connection: install needs a declaration, connect is manual
A mount-control plug entry in snap.yaml, the AppArmor mount and umount rules generated from it, the rejected injection example, and the policy outcome

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 gatehousethe interfaces overview: plugs, slots, connections gatekeepers' hallhow the backends write the AppArmor and udev files into place buses and boardsthe sibling family, where the gadget declares most of the slots wallsthe device cgroup among the other layers of the sandbox archivesnapshots: the saved data you may carry on removable media
Five roads from this family: the gatehouse, the gatekeepers' hall, buses and boards, the walls, and the archive

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

ALL 35 INTERFACES AT A GLANCE optical-drive alsa block-devices * camera cifs-mount device-buttons display-control dm-crypt * dm-multipath * dvb framebuffer fuse-support hardware-observe hardware-random-control hardware-random-observe hdmi-cec hidraw iscsi-initiator * joystick kvm media-control mount-observe nfs-mount nvme-control * ptp raw-input raw-usb removable-media scsi-generic * u2f-devices uhid uinput * vsock-guest mount-control * raw-volume auto-connectsconditionalby handstore rule to connect* store rule to install · italic: Ubuntu Touch era
Every interface in the devices and storage family, sorted and coloured by how it gets connected: auto-connect, conditional, by hand, or store rule needed

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 familyExceptions
Slotimplicit on the system, on classic and on Ubuntu Coredm-multipath, iscsi-initiator, nvme-control and optical-drive: classic only. hidraw and raw-volume: declared by the gadget or the system snap with path
Connectionby hand, or a store ruleoptical-drive auto-connects on classic unless the plug sets write: true; raw-volume needs a store rule even to connect by hand
Installationfreeblock-devices, dm-crypt, dm-multipath, iscsi-initiator, mount-control, nvme-control, scsi-generic and uinput need a snap-declaration
Device accessan AppArmor path rule plus a udev tag into the device cgroupcifs-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:

InterfaceAppArmor allowsudev tags only
joystickevery /dev/input/event*ENV{ID_INPUT_JOYSTICK}=="1"
device-buttonsevery /dev/input/event*ENV{ID_INPUT_KEY}=="1" and not a keyboard
hidraw with USB idsevery /dev/hidraw*the slot's vendor and product
u2f-devicesevery hidraw nodesecurity 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: false replaces the whole base rule for that snap. Unless it restates deny-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 mount entries 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_intel or kvm_amd from /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 /media and /run/media.
  • No interface in this family takes part in hotplug; only serial-port does.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

RUNNING SNAPS

  • Snapshots — snapshots and the data you carry on removable media

INTERFACE FAMILIES · every interface, grouped by what it touches