From 8716b71ea632a6163b9fd3845c570bdfc0590dad Mon Sep 17 00:00:00 2001 From: Doron Behar Date: Thu, 24 Sep 2020 18:26:30 +0300 Subject: [PATCH] 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. --- .../manual/administration/service-mgmt.xml | 98 ++++++++++++++++--- 1 file changed, 83 insertions(+), 15 deletions(-) diff --git a/nixos/doc/manual/administration/service-mgmt.xml b/nixos/doc/manual/administration/service-mgmt.xml index 1b9c745eb59f..66a4e31ceda2 100644 --- a/nixos/doc/manual/administration/service-mgmt.xml +++ b/nixos/doc/manual/administration/service-mgmt.xml @@ -6,7 +6,7 @@ Service Management 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. - - The command systemctl is the main way to interact with - systemd. Without any arguments, it shows the status of - active units: +
+ Interacting with a running systemd + + The command systemctl is the main way to interact with + systemd. The following paragraphs demonstrate ways to + interact with any OS running systemd as init system. NixOS is of no + exception. The next section + explains NixOS specific things worth knowing. + + + Without any arguments, systmctl the status of active units: $ systemctl -.mount loaded active mounted / @@ -28,10 +35,10 @@ sshd.service loaded active running SSH Daemon graphical.target loaded active active Graphical Interface ... - - - You can ask for detailed status information about a unit, for instance, the - PostgreSQL database service: + + + You can ask for detailed status information about a unit, for instance, the + PostgreSQL database service: $ systemctl status postgresql.service postgresql.service - PostgreSQL Server @@ -62,11 +69,72 @@ Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server. # systemctl start postgresql.service # systemctl restart postgresql.service - 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). - - + - cgroup resource management --> +
+
+ systemd in NixOS + + Packages in Nixpkgs sometimes provide systemd units with them, usually in + e.g #pkg-out#/lib/systemd/. Putting such a package in + environment.systemPackages doesn't make the service + available to users or the system. + + + In order to enable a systemd system service with + provided upstream package, use (e.g): + + = [ pkgs.packagekit ]; + + + + 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 + services.#name#.enable = true;. These services are defined + in Nixpkgs' + + nixos/modules/ directory . In case the service is + simple enough, the above method should work, and start the service on boot. + + + User systemd services on the other hand, should be + treated differently. Given a package that has a systemd unit file at + #pkg-out#/lib/systemd/user/, using + will make you able to start the service via + systemctl --user start, but it won't start automatically on login. + + However, You can imperatively enable it by adding the package's attribute to + + systemd.packages and then do this (e.g): + +$ 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 + + If you are interested in a timer file, use timers.target.wants + instead of default.target.wants in the 1st and 2nd command. + + + Using systemctl --user enable syncthing.service instead of + the above, will work, but it'll use the absolute path of + syncthing.service for the symlink, and this path is in + /nix/store/.../lib/systemd/user/. Hence + garbage collection 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. + +
+