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
01 A click inside the sandbox
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
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.
03 Which links userd will open for app developers for snapd developers
OpenURL accepts eleven listed schemes, and any scheme for which xdg-mime query default x-scheme-handler/<scheme> names a desktop file. Everything else fails with "Supplied URL scheme … is not allowed". The schemes tg and nosuch are only examples.
Say the portal isn't there and a link reaches userd. Nobody asks you anything; a filter decides. The link needs a scheme. Eleven schemes always pass: the web ones, mail, help, apt, snap, and a few chat and meeting apps. Any other scheme passes only if your desktop already has a default handler for it, and userd finds that out by asking xdg-mime. If neither holds, the call fails and names the scheme it wouldn't allow. File isn't on the list; files take the other method. An accepted link goes to the host's xdg-open. On Ubuntu Core, the method refuses.
04 Opening a file takes a yes for app developers for snapd developers
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 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
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.
07 A link that installs a snap
snap handle-link is registered for snap:// links. It offers to install the snap-store snap when it is missing, then starts the Snap Store with the link. From inside a snap the same link goes through xdg-open; snap is one of the schemes userd accepts.
You're reading about an app on the web, and there's a link that starts with snap, colon. Click it and something on your machine has to know what that means. Snapd ships a desktop entry that registers the snap command for that scheme, so the click runs snap handle-link with the address. Is the snap-store snap installed? If not, you're asked whether to install it, with the same five minute dialog. Say no and it stops, saying the Snap Store is required. Say yes and it installs it and waits. Then it hands the link to the Snap Store, and snapd's part ends there.
08 Where to go from here
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
| Command | Role | Started by | Deck |
|---|---|---|---|
snap userd | D-Bus service in the session | bus activation of io.snapcraft.Launcher or io.snapcraft.Settings | this one |
snap userd --agent | session agent | snapd.session-agent.socket | the user session agent |
snap userd --autostart | starts apps at login | an entry in /etc/xdg/autostart | desktop files |
snap userd is a hidden command.
for app developers for snapd developers
Objects on the session bus
| Bus name | Object path | Methods | Reached through |
|---|---|---|---|
io.snapcraft.Launcher | /io/snapcraft/Launcher | OpenURL(s url), OpenFile(s parent_window, h fd) | desktop, unity7 |
io.snapcraft.Settings | /io/snapcraft/Settings | Check, CheckSub, Get, GetSub, Set, SetSub | desktop, unity7 |
| (same connection) | /io/snapcraft/PrivilegedDesktopLauncher | OpenDesktopEntry(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
Links: OpenURL
- 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
| Check | Error |
|---|---|
descriptor opened with O_PATH | cannot use file descriptors opened using O_PATH |
| not a regular file or directory | cannot open anything other than regular files or directories |
| user says no, or 5 minutes pass | permission denied |
| on Ubuntu Core | not 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-browseranddefault-url-scheme-handler(the second with a sub-property, the scheme, through the…Submethods). - 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 givescannot find desktop file "<path>". Setfirst runsxdg-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 throughdesktop-file-ids, are not found, soSetfails withcannot find desktop fileandGetandCheckdo not recognise the snap's own file.
for app developers for snapd developers
Privileged launcher
OpenDesktopEntryaccepts a desktop file id, requires the file to be under/var/lib/snapd/desktop/applications(only launching snap applications from <dir> is supported), expandsExecand runssystemd-run --user --collect -- <command>(without--collecton systemd older than 236).- The method does not check the sender. The
desktop-launchplug's AppArmor rules are what limit who can call it. The base declaration setsallow-installation: falseanddeny-auto-connection: truefor the plug, so a snap needs a store grant to carry it.
for app developers for snapd developers
xdg-open inside a snap
| Step | What happens |
|---|---|
snapctl user-open <url-or-file> | handled inside snapctl; snapd is not contacted |
| first launcher | org.freedesktop.portal.Desktop, interface org.freedesktop.portal.OpenURI, methods OpenFile and OpenURI; waits up to 5 minutes for the user |
| second launcher | io.snapcraft.Launcher |
| portal reported refusal or timeout | the second launcher is not tried |
file: URL or bare path | OpenFile; 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
snap handle-link
- Hidden command, "Handle a snap:// URI". Registered through a desktop entry with
MimeType=x-scheme-handler/snap;andExec=… snap handle-link %U. - If
snap-storeis not installed: "Install snap-aware Snap Store snap?" (5 minutes). No:Snap Store required. Yes: installssnap-storeand 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-portaltests/main/desktop-portal-open-uri,desktop-portal-open-filetests/main/xdg-settings,tests/main/interfaces-desktop-launchtests/main/snap-handle-link,tests/main/snap-userd-reexec
Further reading
- XDG Desktop Portals: the OpenURI portal, the recommended way to open links and files.
- desktop interface: the interface that gives access to portals and to userd.
- desktop-launch interface: the interface behind the privileged launcher.
- desktop-legacy interface: older desktop access for snaps that cannot use portals.
Roads from here
GETTING SNAPS
- The store — the store that the snap-store snap is installed from
SNAPCTL · the snap's API into snapd
- snapctl: how it works — how every other snapctl command reaches snapd unlike user-open
INTERFACE FAMILIES · every interface, grouped by what it touches
- "Interfaces: desktop and session" — the desktop and unity7 and desktop-launch interfaces that open these doors
DESKTOP · snaps in a user session
- What snapd tells desktop services — the portal side and what snapd tells portals about a snap
- Desktop files, icons and D-Bus activation — the desktop files that the launcher and the settings refer to
- The user session agent — the same command in its agent role
- AppArmor prompting — the other way a desktop snap ends up asking the user