What snapd tells desktop services

desktop integration for snapd developers for app developers

Portals and shell integration run outside snapd but need facts only snapd has. snap routine portal-info names the snap and app behind a process. snap routine file-access says whether a snap already sees a file. Two REST endpoints report and install theme snaps and serve a snap's icon. snap run makes sure the document portal is mounted before the sandbox is built.

On the map: desktop district

▶ Watch this deck — 8 scenes, ~6 min

01 Four questions only snapd can answer

WHO ASKS SNAPD not part of snapdxdg-desktop-portalxdg-document-portaltheme and shellintegration snapssnapd which snap is process 4242?snap routine portal-info can photo-editor already see this file?snap routine file-access is there a snap for this theme?/v2/accessories/themes what is this snap's icon?/v2/icons/{name}/icon two commands, two endpoints; the services that ask live outside the snapd tree
Three askers outside snapd, xdg-desktop-portal, xdg-document-portal and theme and shell integration snaps, each put a question to snapd: which snap is process 4242, answered by snap routine portal-info; can photo-editor already see this file, answered by snap routine file-access; is there a snap for this theme, answered by /v2/accessories/themes; what is this snap's icon, answered by /v2/icons/{name}/icon

Portals and shell integration ask snapd four things: the snap behind a process (snap routine portal-info), a snap's view of a file (snap routine file-access), theme snaps (/v2/accessories/themes) and a snap's icon (/v2/icons/{name}/icon).

Photo-editor asks for a file chooser, and a window appears that the app didn't draw. The service behind that window isn't part of snapd, but it can't do its job without asking snapd a question or two. All it has is a process ID, and a number doesn't say who's asking. That's one of four questions desktop services put to snapd. Which snap and app is this process? Can this snap already see this file? Is there a snap for this theme? And what's this snap's icon? Each answer is small: one word, a few lines, or a status for each theme.

02 Which snap is this process?

PORTAL-INFO $ snap routine portal-info 4242 [Snap Info]InstanceName=photo-editorthe PID's cgroup AppName=photo-editorthe process's AppArmor labelelse an app with a desktop file,preferring the one named like the snap DesktopFile=photo-editor_photo-editor.desktopsnapd's details of the snapCommonID= follows when the app has one HasNetworkStatus=falsenetwork-status connected? a keyfile; AppName, DesktopFile and CommonIDare left out when unknown
snap routine portal-info 4242 prints a keyfile: [Snap Info], InstanceName=photo-editor from the process's cgroup, AppName=photo-editor from its AppArmor label, DesktopFile=photo-editor_photo-editor.desktop from snapd's details of the snap, HasNetworkStatus=false from whether network-status is connected; keys without a value are left out

snap routine portal-info <pid> prints a keyfile with InstanceName, AppName, DesktopFile, CommonID and HasNetworkStatus. The snap comes from the cgroup, the app from the AppArmor label.

All the portal has is a number: process 4242 wants a file chooser. The portal runs snap routine portal-info with it. The process's cgroup gives the snap's instance name. Its AppArmor label gives the app. If the label doesn't name one, the command picks an app that has a desktop file, favouring the one named after the snap. snapd's details for the snap add the desktop file name, and the common ID when there is one. The last line says whether the snap has network-status connected. The output is a small key file, and lines without a value are simply left out.

03 Can the snap already see this file?

FILE-ACCESS file chooser: cat.jpgdocument portal $ snap routine file-access photo-editor <path>read-writeread-onlyhidden /home/alex/snap/photo-editor/common/out.pngread-writeits own data: common, current, 42 /home/alex/snap/photo-editor/41/old.pngread-onlyanother revision's data/home/alex/Pictures/cat.jpgread-writebecause home is connected /home/alex/.ssh/confighiddena top-level dot file/home/alex/snap/acme-browser/common/xhiddenanother snap's data/etc/hostshiddeneverything else host paths · file permissions are not checkeda wrong hidden only means the portal proxies a file the app could have opened
After cat.jpg is picked in the file chooser, the document portal runs snap routine file-access photo-editor with a path, which answers read-write, read-only or hidden: read-write for the snap's own common data, read-only for revision 41's data, read-write for a picture in home because home is connected, hidden for a top-level dot file, another snap's data and /etc/hosts

snap routine file-access <snap> <path> prints hidden, read-only or read-write from the snap's data directories and its home, removable-media and system-packages-doc connections. A classic snap gets read-write for any path. hidden means the portal must proxy the file.

You've picked cat.jpg in the file chooser. Now the portal has to get it to photo editor, and the cheapest way is to pass the path, if the app can open that path at all. Can it? The portal runs snap routine file-access with the snap and a host path, and gets one word back. Read-write for the snap's own data. Read-only for another revision's data. With home connected, the rest of your home is read-write too. Hidden for top-level dot files, other snaps' data and everything else. File permissions aren't checked, and a wrong hidden only costs a detour through the portal.

04 With prompting on, home is hidden

ONE QUESTION, NOT TWO prompting on, if the answer stayed read-writefile chooser: cat.jpgdocument portalprompting on, as it isfile chooser: cat.jpgdocument portal read-writephoto-editor opens/home/alex/Pictures/cat.jpg Allow photo-editor to read cat.jpg?a second question hiddenhome connected, prompting supported and enabled photo-editor opens$XDG_RUNTIME_DIR/doc/…/cat.jpgthe portal's own mountno prompt: choosing the file was the answer the snap's own data keeps its answers · /v2/system-info is asked only when home is connected
Two lanes for the same file. Top, with prompting on and the old answer: file chooser, document portal, read-write, photo-editor opens /home/alex/Pictures/cat.jpg and a prompt asks whether photo-editor may read cat.jpg. Bottom, with prompting on as it is: file chooser, document portal, hidden because home is connected and prompting is supported and enabled, photo-editor opens the file under the portal's own mount, and no prompt appears

With home connected and AppArmor prompting supported and enabled, snap routine file-access reports home files as hidden. The document portal then proxies them, and a file chosen in a portal dialog raises no prompt.

Now switch prompting on and replay the same click. If nothing changed here, you'd pick cat.jpg, the portal would pass the real path, and the home interface would then ask: allow photo editor to read cat.jpg? That's a question about a file you chose ten seconds ago. So file access changes its answer. When home is connected and prompting is supported and enabled, the rest of your home is reported hidden. The portal proxies the file through its own mount instead, and no prompt appears. Choosing the file was the answer. The snap's own data keeps its answers, and snapd is asked about prompting only when home is connected.

05 The document portal before the sandbox

IN SNAP RUN $ snap run photo-editor only for apps that plug desktopGetMountPointdocument portalorg.freedesktop.portal.Documents $XDG_RUNTIME_DIR/docmounted: the portal is running mount namespace builtsnap-confine starts after the call service unknown$XDG_RUNTIME_DIR/.portals-unavailable next run: the marker is found and the call is skipped,until the next login clears the runtime directory
snap run photo-editor, for an app that plugs desktop, calls GetMountPoint on org.freedesktop.portal.Documents; once answered, $XDG_RUNTIME_DIR/doc is mounted, and only then is the mount namespace built. If the service is unknown, snap run writes $XDG_RUNTIME_DIR/.portals-unavailable and skips the call on later runs until the next login

For apps that plug desktop, snap run calls GetMountPoint on org.freedesktop.portal.Documents so that $XDG_RUNTIME_DIR/doc is mounted before the mount namespace is built. It skips the call when that directory is already a mount point or there is no session bus. If the service is unknown it writes .portals-unavailable and does not retry.

There's a catch with that portal mount. It has to exist before photo editor's sandbox is put together, and nothing guarantees the portal has started by then: in a normal session it starts on demand. So, for any app that plugs desktop, snap run first asks the document portal for its mount point. Once that call is answered, the portal is running and its mount is in place. Only then is the mount namespace built. If the session bus says there's no such service, snap run leaves a marker file and stops asking until your next login, so a system without portals doesn't pay for a failing call every time.

06 Is there a snap for this theme?

THEMES GET /v2/accessories/themes?gtk-theme=Yaru&gtk-theme=TraditionalHumanized&sound-theme=No-Such-Theme Yaru: installedan installed snap has it in a gtk-3-themes content slot TraditionalHumanized: availablegtk-theme-traditionalhumanizeda snap of that name with a stable release No-Such-Theme: unavailablesound-theme-no-such-theme → sound-theme-no-such→ sound-theme-noeach tried, none found POST /v2/accessories/themes{"gtk-themes": ["TraditionalHumanized"]}change: install-themes a snap needs snap-themes-control to read;installing also needs a logged-in user, root or polkit
A query to /v2/accessories/themes for gtk themes Yaru and TraditionalHumanized and sound theme No-Such-Theme: Yaru is installed because an installed snap has a gtk-3-themes content slot, TraditionalHumanized is available as the snap gtk-theme-traditionalhumanized with a stable release, No-Such-Theme is unavailable after three candidate names; a POST with TraditionalHumanized starts an install-themes change

GET /v2/accessories/themes reports each requested theme as installed, available or unavailable; POST installs the matching gtk-theme-, icon-theme- and sound-theme- snaps in an install-themes change. The docs call this the theme installation API.

You've changed your desktop theme and your snaps still look like yesterday. They only use themes from snaps, so something has to find the right snap. A shell integration snap asks the themes endpoint about GTK, icon or sound themes. A theme is installed when some snap offers it in a content slot of that kind. Otherwise snapd guesses snap names: a prefix for the kind plus the theme name in lower case, shortened a dash at a time. A guess counts only with a stable release. A POST installs them in one install-themes change. A snap needs the snap-themes-control plug to read; installing also needs authentication.

07 What is this snap's icon?

ICONS a prompting clientsnap-interfaces-requests-controla launcherdesktop-launcha refresh UIsnap-refresh-observe snapdGET /v2/icons/photo-editor/icon meta/gui/icon.svgfrom the current revision meta/gui/icon.pngif there is no svg; then any other icon.* icon saved for the snap IDif the snap ships none none: local snap has no icon
A launcher with desktop-launch, a prompting client with snap-interfaces-requests-control and a refresh UI with snap-refresh-observe ask snapd for GET /v2/icons/photo-editor/icon; snapd tries meta/gui/icon.svg from the current revision, then meta/gui/icon.png, then any other meta/gui/icon.*, then the icon it saved for the snap ID; with none of these the answer is local snap has no icon

GET /v2/icons/{name}/icon serves meta/gui/icon.svg, else icon.png, else any other icon.*, else the icon snapd saved for the snap ID. Snaps with desktop-launch, snap-interfaces-requests-control or snap-refresh-observe may read it.

When a prompt says photo-editor wants to read a file, a picture of the app next to it helps you trust the question. The client drawing that prompt is a snap, so where does it get another snap's icon? Launchers and refresh windows have the same problem. snapd serves the icon itself, from one endpoint with the snap's name in the path. It looks in the current revision's meta/gui directory, preferring an SVG icon, then a PNG, then any other icon file. If the snap ships none, it falls back to the icon snapd saved for that snap-id. Still nothing: not found.

08 Where to go from here

ROADS Desktop services AppArmor promptingthe second question avoidedsnap userdxdg-open and the OpenURI portalDesktop filesthe names in portal-info The home interfacemost file-access answersThe content interfacewhere theme snaps are foundDesktop and sessionthe interfaces named here The per-snap mount namespacebuilt after the portal callThe snapd REST APIaccess levels of the endpoints
Roads from What snapd tells desktop services: AppArmor prompting, snap userd, desktop files, the home interface, the content interface, the desktop and session interfaces, the per-snap mount namespace and the snapd REST API

Roads: AppArmor prompting, snap userd, desktop files, the home and content interfaces, the desktop and session interfaces, the per-snap mount namespace and the REST API.

Four questions, four small answers, and one call snap run makes for itself. These roads lead to the things those answers are about. AppArmor prompting covers the questions this deck keeps from being asked twice. Snap userd covers xdg-open and the portal behind it. Desktop files explains where the names in portal info come from. The home and content interface decks explain most file access answers and where theme snaps are found. The desktop and session family lists the interfaces named here. The mount namespace deck shows what the document portal must be mounted before. And the REST API deck explains the access levels these endpoints use.

Read more

Who asks what

AskerQuestionAnswer from
xdg-desktop-portalwhich snap and app is this process?snap routine portal-info <pid>
xdg-document-portalcan this snap already see this file?snap routine file-access <snap> <path>
theme integrationwhich themes have snaps? install themGET and POST /v2/accessories/themes
launchers, prompting clients, refresh UIsa snap's iconGET /v2/icons/{name}/icon

The portal services are not part of snapd.

portal-info output

[Snap Info]
InstanceName=photo-editor
AppName=photo-editor
DesktopFile=photo-editor_photo-editor.desktop
CommonID=<common-id>
HasNetworkStatus=false
KeySourcePresent
InstanceNamethe PID's cgroupalways
AppNamethe AppArmor label; else an app with a desktop file, preferring the one named like the snapif an app was found
DesktopFilethe app's installed desktop file, base name onlyif the app has one
CommonIDthe app's common-idif set
HasNetworkStatusa connected network-status plug of the snapalways

file-access rules, in order

PathAnswer
any path, snap with classic confinementread-write
/var/snap/<snap>read-only
/var/snap/<snap>/common, /current, /<current revision>read-write
other entries of /var/snap/<snap>read-only
/mnt, /media, /run/media, with removable-media connectedread-write
documentation directories such as /usr/share/doc and /usr/share/man, with system-packages-doc connectedread-only
~/snap/<other snap>hidden
~/snap/<snap> and other revisionsread-only
~/snap/<snap>/common, /current, /<current revision>read-write
the rest of the home directory, with home connected and prompting not running, except top-level dot filesread-write
everything elsehidden
  • Paths are host paths, and the home directory is that of the user running the command. File permissions are not checked. A hidden for a file the snap can in fact read is accepted; it only makes the portal proxy the file.
  • "Prompting running" means that /v2/system-info reports the apparmor-prompting feature as supported and enabled. It is asked only when home is connected. See AppArmor prompting.

Themes endpoint

ItemValue
GET query keysgtk-theme, icon-theme, sound-theme, each repeatable
GET resultgtk-themes, icon-themes, sound-themes: theme name to installed, available or unavailable
Installed themescontent slots with content equal to gtk-3-themes, icon-themes or sound-themes; names are the base names of the source.read paths
Candidate snap namesgtk-theme-<name>, icon-theme-<name>, sound-theme-<name>; lower case, runs of other characters become -, trailing - segments dropped one at a time
availablethe candidate exists in the store with a stable release
POST bodygtk-themes, icon-themes, sound-themes (lists)
POST resulta change of kind install-themes, summary Install snap "…" or Install snaps …; nothing to do: no snaps to install
GET accessopen on snapd.socket; on snapd-snap.socket with snap-themes-control
POST accessthe same interface, authenticated: a logged-in snapd user, root, or the polkit action for managing snaps
/v2/accessories/changes/{id}GET only; progress of an install-themes change; open, or a snap with snap-themes-control on the snap socket; other change kinds answer not found

snap-themes-control: plugs have allow-installation: false and deny-auto-connection: true. The endpoint is not in the published OpenAPI file.

Icons endpoint

  • GET /v2/icons/{name}/icon.
  • Order: meta/gui/icon.svg, meta/gui/icon.png, any other meta/gui/icon.* of the current revision, then the icon snapd saved for the snap ID.
  • Errors: snap has no current revision, local snap has no icon.
  • Access: open on snapd.socket; on snapd-snap.socket for snaps with desktop-launch, snap-interfaces-requests-control or snap-refresh-observe.

Portal calls made by snapd

CallerPortalCallNotes
snap run, for apps that plug desktoporg.freedesktop.portal.DocumentsGetMountPointmakes sure $XDG_RUNTIME_DIR/doc is mounted before snap-confine runs; skipped when it is already a mount point or there is no session bus; on "service unknown" writes $XDG_RUNTIME_DIR/.portals-unavailable and does not retry while that file exists
snapctl user-openorg.freedesktop.portal.OpenURI on org.freedesktop.portal.DesktopOpenFile, OpenURIwaits up to 5 minutes for the Response signal; see snap userd

for snapd developers

Spread tests

  • tests/main/snap-routine-portal-info, tests/main/snap-routine-file-access
  • tests/main/theme-install
  • tests/main/document-portal-activation, tests/main/interfaces-desktop-document-portal
  • tests/main/desktop-portal-open-uri, desktop-portal-open-file, desktop-portal-filechooser, desktop-portal-screenshot

Further reading

Roads from here

INTERFACES AND CONFINEMENT

INTERFACE FAMILIES · every interface, grouped by what it touches

DESKTOP · snaps in a user session

SANDBOX INTERNALS · the mount namespace

INSIDE SNAPD · the daemon itself