nixos/doc/manual/administration/service-mgmt.chapter.md

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