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

▶ Watch this deck — 7 scenes, ~6 min

01 Root cannot reach your session

TWO WORLDS system: snapd, as rootsystemd --usersession bussystemd --usersession bussession of alex (uid 1000)session of uid 1001 not reachable from the system service session agentsnap userd --agentsession agentsnap userd --agent a socket per user start, stop, statusnotificationsstart, stop, statusnotifications checks the caller and the unit namechecks the caller and the unit name
snapd runs as root in the system and cannot reach the systemd user instance or session bus of two logged-in users; in each session a session agent, snap userd --agent, is reached over a socket per user and drives that session's systemd and bus, after checking who is calling and that the unit name begins with snap.

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

ON DEMAND snapd.session-agent.socket/run/user/1000/snapd-session-agent.socketwanted by sockets.target: listening from loginlogin first connectionno agent process yet snapd.session-agent.servicesnap userd --agentREADY=1 session bus name io.snapcraft.SessionAgentno session bus:runs anyway, without notifications 30 seconds with no connectionand no pending notification STOPPING=1exits; the socket keeps listening
A timeline from login: the user socket snapd.session-agent.socket listens in /run/user/1000; the first connection starts snapd.session-agent.service, snap userd --agent, which reports READY=1 and takes the bus name io.snapcraft.SessionAgent if there is a session bus; after 30 seconds without connections or pending notifications it reports STOPPING=1 and exits while the socket keeps listening

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 DOOR session agent of uid 1000 snapd (uid 0)accepted alex (uid 1000)accepted uid 1001Blocking request from user ID 1001 checked on every new connectionwith SO_PEERCRED, before the request a confined snap appalso as root: a spread test checks that snaps cannot reach the agent
Four callers try the session agent of uid 1000: snapd as uid 0 and alex as uid 1000 are accepted; uid 1001 is blocked with a log line; a confined snap app is kept out too; the check uses SO_PEERCRED on every new connection

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

FAN-OUT snapdagent, uid 1000systemd --useragent, uid 1001systemd --user /run/user/*/snapd-session-agent.socketfinds the sessions by their sockets the same request, in parallel POST /v1/service-control{"action": "start","services": ["snap.photo-editor.sync.service"]} startstartactions: start · stop · restart · daemon-reloadunit names must begin with snap. $ snap debug api --session-agent-uid=1000 /v1/session-infoone agent, by hand
snapd finds session agents by the sockets under /run/user and posts the same service-control request, start snap.photo-editor.sync.service, to the agents of uid 1000 and uid 1001 in parallel; each agent starts the unit in its own systemd; unit names must begin with snap.; snap debug api --session-agent-uid=1000 reaches one agent by hand

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

THE GATE snap.yamlapps:sync:daemon: simpledaemon-scope: user $ snap install photo-editorexperimental.user-daemons? experimental feature disabled - test it by setting'experimental.user-daemons' to true $ sudo snap set system experimental.user-daemons=trueinstalledunits written for every user five snaps by snap IDexempt: firmware-updater · snapd-desktop-integration · prompting-client · snap-store · openshell also needed: a systemctl that supports user units
A snap.yaml with a sync app that is a daemon with daemon-scope user goes through snap install to a gate, experimental.user-daemons; with the flag off the install fails with experimental feature disabled; after snap set system experimental.user-daemons=true it installs and units are written for every user; five snaps bypass the gate by snap ID; systemctl must also support user units

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

NOTIFICATIONS POST /v1/notifications/pending-refreshPOST /v1/notifications/finish-refreshsession agentorg.gtk.Notifications ororg.freedesktop.Notifications Update available for Photo Editor.Close the application to update now.days: low hours: normalminutes: criticalPhoto Editor is updating now!no time: critical Photo Editor was updated.Ready to launch.finish-refresh in this snapd version nothing in snapd calls these two endpoints snapd records a refresh-inhibit notice instead; a desktop snap with snap-refresh-observe reads itwhether a client outside snapd calls them was not determined
The session agent accepts pending-refresh and finish-refresh requests and shows desktop notifications: Update available for Photo Editor with low, normal or critical urgency as time runs out, Photo Editor is updating now when no time is left, and Photo Editor was updated, Ready to launch; at this snapd version nothing in snapd calls these endpoints, and snapd records a refresh-inhibit notice that a desktop snap with snap-refresh-observe reads

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 The user session agent Servicesuser service units and commandsRefresha refresh that waits for an open app snap userd: links and filesthe same command's other rolesAppArmor promptinga client run as a user service Warnings and noticesthe refresh-inhibit noticesnap debugsnap debug api, one agent at a timeThe snapd REST APIthe daemon's own API
Roads from the user session agent: services, refresh, snap userd links and files, AppArmor prompting, warnings and notices, snap debug and the snapd REST API

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

ItemValue
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 nameio.snapcraft.SessionAgent; its D-Bus service file names the systemd service and has Exec=/bin/false
Idle exit30 seconds without connections or pending notifications
Shutdownwaits up to 5 seconds
systemd notificationsREADY=1, STOPPING=1
Accepted peersuid 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

PathMethodWhat it does
/-registered without a handler
/v1/session-infoGETreturns {"version": …}
/v1/service-controlPOSTaction start, stop, restart or daemon-reload on user units
/v1/service-statusGETstatus of the named user units
/v1/notifications/pending-refreshPOSTnotification "Update available for <name>."
/v1/notifications/finish-refreshPOSTnotification "<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.
  • start with enable enables first and undoes the enable if any start fails.
  • daemon-reload must name no services.

Refresh notification fields

RequestFields
pending-refreshinstance-name, time-remaining, busy-app-name, busy-app-desktop-entry
Time remainingUrgencyText
one day or morelow"Close the application to update now. It will update automatically in N days."
one hour or morenormalthe same, in hours
one minute or morecriticalthe same, in minutes
nonecriticaltitle "<name> is updating now!"
  • The name is the localized Name from 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.Notifications or org.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-inhibit notice, readable by snaps with snap-refresh-observe; see refresh. Whether a client outside snapd calls the endpoints was not determined.

for snapd developers

Callers in snapd

CallerRequest
wrappers/services.gostart, stop, restart and daemon-reload of user services
wrappers/internal/service_status.go, overlord/servicestate/servicestate.gostatus 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 --user are 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-control
  • tests/main/snap-session-agent-socket-activation
  • tests/main/snap-session-agent-unavailable-to-snaps
  • tests/main/snap-user-service and the other snap-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, stop and restart, which the agent carries out for user services.
  • Experimental features: the user-daemons flag.
  • The snap format: daemon-scope and the autostart app 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

ADMINISTRATION · managing a system of snaps

DESKTOP · snaps in a user session

INSIDE SNAPD · the daemon itself