Services and timers

Declare long-running services and scheduled jobs once, and run them on systemd, launchd, runit, OpenRC, dinit or s6.

service(...) describes a program that runs in the background: what to run, whether to restart it, and what it needs first. fspec renders that description for the host's init system, whether that is systemd, launchd on macOS, or runit, OpenRC, dinit or s6. timer(...) runs a command on a schedule. You write each once and the same line works on every host, as long as it only uses fields that host's init supports.

The host's init comes from its system: systemd for an image(...) host and most distros, runit for void(), launchd on macOS, and whatever you pass as init = ... to a distro builtin. See Hosts and modules.

Run a service

service("syncthing", exec = "syncthing serve --no-browser",
        user = True, restart = "always", after = ["network"]),

On apply, fspec writes the unit, enables it so it starts at boot (or login), and starts it now. The plan shows the command:

$ fspec plan
host laptop
  + service:syncthing  syncthing serve --no-browser
  1 to add, 0 to change, 0 to remove

A changed service is restarted. A removed one is stopped, disabled, and its files deleted.

System or user

A system service is in the system scope: fspec writes it as root and the init runs it as root. user = True puts it in the user scope: it runs as you, under your login session, and its files live in your home. Use a user service for anything that belongs to you, such as a sync client or an agent that needs your files.

On systemd a user service is a user unit, started by your user manager at login. On macOS it is a LaunchAgent in your GUI session. OpenRC and s6 have no user services.

exec

exec is one line. A bare command name such as syncthing is looked up on PATH through /usr/bin/env, since init systems do not search PATH themselves. Use a full path when the command lives somewhere the init's PATH does not reach, such as /opt/fspec/current/bin/x.

Shell syntax (pipes, redirects, $VAR, globs, ~) works: where the init wants an argument list, fspec runs such a command through /bin/sh -c.

restart

after

launchd has no ordering between jobs, so it ignores after and description.

env

service("web", exec = "/opt/web/bin/server --port 8080",
        restart = "on_failure", env = {"RUST_LOG": "info"}),

systemd gets Environment= lines, launchd EnvironmentVariables, runit, OpenRC and s6 export lines in their scripts, and dinit a leading /usr/bin/env RUST_LOG=info. Names must be valid shell variable names and values one line.

Escape hatches

Features only one init has go under that init's own argument. On any other init, plan fails and names the field instead of dropping it, so a spec never silently loses a setting.

systemd = {...}

Each key is a [Service] directive. The keys unit, service and install take a dict of directives for that section. A directive you set replaces the one fspec generated with the same name, and a list repeats the directive. Booleans become yes and no.

service(
    "web",
    exec = "/opt/web/bin/server --port 8080",
    restart = "on_failure",
    env = {"RUST_LOG": "info"},
    systemd = {
        "MemoryMax": "512M",
        "unit": {"StartLimitBurst": 3},
    },
),

fspec writes /etc/systemd/system/fspec-web.service:

# Managed by fspec. Edits are overwritten on the next apply.

[Unit]
Description=web
StartLimitBurst=3

[Service]
ExecStart=/opt/web/bin/server --port 8080
Restart=on-failure
Environment="RUST_LOG=info"
MemoryMax=512M

[Install]
WantedBy=multi-user.target

A oneshot that runs at boot and counts as active afterwards:

systemd = {"Type": "oneshot", "RemainAfterExit": True,
           "unit": {"Before": "systemd-user-sessions.service"}},

A user service tied to the graphical session:

service("bar", exec = "waybar", user = True, restart = "always", after = ["graphical-session.target"],
        systemd = {"install": {"WantedBy": "graphical-session.target"}}),

A unit with RefuseManualStart or RefuseManualStop under unit is enabled and disabled but never started, stopped or restarted by apply. It starts with whatever wants it.

launchd = {...}

Raw plist keys merged over the ones fspec writes. Booleans, numbers, strings, lists and dicts map to their plist types.

service(
    "sync-notes",
    exec = "/opt/fspec/current/bin/notes-sync",
    user = True,
    launchd = {
        "StartInterval": 300,
        "StandardOutPath": "/tmp/notes-sync.log",
        "ProcessType": "Background",
    },
),

RunAtLoad = False, KeepAlive = False gives a job that is loaded but idle until you run launchctl kickstart. WatchPaths, ThrottleInterval and LimitLoadToSessionType go in the same way.

A login item that opens an app once at login is a user service with the default restart = "no":

service("login-notes", exec = "/usr/bin/open -g -j -a /Applications/Notes.app", user = True),

Enable a unit the distro ships

Without exec, a service names a unit that a package already installed, and fspec only enables it at boot:

service("sshd"),
service("gdm", display_manager = True),

$ fspec plan
host desktop
  + service:gdm  enable the distro unit
  + service:sshd  enable the distro unit
  2 to add, 0 to change, 0 to remove

fspec does not start the unit, so a new display manager or sshd takes effect at the next boot, and the same apply works inside the root fspec switch --distro builds.

Such a service takes no restart, after, env, description or systemd. On systemd it may set user = True to enable a user unit, and the name may carry a suffix such as service("nordvpnd.socket"). Drift is the unit no longer being enabled. Removing it disables the unit and leaves the distro's files alone.

display_manager = True (systemd only) marks the login screen. While it is declared, the host boots to graphical.target. Some distros default to multi-user.target, which never starts a display manager. Plan reports another default as drift, and removing the service puts back the default it replaced.

Services that belong to a package

A service declared on a package goes with it:

pkg(
    "nordvpn",
    source = zypper(repo = "nordvpn"),
    services = [service("nordvpnd.socket"), service("nordvpnd")],
),
pkg("syncthing", services = [
    service("syncthing", exec = "syncthing serve --no-browser", user = True, restart = "always"),
]),

Removing the pkg line stops and removes its services and timers first, then uninstalls the package. pkg(timers = [...]) works the same way. See Packages.

Restart after a package update

On systemd, apply restarts a running service whose program moved to a new store directory. When a pkg update moves /opt/fspec/current/bin/web to a new version, the running process still executes the old one. fspec compares the unit's ExecStart with the process's executable, and if they resolve to different packages in the store, plan reports the service and apply restarts it:

$ fspec plan
host server
  ! service:web drifted: fspec-web.service runs 1a2b3c4d-web-1.4.0, the store now has 5e6f7a8b-web-1.5.0
  0 to add, 1 to change, 0 to remove
$ fspec apply
...
service:web: restarted, fspec-web.service runs 1a2b3c4d-web-1.4.0, the store now has 5e6f7a8b-web-1.5.0

This covers fspec's own services and distro units, system and user, including a user service that runs a package from the system scope. A unit that refuses manual starts or stops is left for its next start. The other inits do not restart a service for this.

Run a command on a schedule

timer("backup", exec = "restic backup ~/Documents", schedule = "30 2 * * *", user = True),
timer("gc", exec = "/usr/local/bin/fspec gc --older-than 14d", schedule = "@weekly"),

Fields take numbers, *, ranges (1-5), lists (1,15), steps (*/10, 0-30/5), and month and day names (jan, mon). A schedule that restricts both day-of-month and day-of-week fails plan: cron runs the job when either matches, systemd only when both do, so fspec refuses to guess.

A cron system timer is /etc/cron.d/fspec-<name>, run as root. A user timer is a block in your crontab between # BEGIN fspec:<name> and # END fspec:<name>; fspec leaves the rest of the crontab alone. fspec expects a cron that reads /etc/cron.d, such as cronie or vixie-cron. dcron, busybox crond and snooze are not supported.

Where each init's files go

systemd units, OpenRC scripts, dinit files and cron files start with # Managed by fspec. Edits are overwritten on the next apply. An edit to any file fspec rendered shows as drift (... was edited), and the next apply writes the file again.

Init details

• systemd. Apply runs systemctl daemon-reload, then enable and start for a new unit or restart for a changed one (--user for a user unit). A user unit starts with your user manager, so it runs while you are logged in.
• launchd. System jobs load into the system domain, user jobs into gui/<uid>, with launchctl bootstrap. A change runs launchctl bootout, then bootstrap again.
• runit. runsvdir picks up a new link within five seconds, so an add runs no command. A change runs sv restart, a removal sv down. User services are scanned by a system service fspec-runsvdir-<user>, created by the first user service, so that apply needs root. It stays when the last user service goes.
• OpenRC. Apply runs rc-update add fspec-<name> default and rc-service fspec-<name> start.
• dinit. Apply runs dinitctl enable and start; a change runs reload, then restart. enable needs the boot service to have a waits-for.d directory.
• s6. Every fspec service is also in the bundle /etc/s6/sv/fspec, which the host's boot bundle must include. Apply compiles /etc/s6/sv with s6-rc-compile into /etc/s6/db/fspec-g<generation>-a, switches with s6-rc-update, and starts the bundle with s6-rc -u change fspec. Old databases stay in /etc/s6/db.

A unit file you write yourself with file(...) under /etc/systemd/system or ~/.config/systemd/user also gets a daemon-reload, but fspec does not enable it. Pair it with service("<unit name>") to enable it.

Troubleshooting