pyrox.dev
1# Service Management {#sec-systemctl}
2
3In NixOS, all system services are started and monitored using the
4systemd program. systemd is the "init" process of the system (i.e. PID
51), the parent of all other processes. It manages a set of so-called
6"units", which can be things like system services (programs), but also
7mount points, swap files, devices, targets (groups of units) and more.
8Units can have complex dependencies; for instance, one unit can require
9that another unit must be successfully started before the first unit can
10be started. When the system boots, it starts a unit named
11`default.target`; the dependencies of this unit cause all system
12services to be started, file systems to be mounted, swap files to be
13activated, and so on.
14
15## Interacting with a running systemd {#sect-nixos-systemd-general}
16
17The command `systemctl` is the main way to interact with `systemd`. The
18following paragraphs demonstrate ways to interact with any OS running
19systemd as init system. NixOS is of no exception. The [next section
20](#sect-nixos-systemd-nixos) explains NixOS specific things worth
21knowing.
22
23Without any arguments, `systemctl` the status of active units:
24
25```ShellSession
26$ systemctl
27-.mount loaded active mounted /
28swapfile.swap loaded active active /swapfile
29sshd.service loaded active running SSH Daemon
30graphical.target loaded active active Graphical Interface
31...
32```
33
34You can ask for detailed status information about a unit, for instance,
35the PostgreSQL database service:
36
37```ShellSession
38$ systemctl status postgresql.service
39postgresql.service - PostgreSQL Server
40 Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)
41 Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago
42 Main PID: 2390 (postgres)
43 CGroup: name=systemd:/system/postgresql.service
44 ├─2390 postgres
45 ├─2418 postgres: writer process
46 ├─2419 postgres: wal writer process
47 ├─2420 postgres: autovacuum launcher process
48 ├─2421 postgres: stats collector process
49 └─2498 postgres: zabbix zabbix [local] idle
50
51Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET
52Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections
53Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started
54Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
55```
56
57Note that this shows the status of the unit (active and running), all
58the processes belonging to the service, as well as the most recent log
59messages from the service.
60
61Units can be stopped, started or restarted:
62
63```ShellSession
64# systemctl stop postgresql.service
65# systemctl start postgresql.service
66# systemctl restart postgresql.service
67```
68
69These operations are synchronous: they wait until the service has
70finished starting or stopping (or has failed). Starting a unit will
71cause the dependencies of that unit to be started as well (if
72necessary).
73
74## systemd in NixOS {#sect-nixos-systemd-nixos}
75
76Packages in Nixpkgs sometimes provide systemd units with them, usually
77in e.g `#pkg-out#/lib/systemd/`. Putting such a package in
78`environment.systemPackages` doesn't make the service available to
79users or the system.
80
81In order to enable a systemd *system* service with provided upstream
82package, use (e.g):
83
84```nix
85{
86 systemd.packages = [ pkgs.packagekit ];
87}
88```
89
90Usually NixOS modules written by the community do the above, plus take
91care of other details. If a module was written for a service you are
92interested in, you'd probably need only to use
93`services.#name#.enable = true;`. These services are defined in
94Nixpkgs' [ `nixos/modules/` directory
95](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules). In case
96the service is simple enough, the above method should work, and start
97the service on boot.
98
99*User* systemd services on the other hand, should be treated
100differently. Given a package that has a systemd unit file at
101`#pkg-out#/lib/systemd/user/`, using [](#opt-systemd.packages) will
102make you able to start the service via `systemctl --user start`, but it
103won't start automatically on login. However, You can imperatively
104enable it by adding the package's attribute to
105[](#opt-systemd.packages) and then do this (e.g):
106
107```ShellSession
108$ mkdir -p ~/.config/systemd/user/default.target.wants
109$ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
110$ systemctl --user daemon-reload
111$ systemctl --user enable syncthing.service
112```
113
114If you are interested in a timer file, use `timers.target.wants` instead
115of `default.target.wants` in the 1st and 2nd command.
116
117Using `systemctl --user enable syncthing.service` instead of the above,
118will work, but it'll use the absolute path of `syncthing.service` for
119the symlink, and this path is in `/nix/store/.../lib/systemd/user/`.
120Hence [garbage collection](#sec-nix-gc) will remove that file and you
121will wind up with a broken symlink in your systemd configuration, which
122in turn will not make the service / timer start on login.
123
124## Template units {#sect-nixos-systemd-template-units}
125
126systemd supports templated units where a base unit can be started multiple
127times with a different parameter. The syntax to accomplish this is
128`service-name@instance-name.service`. Units get the instance name passed to
129them (see `systemd.unit(5)`). NixOS has support for these kinds of units and
130for template-specific overrides. A service needs to be defined twice, once
131for the base unit and once for the instance. All instances must include
132`overrideStrategy = "asDropin"` for the change detection to work. This
133example illustrates this:
134```nix
135{
136 systemd.services = {
137 "base-unit@".serviceConfig = {
138 ExecStart = "...";
139 User = "...";
140 };
141 "base-unit@instance-a" = {
142 overrideStrategy = "asDropin"; # needed for templates to work
143 wantedBy = [ "multi-user.target" ]; # causes NixOS to manage the instance
144 };
145 "base-unit@instance-b" = {
146 overrideStrategy = "asDropin"; # needed for templates to work
147 wantedBy = [ "multi-user.target" ]; # causes NixOS to manage the instance
148 serviceConfig.User = "root"; # also override something for this specific instance
149 };
150 };
151}
152```