commit d37933c01f5bda5ed0d838d28d5e8180559ea953 · pyrox.dev/nixpkgs

+1 -1

nixos/doc/manual/administration/running.xml

···

       10
       10
        
          such as how to use the <command>systemd</command> service manager.

     

       11
       11
        
         </para>

     

       12
       12
        
        </partintro>

     

       13
       13
       -
        <xi:include href="service-mgmt.xml" />

     

       13
       13
       +
        <xi:include href="../from_md/administration/service-mgmt.chapter.xml" />

     

       14
       14
        
        <xi:include href="rebooting.xml" />

     

       15
       15
        
        <xi:include href="user-sessions.xml" />

     

       16
       16
        
        <xi:include href="control-groups.xml" />

+121

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

···

       1
       1
       +
       # Service Management {#sec-systemctl}

     

       2
       2
       +
       

     

       3
       3
       +
       In NixOS, all system services are started and monitored using the

     

       4
       4
       +
       systemd program. systemd is the "init" process of the system (i.e. PID

     

       5
       5
       +
       1), the parent of all other processes. It manages a set of so-called

     

       6
       6
       +
       "units", which can be things like system services (programs), but also

     

       7
       7
       +
       mount points, swap files, devices, targets (groups of units) and more.

     

       8
       8
       +
       Units can have complex dependencies; for instance, one unit can require

     

       9
       9
       +
       that another unit must be successfully started before the first unit can

     

       10
       10
       +
       be started. When the system boots, it starts a unit named

     

       11
       11
       +
       `default.target`; the dependencies of this unit cause all system

     

       12
       12
       +
       services to be started, file systems to be mounted, swap files to be

     

       13
       13
       +
       activated, and so on.

     

       14
       14
       +
       

     

       15
       15
       +
       ## Interacting with a running systemd {#sect-nixos-systemd-general}

     

       16
       16
       +
       

     

       17
       17
       +
       The command `systemctl` is the main way to interact with `systemd`. The

     

       18
       18
       +
       following paragraphs demonstrate ways to interact with any OS running

     

       19
       19
       +
       systemd as init system. NixOS is of no exception. The [next section

     

       20
       20
       +
       ](#sect-nixos-systemd-nixos) explains NixOS specific things worth

     

       21
       21
       +
       knowing.

     

       22
       22
       +
       

     

       23
       23
       +
       Without any arguments, `systmctl` the status of active units:

     

       24
       24
       +
       

     

       25
       25
       +
       ```ShellSession

     

       26
       26
       +
       $ systemctl

     

       27
       27
       +
       -.mount          loaded active mounted   /

     

       28
       28
       +
       swapfile.swap    loaded active active    /swapfile

     

       29
       29
       +
       sshd.service     loaded active running   SSH Daemon

     

       30
       30
       +
       graphical.target loaded active active    Graphical Interface

     

       31
       31
       +
       ...

     

       32
       32
       +
       ```

     

       33
       33
       +
       

     

       34
       34
       +
       You can ask for detailed status information about a unit, for instance,

     

       35
       35
       +
       the PostgreSQL database service:

     

       36
       36
       +
       

     

       37
       37
       +
       ```ShellSession

     

       38
       38
       +
       $ systemctl status postgresql.service

     

       39
       39
       +
       postgresql.service - PostgreSQL Server

     

       40
       40
       +
                 Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)

     

       41
       41
       +
                 Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago

     

       42
       42
       +
               Main PID: 2390 (postgres)

     

       43
       43
       +
                 CGroup: name=systemd:/system/postgresql.service

     

       44
       44
       +
                         ├─2390 postgres

     

       45
       45
       +
                         ├─2418 postgres: writer process

     

       46
       46
       +
                         ├─2419 postgres: wal writer process

     

       47
       47
       +
                         ├─2420 postgres: autovacuum launcher process

     

       48
       48
       +
                         ├─2421 postgres: stats collector process

     

       49
       49
       +
                         └─2498 postgres: zabbix zabbix [local] idle

     

       50
       50
       +
       

     

       51
       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
       52
       +
       Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG:  database system is ready to accept connections

     

       53
       53
       +
       Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG:  autovacuum launcher started

     

       54
       54
       +
       Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.

     

       55
       55
       +
       ```

     

       56
       56
       +
       

     

       57
       57
       +
       Note that this shows the status of the unit (active and running), all

     

       58
       58
       +
       the processes belonging to the service, as well as the most recent log

     

       59
       59
       +
       messages from the service.

     

       60
       60
       +
       

     

       61
       61
       +
       Units can be stopped, started or restarted:

     

       62
       62
       +
       

     

       63
       63
       +
       ```ShellSession

     

       64
       64
       +
       # systemctl stop postgresql.service

     

       65
       65
       +
       # systemctl start postgresql.service

     

       66
       66
       +
       # systemctl restart postgresql.service

     

       67
       67
       +
       ```

     

       68
       68
       +
       

     

       69
       69
       +
       These operations are synchronous: they wait until the service has

     

       70
       70
       +
       finished starting or stopping (or has failed). Starting a unit will

     

       71
       71
       +
       cause the dependencies of that unit to be started as well (if

     

       72
       72
       +
       necessary).

     

       73
       73
       +
       

     

       74
       74
       +
       ## systemd in NixOS {#sect-nixos-systemd-nixos}

     

       75
       75
       +
       

     

       76
       76
       +
       Packages in Nixpkgs sometimes provide systemd units with them, usually

     

       77
       77
       +
       in e.g `#pkg-out#/lib/systemd/`. Putting such a package in

     

       78
       78
       +
       `environment.systemPackages` doesn\'t make the service available to

     

       79
       79
       +
       users or the system.

     

       80
       80
       +
       

     

       81
       81
       +
       In order to enable a systemd *system* service with provided upstream

     

       82
       82
       +
       package, use (e.g):

     

       83
       83
       +
       

     

       84
       84
       +
       ```nix

     

       85
       85
       +
       systemd.packages = [ pkgs.packagekit ];

     

       86
       86
       +
       ```

     

       87
       87
       +
       

     

       88
       88
       +
       Usually NixOS modules written by the community do the above, plus take

     

       89
       89
       +
       care of other details. If a module was written for a service you are

     

       90
       90
       +
       interested in, you\'d probably need only to use

     

       91
       91
       +
       `services.#name#.enable = true;`. These services are defined in

     

       92
       92
       +
       Nixpkgs\' [ `nixos/modules/` directory

     

       93
       93
       +
       ](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules). In case

     

       94
       94
       +
       the service is simple enough, the above method should work, and start

     

       95
       95
       +
       the service on boot.

     

       96
       96
       +
       

     

       97
       97
       +
       *User* systemd services on the other hand, should be treated

     

       98
       98
       +
       differently. Given a package that has a systemd unit file at

     

       99
       99
       +
       `#pkg-out#/lib/systemd/user/`, using [](#opt-systemd.packages) will

     

       100
       100
       +
       make you able to start the service via `systemctl --user start`, but it

     

       101
       101
       +
       won\'t start automatically on login. However, You can imperatively

     

       102
       102
       +
       enable it by adding the package\'s attribute to [

     

       103
       103
       +
       `systemd.packages`](#opt-environment.systemPackages) and then do this

     

       104
       104
       +
       (e.g):

     

       105
       105
       +
       

     

       106
       106
       +
       ```ShellSession

     

       107
       107
       +
       $ mkdir -p ~/.config/systemd/user/default.target.wants

     

       108
       108
       +
       $ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/

     

       109
       109
       +
       $ systemctl --user daemon-reload

     

       110
       110
       +
       $ systemctl --user enable syncthing.service

     

       111
       111
       +
       ```

     

       112
       112
       +
       

     

       113
       113
       +
       If you are interested in a timer file, use `timers.target.wants` instead

     

       114
       114
       +
       of `default.target.wants` in the 1st and 2nd command.

     

       115
       115
       +
       

     

       116
       116
       +
       Using `systemctl --user enable syncthing.service` instead of the above,

     

       117
       117
       +
       will work, but it\'ll use the absolute path of `syncthing.service` for

     

       118
       118
       +
       the symlink, and this path is in `/nix/store/.../lib/systemd/user/`.

     

       119
       119
       +
       Hence [garbage collection](#sec-nix-gc) will remove that file and you

     

       120
       120
       +
       will wind up with a broken symlink in your systemd configuration, which

     

       121
       121
       +
       in turn will not make the service / timer start on login.

-140

nixos/doc/manual/administration/service-mgmt.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="sec-systemctl">

     

       6
       6
       -
        <title>Service Management</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         In NixOS, all system services are started and monitored using the systemd

     

       9
       9
       -
         program. systemd is the “init” process of the system (i.e. PID 1), the

     

       10
       10
       -
         parent of all other processes. It manages a set of so-called “units”,

     

       11
       11
       -
         which can be things like system services (programs), but also mount points,

     

       12
       12
       -
         swap files, devices, targets (groups of units) and more. Units can have

     

       13
       13
       -
         complex dependencies; for instance, one unit can require that another unit

     

       14
       14
       -
         must be successfully started before the first unit can be started. When the

     

       15
       15
       -
         system boots, it starts a unit named <literal>default.target</literal>; the

     

       16
       16
       -
         dependencies of this unit cause all system services to be started, file

     

       17
       17
       -
         systems to be mounted, swap files to be activated, and so on.

     

       18
       18
       -
        </para>

     

       19
       19
       -
        <section xml:id="sect-nixos-systemd-general">

     

       20
       20
       -
         <title>Interacting with a running systemd</title>

     

       21
       21
       -
          <para>

     

       22
       22
       -
           The command <command>systemctl</command> is the main way to interact with

     

       23
       23
       -
           <command>systemd</command>. The following paragraphs demonstrate ways to

     

       24
       24
       -
           interact with any OS running systemd as init system. NixOS is of no

     

       25
       25
       -
           exception. The <link xlink:href="#sect-nixos-systemd-nixos">next section

     

       26
       26
       -
           </link> explains NixOS specific things worth knowing.

     

       27
       27
       -
          </para>

     

       28
       28
       -
          <para>

     

       29
       29
       -
           Without any arguments, <literal>systmctl</literal> the status of active units:

     

       30
       30
       -
       <screen>

     

       31
       31
       -
       <prompt>$ </prompt>systemctl

     

       32
       32
       -
       -.mount          loaded active mounted   /

     

       33
       33
       -
       swapfile.swap    loaded active active    /swapfile

     

       34
       34
       -
       sshd.service     loaded active running   SSH Daemon

     

       35
       35
       -
       graphical.target loaded active active    Graphical Interface

     

       36
       36
       -
       <replaceable>...</replaceable>

     

       37
       37
       -
       </screen>

     

       38
       38
       -
         </para>

     

       39
       39
       -
         <para>

     

       40
       40
       -
          You can ask for detailed status information about a unit, for instance, the

     

       41
       41
       -
          PostgreSQL database service:

     

       42
       42
       -
       <screen>

     

       43
       43
       -
       <prompt>$ </prompt>systemctl status postgresql.service

     

       44
       44
       -
       postgresql.service - PostgreSQL Server

     

       45
       45
       -
                 Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)

     

       46
       46
       -
                 Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago

     

       47
       47
       -
               Main PID: 2390 (postgres)

     

       48
       48
       -
                 CGroup: name=systemd:/system/postgresql.service

     

       49
       49
       -
                         ├─2390 postgres

     

       50
       50
       -
                         ├─2418 postgres: writer process

     

       51
       51
       -
                         ├─2419 postgres: wal writer process

     

       52
       52
       -
                         ├─2420 postgres: autovacuum launcher process

     

       53
       53
       -
                         ├─2421 postgres: stats collector process

     

       54
       54
       -
                         └─2498 postgres: zabbix zabbix [local] idle

     

       55
       55
       -
       

     

       56
       56
       -
       Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG:  database system was shut down at 2013-01-07 15:55:05 CET

     

       57
       57
       -
       Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG:  database system is ready to accept connections

     

       58
       58
       -
       Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG:  autovacuum launcher started

     

       59
       59
       -
       Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.

     

       60
       60
       -
       </screen>

     

       61
       61
       -
         Note that this shows the status of the unit (active and running), all the

     

       62
       62
       -
         processes belonging to the service, as well as the most recent log messages

     

       63
       63
       -
         from the service.

     

       64
       64
       -
        </para>

     

       65
       65
       -
        <para>

     

       66
       66
       -
         Units can be stopped, started or restarted:

     

       67
       67
       -
       <screen>

     

       68
       68
       -
       <prompt># </prompt>systemctl stop postgresql.service

     

       69
       69
       -
       <prompt># </prompt>systemctl start postgresql.service

     

       70
       70
       -
       <prompt># </prompt>systemctl restart postgresql.service

     

       71
       71
       -
       </screen>

     

       72
       72
       -
          These operations are synchronous: they wait until the service has finished

     

       73
       73
       -
          starting or stopping (or has failed). Starting a unit will cause the

     

       74
       74
       -
          dependencies of that unit to be started as well (if necessary).

     

       75
       75
       -
         </para>

     

       76
       76
       -
         <!-- TODO: document cgroups, draft:

     

       77
       77
       -
          each service and user session is a cgroup

     

       78
       78
       -
       

     

       79
       79
       -
          - cgroup resource management -->

     

       80
       80
       -
        </section>

     

       81
       81
       -
        <section xml:id="sect-nixos-systemd-nixos">

     

       82
       82
       -
         <title>systemd in NixOS</title>

     

       83
       83
       -
         <para>

     

       84
       84
       -
          Packages in Nixpkgs sometimes provide systemd units with them, usually in

     

       85
       85
       -
          e.g <literal>#pkg-out#/lib/systemd/</literal>. Putting such a package in

     

       86
       86
       -
          <literal>environment.systemPackages</literal> doesn't make the service

     

       87
       87
       -
          available to users or the system.

     

       88
       88
       -
         </para>

     

       89
       89
       -
         <para>

     

       90
       90
       -
          In order to enable a systemd <emphasis>system</emphasis> service with

     

       91
       91
       -
          provided upstream package, use (e.g):

     

       92
       92
       -
       <programlisting>

     

       93
       93
       -
       <xref linkend="opt-systemd.packages"/> = [ pkgs.packagekit ];

     

       94
       94
       -
       </programlisting>

     

       95
       95
       -
         </para>

     

       96
       96
       -
         <para>

     

       97
       97
       -
          Usually NixOS modules written by the community do the above, plus take care of

     

       98
       98
       -
          other details. If a module was written for a service you are interested in,

     

       99
       99
       -
          you'd probably need only to use

     

       100
       100
       -
          <literal>services.#name#.enable = true;</literal>. These services are defined

     

       101
       101
       -
          in Nixpkgs'

     

       102
       102
       -
          <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">

     

       103
       103
       -
          <literal>nixos/modules/</literal> directory </link>. In case the service is

     

       104
       104
       -
          simple enough, the above method should work, and start the service on boot.

     

       105
       105
       -
         </para>

     

       106
       106
       -
         <para>

     

       107
       107
       -
          <emphasis>User</emphasis> systemd services on the other hand, should be

     

       108
       108
       -
          treated differently. Given a package that has a systemd unit file at

     

       109
       109
       -
          <literal>#pkg-out#/lib/systemd/user/</literal>, using

     

       110
       110
       -
          <xref linkend="opt-systemd.packages"/> will make you able to start the service via

     

       111
       111
       -
          <literal>systemctl --user start</literal>, but it won't start automatically on login.

     

       112
       112
       -
          <!-- TODO: Document why systemd.packages doesn't work for user services or fix this.

     

       113
       113
       -
          https://github.com/NixOS/nixpkgs/blob/2cd6594a8710a801038af2b72348658f732ce84a/nixos/modules/system/boot/systemd-lib.nix#L177-L198

     

       114
       114
       -
       

     

       115
       115
       -
          This has been talked over at https://discourse.nixos.org/t/how-to-enable-upstream-systemd-user-services-declaratively/7649/5

     

       116
       116
       -
          -->

     

       117
       117
       -
          However, You can imperatively enable it by adding the package's attribute to

     

       118
       118
       -
          <link linkend="opt-environment.systemPackages">

     

       119
       119
       -
          <literal>systemd.packages</literal></link> and then do this (e.g):

     

       120
       120
       -
       <screen>

     

       121
       121
       -
       <prompt>$ </prompt>mkdir -p ~/.config/systemd/user/default.target.wants

     

       122
       122
       -
       <prompt>$ </prompt>ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/

     

       123
       123
       -
       <prompt>$ </prompt>systemctl --user daemon-reload

     

       124
       124
       -
       <prompt>$ </prompt>systemctl --user enable syncthing.service

     

       125
       125
       -
       </screen>

     

       126
       126
       -
          If you are interested in a timer file, use <literal>timers.target.wants</literal>

     

       127
       127
       -
          instead of <literal>default.target.wants</literal> in the 1st and 2nd command.

     

       128
       128
       -
         </para>

     

       129
       129
       -
         <para>

     

       130
       130
       -
          Using <literal>systemctl --user enable syncthing.service</literal> instead of

     

       131
       131
       -
          the above, will work, but it'll use the absolute path of

     

       132
       132
       -
          <literal>syncthing.service</literal> for the symlink, and this path is in

     

       133
       133
       -
          <literal>/nix/store/.../lib/systemd/user/</literal>. Hence

     

       134
       134
       -
          <link xlink:href="#sec-nix-gc">garbage collection</link> will remove that file

     

       135
       135
       -
          and you will wind up with a broken symlink in your systemd configuration, which

     

       136
       136
       -
          in turn will not make the service / timer start on login.

     

       137
       137
       -
         </para>

     

       138
       138
       -
        </section>

     

       139
       139
       -
       </chapter>

     

       140
       140
       -

+142

nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-systemctl">

     

       2
       2
       +
         <title>Service Management</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           In NixOS, all system services are started and monitored using the

     

       5
       5
       +
           systemd program. systemd is the <quote>init</quote> process of the

     

       6
       6
       +
           system (i.e. PID 1), the parent of all other processes. It manages a

     

       7
       7
       +
           set of so-called <quote>units</quote>, which can be things like

     

       8
       8
       +
           system services (programs), but also mount points, swap files,

     

       9
       9
       +
           devices, targets (groups of units) and more. Units can have complex

     

       10
       10
       +
           dependencies; for instance, one unit can require that another unit

     

       11
       11
       +
           must be successfully started before the first unit can be started.

     

       12
       12
       +
           When the system boots, it starts a unit named

     

       13
       13
       +
           <literal>default.target</literal>; the dependencies of this unit

     

       14
       14
       +
           cause all system services to be started, file systems to be mounted,

     

       15
       15
       +
           swap files to be activated, and so on.

     

       16
       16
       +
         </para>

     

       17
       17
       +
         <section xml:id="sect-nixos-systemd-general">

     

       18
       18
       +
           <title>Interacting with a running systemd</title>

     

       19
       19
       +
           <para>

     

       20
       20
       +
             The command <literal>systemctl</literal> is the main way to

     

       21
       21
       +
             interact with <literal>systemd</literal>. The following paragraphs

     

       22
       22
       +
             demonstrate ways to interact with any OS running systemd as init

     

       23
       23
       +
             system. NixOS is of no exception. The

     

       24
       24
       +
             <link linkend="sect-nixos-systemd-nixos">next section </link>

     

       25
       25
       +
             explains NixOS specific things worth knowing.

     

       26
       26
       +
           </para>

     

       27
       27
       +
           <para>

     

       28
       28
       +
             Without any arguments, <literal>systmctl</literal> the status of

     

       29
       29
       +
             active units:

     

       30
       30
       +
           </para>

     

       31
       31
       +
           <programlisting>

     

       32
       32
       +
       $ systemctl

     

       33
       33
       +
       -.mount          loaded active mounted   /

     

       34
       34
       +
       swapfile.swap    loaded active active    /swapfile

     

       35
       35
       +
       sshd.service     loaded active running   SSH Daemon

     

       36
       36
       +
       graphical.target loaded active active    Graphical Interface

     

       37
       37
       +
       ...

     

       38
       38
       +
       </programlisting>

     

       39
       39
       +
           <para>

     

       40
       40
       +
             You can ask for detailed status information about a unit, for

     

       41
       41
       +
             instance, the PostgreSQL database service:

     

       42
       42
       +
           </para>

     

       43
       43
       +
           <programlisting>

     

       44
       44
       +
       $ systemctl status postgresql.service

     

       45
       45
       +
       postgresql.service - PostgreSQL Server

     

       46
       46
       +
                 Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)

     

       47
       47
       +
                 Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago

     

       48
       48
       +
               Main PID: 2390 (postgres)

     

       49
       49
       +
                 CGroup: name=systemd:/system/postgresql.service

     

       50
       50
       +
                         ├─2390 postgres

     

       51
       51
       +
                         ├─2418 postgres: writer process

     

       52
       52
       +
                         ├─2419 postgres: wal writer process

     

       53
       53
       +
                         ├─2420 postgres: autovacuum launcher process

     

       54
       54
       +
                         ├─2421 postgres: stats collector process

     

       55
       55
       +
                         └─2498 postgres: zabbix zabbix [local] idle

     

       56
       56
       +
       

     

       57
       57
       +
       Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG:  database system was shut down at 2013-01-07 15:55:05 CET

     

       58
       58
       +
       Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG:  database system is ready to accept connections

     

       59
       59
       +
       Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG:  autovacuum launcher started

     

       60
       60
       +
       Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.

     

       61
       61
       +
       </programlisting>

     

       62
       62
       +
           <para>

     

       63
       63
       +
             Note that this shows the status of the unit (active and running),

     

       64
       64
       +
             all the processes belonging to the service, as well as the most

     

       65
       65
       +
             recent log messages from the service.

     

       66
       66
       +
           </para>

     

       67
       67
       +
           <para>

     

       68
       68
       +
             Units can be stopped, started or restarted:

     

       69
       69
       +
           </para>

     

       70
       70
       +
           <programlisting>

     

       71
       71
       +
       # systemctl stop postgresql.service

     

       72
       72
       +
       # systemctl start postgresql.service

     

       73
       73
       +
       # systemctl restart postgresql.service

     

       74
       74
       +
       </programlisting>

     

       75
       75
       +
           <para>

     

       76
       76
       +
             These operations are synchronous: they wait until the service has

     

       77
       77
       +
             finished starting or stopping (or has failed). Starting a unit

     

       78
       78
       +
             will cause the dependencies of that unit to be started as well (if

     

       79
       79
       +
             necessary).

     

       80
       80
       +
           </para>

     

       81
       81
       +
         </section>

     

       82
       82
       +
         <section xml:id="sect-nixos-systemd-nixos">

     

       83
       83
       +
           <title>systemd in NixOS</title>

     

       84
       84
       +
           <para>

     

       85
       85
       +
             Packages in Nixpkgs sometimes provide systemd units with them,

     

       86
       86
       +
             usually in e.g <literal>#pkg-out#/lib/systemd/</literal>. Putting

     

       87
       87
       +
             such a package in <literal>environment.systemPackages</literal>

     

       88
       88
       +
             doesn't make the service available to users or the system.

     

       89
       89
       +
           </para>

     

       90
       90
       +
           <para>

     

       91
       91
       +
             In order to enable a systemd <emphasis>system</emphasis> service

     

       92
       92
       +
             with provided upstream package, use (e.g):

     

       93
       93
       +
           </para>

     

       94
       94
       +
           <programlisting language="bash">

     

       95
       95
       +
       systemd.packages = [ pkgs.packagekit ];

     

       96
       96
       +
       </programlisting>

     

       97
       97
       +
           <para>

     

       98
       98
       +
             Usually NixOS modules written by the community do the above, plus

     

       99
       99
       +
             take care of other details. If a module was written for a service

     

       100
       100
       +
             you are interested in, you'd probably need only to use

     

       101
       101
       +
             <literal>services.#name#.enable = true;</literal>. These services

     

       102
       102
       +
             are defined in Nixpkgs'

     

       103
       103
       +
             <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">

     

       104
       104
       +
             <literal>nixos/modules/</literal> directory </link>. In case the

     

       105
       105
       +
             service is simple enough, the above method should work, and start

     

       106
       106
       +
             the service on boot.

     

       107
       107
       +
           </para>

     

       108
       108
       +
           <para>

     

       109
       109
       +
             <emphasis>User</emphasis> systemd services on the other hand,

     

       110
       110
       +
             should be treated differently. Given a package that has a systemd

     

       111
       111
       +
             unit file at <literal>#pkg-out#/lib/systemd/user/</literal>, using

     

       112
       112
       +
             <xref linkend="opt-systemd.packages" /> will make you able to

     

       113
       113
       +
             start the service via <literal>systemctl --user start</literal>,

     

       114
       114
       +
             but it won't start automatically on login. However, You can

     

       115
       115
       +
             imperatively enable it by adding the package's attribute to

     

       116
       116
       +
             <link linkend="opt-environment.systemPackages">

     

       117
       117
       +
             <literal>systemd.packages</literal></link> and then do this (e.g):

     

       118
       118
       +
           </para>

     

       119
       119
       +
           <programlisting>

     

       120
       120
       +
       $ mkdir -p ~/.config/systemd/user/default.target.wants

     

       121
       121
       +
       $ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/

     

       122
       122
       +
       $ systemctl --user daemon-reload

     

       123
       123
       +
       $ systemctl --user enable syncthing.service

     

       124
       124
       +
       </programlisting>

     

       125
       125
       +
           <para>

     

       126
       126
       +
             If you are interested in a timer file, use

     

       127
       127
       +
             <literal>timers.target.wants</literal> instead of

     

       128
       128
       +
             <literal>default.target.wants</literal> in the 1st and 2nd

     

       129
       129
       +
             command.

     

       130
       130
       +
           </para>

     

       131
       131
       +
           <para>

     

       132
       132
       +
             Using <literal>systemctl --user enable syncthing.service</literal>

     

       133
       133
       +
             instead of the above, will work, but it'll use the absolute path

     

       134
       134
       +
             of <literal>syncthing.service</literal> for the symlink, and this

     

       135
       135
       +
             path is in <literal>/nix/store/.../lib/systemd/user/</literal>.

     

       136
       136
       +
             Hence <link linkend="sec-nix-gc">garbage collection</link> will

     

       137
       137
       +
             remove that file and you will wind up with a broken symlink in

     

       138
       138
       +
             your systemd configuration, which in turn will not make the

     

       139
       139
       +
             service / timer start on login.

     

       140
       140
       +
           </para>

     

       141
       141
       +
         </section>

     

       142
       142
       +
       </chapter>