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