Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: NixOS/nixpkgs
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: eed561b82f74
Choose a base ref
...
head repository: NixOS/nixpkgs
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: 25d15ebffb7d
Choose a head ref
  • 2 commits
  • 1 file changed
  • 2 contributors

Commits on Nov 6, 2020

  1. doc/nixos: Explain better NixOS specific Systemd stuff

    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.
    doronbehar committed Nov 6, 2020
    Copy the full SHA
    8716b71 View commit details
  2. Merge pull request #98661 from doronbehar/doc/nixos/systemd-nixos-spe…

    …cific
    
    doc/nixos: Explain better NixOS specific Systemd stuff
    rnhmjoj authored Nov 6, 2020
    Copy the full SHA
    25d15eb View commit details
Showing with 83 additions and 15 deletions.
  1. +83 −15 nixos/doc/manual/administration/service-mgmt.xml
98 changes: 83 additions & 15 deletions nixos/doc/manual/administration/service-mgmt.xml
Original file line number Diff line number Diff line change
@@ -6,7 +6,7 @@
<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
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
@@ -16,10 +16,17 @@
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>
<para>
The command <command>systemctl</command> is the main way to interact with
<command>systemd</command>. Without any arguments, it shows the status of
active units:
<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 /
@@ -28,10 +35,10 @@ 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:
</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
@@ -62,11 +69,72 @@ Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
<prompt># </prompt>systemctl start postgresql.service
<prompt># </prompt>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>
<!-- - cgroups: each service and user session is a cgroup
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 -->
- 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>