"Interfaces: desktop and session"

interface family for users for app developers for snapd developers

Forty-three interfaces for graphical desktops and the user session. Two shapes dominate: classic-only implicit slots standing for one D-Bus session-bus service, and "operating as or interacting with" interfaces whose slot is the system's on classic or an app snap's on Ubuntu Core. Plus the legacy Ubuntu Touch services.

On the map: interfaces district, family row

▶ Watch this deck — 9 scenes, ~7 min

01 The pattern

THE PATTERN shape 1 · a slot that exists only on a classic desktopphoto-editorgsettingssystem slotprovided by snapd one session-bus servicesettings, the calendar, secrets on Ubuntu Core:gsettingsno such slot shape 2 · operating as or interacting withphoto-editorwaylandsystem slotclassiccompositor snapUbuntu Corethe same plug, either slotthe rules name whichever peer it is nearly all of the policy: AppArmor rules for the D-Bus session bus
Two shapes of desktop interface: a plug reaching a classic-only system slot for one session-bus service and nothing on Ubuntu Core, and a plug that reaches either the system slot or a compositor snap's slot

Two shapes: a classic-only implicit slot standing for one session-bus service (absent on Ubuntu Core), and "operating as or interacting with", where the slot is the system's on classic or an app snap's on Ubuntu Core. Nearly all policy is D-Bus session-bus AppArmor rules.

The photo editor on your laptop needs a window, sound, your theme, maybe a saved password. Those are services in your desktop session, and this family's forty three interfaces reach them, mostly in two shapes. In the first, the slot exists only on a classic desktop. snapd provides it, and it stands for one service on the D-Bus session bus, like the calendar or the password manager. On Ubuntu Core there's no such slot. In the second shape, the slot is the system's on classic, or an app snap's, like a compositor, on Ubuntu Core. Nearly all the policy is AppArmor rules for the session bus.

02 What a desktop app connects for users in place of the general version

A DESKTOP APP $ snap connections photo-editorInterface Plug Slot Notes audio-playback photo-editor:audio-playback :audio-playback -desktop photo-editor:desktop :desktop -home photo-editor:home :home -wayland photo-editor:wayland :wayland -x11 photo-editor:x11 :x11 - audio-record photo-editor:audio-record - -password-manager-service photo-editor:password-manager-service - - $ snap connect photo-editor:audio-record Ubuntu Core: except home and opengl, these slots exist only when a snap provides themand then the store must allow the connection
snap connections output for the photo-editor snap: audio-playback, desktop, home, wayland and x11 connected to system slots, audio-record and password-manager-service unconnected, then snap connect for audio-record

On a desktop, desktop, desktop-legacy, x11 or wayland, opengl, audio-playback and home connect at install. audio-record, password-manager-service, screencast-legacy and cups-control wait for snap connect. On Ubuntu Core home and opengl stay with the system; the desktop, display and audio slots exist only when a snap provides them, and then the store must allow the connection.

Install the photo editor on your laptop, and most of what it asks for is connected straight away: desktop, desktop-legacy, x11 or wayland, opengl, audio-playback and home. snapd provides those slots on a desktop. A few stay disconnected until you decide. audio-record, so the editor can't use the microphone until you say so. The password-manager-service. snap connections shows which is which, and snap connect, naming the snap and the plug, grants one. On an Ubuntu Core device, home and opengl still come from the system, but the desktop, display and audio slots exist only when a snap, such as a compositor, provides them.

03 Same plug, two worlds general version

SAME PLUG, TWO WORLDS apps:photo-editor:plugs: [desktop]desktop classic desktopsystem slot · provided by snapdpeer=(label=unconfined)+ desktopConnectedPlugAppArmorClassic:theme files, notifications, media keysrules not yet ported to a snap-provided slot Ubuntu Coreshell snap provides the slotpeer=(label="snap.shell.*")deny-connection:slot-snap-type: [app]plug-side rule → a store rule is needed wayland and x11 say the same with deny-connection: on-classic: false
One desktop plug in snap.yaml connected either to the system slot on classic, with the peer label unconfined and a classic-only snippet, or to a shell snap's slot on Ubuntu Core, with the slot's label and a store rule required

The same desktop plug gets different policy by slot owner: the system slot on classic means peer=(label=unconfined) plus a classic-only snippet; a shell snap's slot on Ubuntu Core means the slot's label and, by the plug-side rule deny-connection: slot-snap-type: [app], a store rule. wayland and x11 use deny-connection: on-classic: false.

Look at the photo editor's snap.yaml and the plug is just desktop. What changes is who owns the slot. On your laptop the slot is the system's. The connected plug rules name the D-Bus peer as unconfined, plus a snippet not yet ported to snap-provided slots: theme files, notifications, media keys. On Ubuntu Core a shell snap provides the slot. That snap's label goes into the rules instead, the extra snippet is left out, and the plug-side base declaration denies connecting to an app's slot: the store has to allow it. wayland and x11 do the same with deny-connection, on-classic: false.

04 The audio split

THE AUDIO SPLIT pulseaudioplayback and recording in one plugno longer auto-connects audio-playbacksound serverpulseaudio or pipewirethe sandbox rules: reach the sound serverauto-connects on a desktop audio-recordno sandbox rules, only a commentwaits for snap connect the server asks snapd: is audio-record connected?
The pulseaudio plug split into audio-playback, connected to the sound server, and audio-record, which has no rules and for which the server asks snapd whether it is connected

pulseaudio granted playback and, on some distributions, recording, and no longer auto-connects. audio-playback has the socket rules and auto-connects on a desktop; audio-record's policy is only a comment: the sound server asks snapd whether it is connected. Recording is a deliberate snap connect.

Say the photo editor can attach a voice note to a picture. Should that mean it can listen? Audio used to be one interface, pulseaudio: playback and, on some distributions, recording. It no longer auto-connects. In its place are two plugs. audio-playback carries the sandbox rules that let the app reach the sound server, and it auto-connects on a desktop. audio-record carries no rules at all. Its policy is a comment saying the audio service will verify that audio-record is connected. The sound server asks snapd before it records for the app. So recording takes a deliberate snap connect.

05 Deny beats allow for app developers for snapd developers

DENY BEATS ALLOW desktop-legacy and unity7 · priority 0/var/lib/snapd/desktop/applications/ r,…/applications/photo-editor_*.desktop r,# every other snap's desktop file:deny …/applications/[^p]*.desktop r,deny …/applications/p[^h]*.desktop r, desktop-launch · reads them all/var/lib/snapd/desktop/applications/{,*} r,/var/lib/snapd/desktop/icons/{,**} r,/snap/*/*/** r,a super-privileged plug: allow-installation: false in AppArmor a deny beats any allow: with both connected, the files would stay unreadable spec.AddPrioritizedSnippet("", prioritizedSnippetDesktopFileAccess, desktopLaunchPriority)an empty snippet under the key "desktop-file-access" at priority 100 replaces the priority-0 rules connected: the deny rules are gone and desktop-launch's allow rules apply · not connected: nothing changes
desktop-legacy's allow and deny rules for desktop files next to desktop-launch's allow rules, a note that deny beats allow, and the prioritized empty snippet that removes the deny rules

desktop-legacy and unity7 deny reading other snaps' desktop files at priority 0 under the key desktop-file-access. Because an AppArmor deny beats any allow, desktop-launch adds an empty snippet under the same key at priority 100, which replaces those deny rules when it is connected.

desktop-legacy and unity7, which the photo editor may plug, add rules for the directory where snapd exports desktop files. The editor can read its own files there; every other snap's is explicitly denied, to cut noisy denials from xdg libraries. A launcher plugs desktop-launch, and needs to read them all. In AppArmor a deny wins over any allow, so adding allows changes nothing. Instead, desktop-launch registers an empty snippet under the key desktop-file-access, at priority one hundred. The deny rules sit at priority zero under the same key, so when desktop-launch is connected, they're dropped. Without it, nothing changes.

06 An interface with no sandbox rules for app developers for snapd developers

NO SANDBOX RULES a desktop helper snapsnap-themes-control AppArmorno snippetseccompno snippetudevno snippetmountno snippet daemon/api_themes.go · Path: "/v2/accessories/themes"ReadAccess: interfaceOpenAccess{Interfaces: []string{"snap-themes-control"}},WriteAccess: interfaceAuthenticatedAccess{Interfaces: ..., Polkit: polkitActionManage},the caller on the snapd socket must be a snap with this plug connected; writes also need root or polkit connected is a capability token, not a rulethe plug is super-privileged: allow-installation: false, so a store declaration is needed to install
A theme installer snap with the snap-themes-control plug, four backends each with no snippet, and the daemon access declarations that the connected plug unlocks

snap-themes-control adds no backend snippets. /v2/accessories/themes gates GET with interfaceOpenAccess and POST with interfaceAuthenticatedAccess plus polkit, both naming the interface. Connected is a capability token. The plug is super-privileged: allow-installation: false.

The photo editor asks for a GTK theme that isn't installed. Something in your session has to notice and install the theme snap, and that something needs snap-themes-control: an interface with no sandbox rules at all. It adds nothing to AppArmor, seccomp, udev or mounts. Its whole effect is inside snapd. The themes endpoint lets a snap with this plug connected check themes, and, as root or through polkit, install them. snapd looks up which snap is calling on its socket and whether that plug is connected. So here, connected is a key, not a rule. Because the key installs snaps, the plug is super-privileged.

07 The legacy shape for Ubuntu Core developers for snapd developers

THE LEGACY SHAPE base-declaration, slots:mir:allow-installation:slot-snap-type: [app]deny-connection: true# no deny-auto-connection snap connect → Check → connection sub-rulesconnection denied by slot rule of interface "mir" install → CheckAutoConnect → auto-connection sub-rulesno rule found: absent means allow kiosk appmirauto-connects at installmir-server snap by design for online-accounts-service: the service itself mediates access to user data legacy: mir, online-accounts-service, ubuntu-download-manager · a Mir kiosk today uses waylandunity8: a plug rule exists, so its slot rule is never consulted
The mir base-declaration slot rule with deny-connection true and no deny-auto-connection; manual connect is denied while auto-connection finds no rule and is allowed, so a kiosk app auto-connects to a Mir server snap

mir, online-accounts-service and ubuntu-download-manager have a base slot rule deny-connection: true and no deny-auto-connection. Manual snap connect is refused; auto-connection finds no rule and is allowed. By design, and legacy. For unity8 the base plug rule is consulted first and has no connection constraint, so snap connect works.

One shape is left over from Ubuntu Touch: mir, online-accounts-service and ubuntu-download-manager. Their base slot rule is deny-connection true, with no deny-auto-connection. A manual snap connect evaluates the connection rules, and is refused. auto-connection at install evaluates the auto-connection rules, finds none, and treats that as allow. So a snap plugging mir auto-connects to an installed Mir server snap, but can't be connected by hand. For online accounts that's by design: the service itself mediates access. unity8 has the same slot rule, but its plug rule is checked first, so a manual connect is allowed there.

08 Where to go from here

ROADS Desktop and session Interfacesthe overview Implementationsnippets collected into profiles Confinementwhere profiles are applied The home interfaceits own deck AppArmor promptingasking you before access Files, data and snapd's APIthe next family
Roads from this family to the interfaces overview, the implementation deck, confinement, the home interface deck, AppArmor prompting and the files, data and snapd's API family

The gatehouse is the overview; the gatekeepers' hall collects the snippets into profiles; the walls apply them; home has its own deck; prompting asks before access; the files, data and snapd's API family is next.

A window, a sound, a theme, and a microphone you switch on yourself. Here's where to go next. The gatehouse is the interfaces overview. The gatekeepers' hall shows how the D-Bus snippets in this family become AppArmor profiles, and the walls show where those profiles apply when the photo editor starts. Home, the one plug almost every desktop app has besides these, has a deck of its own. Prompting shows how home and audio-record can ask you first. And the next family, files, data and snapd's API, has the file access interfaces.

09 All 43 interfaces at a glance

ALL 43 INTERFACES AT A GLANCE desktop-legacy gsettings opengl unity7 audio-playback browser-support desktop media-hub screen-inhibit-control upower-observe wayland x11 mir online-accounts-service ubuntu-download-manager unity8 * accounts-service appstream-metadata audio-record autopilot-introspection calendar-service contacts-service cups-control desktop-launch * gconf jack1 mpris password-manager-service pcscd pipewire pulseaudio screencast-legacy snap-themes-control * udisks2 xdg-portal-permission-store * cups location-control location-observe maliit storage-framework-service thumbnailer-service unity8-calendar unity8-contacts auto-connectsconditionalby handstore rule to connect* store rule to install · italic: Ubuntu Touch era
Every interface in the desktop and session 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: 4 auto-connect, 8 conditionally, 4 auto-connect but need a store rule to connect by hand, 19 by hand, 8 need a store rule to connect; 4 are super-privileged.

All 43 interfaces of the desktop and session family at a glance, sorted by how they get connected. 4 auto-connect on every system: desktop-legacy, gsettings, opengl, unity7. 8 auto-connect under conditions: audio-playback, browser-support, desktop, media-hub, screen-inhibit-control and 3 others. 4 auto-connect, but need a store rule to connect by hand: mir, online-accounts-service, ubuntu-download-manager, unity8. 19 connect by hand with snap connect, which is most of the family. 8 need a store rule even to connect: cups, location-control, location-observe, maliit, storage-framework-service and 3 others. 4, marked with a star, are super-privileged and need a store rule to install. 15, in italics, are Ubuntu Touch era and effectively legacy. Every one of them is in the catalogue below this deck, with what it grants and its rule.

Read more

The three shapes

ShapeMembersSlotConnection
One session service, classic onlyaccounts-service, appstream-metadata, calendar-service, contacts-service, desktop-legacy, desktop-launch, gconf, gsettings, jack1, password-manager-service, pcscd, screencast-legacy, unity7the system, on classic only; none on Ubuntu Coremostly by hand; desktop-legacy, gsettings and unity7 auto-connect
Operating as or interacting withaudio-playback, audio-record, cups-control, desktop, pipewire, pulseaudio, screen-inhibit-control, udisks2, upower-observe, wayland, x11the system on classic, or an app snap such as a compositor or a sound serverconnecting to an app snap's slot needs a store rule (deny-connection: on-classic: false or a plug-side rule)
Ubuntu Touch serviceslocation-control, location-observe, maliit, media-hub, mir, online-accounts-service, storage-framework-service, thumbnailer-service, ubuntu-download-manager, unity8, unity8-calendar, unity8-contactsan app snaplegacy; see below

What connects on a classic desktop

  • At install: desktop, desktop-legacy, x11, wayland, opengl, audio-playback, gsettings, unity7, browser-support (without allow-sandbox) and home.
  • By hand: audio-record, pulseaudio, password-manager-service, screencast-legacy, cups-control, gconf, udisks2 and the calendar, contacts and accounts services.
  • Only with a store rule: desktop-launch, snap-themes-control, xdg-portal-permission-store and unity8 need one to install (super-privileged plugs); browser-support with allow-sandbox: true needs one to connect.

Gotchas

  • audio-record grants nothing by itself. It works only together with audio-playback, and only with a sound server that asks snapd whether it is connected.
  • password-manager-service cannot isolate one snap's secrets from another's: the policy says so. unity7 and desktop-legacy admit that they allow some input sniffing on the session bus.
  • On Ubuntu Core there is no desktop, x11, wayland or audio slot. A kiosk or audio device ships a snap that provides the slot, and connecting to it by hand needs a store rule.
  • mir, online-accounts-service and ubuntu-download-manager auto-connect to an installed snap that provides the slot, but refuse snap connect. Their slot rule has deny-connection: true and no deny-auto-connection, and auto-connection reads only the auto-connection rules. unity8 has a plug rule that is checked first, so manual connection is allowed (policy/basedeclaration_test.go TestConnection).
  • cups-control chooses at auto-connection between the system slot and the cups snap's slot, depending on whether the host has /etc/cups/cupsd.conf.
  • upower-observe has a slot on Ubuntu Core only when the base contains /usr/libexec/upowerd.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

INTERFACE FAMILIES · every interface, grouped by what it touches

DESKTOP · snaps in a user session