Services
running snaps for app developers for administrators for users
An app with a daemon line in snap.yaml is a service. snapd writes a systemd unit for it and systemd runs it through snap run. Timers and sockets get their own units and start the service on demand. On refresh a service is stopped before the switch and started after it unless it asks to endure. snap services and snap start and stop and restart and logs manage them.
On the map: the watch house
01 Who keeps the agent running?
A snap declares its services, snapd writes a systemd unit for each, and systemd runs them through snap run. snap services shows each service's Startup and Current state.
The gateway's been up for three weeks, and acme-agent has been running the whole time. Nobody started it, and when it crashed last Tuesday it came straight back. Who's doing that? Not snapd, at least not directly. The snap says which of its apps are services. snapd writes a systemd unit for each one, and hands it over. systemd starts it at boot and restarts it when it fails: snapd writes the instructions, systemd stands watch. What systemd runs is snap run, so the daemon gets the same confinement as the snap's other apps. Snap services shows the result. The report is inactive: it's waiting for its timer.
02 One line in snap.yaml, one unit file for app developers for administrators
An app with daemon: gets snap.<snap>.<app>.service in /etc/systemd/system. ExecStart is snap run; defaults are Restart=on-failure and TimeoutStopSec=30s. Every other service field maps to one unit line; the reference below lists them.
Open snap.yaml for acme-agent and look for what makes the agent a service. It's one line: daemon, set here to simple. There are five values, simple, forking, oneshot, dbus and notify, and snapd copies yours into the unit as its type. What each type means is up to systemd. The unit's named after the snap and the app, and the start command is always snap run. Say nothing else and the service restarts on failure and gets thirty seconds to stop. It's wanted by the multi-user.target, which is why it starts at boot. And it waits for the snap's mount and for snapd's AppArmor profiles to load.
03 Services that something else starts for app developers for administrators
timer: on a service generates snap.<snap>.<app>.timer with OnCalendar= lines; sockets: generates a .socket unit. The service then has no [Install] section, and start and enable act on the timer or socket.
The agent runs all the time. The report shouldn't: it should run on weekday mornings and then get out of the way. That's one more line, timer, in snapd's own schedule syntax. snapd turns it into a second unit, a systemd timer, with calendar lines worked out from your schedule. The service unit loses its install section, so only the timer starts it. It's started with the schedule on its command line, so snap run can check the time again. That changes what start means: snap start starts the timer and leaves the service to it, while stop stops both. Sockets work the same way, with a socket unit.
04 Two switches: running now, and starting at boot
snap stop, start and restart change whether a service is running; --disable and --enable change whether it starts at boot. Each command is a service-control change. snap logs shows the journal, 10 lines by default.
You need the agent out of the way for an hour. Stopped now, or stopped for good? snapd treats those as two questions. Snap stop stops it now and says nothing about tomorrow: after a reboot, it's back. snap stop --disable keeps it down across reboots, and snap start --enable is the mirror image. So every service has two switches, and snap services shows both. Snap restart with just the snap name restarts its services, skipping any that are stopped and disabled. Each of these commands is a change, so snap changes lists it. Snap logs shows the service's journal: the last ten lines, or follow it live.
05 What a refresh does to a running service
A refresh stops a snap's services before the old revision is unlinked and starts them after the new one is linked. Services that were disabled stay disabled. If the start fails the refresh is undone.
Tonight the gateway refreshes acme-agent from 41 to 42. What happens to the running agent? The download and the checks happen while it keeps going. Then snapd stops the snap's services, while 41 is still in place, so nothing's writing while the data is copied for 42. It switches revisions and starts the services from 42. The agent is down for the switch, and no longer. Before stopping anything, snapd notes which services are disabled and hands that list to the start, so one you switched off doesn't come back with the refresh. And if 42's services fail to start, the refresh is undone, and 41's services start again.
06 Asking to be left running during a refresh for app developers for administrators
refresh-mode: endure: the service is not stopped for a refresh and keeps running the old revision until restarted. If the new revision drops the service it is stopped. A refresh that fails after the services started stops it during the undo.
Suppose the agent is halfway through a long upload when the refresh comes. You can ask snapd to leave it alone, with refresh-mode: endure. snapd skips it when stopping services for a refresh. The process runs straight through the switch, same main PID, and snapd doesn't restart it afterwards either. The price: it's still 41's program until something restarts it. And endure has limits. It's stopped anyway if 42 drops the service, or if the refresh fails late and is undone.
07 Choosing how the agent is stopped for app developers for administrators
stop-mode sets KillSignal=; without -all it also sets KillMode=process, so only the main process is signalled. stop-timeout sets TimeoutStopSec=, 30 seconds by default.
Sooner or later the agent is stopped: by you, by a refresh, or at shutdown. How does it find out? Say nothing, and systemd's defaults apply: every process of the service gets the stop signal. stop-mode names a different signal, here the hangup signal. Without the all suffix, only the main process gets it, and snapd writes that into the unit as a KillMode. With the suffix, every process of the service does. stop-timeout says how long systemd waits for it to finish: thirty seconds by default.
08 The first start, and services that should wait for app developers for administrators
start-snap-services enables and starts services after the install and default-configure hooks and before configure, ordered by before: and after:. A new service with install-mode: disable is left disabled.
Rewind to the day acme-agent was first installed here. When did the agent actually start? At a fixed point: after the install hook and the default-configure hook, and before the configure hook. That's why default-configure exists: defaults are in place before the first start. Now imagine acme-agent had two more apps. snapd enables each service and starts them one at a time, so an uploader that says after agent starts second. A maintenance service with install-mode: disable is installed, but neither enabled nor started, as long as it's new in this revision and no hook enabled it. You, or the snap's own hook, switch it on later.
09 Where to go from here
Roads: refresh, snapctl service commands, configuration, lifecycle hooks, the overlord and confinement.
snapd writes the units, systemd stands watch, and you've got a handful of commands. Here's where the surrounding pieces are explained. The refresh deck covers the whole change around the stop and the start. The snapctl deck shows a snap starting and stopping its own services from inside. Configuration covers the configure hook that runs after the first start. The hooks deck walks through everything that runs around install and refresh. The overlord explains the changes your service commands create. And confinement is what the daemon runs under.
Read more
Commands
| Command | Effect |
|---|---|
snap services [<snap> or <snap>.<app>...] | list services: Service, Startup, Current, Notes |
snap start [--enable] <service>... | start; with --enable also start at boot. Prints Started. |
snap stop [--disable] <service>... | stop; with --disable also keep it from starting at boot. Prints Stopped. |
snap restart [--reload] <service>... | restart; with --reload, reload if the service supports it. Prints Restarted. |
snap logs [-n=<N> or -n=all] [-f] <service>... | show the journal; 10 lines by default |
A service argument is a snap name, meaning all its services, or <snap>.<app>. Scope flags for user services: --system, --user, --users=all. Notes may show user, timer-activated, socket-activated, dbus-activated.
Restart rule: a service named explicitly is restarted whatever its state. When only the snap is named, an inactive service is restarted only if it is enabled.
For a service started by a timer or a socket, snap start acts on the timer or socket unit and leaves the service to it; snap stop stops both.
If snap start --enable fails for one service, the cleanup disables every service the command named, including ones that were enabled before (a snapd issue). Check snap services after a failure.
Messages: There are no services provided by installed snaps., no such service: <name>, <name> is not a service, cannot read logs for app "<name>": not a service.
From inside the snap, snapctl start, stop and restart act on the snap's own services; see snapctl: services, refresh and changes.
for app developers for administrators
Units snapd generates
| Unit | Name | Directory | Wanted by |
|---|---|---|---|
| Service | snap.<snap>.<app>.service | /etc/systemd/system | multi-user.target |
| Timer | snap.<snap>.<app>.timer | /etc/systemd/system | timers.target |
| Socket | snap.<snap>.<app>.<socket>.socket | /etc/systemd/system | sockets.target |
| User service | snap.<snap>.<app>.service | /etc/systemd/user | default.target |
A service with a timer, sockets or activates-on has no [Install] section.
for app developers for administrators
From snap.yaml to the unit
| App field | Unit line | Default |
|---|---|---|
daemon | Type= | required for a service; simple, forking, oneshot, dbus, notify |
command | ExecStart=/usr/bin/snap run <snap>.<app> | |
stop-command | ExecStop=/usr/bin/snap run --command=stop ... | |
reload-command | ExecReload=/usr/bin/snap run --command=reload ... | |
post-stop-command | ExecStopPost=/usr/bin/snap run --command=post-stop ... | |
restart-condition | Restart= | on-failure; never is written as no |
restart-delay | RestartSec= | not written |
stop-timeout | TimeoutStopSec= | 30 seconds |
start-timeout | TimeoutStartSec= | not written |
watchdog-timeout | WatchdogSec= | not written |
success-exit-status | SuccessExitStatus= | not written |
stop-mode | KillSignal=, and KillMode=process without -all | systemd's defaults |
after, before | After=, Before= and snapd's start order | |
bus-name, activates-on | BusName= for daemon: dbus | |
timer | a .timer unit; ExecStart gains --timer="<spec>" | |
sockets | one .socket unit per socket |
Always present: X-Snappy=yes, EnvironmentFile=-/etc/environment, SyslogIdentifier=<snap>.<app>, WorkingDirectory= the snap's data directory. System services also get Requires= and After= the snap's mount unit, Wants= and After= network.target, and After=snapd.apparmor.service, the unit that loads the AppArmor profiles snapd manages.
Special cases: oneshot forces Restart=no and adds RemainAfterExit=yes when there is a stop command. Restart conditions: never, on-success, on-failure, on-abnormal, on-abort, on-watchdog, always. Stop modes: sigterm, sighup, sigusr1, sigusr2, sigint, each also with -all.
after: and before: name other services of the same snap with the same daemon-scope.
for app developers for administrators
Behaviour fields
| Field | Values | Effect |
|---|---|---|
refresh-mode | endure, restart | endure: not stopped for a refresh, unless the new revision drops the service. If the refresh fails after start-snap-services, the undo stops it (a snapd issue). For apps that are not services the only value is ignore-running |
install-mode | enable, disable | disable: a service new in this revision is not enabled or started, unless a hook enabled it |
daemon-scope | system, user | defaults to system |
Sockets: listen-stream may be an abstract socket @snap.<snap>.<name>, a path under $SNAP_DATA, $SNAP_COMMON or $XDG_RUNTIME_DIR, or a network address; socket-mode sets the mode. A confined snap needs the network-bind plug.
for app developers for administrators
User daemons
daemon-scope: userunits are written to/etc/systemd/userand wanted bydefault.target.- Installing a snap with a user daemon needs
snap set system experimental.user-daemons=true, except for a short list of snaps allowed by snap id. - snapd enables them for all users and starts and stops them in running sessions through the user session agent.
- In
snap servicesrun as root, Current shows-for a user daemon. - A new
install-mode: disableuser daemon is kept disabled only for users with a running session at install time; with no session it is enabled for all users (a snapd bug).
for administrators
Quota groups
| Command | Effect |
|---|---|
snap set-quota <group> [--memory=] [--cpu=] [--cpu-set=] [--threads=] [--journal-size=] [--journal-rate-limit=] [--parent=] [<snap>...] | create or change a group |
snap quota <group> | show one group |
snap quotas | list groups |
snap remove-quota <group> | delete a group |
A snap is in at most one group; groups can be nested. A group is a systemd slice snap.<group>.slice, and each member service unit gets a Slice= line.
resilience.vitality-hint (a system option) adds OOMScoreAdjust= to the services of the snaps it lists.
for administrators
Changes and tasks
| Operation | Change kind | Task kinds |
|---|---|---|
snap start, stop, restart | service-control, summary Running service command | one service-control per snap; no undo |
| install, refresh | the install or refresh change | stop-snap-services, start-snap-services |
| quota commands | quota-control, quota-add-snap |
snap changes lists service-control changes like any other; see The overlord.
Further reading
- Control services: the service commands with sample output.
- The snap format: the app keys for daemons. It omits
daemon: dbusand thesigintstop modes. - Install modes:
install-mode: disableand enabling such a service later. - Timer string format: the syntax of
timer:. - Use resource quotas: quota groups in full.
- Use snapctl: controlling services from hooks and apps.
Roads from here
GETTING SNAPS
- Snap packaging — where apps are declared in snap.yaml
INTERFACES AND CONFINEMENT
- Confinement — the confinement a service runs under
RUNNING SNAPS
- Refresh — the refresh that stops and starts services
- Configuration — the configure hook that runs after services start
- The overlord — service operations are changes
SNAPCTL · the snap's API into snapd
- snapctl: services, refresh and changes — starting and stopping services from inside the snap
HOOKS · code snapd runs inside a snap
- Hooks: install, configure, refresh, remove — the hooks around install and refresh
ADMINISTRATION · managing a system of snaps
- Quota groups — limits for a group of services
DESKTOP · snaps in a user session
- The user session agent — user services and the session agent