8716b71ea6
Divide the "Service Management" chapter into two sections. The 1st (the original) explaining General, not NixOS specific ways to interact with Systemd. The 2nd section, explaining NixOS specific things worth knowing. Explain in the 2nd section a bit NixOS modules and services of Nixpkgs, and mention `systemd.user.services` option. Give an example demonstrating how to enable imperatively an upstream provided unit file for a user. Explain why `systemctl --user enable` doesn't work for the long term on NixOS.
141 lines
6.8 KiB
XML
141 lines
6.8 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
version="5.0"
|
|
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 “init” process of the system (i.e. PID 1), the
|
|
parent of all other processes. It manages a set of so-called “units”,
|
|
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 <command>systemctl</command> is the main way to interact with
|
|
<command>systemd</command>. The following paragraphs demonstrate ways to
|
|
interact with any OS running systemd as init system. NixOS is of no
|
|
exception. The <link xlink:href="#sect-nixos-systemd-nixos">next section
|
|
</link> explains NixOS specific things worth knowing.
|
|
</para>
|
|
<para>
|
|
Without any arguments, <literal>systmctl</literal> the status of active units:
|
|
<screen>
|
|
<prompt>$ </prompt>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
|
|
<replaceable>...</replaceable>
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
You can ask for detailed status information about a unit, for instance, the
|
|
PostgreSQL database service:
|
|
<screen>
|
|
<prompt>$ </prompt>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.
|
|
</screen>
|
|
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:
|
|
<screen>
|
|
# systemctl stop postgresql.service
|
|
# systemctl start postgresql.service
|
|
# systemctl restart postgresql.service
|
|
</screen>
|
|
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>
|
|
<!-- TODO: document cgroups, draft:
|
|
each service and user session is a cgroup
|
|
|
|
- cgroup resource management -->
|
|
</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):
|
|
<programlisting>
|
|
<xref linkend="opt-systemd.packages"/> = [ pkgs.packagekit ];
|
|
</programlisting>
|
|
</para>
|
|
<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.
|
|
<!-- TODO: Document why systemd.packages doesn't work for user services or fix this.
|
|
https://github.com/NixOS/nixpkgs/blob/2cd6594a8710a801038af2b72348658f732ce84a/nixos/modules/system/boot/systemd-lib.nix#L177-L198
|
|
|
|
This has been talked over at https://discourse.nixos.org/t/how-to-enable-upstream-systemd-user-services-declaratively/7649/5
|
|
-->
|
|
However, You can imperatively enable it by adding the package's attribute to
|
|
<link linkend="opt-environment.systemPackages">
|
|
<literal>systemd.packages</literal></link> and then do this (e.g):
|
|
<screen>
|
|
<prompt>$ </prompt>mkdir -p ~/.config/systemd/user/default.target.wants
|
|
<prompt>$ </prompt>ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
|
|
<prompt>$ </prompt>systemctl --user daemon-reload
|
|
<prompt>$ </prompt>systemctl --user enable syncthing.service
|
|
</screen>
|
|
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 xlink:href="#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>
|
|
|