snap userd: opening links and files

session service for app developers for users for snapd developers

A confined app cannot start the host's browser or file viewer itself. xdg-open inside a snap asks the desktop portal first and then snap userd which is a D-Bus service in the user session. userd filters URL schemes and asks the user before opening a file or changing the default browser and it can launch another snap's desktop entry for snaps with desktop-launch. snap handle-link passes snap links to the Snap Store.

On the map: desktop district

▶ Watch this deck — 8 scenes, ~6 min

01 A click inside the sandbox

ASKING OUTSIDE photo-editor (confined)Help → online manualyour web browsercannot start it directly snap userda service in your sessionplease open this link(the desktop portal, whenthere is one, answers first) checks the request, or asks you opens it with thedesktop's own opener open a linkopen a filebecome the default browserlaunch another snap's app
photo-editor, a confined snap, cannot start the web browser directly; it asks the desktop portal if there is one, otherwise snap userd, a service in the user session, which checks the request or asks the user and then opens the link with the desktop's own opener; userd handles four kinds of request: open a link, open a file, become the default browser, launch another snap's app

A confined app asks snap userd, a service in the user session, to open links and files, change the default browser or launch another snap's app. userd filters the request or asks the user first. The same command also runs as the session agent and at login with --autostart.

You click Help in photo-editor and your browser opens on the manual. It looks direct, but the app wasn't allowed to start your browser. It's confined, and your browser runs with all your rights, so that's the right call. Instead the request goes over the session bus: to the desktop portal if there is one, otherwise to a small service, the snap command itself, in a role called userd. It runs outside the sandbox and treats the app as a stranger. Some requests it filters by rule, others it puts to you as a question. Then it uses your desktop's own opener. It handles four kinds of request.

02 Portal first, userd second for app developers for snapd developers

xdg-open IN A SNAP $ xdg-open https://example.com/photo-editor/helpinside photo-editor snapctl user-open <url-or-file>handled in the snapctl program: no request to snapd 1desktop portalorg.freedesktop.portal.OpenURI 2snap userdio.snapcraft.Launcheronly if the portal call failed you refused, or no answer in time:stop here, do not try userd file: URL or a bare path → OpenFile · any other scheme → the URL method
xdg-open inside photo-editor runs snapctl user-open, which is handled in the snapctl program without a request to snapd; it tries the desktop portal's OpenURI first and snap userd's io.snapcraft.Launcher second, only if the portal call failed; a refusal or timeout reported by the portal stops it; a file URL or bare path goes to OpenFile, other schemes to the URL method

snapctl user-open is handled inside snapctl. It tries org.freedesktop.portal.OpenURI, then io.snapcraft.Launcher, and stops if the portal reported a refusal or a timeout. Both doors need the desktop plug (userd also through unity7).

Your app doesn't know any of this exists. It runs xdg-open, like any Linux program. Inside a snap, that call ends in snapctl user-open. Unlike every other snapctl command, this one is handled by the snapctl program itself; snapd isn't asked. It tries two doors in a fixed order. First the desktop portal, the documented way, where your desktop can draw its own dialog. If that call fails, say there's no portal, it tries userd. One exception: if the portal said you refused, or nobody answered in time, that answer stands. A file goes to the file method, anything else to the link method.

04 Opening a file takes a yes for app developers for snapd developers

OpenFile photo-editorfd 7 → cat.pdfOpenFile(parent_window, fd)snap userd regular file or directory; not an O_PATH descriptor name from /proc/self/fd/<fd>userd reads the name itself sender → PID → cgroup → snap photo-editor Allow opening file?Allow snap "photo-editor" to open file"/home/alex/snap/photo-editor/42/cat.pdf"?closes after 5 minutes of inactivity yesxdg-open <file>no, or no answer: permission denied
photo-editor passes file descriptor 7 for cat.pdf to snap userd with OpenFile; userd checks it is a regular file or directory and not an O_PATH descriptor, reads the name from /proc/self/fd, finds the calling snap from the sender's PID and cgroup, then shows a dialog Allow snap photo-editor to open file /home/alex/snap/photo-editor/42/cat.pdf; yes runs xdg-open, no or a timeout gives permission denied

OpenFile takes a file descriptor, not a path. userd refuses O_PATH descriptors and special files, names the calling snap from its cgroup and asks "Allow snap … to open file …?" in a zenity or kdialog window before running xdg-open. It is refused on Ubuntu Core.

photo-editor exported a PDF and wants your viewer to show it. A file is different from a link, because the viewer that opens it isn't confined. So the app doesn't send a path. It opens the file and passes the descriptor, proving it could reach the file. userd refuses descriptors opened with O_PATH, which prove nothing, and anything that isn't a regular file or directory. It reads the real name from the descriptor, and finds the calling snap from the caller's process and its cgroup. Then a dialog names the snap and the file. No answer in five minutes means no. On yes, xdg-open shows the file.

05 Becoming the default browser for app developers for snapd developers

io.snapcraft.Settings $ xdg-settings set default-web-browser acme-browser.desktopinside acme-browser(invented) snap userdSet("default-web-browser", "acme-browser.desktop") prefix added by userdacme-browser_acme-browser.desktopthe caller's snap, from its cgroup: only its own files xdg-settings checkalready set:done, no question not setAllow settings change?Allow snap "acme-browser" to change "default-web-browser"to "acme-browser_acme-browser.desktop" ? yesxdg-settings setno: user declined changesnapd bug: parallel installs and files named by desktop-file-ids are not found
Inside the invented acme-browser snap, xdg-settings set default-web-browser acme-browser.desktop calls Set on snap userd; userd prefixes the value with the caller's snap name to get acme-browser_acme-browser.desktop; if xdg-settings check says it is already set it returns, otherwise it asks Allow snap acme-browser to change default-web-browser; yes runs xdg-settings set, no gives user declined change; a snapd bug makes this fail for parallel installs and desktop-file-ids files

io.snapcraft.Settings knows default-web-browser and default-url-scheme-handler. userd prefixes the value with the calling snap's name, skips the question when the setting already matches, and otherwise asks before running xdg-settings set. A snapd bug: the plain <snap>_ prefix misses parallel installs and files named by desktop-file-ids. The browser snap is invented.

A browser snap wants to be your default browser. That's a desktop-wide setting, so a sandboxed app shouldn't just flip it. Its xdg-settings call reaches userd's second object, Settings. Two settings exist: the default web browser, and the default handler for a URL scheme. The value is a plain desktop file name, and userd puts the calling snap's name in front. For an ordinary install that's the installed file's prefix, so a snap can only name its own apps. If the setting already matches, userd returns quietly; some apps ask at every start. Otherwise you're asked, and on yes, xdg-settings makes the change.

06 Launching another snap's app for app developers for snapd developers

PRIVILEGED LAUNCHER acme-dock (invented)desktop-launchsnap userd AppArmor allows this callonly with desktop-launch connecteda snap without the plug OpenDesktopEntry("photo-editor_photo-editor.desktop")the file must be in/var/lib/snapd/desktop/applications otherwise: only launching snap applications from … is supported systemd-run --user --collect -- <Exec line>photo-editor no question to the user; the method does not check the sender
The invented acme-dock snap with a desktop-launch plug calls OpenDesktopEntry on snap userd; AppArmor allows the call only with desktop-launch connected, so a snap without the plug is blocked; userd requires the desktop file to be in /var/lib/snapd/desktop/applications and refuses anything else; it runs the Exec line with systemd-run --user --collect to start photo-editor; nobody is asked and the method does not check the sender

io.snapcraft.PrivilegedDesktopLauncher.OpenDesktopEntry runs the Exec line of a desktop file under /var/lib/snapd/desktop/applications with systemd-run --user. Access is limited by AppArmor to snaps with desktop-launch, whose plug needs a store grant to install. The dock snap is invented.

Now picture a dock that is itself a snap. It starts other apps all day, so asking you each time would be absurd. So where's the check? In front of the call: AppArmor lets a snap send it only with desktop-launch connected, a plug no snap gets for the asking. The dock gives userd's third object a desktop file ID. The file must live where snapd installs snaps' desktop files, so only snap apps start. userd expands the Exec line and runs it through systemd-run in your session, not as a child of the dock. Nobody is asked, and the method doesn't check the caller.

08 Where to go from here

ROADS snap userdDesktop and sessionthe plugs that open the doors Portals and themesthe portal side Desktop fileswhat gets launchedThe user session agentthe same command, another role AppArmor promptinganother way of asking you snapctlhow other commands reach snapd The storewhere the Snap Store comes from
Roads from snap userd: the desktop and session interfaces, what snapd tells desktop services, desktop files, the user session agent, AppArmor prompting, snapctl and the store

Roads: the desktop interfaces, portals and themes, desktop files, the session agent, prompting, snapctl and the store.

Links, files, the default browser and other snaps' apps: four small doors, each with its own lock. Here's where to look next. The desktop interfaces deck covers the plugs that let a snap reach these doors at all. Portals and themes covers the portal side, and what snapd tells portals about a snap. Desktop files covers what actually gets launched. The session agent is the same snap command in another role. Prompting is the other way a desktop snap ends up asking you. And the snapctl deck shows how every other snapctl command reaches snapd, while the store deck is where the Snap Store itself comes from.

Read more

One command, three roles

CommandRoleStarted byDeck
snap userdD-Bus service in the sessionbus activation of io.snapcraft.Launcher or io.snapcraft.Settingsthis one
snap userd --agentsession agentsnapd.session-agent.socketthe user session agent
snap userd --autostartstarts apps at loginan entry in /etc/xdg/autostartdesktop files

snap userd is a hidden command.

for app developers for snapd developers

Objects on the session bus

Bus nameObject pathMethodsReached through
io.snapcraft.Launcher/io/snapcraft/LauncherOpenURL(s url), OpenFile(s parent_window, h fd)desktop, unity7
io.snapcraft.Settings/io/snapcraft/SettingsCheck, CheckSub, Get, GetSub, Set, SetSubdesktop, unity7
(same connection)/io/snapcraft/PrivilegedDesktopLauncherOpenDesktopEntry(s desktop_file_id)desktop-launch

Each object also has Ping and GetMachineId. userd asks for its two bus names without queueing behind another owner.

for app developers for snapd developers

  • Always accepted schemes: apt, help, http, https, mailto, msteams, slack, snap, zoommtg, zoomphonecall, zoomus.
  • A URL without a scheme: cannot open URL without a scheme.
  • Any other scheme: accepted when xdg-mime query default x-scheme-handler/<scheme> prints a valid desktop file name.
  • Otherwise: Supplied URL scheme "<scheme>" is not allowed.
  • Then xdg-open <url>; failure: cannot open supplied URL.
  • On Ubuntu Core: not supported on Ubuntu Core.

for app developers for snapd developers

Files: OpenFile

CheckError
descriptor opened with O_PATHcannot use file descriptors opened using O_PATH
not a regular file or directorycannot open anything other than regular files or directories
user says no, or 5 minutes passpermission denied
on Ubuntu Corenot supported on Ubuntu Core

The question is "Allow opening file?" with the text Allow snap "<snap>" to open file "<file>"?, shown with zenity or kdialog. The calling snap is found from the sender's process ID and its cgroup.

for app developers for snapd developers

Settings

  • Settings: default-web-browser and default-url-scheme-handler (the second with a sub-property, the scheme, through the …Sub methods).
  • The value must be a valid desktop file name such as acme-browser.desktop. userd looks for <calling snap>_<value> among the installed snap desktop files; a missing file gives cannot find desktop file "<path>".
  • Set first runs xdg-settings check; if the answer is yes it returns without a question.
  • The question is "Allow settings change?" with the text Allow snap "<snap>" to change "<setting>" to "<desktop file>" ?. Refusal: cannot change configuration: user declined change.
  • Refused on Ubuntu Core.
  • A snapd bug: the name is built with the plain <snap>_ prefix. A parallel install, whose files use <snap>+<key>_, and files installed without a prefix through desktop-file-ids, are not found, so Set fails with cannot find desktop file and Get and Check do not recognise the snap's own file.

for app developers for snapd developers

Privileged launcher

  • OpenDesktopEntry accepts a desktop file id, requires the file to be under /var/lib/snapd/desktop/applications (only launching snap applications from <dir> is supported), expands Exec and runs systemd-run --user --collect -- <command> (without --collect on systemd older than 236).
  • The method does not check the sender. The desktop-launch plug's AppArmor rules are what limit who can call it. The base declaration sets allow-installation: false and deny-auto-connection: true for the plug, so a snap needs a store grant to carry it.

for app developers for snapd developers

xdg-open inside a snap

StepWhat happens
snapctl user-open <url-or-file>handled inside snapctl; snapd is not contacted
first launcherorg.freedesktop.portal.Desktop, interface org.freedesktop.portal.OpenURI, methods OpenFile and OpenURI; waits up to 5 minutes for the user
second launcherio.snapcraft.Launcher
portal reported refusal or timeoutthe second launcher is not tried
file: URL or bare pathOpenFile; anything else with a scheme: the URL method

Which file in a base snap routes xdg-open to snapctl user-open is outside the snapd tree.

for app developers for snapd developers

  • Hidden command, "Handle a snap:// URI". Registered through a desktop entry with MimeType=x-scheme-handler/snap; and Exec=… snap handle-link %U.
  • If snap-store is not installed: "Install snap-aware Snap Store snap?" (5 minutes). No: Snap Store required. Yes: installs snap-store and waits for the change.
  • Then it becomes snap run snap-store <uri>.

for snapd developers

Spread tests

  • tests/main/xdg-open, xdg-open-compat, xdg-open-portal
  • tests/main/desktop-portal-open-uri, desktop-portal-open-file
  • tests/main/xdg-settings, tests/main/interfaces-desktop-launch
  • tests/main/snap-handle-link, tests/main/snap-userd-reexec

Further reading

Roads from here

GETTING SNAPS

  • The store — the store that the snap-store snap is installed from

SNAPCTL · the snap's API into snapd

INTERFACE FAMILIES · every interface, grouped by what it touches

DESKTOP · snaps in a user session