07cb3bf3cc
Update the pinned channel in `md-to-db`, which bumps the Pandoc version, which fixes https://github.com/NixOS/nixpkgs/issues/125511 maybe.
141 lines
6.5 KiB
XML
141 lines
6.5 KiB
XML
<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="nix">
|
||
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>
|