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 systemd.packages = [ pkgs.packagekit ];
  86 ```
  87
  88 Usually NixOS modules written by the community do the above, plus take
  89 care of other details. If a module was written for a service you are
  90 interested in, you\'d probably need only to use
  91 `services.#name#.enable = true;`. These services are defined in
  92 Nixpkgs\' [ `nixos/modules/` directory
  93 ](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules). In case
  94 the service is simple enough, the above method should work, and start
  95 the service on boot.
  96
  97 *User* systemd services on the other hand, should be treated
  98 differently. Given a package that has a systemd unit file at
  99 `#pkg-out#/lib/systemd/user/`, using [](#opt-systemd.packages) will
 100 make you able to start the service via `systemctl --user start`, but it
 101 won\'t start automatically on login. However, You can imperatively
 102 enable it by adding the package\'s attribute to
 103 [](#opt-systemd.packages) and then do this (e.g):
 104
 105 ```ShellSession
 106 $ mkdir -p ~/.config/systemd/user/default.target.wants
 107 $ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
 108 $ systemctl --user daemon-reload
 109 $ systemctl --user enable syncthing.service
 110 ```
 111
 112 If you are interested in a timer file, use `timers.target.wants` instead
 113 of `default.target.wants` in the 1st and 2nd command.
 114
 115 Using `systemctl --user enable syncthing.service` instead of the above,
 116 will work, but it\'ll use the absolute path of `syncthing.service` for
 117 the symlink, and this path is in `/nix/store/.../lib/systemd/user/`.
 118 Hence [garbage collection](#sec-nix-gc) will remove that file and you
 119 will wind up with a broken symlink in your systemd configuration, which
 120 in turn will not make the service / timer start on login.