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
01 Four questions only snapd can answer
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?
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?
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.
05 The document portal before the sandbox
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?
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?
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: 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
| Asker | Question | Answer from |
|---|---|---|
| xdg-desktop-portal | which snap and app is this process? | snap routine portal-info <pid> |
| xdg-document-portal | can this snap already see this file? | snap routine file-access <snap> <path> |
| theme integration | which themes have snaps? install them | GET and POST /v2/accessories/themes |
| launchers, prompting clients, refresh UIs | a snap's icon | GET /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
| Key | Source | Present |
|---|---|---|
InstanceName | the PID's cgroup | always |
AppName | the AppArmor label; else an app with a desktop file, preferring the one named like the snap | if an app was found |
DesktopFile | the app's installed desktop file, base name only | if the app has one |
CommonID | the app's common-id | if set |
HasNetworkStatus | a connected network-status plug of the snap | always |
file-access rules, in order
| Path | Answer |
|---|---|
| any path, snap with classic confinement | read-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 connected | read-write |
documentation directories such as /usr/share/doc and /usr/share/man, with system-packages-doc connected | read-only |
~/snap/<other snap> | hidden |
~/snap/<snap> and other revisions | read-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 files | read-write |
| everything else | hidden |
- Paths are host paths, and the home directory is that of the user running the command. File permissions are not checked. A
hiddenfor a file the snap can in fact read is accepted; it only makes the portal proxy the file. - "Prompting running" means that
/v2/system-inforeports theapparmor-promptingfeature as supported and enabled. It is asked only whenhomeis connected. See AppArmor prompting.
Themes endpoint
| Item | Value |
|---|---|
| GET query keys | gtk-theme, icon-theme, sound-theme, each repeatable |
| GET result | gtk-themes, icon-themes, sound-themes: theme name to installed, available or unavailable |
| Installed themes | content 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 names | gtk-theme-<name>, icon-theme-<name>, sound-theme-<name>; lower case, runs of other characters become -, trailing - segments dropped one at a time |
available | the candidate exists in the store with a stable release |
| POST body | gtk-themes, icon-themes, sound-themes (lists) |
| POST result | a change of kind install-themes, summary Install snap "…" or Install snaps …; nothing to do: no snaps to install |
| GET access | open on snapd.socket; on snapd-snap.socket with snap-themes-control |
| POST access | the 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 othermeta/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; onsnapd-snap.socketfor snaps withdesktop-launch,snap-interfaces-requests-controlorsnap-refresh-observe.
Portal calls made by snapd
| Caller | Portal | Call | Notes |
|---|---|---|---|
snap run, for apps that plug desktop | org.freedesktop.portal.Documents | GetMountPoint | makes 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-open | org.freedesktop.portal.OpenURI on org.freedesktop.portal.Desktop | OpenFile, OpenURI | waits 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-accesstests/main/theme-installtests/main/document-portal-activation,tests/main/interfaces-desktop-document-portaltests/main/desktop-portal-open-uri,desktop-portal-open-file,desktop-portal-filechooser,desktop-portal-screenshot
Further reading
- XDG Desktop Portals: what portals are, how toolkits use them and the document portal path under
/run/user/<uid>/doc/. - Use the Secret portal: a worked portal call from a snap.
- snap-themes-control interface:
/v2/accessories/themesand/v2/accessories/changes/{id}. - snapd REST API:
/v2/icons/{name}/icon.
Roads from here
INTERFACES AND CONFINEMENT
- The home interface — the home interface that decides most file-access answers
- The content interface — the content slots through which theme snaps are found
INTERFACE FAMILIES · every interface, grouped by what it touches
- "Interfaces: desktop and session" — the interfaces named in this deck
DESKTOP · snaps in a user session
- AppArmor prompting — the prompts that the file-access answer keeps from appearing twice
- snap userd: opening links and files — the portal call behind xdg-open in a snap
- Desktop files, icons and D-Bus activation — where the desktop file name and common id in portal-info come from
SANDBOX INTERNALS · the mount namespace
- The per-snap mount namespace — the namespace that needs the document portal mounted first
INSIDE SNAPD · the daemon itself
- The snapd REST API — access levels such as interface-based and polkit access