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