The user session agent
snapd helper process for snapd developers for app developers for administrators
snapd runs as root and cannot reach a user's systemd instance or session bus. A per-user process started on demand through a socket in the user's runtime directory does that work for it. It starts and stops and reports on snap user services and can show refresh notifications and it accepts connections only from root and from its own user.
On the map: desktop district
01 Root cannot reach your session
User services and desktop notifications belong to a user's systemd instance and session bus. snapd reaches them through one session agent per user, snap userd --agent. The sync service of photo-editor is invented for this deck.
Photo-editor has a sync service that should run as you, in your session. snapd runs as root, outside every session. How does it start something inside yours? Your services run under your systemd, and your desktop talks over your session bus. snapd can't reach either, and two people logged in means two of each. snapd puts a helper in every session: the session agent, the snap command in another role. snapd talks to it over a socket, and the agent drives that session's systemd and bus. It carries out snapd's requests and adds two checks of its own: who is calling, and that the unit belongs to a snap.
02 Started by a knock on the socket
The user unit snapd.session-agent.socket listens on $XDG_RUNTIME_DIR/snapd-session-agent.socket. The first connection starts snapd.session-agent.service, which exits after 30 seconds without connections or pending notifications.
Look for the agent's process after you log in and you won't find one. All that exists is a socket, which your systemd listens on, in your runtime directory. Somebody has to knock. The first connection makes systemd start the service. It's Type=notify, so systemd waits until the agent says it's ready. If there's a session bus, the agent takes a name on it. If there isn't, as in some SSH sessions, it carries on without notifications. After thirty seconds with no connections and nothing pending, it tells systemd it's stopping and exits. The socket stays, so the next knock starts it again.
03 Who may connect
The agent reads the peer's uid with SO_PEERCRED when a connection opens. It serves uid 0 and its own uid and closes every other connection. A spread test checks that confined snap apps, also as root, cannot reach it.
A process that starts and stops services for you had better know who's asking. So on every new connection, before reading the request, the agent asks the kernel who's on the other end. User zero is let in: that's snapd. Alex, user one thousand, whose agent this is, gets in too. Anyone else, like the second user, gets a line in the log and a closed connection. The kernel's answer comes from SO_PEERCRED, so the caller can't just claim a name. Apps inside snaps are kept out as well. snapd's test suite checks that confined apps can't reach the agent, even ones running as root.
04 One request to every session
snapd finds agents by /run/user/*/snapd-session-agent.socket and posts the same /v1/service-control request to each, in parallel (or only to the users named with --users). Unit names must begin with snap.. /v1/service-status answers status queries, and snap debug api --session-agent-uid=N reaches one agent.
The photo editor was just refreshed, and its sync service needs to come back in every open session. snapd keeps no list of sessions. It looks for agent sockets under /run/user, then sends each one the same request at once. The request names an action and the units, and each agent hands it to its own systemd. It refuses any unit whose name doesn't start with snap, so it can't drive the rest of your session. A start can also enable a unit, and that's undone if the start fails. And you can talk to one agent directly, with snap debug api and the --session-agent-uid option.
05 The flag in front of user services for app developers for snapd developers for administrators for Ubuntu Core developers
Installing a snap with a daemon-scope: user service needs experimental.user-daemons=true, except for five snaps listed by snap ID in snapd. Without user unit support in systemctl the install fails with user session daemons are not supported on this release. The sync service is invented.
You've added a user service to your snap, you try to install it, and snapd says no. That's a flag, and the message tells you which one. At install, snapd looks for a service with daemon-scope: user. If it finds one, experimental.user-daemons has to be true. Set it with snap set system, and the install goes through. Five snaps skip the check, matched by snap-id: the firmware updater, snapd desktop integration, the prompting client, the snap store and openshell. The list goes once the feature stops being experimental. And the system's systemctl has to support user units, or the install fails differently.
06 Notifications about a refresh
pending-refresh shows "Update available for …" with low, normal or critical urgency by time remaining; finish-refresh shows "… was updated." At this snapd version no code in snapd calls either endpoint; snapd records a refresh-inhibit notice instead. "Photo Editor" is the name from the desktop file, which the agent prefers to the snap name. The docs name the Snapd User Session Agent as the source.
You've probably seen it: a note saying an update is waiting, asking you to close the app. The agent can show that note. But who asks? A pending refresh request names the snap, the time left and the app in the way. With days left the note is low urgency, with hours normal, with minutes critical, and at zero it says updating now. A finish request says it was updated and is ready to launch. Now the careful part: in the snapd this map was read from, nothing in snapd sends either request. It records a refresh-inhibit notice, and a desktop snap that reads it tells you instead.
07 Where to go from here
Roads: services, refresh, the other roles of snap userd, prompting, notices, snap debug and the REST API.
That's the agent: a socket, a careful door and a very short list of jobs. From here the roads go to what it works for. The services deck covers the units snapd writes for user services, and the commands that manage them. The refresh deck shows a refresh that waits for an open app. The userd deck covers the same command's other roles. Prompting has a client that runs as a user service started this way. Warnings and notices covers the refresh-inhibit notice. snap debug covers snap debug api. And the REST API deck shows the daemon's own API, whose shape the agent's small one copies.
Read more
Units and names
| Item | Value |
|---|---|
| Socket unit (user) | snapd.session-agent.socket, ListenStream=%t/snapd-session-agent.socket, WantedBy=sockets.target |
| Service unit (user) | snapd.session-agent.service, Type=notify, ExecStart=… snap userd --agent, Requires= the socket |
| Socket path | /run/user/<uid>/snapd-session-agent.socket |
| Session bus name | io.snapcraft.SessionAgent; its D-Bus service file names the systemd service and has Exec=/bin/false |
| Idle exit | 30 seconds without connections or pending notifications |
| Shutdown | waits up to 5 seconds |
| systemd notifications | READY=1, STOPPING=1 |
| Accepted peers | uid 0 and the agent's own uid; others: Blocking request from user ID <uid> |
Without a session bus the agent still runs and serves service requests; the notification endpoints then answer cannot connect to the session bus.
Endpoints
| Path | Method | What it does |
|---|---|---|
/ | - | registered without a handler |
/v1/session-info | GET | returns {"version": …} |
/v1/service-control | POST | action start, stop, restart or daemon-reload on user units |
/v1/service-status | GET | status of the named user units |
/v1/notifications/pending-refresh | POST | notification "Update available for <name>." |
/v1/notifications/finish-refresh | POST | notification "<name> was updated." with body "Ready to launch." |
- POST bodies must be
application/json; a charset, if given, must be UTF-8. - Unit names must begin with
snap.:cannot start non-snap service <name>and the like. startwithenableenables first and undoes the enable if any start fails.daemon-reloadmust name no services.
Refresh notification fields
| Request | Fields |
|---|---|
| pending-refresh | instance-name, time-remaining, busy-app-name, busy-app-desktop-entry |
| Time remaining | Urgency | Text |
|---|---|---|
| one day or more | low | "Close the application to update now. It will update automatically in N days." |
| one hour or more | normal | the same, in hours |
| one minute or more | critical | the same, in minutes |
| none | critical | title "<name> is updating now!" |
- The name is the localized
Namefrom the busy app's desktop file when there is one, else the snap name. - The finish-refresh notification has low urgency.
- The desktop entry hint is
io.snapcraft.SessionAgent. - Sent through
org.gtk.Notificationsororg.freedesktop.Notifications. - At this snapd version no code in snapd calls the two notification endpoints. For a refresh blocked by a running app snapd records a
refresh-inhibitnotice, readable by snaps withsnap-refresh-observe; see refresh. Whether a client outside snapd calls the endpoints was not determined.
for snapd developers
Callers in snapd
| Caller | Request |
|---|---|
wrappers/services.go | start, stop, restart and daemon-reload of user services |
wrappers/internal/service_status.go, overlord/servicestate/servicestate.go | status of user services |
snap debug api --session-agent-uid=<uid> | any path, by hand |
The client finds sessions with the pattern /run/user/*/snapd-session-agent.socket and sends a request to all of them or to a given list of uids, in parallel.
for app developers for administrators for snapd developers
User services and the flag
- Setting:
experimental.user-daemons. - Without it:
experimental feature disabled - test it by setting 'experimental.user-daemons' to true. - On a release whose systemctl lacks user unit support:
user session daemons are not supported on this release. - Exempt by snap ID, as the code comments name them: firmware-updater, snapd-desktop-integration, prompting-client, snap-store, openshell.
- Units, scopes and
snap start --userare in services.
for snapd developers for administrators
Talking to one agent by hand
$ snap debug api --session-agent-uid=1000 /v1/session-info
$ echo '{"action": "start", "services": ["snap.photo-editor.sync.service"]}' | \
snap debug api --fail --session-agent-uid=1000 \
-X POST -H "Content-Type: application/json" /v1/service-control
Where presets left the socket disabled, the spread tests enable it for all users with systemctl --user --global enable snapd.session-agent.socket.
for snapd developers
Spread tests
tests/main/snap-session-agent-service-controltests/main/snap-session-agent-socket-activationtests/main/snap-session-agent-unavailable-to-snapstests/main/snap-user-serviceand the othersnap-user-service-*tests
Further reading
- Refresh awareness: the notifications, and the name "Snapd User Session Agent" in GNOME Settings. The page describes the agent as their source; at the snapd version read here snapd records a notice instead.
- Control services:
snap start,stopandrestart, which the agent carries out for user services. - Experimental features: the
user-daemonsflag. - The snap format:
daemon-scopeand theautostartapp key.
Roads from here
RUNNING SNAPS
- Services — the units snapd writes for user services and the commands that manage them
- Refresh — the refresh that waits for a running app and how the user is told today
TOOLS
- snap debug: tools for looking inside — snap debug api which can talk to one session agent directly
ADMINISTRATION · managing a system of snaps
- Warnings and notices — the refresh-inhibit notice that desktop snaps read
DESKTOP · snaps in a user session
- snap userd: opening links and files — the other roles of the same snap userd command
- AppArmor prompting — a client whose handler service is started through the agent
INSIDE SNAPD · the daemon itself
- The snapd REST API — the daemon's own API whose shape the agent's small API copies