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
85systemd.packages = [ pkgs.packagekit ];
86```
87
88Usually NixOS modules written by the community do the above, plus take
89care of other details. If a module was written for a service you are
90interested in, you\'d probably need only to use
91`services.#name#.enable = true;`. These services are defined in
92Nixpkgs\' [ `nixos/modules/` directory
93](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules). In case
94the service is simple enough, the above method should work, and start
95the service on boot.
96
97*User* systemd services on the other hand, should be treated
98differently. Given a package that has a systemd unit file at
99`#pkg-out#/lib/systemd/user/`, using [](#opt-systemd.packages) will
100make you able to start the service via `systemctl --user start`, but it
101won\'t start automatically on login. However, You can imperatively
102enable it by adding the package\'s attribute to
103[](#opt-systemd.packages) and then do this (e.g):
104
105```ShellSession
106$ mkdir -p ~/.config/systemd/user/default.target.wants
107$ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
108$ systemctl --user daemon-reload
109$ systemctl --user enable syncthing.service
110```
111
112If you are interested in a timer file, use `timers.target.wants` instead
113of `default.target.wants` in the 1st and 2nd command.
114
115Using `systemctl --user enable syncthing.service` instead of the above,
116will work, but it\'ll use the absolute path of `syncthing.service` for
117the symlink, and this path is in `/nix/store/.../lib/systemd/user/`.
118Hence [garbage collection](#sec-nix-gc) will remove that file and you
119will wind up with a broken symlink in your systemd configuration, which
120in turn will not make the service / timer start on login.