commit b0ccd6dd16909c8639c2d9bee7dd2a2a0ac74c30 · pyrox.dev/nixpkgs

+26 -6

nixos/doc/manual/administration/boot-problems.xml

···

       6
       6
        
        <title>Boot Problems</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         If NixOS fails to boot, there are a number of kernel command line parameters that may help you to identify or fix the issue. You can add these parameters in the GRUB boot menu by pressing “e” to modify the selected boot entry and editing the line starting with <literal>linux</literal>. The following are some useful kernel command line parameters that are recognised by the NixOS boot scripts or by systemd:

     

       9
       9
       +
         If NixOS fails to boot, there are a number of kernel command line parameters

     

       10
       10
       +
         that may help you to identify or fix the issue. You can add these parameters

     

       11
       11
       +
         in the GRUB boot menu by pressing “e” to modify the selected boot entry

     

       12
       12
       +
         and editing the line starting with <literal>linux</literal>. The following

     

       13
       13
       +
         are some useful kernel command line parameters that are recognised by the

     

       14
       14
       +
         NixOS boot scripts or by systemd:

     

       10
       15
        
         <variablelist>

     

       11
       16
        
          <varlistentry>

     

       12
       17
        
           <term>

     
···

       14
       19
        
           </term>

     

       15
       20
        
           <listitem>

     

       16
       21
        
            <para>

     

       17
       17
       -
             Start a root shell if something goes wrong in stage 1 of the boot process (the initial ramdisk). This is disabled by default because there is no authentication for the root shell.

     

       22
       22
       +
             Start a root shell if something goes wrong in stage 1 of the boot process

     

       23
       23
       +
             (the initial ramdisk). This is disabled by default because there is no

     

       24
       24
       +
             authentication for the root shell.

     

       18
       25
        
            </para>

     

       19
       26
        
           </listitem>

     

       20
       27
        
          </varlistentry>

     
···

       24
       31
        
           </term>

     

       25
       32
        
           <listitem>

     

       26
       33
        
            <para>

     

       27
       27
       -
             Start an interactive shell in stage 1 before anything useful has been done. That is, no modules have been loaded and no file systems have been mounted, except for <filename>/proc</filename> and <filename>/sys</filename>.

     

       34
       34
       +
             Start an interactive shell in stage 1 before anything useful has been

     

       35
       35
       +
             done. That is, no modules have been loaded and no file systems have been

     

       36
       36
       +
             mounted, except for <filename>/proc</filename> and

     

       37
       37
       +
             <filename>/sys</filename>.

     

       28
       38
        
            </para>

     

       29
       39
        
           </listitem>

     

       30
       40
        
          </varlistentry>

     
···

       44
       54
        
           </term>

     

       45
       55
        
           <listitem>

     

       46
       56
        
            <para>

     

       47
       47
       -
             Boot into rescue mode (a.k.a. single user mode). This will cause systemd to start nothing but the unit <literal>rescue.target</literal>, which runs <command>sulogin</command> to prompt for the root password and start a root login shell. Exiting the shell causes the system to continue with the normal boot process.

     

       57
       57
       +
             Boot into rescue mode (a.k.a. single user mode). This will cause systemd

     

       58
       58
       +
             to start nothing but the unit <literal>rescue.target</literal>, which

     

       59
       59
       +
             runs <command>sulogin</command> to prompt for the root password and start

     

       60
       60
       +
             a root login shell. Exiting the shell causes the system to continue with

     

       61
       61
       +
             the normal boot process.

     

       48
       62
        
            </para>

     

       49
       63
        
           </listitem>

     

       50
       64
        
          </varlistentry>

     
···

       54
       68
        
           </term>

     

       55
       69
        
           <listitem>

     

       56
       70
        
            <para>

     

       57
       57
       -
             Make systemd very verbose and send log messages to the console instead of the journal.

     

       71
       71
       +
             Make systemd very verbose and send log messages to the console instead of

     

       72
       72
       +
             the journal.

     

       58
       73
        
            </para>

     

       59
       74
        
           </listitem>

     

       60
       75
        
          </varlistentry>

     
···

       65
       80
        
        </para>

     

       66
       81
        
       

     

       67
       82
        
        <para>

     

       68
       68
       -
         If no login prompts or X11 login screens appear (e.g. due to hanging dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start rescue mode (described above). (Also note that since most units have a 90-second timeout before systemd gives up on them, the <command>agetty</command> login prompts should appear eventually unless something is very wrong.)

     

       83
       83
       +
         If no login prompts or X11 login screens appear (e.g. due to hanging

     

       84
       84
       +
         dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start

     

       85
       85
       +
         rescue mode (described above). (Also note that since most units have a

     

       86
       86
       +
         90-second timeout before systemd gives up on them, the

     

       87
       87
       +
         <command>agetty</command> login prompts should appear eventually unless

     

       88
       88
       +
         something is very wrong.)

     

       69
       89
        
        </para>

     

       70
       90
        
       </section>

+24 -8

nixos/doc/manual/administration/cleaning-store.xml

···

       5
       5
        
               xml:id="sec-nix-gc">

     

       6
       6
        
        <title>Cleaning the Nix Store</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         Nix has a purely functional model, meaning that packages are never upgraded in place. Instead new versions of packages end up in a different location in the Nix store (<filename>/nix/store</filename>). You should periodically run Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced packages. This is easy:

     

       8
       8
       +
         Nix has a purely functional model, meaning that packages are never upgraded

     

       9
       9
       +
         in place. Instead new versions of packages end up in a different location in

     

       10
       10
       +
         the Nix store (<filename>/nix/store</filename>). You should periodically run

     

       11
       11
       +
         Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced

     

       12
       12
       +
         packages. This is easy:

     

       9
       13
        
       <screen>

     

       10
       14
        
       <prompt>$ </prompt>nix-collect-garbage

     

       11
       15
        
       </screen>

     

       12
       12
       -
         Alternatively, you can use a systemd unit that does the same in the background:

     

       16
       16
       +
         Alternatively, you can use a systemd unit that does the same in the

     

       17
       17
       +
         background:

     

       13
       18
        
       <screen>

     

       14
       19
        
       <prompt># </prompt>systemctl start nix-gc.service

     

       15
       20
        
       </screen>

     

       16
       16
       -
         You can tell NixOS in <filename>configuration.nix</filename> to run this unit automatically at certain points in time, for instance, every night at 03:15:

     

       21
       21
       +
         You can tell NixOS in <filename>configuration.nix</filename> to run this unit

     

       22
       22
       +
         automatically at certain points in time, for instance, every night at 03:15:

     

       17
       23
        
       <programlisting>

     

       18
       24
        
       <xref linkend="opt-nix.gc.automatic"/> = true;

     

       19
       25
        
       <xref linkend="opt-nix.gc.dates"/> = "03:15";

     

       20
       26
        
       </programlisting>

     

       21
       27
        
        </para>

     

       22
       28
        
        <para>

     

       23
       23
       -
         The commands above do not remove garbage collector roots, such as old system configurations. Thus they do not remove the ability to roll back to previous configurations. The following command deletes old roots, removing the ability to roll back to them:

     

       29
       29
       +
         The commands above do not remove garbage collector roots, such as old system

     

       30
       30
       +
         configurations. Thus they do not remove the ability to roll back to previous

     

       31
       31
       +
         configurations. The following command deletes old roots, removing the ability

     

       32
       32
       +
         to roll back to them:

     

       24
       33
        
       <screen>

     

       25
       34
        
       <prompt>$ </prompt>nix-collect-garbage -d

     

       26
       35
        
       </screen>

     
···

       28
       37
        
       <screen>

     

       29
       38
        
       <prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old

     

       30
       39
        
       </screen>

     

       31
       31
       -
         Note that NixOS system configurations are stored in the profile <filename>/nix/var/nix/profiles/system</filename>.

     

       40
       40
       +
         Note that NixOS system configurations are stored in the profile

     

       41
       41
       +
         <filename>/nix/var/nix/profiles/system</filename>.

     

       32
       42
        
        </para>

     

       33
       43
        
        <para>

     

       34
       34
       -
         Another way to reclaim disk space (often as much as 40% of the size of the Nix store) is to run Nix’s store optimiser, which seeks out identical files in the store and replaces them with hard links to a single copy.

     

       44
       44
       +
         Another way to reclaim disk space (often as much as 40% of the size of the

     

       45
       45
       +
         Nix store) is to run Nix’s store optimiser, which seeks out identical files

     

       46
       46
       +
         in the store and replaces them with hard links to a single copy.

     

       35
       47
        
       <screen>

     

       36
       48
        
       <prompt>$ </prompt>nix-store --optimise

     

       37
       49
        
       </screen>

     

       38
       38
       -
         Since this command needs to read the entire Nix store, it can take quite a while to finish.

     

       50
       50
       +
         Since this command needs to read the entire Nix store, it can take quite a

     

       51
       51
       +
         while to finish.

     

       39
       52
        
        </para>

     

       40
       53
        
        <section xml:id="sect-nixos-gc-boot-entries">

     

       41
       54
        
         <title>NixOS Boot Entries</title>

     

       42
       55
        
       

     

       43
       56
        
         <para>

     

       44
       44
       -
          If your <filename>/boot</filename> partition runs out of space, after clearing old profiles you must rebuild your system with <literal>nixos-rebuild</literal> to update the <filename>/boot</filename> partition and clear space.

     

       57
       57
       +
          If your <filename>/boot</filename> partition runs out of space, after

     

       58
       58
       +
          clearing old profiles you must rebuild your system with

     

       59
       59
       +
          <literal>nixos-rebuild</literal> to update the <filename>/boot</filename>

     

       60
       60
       +
          partition and clear space.

     

       45
       61
        
         </para>

     

       46
       62
        
        </section>

     

       47
       63
        
       </chapter>

+21 -5

nixos/doc/manual/administration/container-networking.xml

···

       6
       6
        
        <title>Container Networking</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         When you create a container using <literal>nixos-container create</literal>, it gets it own private IPv4 address in the range <literal>10.233.0.0/16</literal>. You can get the container’s IPv4 address as follows:

     

       9
       9
       +
         When you create a container using <literal>nixos-container create</literal>,

     

       10
       10
       +
         it gets it own private IPv4 address in the range

     

       11
       11
       +
         <literal>10.233.0.0/16</literal>. You can get the container’s IPv4 address

     

       12
       12
       +
         as follows:

     

       10
       13
        
       <screen>

     

       11
       14
        
       <prompt># </prompt>nixos-container show-ip foo

     

       12
       15
        
       10.233.4.2

     
···

       17
       20
        
        </para>

     

       18
       21
        
       

     

       19
       22
        
        <para>

     

       20
       20
       -
         Networking is implemented using a pair of virtual Ethernet devices. The network interface in the container is called <literal>eth0</literal>, while the matching interface in the host is called <literal>ve-<replaceable>container-name</replaceable></literal> (e.g., <literal>ve-foo</literal>). The container has its own network namespace and the <literal>CAP_NET_ADMIN</literal> capability, so it can perform arbitrary network configuration such as setting up firewall rules, without affecting or having access to the host’s network.

     

       23
       23
       +
         Networking is implemented using a pair of virtual Ethernet devices. The

     

       24
       24
       +
         network interface in the container is called <literal>eth0</literal>, while

     

       25
       25
       +
         the matching interface in the host is called

     

       26
       26
       +
         <literal>ve-<replaceable>container-name</replaceable></literal> (e.g.,

     

       27
       27
       +
         <literal>ve-foo</literal>). The container has its own network namespace and

     

       28
       28
       +
         the <literal>CAP_NET_ADMIN</literal> capability, so it can perform arbitrary

     

       29
       29
       +
         network configuration such as setting up firewall rules, without affecting or

     

       30
       30
       +
         having access to the host’s network.

     

       21
       31
        
        </para>

     

       22
       32
        
       

     

       23
       33
        
        <para>

     

       24
       24
       -
         By default, containers cannot talk to the outside network. If you want that, you should set up Network Address Translation (NAT) rules on the host to rewrite container traffic to use your external IP address. This can be accomplished using the following configuration on the host:

     

       34
       34
       +
         By default, containers cannot talk to the outside network. If you want that,

     

       35
       35
       +
         you should set up Network Address Translation (NAT) rules on the host to

     

       36
       36
       +
         rewrite container traffic to use your external IP address. This can be

     

       37
       37
       +
         accomplished using the following configuration on the host:

     

       25
       38
        
       <programlisting>

     

       26
       39
        
       <xref linkend="opt-networking.nat.enable"/> = true;

     

       27
       40
        
       <xref linkend="opt-networking.nat.internalInterfaces"/> = ["ve-+"];

     

       28
       41
        
       <xref linkend="opt-networking.nat.externalInterface"/> = "eth0";

     

       29
       42
        
       </programlisting>

     

       30
       30
       -
         where <literal>eth0</literal> should be replaced with the desired external interface. Note that <literal>ve-+</literal> is a wildcard that matches all container interfaces.

     

       43
       43
       +
         where <literal>eth0</literal> should be replaced with the desired external

     

       44
       44
       +
         interface. Note that <literal>ve-+</literal> is a wildcard that matches all

     

       45
       45
       +
         container interfaces.

     

       31
       46
        
        </para>

     

       32
       47
        
       

     

       33
       48
        
        <para>

     

       34
       34
       -
         If you are using Network Manager, you need to explicitly prevent it from managing container interfaces:

     

       49
       49
       +
         If you are using Network Manager, you need to explicitly prevent it from

     

       50
       50
       +
         managing container interfaces:

     

       35
       51
        
       <programlisting>

     

       36
       52
        
       networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];

     

       37
       53
        
       </programlisting>

+16 -3

nixos/doc/manual/administration/containers.xml

···

       5
       5
        
               xml:id="ch-containers">

     

       6
       6
        
        <title>Container Management</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         NixOS allows you to easily run other NixOS instances as <emphasis>containers</emphasis>. Containers are a light-weight approach to virtualisation that runs software in the container at the same speed as in the host system. NixOS containers share the Nix store of the host, making container creation very efficient.

     

       8
       8
       +
         NixOS allows you to easily run other NixOS instances as

     

       9
       9
       +
         <emphasis>containers</emphasis>. Containers are a light-weight approach to

     

       10
       10
       +
         virtualisation that runs software in the container at the same speed as in

     

       11
       11
       +
         the host system. NixOS containers share the Nix store of the host, making

     

       12
       12
       +
         container creation very efficient.

     

       9
       13
        
        </para>

     

       10
       14
        
        <warning>

     

       11
       15
        
         <para>

     

       12
       12
       -
          Currently, NixOS containers are not perfectly isolated from the host system. This means that a user with root access to the container can do things that affect the host. So you should not give container root access to untrusted users.

     

       16
       16
       +
          Currently, NixOS containers are not perfectly isolated from the host system.

     

       17
       17
       +
          This means that a user with root access to the container can do things that

     

       18
       18
       +
          affect the host. So you should not give container root access to untrusted

     

       19
       19
       +
          users.

     

       13
       20
        
         </para>

     

       14
       21
        
        </warning>

     

       15
       22
        
        <para>

     

       16
       16
       -
         NixOS containers can be created in two ways: imperatively, using the command <command>nixos-container</command>, and declaratively, by specifying them in your <filename>configuration.nix</filename>. The declarative approach implies that containers get upgraded along with your host system when you run <command>nixos-rebuild</command>, which is often not what you want. By contrast, in the imperative approach, containers are configured and updated independently from the host system.

     

       23
       23
       +
         NixOS containers can be created in two ways: imperatively, using the command

     

       24
       24
       +
         <command>nixos-container</command>, and declaratively, by specifying them in

     

       25
       25
       +
         your <filename>configuration.nix</filename>. The declarative approach implies

     

       26
       26
       +
         that containers get upgraded along with your host system when you run

     

       27
       27
       +
         <command>nixos-rebuild</command>, which is often not what you want. By

     

       28
       28
       +
         contrast, in the imperative approach, containers are configured and updated

     

       29
       29
       +
         independently from the host system.

     

       17
       30
        
        </para>

     

       18
       31
        
        <xi:include href="imperative-containers.xml" />

     

       19
       32
        
        <xi:include href="declarative-containers.xml" />

+27 -6

nixos/doc/manual/administration/control-groups.xml

···

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

     

       6
       6
        
        <title>Control Groups</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         To keep track of the processes in a running system, systemd uses <emphasis>control groups</emphasis> (cgroups). A control group is a set of processes used to allocate resources such as CPU, memory or I/O bandwidth. There can be multiple control group hierarchies, allowing each kind of resource to be managed independently.

     

       8
       8
       +
         To keep track of the processes in a running system, systemd uses

     

       9
       9
       +
         <emphasis>control groups</emphasis> (cgroups). A control group is a set of

     

       10
       10
       +
         processes used to allocate resources such as CPU, memory or I/O bandwidth.

     

       11
       11
       +
         There can be multiple control group hierarchies, allowing each kind of

     

       12
       12
       +
         resource to be managed independently.

     

       9
       13
        
        </para>

     

       10
       14
        
        <para>

     

       11
       11
       -
         The command <command>systemd-cgls</command> lists all control groups in the <literal>systemd</literal> hierarchy, which is what systemd uses to keep track of the processes belonging to each service or user session:

     

       15
       15
       +
         The command <command>systemd-cgls</command> lists all control groups in the

     

       16
       16
       +
         <literal>systemd</literal> hierarchy, which is what systemd uses to keep

     

       17
       17
       +
         track of the processes belonging to each service or user session:

     

       12
       18
        
       <screen>

     

       13
       19
        
       <prompt>$ </prompt>systemd-cgls

     

       14
       20
        
       ├─user

     
···

       26
       32
        
         │ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf

     

       27
       33
        
         └─ <replaceable>...</replaceable>

     

       28
       34
        
       </screen>

     

       29
       29
       -
         Similarly, <command>systemd-cgls cpu</command> shows the cgroups in the CPU hierarchy, which allows per-cgroup CPU scheduling priorities. By default, every systemd service gets its own CPU cgroup, while all user sessions are in the top-level CPU cgroup. This ensures, for instance, that a thousand run-away processes in the <literal>httpd.service</literal> cgroup cannot starve the CPU for one process in the <literal>postgresql.service</literal> cgroup. (By contrast, it they were in the same cgroup, then the PostgreSQL process would get 1/1001 of the cgroup’s CPU time.) You can limit a service’s CPU share in <filename>configuration.nix</filename>:

     

       35
       35
       +
         Similarly, <command>systemd-cgls cpu</command> shows the cgroups in the CPU

     

       36
       36
       +
         hierarchy, which allows per-cgroup CPU scheduling priorities. By default,

     

       37
       37
       +
         every systemd service gets its own CPU cgroup, while all user sessions are in

     

       38
       38
       +
         the top-level CPU cgroup. This ensures, for instance, that a thousand

     

       39
       39
       +
         run-away processes in the <literal>httpd.service</literal> cgroup cannot

     

       40
       40
       +
         starve the CPU for one process in the <literal>postgresql.service</literal>

     

       41
       41
       +
         cgroup. (By contrast, it they were in the same cgroup, then the PostgreSQL

     

       42
       42
       +
         process would get 1/1001 of the cgroup’s CPU time.) You can limit a

     

       43
       43
       +
         service’s CPU share in <filename>configuration.nix</filename>:

     

       30
       44
        
       <programlisting>

     

       31
       45
        
       <link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.CPUShares = 512;

     

       32
       46
        
       </programlisting>

     

       33
       33
       -
         By default, every cgroup has 1024 CPU shares, so this will halve the CPU allocation of the <literal>httpd.service</literal> cgroup.

     

       47
       47
       +
         By default, every cgroup has 1024 CPU shares, so this will halve the CPU

     

       48
       48
       +
         allocation of the <literal>httpd.service</literal> cgroup.

     

       34
       49
        
        </para>

     

       35
       50
        
        <para>

     

       36
       36
       -
         There also is a <literal>memory</literal> hierarchy that controls memory allocation limits; by default, all processes are in the top-level cgroup, so any service or session can exhaust all available memory. Per-cgroup memory limits can be specified in <filename>configuration.nix</filename>; for instance, to limit <literal>httpd.service</literal> to 512 MiB of RAM (excluding swap):

     

       51
       51
       +
         There also is a <literal>memory</literal> hierarchy that controls memory

     

       52
       52
       +
         allocation limits; by default, all processes are in the top-level cgroup, so

     

       53
       53
       +
         any service or session can exhaust all available memory. Per-cgroup memory

     

       54
       54
       +
         limits can be specified in <filename>configuration.nix</filename>; for

     

       55
       55
       +
         instance, to limit <literal>httpd.service</literal> to 512 MiB of RAM

     

       56
       56
       +
         (excluding swap):

     

       37
       57
        
       <programlisting>

     

       38
       58
        
       <link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.MemoryLimit = "512M";

     

       39
       59
        
       </programlisting>

     

       40
       60
        
        </para>

     

       41
       61
        
        <para>

     

       42
       42
       -
         The command <command>systemd-cgtop</command> shows a continuously updated list of all cgroups with their CPU and memory usage.

     

       62
       62
       +
         The command <command>systemd-cgtop</command> shows a continuously updated

     

       63
       63
       +
         list of all cgroups with their CPU and memory usage.

     

       43
       64
        
        </para>

     

       44
       65
        
       </chapter>

+25 -6

nixos/doc/manual/administration/declarative-containers.xml

···

       6
       6
        
        <title>Declarative Container Specification</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         You can also specify containers and their configuration in the host’s <filename>configuration.nix</filename>. For example, the following specifies that there shall be a container named <literal>database</literal> running PostgreSQL:

     

       9
       9
       +
         You can also specify containers and their configuration in the host’s

     

       10
       10
       +
         <filename>configuration.nix</filename>. For example, the following specifies

     

       11
       11
       +
         that there shall be a container named <literal>database</literal> running

     

       12
       12
       +
         PostgreSQL:

     

       10
       13
        
       <programlisting>

     

       11
       14
        
       containers.database =

     

       12
       15
        
         { config =

     
···

       16
       19
        
             };

     

       17
       20
        
         };

     

       18
       21
        
       </programlisting>

     

       19
       19
       -
         If you run <literal>nixos-rebuild switch</literal>, the container will be built. If the container was already running, it will be updated in place, without rebooting. The container can be configured to start automatically by setting <literal>containers.database.autoStart = true</literal> in its configuration.

     

       22
       22
       +
         If you run <literal>nixos-rebuild switch</literal>, the container will be

     

       23
       23
       +
         built. If the container was already running, it will be updated in place,

     

       24
       24
       +
         without rebooting. The container can be configured to start automatically by

     

       25
       25
       +
         setting <literal>containers.database.autoStart = true</literal> in its

     

       26
       26
       +
         configuration.

     

       20
       27
        
        </para>

     

       21
       28
        
       

     

       22
       29
        
        <para>

     

       23
       23
       -
         By default, declarative containers share the network namespace of the host, meaning that they can listen on (privileged) ports. However, they cannot change the network configuration. You can give a container its own network as follows:

     

       30
       30
       +
         By default, declarative containers share the network namespace of the host,

     

       31
       31
       +
         meaning that they can listen on (privileged) ports. However, they cannot

     

       32
       32
       +
         change the network configuration. You can give a container its own network as

     

       33
       33
       +
         follows:

     

       24
       34
        
       <programlisting>

     

       25
       35
        
       containers.database = {

     

       26
       36
        
         <link linkend="opt-containers._name_.privateNetwork">privateNetwork</link> = true;

     
···

       28
       38
        
         <link linkend="opt-containers._name_.localAddress">localAddress</link> = "192.168.100.11";

     

       29
       39
        
       };

     

       30
       40
        
       </programlisting>

     

       31
       31
       -
         This gives the container a private virtual Ethernet interface with IP address <literal>192.168.100.11</literal>, which is hooked up to a virtual Ethernet interface on the host with IP address <literal>192.168.100.10</literal>. (See the next section for details on container networking.)

     

       41
       41
       +
         This gives the container a private virtual Ethernet interface with IP address

     

       42
       42
       +
         <literal>192.168.100.11</literal>, which is hooked up to a virtual Ethernet

     

       43
       43
       +
         interface on the host with IP address <literal>192.168.100.10</literal>. (See

     

       44
       44
       +
         the next section for details on container networking.)

     

       32
       45
        
        </para>

     

       33
       46
        
       

     

       34
       47
        
        <para>

     

       35
       35
       -
         To disable the container, just remove it from <filename>configuration.nix</filename> and run <literal>nixos-rebuild switch</literal>. Note that this will not delete the root directory of the container in <literal>/var/lib/containers</literal>. Containers can be destroyed using the imperative method: <literal>nixos-container destroy foo</literal>.

     

       48
       48
       +
         To disable the container, just remove it from

     

       49
       49
       +
         <filename>configuration.nix</filename> and run <literal>nixos-rebuild

     

       50
       50
       +
         switch</literal>. Note that this will not delete the root directory of the

     

       51
       51
       +
         container in <literal>/var/lib/containers</literal>. Containers can be

     

       52
       52
       +
         destroyed using the imperative method: <literal>nixos-container destroy

     

       53
       53
       +
         foo</literal>.

     

       36
       54
        
        </para>

     

       37
       55
        
       

     

       38
       56
        
        <para>

     

       39
       39
       -
         Declarative containers can be started and stopped using the corresponding systemd service, e.g. <literal>systemctl start container@database</literal>.

     

       57
       57
       +
         Declarative containers can be started and stopped using the corresponding

     

       58
       58
       +
         systemd service, e.g. <literal>systemctl start container@database</literal>.

     

       40
       59
        
        </para>

     

       41
       60
        
       </section>

+45 -12

nixos/doc/manual/administration/imperative-containers.xml

···

       6
       6
        
        <title>Imperative Container Management</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         We’ll cover imperative container management using <command>nixos-container</command> first. Be aware that container management is currently only possible as <literal>root</literal>.

     

       9
       9
       +
         We’ll cover imperative container management using

     

       10
       10
       +
         <command>nixos-container</command> first. Be aware that container management

     

       11
       11
       +
         is currently only possible as <literal>root</literal>.

     

       10
       12
        
        </para>

     

       11
       13
        
       

     

       12
       14
        
        <para>

     
···

       14
       16
        
       <screen>

     

       15
       17
        
       # nixos-container create foo

     

       16
       18
        
       </screen>

     

       17
       17
       -
         This creates the container’s root directory in <filename>/var/lib/containers/foo</filename> and a small configuration file in <filename>/etc/containers/foo.conf</filename>. It also builds the container’s initial system configuration and stores it in <filename>/nix/var/nix/profiles/per-container/foo/system</filename>. You can modify the initial configuration of the container on the command line. For instance, to create a container that has <command>sshd</command> running, with the given public key for <literal>root</literal>:

     

       19
       19
       +
         This creates the container’s root directory in

     

       20
       20
       +
         <filename>/var/lib/containers/foo</filename> and a small configuration file

     

       21
       21
       +
         in <filename>/etc/containers/foo.conf</filename>. It also builds the

     

       22
       22
       +
         container’s initial system configuration and stores it in

     

       23
       23
       +
         <filename>/nix/var/nix/profiles/per-container/foo/system</filename>. You can

     

       24
       24
       +
         modify the initial configuration of the container on the command line. For

     

       25
       25
       +
         instance, to create a container that has <command>sshd</command> running,

     

       26
       26
       +
         with the given public key for <literal>root</literal>:

     

       18
       27
        
       <screen>

     

       19
       28
        
       # nixos-container create foo --config '

     

       20
       29
        
         <xref linkend="opt-services.openssh.enable"/> = true;

     

       21
       30
        
         <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"];

     

       22
       31
        
       '

     

       23
       32
        
       </screen>

     

       24
       24
       -
         By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen as container IP. This behavior can be altered by setting <literal>--host-address</literal> and <literal>--local-address</literal>:

     

       33
       33
       +
         By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen

     

       34
       34
       +
         as container IP. This behavior can be altered by setting <literal>--host-address</literal> and

     

       35
       35
       +
         <literal>--local-address</literal>:

     

       25
       36
        
       <screen>

     

       26
       37
        
       # nixos-container create test --config-file test-container.nix \

     

       27
       38
        
           --local-address 10.235.1.2 --host-address 10.235.1.1

     
···

       33
       44
        
       <screen>

     

       34
       45
        
       # nixos-container start foo

     

       35
       46
        
       </screen>

     

       36
       36
       -
         This command will return as soon as the container has booted and has reached <literal>multi-user.target</literal>. On the host, the container runs within a systemd unit called <literal>container@<replaceable>container-name</replaceable>.service</literal>. Thus, if something went wrong, you can get status info using <command>systemctl</command>:

     

       47
       47
       +
         This command will return as soon as the container has booted and has reached

     

       48
       48
       +
         <literal>multi-user.target</literal>. On the host, the container runs within

     

       49
       49
       +
         a systemd unit called

     

       50
       50
       +
         <literal>container@<replaceable>container-name</replaceable>.service</literal>.

     

       51
       51
       +
         Thus, if something went wrong, you can get status info using

     

       52
       52
       +
         <command>systemctl</command>:

     

       37
       53
        
       <screen>

     

       38
       54
        
       # systemctl status container@foo

     

       39
       55
        
       </screen>

     

       40
       56
        
        </para>

     

       41
       57
        
       

     

       42
       58
        
        <para>

     

       43
       43
       -
         If the container has started successfully, you can log in as root using the <command>root-login</command> operation:

     

       59
       59
       +
         If the container has started successfully, you can log in as root using the

     

       60
       60
       +
         <command>root-login</command> operation:

     

       44
       61
        
       <screen>

     

       45
       62
        
       # nixos-container root-login foo

     

       46
       63
        
       [root@foo:~]#

     

       47
       64
        
       </screen>

     

       48
       48
       -
         Note that only root on the host can do this (since there is no authentication). You can also get a regular login prompt using the <command>login</command> operation, which is available to all users on the host:

     

       65
       65
       +
         Note that only root on the host can do this (since there is no

     

       66
       66
       +
         authentication). You can also get a regular login prompt using the

     

       67
       67
       +
         <command>login</command> operation, which is available to all users on the

     

       68
       68
       +
         host:

     

       49
       69
        
       <screen>

     

       50
       70
        
       # nixos-container login foo

     

       51
       71
        
       foo login: alice

     

       52
       72
        
       Password: ***

     

       53
       73
        
       </screen>

     

       54
       54
       -
         With <command>nixos-container run</command>, you can execute arbitrary commands in the container:

     

       74
       74
       +
         With <command>nixos-container run</command>, you can execute arbitrary

     

       75
       75
       +
         commands in the container:

     

       55
       76
        
       <screen>

     

       56
       77
        
       # nixos-container run foo -- uname -a

     

       57
       78
        
       Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux

     
···

       59
       80
        
        </para>

     

       60
       81
        
       

     

       61
       82
        
        <para>

     

       62
       62
       -
         There are several ways to change the configuration of the container. First, on the host, you can edit <literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>, and run

     

       83
       83
       +
         There are several ways to change the configuration of the container. First,

     

       84
       84
       +
         on the host, you can edit

     

       85
       85
       +
         <literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>,

     

       86
       86
       +
         and run

     

       63
       87
        
       <screen>

     

       64
       88
        
       # nixos-container update foo

     

       65
       89
        
       </screen>

     

       66
       66
       -
         This will build and activate the new configuration. You can also specify a new configuration on the command line:

     

       90
       90
       +
         This will build and activate the new configuration. You can also specify a

     

       91
       91
       +
         new configuration on the command line:

     

       67
       92
        
       <screen>

     

       68
       93
        
       # nixos-container update foo --config '

     

       69
       94
        
         <xref linkend="opt-services.httpd.enable"/> = true;

     
···

       74
       99
        
       # curl http://$(nixos-container show-ip foo)/

     

       75
       100
        
       &lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…

     

       76
       101
        
       </screen>

     

       77
       77
       -
         However, note that this will overwrite the container’s <filename>/etc/nixos/configuration.nix</filename>.

     

       102
       102
       +
         However, note that this will overwrite the container’s

     

       103
       103
       +
         <filename>/etc/nixos/configuration.nix</filename>.

     

       78
       104
        
        </para>

     

       79
       105
        
       

     

       80
       106
        
        <para>

     

       81
       81
       -
         Alternatively, you can change the configuration from within the container itself by running <command>nixos-rebuild switch</command> inside the container. Note that the container by default does not have a copy of the NixOS channel, so you should run <command>nix-channel --update</command> first.

     

       107
       107
       +
         Alternatively, you can change the configuration from within the container

     

       108
       108
       +
         itself by running <command>nixos-rebuild switch</command> inside the

     

       109
       109
       +
         container. Note that the container by default does not have a copy of the

     

       110
       110
       +
         NixOS channel, so you should run <command>nix-channel --update</command>

     

       111
       111
       +
         first.

     

       82
       112
        
        </para>

     

       83
       113
        
       

     

       84
       114
        
        <para>

     

       85
       85
       -
         Containers can be stopped and started using <literal>nixos-container stop</literal> and <literal>nixos-container start</literal>, respectively, or by using <command>systemctl</command> on the container’s service unit. To destroy a container, including its file system, do

     

       115
       115
       +
         Containers can be stopped and started using <literal>nixos-container

     

       116
       116
       +
         stop</literal> and <literal>nixos-container start</literal>, respectively, or

     

       117
       117
       +
         by using <command>systemctl</command> on the container’s service unit. To

     

       118
       118
       +
         destroy a container, including its file system, do

     

       86
       119
        
       <screen>

     

       87
       120
        
       # nixos-container destroy foo

     

       88
       121
        
       </screen>

+15 -4

nixos/doc/manual/administration/logging.xml

···

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

     

       6
       6
        
        <title>Logging</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         System-wide logging is provided by systemd’s <emphasis>journal</emphasis>, which subsumes traditional logging daemons such as syslogd and klogd. Log entries are kept in binary files in <filename>/var/log/journal/</filename>. The command <literal>journalctl</literal> allows you to see the contents of the journal. For example,

     

       8
       8
       +
         System-wide logging is provided by systemd’s <emphasis>journal</emphasis>,

     

       9
       9
       +
         which subsumes traditional logging daemons such as syslogd and klogd. Log

     

       10
       10
       +
         entries are kept in binary files in <filename>/var/log/journal/</filename>.

     

       11
       11
       +
         The command <literal>journalctl</literal> allows you to see the contents of

     

       12
       12
       +
         the journal. For example,

     

       9
       13
        
       <screen>

     

       10
       14
        
       <prompt>$ </prompt>journalctl -b

     

       11
       15
        
       </screen>

     

       12
       12
       -
         shows all journal entries since the last reboot. (The output of <command>journalctl</command> is piped into <command>less</command> by default.) You can use various options and match operators to restrict output to messages of interest. For instance, to get all messages from PostgreSQL:

     

       16
       16
       +
         shows all journal entries since the last reboot. (The output of

     

       17
       17
       +
         <command>journalctl</command> is piped into <command>less</command> by

     

       18
       18
       +
         default.) You can use various options and match operators to restrict output

     

       19
       19
       +
         to messages of interest. For instance, to get all messages from PostgreSQL:

     

       13
       20
        
       <screen>

     

       14
       21
        
       <prompt>$ </prompt>journalctl -u postgresql.service

     

       15
       22
        
       -- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. --

     
···

       19
       26
        
       Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG:  database system was shut down at 2013-01-07 15:44:14 CET

     

       20
       27
        
       Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG:  database system is ready to accept connections

     

       21
       28
        
       </screen>

     

       22
       22
       -
         Or to get all messages since the last reboot that have at least a “critical” severity level:

     

       29
       29
       +
         Or to get all messages since the last reboot that have at least a

     

       30
       30
       +
         “critical” severity level:

     

       23
       31
        
       <screen>

     

       24
       32
        
       <prompt>$ </prompt>journalctl -b -p crit

     

       25
       33
        
       Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice]

     
···

       27
       35
        
       </screen>

     

       28
       36
        
        </para>

     

       29
       37
        
        <para>

     

       30
       30
       -
         The system journal is readable by root and by users in the <literal>wheel</literal> and <literal>systemd-journal</literal> groups. All users have a private journal that can be read using <command>journalctl</command>.

     

       38
       38
       +
         The system journal is readable by root and by users in the

     

       39
       39
       +
         <literal>wheel</literal> and <literal>systemd-journal</literal> groups. All

     

       40
       40
       +
         users have a private journal that can be read using

     

       41
       41
       +
         <command>journalctl</command>.

     

       31
       42
        
        </para>

     

       32
       43
        
       </chapter>

+3 -1

nixos/doc/manual/administration/maintenance-mode.xml

···

       9
       9
        
         You can enter rescue mode by running:

     

       10
       10
        
       <screen>

     

       11
       11
        
       # systemctl rescue</screen>

     

       12
       12
       -
         This will eventually give you a single-user root shell. Systemd will stop (almost) all system services. To get out of maintenance mode, just exit from the rescue shell.

     

       12
       12
       +
         This will eventually give you a single-user root shell. Systemd will stop

     

       13
       13
       +
         (almost) all system services. To get out of maintenance mode, just exit from

     

       14
       14
       +
         the rescue shell.

     

       13
       15
        
        </para>

     

       14
       16
        
       </section>

+11 -2

nixos/doc/manual/administration/network-problems.xml

···

       6
       6
        
        <title>Network Problems</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Nix uses a so-called <emphasis>binary cache</emphasis> to optimise building a package from source into downloading it as a pre-built binary. That is, whenever a command like <command>nixos-rebuild</command> needs a path in the Nix store, Nix will try to download that path from the Internet rather than build it from source. The default binary cache is <uri>https://cache.nixos.org/</uri>. If this cache is unreachable, Nix operations may take a long time due to HTTP connection timeouts. You can disable the use of the binary cache by adding <option>--option use-binary-caches false</option>, e.g.

     

       9
       9
       +
         Nix uses a so-called <emphasis>binary cache</emphasis> to optimise building a

     

       10
       10
       +
         package from source into downloading it as a pre-built binary. That is,

     

       11
       11
       +
         whenever a command like <command>nixos-rebuild</command> needs a path in the

     

       12
       12
       +
         Nix store, Nix will try to download that path from the Internet rather than

     

       13
       13
       +
         build it from source. The default binary cache is

     

       14
       14
       +
         <uri>https://cache.nixos.org/</uri>. If this cache is unreachable, Nix

     

       15
       15
       +
         operations may take a long time due to HTTP connection timeouts. You can

     

       16
       16
       +
         disable the use of the binary cache by adding <option>--option

     

       17
       17
       +
         use-binary-caches false</option>, e.g.

     

       10
       18
        
       <screen>

     

       11
       19
        
       # nixos-rebuild switch --option use-binary-caches false

     

       12
       20
        
       </screen>

     

       13
       13
       -
         If you have an alternative binary cache at your disposal, you can use it instead:

     

       21
       21
       +
         If you have an alternative binary cache at your disposal, you can use it

     

       22
       22
       +
         instead:

     

       14
       23
        
       <screen>

     

       15
       24
        
       # nixos-rebuild switch --option binary-caches http://my-cache.example.org/

     

       16
       25
        
       </screen>

+8 -3

nixos/doc/manual/administration/rebooting.xml

···

       16
       16
        
       <screen>

     

       17
       17
        
       # reboot

     

       18
       18
        
       </screen>

     

       19
       19
       -
         which is equivalent to <command>systemctl reboot</command>. Alternatively, you can quickly reboot the system using <literal>kexec</literal>, which bypasses the BIOS by directly loading the new kernel into memory:

     

       19
       19
       +
         which is equivalent to <command>systemctl reboot</command>. Alternatively,

     

       20
       20
       +
         you can quickly reboot the system using <literal>kexec</literal>, which

     

       21
       21
       +
         bypasses the BIOS by directly loading the new kernel into memory:

     

       20
       22
        
       <screen>

     

       21
       23
        
       # systemctl kexec

     

       22
       24
        
       </screen>

     

       23
       25
        
        </para>

     

       24
       26
        
        <para>

     

       25
       25
       -
         The machine can be suspended to RAM (if supported) using <command>systemctl suspend</command>, and suspended to disk using <command>systemctl hibernate</command>.

     

       27
       27
       +
         The machine can be suspended to RAM (if supported) using <command>systemctl

     

       28
       28
       +
         suspend</command>, and suspended to disk using <command>systemctl

     

       29
       29
       +
         hibernate</command>.

     

       26
       30
        
        </para>

     

       27
       31
        
        <para>

     

       28
       28
       -
         These commands can be run by any user who is logged in locally, i.e. on a virtual console or in X11; otherwise, the user is asked for authentication.

     

       32
       32
       +
         These commands can be run by any user who is logged in locally, i.e. on a

     

       33
       33
       +
         virtual console or in X11; otherwise, the user is asked for authentication.

     

       29
       34
        
        </para>

     

       30
       35
        
       </chapter>

+12 -3

nixos/doc/manual/administration/rollback.xml

···

       6
       6
        
        <title>Rolling Back Configuration Changes</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         After running <command>nixos-rebuild</command> to switch to a new configuration, you may find that the new configuration doesn’t work very well. In that case, there are several ways to return to a previous configuration.

     

       9
       9
       +
         After running <command>nixos-rebuild</command> to switch to a new

     

       10
       10
       +
         configuration, you may find that the new configuration doesn’t work very

     

       11
       11
       +
         well. In that case, there are several ways to return to a previous

     

       12
       12
       +
         configuration.

     

       10
       13
        
        </para>

     

       11
       14
        
       

     

       12
       15
        
        <para>

     

       13
       13
       -
         First, the GRUB boot manager allows you to boot into any previous configuration that hasn’t been garbage-collected. These configurations can be found under the GRUB submenu “NixOS - All configurations”. This is especially useful if the new configuration fails to boot. After the system has booted, you can make the selected configuration the default for subsequent boots:

     

       16
       16
       +
         First, the GRUB boot manager allows you to boot into any previous

     

       17
       17
       +
         configuration that hasn’t been garbage-collected. These configurations can

     

       18
       18
       +
         be found under the GRUB submenu “NixOS - All configurations”. This is

     

       19
       19
       +
         especially useful if the new configuration fails to boot. After the system

     

       20
       20
       +
         has booted, you can make the selected configuration the default for

     

       21
       21
       +
         subsequent boots:

     

       14
       22
        
       <screen>

     

       15
       23
        
       # /run/current-system/bin/switch-to-configuration boot</screen>

     

       16
       24
        
        </para>

     
···

       22
       30
        
         This is equivalent to running:

     

       23
       31
        
       <screen>

     

       24
       32
        
       # /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>

     

       25
       25
       -
         where <replaceable>N</replaceable> is the number of the NixOS system configuration. To get a list of the available configurations, do:

     

       33
       33
       +
         where <replaceable>N</replaceable> is the number of the NixOS system

     

       34
       34
       +
         configuration. To get a list of the available configurations, do:

     

       26
       35
        
       <screen>

     

       27
       36
        
       <prompt>$ </prompt>ls -l /nix/var/nix/profiles/system-*-link

     

       28
       37
        
       <replaceable>...</replaceable>

+2 -1

nixos/doc/manual/administration/running.xml

···

       6
       6
        
        <title>Administration</title>

     

       7
       7
        
        <partintro xml:id="ch-running-intro">

     

       8
       8
        
         <para>

     

       9
       9
       -
          This chapter describes various aspects of managing a running NixOS system, such as how to use the <command>systemd</command> service manager.

     

       9
       9
       +
          This chapter describes various aspects of managing a running NixOS system,

     

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

     

       10
       11
        
         </para>

     

       11
       12
        
        </partintro>

     

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

+21 -5

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

···

       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 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 complex dependencies; for instance, one unit can require that another unit must be successfully started before the first unit can be started. When the system boots, it starts a unit named <literal>default.target</literal>; the dependencies of this unit cause all system services to be started, file systems to be mounted, swap files to be activated, and so on.

     

       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.

     

       9
       18
        
        </para>

     

       10
       19
        
        <para>

     

       11
       11
       -
         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:

     

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

     

       21
       21
       +
         <command>systemd</command>. Without any arguments, it shows the status of

     

       22
       22
       +
         active units:

     

       12
       23
        
       <screen>

     

       13
       24
        
       <prompt>$ </prompt>systemctl

     

       14
       25
        
       -.mount          loaded active mounted   /

     
···

       19
       30
        
       </screen>

     

       20
       31
        
        </para>

     

       21
       32
        
        <para>

     

       22
       22
       -
         You can ask for detailed status information about a unit, for instance, the PostgreSQL database service:

     

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

     

       34
       34
       +
         PostgreSQL database service:

     

       23
       35
        
       <screen>

     

       24
       36
        
       <prompt>$ </prompt>systemctl status postgresql.service

     

       25
       37
        
       postgresql.service - PostgreSQL Server

     
···

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

     

       40
       52
        
       Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.

     

       41
       53
        
       </screen>

     

       42
       42
       -
         Note that this shows the status of the unit (active and running), all the processes belonging to the service, as well as the most recent log messages from the service.

     

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

     

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

     

       56
       56
       +
         from the service.

     

       43
       57
        
        </para>

     

       44
       58
        
        <para>

     

       45
       59
        
         Units can be stopped, started or restarted:

     
···

       48
       62
        
       # systemctl start postgresql.service

     

       49
       63
        
       # systemctl restart postgresql.service

     

       50
       64
        
       </screen>

     

       51
       51
       -
         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).

     

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

     

       66
       66
       +
         starting or stopping (or has failed). Starting a unit will cause the

     

       67
       67
       +
         dependencies of that unit to be started as well (if necessary).

     

       52
       68
        
        </para>

     

       53
       69
        
       <!-- - cgroups: each service and user session is a cgroup

     

       54
       70

+13 -4

nixos/doc/manual/administration/store-corruption.xml

···

       6
       6
        
        <title>Nix Store Corruption</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         After a system crash, it’s possible for files in the Nix store to become corrupted. (For instance, the Ext4 file system has the tendency to replace un-synced files with zero bytes.) NixOS tries hard to prevent this from happening: it performs a <command>sync</command> before switching to a new configuration, and Nix’s database is fully transactional. If corruption still occurs, you may be able to fix it automatically.

     

       9
       9
       +
         After a system crash, it’s possible for files in the Nix store to become

     

       10
       10
       +
         corrupted. (For instance, the Ext4 file system has the tendency to replace

     

       11
       11
       +
         un-synced files with zero bytes.) NixOS tries hard to prevent this from

     

       12
       12
       +
         happening: it performs a <command>sync</command> before switching to a new

     

       13
       13
       +
         configuration, and Nix’s database is fully transactional. If corruption

     

       14
       14
       +
         still occurs, you may be able to fix it automatically.

     

       10
       15
        
        </para>

     

       11
       16
        
       

     

       12
       17
        
        <para>

     

       13
       13
       -
         If the corruption is in a path in the closure of the NixOS system configuration, you can fix it by doing

     

       18
       18
       +
         If the corruption is in a path in the closure of the NixOS system

     

       19
       19
       +
         configuration, you can fix it by doing

     

       14
       20
        
       <screen>

     

       15
       21
        
       <prompt># </prompt>nixos-rebuild switch --repair

     

       16
       22
        
       </screen>

     

       17
       17
       -
         This will cause Nix to check every path in the closure, and if its cryptographic hash differs from the hash recorded in Nix’s database, the path is rebuilt or redownloaded.

     

       23
       23
       +
         This will cause Nix to check every path in the closure, and if its

     

       24
       24
       +
         cryptographic hash differs from the hash recorded in Nix’s database, the

     

       25
       25
       +
         path is rebuilt or redownloaded.

     

       18
       26
        
        </para>

     

       19
       27
        
       

     

       20
       28
        
        <para>

     
···

       22
       30
        
       <screen>

     

       23
       31
        
       <prompt># </prompt>nix-store --verify --check-contents --repair

     

       24
       32
        
       </screen>

     

       25
       25
       -
         Any corrupt paths will be redownloaded if they’re available in a binary cache; otherwise, they cannot be repaired.

     

       33
       33
       +
         Any corrupt paths will be redownloaded if they’re available in a binary

     

       34
       34
       +
         cache; otherwise, they cannot be repaired.

     

       26
       35
        
        </para>

     

       27
       36
        
       </section>

+2 -1

nixos/doc/manual/administration/troubleshooting.xml

···

       5
       5
        
               xml:id="ch-troubleshooting">

     

       6
       6
        
        <title>Troubleshooting</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         This chapter describes solutions to common problems you might encounter when you manage your NixOS system.

     

       8
       8
       +
         This chapter describes solutions to common problems you might encounter when

     

       9
       9
       +
         you manage your NixOS system.

     

       9
       10
        
        </para>

     

       10
       11
        
        <xi:include href="boot-problems.xml" />

     

       11
       12
        
        <xi:include href="maintenance-mode.xml" />

+12 -3

nixos/doc/manual/administration/user-sessions.xml

···

       5
       5
        
               xml:id="sec-user-sessions">

     

       6
       6
        
        <title>User Sessions</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         Systemd keeps track of all users who are logged into the system (e.g. on a virtual console or remotely via SSH). The command <command>loginctl</command> allows querying and manipulating user sessions. For instance, to list all user sessions:

     

       8
       8
       +
         Systemd keeps track of all users who are logged into the system (e.g. on a

     

       9
       9
       +
         virtual console or remotely via SSH). The command <command>loginctl</command>

     

       10
       10
       +
         allows querying and manipulating user sessions. For instance, to list all

     

       11
       11
       +
         user sessions:

     

       9
       12
        
       <screen>

     

       10
       13
        
       <prompt>$ </prompt>loginctl

     

       11
       14
        
          SESSION        UID USER             SEAT

     
···

       13
       16
        
               c3          0 root             seat0

     

       14
       17
        
               c4        500 alice

     

       15
       18
        
       </screen>

     

       16
       16
       -
         This shows that two users are logged in locally, while another is logged in remotely. (“Seats” are essentially the combinations of displays and input devices attached to the system; usually, there is only one seat.) To get information about a session:

     

       19
       19
       +
         This shows that two users are logged in locally, while another is logged in

     

       20
       20
       +
         remotely. (“Seats” are essentially the combinations of displays and input

     

       21
       21
       +
         devices attached to the system; usually, there is only one seat.) To get

     

       22
       22
       +
         information about a session:

     

       17
       23
        
       <screen>

     

       18
       24
        
       <prompt>$ </prompt>loginctl session-status c3

     

       19
       25
        
       c3 - root (0)

     
···

       28
       34
        
                         ├─10339 -bash

     

       29
       35
        
                         └─10355 w3m nixos.org

     

       30
       36
        
       </screen>

     

       31
       31
       -
         This shows that the user is logged in on virtual console 3. It also lists the processes belonging to this session. Since systemd keeps track of this, you can terminate a session in a way that ensures that all the session’s processes are gone:

     

       37
       37
       +
         This shows that the user is logged in on virtual console 3. It also lists the

     

       38
       38
       +
         processes belonging to this session. Since systemd keeps track of this, you

     

       39
       39
       +
         can terminate a session in a way that ensures that all the session’s

     

       40
       40
       +
         processes are gone:

     

       32
       41
        
       <screen>

     

       33
       42
        
       # loginctl terminate-session c3

     

       34
       43
        
       </screen>

+36 -12

nixos/doc/manual/configuration/abstractions.xml

···

       6
       6
        
        <title>Abstractions</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         If you find yourself repeating yourself over and over, it’s time to abstract. Take, for instance, this Apache HTTP Server configuration:

     

       9
       9
       +
         If you find yourself repeating yourself over and over, it’s time to

     

       10
       10
       +
         abstract. Take, for instance, this Apache HTTP Server configuration:

     

       10
       11
        
       <programlisting>

     

       11
       12
        
       {

     

       12
       13
        
         <xref linkend="opt-services.httpd.virtualHosts"/> =

     
···

       26
       27
        
           ];

     

       27
       28
        
       }

     

       28
       29
        
       </programlisting>

     

       29
       29
       -
         It defines two virtual hosts with nearly identical configuration; the only difference is that the second one has SSL enabled. To prevent this duplication, we can use a <literal>let</literal>:

     

       30
       30
       +
         It defines two virtual hosts with nearly identical configuration; the only

     

       31
       31
       +
         difference is that the second one has SSL enabled. To prevent this

     

       32
       32
       +
         duplication, we can use a <literal>let</literal>:

     

       30
       33
        
       <programlisting>

     

       31
       34
        
       let

     

       32
       35
        
         exampleOrgCommon =

     
···

       47
       50
        
           ];

     

       48
       51
        
       }

     

       49
       52
        
       </programlisting>

     

       50
       50
       -
         The <literal>let exampleOrgCommon = <replaceable>...</replaceable></literal> defines a variable named <literal>exampleOrgCommon</literal>. The <literal>//</literal> operator merges two attribute sets, so the configuration of the second virtual host is the set <literal>exampleOrgCommon</literal> extended with the SSL options.

     

       53
       53
       +
         The <literal>let exampleOrgCommon = <replaceable>...</replaceable></literal>

     

       54
       54
       +
         defines a variable named <literal>exampleOrgCommon</literal>. The

     

       55
       55
       +
         <literal>//</literal> operator merges two attribute sets, so the

     

       56
       56
       +
         configuration of the second virtual host is the set

     

       57
       57
       +
         <literal>exampleOrgCommon</literal> extended with the SSL options.

     

       51
       58
        
        </para>

     

       52
       59
        
       

     

       53
       60
        
        <para>

     

       54
       54
       -
         You can write a <literal>let</literal> wherever an expression is allowed. Thus, you also could have written:

     

       61
       61
       +
         You can write a <literal>let</literal> wherever an expression is allowed.

     

       62
       62
       +
         Thus, you also could have written:

     

       55
       63
        
       <programlisting>

     

       56
       64
        
       {

     

       57
       65
        
         <xref linkend="opt-services.httpd.virtualHosts"/> =

     
···

       61
       69
        
           ];

     

       62
       70
        
       }

     

       63
       71
        
       </programlisting>

     

       64
       64
       -
         but not <literal>{ let exampleOrgCommon = <replaceable>...</replaceable>; in <replaceable>...</replaceable>; }</literal> since attributes (as opposed to attribute values) are not expressions.

     

       72
       72
       +
         but not <literal>{ let exampleOrgCommon = <replaceable>...</replaceable>; in

     

       73
       73
       +
         <replaceable>...</replaceable>; }</literal> since attributes (as opposed to

     

       74
       74
       +
         attribute values) are not expressions.

     

       65
       75
        
        </para>

     

       66
       76
        
       

     

       67
       77
        
        <para>

     

       68
       68
       -
         <emphasis>Functions</emphasis> provide another method of abstraction. For instance, suppose that we want to generate lots of different virtual hosts, all with identical configuration except for the host name. This can be done as follows:

     

       78
       78
       +
         <emphasis>Functions</emphasis> provide another method of abstraction. For

     

       79
       79
       +
         instance, suppose that we want to generate lots of different virtual hosts,

     

       80
       80
       +
         all with identical configuration except for the host name. This can be done

     

       81
       81
       +
         as follows:

     

       69
       82
        
       <programlisting>

     

       70
       83
        
       {

     

       71
       84
        
         <xref linkend="opt-services.httpd.virtualHosts"/> =

     
···

       83
       96
        
             ];

     

       84
       97
        
       }

     

       85
       98
        
       </programlisting>

     

       86
       86
       -
         Here, <varname>makeVirtualHost</varname> is a function that takes a single argument <literal>name</literal> and returns the configuration for a virtual host. That function is then called for several names to produce the list of virtual host configurations.

     

       99
       99
       +
         Here, <varname>makeVirtualHost</varname> is a function that takes a single

     

       100
       100
       +
         argument <literal>name</literal> and returns the configuration for a virtual

     

       101
       101
       +
         host. That function is then called for several names to produce the list of

     

       102
       102
       +
         virtual host configurations.

     

       87
       103
        
        </para>

     

       88
       104
        
       

     

       89
       105
        
        <para>

     

       90
       90
       -
         We can further improve on this by using the function <varname>map</varname>, which applies another function to every element in a list:

     

       106
       106
       +
         We can further improve on this by using the function <varname>map</varname>,

     

       107
       107
       +
         which applies another function to every element in a list:

     

       91
       108
        
       <programlisting>

     

       92
       109
        
       {

     

       93
       110
        
         <xref linkend="opt-services.httpd.virtualHosts"/> =

     
···

       97
       114
        
             [ "example.org" "example.com" "example.gov" "example.nl" ];

     

       98
       115
        
       }

     

       99
       116
        
       </programlisting>

     

       100
       100
       -
         (The function <literal>map</literal> is called a <emphasis>higher-order function</emphasis> because it takes another function as an argument.)

     

       117
       117
       +
         (The function <literal>map</literal> is called a <emphasis>higher-order

     

       118
       118
       +
         function</emphasis> because it takes another function as an argument.)

     

       101
       119
        
        </para>

     

       102
       120
        
       

     

       103
       121
        
        <para>

     

       104
       104
       -
         What if you need more than one argument, for instance, if we want to use a different <literal>documentRoot</literal> for each virtual host? Then we can make <varname>makeVirtualHost</varname> a function that takes a <emphasis>set</emphasis> as its argument, like this:

     

       122
       122
       +
         What if you need more than one argument, for instance, if we want to use a

     

       123
       123
       +
         different <literal>documentRoot</literal> for each virtual host? Then we can

     

       124
       124
       +
         make <varname>makeVirtualHost</varname> a function that takes a

     

       125
       125
       +
         <emphasis>set</emphasis> as its argument, like this:

     

       105
       126
        
       <programlisting>

     

       106
       127
        
       {

     

       107
       128
        
         <xref linkend="opt-services.httpd.virtualHosts"/> =

     
···

       119
       140
        
             ];

     

       120
       141
        
       }

     

       121
       142
        
       </programlisting>

     

       122
       122
       -
         But in this case (where every root is a subdirectory of <filename>/sites</filename> named after the virtual host), it would have been shorter to define <varname>makeVirtualHost</varname> as

     

       143
       143
       +
         But in this case (where every root is a subdirectory of

     

       144
       144
       +
         <filename>/sites</filename> named after the virtual host), it would have been

     

       145
       145
       +
         shorter to define <varname>makeVirtualHost</varname> as

     

       123
       146
        
       <programlisting>

     

       124
       147
        
       makeVirtualHost = name:

     

       125
       148
        
         { hostName = name;

     
···

       127
       150
        
           adminAddr = "alice@example.org";

     

       128
       151
        
         };

     

       129
       152
        
       </programlisting>

     

       130
       130
       -
         Here, the construct <literal>${<replaceable>...</replaceable>}</literal> allows the result of an expression to be spliced into a string.

     

       153
       153
       +
         Here, the construct <literal>${<replaceable>...</replaceable>}</literal>

     

       154
       154
       +
         allows the result of an expression to be spliced into a string.

     

       131
       155
        
        </para>

     

       132
       156
        
       </section>

+4 -1

nixos/doc/manual/configuration/ad-hoc-network-config.xml

···

       6
       6
        
        <title>Ad-Hoc Configuration</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         You can use <xref linkend="opt-networking.localCommands"/> to specify shell commands to be run at the end of <literal>network-setup.service</literal>. This is useful for doing network configuration not covered by the existing NixOS modules. For instance, to statically configure an IPv6 address:

     

       9
       9
       +
         You can use <xref linkend="opt-networking.localCommands"/> to specify shell

     

       10
       10
       +
         commands to be run at the end of <literal>network-setup.service</literal>.

     

       11
       11
       +
         This is useful for doing network configuration not covered by the existing

     

       12
       12
       +
         NixOS modules. For instance, to statically configure an IPv6 address:

     

       10
       13
        
       <programlisting>

     

       11
       14
        
       <xref linkend="opt-networking.localCommands"/> =

     

       12
       15
        
         ''

+21 -5

nixos/doc/manual/configuration/ad-hoc-packages.xml

···

       6
       6
        
        <title>Ad-Hoc Package Management</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         With the command <command>nix-env</command>, you can install and uninstall packages from the command line. For instance, to install Mozilla Thunderbird:

     

       9
       9
       +
         With the command <command>nix-env</command>, you can install and uninstall

     

       10
       10
       +
         packages from the command line. For instance, to install Mozilla Thunderbird:

     

       10
       11
        
       <screen>

     

       11
       12
        
       <prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen>

     

       12
       12
       -
         If you invoke this as root, the package is installed in the Nix profile <filename>/nix/var/nix/profiles/default</filename> and visible to all users of the system; otherwise, the package ends up in <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename> and is not visible to other users. The <option>-A</option> flag specifies the package by its attribute name; without it, the package is installed by matching against its package name (e.g. <literal>thunderbird</literal>). The latter is slower because it requires matching against all available Nix packages, and is ambiguous if there are multiple matching packages.

     

       13
       13
       +
         If you invoke this as root, the package is installed in the Nix profile

     

       14
       14
       +
         <filename>/nix/var/nix/profiles/default</filename> and visible to all users

     

       15
       15
       +
         of the system; otherwise, the package ends up in

     

       16
       16
       +
         <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename>

     

       17
       17
       +
         and is not visible to other users. The <option>-A</option> flag specifies the

     

       18
       18
       +
         package by its attribute name; without it, the package is installed by

     

       19
       19
       +
         matching against its package name (e.g. <literal>thunderbird</literal>). The

     

       20
       20
       +
         latter is slower because it requires matching against all available Nix

     

       21
       21
       +
         packages, and is ambiguous if there are multiple matching packages.

     

       13
       22
        
        </para>

     

       14
       23
        
       

     

       15
       24
        
        <para>

     

       16
       16
       -
         Packages come from the NixOS channel. You typically upgrade a package by updating to the latest version of the NixOS channel:

     

       25
       25
       +
         Packages come from the NixOS channel. You typically upgrade a package by

     

       26
       26
       +
         updating to the latest version of the NixOS channel:

     

       17
       27
        
       <screen>

     

       18
       28
        
       <prompt>$ </prompt>nix-channel --update nixos

     

       19
       29
        
       </screen>

     

       20
       20
       -
         and then running <literal>nix-env -i</literal> again. Other packages in the profile are <emphasis>not</emphasis> affected; this is the crucial difference with the declarative style of package management, where running <command>nixos-rebuild switch</command> causes all packages to be updated to their current versions in the NixOS channel. You can however upgrade all packages for which there is a newer version by doing:

     

       30
       30
       +
         and then running <literal>nix-env -i</literal> again. Other packages in the

     

       31
       31
       +
         profile are <emphasis>not</emphasis> affected; this is the crucial difference

     

       32
       32
       +
         with the declarative style of package management, where running

     

       33
       33
       +
         <command>nixos-rebuild switch</command> causes all packages to be updated to

     

       34
       34
       +
         their current versions in the NixOS channel. You can however upgrade all

     

       35
       35
       +
         packages for which there is a newer version by doing:

     

       21
       36
        
       <screen>

     

       22
       37
        
       <prompt>$ </prompt>nix-env -u '*'

     

       23
       38
        
       </screen>

     
···

       38
       53
        
        </para>

     

       39
       54
        
       

     

       40
       55
        
        <para>

     

       41
       41
       -
         <command>nix-env</command> has many more flags. For details, see the <citerefentry>

     

       56
       56
       +
         <command>nix-env</command> has many more flags. For details, see the

     

       57
       57
       +
         <citerefentry>

     

       42
       58
        
         <refentrytitle>nix-env</refentrytitle>

     

       43
       59
        
         <manvolnum>1</manvolnum></citerefentry> manpage or the Nix manual.

     

       44
       60
        
        </para>

+17 -6

nixos/doc/manual/configuration/adding-custom-packages.xml

···

       6
       6
        
        <title>Adding Custom Packages</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         It’s possible that a package you need is not available in NixOS. In that case, you can do two things. First, you can clone the Nixpkgs repository, add the package to your clone, and (optionally) submit a patch or pull request to have it accepted into the main Nixpkgs repository. This is described in detail in the <link

     

       10
       10
       -
       xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs manual</link>. In short, you clone Nixpkgs:

     

       9
       9
       +
         It’s possible that a package you need is not available in NixOS. In that

     

       10
       10
       +
         case, you can do two things. First, you can clone the Nixpkgs repository, add

     

       11
       11
       +
         the package to your clone, and (optionally) submit a patch or pull request to

     

       12
       12
       +
         have it accepted into the main Nixpkgs repository. This is described in

     

       13
       13
       +
         detail in the <link

     

       14
       14
       +
       xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs

     

       15
       15
       +
         manual</link>. In short, you clone Nixpkgs:

     

       11
       16
        
       <screen>

     

       12
       17
        
       <prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs

     

       13
       18
        
       <prompt>$ </prompt>cd nixpkgs

     

       14
       19
        
       </screen>

     

       15
       15
       -
         Then you write and test the package as described in the Nixpkgs manual. Finally, you add it to <literal>environment.systemPackages</literal>, e.g.

     

       20
       20
       +
         Then you write and test the package as described in the Nixpkgs manual.

     

       21
       21
       +
         Finally, you add it to <literal>environment.systemPackages</literal>, e.g.

     

       16
       22
        
       <programlisting>

     

       17
       23
        
       <xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ];

     

       18
       24
        
       </programlisting>

     

       19
       19
       -
         and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs tree:

     

       25
       25
       +
         and you run <command>nixos-rebuild</command>, specifying your own Nixpkgs

     

       26
       26
       +
         tree:

     

       20
       27
        
       <screen>

     

       21
       28
        
       # nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>

     

       22
       29
        
        </para>

     

       23
       30
        
       

     

       24
       31
        
        <para>

     

       25
       25
       -
         The second possibility is to add the package outside of the Nixpkgs tree. For instance, here is how you specify a build of the <link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link> package directly in <filename>configuration.nix</filename>:

     

       32
       32
       +
         The second possibility is to add the package outside of the Nixpkgs tree. For

     

       33
       33
       +
         instance, here is how you specify a build of the

     

       34
       34
       +
         <link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link>

     

       35
       35
       +
         package directly in <filename>configuration.nix</filename>:

     

       26
       36
        
       <programlisting>

     

       27
       37
        
       <xref linkend="opt-environment.systemPackages"/> =

     

       28
       38
        
         let

     
···

       36
       46
        
         in

     

       37
       47
        
         [ my-hello ];

     

       38
       48
        
       </programlisting>

     

       39
       39
       -
         Of course, you can also move the definition of <literal>my-hello</literal> into a separate Nix expression, e.g.

     

       49
       49
       +
         Of course, you can also move the definition of <literal>my-hello</literal>

     

       50
       50
       +
         into a separate Nix expression, e.g.

     

       40
       51
        
       <programlisting>

     

       41
       52
        
       <xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ];

     

       42
       53
        
       </programlisting>

+57 -14

nixos/doc/manual/configuration/config-file.xml

···

       13
       13
        
       { <replaceable>option definitions</replaceable>

     

       14
       14
        
       }

     

       15
       15
        
       </programlisting>

     

       16
       16
       -
         The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this is actually a function that takes at least the two arguments <varname>config</varname> and <varname>pkgs</varname>. (These are explained later.) The function returns a <emphasis>set</emphasis> of option definitions (<literal>{ <replaceable>...</replaceable> }</literal>). These definitions have the form <literal><replaceable>name</replaceable> = <replaceable>value</replaceable></literal>, where <replaceable>name</replaceable> is the name of an option and <replaceable>value</replaceable> is its value. For example,

     

       16
       16
       +
         The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this

     

       17
       17
       +
         is actually a function that takes at least the two arguments

     

       18
       18
       +
         <varname>config</varname> and <varname>pkgs</varname>. (These are explained

     

       19
       19
       +
         later.) The function returns a <emphasis>set</emphasis> of option definitions

     

       20
       20
       +
         (<literal>{ <replaceable>...</replaceable> }</literal>). These definitions

     

       21
       21
       +
         have the form <literal><replaceable>name</replaceable> =

     

       22
       22
       +
         <replaceable>value</replaceable></literal>, where

     

       23
       23
       +
         <replaceable>name</replaceable> is the name of an option and

     

       24
       24
       +
         <replaceable>value</replaceable> is its value. For example,

     

       17
       25
        
       <programlisting>

     

       18
       26
        
       { config, pkgs, ... }:

     

       19
       27
        
       

     
···

       22
       30
        
         <xref linkend="opt-services.httpd.documentRoot"/> = "/webroot";

     

       23
       31
        
       }

     

       24
       32
        
       </programlisting>

     

       25
       25
       -
         defines a configuration with three option definitions that together enable the Apache HTTP Server with <filename>/webroot</filename> as the document root.

     

       33
       33
       +
         defines a configuration with three option definitions that together enable

     

       34
       34
       +
         the Apache HTTP Server with <filename>/webroot</filename> as the document

     

       35
       35
       +
         root.

     

       26
       36
        
        </para>

     

       27
       37
        
       

     

       28
       38
        
        <para>

     

       29
       29
       -
         Sets can be nested, and in fact dots in option names are shorthand for defining a set containing another set. For instance, <xref linkend="opt-services.httpd.enable"/> defines a set named <varname>services</varname> that contains a set named <varname>httpd</varname>, which in turn contains an option definition named <varname>enable</varname> with value <literal>true</literal>. This means that the example above can also be written as:

     

       39
       39
       +
         Sets can be nested, and in fact dots in option names are shorthand for

     

       40
       40
       +
         defining a set containing another set. For instance,

     

       41
       41
       +
         <xref linkend="opt-services.httpd.enable"/> defines a set named

     

       42
       42
       +
         <varname>services</varname> that contains a set named

     

       43
       43
       +
         <varname>httpd</varname>, which in turn contains an option definition named

     

       44
       44
       +
         <varname>enable</varname> with value <literal>true</literal>. This means that

     

       45
       45
       +
         the example above can also be written as:

     

       30
       46
        
       <programlisting>

     

       31
       47
        
       { config, pkgs, ... }:

     

       32
       48
        
       

     
···

       39
       55
        
         };

     

       40
       56
        
       }

     

       41
       57
        
       </programlisting>

     

       42
       42
       -
         which may be more convenient if you have lots of option definitions that share the same prefix (such as <literal>services.httpd</literal>).

     

       58
       58
       +
         which may be more convenient if you have lots of option definitions that

     

       59
       59
       +
         share the same prefix (such as <literal>services.httpd</literal>).

     

       43
       60
        
        </para>

     

       44
       61
        
       

     

       45
       62
        
        <para>

     

       46
       46
       -
         NixOS checks your option definitions for correctness. For instance, if you try to define an option that doesn’t exist (that is, doesn’t have a corresponding <emphasis>option declaration</emphasis>), <command>nixos-rebuild</command> will give an error like:

     

       63
       63
       +
         NixOS checks your option definitions for correctness. For instance, if you

     

       64
       64
       +
         try to define an option that doesn’t exist (that is, doesn’t have a

     

       65
       65
       +
         corresponding <emphasis>option declaration</emphasis>),

     

       66
       66
       +
         <command>nixos-rebuild</command> will give an error like:

     

       47
       67
        
       <screen>

     

       48
       68
        
       The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.

     

       49
       69
        
       </screen>

     

       50
       50
       -
         Likewise, values in option definitions must have a correct type. For instance, <option>services.httpd.enable</option> must be a Boolean (<literal>true</literal> or <literal>false</literal>). Trying to give it a value of another type, such as a string, will cause an error:

     

       70
       70
       +
         Likewise, values in option definitions must have a correct type. For

     

       71
       71
       +
         instance, <option>services.httpd.enable</option> must be a Boolean

     

       72
       72
       +
         (<literal>true</literal> or <literal>false</literal>). Trying to give it a

     

       73
       73
       +
         value of another type, such as a string, will cause an error:

     

       51
       74
        
       <screen>

     

       52
       75
        
       The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.

     

       53
       76
        
       </screen>

     
···

       66
       89
        
       <programlisting>

     

       67
       90
        
       <xref linkend="opt-networking.hostName"/> = "dexter";

     

       68
       91
        
       </programlisting>

     

       69
       69
       -
             Special characters can be escaped by prefixing them with a backslash (e.g. <literal>\"</literal>).

     

       92
       92
       +
             Special characters can be escaped by prefixing them with a backslash

     

       93
       93
       +
             (e.g. <literal>\"</literal>).

     

       70
       94
        
            </para>

     

       71
       95
        
            <para>

     

       72
       72
       -
             Multi-line strings can be enclosed in <emphasis>double single quotes</emphasis>, e.g.

     

       96
       96
       +
             Multi-line strings can be enclosed in <emphasis>double single

     

       97
       97
       +
             quotes</emphasis>, e.g.

     

       73
       98
        
       <programlisting>

     

       74
       99
        
       <xref linkend="opt-networking.extraHosts"/> =

     

       75
       100
        
         ''

     
···

       77
       102
        
           10.0.0.1 server

     

       78
       103
        
         '';

     

       79
       104
        
       </programlisting>

     

       80
       80
       -
             The main difference is that it strips from each line a number of spaces equal to the minimal indentation of the string as a whole (disregarding the indentation of empty lines), and that characters like <literal>"</literal> and <literal>\</literal> are not special (making it more convenient for including things like shell code). See more info about this in the Nix manual <link

     

       105
       105
       +
             The main difference is that it strips from each line a number of spaces

     

       106
       106
       +
             equal to the minimal indentation of the string as a whole (disregarding

     

       107
       107
       +
             the indentation of empty lines), and that characters like

     

       108
       108
       +
             <literal>"</literal> and <literal>\</literal> are not special (making it

     

       109
       109
       +
             more convenient for including things like shell code). See more info

     

       110
       110
       +
             about this in the Nix manual

     

       111
       111
       +
             <link

     

       81
       112
        
             xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.

     

       82
       113
        
            </para>

     

       83
       114
        
           </listitem>

     
···

       106
       137
        
       <programlisting>

     

       107
       138
        
       <xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;

     

       108
       139
        
       </programlisting>

     

       109
       109
       -
             (Note that here the attribute name <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to prevent it from being interpreted as a set named <literal>net</literal> containing a set named <literal>ipv4</literal>, and so on. This is because it’s not a NixOS option but the literal name of a Linux kernel setting.)

     

       140
       140
       +
             (Note that here the attribute name

     

       141
       141
       +
             <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to

     

       142
       142
       +
             prevent it from being interpreted as a set named <literal>net</literal>

     

       143
       143
       +
             containing a set named <literal>ipv4</literal>, and so on. This is

     

       144
       144
       +
             because it’s not a NixOS option but the literal name of a Linux kernel

     

       145
       145
       +
             setting.)

     

       110
       146
        
            </para>

     

       111
       147
        
           </listitem>

     

       112
       148
        
          </varlistentry>

     
···

       116
       152
        
           </term>

     

       117
       153
        
           <listitem>

     

       118
       154
        
            <para>

     

       119
       119
       -
             Sets were introduced above. They are name/value pairs enclosed in braces, as in the option definition

     

       155
       155
       +
             Sets were introduced above. They are name/value pairs enclosed in braces,

     

       156
       156
       +
             as in the option definition

     

       120
       157
        
       <programlisting>

     

       121
       158
        
       <xref linkend="opt-fileSystems"/>."/boot" =

     

       122
       159
        
         { device = "/dev/sda1";

     
···

       133
       170
        
           </term>

     

       134
       171
        
           <listitem>

     

       135
       172
        
            <para>

     

       136
       136
       -
             The important thing to note about lists is that list elements are separated by whitespace, like this:

     

       173
       173
       +
             The important thing to note about lists is that list elements are

     

       174
       174
       +
             separated by whitespace, like this:

     

       137
       175
        
       <programlisting>

     

       138
       176
        
       <xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];

     

       139
       177
        
       </programlisting>

     
···

       150
       188
        
           </term>

     

       151
       189
        
           <listitem>

     

       152
       190
        
            <para>

     

       153
       153
       -
             Usually, the packages you need are already part of the Nix Packages collection, which is a set that can be accessed through the function argument <varname>pkgs</varname>. Typical uses:

     

       191
       191
       +
             Usually, the packages you need are already part of the Nix Packages

     

       192
       192
       +
             collection, which is a set that can be accessed through the function

     

       193
       193
       +
             argument <varname>pkgs</varname>. Typical uses:

     

       154
       194
        
       <programlisting>

     

       155
       195
        
       <xref linkend="opt-environment.systemPackages"/> =

     

       156
       196
        
         [ pkgs.thunderbird

     
···

       159
       199
        
       

     

       160
       200
        
       <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10;

     

       161
       201
        
       </programlisting>

     

       162
       162
       -
             The latter option definition changes the default PostgreSQL package used by NixOS’s PostgreSQL service to 10.x. For more information on packages, including how to add new ones, see <xref linkend="sec-custom-packages"/>.

     

       202
       202
       +
             The latter option definition changes the default PostgreSQL package used

     

       203
       203
       +
             by NixOS’s PostgreSQL service to 10.x. For more information on

     

       204
       204
       +
             packages, including how to add new ones, see

     

       205
       205
       +
             <xref linkend="sec-custom-packages"/>.

     

       163
       206
        
            </para>

     

       164
       207
        
           </listitem>

     

       165
       208
        
          </varlistentry>

+12 -2

nixos/doc/manual/configuration/config-syntax.xml

···

       5
       5
        
                xml:id="sec-configuration-syntax">

     

       6
       6
        
        <title>Configuration Syntax</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         The NixOS configuration file <filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix expression</emphasis>, which is the Nix package manager’s purely functional language for describing how to build packages and configurations. This means you have all the expressive power of that language at your disposal, including the ability to abstract over common patterns, which is very useful when managing complex systems. The syntax and semantics of the Nix language are fully described in the <link

     

       9
       9
       -
       xlink:href="http://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix manual</link>, but here we give a short overview of the most important constructs useful in NixOS configuration files.

     

       8
       8
       +
         The NixOS configuration file

     

       9
       9
       +
         <filename>/etc/nixos/configuration.nix</filename> is actually a <emphasis>Nix

     

       10
       10
       +
         expression</emphasis>, which is the Nix package manager’s purely functional

     

       11
       11
       +
         language for describing how to build packages and configurations. This means

     

       12
       12
       +
         you have all the expressive power of that language at your disposal,

     

       13
       13
       +
         including the ability to abstract over common patterns, which is very useful

     

       14
       14
       +
         when managing complex systems. The syntax and semantics of the Nix language

     

       15
       15
       +
         are fully described in the

     

       16
       16
       +
         <link

     

       17
       17
       +
       xlink:href="http://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix

     

       18
       18
       +
         manual</link>, but here we give a short overview of the most important

     

       19
       19
       +
         constructs useful in NixOS configuration files.

     

       10
       20
        
        </para>

     

       11
       21
        
        <xi:include href="config-file.xml" />

     

       12
       22
        
        <xi:include href="abstractions.xml" />

+5 -1

nixos/doc/manual/configuration/configuration.xml

···

       6
       6
        
        <title>Configuration</title>

     

       7
       7
        
        <partintro xml:id="ch-configuration-intro">

     

       8
       8
        
         <para>

     

       9
       9
       -
          This chapter describes how to configure various aspects of a NixOS machine through the configuration file <filename>/etc/nixos/configuration.nix</filename>. As described in <xref linkend="sec-changing-config" />, changes to this file only take effect after you run <command>nixos-rebuild</command>.

     

       9
       9
       +
          This chapter describes how to configure various aspects of a NixOS machine

     

       10
       10
       +
          through the configuration file

     

       11
       11
       +
          <filename>/etc/nixos/configuration.nix</filename>. As described in

     

       12
       12
       +
          <xref linkend="sec-changing-config" />, changes to this file only take

     

       13
       13
       +
          effect after you run <command>nixos-rebuild</command>.

     

       10
       14
        
         </para>

     

       11
       15
        
        </partintro>

     

       12
       16
        
        <xi:include href="config-syntax.xml" />

+46 -8

nixos/doc/manual/configuration/customizing-packages.xml

···

       6
       6
        
        <title>Customising Packages</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Some packages in Nixpkgs have options to enable or disable optional functionality or change other aspects of the package. For instance, the Firefox wrapper package (which provides Firefox with a set of plugins such as the Adobe Flash player) has an option to enable the Google Talk plugin. It can be set in <filename>configuration.nix</filename> as follows: <filename> nixpkgs.config.firefox.enableGoogleTalkPlugin = true; </filename>

     

       9
       9
       +
         Some packages in Nixpkgs have options to enable or disable optional

     

       10
       10
       +
         functionality or change other aspects of the package. For instance, the

     

       11
       11
       +
         Firefox wrapper package (which provides Firefox with a set of plugins such as

     

       12
       12
       +
         the Adobe Flash player) has an option to enable the Google Talk plugin. It

     

       13
       13
       +
         can be set in <filename>configuration.nix</filename> as follows: <filename>

     

       14
       14
       +
         nixpkgs.config.firefox.enableGoogleTalkPlugin = true; </filename>

     

       10
       15
        
        </para>

     

       11
       16
        
       

     

       12
       17
        
        <warning>

     

       13
       18
        
         <para>

     

       14
       14
       -
          Unfortunately, Nixpkgs currently lacks a way to query available configuration options.

     

       19
       19
       +
          Unfortunately, Nixpkgs currently lacks a way to query available

     

       20
       20
       +
          configuration options.

     

       15
       21
        
         </para>

     

       16
       22
        
        </warning>

     

       17
       23
        
       

     

       18
       24
        
        <para>

     

       19
       19
       -
         Apart from high-level options, it’s possible to tweak a package in almost arbitrary ways, such as changing or disabling dependencies of a package. For instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2. If you want to build it against GTK 3, you can specify that as follows:

     

       25
       25
       +
         Apart from high-level options, it’s possible to tweak a package in almost

     

       26
       26
       +
         arbitrary ways, such as changing or disabling dependencies of a package. For

     

       27
       27
       +
         instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2.

     

       28
       28
       +
         If you want to build it against GTK 3, you can specify that as follows:

     

       20
       29
        
       <programlisting>

     

       21
       30
        
       <xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];

     

       22
       31
        
       </programlisting>

     

       23
       23
       -
         The function <varname>override</varname> performs the call to the Nix function that produces Emacs, with the original arguments amended by the set of arguments specified by you. So here the function argument <varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing Emacs to depend on GTK 3. (The parentheses are necessary because in Nix, function application binds more weakly than list construction, so without them, <xref linkend="opt-environment.systemPackages"/> would be a list with two elements.)

     

       32
       32
       +
         The function <varname>override</varname> performs the call to the Nix

     

       33
       33
       +
         function that produces Emacs, with the original arguments amended by the set

     

       34
       34
       +
         of arguments specified by you. So here the function argument

     

       35
       35
       +
         <varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing

     

       36
       36
       +
         Emacs to depend on GTK 3. (The parentheses are necessary because in Nix,

     

       37
       37
       +
         function application binds more weakly than list construction, so without

     

       38
       38
       +
         them, <xref linkend="opt-environment.systemPackages"/> would be a list with

     

       39
       39
       +
         two elements.)

     

       24
       40
        
        </para>

     

       25
       41
        
       

     

       26
       42
        
        <para>

     

       27
       27
       -
         Even greater customisation is possible using the function <varname>overrideAttrs</varname>. While the <varname>override</varname> mechanism above overrides the arguments of a package function, <varname>overrideAttrs</varname> allows changing the <emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>. This permits changing any aspect of the package, such as the source code. For instance, if you want to override the source code of Emacs, you can say:

     

       43
       43
       +
         Even greater customisation is possible using the function

     

       44
       44
       +
         <varname>overrideAttrs</varname>. While the <varname>override</varname>

     

       45
       45
       +
         mechanism above overrides the arguments of a package function,

     

       46
       46
       +
         <varname>overrideAttrs</varname> allows changing the

     

       47
       47
       +
         <emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>.

     

       48
       48
       +
         This permits changing any aspect of the package, such as the source code. For

     

       49
       49
       +
         instance, if you want to override the source code of Emacs, you can say:

     

       28
       50
        
       <programlisting>

     

       29
       51
        
       <xref linkend="opt-environment.systemPackages"/> = [

     

       30
       52
        
         (pkgs.emacs.overrideAttrs (oldAttrs: {

     
···

       33
       55
        
         }))

     

       34
       56
        
       ];

     

       35
       57
        
       </programlisting>

     

       36
       36
       -
         Here, <varname>overrideAttrs</varname> takes the Nix derivation specified by <varname>pkgs.emacs</varname> and produces a new derivation in which the original’s <literal>name</literal> and <literal>src</literal> attribute have been replaced by the given values by re-calling <literal>stdenv.mkDerivation</literal>. The original attributes are accessible via the function argument, which is conventionally named <varname>oldAttrs</varname>.

     

       58
       58
       +
         Here, <varname>overrideAttrs</varname> takes the Nix derivation specified by

     

       59
       59
       +
         <varname>pkgs.emacs</varname> and produces a new derivation in which the

     

       60
       60
       +
         original’s <literal>name</literal> and <literal>src</literal> attribute

     

       61
       61
       +
         have been replaced by the given values by re-calling

     

       62
       62
       +
         <literal>stdenv.mkDerivation</literal>. The original attributes are

     

       63
       63
       +
         accessible via the function argument, which is conventionally named

     

       64
       64
       +
         <varname>oldAttrs</varname>.

     

       37
       65
        
        </para>

     

       38
       66
        
       

     

       39
       67
        
        <para>

     

       40
       40
       -
         The overrides shown above are not global. They do not affect the original package; other packages in Nixpkgs continue to depend on the original rather than the customised package. This means that if another package in your system depends on the original package, you end up with two instances of the package. If you want to have everything depend on your customised instance, you can apply a <emphasis>global</emphasis> override as follows:

     

       68
       68
       +
         The overrides shown above are not global. They do not affect the original

     

       69
       69
       +
         package; other packages in Nixpkgs continue to depend on the original rather

     

       70
       70
       +
         than the customised package. This means that if another package in your

     

       71
       71
       +
         system depends on the original package, you end up with two instances of the

     

       72
       72
       +
         package. If you want to have everything depend on your customised instance,

     

       73
       73
       +
         you can apply a <emphasis>global</emphasis> override as follows:

     

       41
       74
        
       <screen>

     

       42
       75
        
       nixpkgs.config.packageOverrides = pkgs:

     

       43
       76
        
         { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };

     

       44
       77
        
         };

     

       45
       78
        
       </screen>

     

       46
       46
       -
         The effect of this definition is essentially equivalent to modifying the <literal>emacs</literal> attribute in the Nixpkgs source tree. Any package in Nixpkgs that depends on <literal>emacs</literal> will be passed your customised instance. (However, the value <literal>pkgs.emacs</literal> in <varname>nixpkgs.config.packageOverrides</varname> refers to the original rather than overridden instance, to prevent an infinite recursion.)

     

       79
       79
       +
         The effect of this definition is essentially equivalent to modifying the

     

       80
       80
       +
         <literal>emacs</literal> attribute in the Nixpkgs source tree. Any package in

     

       81
       81
       +
         Nixpkgs that depends on <literal>emacs</literal> will be passed your

     

       82
       82
       +
         customised instance. (However, the value <literal>pkgs.emacs</literal> in

     

       83
       83
       +
         <varname>nixpkgs.config.packageOverrides</varname> refers to the original

     

       84
       84
       +
         rather than overridden instance, to prevent an infinite recursion.)

     

       47
       85
        
        </para>

     

       48
       86
        
       </section>

+17 -6

nixos/doc/manual/configuration/declarative-packages.xml

···

       6
       6
        
        <title>Declarative Package Management</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         With declarative package management, you specify which packages you want on your system by setting the option <xref linkend="opt-environment.systemPackages"/>. For instance, adding the following line to <filename>configuration.nix</filename> enables the Mozilla Thunderbird email application:

     

       9
       9
       +
         With declarative package management, you specify which packages you want on

     

       10
       10
       +
         your system by setting the option

     

       11
       11
       +
         <xref linkend="opt-environment.systemPackages"/>. For instance, adding the

     

       12
       12
       +
         following line to <filename>configuration.nix</filename> enables the Mozilla

     

       13
       13
       +
         Thunderbird email application:

     

       10
       14
        
       <programlisting>

     

       11
       15
        
       <xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];

     

       12
       16
        
       </programlisting>

     

       13
       13
       -
         The effect of this specification is that the Thunderbird package from Nixpkgs will be built or downloaded as part of the system when you run <command>nixos-rebuild switch</command>.

     

       17
       17
       +
         The effect of this specification is that the Thunderbird package from Nixpkgs

     

       18
       18
       +
         will be built or downloaded as part of the system when you run

     

       19
       19
       +
         <command>nixos-rebuild switch</command>.

     

       14
       20
        
        </para>

     

       15
       21
        
       

     

       16
       22
        
        <para>

     
···

       20
       26
        
       nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded

     

       21
       27
        
       <replaceable>...</replaceable>

     

       22
       28
        
       </screen>

     

       23
       23
       -
         The first column in the output is the <emphasis>attribute name</emphasis>, such as <literal>nixos.thunderbird</literal>.

     

       29
       29
       +
         The first column in the output is the <emphasis>attribute name</emphasis>,

     

       30
       30
       +
         such as <literal>nixos.thunderbird</literal>.

     

       24
       31
        
        </para>

     

       25
       25
       -
       

     

       26
       32
        
        <para>

     

       27
       27
       -
         Note: the <literal>nixos</literal> prefix tells us that we want to get the package from the <literal>nixos</literal> channel and works only in CLI tools. In declarative configuration use <literal>pkgs</literal> prefix (variable).

     

       33
       33
       +
         Note: the <literal>nixos</literal> prefix tells us that we want to get the

     

       34
       34
       +
         package from the <literal>nixos</literal> channel and works only in CLI tools.

     

       35
       35
       +
       

     

       36
       36
       +
         In declarative configuration use <literal>pkgs</literal> prefix (variable).

     

       28
       37
        
        </para>

     

       29
       38
        
       

     

       30
       39
        
        <para>

     

       31
       31
       -
         To “uninstall” a package, simply remove it from <xref linkend="opt-environment.systemPackages"/> and run <command>nixos-rebuild switch</command>.

     

       40
       40
       +
         To “uninstall” a package, simply remove it from

     

       41
       41
       +
         <xref linkend="opt-environment.systemPackages"/> and run

     

       42
       42
       +
         <command>nixos-rebuild switch</command>.

     

       32
       43
        
        </para>

     

       33
       44
        
       

     

       34
       45
        
        <xi:include href="customizing-packages.xml" />

+24 -4

nixos/doc/manual/configuration/file-systems.xml

···

       5
       5
        
                xml:id="ch-file-systems">

     

       6
       6
        
        <title>File Systems</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         You can define file systems using the <option>fileSystems</option> configuration option. For instance, the following definition causes NixOS to mount the Ext4 file system on device <filename>/dev/disk/by-label/data</filename> onto the mount point <filename>/data</filename>:

     

       8
       8
       +
         You can define file systems using the <option>fileSystems</option>

     

       9
       9
       +
         configuration option. For instance, the following definition causes NixOS to

     

       10
       10
       +
         mount the Ext4 file system on device

     

       11
       11
       +
         <filename>/dev/disk/by-label/data</filename> onto the mount point

     

       12
       12
       +
         <filename>/data</filename>:

     

       9
       13
        
       <programlisting>

     

       10
       14
        
       <xref linkend="opt-fileSystems"/>."/data" =

     

       11
       15
        
         { device = "/dev/disk/by-label/data";

     

       12
       16
        
           fsType = "ext4";

     

       13
       17
        
         };

     

       14
       18
        
       </programlisting>

     

       15
       15
       -
         Mount points are created automatically if they don’t already exist. For <option><link linkend="opt-fileSystems._name__.device">device</link></option>, it’s best to use the topology-independent device aliases in <filename>/dev/disk/by-label</filename> and <filename>/dev/disk/by-uuid</filename>, as these don’t change if the topology changes (e.g. if a disk is moved to another IDE controller).

     

       19
       19
       +
         Mount points are created automatically if they don’t already exist. For

     

       20
       20
       +
         <option><link linkend="opt-fileSystems._name__.device">device</link></option>,

     

       21
       21
       +
         it’s best to use the topology-independent device aliases in

     

       22
       22
       +
         <filename>/dev/disk/by-label</filename> and

     

       23
       23
       +
         <filename>/dev/disk/by-uuid</filename>, as these don’t change if the

     

       24
       24
       +
         topology changes (e.g. if a disk is moved to another IDE controller).

     

       16
       25
        
        </para>

     

       17
       26
        
        <para>

     

       18
       18
       -
         You can usually omit the file system type (<option><link linkend="opt-fileSystems._name__.fsType">fsType</link></option>), since <command>mount</command> can usually detect the type and load the necessary kernel module automatically. However, if the file system is needed at early boot (in the initial ramdisk) and is not <literal>ext2</literal>, <literal>ext3</literal> or <literal>ext4</literal>, then it’s best to specify <option>fsType</option> to ensure that the kernel module is available.

     

       27
       27
       +
         You can usually omit the file system type

     

       28
       28
       +
         (<option><link linkend="opt-fileSystems._name__.fsType">fsType</link></option>),

     

       29
       29
       +
         since <command>mount</command> can usually detect the type and load the

     

       30
       30
       +
         necessary kernel module automatically. However, if the file system is needed

     

       31
       31
       +
         at early boot (in the initial ramdisk) and is not <literal>ext2</literal>,

     

       32
       32
       +
         <literal>ext3</literal> or <literal>ext4</literal>, then it’s best to

     

       33
       33
       +
         specify <option>fsType</option> to ensure that the kernel module is

     

       34
       34
       +
         available.

     

       19
       35
        
        </para>

     

       20
       36
        
        <note>

     

       21
       37
        
         <para>

     

       22
       22
       -
          System startup will fail if any of the filesystems fails to mount, dropping you to the emergency shell. You can make a mount asynchronous and non-critical by adding <literal><link linkend="opt-fileSystems._name__.options">options</link> = [ "nofail" ];</literal>.

     

       38
       38
       +
          System startup will fail if any of the filesystems fails to mount, dropping

     

       39
       39
       +
          you to the emergency shell. You can make a mount asynchronous and

     

       40
       40
       +
          non-critical by adding

     

       41
       41
       +
          <literal><link linkend="opt-fileSystems._name__.options">options</link> = [

     

       42
       42
       +
          "nofail" ];</literal>.

     

       23
       43
        
         </para>

     

       24
       44
        
        </note>

     

       25
       45
        
        <xi:include href="luks-file-systems.xml" />

+11 -4

nixos/doc/manual/configuration/firewall.xml

···

       6
       6
        
        <title>Firewall</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         NixOS has a simple stateful firewall that blocks incoming connections and other unexpected packets. The firewall applies to both IPv4 and IPv6 traffic. It is enabled by default. It can be disabled as follows:

     

       9
       9
       +
         NixOS has a simple stateful firewall that blocks incoming connections and

     

       10
       10
       +
         other unexpected packets. The firewall applies to both IPv4 and IPv6 traffic.

     

       11
       11
       +
         It is enabled by default. It can be disabled as follows:

     

       10
       12
        
       <programlisting>

     

       11
       13
        
       <xref linkend="opt-networking.firewall.enable"/> = false;

     

       12
       14
        
       </programlisting>

     

       13
       13
       -
         If the firewall is enabled, you can open specific TCP ports to the outside world:

     

       15
       15
       +
         If the firewall is enabled, you can open specific TCP ports to the outside

     

       16
       16
       +
         world:

     

       14
       17
        
       <programlisting>

     

       15
       18
        
       <xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 443 ];

     

       16
       19
        
       </programlisting>

     

       17
       17
       -
         Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is enabled (<option><xref linkend="opt-services.openssh.enable"/> = true</option>). UDP ports can be opened through <xref linkend="opt-networking.firewall.allowedUDPPorts"/>.

     

       20
       20
       +
         Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is

     

       21
       21
       +
         enabled (<option><xref linkend="opt-services.openssh.enable"/> =

     

       22
       22
       +
         true</option>). UDP ports can be opened through

     

       23
       23
       +
         <xref linkend="opt-networking.firewall.allowedUDPPorts"/>.

     

       18
       24
        
        </para>

     

       19
       25
        
       

     

       20
       26
        
        <para>

     
···

       25
       31
        
         { from = 8000; to = 8010; }

     

       26
       32
        
       ];

     

       27
       33
        
       </programlisting>

     

       28
       28
       -
         Similarly, UDP port ranges can be opened through <xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>.

     

       34
       34
       +
         Similarly, UDP port ranges can be opened through

     

       35
       35
       +
         <xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>.

     

       29
       36
        
        </para>

     

       30
       37
        
       </section>

+11 -4

nixos/doc/manual/configuration/ipv4-config.xml

···

       6
       6
        
        <title>IPv4 Configuration</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         By default, NixOS uses DHCP (specifically, <command>dhcpcd</command>) to automatically configure network interfaces. However, you can configure an interface manually as follows:

     

       9
       9
       +
         By default, NixOS uses DHCP (specifically, <command>dhcpcd</command>) to

     

       10
       10
       +
         automatically configure network interfaces. However, you can configure an

     

       11
       11
       +
         interface manually as follows:

     

       10
       12
        
       <programlisting>

     

       11
       13
        
       <link linkend="opt-networking.interfaces._name__.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ {

     

       12
       14
        
         address = "192.168.1.2";

     

       13
       15
        
         prefixLength = 24;

     

       14
       16
        
       } ];

     

       15
       17
        
       </programlisting>

     

       16
       16
       -
         Typically you’ll also want to set a default gateway and set of name servers:

     

       18
       18
       +
         Typically you’ll also want to set a default gateway and set of name

     

       19
       19
       +
         servers:

     

       17
       20
        
       <programlisting>

     

       18
       21
        
       <xref linkend="opt-networking.defaultGateway"/> = "192.168.1.1";

     

       19
       22
        
       <xref linkend="opt-networking.nameservers"/> = [ "8.8.8.8" ];

     
···

       22
       25
        
       

     

       23
       26
        
        <note>

     

       24
       27
        
         <para>

     

       25
       25
       -
          Statically configured interfaces are set up by the systemd service <replaceable>interface-name</replaceable><literal>-cfg.service</literal>. The default gateway and name server configuration is performed by <literal>network-setup.service</literal>.

     

       28
       28
       +
          Statically configured interfaces are set up by the systemd service

     

       29
       29
       +
          <replaceable>interface-name</replaceable><literal>-cfg.service</literal>.

     

       30
       30
       +
          The default gateway and name server configuration is performed by

     

       31
       31
       +
          <literal>network-setup.service</literal>.

     

       26
       32
        
         </para>

     

       27
       33
        
        </note>

     

       28
       34
        
       

     
···

       31
       37
        
       <programlisting>

     

       32
       38
        
       <xref linkend="opt-networking.hostName"/> = "cartman";

     

       33
       39
        
       </programlisting>

     

       34
       34
       -
         The default host name is <literal>nixos</literal>. Set it to the empty string (<literal>""</literal>) to allow the DHCP server to provide the host name.

     

       40
       40
       +
         The default host name is <literal>nixos</literal>. Set it to the empty string

     

       41
       41
       +
         (<literal>""</literal>) to allow the DHCP server to provide the host name.

     

       35
       42
        
        </para>

     

       36
       43
        
       </section>

+9 -4

nixos/doc/manual/configuration/ipv6-config.xml

···

       6
       6
        
        <title>IPv6 Configuration</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         IPv6 is enabled by default. Stateless address autoconfiguration is used to automatically assign IPv6 addresses to all interfaces. You can disable IPv6 support globally by setting:

     

       9
       9
       +
         IPv6 is enabled by default. Stateless address autoconfiguration is used to

     

       10
       10
       +
         automatically assign IPv6 addresses to all interfaces. You can disable IPv6

     

       11
       11
       +
         support globally by setting:

     

       10
       12
        
       <programlisting>

     

       11
       13
        
       <xref linkend="opt-networking.enableIPv6"/> = false;

     

       12
       14
        
       </programlisting>

     

       13
       15
        
        </para>

     

       14
       16
        
       

     

       15
       17
        
        <para>

     

       16
       16
       -
         You can disable IPv6 on a single interface using a normal sysctl (in this example, we use interface <varname>eth0</varname>):

     

       18
       18
       +
         You can disable IPv6 on a single interface using a normal sysctl (in this

     

       19
       19
       +
         example, we use interface <varname>eth0</varname>):

     

       17
       20
        
       <programlisting>

     

       18
       21
        
       <xref linkend="opt-boot.kernel.sysctl"/>."net.ipv6.conf.eth0.disable_ipv6" = true;

     

       19
       22
        
       </programlisting>

     

       20
       23
        
        </para>

     

       21
       24
        
       

     

       22
       25
        
        <para>

     

       23
       23
       -
         As with IPv4 networking interfaces are automatically configured via DHCPv6. You can configure an interface manually:

     

       26
       26
       +
         As with IPv4 networking interfaces are automatically configured via DHCPv6.

     

       27
       27
       +
         You can configure an interface manually:

     

       24
       28
        
       <programlisting>

     

       25
       29
        
       <link linkend="opt-networking.interfaces._name__.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ {

     

       26
       30
        
         address = "fe00:aa:bb:cc::2";

     
···

       40
       44
        
        </para>

     

       41
       45
        
       

     

       42
       46
        
        <para>

     

       43
       43
       -
         See <xref linkend='sec-ipv4' /> for similar examples and additional information.

     

       47
       47
       +
         See <xref linkend='sec-ipv4' /> for similar examples and additional

     

       48
       48
       +
         information.

     

       44
       49
        
        </para>

     

       45
       50
        
       </section>

+62 -12

nixos/doc/manual/configuration/kubernetes.xml

···

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

     

       6
       6
        
        <title>Kubernetes</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         The NixOS Kubernetes module is a collective term for a handful of individual submodules implementing the Kubernetes cluster components.

     

       8
       8
       +
         The NixOS Kubernetes module is a collective term for a handful of individual

     

       9
       9
       +
         submodules implementing the Kubernetes cluster components.

     

       9
       10
        
        </para>

     

       10
       11
        
        <para>

     

       11
       11
       -
         There are generally two ways of enabling Kubernetes on NixOS. One way is to enable and configure cluster components appropriately by hand:

     

       12
       12
       +
         There are generally two ways of enabling Kubernetes on NixOS. One way is to

     

       13
       13
       +
         enable and configure cluster components appropriately by hand:

     

       12
       14
        
       <programlisting>

     

       13
       15
        
       services.kubernetes = {

     

       14
       16
        
         apiserver.enable = true;

     
···

       19
       21
        
         flannel.enable = true;

     

       20
       22
        
       };

     

       21
       23
        
       </programlisting>

     

       22
       22
       -
         Another way is to assign cluster roles ("master" and/or "node") to the host. This enables apiserver, controllerManager, scheduler, addonManager, kube-proxy and etcd:

     

       24
       24
       +
         Another way is to assign cluster roles ("master" and/or "node") to the host.

     

       25
       25
       +
         This enables apiserver, controllerManager, scheduler, addonManager,

     

       26
       26
       +
         kube-proxy and etcd:

     

       23
       27
        
       <programlisting>

     

       24
       28
        
       <xref linkend="opt-services.kubernetes.roles"/> = [ "master" ];

     

       25
       29
        
       </programlisting>

     
···

       27
       31
        
       <programlisting>

     

       28
       32
        
       <xref linkend="opt-services.kubernetes.roles"/> = [ "node" ];

     

       29
       33
        
       </programlisting>

     

       30
       30
       -
         Assigning both the master and node roles is usable if you want a single node Kubernetes cluster for dev or testing purposes:

     

       34
       34
       +
         Assigning both the master and node roles is usable if you want a single node

     

       35
       35
       +
         Kubernetes cluster for dev or testing purposes:

     

       31
       36
        
       <programlisting>

     

       32
       37
        
       <xref linkend="opt-services.kubernetes.roles"/> = [ "master" "node" ];

     

       33
       38
        
       </programlisting>

     

       34
       34
       -
         Note: Assigning either role will also default both <xref linkend="opt-services.kubernetes.flannel.enable"/> and <xref linkend="opt-services.kubernetes.easyCerts"/> to true. This sets up flannel as CNI and activates automatic PKI bootstrapping.

     

       39
       39
       +
         Note: Assigning either role will also default both

     

       40
       40
       +
         <xref linkend="opt-services.kubernetes.flannel.enable"/> and

     

       41
       41
       +
         <xref linkend="opt-services.kubernetes.easyCerts"/> to true. This sets up

     

       42
       42
       +
         flannel as CNI and activates automatic PKI bootstrapping.

     

       35
       43
        
        </para>

     

       36
       44
        
        <para>

     

       37
       37
       -
         As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have been disabled by default. While opening insecure ports is still possible, it is recommended not to bind these to other interfaces than loopback. To re-enable the insecure port on the apiserver, see options: <xref linkend="opt-services.kubernetes.apiserver.insecurePort"/> and <xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress"/>

     

       45
       45
       +
         As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports

     

       46
       46
       +
         on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have

     

       47
       47
       +
         been disabled by default. While opening insecure ports is still possible, it

     

       48
       48
       +
         is recommended not to bind these to other interfaces than loopback. To

     

       49
       49
       +
         re-enable the insecure port on the apiserver, see options:

     

       50
       50
       +
         <xref linkend="opt-services.kubernetes.apiserver.insecurePort"/> and

     

       51
       51
       +
         <xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress"/>

     

       38
       52
        
        </para>

     

       39
       53
        
        <note>

     

       40
       54
        
         <para>

     

       41
       41
       -
          As of NixOS 19.03, it is mandatory to configure: <xref linkend="opt-services.kubernetes.masterAddress"/>. The masterAddress must be resolveable and routeable by all cluster nodes. In single node clusters, this can be set to <literal>localhost</literal>.

     

       55
       55
       +
          As of NixOS 19.03, it is mandatory to configure:

     

       56
       56
       +
          <xref linkend="opt-services.kubernetes.masterAddress"/>. The masterAddress

     

       57
       57
       +
          must be resolveable and routeable by all cluster nodes. In single node

     

       58
       58
       +
          clusters, this can be set to <literal>localhost</literal>.

     

       42
       59
        
         </para>

     

       43
       60
        
        </note>

     

       44
       61
        
        <para>

     

       45
       45
       -
         Role-based access control (RBAC) authorization mode is enabled by default. This means that anonymous requests to the apiserver secure port will expectedly cause a permission denied error. All cluster components must therefore be configured with x509 certificates for two-way tls communication. The x509 certificate subject section determines the roles and permissions granted by the apiserver to perform clusterwide or namespaced operations. See also: <link

     

       46
       46
       -
            xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/"> Using RBAC Authorization</link>.

     

       62
       62
       +
         Role-based access control (RBAC) authorization mode is enabled by default.

     

       63
       63
       +
         This means that anonymous requests to the apiserver secure port will

     

       64
       64
       +
         expectedly cause a permission denied error. All cluster components must

     

       65
       65
       +
         therefore be configured with x509 certificates for two-way tls communication.

     

       66
       66
       +
         The x509 certificate subject section determines the roles and permissions

     

       67
       67
       +
         granted by the apiserver to perform clusterwide or namespaced operations. See

     

       68
       68
       +
         also:

     

       69
       69
       +
         <link

     

       70
       70
       +
            xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">

     

       71
       71
       +
         Using RBAC Authorization</link>.

     

       47
       72
        
        </para>

     

       48
       73
        
        <para>

     

       49
       49
       -
         The NixOS kubernetes module provides an option for automatic certificate bootstrapping and configuration, <xref linkend="opt-services.kubernetes.easyCerts"/>. The PKI bootstrapping process involves setting up a certificate authority (CA) daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert for the cluster, and uses the CA-cert for signing subordinate certs issued to each of the cluster components. Subsequently, the certmgr daemon monitors active certificates and renews them when needed. For single node Kubernetes clusters, setting <xref linkend="opt-services.kubernetes.easyCerts"/> = true is sufficient and no further action is required. For joining extra node machines to an existing cluster on the other hand, establishing initial trust is mandatory.

     

       74
       74
       +
         The NixOS kubernetes module provides an option for automatic certificate

     

       75
       75
       +
         bootstrapping and configuration,

     

       76
       76
       +
         <xref linkend="opt-services.kubernetes.easyCerts"/>. The PKI bootstrapping

     

       77
       77
       +
         process involves setting up a certificate authority (CA) daemon (cfssl) on

     

       78
       78
       +
         the kubernetes master node. cfssl generates a CA-cert for the cluster, and

     

       79
       79
       +
         uses the CA-cert for signing subordinate certs issued to each of the cluster

     

       80
       80
       +
         components. Subsequently, the certmgr daemon monitors active certificates and

     

       81
       81
       +
         renews them when needed. For single node Kubernetes clusters, setting

     

       82
       82
       +
         <xref linkend="opt-services.kubernetes.easyCerts"/> = true is sufficient and

     

       83
       83
       +
         no further action is required. For joining extra node machines to an existing

     

       84
       84
       +
         cluster on the other hand, establishing initial trust is mandatory.

     

       50
       85
        
        </para>

     

       51
       86
        
        <para>

     

       52
       52
       -
         To add new nodes to the cluster: On any (non-master) cluster node where <xref linkend="opt-services.kubernetes.easyCerts"/> is enabled, the helper script <literal>nixos-kubernetes-node-join</literal> is available on PATH. Given a token on stdin, it will copy the token to the kubernetes secrets directory and restart the certmgr service. As requested certificates are issued, the script will restart kubernetes cluster components as needed for them to pick up new keypairs.

     

       87
       87
       +
         To add new nodes to the cluster: On any (non-master) cluster node where

     

       88
       88
       +
         <xref linkend="opt-services.kubernetes.easyCerts"/> is enabled, the helper

     

       89
       89
       +
         script <literal>nixos-kubernetes-node-join</literal> is available on PATH.

     

       90
       90
       +
         Given a token on stdin, it will copy the token to the kubernetes secrets

     

       91
       91
       +
         directory and restart the certmgr service. As requested certificates are

     

       92
       92
       +
         issued, the script will restart kubernetes cluster components as needed for

     

       93
       93
       +
         them to pick up new keypairs.

     

       53
       94
        
        </para>

     

       54
       95
        
        <note>

     

       55
       96
        
         <para>

     
···

       57
       98
        
         </para>

     

       58
       99
        
        </note>

     

       59
       100
        
        <para>

     

       60
       60
       -
         In order to interact with an RBAC-enabled cluster as an administrator, one needs to have cluster-admin privileges. By default, when easyCerts is enabled, a cluster-admin kubeconfig file is generated and linked into <literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as determined by <xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig"/>. <literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal> will make kubectl use this kubeconfig to access and authenticate the cluster. The cluster-admin kubeconfig references an auto-generated keypair owned by root. Thus, only root on the kubernetes master may obtain cluster-admin rights by means of this file.

     

       101
       101
       +
         In order to interact with an RBAC-enabled cluster as an administrator, one

     

       102
       102
       +
         needs to have cluster-admin privileges. By default, when easyCerts is

     

       103
       103
       +
         enabled, a cluster-admin kubeconfig file is generated and linked into

     

       104
       104
       +
         <literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as determined by

     

       105
       105
       +
         <xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig"/>.

     

       106
       106
       +
         <literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal>

     

       107
       107
       +
         will make kubectl use this kubeconfig to access and authenticate the cluster.

     

       108
       108
       +
         The cluster-admin kubeconfig references an auto-generated keypair owned by

     

       109
       109
       +
         root. Thus, only root on the kubernetes master may obtain cluster-admin

     

       110
       110
       +
         rights by means of this file.

     

       61
       111
        
        </para>

     

       62
       112
        
       </chapter>

+44 -15

nixos/doc/manual/configuration/linux-kernel.xml

···

       5
       5
        
                xml:id="sec-kernel-config">

     

       6
       6
        
        <title>Linux Kernel</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         You can override the Linux kernel and associated packages using the option <option>boot.kernelPackages</option>. For instance, this selects the Linux 3.10 kernel:

     

       8
       8
       +
         You can override the Linux kernel and associated packages using the option

     

       9
       9
       +
         <option>boot.kernelPackages</option>. For instance, this selects the Linux

     

       10
       10
       +
         3.10 kernel:

     

       9
       11
        
       <programlisting>

     

       10
       12
        
       <xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxPackages_3_10;

     

       11
       13
        
       </programlisting>

     

       12
       12
       -
         Note that this not only replaces the kernel, but also packages that are specific to the kernel version, such as the NVIDIA video drivers. This ensures that driver packages are consistent with the kernel.

     

       14
       14
       +
         Note that this not only replaces the kernel, but also packages that are

     

       15
       15
       +
         specific to the kernel version, such as the NVIDIA video drivers. This

     

       16
       16
       +
         ensures that driver packages are consistent with the kernel.

     

       13
       17
        
        </para>

     

       14
       18
        
        <para>

     

       15
       15
       -
         The default Linux kernel configuration should be fine for most users. You can see the configuration of your current kernel with the following command:

     

       19
       19
       +
         The default Linux kernel configuration should be fine for most users. You can

     

       20
       20
       +
         see the configuration of your current kernel with the following command:

     

       16
       21
        
       <programlisting>

     

       17
       22
        
       zcat /proc/config.gz

     

       18
       23
        
       </programlisting>

     

       19
       19
       -
         If you want to change the kernel configuration, you can use the <option>packageOverrides</option> feature (see <xref

     

       20
       20
       -
       linkend="sec-customising-packages" />). For instance, to enable support for the kernel debugger KGDB:

     

       24
       24
       +
         If you want to change the kernel configuration, you can use the

     

       25
       25
       +
         <option>packageOverrides</option> feature (see

     

       26
       26
       +
         <xref

     

       27
       27
       +
       linkend="sec-customising-packages" />). For instance, to enable support

     

       28
       28
       +
         for the kernel debugger KGDB:

     

       21
       29
        
       <programlisting>

     

       22
       30
        
       nixpkgs.config.packageOverrides = pkgs:

     

       23
       31
        
         { linux_3_4 = pkgs.linux_3_4.override {

     
···

       28
       36
        
           };

     

       29
       37
        
         };

     

       30
       38
        
       </programlisting>

     

       31
       31
       -
         <varname>extraConfig</varname> takes a list of Linux kernel configuration options, one per line. The name of the option should not include the prefix <literal>CONFIG_</literal>. The option value is typically <literal>y</literal>, <literal>n</literal> or <literal>m</literal> (to build something as a kernel module).

     

       39
       39
       +
         <varname>extraConfig</varname> takes a list of Linux kernel configuration

     

       40
       40
       +
         options, one per line. The name of the option should not include the prefix

     

       41
       41
       +
         <literal>CONFIG_</literal>. The option value is typically

     

       42
       42
       +
         <literal>y</literal>, <literal>n</literal> or <literal>m</literal> (to build

     

       43
       43
       +
         something as a kernel module).

     

       32
       44
        
        </para>

     

       33
       45
        
        <para>

     

       34
       34
       -
         Kernel modules for hardware devices are generally loaded automatically by <command>udev</command>. You can force a module to be loaded via <xref linkend="opt-boot.kernelModules"/>, e.g.

     

       46
       46
       +
         Kernel modules for hardware devices are generally loaded automatically by

     

       47
       47
       +
         <command>udev</command>. You can force a module to be loaded via

     

       48
       48
       +
         <xref linkend="opt-boot.kernelModules"/>, e.g.

     

       35
       49
        
       <programlisting>

     

       36
       50
        
       <xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];

     

       37
       51
        
       </programlisting>

     

       38
       38
       -
         If the module is required early during the boot (e.g. to mount the root file system), you can use <xref linkend="opt-boot.initrd.kernelModules"/>:

     

       52
       52
       +
         If the module is required early during the boot (e.g. to mount the root file

     

       53
       53
       +
         system), you can use <xref linkend="opt-boot.initrd.kernelModules"/>:

     

       39
       54
        
       <programlisting>

     

       40
       55
        
       <xref linkend="opt-boot.initrd.kernelModules"/> = [ "cifs" ];

     

       41
       56
        
       </programlisting>

     

       42
       42
       -
         This causes the specified modules and their dependencies to be added to the initial ramdisk.

     

       57
       57
       +
         This causes the specified modules and their dependencies to be added to the

     

       58
       58
       +
         initial ramdisk.

     

       43
       59
        
        </para>

     

       44
       60
        
        <para>

     

       45
       45
       -
         Kernel runtime parameters can be set through <xref linkend="opt-boot.kernel.sysctl"/>, e.g.

     

       61
       61
       +
         Kernel runtime parameters can be set through

     

       62
       62
       +
         <xref linkend="opt-boot.kernel.sysctl"/>, e.g.

     

       46
       63
        
       <programlisting>

     

       47
       64
        
       <xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120;

     

       48
       65
        
       </programlisting>

     

       49
       49
       -
         sets the kernel’s TCP keepalive time to 120 seconds. To see the available parameters, run <command>sysctl -a</command>.

     

       66
       66
       +
         sets the kernel’s TCP keepalive time to 120 seconds. To see the available

     

       67
       67
       +
         parameters, run <command>sysctl -a</command>.

     

       50
       68
        
        </para>

     

       51
       69
        
        <section xml:id="sec-linux-config-customizing">

     

       52
       70
        
         <title>Customize your kernel</title>

     

       53
       71
        
       

     

       54
       72
        
         <para>

     

       55
       55
       -
          The first step before compiling the kernel is to generate an appropriate <literal>.config</literal> configuration. Either you pass your own config via the <literal>configfile</literal> setting of <literal>linuxManualConfig</literal>:

     

       73
       73
       +
          The first step before compiling the kernel is to generate an appropriate

     

       74
       74
       +
          <literal>.config</literal> configuration. Either you pass your own config

     

       75
       75
       +
          via the <literal>configfile</literal> setting of

     

       76
       76
       +
          <literal>linuxManualConfig</literal>:

     

       56
       77
        
       <screen><![CDATA[

     

       57
       78
        
         custom-kernel = super.linuxManualConfig {

     

       58
       79
        
           inherit (super) stdenv hostPlatform;

     
···

       63
       84
        
           allowImportFromDerivation = true;

     

       64
       85
        
         };

     

       65
       86
        
         ]]></screen>

     

       66
       66
       -
          You can edit the config with this snippet (by default <command>make menuconfig</command> won't work out of the box on nixos):

     

       87
       87
       +
          You can edit the config with this snippet (by default <command>make

     

       88
       88
       +
          menuconfig</command> won't work out of the box on nixos):

     

       67
       89
        
       <screen><![CDATA[

     

       68
       90
        
             nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkgconfig ncurses ];})'

     

       69
       91
        
         ]]></screen>

     

       70
       70
       -
          or you can let nixpkgs generate the configuration. Nixpkgs generates it via answering the interactive kernel utility <command>make config</command>. The answers depend on parameters passed to <filename>pkgs/os-specific/linux/kernel/generic.nix</filename> (which you can influence by overriding <literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>).

     

       92
       92
       +
          or you can let nixpkgs generate the configuration. Nixpkgs generates it via

     

       93
       93
       +
          answering the interactive kernel utility <command>make config</command>. The

     

       94
       94
       +
          answers depend on parameters passed to

     

       95
       95
       +
          <filename>pkgs/os-specific/linux/kernel/generic.nix</filename> (which you

     

       96
       96
       +
          can influence by overriding <literal>extraConfig, autoModules,

     

       97
       97
       +
          modDirVersion, preferBuiltin, extraConfig</literal>).

     

       71
       98
        
       <screen><![CDATA[

     

       72
       99
        
       

     

       73
       100
        
         mptcp93.override ({

     
···

       94
       121
        
         <title>Developing kernel modules</title>

     

       95
       122
        
       

     

       96
       123
        
         <para>

     

       97
       97
       -
          When developing kernel modules it's often convenient to run edit-compile-run loop as quickly as possible. See below snippet as an example of developing <literal>mellanox</literal> drivers.

     

       124
       124
       +
          When developing kernel modules it's often convenient to run edit-compile-run

     

       125
       125
       +
          loop as quickly as possible. See below snippet as an example of developing

     

       126
       126
       +
          <literal>mellanox</literal> drivers.

     

       98
       127
        
         </para>

     

       99
       128
        
       

     

       100
       129
        
       <screen><![CDATA[

+9 -3

nixos/doc/manual/configuration/luks-file-systems.xml

···

       6
       6
        
        <title>LUKS-Encrypted File Systems</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         NixOS supports file systems that are encrypted using <emphasis>LUKS</emphasis> (Linux Unified Key Setup). For example, here is how you create an encrypted Ext4 file system on the device <filename>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>:

     

       9
       9
       +
         NixOS supports file systems that are encrypted using

     

       10
       10
       +
         <emphasis>LUKS</emphasis> (Linux Unified Key Setup). For example, here is how

     

       11
       11
       +
         you create an encrypted Ext4 file system on the device

     

       12
       12
       +
         <filename>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>:

     

       10
       13
        
       <screen>

     

       11
       14
        
       # cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d

     

       12
       15
        
       

     
···

       23
       26
        
       

     

       24
       27
        
       # mkfs.ext4 /dev/mapper/crypted

     

       25
       28
        
       </screen>

     

       26
       26
       -
         To ensure that this file system is automatically mounted at boot time as <filename>/</filename>, add the following to <filename>configuration.nix</filename>:

     

       29
       29
       +
         To ensure that this file system is automatically mounted at boot time as

     

       30
       30
       +
         <filename>/</filename>, add the following to

     

       31
       31
       +
         <filename>configuration.nix</filename>:

     

       27
       32
        
       <programlisting>

     

       28
       33
        
       <link linkend="opt-boot.initrd.luks.devices._name__.device">boot.initrd.luks.devices.crypted.device</link> = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";

     

       29
       34
        
       <xref linkend="opt-fileSystems"/>."/".device = "/dev/mapper/crypted";

     

       30
       35
        
       </programlisting>

     

       31
       31
       -
         Should grub be used as bootloader, and <filename>/boot</filename> is located on an encrypted partition, it is necessary to add the following grub option:

     

       36
       36
       +
         Should grub be used as bootloader, and <filename>/boot</filename> is located

     

       37
       37
       +
         on an encrypted partition, it is necessary to add the following grub option:

     

       32
       38
        
       <programlisting><xref linkend="opt-boot.loader.grub.enableCryptodisk"/> = true;</programlisting>

     

       33
       39
        
        </para>

     

       34
       40
        
       </section>

+65 -8

nixos/doc/manual/configuration/matrix.xml

···

       5
       5
        
                xml:id="module-services-matrix">

     

       6
       6
        
        <title>Matrix</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         <link xlink:href="https://matrix.org/">Matrix</link> is an open standard for interoperable, decentralised, real-time communication over IP. It can be used to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things communication - or anywhere you need a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history.

     

       8
       8
       +
         <link xlink:href="https://matrix.org/">Matrix</link> is an open standard for

     

       9
       9
       +
         interoperable, decentralised, real-time communication over IP. It can be used

     

       10
       10
       +
         to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things

     

       11
       11
       +
         communication - or anywhere you need a standard HTTP API for publishing and

     

       12
       12
       +
         subscribing to data whilst tracking the conversation history.

     

       9
       13
        
        </para>

     

       10
       14
        
        <para>

     

       11
       11
       -
         This chapter will show you how to set up your own, self-hosted Matrix homeserver using the Synapse reference homeserver, and how to serve your own copy of the Riot web client. See the <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try Matrix Now!</link> overview page for links to Riot Apps for Android and iOS, desktop clients, as well as bridges to other networks and other projects around Matrix.

     

       15
       15
       +
         This chapter will show you how to set up your own, self-hosted Matrix

     

       16
       16
       +
         homeserver using the Synapse reference homeserver, and how to serve your own

     

       17
       17
       +
         copy of the Riot web client. See the

     

       18
       18
       +
         <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try

     

       19
       19
       +
         Matrix Now!</link> overview page for links to Riot Apps for Android and iOS,

     

       20
       20
       +
         desktop clients, as well as bridges to other networks and other projects

     

       21
       21
       +
         around Matrix.

     

       12
       22
        
        </para>

     

       13
       23
        
        <section xml:id="module-services-matrix-synapse">

     

       14
       24
        
         <title>Synapse Homeserver</title>

     

       15
       25
        
       

     

       16
       26
        
         <para>

     

       17
       17
       -
          <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link> is the reference homeserver implementation of Matrix from the core development team at matrix.org. The following configuration example will set up a synapse server for the <literal>example.org</literal> domain, served from the host <literal>myhostname.example.org</literal>. For more information, please refer to the <link xlink:href="https://github.com/matrix-org/synapse#synapse-installation"> installation instructions of Synapse </link>.

     

       27
       27
       +
          <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link> is

     

       28
       28
       +
          the reference homeserver implementation of Matrix from the core development

     

       29
       29
       +
          team at matrix.org. The following configuration example will set up a

     

       30
       30
       +
          synapse server for the <literal>example.org</literal> domain, served from

     

       31
       31
       +
          the host <literal>myhostname.example.org</literal>. For more information,

     

       32
       32
       +
          please refer to the

     

       33
       33
       +
          <link xlink:href="https://github.com/matrix-org/synapse#synapse-installation">

     

       34
       34
       +
          installation instructions of Synapse </link>.

     

       18
       35
        
       <programlisting>

     

       19
       36
        
       let

     

       20
       37
        
         fqdn =

     
···

       104
       121
        
         </para>

     

       105
       122
        
       

     

       106
       123
        
         <para>

     

       107
       107
       -
          If the <code>A</code> and <code>AAAA</code> DNS records on <literal>example.org</literal> do not point on the same host as the records for <code>myhostname.example.org</code>, you can easily move the <code>/.well-known</code> virtualHost section of the code to the host that is serving <literal>example.org</literal>, while the rest stays on <literal>myhostname.example.org</literal> with no other changes required. This pattern also allows to seamlessly move the homeserver from <literal>myhostname.example.org</literal> to <literal>myotherhost.example.org</literal> by only changing the <code>/.well-known</code> redirection target.

     

       124
       124
       +
          If the <code>A</code> and <code>AAAA</code> DNS records on

     

       125
       125
       +
          <literal>example.org</literal> do not point on the same host as the records

     

       126
       126
       +
          for <code>myhostname.example.org</code>, you can easily move the

     

       127
       127
       +
          <code>/.well-known</code> virtualHost section of the code to the host that

     

       128
       128
       +
          is serving <literal>example.org</literal>, while the rest stays on

     

       129
       129
       +
          <literal>myhostname.example.org</literal> with no other changes required.

     

       130
       130
       +
          This pattern also allows to seamlessly move the homeserver from

     

       131
       131
       +
          <literal>myhostname.example.org</literal> to

     

       132
       132
       +
          <literal>myotherhost.example.org</literal> by only changing the

     

       133
       133
       +
          <code>/.well-known</code> redirection target.

     

       108
       134
        
         </para>

     

       109
       135
        
       

     

       110
       136
        
         <para>

     

       111
       111
       -
          If you want to run a server with public registration by anybody, you can then enable <option>services.matrix-synapse.enable_registration = true;</option>. Otherwise, or you can generate a registration secret with <command>pwgen -s 64 1</command> and set it with <option>services.matrix-synapse.registration_shared_secret</option>. To create a new user or admin, run the following after you have set the secret and have rebuilt NixOS:

     

       137
       137
       +
          If you want to run a server with public registration by anybody, you can

     

       138
       138
       +
          then enable <option>services.matrix-synapse.enable_registration =

     

       139
       139
       +
          true;</option>. Otherwise, or you can generate a registration secret with

     

       140
       140
       +
          <command>pwgen -s 64 1</command> and set it with

     

       141
       141
       +
          <option>services.matrix-synapse.registration_shared_secret</option>. To

     

       142
       142
       +
          create a new user or admin, run the following after you have set the secret

     

       143
       143
       +
          and have rebuilt NixOS:

     

       112
       144
        
       <screen>

     

       113
       145
        
       <prompt>$ </prompt>nix run nixpkgs.matrix-synapse

     

       114
       146
        
       <prompt>$ </prompt>register_new_matrix_user -k <replaceable>your-registration-shared-secret</replaceable> http://localhost:8008

     
···

       118
       150
        
       <prompt>Make admin [no]:</prompt>

     

       119
       151
        
       Success!

     

       120
       152
        
       </screen>

     

       121
       121
       -
          In the example, this would create a user with the Matrix Identifier <literal>@your-username:example.org</literal>. Note that the registration secret ends up in the nix store and therefore is world-readable by any user on your machine, so it makes sense to only temporarily activate the <option>registration_shared_secret</option> option until a better solution for NixOS is in place.

     

       153
       153
       +
          In the example, this would create a user with the Matrix Identifier

     

       154
       154
       +
          <literal>@your-username:example.org</literal>. Note that the registration

     

       155
       155
       +
          secret ends up in the nix store and therefore is world-readable by any user

     

       156
       156
       +
          on your machine, so it makes sense to only temporarily activate the

     

       157
       157
       +
          <option>registration_shared_secret</option> option until a better solution

     

       158
       158
       +
          for NixOS is in place.

     

       122
       159
        
         </para>

     

       123
       160
        
        </section>

     

       124
       161
        
        <section xml:id="module-services-matrix-riot-web">

     

       125
       162
        
         <title>Riot Web Client</title>

     

       126
       163
        
       

     

       127
       164
        
         <para>

     

       128
       128
       -
          <link xlink:href="https://github.com/vector-im/riot-web/">Riot Web</link> is the reference web client for Matrix and developed by the core team at matrix.org. The following snippet can be optionally added to the code before to complete the synapse installation with a web client served at <code>https://riot.myhostname.example.org</code> and <code>https://riot.example.org</code>. Alternatively, you can use the hosted copy at <link xlink:href="https://riot.im/app">https://riot.im/app</link>, or use other web clients or native client applications. Due to the <literal>/.well-known</literal> urls set up done above, many clients should fill in the required connection details automatically when you enter your Matrix Identifier. See <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try Matrix Now!</link> for a list of existing clients and their supported featureset.

     

       165
       165
       +
          <link xlink:href="https://github.com/vector-im/riot-web/">Riot Web</link> is

     

       166
       166
       +
          the reference web client for Matrix and developed by the core team at

     

       167
       167
       +
          matrix.org. The following snippet can be optionally added to the code before

     

       168
       168
       +
          to complete the synapse installation with a web client served at

     

       169
       169
       +
          <code>https://riot.myhostname.example.org</code> and

     

       170
       170
       +
          <code>https://riot.example.org</code>. Alternatively, you can use the hosted

     

       171
       171
       +
          copy at <link xlink:href="https://riot.im/app">https://riot.im/app</link>,

     

       172
       172
       +
          or use other web clients or native client applications. Due to the

     

       173
       173
       +
          <literal>/.well-known</literal> urls set up done above, many clients should

     

       174
       174
       +
          fill in the required connection details automatically when you enter your

     

       175
       175
       +
          Matrix Identifier. See

     

       176
       176
       +
          <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try

     

       177
       177
       +
          Matrix Now!</link> for a list of existing clients and their supported

     

       178
       178
       +
          featureset.

     

       129
       179
        
       <programlisting>

     

       130
       180
        
       services.nginx.virtualHosts."riot.${fqdn}" = {

     

       131
       181
        
         enableACME = true;

     
···

       140
       190
        
         </para>

     

       141
       191
        
       

     

       142
       192
        
         <para>

     

       143
       143
       -
          Note that the Riot developers do not recommend running Riot and your Matrix homeserver on the same fully-qualified domain name for security reasons. In the example, this means that you should not reuse the <literal>myhostname.example.org</literal> virtualHost to also serve Riot, but instead serve it on a different subdomain, like <literal>riot.example.org</literal> in the example. See the <link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Riot Important Security Notes</link> for more information on this subject.

     

       193
       193
       +
          Note that the Riot developers do not recommend running Riot and your Matrix

     

       194
       194
       +
          homeserver on the same fully-qualified domain name for security reasons. In

     

       195
       195
       +
          the example, this means that you should not reuse the

     

       196
       196
       +
          <literal>myhostname.example.org</literal> virtualHost to also serve Riot,

     

       197
       197
       +
          but instead serve it on a different subdomain, like

     

       198
       198
       +
          <literal>riot.example.org</literal> in the example. See the

     

       199
       199
       +
          <link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Riot

     

       200
       200
       +
          Important Security Notes</link> for more information on this subject.

     

       144
       201
        
         </para>

     

       145
       202
        
        </section>

     

       146
       203
        
       </chapter>

+50 -13

nixos/doc/manual/configuration/modularity.xml

···

       6
       6
        
        <title>Modularity</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         The NixOS configuration mechanism is modular. If your <filename>configuration.nix</filename> becomes too big, you can split it into multiple files. Likewise, if you have multiple NixOS configurations (e.g. for different computers) with some commonality, you can move the common configuration into a shared file.

     

       9
       9
       +
         The NixOS configuration mechanism is modular. If your

     

       10
       10
       +
         <filename>configuration.nix</filename> becomes too big, you can split it into

     

       11
       11
       +
         multiple files. Likewise, if you have multiple NixOS configurations (e.g. for

     

       12
       12
       +
         different computers) with some commonality, you can move the common

     

       13
       13
       +
         configuration into a shared file.

     

       10
       14
        
        </para>

     

       11
       15
        
       

     

       12
       16
        
        <para>

     

       13
       13
       -
         Modules have exactly the same syntax as <filename>configuration.nix</filename>. In fact, <filename>configuration.nix</filename> is itself a module. You can use other modules by including them from <filename>configuration.nix</filename>, e.g.:

     

       17
       17
       +
         Modules have exactly the same syntax as

     

       18
       18
       +
         <filename>configuration.nix</filename>. In fact,

     

       19
       19
       +
         <filename>configuration.nix</filename> is itself a module. You can use other

     

       20
       20
       +
         modules by including them from <filename>configuration.nix</filename>, e.g.:

     

       14
       21
        
       <programlisting>

     

       15
       22
        
       { config, pkgs, ... }:

     

       16
       23
        
       

     
···

       20
       27
        
         <replaceable>...</replaceable>

     

       21
       28
        
       }

     

       22
       29
        
       </programlisting>

     

       23
       23
       -
         Here, we include two modules from the same directory, <filename>vpn.nix</filename> and <filename>kde.nix</filename>. The latter might look like this:

     

       30
       30
       +
         Here, we include two modules from the same directory,

     

       31
       31
       +
         <filename>vpn.nix</filename> and <filename>kde.nix</filename>. The latter

     

       32
       32
       +
         might look like this:

     

       24
       33
        
       <programlisting>

     

       25
       34
        
       { config, pkgs, ... }:

     

       26
       35
        
       

     
···

       29
       38
        
         <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;

     

       30
       39
        
       }

     

       31
       40
        
       </programlisting>

     

       32
       32
       -
         Note that both <filename>configuration.nix</filename> and <filename>kde.nix</filename> define the option <xref linkend="opt-environment.systemPackages"/>. When multiple modules define an option, NixOS will try to <emphasis>merge</emphasis> the definitions. In the case of <xref linkend="opt-environment.systemPackages"/>, that’s easy: the lists of packages can simply be concatenated. The value in <filename>configuration.nix</filename> is merged last, so for list-type options, it will appear at the end of the merged list. If you want it to appear first, you can use <varname>mkBefore</varname>:

     

       41
       41
       +
         Note that both <filename>configuration.nix</filename> and

     

       42
       42
       +
         <filename>kde.nix</filename> define the option

     

       43
       43
       +
         <xref linkend="opt-environment.systemPackages"/>. When multiple modules

     

       44
       44
       +
         define an option, NixOS will try to <emphasis>merge</emphasis> the

     

       45
       45
       +
         definitions. In the case of <xref linkend="opt-environment.systemPackages"/>,

     

       46
       46
       +
         that’s easy: the lists of packages can simply be concatenated. The value in

     

       47
       47
       +
         <filename>configuration.nix</filename> is merged last, so for list-type

     

       48
       48
       +
         options, it will appear at the end of the merged list. If you want it to

     

       49
       49
       +
         appear first, you can use <varname>mkBefore</varname>:

     

       33
       50
        
       <programlisting>

     

       34
       51
        
       <xref linkend="opt-boot.kernelModules"/> = mkBefore [ "kvm-intel" ];

     

       35
       52
        
       </programlisting>

     

       36
       36
       -
         This causes the <literal>kvm-intel</literal> kernel module to be loaded before any other kernel modules.

     

       53
       53
       +
         This causes the <literal>kvm-intel</literal> kernel module to be loaded

     

       54
       54
       +
         before any other kernel modules.

     

       37
       55
        
        </para>

     

       38
       56
        
       

     

       39
       57
        
        <para>

     

       40
       40
       -
         For other types of options, a merge may not be possible. For instance, if two modules define <xref linkend="opt-services.httpd.adminAddr"/>, <command>nixos-rebuild</command> will give an error:

     

       58
       58
       +
         For other types of options, a merge may not be possible. For instance, if two

     

       59
       59
       +
         modules define <xref linkend="opt-services.httpd.adminAddr"/>,

     

       60
       60
       +
         <command>nixos-rebuild</command> will give an error:

     

       41
       61
        
       <screen>

     

       42
       62
        
       The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.

     

       43
       63
        
       </screen>

     

       44
       44
       -
         When that happens, it’s possible to force one definition take precedence over the others:

     

       64
       64
       +
         When that happens, it’s possible to force one definition take precedence

     

       65
       65
       +
         over the others:

     

       45
       66
        
       <programlisting>

     

       46
       67
        
       <xref linkend="opt-services.httpd.adminAddr"/> = pkgs.lib.mkForce "bob@example.org";

     

       47
       68
        
       </programlisting>

     

       48
       69
        
        </para>

     

       49
       70
        
       

     

       50
       71
        
        <para>

     

       51
       51
       -
         When using multiple modules, you may need to access configuration values defined in other modules. This is what the <varname>config</varname> function argument is for: it contains the complete, merged system configuration. That is, <varname>config</varname> is the result of combining the configurations returned by every module

     

       72
       72
       +
         When using multiple modules, you may need to access configuration values

     

       73
       73
       +
         defined in other modules. This is what the <varname>config</varname> function

     

       74
       74
       +
         argument is for: it contains the complete, merged system configuration. That

     

       75
       75
       +
         is, <varname>config</varname> is the result of combining the configurations

     

       76
       76
       +
         returned by every module

     

       52
       77
        
         <footnote xml:id="footnote-nix-is-lazy">

     

       53
       78
        
          <para>

     

       54
       54
       -
           If you’re wondering how it’s possible that the (indirect) <emphasis>result</emphasis> of a function is passed as an <emphasis>input</emphasis> to that same function: that’s because Nix is a “lazy” language — it only computes values when they are needed. This works as long as no individual configuration value depends on itself.

     

       79
       79
       +
           If you’re wondering how it’s possible that the (indirect)

     

       80
       80
       +
           <emphasis>result</emphasis> of a function is passed as an

     

       81
       81
       +
           <emphasis>input</emphasis> to that same function: that’s because Nix is a

     

       82
       82
       +
           “lazy” language — it only computes values when they are needed. This

     

       83
       83
       +
           works as long as no individual configuration value depends on itself.

     

       55
       84
        
          </para>

     

       56
       85
        
         </footnote>

     

       57
       57
       -
         . For example, here is a module that adds some packages to <xref linkend="opt-environment.systemPackages"/> only if <xref linkend="opt-services.xserver.enable"/> is set to <literal>true</literal> somewhere else:

     

       86
       86
       +
         . For example, here is a module that adds some packages to

     

       87
       87
       +
         <xref linkend="opt-environment.systemPackages"/> only if

     

       88
       88
       +
         <xref linkend="opt-services.xserver.enable"/> is set to

     

       89
       89
       +
         <literal>true</literal> somewhere else:

     

       58
       90
        
       <programlisting>

     

       59
       91
        
       { config, pkgs, ... }:

     

       60
       92
        
       

     
···

       70
       102
        
        </para>

     

       71
       103
        
       

     

       72
       104
        
        <para>

     

       73
       73
       -
         With multiple modules, it may not be obvious what the final value of a configuration option is. The command <option>nixos-option</option> allows you to find out:

     

       105
       105
       +
         With multiple modules, it may not be obvious what the final value of a

     

       106
       106
       +
         configuration option is. The command <option>nixos-option</option> allows you

     

       107
       107
       +
         to find out:

     

       74
       108
        
       <screen>

     

       75
       109
        
       <prompt>$ </prompt>nixos-option <xref linkend="opt-services.xserver.enable"/>

     

       76
       110
        
       true

     
···

       78
       112
        
       <prompt>$ </prompt>nixos-option <xref linkend="opt-boot.kernelModules"/>

     

       79
       113
        
       [ "tun" "ipv6" "loop" <replaceable>...</replaceable> ]

     

       80
       114
        
       </screen>

     

       81
       81
       -
         Interactive exploration of the configuration is possible using <command>nix repl</command>, a read-eval-print loop for Nix expressions. A typical use:

     

       115
       115
       +
         Interactive exploration of the configuration is possible using <command>nix

     

       116
       116
       +
         repl</command>, a read-eval-print loop for Nix expressions. A typical use:

     

       82
       117
        
       <screen>

     

       83
       118
        
       <prompt>$ </prompt>nix repl '&lt;nixpkgs/nixos>'

     

       84
       119
        
       

     
···

       91
       126
        
        </para>

     

       92
       127
        
       

     

       93
       128
        
        <para>

     

       94
       94
       -
         While abstracting your configuration, you may find it useful to generate modules using code, instead of writing files. The example below would have the same effect as importing a file which sets those options.

     

       129
       129
       +
         While abstracting your configuration, you may find it useful to generate

     

       130
       130
       +
         modules using code, instead of writing files. The example below would have

     

       131
       131
       +
         the same effect as importing a file which sets those options.

     

       95
       132
        
       <programlisting>

     

       96
       133
        
       { config, pkgs, ... }:

     

       97
       134

+17 -5

nixos/doc/manual/configuration/network-manager.xml

···

       6
       6
        
        <title>NetworkManager</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         To facilitate network configuration, some desktop environments use NetworkManager. You can enable NetworkManager by setting:

     

       9
       9
       +
         To facilitate network configuration, some desktop environments use

     

       10
       10
       +
         NetworkManager. You can enable NetworkManager by setting:

     

       10
       11
        
       <programlisting>

     

       11
       12
        
       <xref linkend="opt-networking.networkmanager.enable"/> = true;

     

       12
       13
        
       </programlisting>

     

       13
       13
       -
         some desktop managers (e.g., GNOME) enable NetworkManager automatically for you.

     

       14
       14
       +
         some desktop managers (e.g., GNOME) enable NetworkManager automatically for

     

       15
       15
       +
         you.

     

       14
       16
        
        </para>

     

       15
       17
        
       

     

       16
       18
        
        <para>

     

       17
       17
       -
         All users that should have permission to change network settings must belong to the <code>networkmanager</code> group:

     

       19
       19
       +
         All users that should have permission to change network settings must belong

     

       20
       20
       +
         to the <code>networkmanager</code> group:

     

       18
       21
        
       <programlisting>

     

       19
       22
        
       <link linkend="opt-users.users._name__.extraGroups">users.users.alice.extraGroups</link> = [ "networkmanager" ];

     

       20
       23
        
       </programlisting>

     

       21
       24
        
        </para>

     

       22
       25
        
       

     

       23
       26
        
        <para>

     

       24
       24
       -
         NetworkManager is controlled using either <command>nmcli</command> or <command>nmtui</command> (curses-based terminal user interface). See their manual pages for details on their usage. Some desktop environments (GNOME, KDE) have their own configuration tools for NetworkManager. On XFCE, there is no configuration tool for NetworkManager by default: by adding <code>networkmanagerapplet</code> to the list of system packages, the graphical applet will be installed and will launch automatically when XFCE is starting (and will show in the status tray).

     

       27
       27
       +
         NetworkManager is controlled using either <command>nmcli</command> or

     

       28
       28
       +
         <command>nmtui</command> (curses-based terminal user interface). See their

     

       29
       29
       +
         manual pages for details on their usage. Some desktop environments (GNOME,

     

       30
       30
       +
         KDE) have their own configuration tools for NetworkManager. On XFCE, there is

     

       31
       31
       +
         no configuration tool for NetworkManager by default: by adding

     

       32
       32
       +
         <code>networkmanagerapplet</code> to the list of system packages, the

     

       33
       33
       +
         graphical applet will be installed and will launch automatically when XFCE is

     

       34
       34
       +
         starting (and will show in the status tray).

     

       25
       35
        
        </para>

     

       26
       36
        
       

     

       27
       37
        
        <note>

     

       28
       38
        
         <para>

     

       29
       29
       -
          <code>networking.networkmanager</code> and <code>networking.wireless</code> (WPA Supplicant) cannot be enabled at the same time: you can still connect to the wireless networks using NetworkManager.

     

       39
       39
       +
          <code>networking.networkmanager</code> and <code>networking.wireless</code>

     

       40
       40
       +
          (WPA Supplicant) cannot be enabled at the same time: you can still connect

     

       41
       41
       +
          to the wireless networks using NetworkManager.

     

       30
       42
        
         </para>

     

       31
       43
        
        </note>

     

       32
       44
        
       </section>

+2 -1

nixos/doc/manual/configuration/networking.xml

···

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

     

       6
       6
        
        <title>Networking</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         This section describes how to configure networking components on your NixOS machine.

     

       8
       8
       +
         This section describes how to configure networking components on your NixOS

     

       9
       9
       +
         machine.

     

       9
       10
        
        </para>

     

       10
       11
        
        <xi:include href="network-manager.xml" />

     

       11
       12
        
        <xi:include href="ssh.xml" />

+10 -3

nixos/doc/manual/configuration/package-mgmt.xml

···

       5
       5
        
                xml:id="sec-package-management">

     

       6
       6
        
        <title>Package Management</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         This section describes how to add additional packages to your system. NixOS has two distinct styles of package management:

     

       8
       8
       +
         This section describes how to add additional packages to your system. NixOS

     

       9
       9
       +
         has two distinct styles of package management:

     

       9
       10
        
         <itemizedlist>

     

       10
       11
        
          <listitem>

     

       11
       12
        
           <para>

     

       12
       12
       -
            <emphasis>Declarative</emphasis>, where you declare what packages you want in your <filename>configuration.nix</filename>. Every time you run <command>nixos-rebuild</command>, NixOS will ensure that you get a consistent set of binaries corresponding to your specification.

     

       13
       13
       +
            <emphasis>Declarative</emphasis>, where you declare what packages you want

     

       14
       14
       +
            in your <filename>configuration.nix</filename>. Every time you run

     

       15
       15
       +
            <command>nixos-rebuild</command>, NixOS will ensure that you get a

     

       16
       16
       +
            consistent set of binaries corresponding to your specification.

     

       13
       17
        
           </para>

     

       14
       18
        
          </listitem>

     

       15
       19
        
          <listitem>

     

       16
       20
        
           <para>

     

       17
       17
       -
            <emphasis>Ad hoc</emphasis>, where you install, upgrade and uninstall packages via the <command>nix-env</command> command. This style allows mixing packages from different Nixpkgs versions. It’s the only choice for non-root users.

     

       21
       21
       +
            <emphasis>Ad hoc</emphasis>, where you install, upgrade and uninstall

     

       22
       22
       +
            packages via the <command>nix-env</command> command. This style allows

     

       23
       23
       +
            mixing packages from different Nixpkgs versions. It’s the only choice

     

       24
       24
       +
            for non-root users.

     

       18
       25
        
           </para>

     

       19
       26
        
          </listitem>

     

       20
       27
        
         </itemizedlist>

+10 -3

nixos/doc/manual/configuration/profiles.xml

···

       5
       5
        
                xml:id="ch-profiles">

     

       6
       6
        
        <title>Profiles</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         In some cases, it may be desirable to take advantage of commonly-used, predefined configurations provided by nixpkgs, but different from those that come as default. This is a role fulfilled by NixOS's Profiles, which come as files living in <filename>&lt;nixpkgs/nixos/modules/profiles&gt;</filename>. That is to say, expected usage is to add them to the imports list of your <filename>/etc/configuration.nix</filename> as such:

     

       8
       8
       +
         In some cases, it may be desirable to take advantage of commonly-used,

     

       9
       9
       +
         predefined configurations provided by nixpkgs, but different from those that

     

       10
       10
       +
         come as default. This is a role fulfilled by NixOS's Profiles, which come as

     

       11
       11
       +
         files living in <filename>&lt;nixpkgs/nixos/modules/profiles&gt;</filename>.

     

       12
       12
       +
         That is to say, expected usage is to add them to the imports list of your

     

       13
       13
       +
         <filename>/etc/configuration.nix</filename> as such:

     

       9
       14
        
        </para>

     

       10
       15
        
       <programlisting>

     

       11
       16
        
         imports = [

     
···

       13
       18
        
         ];

     

       14
       19
        
       </programlisting>

     

       15
       20
        
        <para>

     

       16
       16
       -
         Even if some of these profiles seem only useful in the context of install media, many are actually intended to be used in real installs.

     

       21
       21
       +
         Even if some of these profiles seem only useful in the context of install

     

       22
       22
       +
         media, many are actually intended to be used in real installs.

     

       17
       23
        
        </para>

     

       18
       24
        
        <para>

     

       19
       19
       -
         What follows is a brief explanation on the purpose and use-case for each profile. Detailing each option configured by each one is out of scope.

     

       25
       25
       +
         What follows is a brief explanation on the purpose and use-case for each

     

       26
       26
       +
         profile. Detailing each option configured by each one is out of scope.

     

       20
       27
        
        </para>

     

       21
       28
        
        <xi:include href="profiles/all-hardware.xml" />

     

       22
       29
        
        <xi:include href="profiles/base.xml" />

+8 -2

nixos/doc/manual/configuration/profiles/all-hardware.xml

···

       6
       6
        
        <title>All Hardware</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Enables all hardware supported by NixOS: i.e., all firmware is included, and all devices from which one may boot are enabled in the initrd. Its primary use is in the NixOS installation CDs.

     

       9
       9
       +
         Enables all hardware supported by NixOS: i.e., all firmware is included, and

     

       10
       10
       +
         all devices from which one may boot are enabled in the initrd. Its primary

     

       11
       11
       +
         use is in the NixOS installation CDs.

     

       10
       12
        
        </para>

     

       11
       13
        
       

     

       12
       14
        
        <para>

     

       13
       13
       -
         The enabled kernel modules include support for SATA and PATA, SCSI (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and Hyper-V. Additionally, <xref linkend="opt-hardware.enableAllFirmware"/> is enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically installed.

     

       15
       15
       +
         The enabled kernel modules include support for SATA and PATA, SCSI

     

       16
       16
       +
         (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and

     

       17
       17
       +
         Hyper-V. Additionally, <xref linkend="opt-hardware.enableAllFirmware"/> is

     

       18
       18
       +
         enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically

     

       19
       19
       +
         installed.

     

       14
       20
        
        </para>

     

       15
       21
        
       </section>

+5 -1

nixos/doc/manual/configuration/profiles/base.xml

···

       6
       6
        
        <title>Base</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Defines the software packages included in the "minimal" installation CD. It installs several utilities useful in a simple recovery or install media, such as a text-mode web browser, and tools for manipulating block devices, networking, hardware diagnostics, and filesystems (with their respective kernel modules).

     

       9
       9
       +
         Defines the software packages included in the "minimal" installation CD. It

     

       10
       10
       +
         installs several utilities useful in a simple recovery or install media, such

     

       11
       11
       +
         as a text-mode web browser, and tools for manipulating block devices,

     

       12
       12
       +
         networking, hardware diagnostics, and filesystems (with their respective

     

       13
       13
       +
         kernel modules).

     

       10
       14
        
        </para>

     

       11
       15
        
       </section>

+8 -2

nixos/doc/manual/configuration/profiles/clone-config.xml

···

       6
       6
        
        <title>Clone Config</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         This profile is used in installer images. It provides an editable configuration.nix that imports all the modules that were also used when creating the image in the first place. As a result it allows users to edit and rebuild the live-system.

     

       9
       9
       +
         This profile is used in installer images. It provides an editable

     

       10
       10
       +
         configuration.nix that imports all the modules that were also used when

     

       11
       11
       +
         creating the image in the first place. As a result it allows users to edit

     

       12
       12
       +
         and rebuild the live-system.

     

       10
       13
        
        </para>

     

       11
       14
        
       

     

       12
       15
        
        <para>

     

       13
       13
       -
         On images where the installation media also becomes an installation target, copying over <literal>configuration.nix</literal> should be disabled by setting <literal>installer.cloneConfig</literal> to <literal>false</literal>. For example, this is done in <literal>sd-image-aarch64.nix</literal>.

     

       16
       16
       +
         On images where the installation media also becomes an installation target,

     

       17
       17
       +
         copying over <literal>configuration.nix</literal> should be disabled by

     

       18
       18
       +
         setting <literal>installer.cloneConfig</literal> to <literal>false</literal>.

     

       19
       19
       +
         For example, this is done in <literal>sd-image-aarch64.nix</literal>.

     

       14
       20
        
        </para>

     

       15
       21
        
       </section>

+5 -1

nixos/doc/manual/configuration/profiles/demo.xml

···

       6
       6
        
        <title>Demo</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         This profile just enables a <systemitem class="username">demo</systemitem> user, with password <literal>demo</literal>, uid <literal>1000</literal>, <systemitem class="groupname">wheel</systemitem> group and <link linkend="opt-services.xserver.displayManager.sddm.autoLogin"> autologin in the SDDM display manager</link>.

     

       9
       9
       +
         This profile just enables a <systemitem class="username">demo</systemitem>

     

       10
       10
       +
         user, with password <literal>demo</literal>, uid <literal>1000</literal>,

     

       11
       11
       +
         <systemitem class="groupname">wheel</systemitem> group and

     

       12
       12
       +
         <link linkend="opt-services.xserver.displayManager.sddm.autoLogin"> autologin

     

       13
       13
       +
         in the SDDM display manager</link>.

     

       10
       14
        
        </para>

     

       11
       15
        
       </section>

+6 -1

nixos/doc/manual/configuration/profiles/docker-container.xml

···

       6
       6
        
        <title>Docker Container</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         This is the profile from which the Docker images are generated. It prepares a working system by importing the <link linkend="sec-profile-minimal">Minimal</link> and <link linkend="sec-profile-clone-config">Clone Config</link> profiles, and setting appropriate configuration options that are useful inside a container context, like <xref linkend="opt-boot.isContainer"/>.

     

       9
       9
       +
         This is the profile from which the Docker images are generated. It prepares a

     

       10
       10
       +
         working system by importing the

     

       11
       11
       +
         <link linkend="sec-profile-minimal">Minimal</link> and

     

       12
       12
       +
         <link linkend="sec-profile-clone-config">Clone Config</link> profiles, and

     

       13
       13
       +
         setting appropriate configuration options that are useful inside a container

     

       14
       14
       +
         context, like <xref linkend="opt-boot.isContainer"/>.

     

       10
       15
        
        </para>

     

       11
       16
        
       </section>

+9 -2

nixos/doc/manual/configuration/profiles/graphical.xml

···

       6
       6
        
        <title>Graphical</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Defines a NixOS configuration with the Plasma 5 desktop. It's used by the graphical installation CD.

     

       9
       9
       +
         Defines a NixOS configuration with the Plasma 5 desktop. It's used by the

     

       10
       10
       +
         graphical installation CD.

     

       10
       11
        
        </para>

     

       11
       12
        
       

     

       12
       13
        
        <para>

     

       13
       13
       -
         It sets <xref linkend="opt-services.xserver.enable"/>, <xref linkend="opt-services.xserver.displayManager.sddm.enable"/>, <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> ( <link linkend="opt-services.xserver.desktopManager.plasma5.enableQt4Support"> without Qt4 Support</link>), and <xref linkend="opt-services.xserver.libinput.enable"/> to true. It also includes glxinfo and firefox in the system packages list.

     

       14
       14
       +
         It sets <xref linkend="opt-services.xserver.enable"/>,

     

       15
       15
       +
         <xref linkend="opt-services.xserver.displayManager.sddm.enable"/>,

     

       16
       16
       +
         <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> (

     

       17
       17
       +
         <link linkend="opt-services.xserver.desktopManager.plasma5.enableQt4Support">

     

       18
       18
       +
         without Qt4 Support</link>), and

     

       19
       19
       +
         <xref linkend="opt-services.xserver.libinput.enable"/> to true. It also

     

       20
       20
       +
         includes glxinfo and firefox in the system packages list.

     

       14
       21
        
        </para>

     

       15
       22
        
       </section>

+11 -3

nixos/doc/manual/configuration/profiles/hardened.xml

···

       6
       6
        
        <title>Hardened</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         A profile with most (vanilla) hardening options enabled by default, potentially at the cost of features and performance.

     

       9
       9
       +
         A profile with most (vanilla) hardening options enabled by default,

     

       10
       10
       +
         potentially at the cost of features and performance.

     

       10
       11
        
        </para>

     

       11
       12
        
       

     

       12
       13
        
        <para>

     

       13
       13
       -
         This includes a hardened kernel, and limiting the system information available to processes through the <filename>/sys</filename> and <filename>/proc</filename> filesystems. It also disables the User Namespaces feature of the kernel, which stops Nix from being able to build anything (this particular setting can be overriden via <xref linkend="opt-security.allowUserNamespaces"/>). See the <literal

     

       14
       14
       -
          xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix"> profile source</literal> for further detail on which settings are altered.

     

       14
       14
       +
         This includes a hardened kernel, and limiting the system information

     

       15
       15
       +
         available to processes through the <filename>/sys</filename> and

     

       16
       16
       +
         <filename>/proc</filename> filesystems. It also disables the User Namespaces

     

       17
       17
       +
         feature of the kernel, which stops Nix from being able to build anything

     

       18
       18
       +
         (this particular setting can be overriden via

     

       19
       19
       +
         <xref linkend="opt-security.allowUserNamespaces"/>). See the

     

       20
       20
       +
         <literal

     

       21
       21
       +
          xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix">

     

       22
       22
       +
         profile source</literal> for further detail on which settings are altered.

     

       15
       23
        
        </para>

     

       16
       24
        
       </section>

+5 -1

nixos/doc/manual/configuration/profiles/headless.xml

···

       10
       10
        
        </para>

     

       11
       11
        
       

     

       12
       12
        
        <para>

     

       13
       13
       -
         Disables <link linkend="opt-sound.enable">sound</link>, <link linkend="opt-boot.vesa">vesa</link>, serial consoles, <link linkend="opt-systemd.enableEmergencyMode">emergency mode</link>, <link linkend="opt-boot.loader.grub.splashImage">grub splash images</link> and configures the kernel to reboot automatically on panic.

     

       13
       13
       +
         Disables <link linkend="opt-sound.enable">sound</link>,

     

       14
       14
       +
         <link linkend="opt-boot.vesa">vesa</link>, serial consoles,

     

       15
       15
       +
         <link linkend="opt-systemd.enableEmergencyMode">emergency mode</link>,

     

       16
       16
       +
         <link linkend="opt-boot.loader.grub.splashImage">grub splash images</link>

     

       17
       17
       +
         and configures the kernel to reboot automatically on panic.

     

       14
       18
        
        </para>

     

       15
       19
        
       </section>

+19 -6

nixos/doc/manual/configuration/profiles/installation-device.xml

···

       6
       6
        
        <title>Installation Device</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Provides a basic configuration for installation devices like CDs. This enables redistributable firmware, includes the <link linkend="sec-profile-clone-config">Clone Config profile</link> and a copy of the Nixpkgs channel, so <command>nixos-install</command> works out of the box.

     

       9
       9
       +
         Provides a basic configuration for installation devices like CDs.

     

       10
       10
       +
         This enables redistributable firmware, includes the

     

       11
       11
       +
         <link linkend="sec-profile-clone-config">Clone Config profile</link>

     

       12
       12
       +
         and a copy of the Nixpkgs channel, so <command>nixos-install</command>

     

       13
       13
       +
         works out of the box.

     

       10
       14
        
        </para>

     

       11
       11
       -
       

     

       12
       15
        
        <para>

     

       13
       13
       -
         Documentation for <link linkend="opt-documentation.enable">Nixpkgs</link> and <link linkend="opt-documentation.nixos.enable">NixOS</link> are forcefully enabled (to override the <link linkend="sec-profile-minimal">Minimal profile</link> preference); the NixOS manual is shown automatically on TTY 8, udisks is disabled. Autologin is enabled as <literal>nixos</literal> user, while passwordless login as both <literal>root</literal> and <literal>nixos</literal> is possible. Passwordless <command>sudo</command> is enabled too. <link linkend="opt-networking.wireless.enable">wpa_supplicant</link> is enabled, but configured to not autostart.

     

       16
       16
       +
         Documentation for <link linkend="opt-documentation.enable">Nixpkgs</link>

     

       17
       17
       +
         and <link linkend="opt-documentation.nixos.enable">NixOS</link> are

     

       18
       18
       +
         forcefully enabled (to override the

     

       19
       19
       +
         <link linkend="sec-profile-minimal">Minimal profile</link> preference); the

     

       20
       20
       +
         NixOS manual is shown automatically on TTY 8, udisks is disabled.

     

       21
       21
       +
         Autologin is enabled as <literal>nixos</literal> user, while passwordless

     

       22
       22
       +
         login as both <literal>root</literal> and <literal>nixos</literal> is possible.

     

       23
       23
       +
         Passwordless <command>sudo</command> is enabled too.

     

       24
       24
       +
         <link linkend="opt-networking.wireless.enable">wpa_supplicant</link> is

     

       25
       25
       +
         enabled, but configured to not autostart.

     

       14
       26
        
        </para>

     

       15
       15
       -
       

     

       16
       27
        
        <para>

     

       17
       17
       -
         It is explained how to login, start the ssh server, and if available, how to start the display manager.

     

       28
       28
       +
         It is explained how to login, start the ssh server, and if available,

     

       29
       29
       +
         how to start the display manager.

     

       18
       30
        
        </para>

     

       19
       31
        
       

     

       20
       32
        
        <para>

     

       21
       21
       -
         Several settings are tweaked so that the installer has a better chance of succeeding under low-memory environments.

     

       33
       33
       +
         Several settings are tweaked so that the installer has a better chance of

     

       34
       34
       +
         succeeding under low-memory environments.

     

       22
       35
        
        </para>

     

       23
       36
        
       </section>

+7 -1

nixos/doc/manual/configuration/profiles/minimal.xml

···

       6
       6
        
        <title>Minimal</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         This profile defines a small NixOS configuration. It does not contain any graphical stuff. It's a very short file that enables <link linkend="opt-environment.noXlibs">noXlibs</link>, sets <link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link> to only support the user-selected locale, <link linkend="opt-documentation.enable">disables packages' documentation </link>, and <link linkend="opt-sound.enable">disables sound</link>.

     

       9
       9
       +
         This profile defines a small NixOS configuration. It does not contain any

     

       10
       10
       +
         graphical stuff. It's a very short file that enables

     

       11
       11
       +
         <link linkend="opt-environment.noXlibs">noXlibs</link>, sets

     

       12
       12
       +
         <link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link> to

     

       13
       13
       +
         only support the user-selected locale,

     

       14
       14
       +
         <link linkend="opt-documentation.enable">disables packages' documentation

     

       15
       15
       +
         </link>, and <link linkend="opt-sound.enable">disables sound</link>.

     

       10
       16
        
        </para>

     

       11
       17
        
       </section>

+5 -2

nixos/doc/manual/configuration/profiles/qemu-guest.xml

···

       6
       6
        
        <title>QEMU Guest</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         This profile contains common configuration for virtual machines running under QEMU (using virtio).

     

       9
       9
       +
         This profile contains common configuration for virtual machines running under

     

       10
       10
       +
         QEMU (using virtio).

     

       10
       11
        
        </para>

     

       11
       12
        
       

     

       12
       13
        
        <para>

     

       13
       13
       -
         It makes virtio modules available on the initrd, sets the system time from the hardware clock to work around a bug in qemu-kvm, and <link linkend="opt-security.rngd.enable">enables rngd</link>.

     

       14
       14
       +
         It makes virtio modules available on the initrd, sets the system time from

     

       15
       15
       +
         the hardware clock to work around a bug in qemu-kvm, and

     

       16
       16
       +
         <link linkend="opt-security.rngd.enable">enables rngd</link>.

     

       14
       17
        
        </para>

     

       15
       18
        
       </section>

+5 -2

nixos/doc/manual/configuration/ssh.xml

···

       10
       10
        
       <programlisting>

     

       11
       11
        
       <xref linkend="opt-services.openssh.enable"/> = true;

     

       12
       12
        
       </programlisting>

     

       13
       13
       -
         By default, root logins using a password are disallowed. They can be disabled entirely by setting <xref linkend="opt-services.openssh.permitRootLogin"/> to <literal>"no"</literal>.

     

       13
       13
       +
         By default, root logins using a password are disallowed. They can be disabled

     

       14
       14
       +
         entirely by setting <xref linkend="opt-services.openssh.permitRootLogin"/> to

     

       15
       15
       +
         <literal>"no"</literal>.

     

       14
       16
        
        </para>

     

       15
       17
        
       

     

       16
       18
        
        <para>

     

       17
       17
       -
         You can declaratively specify authorised RSA/DSA public keys for a user as follows:

     

       19
       19
       +
         You can declaratively specify authorised RSA/DSA public keys for a user as

     

       20
       20
       +
         follows:

     

       18
       21
        
       <!-- FIXME: this might not work if the user is unmanaged. -->

     

       19
       22
        
       <programlisting>

     

       20
       23
        
       <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.alice.openssh.authorizedKeys.keys</link> =

+6 -2

nixos/doc/manual/configuration/summary.xml

···

       6
       6
        
        <title>Syntax Summary</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Below is a summary of the most important syntactic constructs in the Nix expression language. It’s not complete. In particular, there are many other built-in functions. See the <link

     

       10
       10
       -
       xlink:href="http://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix manual</link> for the rest.

     

       9
       9
       +
         Below is a summary of the most important syntactic constructs in the Nix

     

       10
       10
       +
         expression language. It’s not complete. In particular, there are many other

     

       11
       11
       +
         built-in functions. See the

     

       12
       12
       +
         <link

     

       13
       13
       +
       xlink:href="http://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix

     

       14
       14
       +
         manual</link> for the rest.

     

       11
       15
        
        </para>

     

       12
       16
        
       

     

       13
       17
        
        <informaltable frame='none'>

+43 -10

nixos/doc/manual/configuration/user-mgmt.xml

···

       5
       5
        
                xml:id="sec-user-management">

     

       6
       6
        
        <title>User Management</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         NixOS supports both declarative and imperative styles of user management. In the declarative style, users are specified in <filename>configuration.nix</filename>. For instance, the following states that a user account named <literal>alice</literal> shall exist:

     

       8
       8
       +
         NixOS supports both declarative and imperative styles of user management. In

     

       9
       9
       +
         the declarative style, users are specified in

     

       10
       10
       +
         <filename>configuration.nix</filename>. For instance, the following states

     

       11
       11
       +
         that a user account named <literal>alice</literal> shall exist:

     

       9
       12
        
       <programlisting>

     

       10
       13
        
       <xref linkend="opt-users.users"/>.alice = {

     

       11
       14
        
         <link linkend="opt-users.users._name__.isNormalUser">isNormalUser</link> = true;

     
···

       15
       18
        
         <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ];

     

       16
       19
        
       };

     

       17
       20
        
       </programlisting>

     

       18
       18
       -
         Note that <literal>alice</literal> is a member of the <literal>wheel</literal> and <literal>networkmanager</literal> groups, which allows her to use <command>sudo</command> to execute commands as <literal>root</literal> and to configure the network, respectively. Also note the SSH public key that allows remote logins with the corresponding private key. Users created in this way do not have a password by default, so they cannot log in via mechanisms that require a password. However, you can use the <command>passwd</command> program to set a password, which is retained across invocations of <command>nixos-rebuild</command>.

     

       21
       21
       +
         Note that <literal>alice</literal> is a member of the

     

       22
       22
       +
         <literal>wheel</literal> and <literal>networkmanager</literal> groups, which

     

       23
       23
       +
         allows her to use <command>sudo</command> to execute commands as

     

       24
       24
       +
         <literal>root</literal> and to configure the network, respectively. Also note

     

       25
       25
       +
         the SSH public key that allows remote logins with the corresponding private

     

       26
       26
       +
         key. Users created in this way do not have a password by default, so they

     

       27
       27
       +
         cannot log in via mechanisms that require a password. However, you can use

     

       28
       28
       +
         the <command>passwd</command> program to set a password, which is retained

     

       29
       29
       +
         across invocations of <command>nixos-rebuild</command>.

     

       19
       30
        
        </para>

     

       20
       31
        
        <para>

     

       21
       21
       -
         If you set <xref linkend="opt-users.mutableUsers"/> to false, then the contents of <literal>/etc/passwd</literal> and <literal>/etc/group</literal> will be congruent to your NixOS configuration. For instance, if you remove a user from <xref linkend="opt-users.users"/> and run nixos-rebuild, the user account will cease to exist. Also, imperative commands for managing users and groups, such as useradd, are no longer available. Passwords may still be assigned by setting the user's <link linkend="opt-users.users._name__.hashedPassword">hashedPassword</link> option. A hashed password can be generated using <command>mkpasswd -m sha-512</command> after installing the <literal>mkpasswd</literal> package.

     

       32
       32
       +
         If you set <xref linkend="opt-users.mutableUsers"/> to false, then the

     

       33
       33
       +
         contents of <literal>/etc/passwd</literal> and <literal>/etc/group</literal>

     

       34
       34
       +
         will be congruent to your NixOS configuration. For instance, if you remove a

     

       35
       35
       +
         user from <xref linkend="opt-users.users"/> and run nixos-rebuild, the user

     

       36
       36
       +
         account will cease to exist. Also, imperative commands for managing users and

     

       37
       37
       +
         groups, such as useradd, are no longer available. Passwords may still be

     

       38
       38
       +
         assigned by setting the user's

     

       39
       39
       +
         <link linkend="opt-users.users._name__.hashedPassword">hashedPassword</link>

     

       40
       40
       +
         option. A hashed password can be generated using <command>mkpasswd -m

     

       41
       41
       +
         sha-512</command> after installing the <literal>mkpasswd</literal> package.

     

       22
       42
        
        </para>

     

       23
       43
        
        <para>

     

       24
       24
       -
         A user ID (uid) is assigned automatically. You can also specify a uid manually by adding

     

       44
       44
       +
         A user ID (uid) is assigned automatically. You can also specify a uid

     

       45
       45
       +
         manually by adding

     

       25
       46
        
       <programlisting>

     

       26
       47
        
       uid = 1000;

     

       27
       48
        
       </programlisting>

     

       28
       49
        
         to the user specification.

     

       29
       50
        
        </para>

     

       30
       51
        
        <para>

     

       31
       31
       -
         Groups can be specified similarly. The following states that a group named <literal>students</literal> shall exist:

     

       52
       52
       +
         Groups can be specified similarly. The following states that a group named

     

       53
       53
       +
         <literal>students</literal> shall exist:

     

       32
       54
        
       <programlisting>

     

       33
       55
        
       <xref linkend="opt-users.groups"/>.students.gid = 1000;

     

       34
       56
        
       </programlisting>

     

       35
       35
       -
         As with users, the group ID (gid) is optional and will be assigned automatically if it’s missing.

     

       57
       57
       +
         As with users, the group ID (gid) is optional and will be assigned

     

       58
       58
       +
         automatically if it’s missing.

     

       36
       59
        
        </para>

     

       37
       60
        
        <para>

     

       38
       38
       -
         In the imperative style, users and groups are managed by commands such as <command>useradd</command>, <command>groupmod</command> and so on. For instance, to create a user account named <literal>alice</literal>:

     

       61
       61
       +
         In the imperative style, users and groups are managed by commands such as

     

       62
       62
       +
         <command>useradd</command>, <command>groupmod</command> and so on. For

     

       63
       63
       +
         instance, to create a user account named <literal>alice</literal>:

     

       39
       64
        
       <screen>

     

       40
       65
        
       # useradd -m alice</screen>

     

       41
       41
       -
         To make all nix tools available to this new user use `su - USER` which opens a login shell (==shell that loads the profile) for given user. This will create the ~/.nix-defexpr symlink. So run:

     

       66
       66
       +
         To make all nix tools available to this new user use `su - USER` which opens

     

       67
       67
       +
         a login shell (==shell that loads the profile) for given user. This will

     

       68
       68
       +
         create the ~/.nix-defexpr symlink. So run:

     

       42
       69
        
       <screen>

     

       43
       70
        
       # su - alice -c "true"</screen>

     

       44
       44
       -
         The flag <option>-m</option> causes the creation of a home directory for the new user, which is generally what you want. The user does not have an initial password and therefore cannot log in. A password can be set using the <command>passwd</command> utility:

     

       71
       71
       +
         The flag <option>-m</option> causes the creation of a home directory for the

     

       72
       72
       +
         new user, which is generally what you want. The user does not have an initial

     

       73
       73
       +
         password and therefore cannot log in. A password can be set using the

     

       74
       74
       +
         <command>passwd</command> utility:

     

       45
       75
        
       <screen>

     

       46
       76
        
       # passwd alice

     

       47
       77
        
       Enter new UNIX password: ***

     
···

       50
       80
        
         A user can be deleted using <command>userdel</command>:

     

       51
       81
        
       <screen>

     

       52
       82
        
       # userdel -r alice</screen>

     

       53
       53
       -
         The flag <option>-r</option> deletes the user’s home directory. Accounts can be modified using <command>usermod</command>. Unix groups can be managed using <command>groupadd</command>, <command>groupmod</command> and <command>groupdel</command>.

     

       83
       83
       +
         The flag <option>-r</option> deletes the user’s home directory. Accounts

     

       84
       84
       +
         can be modified using <command>usermod</command>. Unix groups can be managed

     

       85
       85
       +
         using <command>groupadd</command>, <command>groupmod</command> and

     

       86
       86
       +
         <command>groupdel</command>.

     

       54
       87
        
        </para>

     

       55
       88
        
       </chapter>

+13 -5

nixos/doc/manual/configuration/wireless.xml

···

       6
       6
        
        <title>Wireless Networks</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         For a desktop installation using NetworkManager (e.g., GNOME), you just have to make sure the user is in the <code>networkmanager</code> group and you can skip the rest of this section on wireless networks.

     

       9
       9
       +
         For a desktop installation using NetworkManager (e.g., GNOME), you just have

     

       10
       10
       +
         to make sure the user is in the <code>networkmanager</code> group and you can

     

       11
       11
       +
         skip the rest of this section on wireless networks.

     

       10
       12
        
        </para>

     

       11
       13
        
       

     

       12
       14
        
        <para>

     
···

       23
       25
        
         "free.wifi" = {};

     

       24
       26
        
       };

     

       25
       27
        
       </programlisting>

     

       26
       26
       -
         Be aware that keys will be written to the nix store in plaintext! When no networks are set, it will default to using a configuration file at <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file yourself to define wireless networks, WPA keys and so on (see <citerefentry>

     

       28
       28
       +
         Be aware that keys will be written to the nix store in plaintext! When no

     

       29
       29
       +
         networks are set, it will default to using a configuration file at

     

       30
       30
       +
         <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file

     

       31
       31
       +
         yourself to define wireless networks, WPA keys and so on (see <citerefentry>

     

       27
       32
        
         <refentrytitle>wpa_supplicant.conf</refentrytitle>

     

       28
       33
        
         <manvolnum>5</manvolnum> </citerefentry>).

     

       29
       34
        
        </para>

     

       30
       35
        
       

     

       31
       36
        
        <para>

     

       32
       32
       -
         If you are using WPA2 you can generate pskRaw key using <command>wpa_passphrase</command>:

     

       37
       37
       +
         If you are using WPA2 you can generate pskRaw key using

     

       38
       38
       +
         <command>wpa_passphrase</command>:

     

       33
       39
        
       <screen>

     

       34
       40
        
       <prompt>$ </prompt>wpa_passphrase ESSID PSK

     

       35
       41
        
       network={

     
···

       45
       51
        
         };

     

       46
       52
        
       }

     

       47
       53
        
       </programlisting>

     

       48
       48
       -
         or you can use it to directly generate the <literal>wpa_supplicant.conf</literal>:

     

       54
       54
       +
         or you can use it to directly generate the

     

       55
       55
       +
         <literal>wpa_supplicant.conf</literal>:

     

       49
       56
        
       <screen>

     

       50
       57
        
       <prompt># </prompt>wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen>

     

       51
       51
       -
         After you have edited the <literal>wpa_supplicant.conf</literal>, you need to restart the wpa_supplicant service.

     

       58
       58
       +
         After you have edited the <literal>wpa_supplicant.conf</literal>, you need to

     

       59
       59
       +
         restart the wpa_supplicant service.

     

       52
       60
        
       <screen>

     

       53
       61
        
       <prompt># </prompt>systemctl restart wpa_supplicant.service</screen>

     

       54
       62
        
        </para>

+111 -40

nixos/doc/manual/configuration/x-windows.xml

···

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

     

       6
       6
        
        <title>X Window System</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         The X Window System (X11) provides the basis of NixOS’ graphical user interface. It can be enabled as follows:

     

       8
       8
       +
         The X Window System (X11) provides the basis of NixOS’ graphical user

     

       9
       9
       +
         interface. It can be enabled as follows:

     

       9
       10
        
       <programlisting>

     

       10
       11
        
       <xref linkend="opt-services.xserver.enable"/> = true;

     

       11
       12
        
       </programlisting>

     

       12
       12
       -
         The X server will automatically detect and use the appropriate video driver from a set of X.org drivers (such as <literal>vesa</literal> and <literal>intel</literal>). You can also specify a driver manually, e.g.

     

       13
       13
       +
         The X server will automatically detect and use the appropriate video driver

     

       14
       14
       +
         from a set of X.org drivers (such as <literal>vesa</literal> and

     

       15
       15
       +
         <literal>intel</literal>). You can also specify a driver manually, e.g.

     

       13
       16
        
       <programlisting>

     

       14
       17
        
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "r128" ];

     

       15
       18
        
       </programlisting>

     

       16
       19
        
         to enable X.org’s <literal>xf86-video-r128</literal> driver.

     

       17
       20
        
        </para>

     

       18
       21
        
        <para>

     

       19
       19
       -
         You also need to enable at least one desktop or window manager. Otherwise, you can only log into a plain undecorated <command>xterm</command> window. Thus you should pick one or more of the following lines:

     

       22
       22
       +
         You also need to enable at least one desktop or window manager. Otherwise,

     

       23
       23
       +
         you can only log into a plain undecorated <command>xterm</command> window.

     

       24
       24
       +
         Thus you should pick one or more of the following lines:

     

       20
       25
        
       <programlisting>

     

       21
       26
        
       <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;

     

       22
       27
        
       <xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true;

     
···

       29
       34
        
       </programlisting>

     

       30
       35
        
        </para>

     

       31
       36
        
        <para>

     

       32
       32
       -
         NixOS’s default <emphasis>display manager</emphasis> (the program that provides a graphical login prompt and manages the X server) is LightDM. You can select an alternative one by picking one of the following lines:

     

       37
       37
       +
         NixOS’s default <emphasis>display manager</emphasis> (the program that

     

       38
       38
       +
         provides a graphical login prompt and manages the X server) is LightDM. You

     

       39
       39
       +
         can select an alternative one by picking one of the following lines:

     

       33
       40
        
       <programlisting>

     

       34
       41
        
       <xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;

     

       35
       42
        
       <xref linkend="opt-services.xserver.displayManager.slim.enable"/> = true;

     
···

       43
       50
        
       </programlisting>

     

       44
       51
        
        </para>

     

       45
       52
        
        <para>

     

       46
       46
       -
         The X server is started automatically at boot time. If you don’t want this to happen, you can set:

     

       53
       53
       +
         The X server is started automatically at boot time. If you don’t want this

     

       54
       54
       +
         to happen, you can set:

     

       47
       55
        
       <programlisting>

     

       48
       56
        
       <xref linkend="opt-services.xserver.autorun"/> = false;

     

       49
       57
        
       </programlisting>

     
···

       53
       61
        
       </screen>

     

       54
       62
        
        </para>

     

       55
       63
        
        <para>

     

       56
       56
       -
         On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine, you should also set the following:

     

       64
       64
       +
         On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine,

     

       65
       65
       +
         you should also set the following:

     

       57
       66
        
       <programlisting>

     

       58
       67
        
       <xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true;

     

       59
       68
        
       </programlisting>

     
···

       61
       70
        
        <simplesect xml:id="sec-x11-auto-login">

     

       62
       71
        
         <title>Auto-login</title>

     

       63
       72
        
         <para>

     

       64
       64
       -
          The x11 login screen can be skipped entirely, automatically logging you into your window manager and desktop environment when you boot your computer.

     

       73
       73
       +
         The x11 login screen can be skipped entirely, automatically logging you into

     

       74
       74
       +
         your window manager and desktop environment when you boot your computer.

     

       65
       75
        
         </para>

     

       66
       76
        
         <para>

     

       67
       67
       -
          This is especially helpful if you have disk encryption enabled. Since you already have to provide a password to decrypt your disk, entering a second password to login can be redundant.

     

       77
       77
       +
         This is especially helpful if you have disk encryption enabled. Since you

     

       78
       78
       +
         already have to provide a password to decrypt your disk, entering a second

     

       79
       79
       +
         password to login can be redundant.

     

       68
       80
        
         </para>

     

       69
       81
        
         <para>

     

       70
       70
       -
          To enable auto-login, you need to define your default window manager and desktop environment. If you wanted no desktop environment and i3 as your your window manager, you'd define:

     

       82
       82
       +
         To enable auto-login, you need to define your default window manager and

     

       83
       83
       +
         desktop environment. If you wanted no desktop environment and i3 as your your

     

       84
       84
       +
         window manager, you'd define:

     

       71
       85
        
       <programlisting>

     

       72
       86
        
       <xref linkend="opt-services.xserver.desktopManager.default"/> = "none";

     

       73
       87
        
       <xref linkend="opt-services.xserver.windowManager.default"/> = "i3";

     

       74
       88
        
       </programlisting>

     

       75
       75
       -
          And, finally, to enable auto-login for a user <literal>johndoe</literal>:

     

       89
       89
       +
         And, finally, to enable auto-login for a user <literal>johndoe</literal>:

     

       76
       90
        
       <programlisting>

     

       77
       91
        
       <xref linkend="opt-services.xserver.displayManager.auto.enable"/> = true;

     

       78
       92
        
       <xref linkend="opt-services.xserver.displayManager.auto.user"/> = "johndoe";

     
···

       82
       96
        
        <simplesect xml:id="sec-x11-graphics-cards-nvidia">

     

       83
       97
        
         <title>Proprietary NVIDIA drivers</title>

     

       84
       98
        
         <para>

     

       85
       85
       -
          NVIDIA provides a proprietary driver for its graphics cards that has better 3D performance than the X.org drivers. It is not enabled by default because it’s not free software. You can enable it as follows:

     

       99
       99
       +
          NVIDIA provides a proprietary driver for its graphics cards that has better

     

       100
       100
       +
          3D performance than the X.org drivers. It is not enabled by default because

     

       101
       101
       +
          it’s not free software. You can enable it as follows:

     

       86
       102
        
       <programlisting>

     

       87
       103
        
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidia" ];

     

       88
       104
        
       </programlisting>

     
···

       93
       109
        
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ];

     

       94
       110
        
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy173" ];

     

       95
       111
        
       </programlisting>

     

       96
       96
       -
          You may need to reboot after enabling this driver to prevent a clash with other kernel modules.

     

       112
       112
       +
          You may need to reboot after enabling this driver to prevent a clash with

     

       113
       113
       +
          other kernel modules.

     

       97
       114
        
         </para>

     

       98
       115
        
        </simplesect>

     

       99
       116
        
        <simplesect xml:id="sec-x11--graphics-cards-amd">

     

       100
       117
        
         <title>Proprietary AMD drivers</title>

     

       101
       118
        
         <para>

     

       102
       102
       -
          AMD provides a proprietary driver for its graphics cards that has better 3D performance than the X.org drivers. It is not enabled by default because it’s not free software. You can enable it as follows:

     

       119
       119
       +
          AMD provides a proprietary driver for its graphics cards that has better 3D

     

       120
       120
       +
          performance than the X.org drivers. It is not enabled by default because

     

       121
       121
       +
          it’s not free software. You can enable it as follows:

     

       103
       122
        
       <programlisting>

     

       104
       123
        
       <xref linkend="opt-services.xserver.videoDrivers"/> = [ "ati_unfree" ];

     

       105
       124
        
       </programlisting>

     

       106
       106
       -
          You will need to reboot after enabling this driver to prevent a clash with other kernel modules.

     

       125
       125
       +
          You will need to reboot after enabling this driver to prevent a clash with

     

       126
       126
       +
          other kernel modules.

     

       107
       127
        
         </para>

     

       108
       128
        
         <note>

     

       109
       109
       -
          <para>

     

       110
       110
       -
           For recent AMD GPUs you most likely want to keep either the defaults or <literal>"amdgpu"</literal> (both free).

     

       111
       111
       -
          </para>

     

       129
       129
       +
         <para>

     

       130
       130
       +
          For recent AMD GPUs you most likely want to keep either the defaults

     

       131
       131
       +
          or <literal>"amdgpu"</literal> (both free).

     

       132
       132
       +
         </para>

     

       112
       133
        
         </note>

     

       113
       134
        
        </simplesect>

     

       114
       135
        
        <simplesect xml:id="sec-x11-touchpads">

     

       115
       136
        
         <title>Touchpads</title>

     

       116
       137
        
         <para>

     

       117
       117
       -
          Support for Synaptics touchpads (found in many laptops such as the Dell Latitude series) can be enabled as follows:

     

       138
       138
       +
          Support for Synaptics touchpads (found in many laptops such as the Dell

     

       139
       139
       +
          Latitude series) can be enabled as follows:

     

       118
       140
        
       <programlisting>

     

       119
       141
        
       <xref linkend="opt-services.xserver.libinput.enable"/> = true;

     

       120
       142
        
       </programlisting>

     

       121
       121
       -
          The driver has many options (see <xref linkend="ch-options"/>). For instance, the following disables tap-to-click behavior:

     

       143
       143
       +
          The driver has many options (see <xref linkend="ch-options"/>). For

     

       144
       144
       +
          instance, the following disables tap-to-click behavior:

     

       122
       145
        
       <programlisting>

     

       123
       146
        
       <xref linkend="opt-services.xserver.libinput.tapping"/> = false;

     

       124
       147
        
       </programlisting>

     

       125
       125
       -
          Note: the use of <literal>services.xserver.synaptics</literal> is deprecated since NixOS 17.09.

     

       148
       148
       +
          Note: the use of <literal>services.xserver.synaptics</literal> is deprecated

     

       149
       149
       +
          since NixOS 17.09.

     

       126
       150
        
         </para>

     

       127
       151
        
        </simplesect>

     

       128
       152
        
        <simplesect xml:id="sec-x11-gtk-and-qt-themes">

     

       129
       153
        
         <title>GTK/Qt themes</title>

     

       130
       154
        
         <para>

     

       131
       131
       -
          GTK themes can be installed either to user profile or system-wide (via <literal>environment.systemPackages</literal>). To make Qt 5 applications look similar to GTK2 ones, you can install <literal>qt5.qtbase.gtk</literal> package into your system environment. It should work for all Qt 5 library versions.

     

       155
       155
       +
          GTK themes can be installed either to user profile or system-wide (via

     

       156
       156
       +
          <literal>environment.systemPackages</literal>). To make Qt 5 applications

     

       157
       157
       +
          look similar to GTK2 ones, you can install <literal>qt5.qtbase.gtk</literal>

     

       158
       158
       +
          package into your system environment. It should work for all Qt 5 library

     

       159
       159
       +
          versions.

     

       132
       160
        
         </para>

     

       133
       161
        
        </simplesect>

     

       134
       162
        
        <simplesect xml:id="custom-xkb-layouts">

     

       135
       163
        
         <title>Custom XKB layouts</title>

     

       136
       164
        
         <para>

     

       137
       137
       -
          It is possible to install custom <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension"> XKB </link> keyboard layouts using the option <option> <link linkend="opt-services.xserver.extraLayouts"> services.xserver.extraLayouts </link> </option>. As a first example, we are going to create a layout based on the basic US layout, with an additional layer to type some greek symbols by pressing the right-alt key.

     

       165
       165
       +
          It is possible to install custom

     

       166
       166
       +
          <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension">

     

       167
       167
       +
           XKB

     

       168
       168
       +
          </link>

     

       169
       169
       +
          keyboard layouts using the option

     

       170
       170
       +
          <option>

     

       171
       171
       +
           <link linkend="opt-services.xserver.extraLayouts">

     

       172
       172
       +
            services.xserver.extraLayouts

     

       173
       173
       +
           </link>

     

       174
       174
       +
          </option>.

     

       175
       175
       +
          As a first example, we are going to create a layout based on the basic US

     

       176
       176
       +
          layout, with an additional layer to type some greek symbols by pressing the

     

       177
       177
       +
          right-alt key.

     

       138
       178
        
         </para>

     

       139
       179
        
         <para>

     

       140
       140
       -
          To do this we are going to create a <literal>us-greek</literal> file with a <literal>xkb_symbols</literal> section.

     

       180
       180
       +
          To do this we are going to create a <literal>us-greek</literal> file

     

       181
       181
       +
          with a <literal>xkb_symbols</literal> section.

     

       141
       182
        
         </para>

     

       142
       183
        
       <programlisting>

     

       143
       184
        
       xkb_symbols &quot;us-greek&quot;

     
···

       153
       194
        
       };

     

       154
       195
        
       </programlisting>

     

       155
       196
        
         <para>

     

       156
       156
       -
          To install the layout, the filepath, a description and the list of languages must be given:

     

       197
       197
       +
          To install the layout, the filepath, a description and the list of

     

       198
       198
       +
          languages must be given:

     

       157
       199
        
         </para>

     

       158
       200
        
       <programlisting>

     

       159
       201
        
       <xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = {

     
···

       163
       205
        
       }

     

       164
       206
        
       </programlisting>

     

       165
       207
        
         <note>

     

       166
       166
       -
          <para>

     

       167
       167
       -
           The name should match the one given to the <literal>xkb_symbols</literal> block.

     

       168
       168
       -
          </para>

     

       208
       208
       +
         <para>

     

       209
       209
       +
          The name should match the one given to the

     

       210
       210
       +
          <literal>xkb_symbols</literal> block.

     

       211
       211
       +
         </para>

     

       169
       212
        
         </note>

     

       170
       213
        
         <para>

     

       171
       171
       -
          The layout should now be installed and ready to use: try it by running <literal>setxkbmap us-greek</literal> and type <literal>&lt;alt&gt;+a</literal>. To change the default the usual <option> <link linkend="opt-services.xserver.layout"> services.xserver.layout </link> </option> option can still be used.

     

       214
       214
       +
          The layout should now be installed and ready to use: try it by

     

       215
       215
       +
          running <literal>setxkbmap us-greek</literal> and type

     

       216
       216
       +
          <literal>&lt;alt&gt;+a</literal>. To change the default the usual

     

       217
       217
       +
          <option>

     

       218
       218
       +
           <link linkend="opt-services.xserver.layout">

     

       219
       219
       +
            services.xserver.layout

     

       220
       220
       +
           </link>

     

       221
       221
       +
          </option>

     

       222
       222
       +
          option can still be used.

     

       172
       223
        
         </para>

     

       173
       224
        
         <para>

     

       174
       174
       -
          A layout can have several other components besides <literal>xkb_symbols</literal>, for example we will define new keycodes for some multimedia key and bind these to some symbol.

     

       225
       225
       +
          A layout can have several other components besides

     

       226
       226
       +
          <literal>xkb_symbols</literal>, for example we will define new

     

       227
       227
       +
          keycodes for some multimedia key and bind these to some symbol.

     

       175
       228
        
         </para>

     

       176
       229
        
         <para>

     

       177
       177
       -
          Use the <emphasis>xev</emphasis> utility from <literal>pkgs.xorg.xev</literal> to find the codes of the keys of interest, then create a <literal>media-key</literal> file to hold the keycodes definitions

     

       230
       230
       +
          Use the <emphasis>xev</emphasis> utility from

     

       231
       231
       +
          <literal>pkgs.xorg.xev</literal> to find the codes of the keys of

     

       232
       232
       +
          interest, then create a <literal>media-key</literal> file to hold

     

       233
       233
       +
          the keycodes definitions

     

       178
       234
        
         </para>

     

       179
       235
        
       <programlisting>

     

       180
       236
        
       xkb_keycodes &quot;media&quot;

     
···

       184
       240
        
       }

     

       185
       241
        
       </programlisting>

     

       186
       242
        
         <para>

     

       187
       187
       -
          Now use the newly define keycodes in <literal>media-sym</literal>:

     

       243
       243
       +
           Now use the newly define keycodes in <literal>media-sym</literal>:

     

       188
       244
        
         </para>

     

       189
       245
        
       <programlisting>

     

       190
       246
        
       xkb_symbols &quot;media&quot;

     
···

       195
       251
        
       }

     

       196
       252
        
       </programlisting>

     

       197
       253
        
         <para>

     

       198
       198
       -
          As before, to install the layout do

     

       254
       254
       +
           As before, to install the layout do

     

       199
       255
        
         </para>

     

       200
       256
        
       <programlisting>

     

       201
       257
        
       <xref linkend="opt-services.xserver.extraLayouts"/>.media = {

     
···

       206
       262
        
       };

     

       207
       263
        
       </programlisting>

     

       208
       264
        
         <note>

     

       209
       209
       -
          <para>

     

       210
       210
       -
           The function <literal>pkgs.writeText &lt;filename&gt; &lt;content&gt; </literal> can be useful if you prefer to keep the layout definitions inside the NixOS configuration.

     

       211
       211
       -
          </para>

     

       265
       265
       +
         <para>

     

       266
       266
       +
          The function <literal>pkgs.writeText &lt;filename&gt; &lt;content&gt;

     

       267
       267
       +
          </literal> can be useful if you prefer to keep the layout definitions

     

       268
       268
       +
          inside the NixOS configuration.

     

       269
       269
       +
         </para>

     

       212
       270
        
         </note>

     

       213
       271
        
         <para>

     

       214
       214
       -
          Unfortunately, the Xorg server does not (currently) support setting a keymap directly but relies instead on XKB rules to select the matching components (keycodes, types, ...) of a layout. This means that components other than symbols won't be loaded by default. As a workaround, you can set the keymap using <literal>setxkbmap</literal> at the start of the session with:

     

       272
       272
       +
           Unfortunately, the Xorg server does not (currently) support setting a

     

       273
       273
       +
           keymap directly but relies instead on XKB rules to select the matching

     

       274
       274
       +
           components (keycodes, types, ...) of a layout. This means that components

     

       275
       275
       +
           other than symbols won't be loaded by default. As a workaround, you

     

       276
       276
       +
           can set the keymap using <literal>setxkbmap</literal> at the start of the

     

       277
       277
       +
           session with:

     

       215
       278
        
         </para>

     

       216
       279
        
       <programlisting>

     

       217
       280
        
       <xref linkend="opt-services.xserver.displayManager.sessionCommands"/> = "setxkbmap -keycodes media";

     

       218
       281
        
       </programlisting>

     

       219
       282
        
         <para>

     

       220
       220
       -
          If you are manually starting the X server, you should set the argument <literal>-xkbdir /etc/X11/xkb</literal>, otherwise X won't find your layout files. For example with <command>xinit</command> run

     

       221
       221
       -
       <screen><prompt>$ </prompt>xinit -- -xkbdir /etc/X11/xkb</screen>

     

       283
       283
       +
           If you are manually starting the X server, you should set the argument

     

       284
       284
       +
           <literal>-xkbdir /etc/X11/xkb</literal>, otherwise X won't find your layout files.

     

       285
       285
       +
           For example with <command>xinit</command> run

     

       286
       286
       +
           <screen><prompt>$ </prompt>xinit -- -xkbdir /etc/X11/xkb</screen>

     

       222
       287
        
         </para>

     

       223
       288
        
         <para>

     

       224
       224
       -
          To learn how to write layouts take a look at the XKB <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts"> documentation </link>. More example layouts can also be found <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples"> here </link>.

     

       289
       289
       +
          To learn how to write layouts take a look at the XKB

     

       290
       290
       +
         <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts">

     

       291
       291
       +
          documentation

     

       292
       292
       +
         </link>. More example layouts can also be found

     

       293
       293
       +
         <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples">

     

       294
       294
       +
          here

     

       295
       295
       +
         </link>.

     

       225
       296
        
         </para>

     

       226
       226
       -
        </simplesect>

     

       297
       297
       +
       </simplesect>

     

       227
       298
        
       </chapter>

+16 -5

nixos/doc/manual/configuration/xfce.xml

···

       14
       14
        
       </programlisting>

     

       15
       15
        
        </para>

     

       16
       16
        
        <para>

     

       17
       17
       -
         Optionally, <emphasis>compton</emphasis> can be enabled for nice graphical effects, some example settings:

     

       17
       17
       +
         Optionally, <emphasis>compton</emphasis> can be enabled for nice graphical

     

       18
       18
       +
         effects, some example settings:

     

       18
       19
        
       <programlisting>

     

       19
       20
        
       <link linkend="opt-services.compton.enable">services.compton</link> = {

     

       20
       21
        
         <link linkend="opt-services.compton.enable">enable</link>          = true;

     
···

       26
       27
        
       </programlisting>

     

       27
       28
        
        </para>

     

       28
       29
        
        <para>

     

       29
       29
       -
         Some Xfce programs are not installed automatically. To install them manually (system wide), put them into your <xref linkend="opt-environment.systemPackages"/>.

     

       30
       30
       +
         Some Xfce programs are not installed automatically. To install them manually

     

       31
       31
       +
         (system wide), put them into your

     

       32
       32
       +
         <xref linkend="opt-environment.systemPackages"/>.

     

       30
       33
        
        </para>

     

       31
       34
        
        <simplesect xml:id="sec-xfce-thunar-volumes">

     

       32
       35
        
         <title>Thunar Volume Support</title>

     
···

       41
       44
        
        <simplesect xml:id="sec-xfce-polkit">

     

       42
       45
        
         <title>Polkit Authentication Agent</title>

     

       43
       46
        
         <para>

     

       44
       44
       -
          There is no authentication agent automatically installed alongside Xfce. To allow mounting of local (non-removable) filesystems, you will need to install one. Installing <emphasis>polkit_gnome</emphasis>, a rebuild, logout and login did the trick.

     

       47
       47
       +
          There is no authentication agent automatically installed alongside Xfce. To

     

       48
       48
       +
          allow mounting of local (non-removable) filesystems, you will need to

     

       49
       49
       +
          install one. Installing <emphasis>polkit_gnome</emphasis>, a rebuild, logout

     

       50
       50
       +
          and login did the trick.

     

       45
       51
        
         </para>

     

       46
       52
        
        </simplesect>

     

       47
       53
        
        <simplesect xml:id="sec-xfce-troubleshooting">

     

       48
       54
        
         <title>Troubleshooting</title>

     

       49
       55
        
         <para>

     

       50
       50
       -
          Even after enabling udisks2, volume management might not work. Thunar and/or the desktop takes time to show up. Thunar will spit out this kind of message on start (look at <command>journalctl --user -b</command>).

     

       56
       56
       +
          Even after enabling udisks2, volume management might not work. Thunar and/or

     

       57
       57
       +
          the desktop takes time to show up. Thunar will spit out this kind of message

     

       58
       58
       +
          on start (look at <command>journalctl --user -b</command>).

     

       51
       59
        
       <programlisting>

     

       52
       60
        
       Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported

     

       53
       61
        
       </programlisting>

     

       54
       54
       -
          This is caused by some needed GNOME services not running. This is all fixed by enabling "Launch GNOME services on startup" in the Advanced tab of the Session and Startup settings panel. Alternatively, you can run this command to do the same thing.

     

       62
       62
       +
          This is caused by some needed GNOME services not running. This is all fixed

     

       63
       63
       +
          by enabling "Launch GNOME services on startup" in the Advanced tab of the

     

       64
       64
       +
          Session and Startup settings panel. Alternatively, you can run this command

     

       65
       65
       +
          to do the same thing.

     

       55
       66
        
       <programlisting>

     

       56
       67
        
       <prompt>$ </prompt>xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true

     

       57
       68
        
       </programlisting>

+15 -3

nixos/doc/manual/development/assertions.xml

···

       6
       6
        
        <title>Warnings and Assertions</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         When configuration problems are detectable in a module, it is a good idea to write an assertion or warning. Doing so provides clear feedback to the user and prevents errors after the build.

     

       9
       9
       +
         When configuration problems are detectable in a module, it is a good idea to

     

       10
       10
       +
         write an assertion or warning. Doing so provides clear feedback to the user

     

       11
       11
       +
         and prevents errors after the build.

     

       10
       12
        
        </para>

     

       11
       13
        
       

     

       12
       14
        
        <para>

     

       13
       13
       -
         Although Nix has the <literal>abort</literal> and <literal>builtins.trace</literal> <link xlink:href="https://nixos.org/nix/manual/#ssec-builtins">functions</link> to perform such tasks, they are not ideally suited for NixOS modules. Instead of these functions, you can declare your warnings and assertions using the NixOS module system.

     

       15
       15
       +
         Although Nix has the <literal>abort</literal> and

     

       16
       16
       +
         <literal>builtins.trace</literal>

     

       17
       17
       +
         <link xlink:href="https://nixos.org/nix/manual/#ssec-builtins">functions</link>

     

       18
       18
       +
         to perform such tasks, they are not ideally suited for NixOS modules. Instead

     

       19
       19
       +
         of these functions, you can declare your warnings and assertions using the

     

       20
       20
       +
         NixOS module system.

     

       14
       21
        
        </para>

     

       15
       22
        
       

     

       16
       23
        
        <section xml:id="sec-assertions-warnings">

     
···

       41
       48
        
         <title>Assertions</title>

     

       42
       49
        
       

     

       43
       50
        
         <para>

     

       44
       44
       -
          This example, extracted from the <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix"> <literal>syslogd</literal> module </link> shows how to use <literal>assertions</literal>. Since there can only be one active syslog daemon at a time, an assertion is useful to prevent such a broken system from being built.

     

       51
       51
       +
          This example, extracted from the

     

       52
       52
       +
          <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix">

     

       53
       53
       +
          <literal>syslogd</literal> module </link> shows how to use

     

       54
       54
       +
          <literal>assertions</literal>. Since there can only be one active syslog

     

       55
       55
       +
          daemon at a time, an assertion is useful to prevent such a broken system

     

       56
       56
       +
          from being built.

     

       45
       57
        
         </para>

     

       46
       58
        
       

     

       47
       59
        
       <programlisting>

+8 -3

nixos/doc/manual/development/building-nixos.xml

···

       5
       5
        
               xml:id="sec-building-cd">

     

       6
       6
        
        <title>Building Your Own NixOS CD</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         Building a NixOS CD is as easy as configuring your own computer. The idea is to use another module which will replace your <filename>configuration.nix</filename> to configure the system that would be installed on the CD.

     

       8
       8
       +
         Building a NixOS CD is as easy as configuring your own computer. The idea is

     

       9
       9
       +
         to use another module which will replace your

     

       10
       10
       +
         <filename>configuration.nix</filename> to configure the system that would be

     

       11
       11
       +
         installed on the CD.

     

       9
       12
        
        </para>

     

       10
       13
        
        <para>

     

       11
       11
       -
         Default CD/DVD configurations are available inside <filename>nixos/modules/installer/cd-dvd</filename>.

     

       14
       14
       +
         Default CD/DVD configurations are available inside

     

       15
       15
       +
         <filename>nixos/modules/installer/cd-dvd</filename>.

     

       12
       16
        
       <screen>

     

       13
       17
        
       <prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs.git

     

       14
       18
        
       <prompt>$ </prompt>cd nixpkgs/nixos

     

       15
       19
        
       <prompt>$ </prompt>nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix</screen>

     

       16
       20
        
        </para>

     

       17
       21
        
        <para>

     

       18
       18
       -
         Before burning your CD/DVD, you can check the content of the image by mounting anywhere like suggested by the following command:

     

       22
       22
       +
         Before burning your CD/DVD, you can check the content of the image by

     

       23
       23
       +
         mounting anywhere like suggested by the following command:

     

       19
       24
        
       <screen>

     

       20
       25
        
       <prompt># </prompt>mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>

     

       21
       26
        
        </para>

+23 -8

nixos/doc/manual/development/building-parts.xml

···

       5
       5
        
               xml:id="sec-building-parts">

     

       6
       6
        
        <title>Building Specific Parts of NixOS</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         With the command <command>nix-build</command>, you can build specific parts of your NixOS configuration. This is done as follows:

     

       8
       8
       +
         With the command <command>nix-build</command>, you can build specific parts

     

       9
       9
       +
         of your NixOS configuration. This is done as follows:

     

       9
       10
        
       <screen>

     

       10
       11
        
       <prompt>$ </prompt>cd <replaceable>/path/to/nixpkgs/nixos</replaceable>

     

       11
       12
        
       <prompt>$ </prompt>nix-build -A config.<replaceable>option</replaceable></screen>

     

       12
       12
       -
         where <replaceable>option</replaceable> is a NixOS option with type “derivation” (i.e. something that can be built). Attributes of interest include:

     

       13
       13
       +
         where <replaceable>option</replaceable> is a NixOS option with type

     

       14
       14
       +
         “derivation” (i.e. something that can be built). Attributes of interest

     

       15
       15
       +
         include:

     

       13
       16
        
         <variablelist>

     

       14
       17
        
          <varlistentry>

     

       15
       18
        
           <term>

     
···

       17
       20
        
           </term>

     

       18
       21
        
           <listitem>

     

       19
       22
        
            <para>

     

       20
       20
       -
             The top-level option that builds the entire NixOS system. Everything else in your configuration is indirectly pulled in by this option. This is what <command>nixos-rebuild</command> builds and what <filename>/run/current-system</filename> points to afterwards.

     

       23
       23
       +
             The top-level option that builds the entire NixOS system. Everything else

     

       24
       24
       +
             in your configuration is indirectly pulled in by this option. This is

     

       25
       25
       +
             what <command>nixos-rebuild</command> builds and what

     

       26
       26
       +
             <filename>/run/current-system</filename> points to afterwards.

     

       21
       27
        
            </para>

     

       22
       28
        
            <para>

     

       23
       29
        
             A shortcut to build this is:

     
···

       42
       48
        
           </term>

     

       43
       49
        
           <listitem>

     

       44
       50
        
            <para>

     

       45
       45
       -
             A tree of symlinks that form the static parts of <filename>/etc</filename>.

     

       51
       51
       +
             A tree of symlinks that form the static parts of

     

       52
       52
       +
             <filename>/etc</filename>.

     

       46
       53
        
            </para>

     

       47
       54
        
           </listitem>

     

       48
       55
        
          </varlistentry>

     
···

       55
       62
        
           </term>

     

       56
       63
        
           <listitem>

     

       57
       64
        
            <para>

     

       58
       58
       -
             The initial ramdisk and kernel of the system. This allows a quick way to test whether the kernel and the initial ramdisk boot correctly, by using QEMU’s <option>-kernel</option> and <option>-initrd</option> options:

     

       65
       65
       +
             The initial ramdisk and kernel of the system. This allows a quick way to

     

       66
       66
       +
             test whether the kernel and the initial ramdisk boot correctly, by using

     

       67
       67
       +
             QEMU’s <option>-kernel</option> and <option>-initrd</option> options:

     

       59
       68
        
       <screen>

     

       60
       69
        
       <prompt>$ </prompt>nix-build -A config.system.build.initialRamdisk -o initrd

     

       61
       70
        
       <prompt>$ </prompt>nix-build -A config.system.build.kernel -o kernel

     
···

       86
       95
        
           </term>

     

       87
       96
        
           <listitem>

     

       88
       97
        
            <para>

     

       89
       89
       -
             This builds the unit with the specified name. Note that since unit names contain dots (e.g. <literal>httpd.service</literal>), you need to put them between quotes, like this:

     

       98
       98
       +
             This builds the unit with the specified name. Note that since unit names

     

       99
       99
       +
             contain dots (e.g. <literal>httpd.service</literal>), you need to put

     

       100
       100
       +
             them between quotes, like this:

     

       90
       101
        
       <screen>

     

       91
       102
        
       <prompt>$ </prompt>nix-build -A 'config.systemd.units."httpd.service".unit'

     

       92
       103
        
       </screen>

     

       93
       93
       -
             You can also test individual units, without rebuilding the whole system, by putting them in <filename>/run/systemd/system</filename>:

     

       104
       104
       +
             You can also test individual units, without rebuilding the whole system,

     

       105
       105
       +
             by putting them in <filename>/run/systemd/system</filename>:

     

       94
       106
        
       <screen>

     

       95
       107
        
       <prompt>$ </prompt>cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \

     

       96
       108
        
           /run/systemd/system/tmp-httpd.service

     

       97
       109
        
       <prompt># </prompt>systemctl daemon-reload

     

       98
       110
        
       <prompt># </prompt>systemctl start tmp-httpd.service

     

       99
       111
        
       </screen>

     

       100
       100
       -
             Note that the unit must not have the same name as any unit in <filename>/etc/systemd/system</filename> since those take precedence over <filename>/run/systemd/system</filename>. That’s why the unit is installed as <filename>tmp-httpd.service</filename> here.

     

       112
       112
       +
             Note that the unit must not have the same name as any unit in

     

       113
       113
       +
             <filename>/etc/systemd/system</filename> since those take precedence over

     

       114
       114
       +
             <filename>/run/systemd/system</filename>. That’s why the unit is

     

       115
       115
       +
             installed as <filename>tmp-httpd.service</filename> here.

     

       101
       116
        
            </para>

     

       102
       117
        
           </listitem>

     

       103
       118
        
          </varlistentry>

+5 -2

nixos/doc/manual/development/importing-modules.xml

···

       6
       6
        
        <title>Importing Modules</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Sometimes NixOS modules need to be used in configuration but exist outside of Nixpkgs. These modules can be imported:

     

       9
       9
       +
         Sometimes NixOS modules need to be used in configuration but exist outside of

     

       10
       10
       +
         Nixpkgs. These modules can be imported:

     

       10
       11
        
        </para>

     

       11
       12
        
       

     

       12
       13
        
       <programlisting>

     
···

       24
       25
        
       </programlisting>

     

       25
       26
        
       

     

       26
       27
        
        <para>

     

       27
       27
       -
         The environment variable <literal>NIXOS_EXTRA_MODULE_PATH</literal> is an absolute path to a NixOS module that is included alongside the Nixpkgs NixOS modules. Like any NixOS module, this module can import additional modules:

     

       28
       28
       +
         The environment variable <literal>NIXOS_EXTRA_MODULE_PATH</literal> is an

     

       29
       29
       +
         absolute path to a NixOS module that is included alongside the Nixpkgs NixOS

     

       30
       30
       +
         modules. Like any NixOS module, this module can import additional modules:

     

       28
       31
        
        </para>

     

       29
       32
        
       

     

       30
       33
        
       <programlisting>

+14 -5

nixos/doc/manual/development/meta-attributes.xml

···

       6
       6
        
        <title>Meta Attributes</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Like Nix packages, NixOS modules can declare meta-attributes to provide extra information. Module meta attributes are defined in the <filename

     

       10
       10
       -
           xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/misc/meta.nix">meta.nix</filename> special module.

     

       9
       9
       +
         Like Nix packages, NixOS modules can declare meta-attributes to provide extra

     

       10
       10
       +
         information. Module meta attributes are defined in the

     

       11
       11
       +
         <filename

     

       12
       12
       +
           xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/misc/meta.nix">meta.nix</filename>

     

       13
       13
       +
         special module.

     

       11
       14
        
        </para>

     

       12
       15
        
       

     

       13
       16
        
        <para>

     

       14
       14
       -
         <literal>meta</literal> is a top level attribute like <literal>options</literal> and <literal>config</literal>. Available meta-attributes are <literal>maintainers</literal> and <literal>doc</literal>.

     

       17
       17
       +
         <literal>meta</literal> is a top level attribute like

     

       18
       18
       +
         <literal>options</literal> and <literal>config</literal>. Available

     

       19
       19
       +
         meta-attributes are <literal>maintainers</literal> and

     

       20
       20
       +
         <literal>doc</literal>.

     

       15
       21
        
        </para>

     

       16
       22
        
       

     

       17
       23
        
        <para>

     
···

       45
       51
        
         </callout>

     

       46
       52
        
         <callout arearefs='modules-meta-2'>

     

       47
       53
        
          <para>

     

       48
       48
       -
           <varname>doc</varname> points to a valid DocBook file containing the module documentation. Its contents is automatically added to <xref

     

       49
       49
       -
             linkend="ch-configuration"/>. Changes to a module documentation have to be checked to not break building the NixOS manual:

     

       54
       54
       +
           <varname>doc</varname> points to a valid DocBook file containing the module

     

       55
       55
       +
           documentation. Its contents is automatically added to

     

       56
       56
       +
           <xref

     

       57
       57
       +
             linkend="ch-configuration"/>. Changes to a module documentation

     

       58
       58
       +
           have to be checked to not break building the NixOS manual:

     

       50
       59
        
          </para>

     

       51
       60
        
       <programlisting>$ nix-build nixos/release.nix -A manual</programlisting>

     

       52
       61
        
         </callout>

+7 -2

nixos/doc/manual/development/nixos-tests.xml

···

       5
       5
        
               xml:id="sec-nixos-tests">

     

       6
       6
        
        <title>NixOS Tests</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         When you add some feature to NixOS, you should write a test for it. NixOS tests are kept in the directory <filename

     

       9
       9
       -
       xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/tests</filename>, and are executed (using Nix) by a testing framework that automatically starts one or more virtual machines containing the NixOS system(s) required for the test.

     

       8
       8
       +
         When you add some feature to NixOS, you should write a test for it. NixOS

     

       9
       9
       +
         tests are kept in the directory

     

       10
       10
       +
         <filename

     

       11
       11
       +
       xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/tests</filename>,

     

       12
       12
       +
         and are executed (using Nix) by a testing framework that automatically starts

     

       13
       13
       +
         one or more virtual machines containing the NixOS system(s) required for the

     

       14
       14
       +
         test.

     

       10
       15
        
        </para>

     

       11
       16
        
        <xi:include href="writing-nixos-tests.xml" />

     

       12
       17
        
        <xi:include href="running-nixos-tests.xml" />

+61 -19

nixos/doc/manual/development/option-declarations.xml

···

       6
       6
        
        <title>Option Declarations</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         An option declaration specifies the name, type and description of a NixOS configuration option. It is invalid to define an option that hasn’t been declared in any module. An option declaration generally looks like this:

     

       9
       9
       +
         An option declaration specifies the name, type and description of a NixOS

     

       10
       10
       +
         configuration option. It is invalid to define an option that hasn’t been

     

       11
       11
       +
         declared in any module. An option declaration generally looks like this:

     

       10
       12
        
       <programlisting>

     

       11
       13
        
       options = {

     

       12
       14
        
         <replaceable>name</replaceable> = mkOption {

     
···

       17
       19
        
         };

     

       18
       20
        
       };

     

       19
       21
        
       </programlisting>

     

       20
       20
       -
         The attribute names within the <replaceable>name</replaceable> attribute path must be camel cased in general but should, as an exception, match the <link

     

       21
       21
       -
       xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> package attribute name</link> when referencing a Nixpkgs package. For example, the option <varname>services.nix-serve.bindAddress</varname> references the <varname>nix-serve</varname> Nixpkgs package.

     

       22
       22
       +
         The attribute names within the <replaceable>name</replaceable> attribute path

     

       23
       23
       +
         must be camel cased in general but should, as an exception, match the

     

       24
       24
       +
         <link

     

       25
       25
       +
       xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming">

     

       26
       26
       +
         package attribute name</link> when referencing a Nixpkgs package. For

     

       27
       27
       +
         example, the option <varname>services.nix-serve.bindAddress</varname>

     

       28
       28
       +
         references the <varname>nix-serve</varname> Nixpkgs package.

     

       22
       29
        
        </para>

     

       23
       30
        
       

     

       24
       31
        
        <para>

     
···

       30
       37
        
           </term>

     

       31
       38
        
           <listitem>

     

       32
       39
        
            <para>

     

       33
       33
       -
             The type of the option (see <xref linkend='sec-option-types' />). It may be omitted, but that’s not advisable since it may lead to errors that are hard to diagnose.

     

       40
       40
       +
             The type of the option (see <xref linkend='sec-option-types' />). It may

     

       41
       41
       +
             be omitted, but that’s not advisable since it may lead to errors that

     

       42
       42
       +
             are hard to diagnose.

     

       34
       43
        
            </para>

     

       35
       44
        
           </listitem>

     

       36
       45
        
          </varlistentry>

     
···

       40
       49
        
           </term>

     

       41
       50
        
           <listitem>

     

       42
       51
        
            <para>

     

       43
       43
       -
             The default value used if no value is defined by any module. A default is not required; but if a default is not given, then users of the module will have to define the value of the option, otherwise an error will be thrown.

     

       52
       52
       +
             The default value used if no value is defined by any module. A default is

     

       53
       53
       +
             not required; but if a default is not given, then users of the module

     

       54
       54
       +
             will have to define the value of the option, otherwise an error will be

     

       55
       55
       +
             thrown.

     

       44
       56
        
            </para>

     

       45
       57
        
           </listitem>

     

       46
       58
        
          </varlistentry>

     
···

       60
       72
        
           </term>

     

       61
       73
        
           <listitem>

     

       62
       74
        
            <para>

     

       63
       63
       -
             A textual description of the option, in DocBook format, that will be included in the NixOS manual.

     

       75
       75
       +
             A textual description of the option, in DocBook format, that will be

     

       76
       76
       +
             included in the NixOS manual.

     

       64
       77
        
            </para>

     

       65
       78
        
           </listitem>

     

       66
       79
        
          </varlistentry>

     
···

       71
       84
        
         <title>Extensible Option Types</title>

     

       72
       85
        
       

     

       73
       86
        
         <para>

     

       74
       74
       -
          Extensible option types is a feature that allow to extend certain types declaration through multiple module files. This feature only work with a restricted set of types, namely <literal>enum</literal> and <literal>submodules</literal> and any composed forms of them.

     

       87
       87
       +
          Extensible option types is a feature that allow to extend certain types

     

       88
       88
       +
          declaration through multiple module files. This feature only work with a

     

       89
       89
       +
          restricted set of types, namely <literal>enum</literal> and

     

       90
       90
       +
          <literal>submodules</literal> and any composed forms of them.

     

       75
       91
        
         </para>

     

       76
       92
        
       

     

       77
       93
        
         <para>

     

       78
       78
       -
          Extensible option types can be used for <literal>enum</literal> options that affects multiple modules, or as an alternative to related <literal>enable</literal> options.

     

       94
       94
       +
          Extensible option types can be used for <literal>enum</literal> options that

     

       95
       95
       +
          affects multiple modules, or as an alternative to related

     

       96
       96
       +
          <literal>enable</literal> options.

     

       79
       97
        
         </para>

     

       80
       98
        
       

     

       81
       99
        
         <para>

     

       82
       82
       -
          As an example, we will take the case of display managers. There is a central display manager module for generic display manager options and a module file per display manager backend (slim, sddm, gdm ...).

     

       100
       100
       +
          As an example, we will take the case of display managers. There is a central

     

       101
       101
       +
          display manager module for generic display manager options and a module file

     

       102
       102
       +
          per display manager backend (slim, sddm, gdm ...).

     

       83
       103
        
         </para>

     

       84
       104
        
       

     

       85
       105
        
         <para>

     
···

       87
       107
        
          <itemizedlist>

     

       88
       108
        
           <listitem>

     

       89
       109
        
            <para>

     

       90
       90
       -
             Managing the display managers independently by adding an enable option to every display manager module backend. (NixOS)

     

       110
       110
       +
             Managing the display managers independently by adding an enable option to

     

       111
       111
       +
             every display manager module backend. (NixOS)

     

       91
       112
        
            </para>

     

       92
       113
        
           </listitem>

     

       93
       114
        
           <listitem>

     

       94
       115
        
            <para>

     

       95
       95
       -
             Managing the display managers in the central module by adding an option to select which display manager backend to use.

     

       116
       116
       +
             Managing the display managers in the central module by adding an option

     

       117
       117
       +
             to select which display manager backend to use.

     

       96
       118
        
            </para>

     

       97
       119
        
           </listitem>

     

       98
       120
        
          </itemizedlist>

     
···

       103
       125
        
         </para>

     

       104
       126
        
       

     

       105
       127
        
         <para>

     

       106
       106
       -
          Making backends independent can quickly become hard to manage. For display managers, there can be only one enabled at a time, but the type system can not enforce this restriction as there is no relation between each backend <literal>enable</literal> option. As a result, this restriction has to be done explicitely by adding assertions in each display manager backend module.

     

       128
       128
       +
          Making backends independent can quickly become hard to manage. For display

     

       129
       129
       +
          managers, there can be only one enabled at a time, but the type system can

     

       130
       130
       +
          not enforce this restriction as there is no relation between each backend

     

       131
       131
       +
          <literal>enable</literal> option. As a result, this restriction has to be

     

       132
       132
       +
          done explicitely by adding assertions in each display manager backend

     

       133
       133
       +
          module.

     

       107
       134
        
         </para>

     

       108
       135
        
       

     

       109
       136
        
         <para>

     

       110
       110
       -
          On the other hand, managing the display managers backends in the central module will require to change the central module option every time a new backend is added or removed.

     

       137
       137
       +
          On the other hand, managing the display managers backends in the central

     

       138
       138
       +
          module will require to change the central module option every time a new

     

       139
       139
       +
          backend is added or removed.

     

       111
       140
        
         </para>

     

       112
       141
        
       

     

       113
       142
        
         <para>

     

       114
       114
       -
          By using extensible option types, it is possible to create a placeholder option in the central module (<xref linkend='ex-option-declaration-eot-service'

     

       115
       115
       -
             />), and to extend it in each backend module (<xref

     

       116
       116
       -
             linkend='ex-option-declaration-eot-backend-slim' />, <xref

     

       143
       143
       +
          By using extensible option types, it is possible to create a placeholder

     

       144
       144
       +
          option in the central module

     

       145
       145
       +
          (<xref linkend='ex-option-declaration-eot-service'

     

       146
       146
       +
             />), and to extend

     

       147
       147
       +
          it in each backend module

     

       148
       148
       +
          (<xref

     

       149
       149
       +
             linkend='ex-option-declaration-eot-backend-slim' />,

     

       150
       150
       +
          <xref

     

       117
       151
        
             linkend='ex-option-declaration-eot-backend-sddm' />).

     

       118
       152
        
         </para>

     

       119
       153
        
       

     

       120
       154
        
         <para>

     

       121
       121
       -
          As a result, <literal>displayManager.enable</literal> option values can be added without changing the main service module file and the type system automatically enforce that there can only be a single display manager enabled.

     

       155
       155
       +
          As a result, <literal>displayManager.enable</literal> option values can be

     

       156
       156
       +
          added without changing the main service module file and the type system

     

       157
       157
       +
          automatically enforce that there can only be a single display manager

     

       158
       158
       +
          enabled.

     

       122
       159
        
         </para>

     

       123
       160
        
       

     

       124
       161
        
         <example xml:id='ex-option-declaration-eot-service'>

     
···

       147
       184
        
         </example>

     

       148
       185
        
       

     

       149
       186
        
         <para>

     

       150
       150
       -
          The placeholder declaration is a standard <literal>mkOption</literal> declaration, but it is important that extensible option declarations only use the <literal>type</literal> argument.

     

       187
       187
       +
          The placeholder declaration is a standard <literal>mkOption</literal>

     

       188
       188
       +
          declaration, but it is important that extensible option declarations only

     

       189
       189
       +
          use the <literal>type</literal> argument.

     

       151
       190
        
         </para>

     

       152
       191
        
       

     

       153
       192
        
         <para>

     

       154
       154
       -
          Extensible option types work with any of the composed variants of <literal>enum</literal> such as <literal>with types; nullOr (enum [ "foo" "bar" ])</literal> or <literal>with types; listOf (enum [ "foo" "bar" ])</literal>.

     

       193
       193
       +
          Extensible option types work with any of the composed variants of

     

       194
       194
       +
          <literal>enum</literal> such as <literal>with types; nullOr (enum [ "foo"

     

       195
       195
       +
          "bar" ])</literal> or <literal>with types; listOf (enum [ "foo" "bar"

     

       196
       196
       +
          ])</literal>.

     

       155
       197
        
         </para>

     

       156
       198
        
        </section>

     

       157
       199
        
       </section>

+26 -8

nixos/doc/manual/development/option-def.xml

···

       6
       6
        
        <title>Option Definitions</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Option definitions are generally straight-forward bindings of values to option names, like

     

       9
       9
       +
         Option definitions are generally straight-forward bindings of values to

     

       10
       10
       +
         option names, like

     

       10
       11
        
       <programlisting>

     

       11
       12
        
       config = {

     

       12
       13
        
         services.httpd.enable = true;

     

       13
       14
        
       };

     

       14
       15
        
       </programlisting>

     

       15
       15
       -
         However, sometimes you need to wrap an option definition or set of option definitions in a <emphasis>property</emphasis> to achieve certain effects:

     

       16
       16
       +
         However, sometimes you need to wrap an option definition or set of option

     

       17
       17
       +
         definitions in a <emphasis>property</emphasis> to achieve certain effects:

     

       16
       18
        
        </para>

     

       17
       19
        
       

     

       18
       20
        
        <simplesect xml:id="sec-option-definitions-delaying-conditionals">

     

       19
       21
        
         <title>Delaying Conditionals</title>

     

       20
       22
        
         <para>

     

       21
       21
       -
          If a set of option definitions is conditional on the value of another option, you may need to use <varname>mkIf</varname>. Consider, for instance:

     

       23
       23
       +
          If a set of option definitions is conditional on the value of another

     

       24
       24
       +
          option, you may need to use <varname>mkIf</varname>. Consider, for instance:

     

       22
       25
        
       <programlisting>

     

       23
       26
        
       config = if config.services.httpd.enable then {

     

       24
       27
        
         environment.systemPackages = [ <replaceable>...</replaceable> ];

     

       25
       28
        
         <replaceable>...</replaceable>

     

       26
       29
        
       } else {};

     

       27
       30
        
       </programlisting>

     

       28
       28
       -
          This definition will cause Nix to fail with an “infinite recursion” error. Why? Because the value of <option>config.services.httpd.enable</option> depends on the value being constructed here. After all, you could also write the clearly circular and contradictory:

     

       31
       31
       +
          This definition will cause Nix to fail with an “infinite recursion”

     

       32
       32
       +
          error. Why? Because the value of

     

       33
       33
       +
          <option>config.services.httpd.enable</option> depends on the value being

     

       34
       34
       +
          constructed here. After all, you could also write the clearly circular and

     

       35
       35
       +
          contradictory:

     

       29
       36
        
       <programlisting>

     

       30
       37
        
       config = if config.services.httpd.enable then {

     

       31
       38
        
         services.httpd.enable = false;

     
···

       40
       47
        
         <replaceable>...</replaceable>

     

       41
       48
        
       };

     

       42
       49
        
       </programlisting>

     

       43
       43
       -
          The special function <varname>mkIf</varname> causes the evaluation of the conditional to be “pushed down” into the individual definitions, as if you had written:

     

       50
       50
       +
          The special function <varname>mkIf</varname> causes the evaluation of the

     

       51
       51
       +
          conditional to be “pushed down” into the individual definitions, as if

     

       52
       52
       +
          you had written:

     

       44
       53
        
       <programlisting>

     

       45
       54
        
       config = {

     

       46
       55
        
         environment.systemPackages = if config.services.httpd.enable then [ <replaceable>...</replaceable> ] else [];

     
···

       53
       62
        
        <simplesect xml:id="sec-option-definitions-setting-priorities">

     

       54
       63
        
         <title>Setting Priorities</title>

     

       55
       64
        
         <para>

     

       56
       56
       -
          A module can override the definitions of an option in other modules by setting a <emphasis>priority</emphasis>. All option definitions that do not have the lowest priority value are discarded. By default, option definitions have priority 1000. You can specify an explicit priority by using <varname>mkOverride</varname>, e.g.

     

       65
       65
       +
          A module can override the definitions of an option in other modules by

     

       66
       66
       +
          setting a <emphasis>priority</emphasis>. All option definitions that do not

     

       67
       67
       +
          have the lowest priority value are discarded. By default, option definitions

     

       68
       68
       +
          have priority 1000. You can specify an explicit priority by using

     

       69
       69
       +
          <varname>mkOverride</varname>, e.g.

     

       57
       70
        
       <programlisting>

     

       58
       71
        
       services.openssh.enable = mkOverride 10 false;

     

       59
       72
        
       </programlisting>

     

       60
       60
       -
          This definition causes all other definitions with priorities above 10 to be discarded. The function <varname>mkForce</varname> is equal to <varname>mkOverride 50</varname>.

     

       73
       73
       +
          This definition causes all other definitions with priorities above 10 to be

     

       74
       74
       +
          discarded. The function <varname>mkForce</varname> is equal to

     

       75
       75
       +
          <varname>mkOverride 50</varname>.

     

       61
       76
        
         </para>

     

       62
       77
        
        </simplesect>

     

       63
       78
        
       

     

       64
       79
        
        <simplesect xml:id="sec-option-definitions-merging">

     

       65
       80
        
         <title>Merging Configurations</title>

     

       66
       81
        
         <para>

     

       67
       67
       -
          In conjunction with <literal>mkIf</literal>, it is sometimes useful for a module to return multiple sets of option definitions, to be merged together as if they were declared in separate modules. This can be done using <varname>mkMerge</varname>:

     

       82
       82
       +
          In conjunction with <literal>mkIf</literal>, it is sometimes useful for a

     

       83
       83
       +
          module to return multiple sets of option definitions, to be merged together

     

       84
       84
       +
          as if they were declared in separate modules. This can be done using

     

       85
       85
       +
          <varname>mkMerge</varname>:

     

       68
       86
        
       <programlisting>

     

       69
       87
        
       config = mkMerge

     

       70
       88
        
         [ # Unconditional stuff.

+161 -47

nixos/doc/manual/development/option-types.xml

···

       6
       6
        
        <title>Options Types</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Option types are a way to put constraints on the values a module option can take. Types are also responsible of how values are merged in case of multiple value definitions.

     

       9
       9
       +
         Option types are a way to put constraints on the values a module option can

     

       10
       10
       +
         take. Types are also responsible of how values are merged in case of multiple

     

       11
       11
       +
         value definitions.

     

       10
       12
        
        </para>

     

       11
       13
        
       

     

       12
       14
        
        <section xml:id="sec-option-types-basic">

     

       13
       15
        
         <title>Basic Types</title>

     

       14
       16
        
       

     

       15
       17
        
         <para>

     

       16
       16
       -
          Basic types are the simplest available types in the module system. Basic types include multiple string types that mainly differ in how definition merging is handled.

     

       18
       18
       +
          Basic types are the simplest available types in the module system. Basic

     

       19
       19
       +
          types include multiple string types that mainly differ in how definition

     

       20
       20
       +
          merging is handled.

     

       17
       21
        
         </para>

     

       18
       22
        
       

     

       19
       23
        
         <variablelist>

     
···

       33
       37
        
           </term>

     

       34
       38
        
           <listitem>

     

       35
       39
        
            <para>

     

       36
       36
       -
             A boolean, its values can be <literal>true</literal> or <literal>false</literal>.

     

       40
       40
       +
             A boolean, its values can be <literal>true</literal> or

     

       41
       41
       +
             <literal>false</literal>.

     

       37
       42
        
            </para>

     

       38
       43
        
           </listitem>

     

       39
       44
        
          </varlistentry>

     
···

       43
       48
        
           </term>

     

       44
       49
        
           <listitem>

     

       45
       50
        
            <para>

     

       46
       46
       -
             A filesystem path, defined as anything that when coerced to a string starts with a slash. Even if derivations can be considered as path, the more specific <literal>types.package</literal> should be preferred.

     

       51
       51
       +
             A filesystem path, defined as anything that when coerced to a string

     

       52
       52
       +
             starts with a slash. Even if derivations can be considered as path, the

     

       53
       53
       +
             more specific <literal>types.package</literal> should be preferred.

     

       47
       54
        
            </para>

     

       48
       55
        
           </listitem>

     

       49
       56
        
          </varlistentry>

     
···

       80
       87
        
           </term>

     

       81
       88
        
           <listitem>

     

       82
       89
        
            <para>

     

       83
       83
       -
             Signed integers with a fixed length (8, 16 or 32 bits). They go from <inlineequation><mathphrase>−2<superscript>n</superscript>/2</mathphrase> </inlineequation> to <inlineequation> <mathphrase>2<superscript>n</superscript>/2−1</mathphrase> </inlineequation> respectively (e.g. <literal>−128</literal> to <literal>127</literal> for 8 bits).

     

       90
       90
       +
             Signed integers with a fixed length (8, 16 or 32 bits). They go from

     

       91
       91
       +
             <inlineequation><mathphrase>−2<superscript>n</superscript>/2</mathphrase>

     

       92
       92
       +
             </inlineequation> to <inlineequation>

     

       93
       93
       +
             <mathphrase>2<superscript>n</superscript>/2−1</mathphrase>

     

       94
       94
       +
             </inlineequation> respectively (e.g. <literal>−128</literal> to

     

       95
       95
       +
             <literal>127</literal> for 8 bits).

     

       84
       96
        
            </para>

     

       85
       97
        
           </listitem>

     

       86
       98
        
          </varlistentry>

     
···

       100
       112
        
           </term>

     

       101
       113
        
           <listitem>

     

       102
       114
        
            <para>

     

       103
       103
       -
             Unsigned integers with a fixed length (8, 16 or 32 bits). They go from <inlineequation><mathphrase>0</mathphrase></inlineequation> to <inlineequation> <mathphrase>2<superscript>n</superscript>−1</mathphrase> </inlineequation> respectively (e.g. <literal>0</literal> to <literal>255</literal> for 8 bits).

     

       115
       115
       +
             Unsigned integers with a fixed length (8, 16 or 32 bits). They go from

     

       116
       116
       +
             <inlineequation><mathphrase>0</mathphrase></inlineequation> to

     

       117
       117
       +
             <inlineequation>

     

       118
       118
       +
             <mathphrase>2<superscript>n</superscript>−1</mathphrase>

     

       119
       119
       +
             </inlineequation> respectively (e.g. <literal>0</literal> to

     

       120
       120
       +
             <literal>255</literal> for 8 bits).

     

       104
       121
        
            </para>

     

       105
       122
        
           </listitem>

     

       106
       123
        
          </varlistentry>

     
···

       120
       137
        
           </term>

     

       121
       138
        
           <listitem>

     

       122
       139
        
            <para>

     

       123
       123
       -
             A port number. This type is an alias to <link linkend='types.ints.ux'><varname>types.ints.u16</varname></link>.

     

       140
       140
       +
             A port number. This type is an alias to

     

       141
       141
       +
             <link linkend='types.ints.ux'><varname>types.ints.u16</varname></link>.

     

       124
       142
        
            </para>

     

       125
       143
        
           </listitem>

     

       126
       144
        
          </varlistentry>

     
···

       147
       165
        
           </term>

     

       148
       166
        
           <listitem>

     

       149
       167
        
            <para>

     

       150
       150
       -
             A string. Multiple definitions are concatenated with a new line <literal>"\n"</literal>.

     

       168
       168
       +
             A string. Multiple definitions are concatenated with a new line

     

       169
       169
       +
             <literal>"\n"</literal>.

     

       151
       170
        
            </para>

     

       152
       171
        
           </listitem>

     

       153
       172
        
          </varlistentry>

     
···

       157
       176
        
           </term>

     

       158
       177
        
           <listitem>

     

       159
       178
        
            <para>

     

       160
       160
       -
             A string. Multiple definitions are concatenated with a comma <literal>","</literal>.

     

       179
       179
       +
             A string. Multiple definitions are concatenated with a comma

     

       180
       180
       +
             <literal>","</literal>.

     

       161
       181
        
            </para>

     

       162
       182
        
           </listitem>

     

       163
       183
        
          </varlistentry>

     
···

       167
       187
        
           </term>

     

       168
       188
        
           <listitem>

     

       169
       189
        
            <para>

     

       170
       170
       -
             A string. Multiple definitions are concatenated with a collon <literal>":"</literal>.

     

       190
       190
       +
             A string. Multiple definitions are concatenated with a collon

     

       191
       191
       +
             <literal>":"</literal>.

     

       171
       192
        
            </para>

     

       172
       193
        
           </listitem>

     

       173
       194
        
          </varlistentry>

     
···

       177
       198
        
           </term>

     

       178
       199
        
           <listitem>

     

       179
       200
        
            <para>

     

       180
       180
       -
             A string matching a specific regular expression. Multiple definitions cannot be merged. The regular expression is processed using <literal>builtins.match</literal>.

     

       201
       201
       +
             A string matching a specific regular expression. Multiple definitions

     

       202
       202
       +
             cannot be merged. The regular expression is processed using

     

       203
       203
       +
             <literal>builtins.match</literal>.

     

       181
       204
        
            </para>

     

       182
       205
        
           </listitem>

     

       183
       206
        
          </varlistentry>

     
···

       198
       221
        
           </term>

     

       199
       222
        
           <listitem>

     

       200
       223
        
            <para>

     

       201
       201
       -
             One element of the list <replaceable>l</replaceable>, e.g. <literal>types.enum [ "left" "right" ]</literal>. Multiple definitions cannot be merged.

     

       224
       224
       +
             One element of the list <replaceable>l</replaceable>, e.g.

     

       225
       225
       +
             <literal>types.enum [ "left" "right" ]</literal>. Multiple definitions

     

       226
       226
       +
             cannot be merged.

     

       202
       227
        
            </para>

     

       203
       228
        
           </listitem>

     

       204
       229
        
          </varlistentry>

     
···

       208
       233
        
           </term>

     

       209
       234
        
           <listitem>

     

       210
       235
        
            <para>

     

       211
       211
       -
             A string with a custom separator <replaceable>sep</replaceable>, e.g. <literal>types.separatedString "|"</literal>.

     

       236
       236
       +
             A string with a custom separator <replaceable>sep</replaceable>, e.g.

     

       237
       237
       +
             <literal>types.separatedString "|"</literal>.

     

       212
       238
        
            </para>

     

       213
       239
        
           </listitem>

     

       214
       240
        
          </varlistentry>

     
···

       218
       244
        
           </term>

     

       219
       245
        
           <listitem>

     

       220
       246
        
            <para>

     

       221
       221
       -
             An integer between <replaceable>lowest</replaceable> and <replaceable>highest</replaceable> (both inclusive). Useful for creating types like <literal>types.port</literal>.

     

       247
       247
       +
             An integer between <replaceable>lowest</replaceable> and

     

       248
       248
       +
             <replaceable>highest</replaceable> (both inclusive). Useful for creating

     

       249
       249
       +
             types like <literal>types.port</literal>.

     

       222
       250
        
            </para>

     

       223
       251
        
           </listitem>

     

       224
       252
        
          </varlistentry>

     
···

       228
       256
        
           </term>

     

       229
       257
        
           <listitem>

     

       230
       258
        
            <para>

     

       231
       231
       -
             A set of sub options <replaceable>o</replaceable>. <replaceable>o</replaceable> can be an attribute set or a function returning an attribute set. Submodules are used in composed types to create modular options. Submodule are detailed in <xref

     

       259
       259
       +
             A set of sub options <replaceable>o</replaceable>.

     

       260
       260
       +
             <replaceable>o</replaceable> can be an attribute set or a function

     

       261
       261
       +
             returning an attribute set. Submodules are used in composed types to

     

       262
       262
       +
             create modular options. Submodule are detailed in

     

       263
       263
       +
             <xref

     

       232
       264
        
                 linkend='section-option-types-submodule' />.

     

       233
       265
        
            </para>

     

       234
       266
        
           </listitem>

     
···

       240
       272
        
         <title>Composed Types</title>

     

       241
       273
        
       

     

       242
       274
        
         <para>

     

       243
       243
       -
          Composed types are types that take a type as parameter. <literal>listOf int</literal> and <literal>either int str</literal> are examples of composed types.

     

       275
       275
       +
          Composed types are types that take a type as parameter. <literal>listOf

     

       276
       276
       +
          int</literal> and <literal>either int str</literal> are examples of composed

     

       277
       277
       +
          types.

     

       244
       278
        
         </para>

     

       245
       279
        
       

     

       246
       280
        
         <variablelist>

     
···

       250
       284
        
           </term>

     

       251
       285
        
           <listitem>

     

       252
       286
        
            <para>

     

       253
       253
       -
             A list of <replaceable>t</replaceable> type, e.g. <literal>types.listOf int</literal>. Multiple definitions are merged with list concatenation.

     

       287
       287
       +
             A list of <replaceable>t</replaceable> type, e.g. <literal>types.listOf

     

       288
       288
       +
             int</literal>. Multiple definitions are merged with list concatenation.

     

       254
       289
        
            </para>

     

       255
       290
        
           </listitem>

     

       256
       291
        
          </varlistentry>

     
···

       260
       295
        
           </term>

     

       261
       296
        
           <listitem>

     

       262
       297
        
            <para>

     

       263
       263
       -
             An attribute set of where all the values are of <replaceable>t</replaceable> type. Multiple definitions result in the joined attribute set.

     

       298
       298
       +
             An attribute set of where all the values are of

     

       299
       299
       +
             <replaceable>t</replaceable> type. Multiple definitions result in the

     

       300
       300
       +
             joined attribute set.

     

       264
       301
        
            </para>

     

       265
       302
        
           </listitem>

     

       266
       303
        
          </varlistentry>

     
···

       270
       307
        
           </term>

     

       271
       308
        
           <listitem>

     

       272
       309
        
            <para>

     

       273
       273
       -
             An attribute set or a list of <replaceable>t</replaceable> type. Multiple definitions are merged according to the value.

     

       310
       310
       +
             An attribute set or a list of <replaceable>t</replaceable> type. Multiple

     

       311
       311
       +
             definitions are merged according to the value.

     

       274
       312
        
            </para>

     

       275
       313
        
           </listitem>

     

       276
       314
        
          </varlistentry>

     
···

       280
       318
        
           </term>

     

       281
       319
        
           <listitem>

     

       282
       320
        
            <para>

     

       283
       283
       -
             <literal>null</literal> or type <replaceable>t</replaceable>. Multiple definitions are merged according to type <replaceable>t</replaceable>.

     

       321
       321
       +
             <literal>null</literal> or type <replaceable>t</replaceable>. Multiple

     

       322
       322
       +
             definitions are merged according to type <replaceable>t</replaceable>.

     

       284
       323
        
            </para>

     

       285
       324
        
           </listitem>

     

       286
       325
        
          </varlistentry>

     
···

       290
       329
        
           </term>

     

       291
       330
        
           <listitem>

     

       292
       331
        
            <para>

     

       293
       293
       -
             Ensures that type <replaceable>t</replaceable> cannot be merged. It is used to ensure option definitions are declared only once.

     

       332
       332
       +
             Ensures that type <replaceable>t</replaceable> cannot be merged. It is

     

       333
       333
       +
             used to ensure option definitions are declared only once.

     

       294
       334
        
            </para>

     

       295
       335
        
           </listitem>

     

       296
       336
        
          </varlistentry>

     
···

       300
       340
        
           </term>

     

       301
       341
        
           <listitem>

     

       302
       342
        
            <para>

     

       303
       303
       -
             Type <replaceable>t1</replaceable> or type <replaceable>t2</replaceable>, e.g. <literal>with types; either int str</literal>. Multiple definitions cannot be merged.

     

       343
       343
       +
             Type <replaceable>t1</replaceable> or type <replaceable>t2</replaceable>,

     

       344
       344
       +
             e.g. <literal>with types; either int str</literal>. Multiple definitions

     

       345
       345
       +
             cannot be merged.

     

       304
       346
        
            </para>

     

       305
       347
        
           </listitem>

     

       306
       348
        
          </varlistentry>

     
···

       310
       352
        
           </term>

     

       311
       353
        
           <listitem>

     

       312
       354
        
            <para>

     

       313
       313
       -
             Type <replaceable>t1</replaceable> or type <replaceable>t2</replaceable> and so forth, e.g. <literal>with types; oneOf [ int str bool ]</literal>. Multiple definitions cannot be merged.

     

       355
       355
       +
             Type <replaceable>t1</replaceable> or type <replaceable>t2</replaceable> and so forth,

     

       356
       356
       +
             e.g. <literal>with types; oneOf [ int str bool ]</literal>. Multiple definitions

     

       357
       357
       +
             cannot be merged.

     

       314
       358
        
            </para>

     

       315
       359
        
           </listitem>

     

       316
       360
        
          </varlistentry>

     
···

       320
       364
        
           </term>

     

       321
       365
        
           <listitem>

     

       322
       366
        
            <para>

     

       323
       323
       -
             Type <replaceable>to</replaceable> or type <replaceable>from</replaceable> which will be coerced to type <replaceable>to</replaceable> using function <replaceable>f</replaceable> which takes an argument of type <replaceable>from</replaceable> and return a value of type <replaceable>to</replaceable>. Can be used to preserve backwards compatibility of an option if its type was changed.

     

       367
       367
       +
             Type <replaceable>to</replaceable> or type

     

       368
       368
       +
             <replaceable>from</replaceable> which will be coerced to type

     

       369
       369
       +
             <replaceable>to</replaceable> using function <replaceable>f</replaceable>

     

       370
       370
       +
             which takes an argument of type <replaceable>from</replaceable> and

     

       371
       371
       +
             return a value of type <replaceable>to</replaceable>. Can be used to

     

       372
       372
       +
             preserve backwards compatibility of an option if its type was changed.

     

       324
       373
        
            </para>

     

       325
       374
        
           </listitem>

     

       326
       375
        
          </varlistentry>

     
···

       331
       380
        
         <title>Submodule</title>

     

       332
       381
        
       

     

       333
       382
        
         <para>

     

       334
       334
       -
          <literal>submodule</literal> is a very powerful type that defines a set of sub-options that are handled like a separate module.

     

       383
       383
       +
          <literal>submodule</literal> is a very powerful type that defines a set of

     

       384
       384
       +
          sub-options that are handled like a separate module.

     

       335
       385
        
         </para>

     

       336
       386
        
       

     

       337
       387
        
         <para>

     

       338
       338
       -
          It takes a parameter <replaceable>o</replaceable>, that should be a set, or a function returning a set with an <literal>options</literal> key defining the sub-options. Submodule option definitions are type-checked accordingly to the <literal>options</literal> declarations. Of course, you can nest submodule option definitons for even higher modularity.

     

       388
       388
       +
          It takes a parameter <replaceable>o</replaceable>, that should be a set, or

     

       389
       389
       +
          a function returning a set with an <literal>options</literal> key defining

     

       390
       390
       +
          the sub-options. Submodule option definitions are type-checked accordingly

     

       391
       391
       +
          to the <literal>options</literal> declarations. Of course, you can nest

     

       392
       392
       +
          submodule option definitons for even higher modularity.

     

       339
       393
        
         </para>

     

       340
       394
        
       

     

       341
       395
        
         <para>

     

       342
       342
       -
          The option set can be defined directly (<xref linkend='ex-submodule-direct' />) or as reference (<xref linkend='ex-submodule-reference' />).

     

       396
       396
       +
          The option set can be defined directly

     

       397
       397
       +
          (<xref linkend='ex-submodule-direct' />) or as reference

     

       398
       398
       +
          (<xref linkend='ex-submodule-reference' />).

     

       343
       399
        
         </para>

     

       344
       400
        
       

     

       345
       401
        
         <example xml:id='ex-submodule-direct'>

     
···

       382
       438
        
         </example>

     

       383
       439
        
       

     

       384
       440
        
         <para>

     

       385
       385
       -
          The <literal>submodule</literal> type is especially interesting when used with composed types like <literal>attrsOf</literal> or <literal>listOf</literal>. When composed with <literal>listOf</literal> (<xref linkend='ex-submodule-listof-declaration' />), <literal>submodule</literal> allows multiple definitions of the submodule option set (<xref linkend='ex-submodule-listof-definition' />).

     

       441
       441
       +
          The <literal>submodule</literal> type is especially interesting when used

     

       442
       442
       +
          with composed types like <literal>attrsOf</literal> or

     

       443
       443
       +
          <literal>listOf</literal>. When composed with <literal>listOf</literal>

     

       444
       444
       +
          (<xref linkend='ex-submodule-listof-declaration' />),

     

       445
       445
       +
          <literal>submodule</literal> allows multiple definitions of the submodule

     

       446
       446
       +
          option set (<xref linkend='ex-submodule-listof-definition' />).

     

       386
       447
        
         </para>

     

       387
       448
        
       

     

       388
       449
        
         <example xml:id='ex-submodule-listof-declaration'>

     
···

       413
       474
        
         </example>

     

       414
       475
        
       

     

       415
       476
        
         <para>

     

       416
       416
       -
          When composed with <literal>attrsOf</literal> (<xref linkend='ex-submodule-attrsof-declaration' />), <literal>submodule</literal> allows multiple named definitions of the submodule option set (<xref linkend='ex-submodule-attrsof-definition' />).

     

       477
       477
       +
          When composed with <literal>attrsOf</literal>

     

       478
       478
       +
          (<xref linkend='ex-submodule-attrsof-declaration' />),

     

       479
       479
       +
          <literal>submodule</literal> allows multiple named definitions of the

     

       480
       480
       +
          submodule option set (<xref linkend='ex-submodule-attrsof-definition' />).

     

       417
       481
        
         </para>

     

       418
       482
        
       

     

       419
       483
        
         <example xml:id='ex-submodule-attrsof-declaration'>

     
···

       446
       510
        
         <title>Extending types</title>

     

       447
       511
        
       

     

       448
       512
        
         <para>

     

       449
       449
       -
          Types are mainly characterized by their <literal>check</literal> and <literal>merge</literal> functions.

     

       513
       513
       +
          Types are mainly characterized by their <literal>check</literal> and

     

       514
       514
       +
          <literal>merge</literal> functions.

     

       450
       515
        
         </para>

     

       451
       516
        
       

     

       452
       517
        
         <variablelist>

     
···

       456
       521
        
           </term>

     

       457
       522
        
           <listitem>

     

       458
       523
        
            <para>

     

       459
       459
       -
             The function to type check the value. Takes a value as parameter and return a boolean. It is possible to extend a type check with the <literal>addCheck</literal> function (<xref

     

       460
       460
       -
                 linkend='ex-extending-type-check-1' />), or to fully override the check function (<xref linkend='ex-extending-type-check-2' />).

     

       524
       524
       +
             The function to type check the value. Takes a value as parameter and

     

       525
       525
       +
             return a boolean. It is possible to extend a type check with the

     

       526
       526
       +
             <literal>addCheck</literal> function

     

       527
       527
       +
             (<xref

     

       528
       528
       +
                 linkend='ex-extending-type-check-1' />), or to fully

     

       529
       529
       +
             override the check function

     

       530
       530
       +
             (<xref linkend='ex-extending-type-check-2' />).

     

       461
       531
        
            </para>

     

       462
       532
        
            <example xml:id='ex-extending-type-check-1'>

     

       463
       533
        
             <title>Adding a type check</title>

     
···

       485
       555
        
           </term>

     

       486
       556
        
           <listitem>

     

       487
       557
        
            <para>

     

       488
       488
       -
             Function to merge the options values when multiple values are set. The function takes two parameters, <literal>loc</literal> the option path as a list of strings, and <literal>defs</literal> the list of defined values as a list. It is possible to override a type merge function for custom needs.

     

       558
       558
       +
             Function to merge the options values when multiple values are set. The

     

       559
       559
       +
             function takes two parameters, <literal>loc</literal> the option path as

     

       560
       560
       +
             a list of strings, and <literal>defs</literal> the list of defined values

     

       561
       561
       +
             as a list. It is possible to override a type merge function for custom

     

       562
       562
       +
             needs.

     

       489
       563
        
            </para>

     

       490
       564
        
           </listitem>

     

       491
       565
        
          </varlistentry>

     
···

       496
       570
        
         <title>Custom Types</title>

     

       497
       571
        
       

     

       498
       572
        
         <para>

     

       499
       499
       -
          Custom types can be created with the <literal>mkOptionType</literal> function. As type creation includes some more complex topics such as submodule handling, it is recommended to get familiar with <filename

     

       500
       500
       -
         xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/types.nix">types.nix</filename> code before creating a new type.

     

       573
       573
       +
          Custom types can be created with the <literal>mkOptionType</literal>

     

       574
       574
       +
          function. As type creation includes some more complex topics such as

     

       575
       575
       +
          submodule handling, it is recommended to get familiar with

     

       576
       576
       +
          <filename

     

       577
       577
       +
         xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/types.nix">types.nix</filename>

     

       578
       578
       +
          code before creating a new type.

     

       501
       579
        
         </para>

     

       502
       580
        
       

     

       503
       581
        
         <para>

     
···

       521
       599
        
           </term>

     

       522
       600
        
           <listitem>

     

       523
       601
        
            <para>

     

       524
       524
       -
             Description of the type used in documentation. Give information of the type and any of its arguments.

     

       602
       602
       +
             Description of the type used in documentation. Give information of the

     

       603
       603
       +
             type and any of its arguments.

     

       525
       604
        
            </para>

     

       526
       605
        
           </listitem>

     

       527
       606
        
          </varlistentry>

     
···

       531
       610
        
           </term>

     

       532
       611
        
           <listitem>

     

       533
       612
        
            <para>

     

       534
       534
       -
             A function to type check the definition value. Takes the definition value as a parameter and returns a boolean indicating the type check result, <literal>true</literal> for success and <literal>false</literal> for failure.

     

       613
       613
       +
             A function to type check the definition value. Takes the definition value

     

       614
       614
       +
             as a parameter and returns a boolean indicating the type check result,

     

       615
       615
       +
             <literal>true</literal> for success and <literal>false</literal> for

     

       616
       616
       +
             failure.

     

       535
       617
        
            </para>

     

       536
       618
        
           </listitem>

     

       537
       619
        
          </varlistentry>

     
···

       550
       632
        
              </term>

     

       551
       633
        
              <listitem>

     

       552
       634
        
               <para>

     

       553
       553
       -
                The option path as a list of strings, e.g. <literal>["boot" "loader "grub" "enable"]</literal>.

     

       635
       635
       +
                The option path as a list of strings, e.g. <literal>["boot" "loader

     

       636
       636
       +
                "grub" "enable"]</literal>.

     

       554
       637
        
               </para>

     

       555
       638
        
              </listitem>

     

       556
       639
        
             </varlistentry>

     
···

       560
       643
        
              </term>

     

       561
       644
        
              <listitem>

     

       562
       645
        
               <para>

     

       563
       563
       -
                The list of sets of defined <literal>value</literal> and <literal>file</literal> where the value was defined, e.g. <literal>[ { file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 } ]</literal>. The <literal>merge</literal> function should return the merged value or throw an error in case the values are impossible or not meant to be merged.

     

       646
       646
       +
                The list of sets of defined <literal>value</literal> and

     

       647
       647
       +
                <literal>file</literal> where the value was defined, e.g. <literal>[ {

     

       648
       648
       +
                file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 }

     

       649
       649
       +
                ]</literal>. The <literal>merge</literal> function should return the

     

       650
       650
       +
                merged value or throw an error in case the values are impossible or

     

       651
       651
       +
                not meant to be merged.

     

       564
       652
        
               </para>

     

       565
       653
        
              </listitem>

     

       566
       654
        
             </varlistentry>

     
···

       573
       661
        
           </term>

     

       574
       662
        
           <listitem>

     

       575
       663
        
            <para>

     

       576
       576
       -
             For composed types that can take a submodule as type parameter, this function generate sub-options documentation. It takes the current option prefix as a list and return the set of sub-options. Usually defined in a recursive manner by adding a term to the prefix, e.g. <literal>prefix: elemType.getSubOptions (prefix ++ [<replaceable>"prefix"</replaceable>])</literal> where <replaceable>"prefix"</replaceable> is the newly added prefix.

     

       664
       664
       +
             For composed types that can take a submodule as type parameter, this

     

       665
       665
       +
             function generate sub-options documentation. It takes the current option

     

       666
       666
       +
             prefix as a list and return the set of sub-options. Usually defined in a

     

       667
       667
       +
             recursive manner by adding a term to the prefix, e.g. <literal>prefix:

     

       668
       668
       +
             elemType.getSubOptions (prefix ++

     

       669
       669
       +
             [<replaceable>"prefix"</replaceable>])</literal> where

     

       670
       670
       +
             <replaceable>"prefix"</replaceable> is the newly added prefix.

     

       577
       671
        
            </para>

     

       578
       672
        
           </listitem>

     

       579
       673
        
          </varlistentry>

     
···

       583
       677
        
           </term>

     

       584
       678
        
           <listitem>

     

       585
       679
        
            <para>

     

       586
       586
       -
             For composed types that can take a submodule as type parameter, this function should return the type parameters submodules. If the type parameter is called <literal>elemType</literal>, the function should just recursively look into submodules by returning <literal>elemType.getSubModules;</literal>.

     

       680
       680
       +
             For composed types that can take a submodule as type parameter, this

     

       681
       681
       +
             function should return the type parameters submodules. If the type

     

       682
       682
       +
             parameter is called <literal>elemType</literal>, the function should just

     

       683
       683
       +
             recursively look into submodules by returning

     

       684
       684
       +
             <literal>elemType.getSubModules;</literal>.

     

       587
       685
        
            </para>

     

       588
       686
        
           </listitem>

     

       589
       687
        
          </varlistentry>

     
···

       593
       691
        
           </term>

     

       594
       692
        
           <listitem>

     

       595
       693
        
            <para>

     

       596
       596
       -
             For composed types that can take a submodule as type parameter, this function can be used to substitute the parameter of a submodule type. It takes a module as parameter and return the type with the submodule options substituted. It is usually defined as a type function call with a recursive call to <literal>substSubModules</literal>, e.g for a type <literal>composedType</literal> that take an <literal>elemtype</literal> type parameter, this function should be defined as <literal>m: composedType (elemType.substSubModules m)</literal>.

     

       694
       694
       +
             For composed types that can take a submodule as type parameter, this

     

       695
       695
       +
             function can be used to substitute the parameter of a submodule type. It

     

       696
       696
       +
             takes a module as parameter and return the type with the submodule

     

       697
       697
       +
             options substituted. It is usually defined as a type function call with a

     

       698
       698
       +
             recursive call to <literal>substSubModules</literal>, e.g for a type

     

       699
       699
       +
             <literal>composedType</literal> that take an <literal>elemtype</literal>

     

       700
       700
       +
             type parameter, this function should be defined as <literal>m:

     

       701
       701
       +
             composedType (elemType.substSubModules m)</literal>.

     

       597
       702
        
            </para>

     

       598
       703
        
           </listitem>

     

       599
       704
        
          </varlistentry>

     
···

       603
       708
        
           </term>

     

       604
       709
        
           <listitem>

     

       605
       710
        
            <para>

     

       606
       606
       -
             A function to merge multiple type declarations. Takes the type to merge <literal>functor</literal> as parameter. A <literal>null</literal> return value means that type cannot be merged.

     

       711
       711
       +
             A function to merge multiple type declarations. Takes the type to merge

     

       712
       712
       +
             <literal>functor</literal> as parameter. A <literal>null</literal> return

     

       713
       713
       +
             value means that type cannot be merged.

     

       607
       714
        
            </para>

     

       608
       715
        
            <variablelist>

     

       609
       716
        
             <varlistentry>

     
···

       618
       725
        
             </varlistentry>

     

       619
       726
        
            </variablelist>

     

       620
       727
        
            <para>

     

       621
       621
       -
             Note: There is a generic <literal>defaultTypeMerge</literal> that work with most of value and composed types.

     

       728
       728
       +
             Note: There is a generic <literal>defaultTypeMerge</literal> that work

     

       729
       729
       +
             with most of value and composed types.

     

       622
       730
        
            </para>

     

       623
       731
        
           </listitem>

     

       624
       732
        
          </varlistentry>

     
···

       628
       736
        
           </term>

     

       629
       737
        
           <listitem>

     

       630
       738
        
            <para>

     

       631
       631
       -
             An attribute set representing the type. It is used for type operations and has the following keys:

     

       739
       739
       +
             An attribute set representing the type. It is used for type operations

     

       740
       740
       +
             and has the following keys:

     

       632
       741
        
            </para>

     

       633
       742
        
            <variablelist>

     

       634
       743
        
             <varlistentry>

     
···

       657
       766
        
              </term>

     

       658
       767
        
              <listitem>

     

       659
       768
        
               <para>

     

       660
       660
       -
                Holds the value parameter for value types. The types that have a <literal>payload</literal> are the <literal>enum</literal>, <literal>separatedString</literal> and <literal>submodule</literal> types.

     

       769
       769
       +
                Holds the value parameter for value types. The types that have a

     

       770
       770
       +
                <literal>payload</literal> are the <literal>enum</literal>,

     

       771
       771
       +
                <literal>separatedString</literal> and <literal>submodule</literal>

     

       772
       772
       +
                types.

     

       661
       773
        
               </para>

     

       662
       774
        
              </listitem>

     

       663
       775
        
             </varlistentry>

     
···

       667
       779
        
              </term>

     

       668
       780
        
              <listitem>

     

       669
       781
        
               <para>

     

       670
       670
       -
                A binary operation that can merge the payloads of two same types. Defined as a function that take two payloads as parameters and return the payloads merged.

     

       782
       782
       +
                A binary operation that can merge the payloads of two same types.

     

       783
       783
       +
                Defined as a function that take two payloads as parameters and return

     

       784
       784
       +
                the payloads merged.

     

       671
       785
        
               </para>

     

       672
       786
        
              </listitem>

     

       673
       787
        
             </varlistentry>

+72 -54

nixos/doc/manual/development/releases.xml

···

       17
       17
        
          <itemizedlist spacing="compact">

     

       18
       18
        
           <listitem>

     

       19
       19
        
            <para>

     

       20
       20
       -
             Send an email to the nix-devel mailinglist as a warning about upcoming beta "feature freeze" in a month.

     

       20
       20
       +
             Send an email to the nix-devel mailinglist as a warning about upcoming

     

       21
       21
       +
             beta "feature freeze" in a month.

     

       21
       22
        
            </para>

     

       22
       23
        
           </listitem>

     

       23
       24
        
           <listitem>

     

       24
       25
        
            <para>

     

       25
       25
       -
             Discuss with Eelco Dolstra and the community (via IRC, ML) about what will reach the deadline. Any issue or Pull Request targeting the release should be included in the release milestone.

     

       26
       26
       +
             Discuss with Eelco Dolstra and the community (via IRC, ML) about what

     

       27
       27
       +
             will reach the deadline. Any issue or Pull Request targeting the release

     

       28
       28
       +
             should be included in the release milestone.

     

       26
       29
        
            </para>

     

       27
       30
        
           </listitem>

     

       28
       31
        
          </itemizedlist>

     
···

       34
       37
        
          <itemizedlist spacing="compact">

     

       35
       38
        
           <listitem>

     

       36
       39
        
            <para>

     

       37
       37
       -
             <link xlink:href="https://github.com/NixOS/nixpkgs/issues/13559">Create an issue for tracking Zero Hydra Failures progress. ZHF is an effort to get build failures down to zero.</link>

     

       40
       40
       +
             <link xlink:href="https://github.com/NixOS/nixpkgs/issues/13559">Create

     

       41
       41
       +
             an issue for tracking Zero Hydra Failures progress. ZHF is an effort to

     

       42
       42
       +
             get build failures down to zero.</link>

     

       38
       43
        
            </para>

     

       39
       44
        
           </listitem>

     

       40
       45
        
           <listitem>

     

       41
       46
        
            <para>

     

       42
       42
       -
             <literal>git tag -a -s -m &quot;Release 17.09-beta&quot; 17.09-beta &amp;&amp; git push --tags</literal>

     

       47
       47
       +
             <literal>git tag -a -s -m &quot;Release 17.09-beta&quot; 17.09-beta

     

       48
       48
       +
             &amp;&amp; git push --tags</literal>

     

       43
       49
        
            </para>

     

       44
       50
        
           </listitem>

     

       45
       51
        
           <listitem>

     

       46
       52
        
            <para>

     

       47
       47
       -
             From the master branch run <literal>git checkout -B release-17.09</literal>.

     

       53
       53
       +
             From the master branch run <literal>git checkout -B

     

       54
       54
       +
             release-17.09</literal>.

     

       48
       55
        
            </para>

     

       49
       56
        
           </listitem>

     

       50
       57
        
           <listitem>

     

       51
       58
        
            <para>

     

       52
       52
       -
             <link xlink:href="https://github.com/NixOS/nixos-org-configurations/pull/18"> Make sure a channel is created at http://nixos.org/channels/. </link>

     

       59
       59
       +
             <link xlink:href="https://github.com/NixOS/nixos-org-configurations/pull/18">

     

       60
       60
       +
             Make sure a channel is created at http://nixos.org/channels/. </link>

     

       53
       61
        
            </para>

     

       54
       62
        
           </listitem>

     

       55
       63
        
           <listitem>

     

       56
       64
        
            <para>

     

       57
       57
       -
             <link xlink:href="https://github.com/NixOS/nixpkgs/compare/bdf161ed8d21...6b63c4616790"> Bump the <literal>system.defaultChannel</literal> attribute in <literal>nixos/modules/misc/version.nix</literal> </link>

     

       65
       65
       +
             <link xlink:href="https://github.com/NixOS/nixpkgs/compare/bdf161ed8d21...6b63c4616790">

     

       66
       66
       +
             Bump the <literal>system.defaultChannel</literal> attribute in

     

       67
       67
       +
             <literal>nixos/modules/misc/version.nix</literal> </link>

     

       58
       68
        
            </para>

     

       59
       69
        
           </listitem>

     

       60
       70
        
           <listitem>

     

       61
       71
        
            <para>

     

       62
       62
       -
             <link xlink:href="https://github.com/NixOS/nixpkgs/commit/d6b08acd1ccac0d9d502c4b635e00b04d3387f06"> Update <literal>versionSuffix</literal> in <literal>nixos/release.nix</literal></link>, use <literal>git log --format=%an|wc -l</literal> to get the commit count

     

       72
       72
       +
             <link xlink:href="https://github.com/NixOS/nixpkgs/commit/d6b08acd1ccac0d9d502c4b635e00b04d3387f06">

     

       73
       73
       +
             Update <literal>versionSuffix</literal> in

     

       74
       74
       +
             <literal>nixos/release.nix</literal></link>, use <literal>git log

     

       75
       75
       +
             --format=%an|wc -l</literal> to get the commit count

     

       63
       76
        
            </para>

     

       64
       77
        
           </listitem>

     

       65
       78
        
           <listitem>

     
···

       69
       82
        
           </listitem>

     

       70
       83
        
           <listitem>

     

       71
       84
        
            <para>

     

       72
       72
       -
             <link xlink:href="https://github.com/NixOS/nixpkgs/commit/b8a4095003e27659092892a4708bb3698231a842"> Pick a new name for the unstable branch. </link>

     

       85
       85
       +
             <link xlink:href="https://github.com/NixOS/nixpkgs/commit/b8a4095003e27659092892a4708bb3698231a842">

     

       86
       86
       +
             Pick a new name for the unstable branch. </link>

     

       73
       87
        
            </para>

     

       74
       88
        
           </listitem>

     

       75
       89
        
           <listitem>

     

       76
       90
        
            <para>

     

       77
       77
       -
             Create a new release notes file for the upcoming release + 1, in this case <literal>rl-1803.xml</literal>.

     

       91
       91
       +
             Create a new release notes file for the upcoming release + 1, in this

     

       92
       92
       +
             case <literal>rl-1803.xml</literal>.

     

       78
       93
        
            </para>

     

       79
       94
        
           </listitem>

     

       80
       95
        
           <listitem>

     

       81
       96
        
            <para>

     

       82
       82
       -
             Create two Hydra jobsets: release-17.09 and release-17.09-small with <literal>stableBranch</literal> set to false.

     

       97
       97
       +
             Create two Hydra jobsets: release-17.09 and release-17.09-small with

     

       98
       98
       +
             <literal>stableBranch</literal> set to false.

     

       83
       99
        
            </para>

     

       84
       100
        
           </listitem>

     

       85
       101
        
           <listitem>

     

       86
       102
        
            <para>

     

       87
       87
       -
             Remove attributes that we know we will not be able to support, especially if there is a stable alternative. E.g. Check that our Linux kernels' <link xlink:href="https://www.kernel.org/category/releases.html"> projected end-of-life</link> are after our release projected end-of-life

     

       103
       103
       +
             Remove attributes that we know we will not be able to support,

     

       104
       104
       +
             especially if there is a stable alternative. E.g. Check that our

     

       105
       105
       +
             Linux kernels'

     

       106
       106
       +
             <link xlink:href="https://www.kernel.org/category/releases.html">

     

       107
       107
       +
             projected end-of-life</link> are after our release projected

     

       108
       108
       +
             end-of-life

     

       88
       109
        
            </para>

     

       89
       110
        
           </listitem>

     

       90
       111
        
           <listitem>

     

       91
       112
        
            <para>

     

       92
       92
       -
             Edit changelog at <literal>nixos/doc/manual/release-notes/rl-1709.xml</literal> (double check desktop versions are noted)

     

       113
       113
       +
             Edit changelog at

     

       114
       114
       +
             <literal>nixos/doc/manual/release-notes/rl-1709.xml</literal> (double

     

       115
       115
       +
             check desktop versions are noted)

     

       93
       116
        
            </para>

     

       94
       117
        
            <itemizedlist spacing="compact">

     

       95
       118
        
             <listitem>

     

       96
       119
        
              <para>

     

       97
       97
       -
               Get all new NixOS modules <literal>git diff release-17.03..release-17.09 nixos/modules/module-list.nix|grep ^+</literal>

     

       120
       120
       +
               Get all new NixOS modules <literal>git diff

     

       121
       121
       +
               release-17.03..release-17.09 nixos/modules/module-list.nix|grep

     

       122
       122
       +
               ^+</literal>

     

       98
       123
        
              </para>

     

       99
       124
        
             </listitem>

     

       100
       125
        
             <listitem>

     
···

       113
       138
        
          <itemizedlist spacing="compact">

     

       114
       139
        
           <listitem>

     

       115
       140
        
            <para>

     

       116
       116
       -
             Monitor the master branch for bugfixes and minor updates and cherry-pick them to the release branch.

     

       141
       141
       +
             Monitor the master branch for bugfixes and minor updates and cherry-pick

     

       142
       142
       +
             them to the release branch.

     

       117
       143
        
            </para>

     

       118
       144
        
           </listitem>

     

       119
       145
        
          </itemizedlist>

     
···

       130
       156
        
           </listitem>

     

       131
       157
        
           <listitem>

     

       132
       158
        
            <para>

     

       133
       133
       -
             Release Nix (currently only Eelco Dolstra can do that). <link xlink:href="https://github.com/NixOS/nixpkgs/commit/53710c752a85f00658882531bc90a23a3d1287e4"> Make sure fallback is updated. </link>

     

       159
       159
       +
             Release Nix (currently only Eelco Dolstra can do that).

     

       160
       160
       +
             <link xlink:href="https://github.com/NixOS/nixpkgs/commit/53710c752a85f00658882531bc90a23a3d1287e4">

     

       161
       161
       +
             Make sure fallback is updated. </link>

     

       134
       162
        
            </para>

     

       135
       163
        
           </listitem>

     

       136
       164
        
           <listitem>

     

       137
       165
        
            <para>

     

       138
       138
       -
             <link xlink:href="https://github.com/NixOS/nixpkgs/commit/40fd9ae3ac8048758abdcfc7d28a78b5f22fe97e"> Update README.md with new stable NixOS version information. </link>

     

       166
       166
       +
             <link xlink:href="https://github.com/NixOS/nixpkgs/commit/40fd9ae3ac8048758abdcfc7d28a78b5f22fe97e">

     

       167
       167
       +
             Update README.md with new stable NixOS version information. </link>

     

       139
       168
        
            </para>

     

       140
       169
        
           </listitem>

     

       141
       170
        
           <listitem>

     

       142
       171
        
            <para>

     

       143
       143
       -
             Change <literal>stableBranch</literal> to true and wait for channel to update.

     

       172
       172
       +
             Change <literal>stableBranch</literal> to true and wait for channel to

     

       173
       173
       +
             update.

     

       144
       174
        
            </para>

     

       145
       175
        
           </listitem>

     

       146
       176
        
          </itemizedlist>

     
···

       157
       187
        
           </listitem>

     

       158
       188
        
           <listitem>

     

       159
       189
        
            <para>

     

       160
       160
       -
             Update "Chapter 4. Upgrading NixOS" section of the manual to match new stable release version.

     

       190
       190
       +
             Update "Chapter 4. Upgrading NixOS" section of the manual to match 

     

       191
       191
       +
             new stable release version.

     

       161
       192
        
            </para>

     

       162
       193
        
           </listitem>

     

       163
       194
        
           <listitem>

     

       164
       195
        
            <para>

     

       165
       165
       -
             Update http://nixos.org/nixos/download.html and http://nixos.org/nixos/manual in https://github.com/NixOS/nixos-org-configurations

     

       196
       196
       +
             Update http://nixos.org/nixos/download.html and

     

       197
       197
       +
             http://nixos.org/nixos/manual in

     

       198
       198
       +
             https://github.com/NixOS/nixos-org-configurations

     

       166
       199
        
            </para>

     

       167
       200
        
           </listitem>

     

       168
       201
        
           <listitem>

     

       169
       202
        
            <para>

     

       170
       170
       -
             Get number of commits for the release: <literal>git log release-14.04..release-14.12 --format=%an|wc -l</literal>

     

       203
       203
       +
             Get number of commits for the release: <literal>git log

     

       204
       204
       +
             release-14.04..release-14.12 --format=%an|wc -l</literal>

     

       171
       205
        
            </para>

     

       172
       206
        
           </listitem>

     

       173
       207
        
           <listitem>

     

       174
       208
        
            <para>

     

       175
       175
       -
             Commits by contributor: <literal>git log release-14.04..release-14.12 --format=%an|sort|uniq -c|sort -rn</literal>

     

       209
       209
       +
             Commits by contributor: <literal>git log release-14.04..release-14.12

     

       210
       210
       +
             --format=%an|sort|uniq -c|sort -rn</literal>

     

       176
       211
        
            </para>

     

       177
       212
        
           </listitem>

     

       178
       213
        
           <listitem>

     

       179
       214
        
            <para>

     

       180
       180
       -
             Send an email to nix-dev to announce the release with above information. Best to check how previous email was formulated to see what needs to be included.

     

       215
       215
       +
             Send an email to nix-dev to announce the release with above information.

     

       216
       216
       +
             Best to check how previous email was formulated to see what needs to be

     

       217
       217
       +
             included.

     

       181
       218
        
            </para>

     

       182
       219
        
           </listitem>

     

       183
       220
        
          </itemizedlist>

     
···

       185
       222
        
        </section>

     

       186
       223
        
        <section xml:id="release-managers">

     

       187
       224
        
         <title>Release Management Team</title>

     

       188
       188
       -
       

     

       189
       225
        
         <para>

     

       190
       190
       -
          For each release there are two release managers. After each release the release manager having managed two releases steps down and the release management team of the last release appoints a new release manager.

     

       226
       226
       +
          For each release there are two release managers. After each release the

     

       227
       227
       +
          release manager having managed two releases steps down and the release

     

       228
       228
       +
          management team of the last release appoints a new release manager.

     

       191
       229
        
         </para>

     

       192
       192
       -
       

     

       193
       230
        
         <para>

     

       194
       194
       -
          This makes sure a release management team always consists of one release manager who already has managed one release and one release manager being introduced to their role, making it easier to pass on knowledge and experience.

     

       231
       231
       +
          This makes sure a release management team always consists of one release

     

       232
       232
       +
          manager who already has managed one release and one release manager being

     

       233
       233
       +
          introduced to their role, making it easier to pass on knowledge and

     

       234
       234
       +
          experience.

     

       195
       235
        
         </para>

     

       196
       196
       -
       

     

       197
       236
        
         <para>

     

       198
       237
        
          A release manager's role and responsibilities are:

     

       199
       238
        
         </para>

     

       200
       200
       -
       

     

       201
       239
        
         <itemizedlist>

     

       202
       202
       -
          <listitem>

     

       203
       203
       -
           <para>

     

       204
       204
       -
            manage the release process

     

       205
       205
       -
           </para>

     

       206
       206
       -
          </listitem>

     

       207
       207
       -
          <listitem>

     

       208
       208
       -
           <para>

     

       209
       209
       -
            start discussions about features and changes for a given release

     

       210
       210
       -
           </para>

     

       211
       211
       -
          </listitem>

     

       212
       212
       -
          <listitem>

     

       213
       213
       -
           <para>

     

       214
       214
       -
            create a roadmap

     

       215
       215
       -
           </para>

     

       216
       216
       -
          </listitem>

     

       217
       217
       -
          <listitem>

     

       218
       218
       -
           <para>

     

       219
       219
       -
            release in cooperation with Eelco Dolstra

     

       220
       220
       -
           </para>

     

       221
       221
       -
          </listitem>

     

       222
       222
       -
          <listitem>

     

       223
       223
       -
           <para>

     

       224
       224
       -
            decide which bug fixes, features, etc... get backported after a release

     

       225
       225
       -
           </para>

     

       226
       226
       -
          </listitem>

     

       240
       240
       +
          <listitem><para>manage the release process</para></listitem>

     

       241
       241
       +
          <listitem><para>start discussions about features and changes for a given release</para></listitem>

     

       242
       242
       +
          <listitem><para>create a roadmap</para></listitem>

     

       243
       243
       +
          <listitem><para>release in cooperation with Eelco Dolstra</para></listitem>

     

       244
       244
       +
          <listitem><para>decide which bug fixes, features, etc... get backported after a release</para></listitem>

     

       227
       245
        
         </itemizedlist>

     

       228
       246
        
        </section>

     

       229
       247
        
        <section xml:id="release-schedule">

+18 -4

nixos/doc/manual/development/replace-modules.xml

···

       6
       6
        
        <title>Replace Modules</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Modules that are imported can also be disabled. The option declarations and config implementation of a disabled module will be ignored, allowing another to take it's place. This can be used to import a set of modules from another channel while keeping the rest of the system on a stable release.

     

       9
       9
       +
         Modules that are imported can also be disabled. The option declarations and

     

       10
       10
       +
         config implementation of a disabled module will be ignored, allowing another

     

       11
       11
       +
         to take it's place. This can be used to import a set of modules from another

     

       12
       12
       +
         channel while keeping the rest of the system on a stable release.

     

       10
       13
        
        </para>

     

       11
       14
        
       

     

       12
       15
        
        <para>

     

       13
       13
       -
         <literal>disabledModules</literal> is a top level attribute like <literal>imports</literal>, <literal>options</literal> and <literal>config</literal>. It contains a list of modules that will be disabled. This can either be the full path to the module or a string with the filename relative to the modules path (eg. &lt;nixpkgs/nixos/modules&gt; for nixos).

     

       16
       16
       +
         <literal>disabledModules</literal> is a top level attribute like

     

       17
       17
       +
         <literal>imports</literal>, <literal>options</literal> and

     

       18
       18
       +
         <literal>config</literal>. It contains a list of modules that will be

     

       19
       19
       +
         disabled. This can either be the full path to the module or a string with the

     

       20
       20
       +
         filename relative to the modules path (eg. &lt;nixpkgs/nixos/modules&gt; for

     

       21
       21
       +
         nixos).

     

       14
       22
        
        </para>

     

       15
       23
        
       

     

       16
       24
        
        <para>

     

       17
       17
       -
         This example will replace the existing postgresql module with the version defined in the nixos-unstable channel while keeping the rest of the modules and packages from the original nixos channel. This only overrides the module definition, this won't use postgresql from nixos-unstable unless explicitly configured to do so.

     

       25
       25
       +
         This example will replace the existing postgresql module with the version

     

       26
       26
       +
         defined in the nixos-unstable channel while keeping the rest of the modules

     

       27
       27
       +
         and packages from the original nixos channel. This only overrides the module

     

       28
       28
       +
         definition, this won't use postgresql from nixos-unstable unless explicitly

     

       29
       29
       +
         configured to do so.

     

       18
       30
        
        </para>

     

       19
       31
        
       

     

       20
       32
        
       <programlisting>

     
···

       34
       46
        
       </programlisting>

     

       35
       47
        
       

     

       36
       48
        
        <para>

     

       37
       37
       -
         This example shows how to define a custom module as a replacement for an existing module. Importing this module will disable the original module without having to know it's implementation details.

     

       49
       49
       +
         This example shows how to define a custom module as a replacement for an

     

       50
       50
       +
         existing module. Importing this module will disable the original module

     

       51
       51
       +
         without having to know it's implementation details.

     

       38
       52
        
        </para>

     

       39
       53
        
       

     

       40
       54
        
       <programlisting>

+10 -4

nixos/doc/manual/development/running-nixos-tests-interactively.xml

···

       6
       6
        
        <title>Running Tests interactively</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         The test itself can be run interactively. This is particularly useful when developing or debugging a test:

     

       9
       9
       +
         The test itself can be run interactively. This is particularly useful when

     

       10
       10
       +
         developing or debugging a test:

     

       10
       11
        
       <screen>

     

       11
       12
        
       <prompt>$ </prompt>nix-build nixos/tests/login.nix -A driver

     

       12
       13
        
       <prompt>$ </prompt>./result/bin/nixos-test-driver

     
···

       20
       21
        
       <prompt>&gt;</prompt> $machine->succeed("touch /tmp/foo")

     

       21
       22
        
       <prompt>&gt;</prompt> print($machine->succeed("pwd")) # Show stdout of command

     

       22
       23
        
       </screen>

     

       23
       23
       -
         The function <command>testScript</command> executes the entire test script and drops you back into the test driver command line upon its completion. This allows you to inspect the state of the VMs after the test (e.g. to debug the test script).

     

       24
       24
       +
         The function <command>testScript</command> executes the entire test script

     

       25
       25
       +
         and drops you back into the test driver command line upon its completion.

     

       26
       26
       +
         This allows you to inspect the state of the VMs after the test (e.g. to debug

     

       27
       27
       +
         the test script).

     

       24
       28
        
        </para>

     

       25
       29
        
       

     

       26
       30
        
        <para>

     
···

       29
       33
        
       <prompt>$ </prompt>nix-build nixos/tests/login.nix -A driver

     

       30
       34
        
       <prompt>$ </prompt>./result/bin/nixos-run-vms

     

       31
       35
        
       </screen>

     

       32
       32
       -
         The script <command>nixos-run-vms</command> starts the virtual machines defined by test.

     

       36
       36
       +
         The script <command>nixos-run-vms</command> starts the virtual machines

     

       37
       37
       +
         defined by test.

     

       33
       38
        
        </para>

     

       34
       39
        
       

     

       35
       40
        
        <para>

     

       36
       36
       -
         The machine state is kept across VM restarts in <filename>/tmp/vm-state-</filename><varname>machinename</varname>.

     

       41
       41
       +
         The machine state is kept across VM restarts in

     

       42
       42
       +
         <filename>/tmp/vm-state-</filename><varname>machinename</varname>.

     

       37
       43
        
        </para>

     

       38
       44
        
       </section>

+10 -3

nixos/doc/manual/development/running-nixos-tests.xml

···

       6
       6
        
        <title>Running Tests</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         You can run tests using <command>nix-build</command>. For example, to run the test <filename

     

       10
       10
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>, you just do:

     

       9
       9
       +
         You can run tests using <command>nix-build</command>. For example, to run the

     

       10
       10
       +
         test

     

       11
       11
       +
         <filename

     

       12
       12
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>,

     

       13
       13
       +
         you just do:

     

       11
       14
        
       <screen>

     

       12
       15
        
       <prompt>$ </prompt>nix-build '&lt;nixpkgs/nixos/tests/login.nix>'

     

       13
       16
        
       </screen>

     
···

       21
       24
        
       …

     

       22
       25
        
       6 out of 6 tests succeeded

     

       23
       26
        
       </screen>

     

       24
       24
       -
         After building/downloading all required dependencies, this will perform a build that starts a QEMU/KVM virtual machine containing a NixOS system. The virtual machine mounts the Nix store of the host; this makes VM creation very fast, as no disk image needs to be created. Afterwards, you can view a pretty-printed log of the test:

     

       27
       27
       +
         After building/downloading all required dependencies, this will perform a

     

       28
       28
       +
         build that starts a QEMU/KVM virtual machine containing a NixOS system. The

     

       29
       29
       +
         virtual machine mounts the Nix store of the host; this makes VM creation very

     

       30
       30
       +
         fast, as no disk image needs to be created. Afterwards, you can view a

     

       31
       31
       +
         pretty-printed log of the test:

     

       25
       32
        
       <screen>

     

       26
       33
        
       <prompt>$ </prompt>firefox result/log.html

     

       27
       34
        
       </screen>

+39 -9

nixos/doc/manual/development/sources.xml

···

       5
       5
        
               xml:id="sec-getting-sources">

     

       6
       6
        
        <title>Getting the Sources</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         By default, NixOS’s <command>nixos-rebuild</command> command uses the NixOS and Nixpkgs sources provided by the <literal>nixos</literal> channel (kept in <filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>). To modify NixOS, however, you should check out the latest sources from Git. This is as follows:

     

       8
       8
       +
         By default, NixOS’s <command>nixos-rebuild</command> command uses the NixOS

     

       9
       9
       +
         and Nixpkgs sources provided by the <literal>nixos</literal> channel (kept in

     

       10
       10
       +
         <filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>). To

     

       11
       11
       +
         modify NixOS, however, you should check out the latest sources from Git. This

     

       12
       12
       +
         is as follows:

     

       9
       13
        
       <screen>

     

       10
       14
        
       <prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs

     

       11
       15
        
       <prompt>$ </prompt>cd nixpkgs

     

       12
       16
        
       <prompt>$ </prompt>git remote add channels https://github.com/NixOS/nixpkgs-channels

     

       13
       17
        
       <prompt>$ </prompt>git remote update channels

     

       14
       18
        
       </screen>

     

       15
       15
       -
         This will check out the latest Nixpkgs sources to <filename>./nixpkgs</filename> the NixOS sources to <filename>./nixpkgs/nixos</filename>. (The NixOS source tree lives in a subdirectory of the Nixpkgs repository.) The remote <literal>channels</literal> refers to a read-only repository that tracks the Nixpkgs/NixOS channels (see <xref linkend="sec-upgrading"/> for more information about channels). Thus, the Git branch <literal>channels/nixos-17.03</literal> will contain the latest built and tested version available in the <literal>nixos-17.03</literal> channel.

     

       19
       19
       +
         This will check out the latest Nixpkgs sources to

     

       20
       20
       +
         <filename>./nixpkgs</filename> the NixOS sources to

     

       21
       21
       +
         <filename>./nixpkgs/nixos</filename>. (The NixOS source tree lives in a

     

       22
       22
       +
         subdirectory of the Nixpkgs repository.) The remote

     

       23
       23
       +
         <literal>channels</literal> refers to a read-only repository that tracks the

     

       24
       24
       +
         Nixpkgs/NixOS channels (see <xref linkend="sec-upgrading"/> for more

     

       25
       25
       +
         information about channels). Thus, the Git branch

     

       26
       26
       +
         <literal>channels/nixos-17.03</literal> will contain the latest built and

     

       27
       27
       +
         tested version available in the <literal>nixos-17.03</literal> channel.

     

       16
       28
        
        </para>

     

       17
       29
        
        <para>

     

       18
       18
       -
         It’s often inconvenient to develop directly on the master branch, since if somebody has just committed (say) a change to GCC, then the binary cache may not have caught up yet and you’ll have to rebuild everything from source. So you may want to create a local branch based on your current NixOS version:

     

       30
       30
       +
         It’s often inconvenient to develop directly on the master branch, since if

     

       31
       31
       +
         somebody has just committed (say) a change to GCC, then the binary cache may

     

       32
       32
       +
         not have caught up yet and you’ll have to rebuild everything from source.

     

       33
       33
       +
         So you may want to create a local branch based on your current NixOS version:

     

       19
       34
        
       <screen>

     

       20
       35
        
       <prompt>$ </prompt>nixos-version

     

       21
       36
        
       17.09pre104379.6e0b727 (Hummingbird)

     

       22
       37
        
       

     

       23
       38
        
       <prompt>$ </prompt>git checkout -b local 6e0b727

     

       24
       39
        
       </screen>

     

       25
       25
       -
         Or, to base your local branch on the latest version available in a NixOS channel:

     

       40
       40
       +
         Or, to base your local branch on the latest version available in a NixOS

     

       41
       41
       +
         channel:

     

       26
       42
        
       <screen>

     

       27
       43
        
       <prompt>$ </prompt>git remote update channels

     

       28
       44
        
       <prompt>$ </prompt>git checkout -b local channels/nixos-17.03

     

       29
       45
        
       </screen>

     

       30
       30
       -
         (Replace <literal>nixos-17.03</literal> with the name of the channel you want to use.) You can use <command>git merge</command> or <command>git rebase</command> to keep your local branch in sync with the channel, e.g.

     

       46
       46
       +
         (Replace <literal>nixos-17.03</literal> with the name of the channel you want

     

       47
       47
       +
         to use.) You can use <command>git merge</command> or <command>git

     

       48
       48
       +
         rebase</command> to keep your local branch in sync with the channel, e.g.

     

       31
       49
        
       <screen>

     

       32
       50
        
       <prompt>$ </prompt>git remote update channels

     

       33
       51
        
       <prompt>$ </prompt>git merge channels/nixos-17.03

     

       34
       52
        
       </screen>

     

       35
       35
       -
         You can use <command>git cherry-pick</command> to copy commits from your local branch to the upstream branch.

     

       53
       53
       +
         You can use <command>git cherry-pick</command> to copy commits from your

     

       54
       54
       +
         local branch to the upstream branch.

     

       36
       55
        
        </para>

     

       37
       56
        
        <para>

     

       38
       38
       -
         If you want to rebuild your system using your (modified) sources, you need to tell <command>nixos-rebuild</command> about them using the <option>-I</option> flag:

     

       57
       57
       +
         If you want to rebuild your system using your (modified) sources, you need to

     

       58
       58
       +
         tell <command>nixos-rebuild</command> about them using the

     

       59
       59
       +
         <option>-I</option> flag:

     

       39
       60
        
       <screen>

     

       40
       61
        
       <prompt># </prompt>nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs

     

       41
       62
        
       </screen>

     

       42
       63
        
        </para>

     

       43
       64
        
        <para>

     

       44
       44
       -
         If you want <command>nix-env</command> to use the expressions in <replaceable>/my/sources</replaceable>, use <command>nix-env -f <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change the default by adding a symlink in <filename>~/.nix-defexpr</filename>:

     

       65
       65
       +
         If you want <command>nix-env</command> to use the expressions in

     

       66
       66
       +
         <replaceable>/my/sources</replaceable>, use <command>nix-env -f

     

       67
       67
       +
         <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change the

     

       68
       68
       +
         default by adding a symlink in <filename>~/.nix-defexpr</filename>:

     

       45
       69
        
       <screen>

     

       46
       70
        
       <prompt>$ </prompt>ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs

     

       47
       71
        
       </screen>

     

       48
       48
       -
         You may want to delete the symlink <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s NixOS channel from clashing with your own tree (this may break the command-not-found utility though). If you want to go back to the default state, you may just remove the <filename>~/.nix-defexpr</filename> directory completely, log out and log in again and it should have been recreated with a link to the root channels.

     

       72
       72
       +
         You may want to delete the symlink

     

       73
       73
       +
         <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s NixOS

     

       74
       74
       +
         channel from clashing with your own tree (this may break the

     

       75
       75
       +
         command-not-found utility though). If you want to go back to the default

     

       76
       76
       +
         state, you may just remove the <filename>~/.nix-defexpr</filename> directory

     

       77
       77
       +
         completely, log out and log in again and it should have been recreated with a

     

       78
       78
       +
         link to the root channels.

     

       49
       79
        
        </para>

     

       50
       80
        
       <!-- FIXME: not sure what this means.

     

       51
       81
        
       <para>You should not pass the base directory

+4 -2

nixos/doc/manual/development/testing-installer.xml

···

       5
       5
        
               xml:id="ch-testing-installer">

     

       6
       6
        
        <title>Testing the Installer</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         Building, burning, and booting from an installation CD is rather tedious, so here is a quick way to see if the installer works properly:

     

       8
       8
       +
         Building, burning, and booting from an installation CD is rather tedious, so

     

       9
       9
       +
         here is a quick way to see if the installer works properly:

     

       9
       10
        
       <screen>

     

       10
       11
        
       <prompt># </prompt>mount -t tmpfs none /mnt

     

       11
       12
        
       <prompt># </prompt>nixos-generate-config --root /mnt

     

       12
       13
        
       <prompt>$ </prompt>nix-build '&lt;nixpkgs/nixos>' -A config.system.build.nixos-install

     

       13
       14
        
       <prompt># </prompt>./result/bin/nixos-install</screen>

     

       14
       14
       -
         To start a login shell in the new NixOS installation in <filename>/mnt</filename>:

     

       15
       15
       +
         To start a login shell in the new NixOS installation in

     

       16
       16
       +
         <filename>/mnt</filename>:

     

       15
       17
        
       <screen>

     

       16
       18
        
       <prompt>$ </prompt>nix-build '&lt;nixpkgs/nixos>' -A config.system.build.nixos-enter

     

       17
       19
        
       <prompt># </prompt>./result/bin/nixos-enter

+56 -18

nixos/doc/manual/development/writing-documentation.xml

···

       5
       5
        
               xml:id="sec-writing-documentation">

     

       6
       6
        
        <title>Writing NixOS Documentation</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         As NixOS grows, so too does the need for a catalogue and explanation of its extensive functionality. Collecting pertinent information from disparate sources and presenting it in an accessible style would be a worthy contribution to the project.

     

       8
       8
       +
         As NixOS grows, so too does the need for a catalogue and explanation of its

     

       9
       9
       +
         extensive functionality. Collecting pertinent information from disparate

     

       10
       10
       +
         sources and presenting it in an accessible style would be a worthy

     

       11
       11
       +
         contribution to the project.

     

       9
       12
        
        </para>

     

       10
       13
        
        <section xml:id="sec-writing-docs-building-the-manual">

     

       11
       14
        
         <title>Building the Manual</title>

     

       12
       15
        
       

     

       13
       16
        
         <para>

     

       14
       14
       -
          The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link> subdirectory of the Nixpkgs repository.

     

       17
       17
       +
          The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the

     

       18
       18
       +
          <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>

     

       19
       19
       +
          subdirectory of the Nixpkgs repository.

     

       15
       20
        
         </para>

     

       16
       21
        
       

     

       17
       22
        
         <para>

     
···

       24
       29
        
       </screen>

     

       25
       30
        
       

     

       26
       31
        
         <para>

     

       27
       27
       -
          Once you are done making modifications to the manual, it's important to build it before committing. You can do that as follows:

     

       32
       32
       +
          Once you are done making modifications to the manual, it's important to

     

       33
       33
       +
          build it before committing. You can do that as follows:

     

       28
       34
        
         </para>

     

       29
       35
        
       

     

       30
       36
        
       <screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>

     

       31
       37
        
       

     

       32
       38
        
         <para>

     

       33
       33
       -
          When this command successfully finishes, it will tell you where the manual got generated. The HTML will be accessible through the <filename>result</filename> symlink at <filename>./result/share/doc/nixos/index.html</filename>.

     

       39
       39
       +
          When this command successfully finishes, it will tell you where the manual

     

       40
       40
       +
          got generated. The HTML will be accessible through the

     

       41
       41
       +
          <filename>result</filename> symlink at

     

       42
       42
       +
          <filename>./result/share/doc/nixos/index.html</filename>.

     

       34
       43
        
         </para>

     

       35
       44
        
        </section>

     

       36
       45
        
        <section xml:id="sec-writing-docs-editing-docbook-xml">

     

       37
       46
        
         <title>Editing DocBook XML</title>

     

       38
       47
        
       

     

       39
       48
        
         <para>

     

       40
       40
       -
          For general information on how to write in DocBook, see <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html"> DocBook 5: The Definitive Guide</link>.

     

       49
       49
       +
          For general information on how to write in DocBook, see

     

       50
       50
       +
          <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html"> DocBook

     

       51
       51
       +
          5: The Definitive Guide</link>.

     

       41
       52
        
         </para>

     

       42
       53
        
       

     

       43
       54
        
         <para>

     

       44
       44
       -
          Emacs nXML Mode is very helpful for editing DocBook XML because it validates the document as you write, and precisely locates errors. To use it, see <xref linkend="sec-emacs-docbook-xml"/>.

     

       55
       55
       +
          Emacs nXML Mode is very helpful for editing DocBook XML because it validates

     

       56
       56
       +
          the document as you write, and precisely locates errors. To use it, see

     

       57
       57
       +
          <xref linkend="sec-emacs-docbook-xml"/>.

     

       45
       58
        
         </para>

     

       46
       59
        
       

     

       47
       60
        
         <para>

     

       48
       48
       -
          <link xlink:href="http://pandoc.org">Pandoc</link> can generate DocBook XML from a multitude of formats, which makes a good starting point.

     

       61
       61
       +
          <link xlink:href="http://pandoc.org">Pandoc</link> can generate DocBook XML

     

       62
       62
       +
          from a multitude of formats, which makes a good starting point.

     

       49
       63
        
          <example xml:id="ex-pandoc-xml-conv">

     

       50
       64
        
           <title>Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML</title>

     

       51
       65
        
       <screen>pandoc -f markdown_github -t docbook5 docs.md -o my-section.md</screen>

     

       52
       66
        
          </example>

     

       53
       53
       -
          Pandoc can also quickly convert a single <filename>section.xml</filename> to HTML, which is helpful when drafting.

     

       67
       67
       +
          Pandoc can also quickly convert a single <filename>section.xml</filename> to

     

       68
       68
       +
          HTML, which is helpful when drafting.

     

       54
       69
        
         </para>

     

       55
       70
        
       

     

       56
       71
        
         <para>

     

       57
       57
       -
          Sometimes writing valid DocBook is simply too difficult. In this case, submit your documentation updates in a <link

     

       58
       58
       -
         xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub Issue</link> and someone will handle the conversion to XML for you.

     

       72
       72
       +
          Sometimes writing valid DocBook is simply too difficult. In this case,

     

       73
       73
       +
          submit your documentation updates in a

     

       74
       74
       +
          <link

     

       75
       75
       +
         xlink:href="https://github.com/NixOS/nixpkgs/issues/new">GitHub

     

       76
       76
       +
          Issue</link> and someone will handle the conversion to XML for you.

     

       59
       77
        
         </para>

     

       60
       78
        
        </section>

     

       61
       79
        
        <section xml:id="sec-writing-docs-creating-a-topic">

     

       62
       80
        
         <title>Creating a Topic</title>

     

       63
       81
        
       

     

       64
       82
        
         <para>

     

       65
       65
       -
          You can use an existing topic as a basis for the new topic or create a topic from scratch.

     

       83
       83
       +
          You can use an existing topic as a basis for the new topic or create a topic

     

       84
       84
       +
          from scratch.

     

       66
       85
        
         </para>

     

       67
       86
        
       

     

       68
       87
        
         <para>

     
···

       70
       89
        
          <itemizedlist>

     

       71
       90
        
           <listitem>

     

       72
       91
        
            <para>

     

       73
       73
       -
             The NixOS <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link> element is in <filename>nixos/doc/manual/manual.xml</filename>. It includes several <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link> which are in subdirectories.

     

       92
       92
       +
             The NixOS

     

       93
       93
       +
             <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>book</tag></link>

     

       94
       94
       +
             element is in <filename>nixos/doc/manual/manual.xml</filename>. It

     

       95
       95
       +
             includes several

     

       96
       96
       +
             <link xlink:href="http://www.docbook.org/tdg5/en/html/book.html"><tag>part</tag>s</link>

     

       97
       97
       +
             which are in subdirectories.

     

       74
       98
        
            </para>

     

       75
       99
        
           </listitem>

     

       76
       100
        
           <listitem>

     

       77
       101
        
            <para>

     

       78
       78
       -
             Store the topic file in the same directory as the <tag>part</tag> to which it belongs. If your topic is about configuring a NixOS module, then the XML file can be stored alongside the module definition <filename>nix</filename> file.

     

       102
       102
       +
             Store the topic file in the same directory as the <tag>part</tag> to

     

       103
       103
       +
             which it belongs. If your topic is about configuring a NixOS module, then

     

       104
       104
       +
             the XML file can be stored alongside the module definition

     

       105
       105
       +
             <filename>nix</filename> file.

     

       79
       106
        
            </para>

     

       80
       107
        
           </listitem>

     

       81
       108
        
           <listitem>

     

       82
       109
        
            <para>

     

       83
       83
       -
             If you include multiple words in the file name, separate the words with a dash. For example: <filename>ipv6-config.xml</filename>.

     

       110
       110
       +
             If you include multiple words in the file name, separate the words with a

     

       111
       111
       +
             dash. For example: <filename>ipv6-config.xml</filename>.

     

       84
       112
        
            </para>

     

       85
       113
        
           </listitem>

     

       86
       114
        
           <listitem>

     

       87
       115
        
            <para>

     

       88
       88
       -
             Make sure that the <tag>xml:id</tag> value is unique. You can use abbreviations if the ID is too long. For example: <varname>nixos-config</varname>.

     

       116
       116
       +
             Make sure that the <tag>xml:id</tag> value is unique. You can use

     

       117
       117
       +
             abbreviations if the ID is too long. For example:

     

       118
       118
       +
             <varname>nixos-config</varname>.

     

       89
       119
        
            </para>

     

       90
       120
        
           </listitem>

     

       91
       121
        
           <listitem>

     

       92
       122
        
            <para>

     

       93
       93
       -
             Determine whether your topic is a chapter or a section. If you are unsure, open an existing topic file and check whether the main element is chapter or section.

     

       123
       123
       +
             Determine whether your topic is a chapter or a section. If you are

     

       124
       124
       +
             unsure, open an existing topic file and check whether the main element is

     

       125
       125
       +
             chapter or section.

     

       94
       126
        
            </para>

     

       95
       127
        
           </listitem>

     

       96
       128
        
          </itemizedlist>

     
···

       100
       132
        
         <title>Adding a Topic to the Book</title>

     

       101
       133
        
       

     

       102
       134
        
         <para>

     

       103
       103
       -
          Open the parent XML file and add an <varname>xi:include</varname> element to the list of chapters with the file name of the topic that you created. If you created a <tag>section</tag>, you add the file to the <tag>chapter</tag> file. If you created a <tag>chapter</tag>, you add the file to the <tag>part</tag> file.

     

       135
       135
       +
          Open the parent XML file and add an <varname>xi:include</varname> element to

     

       136
       136
       +
          the list of chapters with the file name of the topic that you created. If

     

       137
       137
       +
          you created a <tag>section</tag>, you add the file to the <tag>chapter</tag>

     

       138
       138
       +
          file. If you created a <tag>chapter</tag>, you add the file to the

     

       139
       139
       +
          <tag>part</tag> file.

     

       104
       140
        
         </para>

     

       105
       141
        
       

     

       106
       142
        
         <para>

     

       107
       107
       -
          If the topic is about configuring a NixOS module, it can be automatically included in the manual by using the <varname>meta.doc</varname> attribute. See <xref

     

       143
       143
       +
          If the topic is about configuring a NixOS module, it can be automatically

     

       144
       144
       +
          included in the manual by using the <varname>meta.doc</varname> attribute.

     

       145
       145
       +
          See <xref

     

       108
       146
        
         linkend="sec-meta-attributes"/> for an explanation.

     

       109
       147
        
         </para>

     

       110
       148
        
        </section>

+56 -13

nixos/doc/manual/development/writing-modules.xml

···

       5
       5
        
               xml:id="sec-writing-modules">

     

       6
       6
        
        <title>Writing NixOS Modules</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         NixOS has a modular system for declarative configuration. This system combines multiple <emphasis>modules</emphasis> to produce the full system configuration. One of the modules that constitute the configuration is <filename>/etc/nixos/configuration.nix</filename>. Most of the others live in the <link

     

       9
       9
       -
       xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"><filename>nixos/modules</filename></link> subdirectory of the Nixpkgs tree.

     

       8
       8
       +
         NixOS has a modular system for declarative configuration. This system

     

       9
       9
       +
         combines multiple <emphasis>modules</emphasis> to produce the full system

     

       10
       10
       +
         configuration. One of the modules that constitute the configuration is

     

       11
       11
       +
         <filename>/etc/nixos/configuration.nix</filename>. Most of the others live in

     

       12
       12
       +
         the

     

       13
       13
       +
         <link

     

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

     

       15
       15
       +
         subdirectory of the Nixpkgs tree.

     

       10
       16
        
        </para>

     

       11
       17
        
        <para>

     

       12
       12
       -
         Each NixOS module is a file that handles one logical aspect of the configuration, such as a specific kind of hardware, a service, or network settings. A module configuration does not have to handle everything from scratch; it can use the functionality provided by other modules for its implementation. Thus a module can <emphasis>declare</emphasis> options that can be used by other modules, and conversely can <emphasis>define</emphasis> options provided by other modules in its own implementation. For example, the module <link

     

       13
       13
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link> declares the option <option>security.pam.services</option> that allows other modules (e.g. <link

     

       14
       14
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>) to define PAM services; and it defines the option <option>environment.etc</option> (declared by <link

     

       15
       15
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>) to cause files to be created in <filename>/etc/pam.d</filename>.

     

       18
       18
       +
         Each NixOS module is a file that handles one logical aspect of the

     

       19
       19
       +
         configuration, such as a specific kind of hardware, a service, or network

     

       20
       20
       +
         settings. A module configuration does not have to handle everything from

     

       21
       21
       +
         scratch; it can use the functionality provided by other modules for its

     

       22
       22
       +
         implementation. Thus a module can <emphasis>declare</emphasis> options that

     

       23
       23
       +
         can be used by other modules, and conversely can <emphasis>define</emphasis>

     

       24
       24
       +
         options provided by other modules in its own implementation. For example, the

     

       25
       25
       +
         module

     

       26
       26
       +
         <link

     

       27
       27
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link>

     

       28
       28
       +
         declares the option <option>security.pam.services</option> that allows other

     

       29
       29
       +
         modules (e.g.

     

       30
       30
       +
         <link

     

       31
       31
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>)

     

       32
       32
       +
         to define PAM services; and it defines the option

     

       33
       33
       +
         <option>environment.etc</option> (declared by

     

       34
       34
       +
         <link

     

       35
       35
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>)

     

       36
       36
       +
         to cause files to be created in <filename>/etc/pam.d</filename>.

     

       16
       37
        
        </para>

     

       17
       38
        
        <para xml:id="para-module-syn">

     

       18
       39
        
         In <xref

     

       19
       19
       -
       linkend="sec-configuration-syntax"/>, we saw the following structure of NixOS modules:

     

       40
       40
       +
       linkend="sec-configuration-syntax"/>, we saw the following structure

     

       41
       41
       +
         of NixOS modules:

     

       20
       42
        
       <programlisting>

     

       21
       43
        
       { config, pkgs, ... }:

     

       22
       44
        
       

     

       23
       45
        
       { <replaceable>option definitions</replaceable>

     

       24
       46
        
       }

     

       25
       47
        
       </programlisting>

     

       26
       26
       -
         This is actually an <emphasis>abbreviated</emphasis> form of module that only defines options, but does not declare any. The structure of full NixOS modules is shown in <xref linkend='ex-module-syntax' />.

     

       48
       48
       +
         This is actually an <emphasis>abbreviated</emphasis> form of module that only

     

       49
       49
       +
         defines options, but does not declare any. The structure of full NixOS

     

       50
       50
       +
         modules is shown in <xref linkend='ex-module-syntax' />.

     

       27
       51
        
        </para>

     

       28
       52
        
        <example xml:id='ex-module-syntax'>

     

       29
       53
        
         <title>Structure of NixOS Modules</title>

     
···

       49
       73
        
         <calloutlist>

     

       50
       74
        
          <callout arearefs='module-syntax-1'>

     

       51
       75
        
           <para>

     

       52
       52
       -
            This line makes the current Nix expression a function. The variable <varname>pkgs</varname> contains Nixpkgs, while <varname>config</varname> contains the full system configuration. This line can be omitted if there is no reference to <varname>pkgs</varname> and <varname>config</varname> inside the module.

     

       76
       76
       +
            This line makes the current Nix expression a function. The variable

     

       77
       77
       +
            <varname>pkgs</varname> contains Nixpkgs, while <varname>config</varname>

     

       78
       78
       +
            contains the full system configuration. This line can be omitted if there

     

       79
       79
       +
            is no reference to <varname>pkgs</varname> and <varname>config</varname>

     

       80
       80
       +
            inside the module.

     

       53
       81
        
           </para>

     

       54
       82
        
          </callout>

     

       55
       83
        
          <callout arearefs='module-syntax-2'>

     

       56
       84
        
           <para>

     

       57
       57
       -
            This list enumerates the paths to other NixOS modules that should be included in the evaluation of the system configuration. A default set of modules is defined in the file <filename>modules/module-list.nix</filename>. These don't need to be added in the import list.

     

       85
       85
       +
            This list enumerates the paths to other NixOS modules that should be

     

       86
       86
       +
            included in the evaluation of the system configuration. A default set of

     

       87
       87
       +
            modules is defined in the file

     

       88
       88
       +
            <filename>modules/module-list.nix</filename>. These don't need to be added

     

       89
       89
       +
            in the import list.

     

       58
       90
        
           </para>

     

       59
       91
        
          </callout>

     

       60
       92
        
          <callout arearefs='module-syntax-3'>

     

       61
       93
        
           <para>

     

       62
       62
       -
            The attribute <varname>options</varname> is a nested set of <emphasis>option declarations</emphasis> (described below).

     

       94
       94
       +
            The attribute <varname>options</varname> is a nested set of

     

       95
       95
       +
            <emphasis>option declarations</emphasis> (described below).

     

       63
       96
        
           </para>

     

       64
       97
        
          </callout>

     

       65
       98
        
          <callout arearefs='module-syntax-4'>

     

       66
       99
        
           <para>

     

       67
       67
       -
            The attribute <varname>config</varname> is a nested set of <emphasis>option definitions</emphasis> (also described below).

     

       100
       100
       +
            The attribute <varname>config</varname> is a nested set of

     

       101
       101
       +
            <emphasis>option definitions</emphasis> (also described below).

     

       68
       102
        
           </para>

     

       69
       103
        
          </callout>

     

       70
       104
        
         </calloutlist>

     

       71
       105
        
        </para>

     

       72
       106
        
        <para>

     

       73
       73
       -
         <xref linkend='locate-example' /> shows a module that handles the regular update of the “locate” database, an index of all files in the file system. This module declares two options that can be defined by other modules (typically the user’s <filename>configuration.nix</filename>): <option>services.locate.enable</option> (whether the database should be updated) and <option>services.locate.interval</option> (when the update should be done). It implements its functionality by defining two options declared by other modules: <option>systemd.services</option> (the set of all systemd services) and <option>systemd.timers</option> (the list of commands to be executed periodically by <command>systemd</command>).

     

       107
       107
       +
         <xref linkend='locate-example' /> shows a module that handles the regular

     

       108
       108
       +
         update of the “locate” database, an index of all files in the file

     

       109
       109
       +
         system. This module declares two options that can be defined by other modules

     

       110
       110
       +
         (typically the user’s <filename>configuration.nix</filename>):

     

       111
       111
       +
         <option>services.locate.enable</option> (whether the database should be

     

       112
       112
       +
         updated) and <option>services.locate.interval</option> (when the update

     

       113
       113
       +
         should be done). It implements its functionality by defining two options

     

       114
       114
       +
         declared by other modules: <option>systemd.services</option> (the set of all

     

       115
       115
       +
         systemd services) and <option>systemd.timers</option> (the list of commands

     

       116
       116
       +
         to be executed periodically by <command>systemd</command>).

     

       74
       117
        
        </para>

     

       75
       118
        
        <example xml:id='locate-example'>

     

       76
       119
        
         <title>NixOS Module for the “locate” Service</title>

+84 -29

nixos/doc/manual/development/writing-nixos-tests.xml

···

       31
       31
        
           '';

     

       32
       32
        
       }

     

       33
       33
        
       </programlisting>

     

       34
       34
       -
         The attribute <literal>testScript</literal> is a bit of Perl code that executes the test (described below). During the test, it will start one or more virtual machines, the configuration of which is described by the attribute <literal>machine</literal> (if you need only one machine in your test) or by the attribute <literal>nodes</literal> (if you need multiple machines). For instance, <filename

     

       35
       35
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename> only needs a single machine to test whether users can log in on the virtual console, whether device ownership is correctly maintained when switching between consoles, and so on. On the other hand, <filename

     

       36
       36
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs.nix">nfs.nix</filename>, which tests NFS client and server functionality in the Linux kernel (including whether locks are maintained across server crashes), requires three machines: a server and two clients.

     

       34
       34
       +
         The attribute <literal>testScript</literal> is a bit of Perl code that

     

       35
       35
       +
         executes the test (described below). During the test, it will start one or

     

       36
       36
       +
         more virtual machines, the configuration of which is described by the

     

       37
       37
       +
         attribute <literal>machine</literal> (if you need only one machine in your

     

       38
       38
       +
         test) or by the attribute <literal>nodes</literal> (if you need multiple

     

       39
       39
       +
         machines). For instance,

     

       40
       40
       +
         <filename

     

       41
       41
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>

     

       42
       42
       +
         only needs a single machine to test whether users can log in on the virtual

     

       43
       43
       +
         console, whether device ownership is correctly maintained when switching

     

       44
       44
       +
         between consoles, and so on. On the other hand,

     

       45
       45
       +
         <filename

     

       46
       46
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs.nix">nfs.nix</filename>,

     

       47
       47
       +
         which tests NFS client and server functionality in the Linux kernel

     

       48
       48
       +
         (including whether locks are maintained across server crashes), requires

     

       49
       49
       +
         three machines: a server and two clients.

     

       37
       50
        
        </para>

     

       38
       51
        
       

     

       39
       52
        
        <para>

     
···

       56
       69
        
           </term>

     

       57
       70
        
           <listitem>

     

       58
       71
        
            <para>

     

       59
       59
       -
             The virtual networks to which the VM is connected. See <filename

     

       60
       60
       -
           xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nat.nix">nat.nix</filename> for an example.

     

       72
       72
       +
             The virtual networks to which the VM is connected. See

     

       73
       73
       +
             <filename

     

       74
       74
       +
           xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nat.nix">nat.nix</filename>

     

       75
       75
       +
             for an example.

     

       61
       76
        
            </para>

     

       62
       77
        
           </listitem>

     

       63
       78
        
          </varlistentry>

     
···

       67
       82
        
           </term>

     

       68
       83
        
           <listitem>

     

       69
       84
        
            <para>

     

       70
       70
       -
             By default, the Nix store in the VM is not writable. If you enable this option, a writable union file system is mounted on top of the Nix store to make it appear writable. This is necessary for tests that run Nix operations that modify the store.

     

       85
       85
       +
             By default, the Nix store in the VM is not writable. If you enable this

     

       86
       86
       +
             option, a writable union file system is mounted on top of the Nix store

     

       87
       87
       +
             to make it appear writable. This is necessary for tests that run Nix

     

       88
       88
       +
             operations that modify the store.

     

       71
       89
        
            </para>

     

       72
       90
        
           </listitem>

     

       73
       91
        
          </varlistentry>

     

       74
       92
        
         </variablelist>

     

       75
       75
       -
         For more options, see the module <filename

     

       93
       93
       +
         For more options, see the module

     

       94
       94
       +
         <filename

     

       76
       95
        
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix">qemu-vm.nix</filename>.

     

       77
       96
        
        </para>

     

       78
       97
        
       

     

       79
       98
        
        <para>

     

       80
       80
       -
         The test script is a sequence of Perl statements that perform various actions, such as starting VMs, executing commands in the VMs, and so on. Each virtual machine is represented as an object stored in the variable <literal>$<replaceable>name</replaceable></literal>, where <replaceable>name</replaceable> is the identifier of the machine (which is just <literal>machine</literal> if you didn’t specify multiple machines using the <literal>nodes</literal> attribute). For instance, the following starts the machine, waits until it has finished booting, then executes a command and checks that the output is more-or-less correct:

     

       99
       99
       +
         The test script is a sequence of Perl statements that perform various

     

       100
       100
       +
         actions, such as starting VMs, executing commands in the VMs, and so on. Each

     

       101
       101
       +
         virtual machine is represented as an object stored in the variable

     

       102
       102
       +
         <literal>$<replaceable>name</replaceable></literal>, where

     

       103
       103
       +
         <replaceable>name</replaceable> is the identifier of the machine (which is

     

       104
       104
       +
         just <literal>machine</literal> if you didn’t specify multiple machines

     

       105
       105
       +
         using the <literal>nodes</literal> attribute). For instance, the following

     

       106
       106
       +
         starts the machine, waits until it has finished booting, then executes a

     

       107
       107
       +
         command and checks that the output is more-or-less correct:

     

       81
       108
        
       <programlisting>

     

       82
       109
        
       $machine->start;

     

       83
       110
        
       $machine->waitForUnit("default.target");

     

       84
       111
        
       $machine->succeed("uname") =~ /Linux/ or die;

     

       85
       112
        
       </programlisting>

     

       86
       86
       -
         The first line is actually unnecessary; machines are implicitly started when you first execute an action on them (such as <literal>waitForUnit</literal> or <literal>succeed</literal>). If you have multiple machines, you can speed up the test by starting them in parallel:

     

       113
       113
       +
         The first line is actually unnecessary; machines are implicitly started when

     

       114
       114
       +
         you first execute an action on them (such as <literal>waitForUnit</literal>

     

       115
       115
       +
         or <literal>succeed</literal>). If you have multiple machines, you can speed

     

       116
       116
       +
         up the test by starting them in parallel:

     

       87
       117
        
       <programlisting>

     

       88
       118
        
       startAll;

     

       89
       119
        
       </programlisting>

     
···

       98
       128
        
           </term>

     

       99
       129
        
           <listitem>

     

       100
       130
        
            <para>

     

       101
       101
       -
             Start the virtual machine. This method is asynchronous — it does not wait for the machine to finish booting.

     

       131
       131
       +
             Start the virtual machine. This method is asynchronous — it does not

     

       132
       132
       +
             wait for the machine to finish booting.

     

       102
       133
        
            </para>

     

       103
       134
        
           </listitem>

     

       104
       135
        
          </varlistentry>

     
···

       128
       159
        
           </term>

     

       129
       160
        
           <listitem>

     

       130
       161
        
            <para>

     

       131
       131
       -
             Simulate unplugging the Ethernet cable that connects the machine to the other machines.

     

       162
       162
       +
             Simulate unplugging the Ethernet cable that connects the machine to the

     

       163
       163
       +
             other machines.

     

       132
       164
        
            </para>

     

       133
       165
        
           </listitem>

     

       134
       166
        
          </varlistentry>

     
···

       148
       180
        
           </term>

     

       149
       181
        
           <listitem>

     

       150
       182
        
            <para>

     

       151
       151
       -
             Take a picture of the display of the virtual machine, in PNG format. The screenshot is linked from the HTML log.

     

       183
       183
       +
             Take a picture of the display of the virtual machine, in PNG format. The

     

       184
       184
       +
             screenshot is linked from the HTML log.

     

       152
       185
        
            </para>

     

       153
       186
        
           </listitem>

     

       154
       187
        
          </varlistentry>

     
···

       158
       191
        
           </term>

     

       159
       192
        
           <listitem>

     

       160
       193
        
            <para>

     

       161
       161
       -
             Return a textual representation of what is currently visible on the machine's screen using optical character recognition.

     

       194
       194
       +
             Return a textual representation of what is currently visible on the

     

       195
       195
       +
             machine's screen using optical character recognition.

     

       162
       196
        
            </para>

     

       163
       197
        
            <note>

     

       164
       198
        
             <para>

     

       165
       165
       -
              This requires passing <option>enableOCR</option> to the test attribute set.

     

       199
       199
       +
              This requires passing <option>enableOCR</option> to the test attribute

     

       200
       200
       +
              set.

     

       166
       201
        
             </para>

     

       167
       202
        
            </note>

     

       168
       203
        
           </listitem>

     
···

       173
       208
        
           </term>

     

       174
       209
        
           <listitem>

     

       175
       210
        
            <para>

     

       176
       176
       -
             Send a command to the QEMU monitor. This is rarely used, but allows doing stuff such as attaching virtual USB disks to a running machine.

     

       211
       211
       +
             Send a command to the QEMU monitor. This is rarely used, but allows doing

     

       212
       212
       +
             stuff such as attaching virtual USB disks to a running machine.

     

       177
       213
        
            </para>

     

       178
       214
        
           </listitem>

     

       179
       215
        
          </varlistentry>

     
···

       183
       219
        
           </term>

     

       184
       220
        
           <listitem>

     

       185
       221
        
            <para>

     

       186
       186
       -
             Simulate pressing keys on the virtual keyboard, e.g., <literal>sendKeys("ctrl-alt-delete")</literal>.

     

       222
       222
       +
             Simulate pressing keys on the virtual keyboard, e.g.,

     

       223
       223
       +
             <literal>sendKeys("ctrl-alt-delete")</literal>.

     

       187
       224
        
            </para>

     

       188
       225
        
           </listitem>

     

       189
       226
        
          </varlistentry>

     
···

       193
       230
        
           </term>

     

       194
       231
        
           <listitem>

     

       195
       232
        
            <para>

     

       196
       196
       -
             Simulate typing a sequence of characters on the virtual keyboard, e.g., <literal>sendKeys("foobar\n")</literal> will type the string <literal>foobar</literal> followed by the Enter key.

     

       233
       233
       +
             Simulate typing a sequence of characters on the virtual keyboard, e.g.,

     

       234
       234
       +
             <literal>sendKeys("foobar\n")</literal> will type the string

     

       235
       235
       +
             <literal>foobar</literal> followed by the Enter key.

     

       197
       236
        
            </para>

     

       198
       237
        
           </listitem>

     

       199
       238
        
          </varlistentry>

     
···

       203
       242
        
           </term>

     

       204
       243
        
           <listitem>

     

       205
       244
        
            <para>

     

       206
       206
       -
             Execute a shell command, returning a list <literal>(<replaceable>status</replaceable>, <replaceable>stdout</replaceable>)</literal>.

     

       245
       245
       +
             Execute a shell command, returning a list

     

       246
       246
       +
             <literal>(<replaceable>status</replaceable>,

     

       247
       247
       +
             <replaceable>stdout</replaceable>)</literal>.

     

       207
       248
        
            </para>

     

       208
       249
        
           </listitem>

     

       209
       250
        
          </varlistentry>

     
···

       213
       254
        
           </term>

     

       214
       255
        
           <listitem>

     

       215
       256
        
            <para>

     

       216
       216
       -
             Execute a shell command, raising an exception if the exit status is not zero, otherwise returning the standard output.

     

       257
       257
       +
             Execute a shell command, raising an exception if the exit status is not

     

       258
       258
       +
             zero, otherwise returning the standard output.

     

       217
       259
        
            </para>

     

       218
       260
        
           </listitem>

     

       219
       261
        
          </varlistentry>

     
···

       223
       265
        
           </term>

     

       224
       266
        
           <listitem>

     

       225
       267
        
            <para>

     

       226
       226
       -
             Like <methodname>succeed</methodname>, but raising an exception if the command returns a zero status.

     

       268
       268
       +
             Like <methodname>succeed</methodname>, but raising an exception if the

     

       269
       269
       +
             command returns a zero status.

     

       227
       270
        
            </para>

     

       228
       271
        
           </listitem>

     

       229
       272
        
          </varlistentry>

     
···

       273
       316
        
           </term>

     

       274
       317
        
           <listitem>

     

       275
       318
        
            <para>

     

       276
       276
       -
             Wait until a process is listening on the given TCP port (on <literal>localhost</literal>, at least).

     

       319
       319
       +
             Wait until a process is listening on the given TCP port (on

     

       320
       320
       +
             <literal>localhost</literal>, at least).

     

       277
       321
        
            </para>

     

       278
       322
        
           </listitem>

     

       279
       323
        
          </varlistentry>

     
···

       303
       347
        
           </term>

     

       304
       348
        
           <listitem>

     

       305
       349
        
            <para>

     

       306
       306
       -
             Wait until the supplied regular expressions matches the textual contents of the screen by using optical character recognition (see <methodname>getScreenText</methodname>).

     

       350
       350
       +
             Wait until the supplied regular expressions matches the textual contents

     

       351
       351
       +
             of the screen by using optical character recognition (see

     

       352
       352
       +
             <methodname>getScreenText</methodname>).

     

       307
       353
        
            </para>

     

       308
       354
        
            <note>

     

       309
       355
        
             <para>

     

       310
       310
       -
              This requires passing <option>enableOCR</option> to the test attribute set.

     

       356
       356
       +
              This requires passing <option>enableOCR</option> to the test attribute

     

       357
       357
       +
              set.

     

       311
       358
        
             </para>

     

       312
       359
        
            </note>

     

       313
       360
        
           </listitem>

     
···

       318
       365
        
           </term>

     

       319
       366
        
           <listitem>

     

       320
       367
        
            <para>

     

       321
       321
       -
             Wait until an X11 window has appeared whose name matches the given regular expression, e.g., <literal>waitForWindow(qr/Terminal/)</literal>.

     

       368
       368
       +
             Wait until an X11 window has appeared whose name matches the given

     

       369
       369
       +
             regular expression, e.g., <literal>waitForWindow(qr/Terminal/)</literal>.

     

       322
       370
        
            </para>

     

       323
       371
        
           </listitem>

     

       324
       372
        
          </varlistentry>

     
···

       328
       376
        
           </term>

     

       329
       377
        
           <listitem>

     

       330
       378
        
            <para>

     

       331
       331
       -
             Copies a file from host to machine, e.g., <literal>copyFileFromHost("myfile", "/etc/my/important/file")</literal>.

     

       379
       379
       +
             Copies a file from host to machine, e.g.,

     

       380
       380
       +
             <literal>copyFileFromHost("myfile", "/etc/my/important/file")</literal>.

     

       332
       381
        
            </para>

     

       333
       382
        
            <para>

     

       334
       334
       -
             The first argument is the file on the host. The file needs to be accessible while building the nix derivation. The second argument is the location of the file on the machine.

     

       383
       383
       +
             The first argument is the file on the host. The file needs to be

     

       384
       384
       +
             accessible while building the nix derivation. The second argument is the

     

       385
       385
       +
             location of the file on the machine.

     

       335
       386
        
            </para>

     

       336
       387
        
           </listitem>

     

       337
       388
        
          </varlistentry>

     
···

       341
       392
        
           </term>

     

       342
       393
        
           <listitem>

     

       343
       394
        
            <para>

     

       344
       344
       -
             Runs <literal>systemctl</literal> commands with optional support for <literal>systemctl --user</literal>

     

       395
       395
       +
             Runs <literal>systemctl</literal> commands with optional support for

     

       396
       396
       +
             <literal>systemctl --user</literal>

     

       345
       397
        
            </para>

     

       346
       398
        
            <para>

     

       347
       399
        
       <programlisting>

     
···

       355
       407
        
        </para>

     

       356
       408
        
       

     

       357
       409
        
        <para>

     

       358
       358
       -
         To test user units declared by <literal>systemd.user.services</literal> the optional <literal>$user</literal> argument can be used:

     

       410
       410
       +
         To test user units declared by <literal>systemd.user.services</literal> the

     

       411
       411
       +
         optional <literal>$user</literal> argument can be used:

     

       359
       412
        
       <programlisting>

     

       360
       413
        
       $machine->start;

     

       361
       414
        
       $machine->waitForX;

     

       362
       415
        
       $machine->waitForUnit("xautolock.service", "x-session-user");

     

       363
       416
        
       </programlisting>

     

       364
       364
       -
         This applies to <literal>systemctl</literal>, <literal>getUnitInfo</literal>, <literal>waitForUnit</literal>, <literal>startJob</literal> and <literal>stopJob</literal>.

     

       417
       417
       +
         This applies to <literal>systemctl</literal>, <literal>getUnitInfo</literal>,

     

       418
       418
       +
         <literal>waitForUnit</literal>, <literal>startJob</literal> and

     

       419
       419
       +
         <literal>stopJob</literal>.

     

       365
       420
        
        </para>

     

       366
       421
        
       </section>

+40 -13

nixos/doc/manual/installation/changing-config.xml

···

       4
       4
        
                xml:id="sec-changing-config">

     

       5
       5
        
        <title>Changing the Configuration</title>

     

       6
       6
        
        <para>

     

       7
       7
       -
         The file <filename>/etc/nixos/configuration.nix</filename> contains the current configuration of your machine. Whenever you’ve <link linkend="ch-configuration">changed something</link> in that file, you should do

     

       7
       7
       +
         The file <filename>/etc/nixos/configuration.nix</filename> contains the

     

       8
       8
       +
         current configuration of your machine. Whenever you’ve

     

       9
       9
       +
         <link linkend="ch-configuration">changed something</link> in that file, you

     

       10
       10
       +
         should do

     

       8
       11
        
       <screen>

     

       9
       12
        
       <prompt># </prompt>nixos-rebuild switch

     

       10
       13
        
       </screen>

     

       11
       11
       -
         to build the new configuration, make it the default configuration for booting, and try to realise the configuration in the running system (e.g., by restarting system services).

     

       14
       14
       +
         to build the new configuration, make it the default configuration for

     

       15
       15
       +
         booting, and try to realise the configuration in the running system (e.g., by

     

       16
       16
       +
         restarting system services).

     

       12
       17
        
         <warning>

     

       13
       18
        
          <para>

     

       14
       14
       -
           This command doesn't start/stop <link linkend="opt-systemd.user.services">user services</link> automatically. <command>nixos-rebuild</command> only runs a <literal>daemon-reload</literal> for each user with running user services.

     

       19
       19
       +
           This command doesn't start/stop <link linkend="opt-systemd.user.services">user

     

       20
       20
       +
           services</link> automatically. <command>nixos-rebuild</command> only runs a

     

       21
       21
       +
           <literal>daemon-reload</literal> for each user with running user services.

     

       15
       22
        
          </para>

     

       16
       23
        
         </warning>

     

       17
       24
        
        </para>

     

       18
       25
        
        <warning>

     

       19
       26
        
         <para>

     

       20
       20
       -
          These commands must be executed as root, so you should either run them from a root shell or by prefixing them with <literal>sudo -i</literal>.

     

       27
       27
       +
          These commands must be executed as root, so you should either run them from

     

       28
       28
       +
          a root shell or by prefixing them with <literal>sudo -i</literal>.

     

       21
       29
        
         </para>

     

       22
       30
        
        </warning>

     

       23
       31
        
        <para>

     
···

       25
       33
        
       <screen>

     

       26
       34
        
       <prompt># </prompt>nixos-rebuild test

     

       27
       35
        
       </screen>

     

       28
       28
       -
         to build the configuration and switch the running system to it, but without making it the boot default. So if (say) the configuration locks up your machine, you can just reboot to get back to a working configuration.

     

       36
       36
       +
         to build the configuration and switch the running system to it, but without

     

       37
       37
       +
         making it the boot default. So if (say) the configuration locks up your

     

       38
       38
       +
         machine, you can just reboot to get back to a working configuration.

     

       29
       39
        
        </para>

     

       30
       40
        
        <para>

     

       31
       41
        
         There is also

     

       32
       42
        
       <screen>

     

       33
       43
        
       <prompt># </prompt>nixos-rebuild boot

     

       34
       44
        
       </screen>

     

       35
       35
       -
         to build the configuration and make it the boot default, but not switch to it now (so it will only take effect after the next reboot).

     

       45
       45
       +
         to build the configuration and make it the boot default, but not switch to it

     

       46
       46
       +
         now (so it will only take effect after the next reboot).

     

       36
       47
        
        </para>

     

       37
       48
        
        <para>

     

       38
       38
       -
         You can make your configuration show up in a different submenu of the GRUB 2 boot screen by giving it a different <emphasis>profile name</emphasis>, e.g.

     

       49
       49
       +
         You can make your configuration show up in a different submenu of the GRUB 2

     

       50
       50
       +
         boot screen by giving it a different <emphasis>profile name</emphasis>, e.g.

     

       39
       51
        
       <screen>

     

       40
       52
        
       <prompt># </prompt>nixos-rebuild switch -p test

     

       41
       53
        
       </screen>

     

       42
       42
       -
         which causes the new configuration (and previous ones created using <literal>-p test</literal>) to show up in the GRUB submenu “NixOS - Profile 'test'”. This can be useful to separate test configurations from “stable” configurations.

     

       54
       54
       +
         which causes the new configuration (and previous ones created using

     

       55
       55
       +
         <literal>-p test</literal>) to show up in the GRUB submenu “NixOS - Profile

     

       56
       56
       +
         'test'”. This can be useful to separate test configurations from

     

       57
       57
       +
         “stable” configurations.

     

       43
       58
        
        </para>

     

       44
       59
        
        <para>

     

       45
       60
        
         Finally, you can do

     

       46
       61
        
       <screen>

     

       47
       62
        
       <prompt>$ </prompt>nixos-rebuild build

     

       48
       63
        
       </screen>

     

       49
       49
       -
         to build the configuration but nothing more. This is useful to see whether everything compiles cleanly.

     

       64
       64
       +
         to build the configuration but nothing more. This is useful to see whether

     

       65
       65
       +
         everything compiles cleanly.

     

       50
       66
        
        </para>

     

       51
       67
        
        <para>

     

       52
       52
       -
         If you have a machine that supports hardware virtualisation, you can also test the new configuration in a sandbox by building and running a QEMU <emphasis>virtual machine</emphasis> that contains the desired configuration. Just do

     

       68
       68
       +
         If you have a machine that supports hardware virtualisation, you can also

     

       69
       69
       +
         test the new configuration in a sandbox by building and running a QEMU

     

       70
       70
       +
         <emphasis>virtual machine</emphasis> that contains the desired configuration.

     

       71
       71
       +
         Just do

     

       53
       72
        
       <screen>

     

       54
       73
        
       <prompt>$ </prompt>nixos-rebuild build-vm

     

       55
       74
        
       <prompt>$ </prompt>./result/bin/run-*-vm

     

       56
       75
        
       </screen>

     

       57
       57
       -
         The VM does not have any data from your host system, so your existing user accounts and home directories will not be available unless you have set <literal>mutableUsers = false</literal>. Another way is to temporarily add the following to your configuration:

     

       76
       76
       +
         The VM does not have any data from your host system, so your existing user

     

       77
       77
       +
         accounts and home directories will not be available unless you have set

     

       78
       78
       +
         <literal>mutableUsers = false</literal>. Another way is to temporarily add

     

       79
       79
       +
         the following to your configuration:

     

       58
       80
        
       <screen>

     

       59
       81
        
       <link linkend="opt-users.users._name__.initialHashedPassword">users.users.your-user.initialHashedPassword</link> = "test";

     

       60
       82
        
       </screen>

     

       61
       61
       -
         <emphasis>Important:</emphasis> delete the $hostname.qcow2 file if you have started the virtual machine at least once without the right users, otherwise the changes will not get picked up. You can forward ports on the host to the guest. For instance, the following will forward host port 2222 to guest port 22 (SSH):

     

       83
       83
       +
         <emphasis>Important:</emphasis> delete the $hostname.qcow2 file if you have

     

       84
       84
       +
         started the virtual machine at least once without the right users, otherwise

     

       85
       85
       +
         the changes will not get picked up. You can forward ports on the host to the

     

       86
       86
       +
         guest. For instance, the following will forward host port 2222 to guest port

     

       87
       87
       +
         22 (SSH):

     

       62
       88
        
       <screen>

     

       63
       89
        
       <prompt>$ </prompt>QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm

     

       64
       90
        
       </screen>

     

       65
       65
       -
         allowing you to log in via SSH (assuming you have set the appropriate passwords or SSH authorized keys):

     

       91
       91
       +
         allowing you to log in via SSH (assuming you have set the appropriate

     

       92
       92
       +
         passwords or SSH authorized keys):

     

       66
       93
        
       <screen>

     

       67
       94
        
       <prompt>$ </prompt>ssh -p 2222 localhost

     

       68
       95
        
       </screen>

+2 -1

nixos/doc/manual/installation/installation.xml

···

       6
       6
        
        <title>Installation</title>

     

       7
       7
        
        <partintro xml:id="ch-installation-intro">

     

       8
       8
        
         <para>

     

       9
       9
       -
          This section describes how to obtain, install, and configure NixOS for first-time use.

     

       9
       9
       +
          This section describes how to obtain, install, and configure NixOS for

     

       10
       10
       +
          first-time use.

     

       10
       11
        
         </para>

     

       11
       12
        
        </partintro>

     

       12
       13
        
        <xi:include href="obtaining.xml" />

+11 -4

nixos/doc/manual/installation/installing-behind-a-proxy.xml

···

       6
       6
        
        <title>Installing behind a proxy</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         To install NixOS behind a proxy, do the following before running <literal>nixos-install</literal>.

     

       9
       9
       +
         To install NixOS behind a proxy, do the following before running

     

       10
       10
       +
         <literal>nixos-install</literal>.

     

       10
       11
        
        </para>

     

       11
       12
        
       

     

       12
       13
        
        <orderedlist numeration="arabic">

     

       13
       14
        
         <listitem>

     

       14
       15
        
          <para>

     

       15
       15
       -
           Update proxy configuration in <literal>/mnt/etc/nixos/configuration.nix</literal> to keep the internet accessible after reboot.

     

       16
       16
       +
           Update proxy configuration in

     

       17
       17
       +
           <literal>/mnt/etc/nixos/configuration.nix</literal> to keep the internet

     

       18
       18
       +
           accessible after reboot.

     

       16
       19
        
          </para>

     

       17
       20
        
       <programlisting>

     

       18
       21
        
       networking.proxy.default = &quot;http://user:password@proxy:port/&quot;;

     
···

       21
       24
        
         </listitem>

     

       22
       25
        
         <listitem>

     

       23
       26
        
          <para>

     

       24
       24
       -
           Setup the proxy environment variables in the shell where you are running <literal>nixos-install</literal>.

     

       27
       27
       +
           Setup the proxy environment variables in the shell where you are running

     

       28
       28
       +
           <literal>nixos-install</literal>.

     

       25
       29
        
          </para>

     

       26
       30
        
       <programlisting>

     

       27
       31
        
       # proxy_url=&quot;http://user:password@proxy:port/&quot;

     
···

       35
       39
        
       

     

       36
       40
        
        <note>

     

       37
       41
        
         <para>

     

       38
       38
       -
          If you are switching networks with different proxy configurations, use the <literal>nesting.clone</literal> option in <literal>configuration.nix</literal> to switch proxies at runtime. Refer to <xref linkend="ch-options" /> for more information.

     

       42
       42
       +
          If you are switching networks with different proxy configurations, use the

     

       43
       43
       +
          <literal>nesting.clone</literal> option in

     

       44
       44
       +
          <literal>configuration.nix</literal> to switch proxies at runtime. Refer to

     

       45
       45
       +
          <xref linkend="ch-options" /> for more information.

     

       39
       46
        
         </para>

     

       40
       47
        
        </note>

     

       41
       48
        
       </section>

+112 -40

nixos/doc/manual/installation/installing-from-other-distro.xml

···

       8
       8
        
        <title>Installing from another Linux distribution</title>

     

       9
       9
        
       

     

       10
       10
        
        <para>

     

       11
       11
       -
         Because Nix (the package manager) &amp; Nixpkgs (the Nix packages collection) can both be installed on any (most?) Linux distributions, they can be used to install NixOS in various creative ways. You can, for instance:

     

       11
       11
       +
         Because Nix (the package manager) &amp; Nixpkgs (the Nix packages collection)

     

       12
       12
       +
         can both be installed on any (most?) Linux distributions, they can be used to

     

       13
       13
       +
         install NixOS in various creative ways. You can, for instance:

     

       12
       14
        
        </para>

     

       13
       15
        
       

     

       14
       16
        
        <orderedlist>

     

       15
       17
        
         <listitem>

     

       16
       18
        
          <para>

     

       17
       17
       -
           Install NixOS on another partition, from your existing Linux distribution (without the use of a USB or optical device!)

     

       19
       19
       +
           Install NixOS on another partition, from your existing Linux distribution

     

       20
       20
       +
           (without the use of a USB or optical device!)

     

       18
       21
        
          </para>

     

       19
       22
        
         </listitem>

     

       20
       23
        
         <listitem>

     

       21
       24
        
          <para>

     

       22
       22
       -
           Install NixOS on the same partition (in place!), from your existing non-NixOS Linux distribution using <literal>NIXOS_LUSTRATE</literal>.

     

       25
       25
       +
           Install NixOS on the same partition (in place!), from your existing

     

       26
       26
       +
           non-NixOS Linux distribution using <literal>NIXOS_LUSTRATE</literal>.

     

       23
       27
        
          </para>

     

       24
       28
        
         </listitem>

     

       25
       29
        
         <listitem>

     

       26
       30
        
          <para>

     

       27
       27
       -
           Install NixOS on your hard drive from the Live CD of any Linux distribution.

     

       31
       31
       +
           Install NixOS on your hard drive from the Live CD of any Linux

     

       32
       32
       +
           distribution.

     

       28
       33
        
          </para>

     

       29
       34
        
         </listitem>

     

       30
       35
        
        </orderedlist>

     
···

       45
       50
        
       <prompt>$ </prompt>curl https://nixos.org/nix/install | sh

     

       46
       51
        
       <prompt>$ </prompt>. $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen>

     

       47
       52
        
          <para>

     

       48
       48
       -
           More details in the <link

     

       49
       49
       -
                           xlink:href="https://nixos.org/nix/manual/#chap-quick-start"> Nix manual</link>

     

       53
       53
       +
           More details in the

     

       54
       54
       +
           <link

     

       55
       55
       +
                           xlink:href="https://nixos.org/nix/manual/#chap-quick-start">

     

       56
       56
       +
           Nix manual</link>

     

       50
       57
        
          </para>

     

       51
       58
        
         </listitem>

     

       52
       59
        
         <listitem>

     
···

       54
       61
        
           Switch to the NixOS channel:

     

       55
       62
        
          </para>

     

       56
       63
        
          <para>

     

       57
       57
       -
           If you've just installed Nix on a non-NixOS distribution, you will be on the <literal>nixpkgs</literal> channel by default.

     

       64
       64
       +
           If you've just installed Nix on a non-NixOS distribution, you will be on

     

       65
       65
       +
           the <literal>nixpkgs</literal> channel by default.

     

       58
       66
        
          </para>

     

       59
       67
        
       <screen>

     

       60
       68
        
       <prompt>$ </prompt>nix-channel --list

     

       61
       69
        
       nixpkgs https://nixos.org/channels/nixpkgs-unstable</screen>

     

       62
       70
        
          <para>

     

       63
       63
       -
           As that channel gets released without running the NixOS tests, it will be safer to use the <literal>nixos-*</literal> channels instead:

     

       71
       71
       +
           As that channel gets released without running the NixOS tests, it will be

     

       72
       72
       +
           safer to use the <literal>nixos-*</literal> channels instead:

     

       64
       73
        
          </para>

     

       65
       74
        
       <screen>

     

       66
       75
        
       <prompt>$ </prompt>nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen>

     

       67
       76
        
          <para>

     

       68
       68
       -
           You may want to throw in a <literal>nix-channel --update</literal> for good measure.

     

       77
       77
       +
           You may want to throw in a <literal>nix-channel --update</literal> for good

     

       78
       78
       +
           measure.

     

       69
       79
        
          </para>

     

       70
       80
        
         </listitem>

     

       71
       81
        
         <listitem>

     
···

       73
       83
        
           Install the NixOS installation tools:

     

       74
       84
        
          </para>

     

       75
       85
        
          <para>

     

       76
       76
       -
           You'll need <literal>nixos-generate-config</literal> and <literal>nixos-install</literal> and we'll throw in some man pages and <literal>nixos-enter</literal> just in case you want to chroot into your NixOS partition. They are installed by default on NixOS, but you don't have NixOS yet..

     

       86
       86
       +
           You'll need <literal>nixos-generate-config</literal> and

     

       87
       87
       +
           <literal>nixos-install</literal> and we'll throw in some man pages and

     

       88
       88
       +
           <literal>nixos-enter</literal> just in case you want to chroot into your

     

       89
       89
       +
           NixOS partition. They are installed by default on NixOS, but you don't have

     

       90
       90
       +
           NixOS yet..

     

       77
       91
        
          </para>

     

       78
       92
        
       <screen><prompt>$ </prompt>nix-env -iE "_: with import &lt;nixpkgs/nixos&gt; { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen>

     

       79
       93
        
         </listitem>

     

       80
       94
        
         <listitem>

     

       81
       95
        
          <note>

     

       82
       96
        
           <para>

     

       83
       83
       -
            The following 5 steps are only for installing NixOS to another partition. For installing NixOS in place using <literal>NIXOS_LUSTRATE</literal>, skip ahead.

     

       97
       97
       +
            The following 5 steps are only for installing NixOS to another partition.

     

       98
       98
       +
            For installing NixOS in place using <literal>NIXOS_LUSTRATE</literal>,

     

       99
       99
       +
            skip ahead.

     

       84
       100
        
           </para>

     

       85
       101
        
          </note>

     

       86
       102
        
          <para>

     

       87
       103
        
           Prepare your target partition:

     

       88
       104
        
          </para>

     

       89
       105
        
          <para>

     

       90
       90
       -
           At this point it is time to prepare your target partition. Please refer to the partitioning, file-system creation, and mounting steps of <xref linkend="sec-installation" />

     

       106
       106
       +
           At this point it is time to prepare your target partition. Please refer to

     

       107
       107
       +
           the partitioning, file-system creation, and mounting steps of

     

       108
       108
       +
           <xref linkend="sec-installation" />

     

       91
       109
        
          </para>

     

       92
       110
        
          <para>

     

       93
       93
       -
           If you're about to install NixOS in place using <literal>NIXOS_LUSTRATE</literal> there is nothing to do for this step.

     

       111
       111
       +
           If you're about to install NixOS in place using

     

       112
       112
       +
           <literal>NIXOS_LUSTRATE</literal> there is nothing to do for this step.

     

       94
       113
        
          </para>

     

       95
       114
        
         </listitem>

     

       96
       115
        
         <listitem>

     
···

       99
       118
        
          </para>

     

       100
       119
        
       <screen><prompt>$ </prompt>sudo `which nixos-generate-config` --root /mnt</screen>

     

       101
       120
        
          <para>

     

       102
       102
       -
           You'll probably want to edit the configuration files. Refer to the <literal>nixos-generate-config</literal> step in <xref

     

       103
       103
       -
                           linkend="sec-installation" /> for more information.

     

       121
       121
       +
           You'll probably want to edit the configuration files. Refer to the

     

       122
       122
       +
           <literal>nixos-generate-config</literal> step in

     

       123
       123
       +
           <xref

     

       124
       124
       +
                           linkend="sec-installation" /> for more

     

       125
       125
       +
           information.

     

       104
       126
        
          </para>

     

       105
       127
        
          <para>

     

       106
       106
       -
           Consider setting up the NixOS bootloader to give you the ability to boot on your existing Linux partition. For instance, if you're using GRUB and your existing distribution is running Ubuntu, you may want to add something like this to your <literal>configuration.nix</literal>:

     

       128
       128
       +
           Consider setting up the NixOS bootloader to give you the ability to boot on

     

       129
       129
       +
           your existing Linux partition. For instance, if you're using GRUB and your

     

       130
       130
       +
           existing distribution is running Ubuntu, you may want to add something like

     

       131
       131
       +
           this to your <literal>configuration.nix</literal>:

     

       107
       132
        
          </para>

     

       108
       133
        
       <programlisting>

     

       109
       134
        
       <xref linkend="opt-boot.loader.grub.extraEntries"/> = ''

     
···

       113
       138
        
         }

     

       114
       139
        
       '';</programlisting>

     

       115
       140
        
          <para>

     

       116
       116
       -
           (You can find the appropriate UUID for your partition in <literal>/dev/disk/by-uuid</literal>)

     

       141
       141
       +
           (You can find the appropriate UUID for your partition in

     

       142
       142
       +
           <literal>/dev/disk/by-uuid</literal>)

     

       117
       143
        
          </para>

     

       118
       144
        
         </listitem>

     

       119
       145
        
         <listitem>

     

       120
       146
        
          <para>

     

       121
       121
       -
           Create the <literal>nixbld</literal> group and user on your original distribution:

     

       147
       147
       +
           Create the <literal>nixbld</literal> group and user on your original

     

       148
       148
       +
           distribution:

     

       122
       149
        
          </para>

     

       123
       150
        
       <screen>

     

       124
       151
        
       <prompt>$ </prompt>sudo groupadd -g 30000 nixbld

     
···

       130
       157
        
          </para>

     

       131
       158
        
          <warning>

     

       132
       159
        
           <para>

     

       133
       133
       -
            Once you complete this step, you might no longer be able to boot on existing systems without the help of a rescue USB drive or similar.

     

       160
       160
       +
            Once you complete this step, you might no longer be able to boot on

     

       161
       161
       +
            existing systems without the help of a rescue USB drive or similar.

     

       134
       162
        
           </para>

     

       135
       163
        
          </warning>

     

       136
       164
        
       <screen><prompt>$ </prompt>sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen>

     

       137
       165
        
          <para>

     

       138
       138
       -
           Again, please refer to the <literal>nixos-install</literal> step in <xref linkend="sec-installation" /> for more information.

     

       166
       166
       +
           Again, please refer to the <literal>nixos-install</literal> step in

     

       167
       167
       +
           <xref linkend="sec-installation" /> for more information.

     

       139
       168
        
          </para>

     

       140
       169
        
          <para>

     

       141
       170
        
           That should be it for installation to another partition!

     
···

       149
       178
        
       <prompt>$ </prompt>sudo userdel nixbld

     

       150
       179
        
       <prompt>$ </prompt>sudo groupdel nixbld</screen>

     

       151
       180
        
          <para>

     

       152
       152
       -
           If you do not wish to keep the Nix package manager installed either, run something like <literal>sudo rm -rv ~/.nix-* /nix</literal> and remove the line that the Nix installer added to your <literal>~/.profile</literal>.

     

       181
       181
       +
           If you do not wish to keep the Nix package manager installed either, run

     

       182
       182
       +
           something like <literal>sudo rm -rv ~/.nix-* /nix</literal> and remove the

     

       183
       183
       +
           line that the Nix installer added to your <literal>~/.profile</literal>.

     

       153
       184
        
          </para>

     

       154
       185
        
         </listitem>

     

       155
       186
        
         <listitem>

     

       156
       187
        
          <note>

     

       157
       188
        
           <para>

     

       158
       158
       -
            The following steps are only for installing NixOS in place using <literal>NIXOS_LUSTRATE</literal>:

     

       189
       189
       +
            The following steps are only for installing NixOS in place using

     

       190
       190
       +
            <literal>NIXOS_LUSTRATE</literal>:

     

       159
       191
        
           </para>

     

       160
       192
        
          </note>

     

       161
       193
        
          <para>

     
···

       163
       195
        
          </para>

     

       164
       196
        
       <screen><prompt>$ </prompt>sudo `which nixos-generate-config` --root /</screen>

     

       165
       197
        
          <para>

     

       166
       166
       -
           Note that this will place the generated configuration files in <literal>/etc/nixos</literal>. You'll probably want to edit the configuration files. Refer to the <literal>nixos-generate-config</literal> step in <xref

     

       167
       167
       -
                           linkend="sec-installation" /> for more information.

     

       198
       198
       +
           Note that this will place the generated configuration files in

     

       199
       199
       +
           <literal>/etc/nixos</literal>. You'll probably want to edit the

     

       200
       200
       +
           configuration files. Refer to the <literal>nixos-generate-config</literal>

     

       201
       201
       +
           step in <xref

     

       202
       202
       +
                           linkend="sec-installation" /> for more

     

       203
       203
       +
           information.

     

       168
       204
        
          </para>

     

       169
       205
        
          <para>

     

       170
       170
       -
           You'll likely want to set a root password for your first boot using the configuration files because you won't have a chance to enter a password until after you reboot. You can initalize the root password to an empty one with this line: (and of course don't forget to set one once you've rebooted or to lock the account with <literal>sudo passwd -l root</literal> if you use <literal>sudo</literal>)

     

       206
       206
       +
           You'll likely want to set a root password for your first boot using the

     

       207
       207
       +
           configuration files because you won't have a chance to enter a password

     

       208
       208
       +
           until after you reboot. You can initalize the root password to an empty one

     

       209
       209
       +
           with this line: (and of course don't forget to set one once you've rebooted

     

       210
       210
       +
           or to lock the account with <literal>sudo passwd -l root</literal> if you

     

       211
       211
       +
           use <literal>sudo</literal>)

     

       171
       212
        
          </para>

     

       172
       213
        
       <programlisting>

     

       173
       214
        
       <link linkend="opt-users.users._name__.initialHashedPassword">users.users.root.initialHashedPassword</link> = "";

     
···

       175
       216
        
         </listitem>

     

       176
       217
        
         <listitem>

     

       177
       218
        
          <para>

     

       178
       178
       -
           Build the NixOS closure and install it in the <literal>system</literal> profile:

     

       219
       219
       +
           Build the NixOS closure and install it in the <literal>system</literal>

     

       220
       220
       +
           profile:

     

       179
       221
        
          </para>

     

       180
       222
        
       <screen><prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/system -f '&lt;nixpkgs/nixos&gt;' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen>

     

       181
       223
        
         </listitem>

     

       182
       224
        
         <listitem>

     

       183
       225
        
          <para>

     

       184
       184
       -
           Change ownership of the <literal>/nix</literal> tree to root (since your Nix install was probably single user):

     

       226
       226
       +
           Change ownership of the <literal>/nix</literal> tree to root (since your

     

       227
       227
       +
           Nix install was probably single user):

     

       185
       228
        
          </para>

     

       186
       229
        
       <screen><prompt>$ </prompt>sudo chown -R 0.0 /nix</screen>

     

       187
       230
        
         </listitem>

     

       188
       231
        
         <listitem>

     

       189
       232
        
          <para>

     

       190
       190
       -
           Set up the <literal>/etc/NIXOS</literal> and <literal>/etc/NIXOS_LUSTRATE</literal> files:

     

       233
       233
       +
           Set up the <literal>/etc/NIXOS</literal> and

     

       234
       234
       +
           <literal>/etc/NIXOS_LUSTRATE</literal> files:

     

       191
       235
        
          </para>

     

       192
       236
        
          <para>

     

       193
       193
       -
           <literal>/etc/NIXOS</literal> officializes that this is now a NixOS partition (the bootup scripts require its presence).

     

       237
       237
       +
           <literal>/etc/NIXOS</literal> officializes that this is now a NixOS

     

       238
       238
       +
           partition (the bootup scripts require its presence).

     

       194
       239
        
          </para>

     

       195
       240
        
          <para>

     

       196
       196
       -
           <literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup scripts to move <emphasis>everything</emphasis> that's in the root partition to <literal>/old-root</literal>. This will move your existing distribution out of the way in the very early stages of the NixOS bootup. There are exceptions (we do need to keep NixOS there after all), so the NixOS lustrate process will not touch:

     

       241
       241
       +
           <literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup scripts to

     

       242
       242
       +
           move <emphasis>everything</emphasis> that's in the root partition to

     

       243
       243
       +
           <literal>/old-root</literal>. This will move your existing distribution out

     

       244
       244
       +
           of the way in the very early stages of the NixOS bootup. There are

     

       245
       245
       +
           exceptions (we do need to keep NixOS there after all), so the NixOS

     

       246
       246
       +
           lustrate process will not touch:

     

       197
       247
        
          </para>

     

       198
       248
        
          <itemizedlist>

     

       199
       249
        
           <listitem>

     
···

       208
       258
        
           </listitem>

     

       209
       259
        
           <listitem>

     

       210
       260
        
            <para>

     

       211
       211
       -
             Any file or directory listed in <literal>/etc/NIXOS_LUSTRATE</literal> (one per line)

     

       261
       261
       +
             Any file or directory listed in <literal>/etc/NIXOS_LUSTRATE</literal>

     

       262
       262
       +
             (one per line)

     

       212
       263
        
            </para>

     

       213
       264
        
           </listitem>

     

       214
       265
        
          </itemizedlist>

     

       215
       266
        
          <note>

     

       216
       267
        
           <para>

     

       217
       217
       -
            Support for <literal>NIXOS_LUSTRATE</literal> was added in NixOS 16.09. The act of "lustrating" refers to the wiping of the existing distribution. Creating <literal>/etc/NIXOS_LUSTRATE</literal> can also be used on NixOS to remove all mutable files from your root partition (anything that's not in <literal>/nix</literal> or <literal>/boot</literal> gets "lustrated" on the next boot.

     

       268
       268
       +
            Support for <literal>NIXOS_LUSTRATE</literal> was added in NixOS 16.09.

     

       269
       269
       +
            The act of "lustrating" refers to the wiping of the existing distribution.

     

       270
       270
       +
            Creating <literal>/etc/NIXOS_LUSTRATE</literal> can also be used on NixOS

     

       271
       271
       +
            to remove all mutable files from your root partition (anything that's not

     

       272
       272
       +
            in <literal>/nix</literal> or <literal>/boot</literal> gets "lustrated" on

     

       273
       273
       +
            the next boot.

     

       218
       274
        
           </para>

     

       219
       275
        
           <para>

     

       220
       276
        
            lustrate /ˈlʌstreɪt/ verb.

     

       221
       277
        
           </para>

     

       222
       278
        
           <para>

     

       223
       223
       -
            purify by expiatory sacrifice, ceremonial washing, or some other ritual action.

     

       279
       279
       +
            purify by expiatory sacrifice, ceremonial washing, or some other ritual

     

       280
       280
       +
            action.

     

       224
       281
        
           </para>

     

       225
       282
        
          </note>

     

       226
       283
        
          <para>

     
···

       231
       288
        
       <prompt>$ </prompt>sudo touch /etc/NIXOS_LUSTRATE

     

       232
       289
        
       </screen>

     

       233
       290
        
          <para>

     

       234
       234
       -
           Let's also make sure the NixOS configuration files are kept once we reboot on NixOS:

     

       291
       291
       +
           Let's also make sure the NixOS configuration files are kept once we reboot

     

       292
       292
       +
           on NixOS:

     

       235
       293
        
          </para>

     

       236
       294
        
       <screen>

     

       237
       295
        
       <prompt>$ </prompt>echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE

     
···

       239
       297
        
         </listitem>

     

       240
       298
        
         <listitem>

     

       241
       299
        
          <para>

     

       242
       242
       -
           Finally, move the <literal>/boot</literal> directory of your current distribution out of the way (the lustrate process will take care of the rest once you reboot, but this one must be moved out now because NixOS needs to install its own boot files:

     

       300
       300
       +
           Finally, move the <literal>/boot</literal> directory of your current

     

       301
       301
       +
           distribution out of the way (the lustrate process will take care of the

     

       302
       302
       +
           rest once you reboot, but this one must be moved out now because NixOS

     

       303
       303
       +
           needs to install its own boot files:

     

       243
       304
        
          </para>

     

       244
       305
        
          <warning>

     

       245
       306
        
           <para>

     

       246
       246
       -
            Once you complete this step, your current distribution will no longer be bootable! If you didn't get all the NixOS configuration right, especially those settings pertaining to boot loading and root partition, NixOS may not be bootable either. Have a USB rescue device ready in case this happens.

     

       307
       307
       +
            Once you complete this step, your current distribution will no longer be

     

       308
       308
       +
            bootable! If you didn't get all the NixOS configuration right, especially

     

       309
       309
       +
            those settings pertaining to boot loading and root partition, NixOS may

     

       310
       310
       +
            not be bootable either. Have a USB rescue device ready in case this

     

       311
       311
       +
            happens.

     

       247
       312
        
           </para>

     

       248
       313
        
          </warning>

     

       249
       314
        
       <screen>

     
···

       256
       321
        
         </listitem>

     

       257
       322
        
         <listitem>

     

       258
       323
        
          <para>

     

       259
       259
       -
           If for some reason you want to revert to the old distribution, you'll need to boot on a USB rescue disk and do something along these lines:

     

       324
       324
       +
           If for some reason you want to revert to the old distribution, you'll need

     

       325
       325
       +
           to boot on a USB rescue disk and do something along these lines:

     

       260
       326
        
          </para>

     

       261
       327
        
       <screen>

     

       262
       328
        
       # mkdir root

     
···

       271
       337
        
           This may work as is or you might also need to reinstall the boot loader

     

       272
       338
        
          </para>

     

       273
       339
        
          <para>

     

       274
       274
       -
           And of course, if you're happy with NixOS and no longer need the old distribution:

     

       340
       340
       +
           And of course, if you're happy with NixOS and no longer need the old

     

       341
       341
       +
           distribution:

     

       275
       342
        
          </para>

     

       276
       343
        
       <screen>sudo rm -rf /old-root</screen>

     

       277
       344
        
         </listitem>

     

       278
       345
        
         <listitem>

     

       279
       346
        
          <para>

     

       280
       280
       -
           It's also worth noting that this whole process can be automated. This is especially useful for Cloud VMs, where provider do not provide NixOS. For instance, <link

     

       281
       281
       -
                           xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link> uses the lustrate process to convert Digital Ocean droplets to NixOS from other distributions automatically.

     

       347
       347
       +
           It's also worth noting that this whole process can be automated. This is

     

       348
       348
       +
           especially useful for Cloud VMs, where provider do not provide NixOS. For

     

       349
       349
       +
           instance,

     

       350
       350
       +
           <link

     

       351
       351
       +
                           xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link>

     

       352
       352
       +
           uses the lustrate process to convert Digital Ocean droplets to NixOS from

     

       353
       353
       +
           other distributions automatically.

     

       282
       354
        
          </para>

     

       283
       355
        
         </listitem>

     

       284
       356
        
        </orderedlist>

+20 -5

nixos/doc/manual/installation/installing-pxe.xml

···

       10
       10
        
        </para>

     

       11
       11
        
       

     

       12
       12
        
        <para>

     

       13
       13
       -
         These instructions assume that you have an existing PXE or iPXE infrastructure and simply want to add the NixOS installer as another option. To build the necessary files from a recent version of nixpkgs, you can run:

     

       13
       13
       +
         These instructions assume that you have an existing PXE or iPXE

     

       14
       14
       +
         infrastructure and simply want to add the NixOS installer as another option.

     

       15
       15
       +
         To build the necessary files from a recent version of nixpkgs, you can run:

     

       14
       16
        
        </para>

     

       15
       17
        
       

     

       16
       18
        
       <programlisting>

     
···

       18
       20
        
       </programlisting>

     

       19
       21
        
       

     

       20
       22
        
        <para>

     

       21
       21
       -
         This will create a <literal>result</literal> directory containing: * <literal>bzImage</literal> – the Linux kernel * <literal>initrd</literal> – the initrd file * <literal>netboot.ipxe</literal> – an example ipxe script demonstrating the appropriate kernel command line arguments for this image

     

       23
       23
       +
         This will create a <literal>result</literal> directory containing: *

     

       24
       24
       +
         <literal>bzImage</literal> – the Linux kernel * <literal>initrd</literal>

     

       25
       25
       +
         – the initrd file * <literal>netboot.ipxe</literal> – an example ipxe

     

       26
       26
       +
         script demonstrating the appropriate kernel command line arguments for this

     

       27
       27
       +
         image

     

       22
       28
        
        </para>

     

       23
       29
        
       

     

       24
       30
        
        <para>

     

       25
       25
       -
         If you’re using plain PXE, configure your boot loader to use the <literal>bzImage</literal> and <literal>initrd</literal> files and have it provide the same kernel command line arguments found in <literal>netboot.ipxe</literal>.

     

       31
       31
       +
         If you’re using plain PXE, configure your boot loader to use the

     

       32
       32
       +
         <literal>bzImage</literal> and <literal>initrd</literal> files and have it

     

       33
       33
       +
         provide the same kernel command line arguments found in

     

       34
       34
       +
         <literal>netboot.ipxe</literal>.

     

       26
       35
        
        </para>

     

       27
       36
        
       

     

       28
       37
        
        <para>

     

       29
       29
       -
         If you’re using iPXE, depending on how your HTTP/FTP/etc. server is configured you may be able to use <literal>netboot.ipxe</literal> unmodified, or you may need to update the paths to the files to match your server’s directory layout

     

       38
       38
       +
         If you’re using iPXE, depending on how your HTTP/FTP/etc. server is

     

       39
       39
       +
         configured you may be able to use <literal>netboot.ipxe</literal> unmodified,

     

       40
       40
       +
         or you may need to update the paths to the files to match your server’s

     

       41
       41
       +
         directory layout

     

       30
       42
        
        </para>

     

       31
       43
        
       

     

       32
       44
        
        <para>

     

       33
       33
       -
         In the future we may begin making these files available as build products from hydra at which point we will update this documentation with instructions on how to obtain them either for placing on a dedicated TFTP server or to boot them directly over the internet.

     

       45
       45
       +
         In the future we may begin making these files available as build products

     

       46
       46
       +
         from hydra at which point we will update this documentation with instructions

     

       47
       47
       +
         on how to obtain them either for placing on a dedicated TFTP server or to

     

       48
       48
       +
         boot them directly over the internet.

     

       34
       49
        
        </para>

     

       35
       50
        
       </section>

+12 -3

nixos/doc/manual/installation/installing-usb.xml

···

       6
       6
        
        <title>Booting from a USB Drive</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         For systems without CD drive, the NixOS live CD can be booted from a USB stick. You can use the <command>dd</command> utility to write the image: <command>dd if=<replaceable>path-to-image</replaceable> of=<replaceable>/dev/sdX</replaceable></command>. Be careful about specifying the correct drive; you can use the <command>lsblk</command> command to get a list of block devices.

     

       9
       9
       +
         For systems without CD drive, the NixOS live CD can be booted from a USB

     

       10
       10
       +
         stick. You can use the <command>dd</command> utility to write the image:

     

       11
       11
       +
         <command>dd if=<replaceable>path-to-image</replaceable>

     

       12
       12
       +
         of=<replaceable>/dev/sdX</replaceable></command>. Be careful about specifying

     

       13
       13
       +
         the correct drive; you can use the <command>lsblk</command> command to get a

     

       14
       14
       +
         list of block devices.

     

       10
       15
        
         <note>

     

       11
       16
        
          <title>On macOS</title>

     

       12
       17
        
          <para>

     
···

       20
       25
        
       Unmount of all volumes on diskN was successful

     

       21
       26
        
       <prompt>$ </prompt>sudo dd if=nix.iso of=/dev/rdiskN

     

       22
       27
        
       </screen>

     

       23
       23
       -
           Using the 'raw' <command>rdiskN</command> device instead of <command>diskN</command> completes in minutes instead of hours. After <command>dd</command> completes, a GUI dialog "The disk you inserted was not readable by this computer" will pop up, which can be ignored.

     

       28
       28
       +
           Using the 'raw' <command>rdiskN</command> device instead of

     

       29
       29
       +
           <command>diskN</command> completes in minutes instead of hours. After

     

       30
       30
       +
           <command>dd</command> completes, a GUI dialog "The disk you inserted was

     

       31
       31
       +
           not readable by this computer" will pop up, which can be ignored.

     

       24
       32
        
          </para>

     

       25
       33
        
         </note>

     

       26
       34
        
        </para>

     

       27
       35
        
       

     

       28
       36
        
        <para>

     

       29
       29
       -
         The <command>dd</command> utility will write the image verbatim to the drive, making it the recommended option for both UEFI and non-UEFI installations.

     

       37
       37
       +
         The <command>dd</command> utility will write the image verbatim to the drive,

     

       38
       38
       +
         making it the recommended option for both UEFI and non-UEFI installations.

     

       30
       39
        
        </para>

     

       31
       40
        
       </section>

+22 -7

nixos/doc/manual/installation/installing-virtualbox-guest.xml

···

       6
       6
        
        <title>Installing in a VirtualBox guest</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         Installing NixOS into a VirtualBox guest is convenient for users who want to try NixOS without installing it on bare metal. If you want to use a pre-made VirtualBox appliance, it is available at <link

     

       10
       10
       -
         xlink:href="https://nixos.org/nixos/download.html">the downloads page</link>. If you want to set up a VirtualBox guest manually, follow these instructions:

     

       9
       9
       +
         Installing NixOS into a VirtualBox guest is convenient for users who want to

     

       10
       10
       +
         try NixOS without installing it on bare metal. If you want to use a pre-made

     

       11
       11
       +
         VirtualBox appliance, it is available at

     

       12
       12
       +
         <link

     

       13
       13
       +
         xlink:href="https://nixos.org/nixos/download.html">the downloads

     

       14
       14
       +
         page</link>. If you want to set up a VirtualBox guest manually, follow these

     

       15
       15
       +
         instructions:

     

       11
       16
        
        </para>

     

       12
       17
        
       

     

       13
       18
        
        <orderedlist>

     
···

       38
       43
        
         </listitem>

     

       39
       44
        
         <listitem>

     

       40
       45
        
          <para>

     

       41
       41
       -
           Click on Settings / System / Acceleration and enable "VT-x/AMD-V" acceleration

     

       46
       46
       +
           Click on Settings / System / Acceleration and enable "VT-x/AMD-V"

     

       47
       47
       +
           acceleration

     

       42
       48
        
          </para>

     

       43
       49
        
         </listitem>

     

       44
       50
        
         <listitem>

     

       45
       51
        
          <para>

     

       46
       46
       -
           Save the settings, start the virtual machine, and continue installation like normal

     

       52
       52
       +
           Save the settings, start the virtual machine, and continue installation

     

       53
       53
       +
           like normal

     

       47
       54
        
          </para>

     

       48
       55
        
         </listitem>

     

       49
       56
        
        </orderedlist>

     

       50
       57
        
       

     

       51
       58
        
        <para>

     

       52
       52
       -
         There are a few modifications you should make in configuration.nix. Enable booting:

     

       59
       59
       +
         There are a few modifications you should make in configuration.nix. Enable

     

       60
       60
       +
         booting:

     

       53
       61
        
        </para>

     

       54
       62
        
       

     

       55
       63
        
       <programlisting>

     
···

       57
       65
        
       </programlisting>

     

       58
       66
        
       

     

       59
       67
        
        <para>

     

       60
       60
       -
         Also remove the fsck that runs at startup. It will always fail to run, stopping your boot until you press <literal>*</literal>.

     

       68
       68
       +
         Also remove the fsck that runs at startup. It will always fail to run,

     

       69
       69
       +
         stopping your boot until you press <literal>*</literal>.

     

       61
       70
        
        </para>

     

       62
       71
        
       

     

       63
       72
        
       <programlisting>

     
···

       65
       74
        
       </programlisting>

     

       66
       75
        
       

     

       67
       76
        
        <para>

     

       68
       68
       -
         Shared folders can be given a name and a path in the host system in the VirtualBox settings (Machine / Settings / Shared Folders, then click on the "Add" icon). Add the following to the <literal>/etc/nixos/configuration.nix</literal> to auto-mount them. If you do not add <literal>"nofail"</literal>, the system will no boot properly. The same goes for disabling <literal>rngd</literal> which is normally used to get randomness but this does not work in virtual machines.

     

       77
       77
       +
         Shared folders can be given a name and a path in the host system in the

     

       78
       78
       +
         VirtualBox settings (Machine / Settings / Shared Folders, then click on the

     

       79
       79
       +
         "Add" icon). Add the following to the

     

       80
       80
       +
         <literal>/etc/nixos/configuration.nix</literal> to auto-mount them. If you do

     

       81
       81
       +
         not add <literal>"nofail"</literal>, the system will no boot properly. The

     

       82
       82
       +
         same goes for disabling <literal>rngd</literal> which is normally used to get

     

       83
       83
       +
         randomness but this does not work in virtual machines.

     

       69
       84
        
        </para>

     

       70
       85
        
       

     

       71
       86
        
       <programlisting>

+177 -53

nixos/doc/manual/installation/installing.xml

···

       8
       8
        
         <title>Booting the system</title>

     

       9
       9
        
       

     

       10
       10
        
         <para>

     

       11
       11
       -
          NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI installation is by and large the same as a BIOS installation. The differences are mentioned in the steps that follow.

     

       11
       11
       +
          NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI

     

       12
       12
       +
          installation is by and large the same as a BIOS installation. The

     

       13
       13
       +
          differences are mentioned in the steps that follow.

     

       12
       14
        
         </para>

     

       13
       15
        
       

     

       14
       16
        
         <para>

     

       15
       15
       -
          The installation media can be burned to a CD, or now more commonly, "burned" to a USB drive (see <xref linkend="sec-booting-from-usb"/>).

     

       17
       17
       +
          The installation media can be burned to a CD, or now more commonly, "burned"

     

       18
       18
       +
          to a USB drive (see <xref linkend="sec-booting-from-usb"/>).

     

       16
       19
        
         </para>

     

       17
       20
        
       

     

       18
       21
        
         <para>

     

       19
       19
       -
          The installation media contains a basic NixOS installation. When it’s finished booting, it should have detected most of your hardware.

     

       22
       22
       +
          The installation media contains a basic NixOS installation. When it’s

     

       23
       23
       +
          finished booting, it should have detected most of your hardware.

     

       20
       24
        
         </para>

     

       21
       25
        
       

     

       22
       26
        
         <para>

     

       23
       23
       -
          The NixOS manual is available on virtual console 8 (press Alt+F8 to access) or by running <command>nixos-help</command>.

     

       27
       27
       +
          The NixOS manual is available on virtual console 8 (press Alt+F8 to access)

     

       28
       28
       +
          or by running <command>nixos-help</command>.

     

       24
       29
        
         </para>

     

       25
       30
        
       

     

       26
       31
        
         <para>

     

       27
       27
       -
          You are logged-in automatically as <literal>nixos</literal>. The <literal>nixos</literal> user account has an empty password so you can use <command>sudo</command> without a password.

     

       32
       32
       +
          You are logged-in automatically as <literal>nixos</literal>.

     

       33
       33
       +
          The <literal>nixos</literal> user account has an empty password so you

     

       34
       34
       +
          can use <command>sudo</command> without a password.

     

       28
       35
        
         </para>

     

       29
       36
        
       

     

       30
       37
        
         <para>

     

       31
       31
       -
          If you downloaded the graphical ISO image, you can run <command>systemctl start display-manager</command> to start the desktop environment. If you want to continue on the terminal, you can use <command>loadkeys</command> to switch to your preferred keyboard layout. (We even provide neo2 via <command>loadkeys de neo</command>!)

     

       38
       38
       +
          If you downloaded the graphical ISO image, you can run <command>systemctl

     

       39
       39
       +
          start display-manager</command> to start the desktop environment. If you want to continue on the

     

       40
       40
       +
          terminal, you can use <command>loadkeys</command> to switch to your

     

       41
       41
       +
          preferred keyboard layout. (We even provide neo2 via <command>loadkeys de

     

       42
       42
       +
          neo</command>!)

     

       32
       43
        
         </para>

     

       33
       44
        
       

     

       34
       45
        
         <section xml:id="sec-installation-booting-networking">

     

       35
       46
        
          <title>Networking in the installer</title>

     

       36
       47
        
       

     

       37
       48
        
          <para>

     

       38
       38
       -
           The boot process should have brought up networking (check <command>ip a</command>). Networking is necessary for the installer, since it will download lots of stuff (such as source tarballs or Nixpkgs channel binaries). It’s best if you have a DHCP server on your network. Otherwise configure networking manually using <command>ifconfig</command>.

     

       49
       49
       +
           The boot process should have brought up networking (check <command>ip

     

       50
       50
       +
           a</command>). Networking is necessary for the installer, since it will

     

       51
       51
       +
           download lots of stuff (such as source tarballs or Nixpkgs channel

     

       52
       52
       +
           binaries). It’s best if you have a DHCP server on your network. Otherwise

     

       53
       53
       +
           configure networking manually using <command>ifconfig</command>.

     

       39
       54
        
          </para>

     

       40
       55
        
       

     

       41
       56
        
          <para>

     

       42
       42
       -
           To manually configure the network on the graphical installer, first disable network-manager with <command>systemctl stop NetworkManager</command>.

     

       57
       57
       +
           To manually configure the network on the graphical installer, first disable

     

       58
       58
       +
           network-manager with <command>systemctl stop NetworkManager</command>.

     

       43
       59
        
          </para>

     

       44
       60
        
       

     

       45
       61
        
          <para>

     

       46
       46
       -
           To manually configure the wifi on the minimal installer, run <command>wpa_supplicant -B -i interface -c &lt;(wpa_passphrase 'SSID' 'key')</command>.

     

       62
       62
       +
           To manually configure the wifi on the minimal installer, run

     

       63
       63
       +
           <command>wpa_supplicant -B -i interface -c &lt;(wpa_passphrase 'SSID'

     

       64
       64
       +
           'key')</command>.

     

       47
       65
        
          </para>

     

       48
       66
        
       

     

       49
       67
        
          <para>

     

       50
       50
       -
           If you would like to continue the installation from a different machine you need to activate the SSH daemon via <command>systemctl start sshd</command>. You then must set a password for either <literal>root</literal> or <literal>nixos</literal> with <command>passwd></command> to be able to login.

     

       68
       68
       +
           If you would like to continue the installation from a different machine you

     

       69
       69
       +
           need to activate the SSH daemon via <command>systemctl start

     

       70
       70
       +
           sshd</command>. You then must set a password for either <literal>root</literal> or

     

       71
       71
       +
           <literal>nixos</literal> with <command>passwd></command> to be able to login.

     

       51
       72
        
          </para>

     

       52
       73
        
         </section>

     

       53
       74
        
        </section>

     
···

       55
       76
        
         <title>Partitioning and formatting</title>

     

       56
       77
        
       

     

       57
       78
        
         <para>

     

       58
       58
       -
          The NixOS installer doesn’t do any partitioning or formatting, so you need to do that yourself.

     

       79
       79
       +
          The NixOS installer doesn’t do any partitioning or formatting, so you need

     

       80
       80
       +
          to do that yourself.

     

       59
       81
        
         </para>

     

       60
       82
        
       

     

       61
       83
        
         <para>

     

       62
       62
       -
          The NixOS installer ships with multiple partitioning tools. The examples below use <command>parted</command>, but also provides <command>fdisk</command>, <command>gdisk</command>, <command>cfdisk</command>, and <command>cgdisk</command>.

     

       84
       84
       +
          The NixOS installer ships with multiple partitioning tools. The examples

     

       85
       85
       +
          below use <command>parted</command>, but also provides

     

       86
       86
       +
          <command>fdisk</command>, <command>gdisk</command>,

     

       87
       87
       +
          <command>cfdisk</command>, and <command>cgdisk</command>.

     

       63
       88
        
         </para>

     

       64
       89
        
       

     

       65
       90
        
         <para>

     

       66
       66
       -
          The recommended partition scheme differs depending if the computer uses <emphasis>Legacy Boot</emphasis> or <emphasis>UEFI</emphasis>.

     

       91
       91
       +
          The recommended partition scheme differs depending if the computer uses

     

       92
       92
       +
          <emphasis>Legacy Boot</emphasis> or <emphasis>UEFI</emphasis>.

     

       67
       93
        
         </para>

     

       68
       94
        
       

     

       69
       95
        
         <section xml:id="sec-installation-partitioning-UEFI">

     

       70
       96
        
          <title>UEFI (GPT)</title>

     

       71
       97
        
       

     

       72
       98
        
          <para>

     

       73
       73
       -
           Here's an example partition scheme for UEFI, using <filename>/dev/sda</filename> as the device.

     

       99
       99
       +
           Here's an example partition scheme for UEFI, using

     

       100
       100
       +
           <filename>/dev/sda</filename> as the device.

     

       74
       101
        
           <note>

     

       75
       102
        
            <para>

     

       76
       76
       -
             You can safely ignore <command>parted</command>'s informational message about needing to update /etc/fstab.

     

       103
       103
       +
             You can safely ignore <command>parted</command>'s informational message

     

       104
       104
       +
             about needing to update /etc/fstab.

     

       77
       105
        
            </para>

     

       78
       106
        
           </note>

     

       79
       107
        
          </para>

     
···

       88
       116
        
            </listitem>

     

       89
       117
        
            <listitem>

     

       90
       118
        
             <para>

     

       91
       91
       -
              Add the <emphasis>root</emphasis> partition. This will fill the disk except for the end part, where the swap will live, and the space left in front (512MiB) which will be used by the boot partition.

     

       119
       119
       +
              Add the <emphasis>root</emphasis> partition. This will fill the disk

     

       120
       120
       +
              except for the end part, where the swap will live, and the space left in

     

       121
       121
       +
              front (512MiB) which will be used by the boot partition.

     

       92
       122
        
       <screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB</screen>

     

       93
       123
        
             </para>

     

       94
       124
        
            </listitem>

     

       95
       125
        
            <listitem>

     

       96
       126
        
             <para>

     

       97
       97
       -
              Next, add a <emphasis>swap</emphasis> partition. The size required will vary according to needs, here a 8GiB one is created.

     

       127
       127
       +
              Next, add a <emphasis>swap</emphasis> partition. The size required will

     

       128
       128
       +
              vary according to needs, here a 8GiB one is created.

     

       98
       129
        
       <screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen>

     

       99
       130
        
              <note>

     

       100
       131
        
               <para>

     

       101
       101
       -
                The swap partition size rules are no different than for other Linux distributions.

     

       132
       132
       +
                The swap partition size rules are no different than for other Linux

     

       133
       133
       +
                distributions.

     

       102
       134
        
               </para>

     

       103
       135
        
              </note>

     

       104
       136
        
             </para>

     

       105
       137
        
            </listitem>

     

       106
       138
        
            <listitem>

     

       107
       139
        
             <para>

     

       108
       108
       -
              Finally, the <emphasis>boot</emphasis> partition. NixOS by default uses the ESP (EFI system partition) as its <emphasis>/boot</emphasis> partition. It uses the initially reserved 512MiB at the start of the disk.

     

       140
       140
       +
              Finally, the <emphasis>boot</emphasis> partition. NixOS by default uses

     

       141
       141
       +
              the ESP (EFI system partition) as its <emphasis>/boot</emphasis>

     

       142
       142
       +
              partition. It uses the initially reserved 512MiB at the start of the

     

       143
       143
       +
              disk.

     

       109
       144
        
       <screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB

     

       110
       145
        
       <prompt># </prompt>parted /dev/sda -- set 3 boot on</screen>

     

       111
       146
        
             </para>

     
···

       114
       149
        
          </para>

     

       115
       150
        
       

     

       116
       151
        
          <para>

     

       117
       117
       -
           Once complete, you can follow with <xref linkend="sec-installation-partitioning-formatting"/>.

     

       152
       152
       +
           Once complete, you can follow with

     

       153
       153
       +
           <xref linkend="sec-installation-partitioning-formatting"/>.

     

       118
       154
        
          </para>

     

       119
       155
        
         </section>

     

       120
       156
        
       

     
···

       122
       158
        
          <title>Legacy Boot (MBR)</title>

     

       123
       159
        
       

     

       124
       160
        
          <para>

     

       125
       125
       -
           Here's an example partition scheme for Legacy Boot, using <filename>/dev/sda</filename> as the device.

     

       161
       161
       +
           Here's an example partition scheme for Legacy Boot, using

     

       162
       162
       +
           <filename>/dev/sda</filename> as the device.

     

       126
       163
        
           <note>

     

       127
       164
        
            <para>

     

       128
       128
       -
             You can safely ignore <command>parted</command>'s informational message about needing to update /etc/fstab.

     

       165
       165
       +
             You can safely ignore <command>parted</command>'s informational message

     

       166
       166
       +
             about needing to update /etc/fstab.

     

       129
       167
        
            </para>

     

       130
       168
        
           </note>

     

       131
       169
        
          </para>

     
···

       140
       178
        
            </listitem>

     

       141
       179
        
            <listitem>

     

       142
       180
        
             <para>

     

       143
       143
       -
              Add the <emphasis>root</emphasis> partition. This will fill the the disk except for the end part, where the swap will live.

     

       181
       181
       +
              Add the <emphasis>root</emphasis> partition. This will fill the the disk

     

       182
       182
       +
              except for the end part, where the swap will live.

     

       144
       183
        
       <screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB</screen>

     

       145
       184
        
             </para>

     

       146
       185
        
            </listitem>

     

       147
       186
        
            <listitem>

     

       148
       187
        
             <para>

     

       149
       149
       -
              Finally, add a <emphasis>swap</emphasis> partition. The size required will vary according to needs, here a 8GiB one is created.

     

       188
       188
       +
              Finally, add a <emphasis>swap</emphasis> partition. The size required

     

       189
       189
       +
              will vary according to needs, here a 8GiB one is created.

     

       150
       190
        
       <screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen>

     

       151
       191
        
              <note>

     

       152
       192
        
               <para>

     

       153
       153
       -
                The swap partition size rules are no different than for other Linux distributions.

     

       193
       193
       +
                The swap partition size rules are no different than for other Linux

     

       194
       194
       +
                distributions.

     

       154
       195
        
               </para>

     

       155
       196
        
              </note>

     

       156
       197
        
             </para>

     
···

       159
       200
        
          </para>

     

       160
       201
        
       

     

       161
       202
        
          <para>

     

       162
       162
       -
           Once complete, you can follow with <xref linkend="sec-installation-partitioning-formatting"/>.

     

       203
       203
       +
           Once complete, you can follow with

     

       204
       204
       +
           <xref linkend="sec-installation-partitioning-formatting"/>.

     

       163
       205
        
          </para>

     

       164
       206
        
         </section>

     

       165
       207
        
       

     
···

       171
       213
        
           <itemizedlist>

     

       172
       214
        
            <listitem>

     

       173
       215
        
             <para>

     

       174
       174
       -
              For initialising Ext4 partitions: <command>mkfs.ext4</command>. It is recommended that you assign a unique symbolic label to the file system using the option <option>-L <replaceable>label</replaceable></option>, since this makes the file system configuration independent from device changes. For example:

     

       216
       216
       +
              For initialising Ext4 partitions: <command>mkfs.ext4</command>. It is

     

       217
       217
       +
              recommended that you assign a unique symbolic label to the file system

     

       218
       218
       +
              using the option <option>-L <replaceable>label</replaceable></option>,

     

       219
       219
       +
              since this makes the file system configuration independent from device

     

       220
       220
       +
              changes. For example:

     

       175
       221
        
       <screen>

     

       176
       222
        
       <prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1</screen>

     

       177
       223
        
             </para>

     

       178
       224
        
            </listitem>

     

       179
       225
        
            <listitem>

     

       180
       226
        
             <para>

     

       181
       181
       -
              For creating swap partitions: <command>mkswap</command>. Again it’s recommended to assign a label to the swap partition: <option>-L <replaceable>label</replaceable></option>. For example:

     

       227
       227
       +
              For creating swap partitions: <command>mkswap</command>. Again it’s

     

       228
       228
       +
              recommended to assign a label to the swap partition: <option>-L

     

       229
       229
       +
              <replaceable>label</replaceable></option>. For example:

     

       182
       230
        
       <screen>

     

       183
       231
        
       <prompt># </prompt>mkswap -L swap /dev/sda2</screen>

     

       184
       232
        
             </para>

     
···

       191
       239
        
               </term>

     

       192
       240
        
               <listitem>

     

       193
       241
        
                <para>

     

       194
       194
       -
                 For creating boot partitions: <command>mkfs.fat</command>. Again it’s recommended to assign a label to the boot partition: <option>-n <replaceable>label</replaceable></option>. For example:

     

       242
       242
       +
                 For creating boot partitions: <command>mkfs.fat</command>. Again

     

       243
       243
       +
                 it’s recommended to assign a label to the boot partition:

     

       244
       244
       +
                 <option>-n <replaceable>label</replaceable></option>. For example:

     

       195
       245
        
       <screen>

     

       196
       246
        
       <prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3</screen>

     

       197
       247
        
                </para>

     
···

       201
       251
        
            </listitem>

     

       202
       252
        
            <listitem>

     

       203
       253
        
             <para>

     

       204
       204
       -
              For creating LVM volumes, the LVM commands, e.g., <command>pvcreate</command>, <command>vgcreate</command>, and <command>lvcreate</command>.

     

       254
       254
       +
              For creating LVM volumes, the LVM commands, e.g.,

     

       255
       255
       +
              <command>pvcreate</command>, <command>vgcreate</command>, and

     

       256
       256
       +
              <command>lvcreate</command>.

     

       205
       257
        
             </para>

     

       206
       258
        
            </listitem>

     

       207
       259
        
            <listitem>

     
···

       219
       271
        
         <orderedlist>

     

       220
       272
        
          <listitem>

     

       221
       273
        
           <para>

     

       222
       222
       -
            Mount the target file system on which NixOS should be installed on <filename>/mnt</filename>, e.g.

     

       274
       274
       +
            Mount the target file system on which NixOS should be installed on

     

       275
       275
       +
            <filename>/mnt</filename>, e.g.

     

       223
       276
        
       <screen>

     

       224
       277
        
       <prompt># </prompt>mount /dev/disk/by-label/nixos /mnt

     

       225
       278
        
       </screen>

     
···

       245
       298
        
          </listitem>

     

       246
       299
        
          <listitem>

     

       247
       300
        
           <para>

     

       248
       248
       -
            If your machine has a limited amount of memory, you may want to activate swap devices now (<command>swapon <replaceable>device</replaceable></command>). The installer (or rather, the build actions that it may spawn) may need quite a bit of RAM, depending on your configuration.

     

       301
       301
       +
            If your machine has a limited amount of memory, you may want to activate

     

       302
       302
       +
            swap devices now (<command>swapon

     

       303
       303
       +
            <replaceable>device</replaceable></command>). The installer (or rather,

     

       304
       304
       +
            the build actions that it may spawn) may need quite a bit of RAM,

     

       305
       305
       +
            depending on your configuration.

     

       249
       306
        
       <screen>

     

       250
       307
        
       <prompt># </prompt>swapon /dev/sda2</screen>

     

       251
       308
        
           </para>

     

       252
       309
        
          </listitem>

     

       253
       310
        
          <listitem>

     

       254
       311
        
           <para>

     

       255
       255
       -
            You now need to create a file <filename>/mnt/etc/nixos/configuration.nix</filename> that specifies the intended configuration of the system. This is because NixOS has a <emphasis>declarative</emphasis> configuration model: you create or edit a description of the desired configuration of your system, and then NixOS takes care of making it happen. The syntax of the NixOS configuration file is described in <xref linkend="sec-configuration-syntax"/>, while a list of available configuration options appears in <xref

     

       256
       256
       -
           linkend="ch-options"/>. A minimal example is shown in <xref

     

       312
       312
       +
            You now need to create a file

     

       313
       313
       +
            <filename>/mnt/etc/nixos/configuration.nix</filename> that specifies the

     

       314
       314
       +
            intended configuration of the system. This is because NixOS has a

     

       315
       315
       +
            <emphasis>declarative</emphasis> configuration model: you create or edit a

     

       316
       316
       +
            description of the desired configuration of your system, and then NixOS

     

       317
       317
       +
            takes care of making it happen. The syntax of the NixOS configuration file

     

       318
       318
       +
            is described in <xref linkend="sec-configuration-syntax"/>, while a list

     

       319
       319
       +
            of available configuration options appears in

     

       320
       320
       +
            <xref

     

       321
       321
       +
           linkend="ch-options"/>. A minimal example is shown in

     

       322
       322
       +
            <xref

     

       257
       323
        
           linkend="ex-config"/>.

     

       258
       324
        
           </para>

     

       259
       325
        
           <para>

     

       260
       260
       -
            The command <command>nixos-generate-config</command> can generate an initial configuration file for you:

     

       326
       326
       +
            The command <command>nixos-generate-config</command> can generate an

     

       327
       327
       +
            initial configuration file for you:

     

       261
       328
        
       <screen>

     

       262
       329
        
       <prompt># </prompt>nixos-generate-config --root /mnt</screen>

     

       263
       263
       -
            You should then edit <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your needs:

     

       330
       330
       +
            You should then edit <filename>/mnt/etc/nixos/configuration.nix</filename>

     

       331
       331
       +
            to suit your needs:

     

       264
       332
        
       <screen>

     

       265
       333
        
       <prompt># </prompt>nano /mnt/etc/nixos/configuration.nix

     

       266
       334
        
       </screen>

     

       267
       267
       -
            If you’re using the graphical ISO image, other editors may be available (such as <command>vim</command>). If you have network access, you can also install other editors — for instance, you can install Emacs by running <literal>nix-env -f '&lt;nixpkgs&gt;' -iA emacs</literal>.

     

       335
       335
       +
            If you’re using the graphical ISO image, other editors may be available

     

       336
       336
       +
            (such as <command>vim</command>). If you have network access, you can also

     

       337
       337
       +
            install other editors — for instance, you can install Emacs by running

     

       338
       338
       +
            <literal>nix-env -f '&lt;nixpkgs&gt;' -iA emacs</literal>.

     

       268
       339
        
           </para>

     

       269
       340
        
           <variablelist>

     

       270
       341
        
            <varlistentry>

     
···

       273
       344
        
             </term>

     

       274
       345
        
             <listitem>

     

       275
       346
        
              <para>

     

       276
       276
       -
               You <emphasis>must</emphasis> set the option <xref linkend="opt-boot.loader.grub.device"/> to specify on which disk the GRUB boot loader is to be installed. Without it, NixOS cannot boot.

     

       347
       347
       +
               You <emphasis>must</emphasis> set the option

     

       348
       348
       +
               <xref linkend="opt-boot.loader.grub.device"/> to specify on which disk

     

       349
       349
       +
               the GRUB boot loader is to be installed. Without it, NixOS cannot boot.

     

       277
       350
        
              </para>

     

       278
       351
        
             </listitem>

     

       279
       352
        
            </varlistentry>

     
···

       283
       356
        
             </term>

     

       284
       357
        
             <listitem>

     

       285
       358
        
              <para>

     

       286
       286
       -
               You <emphasis>must</emphasis> set the option <xref linkend="opt-boot.loader.systemd-boot.enable"/> to <literal>true</literal>. <command>nixos-generate-config</command> should do this automatically for new configurations when booted in UEFI mode.

     

       359
       359
       +
               You <emphasis>must</emphasis> set the option

     

       360
       360
       +
               <xref linkend="opt-boot.loader.systemd-boot.enable"/> to

     

       361
       361
       +
               <literal>true</literal>. <command>nixos-generate-config</command>

     

       362
       362
       +
               should do this automatically for new configurations when booted in UEFI

     

       363
       363
       +
               mode.

     

       287
       364
        
              </para>

     

       288
       365
        
              <para>

     

       289
       289
       -
               You may want to look at the options starting with <option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option> and <option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd</link></option> as well.

     

       366
       366
       +
               You may want to look at the options starting with

     

       367
       367
       +
               <option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option>

     

       368
       368
       +
               and

     

       369
       369
       +
               <option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd</link></option>

     

       370
       370
       +
               as well.

     

       290
       371
        
              </para>

     

       291
       372
        
             </listitem>

     

       292
       373
        
            </varlistentry>

     

       293
       374
        
           </variablelist>

     

       294
       375
        
           <para>

     

       295
       295
       -
            If there are other operating systems running on the machine before installing NixOS, the <xref linkend="opt-boot.loader.grub.useOSProber"/> option can be set to <literal>true</literal> to automatically add them to the grub menu.

     

       376
       376
       +
            If there are other operating systems running on the machine before

     

       377
       377
       +
            installing NixOS, the <xref linkend="opt-boot.loader.grub.useOSProber"/>

     

       378
       378
       +
            option can be set to <literal>true</literal> to automatically add them to

     

       379
       379
       +
            the grub menu.

     

       296
       380
        
           </para>

     

       297
       381
        
           <para>

     

       298
       298
       -
            If you need to configure networking for your machine the configuration options are described in <xref linkend="sec-networking"/>.

     

       382
       382
       +
            If you need to configure networking for your machine the configuration

     

       383
       383
       +
            options are described in <xref linkend="sec-networking"/>.

     

       299
       384
        
           </para>

     

       300
       385
        
           <para>

     

       301
       301
       -
            Another critical option is <option>fileSystems</option>, specifying the file systems that need to be mounted by NixOS. However, you typically don’t need to set it yourself, because <command>nixos-generate-config</command> sets it automatically in <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> from your currently mounted file systems. (The configuration file <filename>hardware-configuration.nix</filename> is included from <filename>configuration.nix</filename> and will be overwritten by future invocations of <command>nixos-generate-config</command>; thus, you generally should not modify it.) Additionally, you may want to look at <link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware configuration for known-hardware</link> at this point or after installation.

     

       386
       386
       +
            Another critical option is <option>fileSystems</option>, specifying the

     

       387
       387
       +
            file systems that need to be mounted by NixOS. However, you typically

     

       388
       388
       +
            don’t need to set it yourself, because

     

       389
       389
       +
            <command>nixos-generate-config</command> sets it automatically in

     

       390
       390
       +
            <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> from your

     

       391
       391
       +
            currently mounted file systems. (The configuration file

     

       392
       392
       +
            <filename>hardware-configuration.nix</filename> is included from

     

       393
       393
       +
            <filename>configuration.nix</filename> and will be overwritten by future

     

       394
       394
       +
            invocations of <command>nixos-generate-config</command>; thus, you

     

       395
       395
       +
            generally should not modify it.) Additionally, you may want to look at 

     

       396
       396
       +
            <link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware

     

       397
       397
       +
            configuration for known-hardware</link> at this point or after

     

       398
       398
       +
            installation.

     

       399
       399
       +
             

     

       302
       400
        
           </para>

     

       303
       401
        
           <note>

     

       304
       402
        
            <para>

     

       305
       305
       -
             Depending on your hardware configuration or type of file system, you may need to set the option <option>boot.initrd.kernelModules</option> to include the kernel modules that are necessary for mounting the root file system, otherwise the installed system will not be able to boot. (If this happens, boot from the installation media again, mount the target file system on <filename>/mnt</filename>, fix <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun <filename>nixos-install</filename>.) In most cases, <command>nixos-generate-config</command> will figure out the required modules.

     

       403
       403
       +
             Depending on your hardware configuration or type of file system, you may

     

       404
       404
       +
             need to set the option <option>boot.initrd.kernelModules</option> to

     

       405
       405
       +
             include the kernel modules that are necessary for mounting the root file

     

       406
       406
       +
             system, otherwise the installed system will not be able to boot. (If this

     

       407
       407
       +
             happens, boot from the installation media again, mount the target file

     

       408
       408
       +
             system on <filename>/mnt</filename>, fix

     

       409
       409
       +
             <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun

     

       410
       410
       +
             <filename>nixos-install</filename>.) In most cases,

     

       411
       411
       +
             <command>nixos-generate-config</command> will figure out the required

     

       412
       412
       +
             modules.

     

       306
       413
        
            </para>

     

       307
       414
        
           </note>

     

       308
       415
        
          </listitem>

     
···

       311
       418
        
            Do the installation:

     

       312
       419
        
       <screen>

     

       313
       420
        
       <prompt># </prompt>nixos-install</screen>

     

       314
       314
       -
            Cross fingers. If this fails due to a temporary problem (such as a network issue while downloading binaries from the NixOS binary cache), you can just re-run <command>nixos-install</command>. Otherwise, fix your <filename>configuration.nix</filename> and then re-run <command>nixos-install</command>.

     

       421
       421
       +
            Cross fingers. If this fails due to a temporary problem (such as a network

     

       422
       422
       +
            issue while downloading binaries from the NixOS binary cache), you can

     

       423
       423
       +
            just re-run <command>nixos-install</command>. Otherwise, fix your

     

       424
       424
       +
            <filename>configuration.nix</filename> and then re-run

     

       425
       425
       +
            <command>nixos-install</command>.

     

       315
       426
        
           </para>

     

       316
       427
        
           <para>

     

       317
       317
       -
            As the last step, <command>nixos-install</command> will ask you to set the password for the <literal>root</literal> user, e.g.

     

       428
       428
       +
            As the last step, <command>nixos-install</command> will ask you to set the

     

       429
       429
       +
            password for the <literal>root</literal> user, e.g.

     

       318
       430
        
       <screen>

     

       319
       431
        
       setting root password...

     

       320
       432
        
       Enter new UNIX password: ***

     

       321
       433
        
       Retype new UNIX password: ***</screen>

     

       322
       434
        
            <note>

     

       323
       435
        
             <para>

     

       324
       324
       -
              For unattended installations, it is possible to use <command>nixos-install --no-root-passwd</command> in order to disable the password prompt entirely.

     

       436
       436
       +
              For unattended installations, it is possible to use

     

       437
       437
       +
              <command>nixos-install --no-root-passwd</command> in order to disable

     

       438
       438
       +
              the password prompt entirely.

     

       325
       439
        
             </para>

     

       326
       440
        
            </note>

     

       327
       441
        
           </para>

     
···

       335
       449
        
          </listitem>

     

       336
       450
        
          <listitem>

     

       337
       451
        
           <para>

     

       338
       338
       -
            You should now be able to boot into the installed NixOS. The GRUB boot menu shows a list of <emphasis>available configurations</emphasis> (initially just one). Every time you change the NixOS configuration (see <link

     

       339
       339
       -
               linkend="sec-changing-config">Changing Configuration</link> ), a new item is added to the menu. This allows you to easily roll back to a previous configuration if something goes wrong.

     

       452
       452
       +
            You should now be able to boot into the installed NixOS. The GRUB boot

     

       453
       453
       +
            menu shows a list of <emphasis>available configurations</emphasis>

     

       454
       454
       +
            (initially just one). Every time you change the NixOS configuration (see

     

       455
       455
       +
            <link

     

       456
       456
       +
               linkend="sec-changing-config">Changing Configuration</link>

     

       457
       457
       +
            ), a new item is added to the menu. This allows you to easily roll back to

     

       458
       458
       +
            a previous configuration if something goes wrong.

     

       340
       459
        
           </para>

     

       341
       460
        
           <para>

     

       342
       342
       -
            You should log in and change the <literal>root</literal> password with <command>passwd</command>.

     

       461
       461
       +
            You should log in and change the <literal>root</literal> password with

     

       462
       462
       +
            <command>passwd</command>.

     

       343
       463
        
           </para>

     

       344
       464
        
           <para>

     

       345
       345
       -
            You’ll probably want to create some user accounts as well, which can be done with <command>useradd</command>:

     

       465
       465
       +
            You’ll probably want to create some user accounts as well, which can be

     

       466
       466
       +
            done with <command>useradd</command>:

     

       346
       467
        
       <screen>

     

       347
       468
        
       <prompt>$ </prompt>useradd -c 'Eelco Dolstra' -m eelco

     

       348
       469
        
       <prompt>$ </prompt>passwd eelco</screen>

     
···

       363
       484
        
         <title>Installation summary</title>

     

       364
       485
        
       

     

       365
       486
        
         <para>

     

       366
       366
       -
          To summarise, <xref linkend="ex-install-sequence" /> shows a typical sequence of commands for installing NixOS on an empty hard drive (here <filename>/dev/sda</filename>). <xref linkend="ex-config"

     

       367
       367
       -
       /> shows a corresponding configuration Nix expression.

     

       487
       487
       +
          To summarise, <xref linkend="ex-install-sequence" /> shows a typical

     

       488
       488
       +
          sequence of commands for installing NixOS on an empty hard drive (here

     

       489
       489
       +
          <filename>/dev/sda</filename>). <xref linkend="ex-config"

     

       490
       490
       +
       /> shows a

     

       491
       491
       +
          corresponding configuration Nix expression.

     

       368
       492
        
         </para>

     

       369
       493
        
       

     

       370
       494
        
         <example xml:id="ex-partition-scheme-MBR">

+29 -9

nixos/doc/manual/installation/obtaining.xml

···

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

     

       6
       6
        
        <title>Obtaining NixOS</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         NixOS ISO images can be downloaded from the <link

     

       9
       9
       -
       xlink:href="http://nixos.org/nixos/download.html">NixOS download page</link>. There are a number of installation options. If you happen to have an optical drive and a spare CD, burning the image to CD and booting from that is probably the easiest option. Most people will need to prepare a USB stick to boot from. <xref linkend="sec-booting-from-usb"/> describes the preferred method to prepare a USB stick. A number of alternative methods are presented in the <link

     

       10
       10
       -
       xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS Wiki</link>.

     

       8
       8
       +
         NixOS ISO images can be downloaded from the

     

       9
       9
       +
         <link

     

       10
       10
       +
       xlink:href="http://nixos.org/nixos/download.html">NixOS download

     

       11
       11
       +
         page</link>. There are a number of installation options. If you happen to

     

       12
       12
       +
         have an optical drive and a spare CD, burning the image to CD and booting

     

       13
       13
       +
         from that is probably the easiest option. Most people will need to prepare a

     

       14
       14
       +
         USB stick to boot from. <xref linkend="sec-booting-from-usb"/> describes the

     

       15
       15
       +
         preferred method to prepare a USB stick. A number of alternative methods are

     

       16
       16
       +
         presented in the

     

       17
       17
       +
         <link

     

       18
       18
       +
       xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS

     

       19
       19
       +
         Wiki</link>.

     

       11
       20
        
        </para>

     

       12
       21
        
        <para>

     

       13
       13
       -
         As an alternative to installing NixOS yourself, you can get a running NixOS system through several other means:

     

       22
       22
       +
         As an alternative to installing NixOS yourself, you can get a running NixOS

     

       23
       23
       +
         system through several other means:

     

       14
       24
        
         <itemizedlist>

     

       15
       25
        
          <listitem>

     

       16
       26
        
           <para>

     

       17
       17
       -
            Using virtual appliances in Open Virtualization Format (OVF) that can be imported into VirtualBox. These are available from the <link xlink:href="http://nixos.org/nixos/download.html">NixOS download page</link>.

     

       27
       27
       +
            Using virtual appliances in Open Virtualization Format (OVF) that can be

     

       28
       28
       +
            imported into VirtualBox. These are available from the

     

       29
       29
       +
            <link xlink:href="http://nixos.org/nixos/download.html">NixOS download

     

       30
       30
       +
            page</link>.

     

       18
       31
        
           </para>

     

       19
       32
        
          </listitem>

     

       20
       33
        
          <listitem>

     

       21
       34
        
           <para>

     

       22
       22
       -
            Using AMIs for Amazon’s EC2. To find one for your region and instance type, please refer to the <link

     

       23
       23
       -
           xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list of most recent AMIs</link>.

     

       35
       35
       +
            Using AMIs for Amazon’s EC2. To find one for your region and instance

     

       36
       36
       +
            type, please refer to the

     

       37
       37
       +
            <link

     

       38
       38
       +
           xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list

     

       39
       39
       +
            of most recent AMIs</link>.

     

       24
       40
        
           </para>

     

       25
       41
        
          </listitem>

     

       26
       42
        
          <listitem>

     

       27
       43
        
           <para>

     

       28
       28
       -
            Using NixOps, the NixOS-based cloud deployment tool, which allows you to provision VirtualBox and EC2 NixOS instances from declarative specifications. Check out the <link

     

       29
       29
       -
           xlink:href="https://nixos.org/nixops">NixOps homepage</link> for details.

     

       44
       44
       +
            Using NixOps, the NixOS-based cloud deployment tool, which allows you to

     

       45
       45
       +
            provision VirtualBox and EC2 NixOS instances from declarative

     

       46
       46
       +
            specifications. Check out the

     

       47
       47
       +
            <link

     

       48
       48
       +
           xlink:href="https://nixos.org/nixops">NixOps homepage</link> for

     

       49
       49
       +
            details.

     

       30
       50
        
           </para>

     

       31
       51
        
          </listitem>

     

       32
       52
        
         </itemizedlist>

+65 -17

nixos/doc/manual/installation/upgrading.xml

···

       4
       4
        
                xml:id="sec-upgrading">

     

       5
       5
        
        <title>Upgrading NixOS</title>

     

       6
       6
        
        <para>

     

       7
       7
       -
         The best way to keep your NixOS installation up to date is to use one of the NixOS <emphasis>channels</emphasis>. A channel is a Nix mechanism for distributing Nix expressions and associated binaries. The NixOS channels are updated automatically from NixOS’s Git repository after certain tests have passed and all packages have been built. These channels are:

     

       7
       7
       +
         The best way to keep your NixOS installation up to date is to use one of the

     

       8
       8
       +
         NixOS <emphasis>channels</emphasis>. A channel is a Nix mechanism for

     

       9
       9
       +
         distributing Nix expressions and associated binaries. The NixOS channels are

     

       10
       10
       +
         updated automatically from NixOS’s Git repository after certain tests have

     

       11
       11
       +
         passed and all packages have been built. These channels are:

     

       8
       12
        
         <itemizedlist>

     

       9
       13
        
          <listitem>

     

       10
       14
        
           <para>

     

       11
       11
       -
            <emphasis>Stable channels</emphasis>, such as <literal

     

       12
       12
       -
           xlink:href="https://nixos.org/channels/nixos-19.03">nixos-19.03</literal>. These only get conservative bug fixes and package upgrades. For instance, a channel update may cause the Linux kernel on your system to be upgraded from 4.19.34 to 4.19.38 (a minor bug fix), but not from 4.19.<replaceable>x</replaceable> to 4.20.<replaceable>x</replaceable> (a major change that has the potential to break things). Stable channels are generally maintained until the next stable branch is created.

     

       15
       15
       +
            <emphasis>Stable channels</emphasis>, such as

     

       16
       16
       +
            <literal

     

       17
       17
       +
           xlink:href="https://nixos.org/channels/nixos-19.03">nixos-19.03</literal>.

     

       18
       18
       +
            These only get conservative bug fixes and package upgrades. For instance,

     

       19
       19
       +
            a channel update may cause the Linux kernel on your system to be upgraded

     

       20
       20
       +
            from 4.19.34 to 4.19.38 (a minor bug fix), but not from

     

       21
       21
       +
            4.19.<replaceable>x</replaceable> to 4.20.<replaceable>x</replaceable> (a

     

       22
       22
       +
            major change that has the potential to break things). Stable channels are

     

       23
       23
       +
            generally maintained until the next stable branch is created.

     

       13
       24
        
           </para>

     

       14
       25
        
           <para></para>

     

       15
       26
        
          </listitem>

     

       16
       27
        
          <listitem>

     

       17
       28
        
           <para>

     

       18
       18
       -
            The <emphasis>unstable channel</emphasis>, <literal

     

       19
       19
       -
           xlink:href="https://nixos.org/channels/nixos-unstable">nixos-unstable</literal>. This corresponds to NixOS’s main development branch, and may thus see radical changes between channel updates. It’s not recommended for production systems.

     

       29
       29
       +
            The <emphasis>unstable channel</emphasis>,

     

       30
       30
       +
            <literal

     

       31
       31
       +
           xlink:href="https://nixos.org/channels/nixos-unstable">nixos-unstable</literal>.

     

       32
       32
       +
            This corresponds to NixOS’s main development branch, and may thus see

     

       33
       33
       +
            radical changes between channel updates. It’s not recommended for

     

       34
       34
       +
            production systems.

     

       20
       35
        
           </para>

     

       21
       36
        
          </listitem>

     

       22
       37
        
          <listitem>

     

       23
       38
        
           <para>

     

       24
       24
       -
            <emphasis>Small channels</emphasis>, such as <literal

     

       25
       25
       -
           xlink:href="https://nixos.org/channels/nixos-19.03-small">nixos-19.03-small</literal> or <literal

     

       26
       26
       -
           xlink:href="https://nixos.org/channels/nixos-unstable-small">nixos-unstable-small</literal>. These are identical to the stable and unstable channels described above, except that they contain fewer binary packages. This means they get updated faster than the regular channels (for instance, when a critical security patch is committed to NixOS’s source tree), but may require more packages to be built from source than usual. They’re mostly intended for server environments and as such contain few GUI applications.

     

       39
       39
       +
            <emphasis>Small channels</emphasis>, such as

     

       40
       40
       +
            <literal

     

       41
       41
       +
           xlink:href="https://nixos.org/channels/nixos-19.03-small">nixos-19.03-small</literal>

     

       42
       42
       +
            or

     

       43
       43
       +
            <literal

     

       44
       44
       +
           xlink:href="https://nixos.org/channels/nixos-unstable-small">nixos-unstable-small</literal>.

     

       45
       45
       +
            These are identical to the stable and unstable channels described above,

     

       46
       46
       +
            except that they contain fewer binary packages. This means they get

     

       47
       47
       +
            updated faster than the regular channels (for instance, when a critical

     

       48
       48
       +
            security patch is committed to NixOS’s source tree), but may require

     

       49
       49
       +
            more packages to be built from source than usual. They’re mostly

     

       50
       50
       +
            intended for server environments and as such contain few GUI applications.

     

       27
       51
        
           </para>

     

       28
       52
        
          </listitem>

     

       29
       53
        
         </itemizedlist>

     

       30
       30
       -
         To see what channels are available, go to <link xlink:href="https://nixos.org/channels"/>. (Note that the URIs of the various channels redirect to a directory that contains the channel’s latest version and includes ISO images and VirtualBox appliances.) Please note that during the release process, channels that are not yet released will be present here as well. See the Getting NixOS page <link xlink:href="https://nixos.org/nixos/download.html"/> to find the newest supported stable release.

     

       54
       54
       +
         To see what channels are available, go to

     

       55
       55
       +
         <link xlink:href="https://nixos.org/channels"/>. (Note that the URIs of the

     

       56
       56
       +
         various channels redirect to a directory that contains the channel’s latest

     

       57
       57
       +
         version and includes ISO images and VirtualBox appliances.) Please note that

     

       58
       58
       +
         during the release process, channels that are not yet released will be

     

       59
       59
       +
         present here as well. See the Getting NixOS page

     

       60
       60
       +
         <link xlink:href="https://nixos.org/nixos/download.html"/> to find the newest

     

       61
       61
       +
         supported stable release.

     

       31
       62
        
        </para>

     

       32
       63
        
        <para>

     

       33
       33
       -
         When you first install NixOS, you’re automatically subscribed to the NixOS channel that corresponds to your installation source. For instance, if you installed from a 19.03 ISO, you will be subscribed to the <literal>nixos-19.03</literal> channel. To see which NixOS channel you’re subscribed to, run the following as root:

     

       64
       64
       +
         When you first install NixOS, you’re automatically subscribed to the NixOS

     

       65
       65
       +
         channel that corresponds to your installation source. For instance, if you

     

       66
       66
       +
         installed from a 19.03 ISO, you will be subscribed to the

     

       67
       67
       +
         <literal>nixos-19.03</literal> channel. To see which NixOS channel you’re

     

       68
       68
       +
         subscribed to, run the following as root:

     

       34
       69
        
       <screen>

     

       35
       70
        
       # nix-channel --list | grep nixos

     

       36
       71
        
       nixos https://nixos.org/channels/nixos-unstable

     
···

       39
       74
        
       <screen>

     

       40
       75
        
       # nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos

     

       41
       76
        
       </screen>

     

       42
       42
       -
         (Be sure to include the <literal>nixos</literal> parameter at the end.) For instance, to use the NixOS 19.03 stable channel:

     

       77
       77
       +
         (Be sure to include the <literal>nixos</literal> parameter at the end.) For

     

       78
       78
       +
         instance, to use the NixOS 19.03 stable channel:

     

       43
       79
        
       <screen>

     

       44
       80
        
       # nix-channel --add https://nixos.org/channels/nixos-19.03 nixos

     

       45
       81
        
       </screen>

     
···

       53
       89
        
       </screen>

     

       54
       90
        
        </para>

     

       55
       91
        
        <para>

     

       56
       56
       -
         You can then upgrade NixOS to the latest version in your chosen channel by running

     

       92
       92
       +
         You can then upgrade NixOS to the latest version in your chosen channel by

     

       93
       93
       +
         running

     

       57
       94
        
       <screen>

     

       58
       95
        
       # nixos-rebuild switch --upgrade

     

       59
       96
        
       </screen>

     

       60
       60
       -
         which is equivalent to the more verbose <literal>nix-channel --update nixos; nixos-rebuild switch</literal>.

     

       97
       97
       +
         which is equivalent to the more verbose <literal>nix-channel --update nixos;

     

       98
       98
       +
         nixos-rebuild switch</literal>.

     

       61
       99
        
        </para>

     

       62
       100
        
        <note>

     

       63
       101
        
         <para>

     

       64
       64
       -
          Channels are set per user. This means that running <literal> nix-channel --add</literal> as a non root user (or without sudo) will not affect configuration in <literal>/etc/nixos/configuration.nix</literal>

     

       102
       102
       +
          Channels are set per user. This means that running <literal> nix-channel

     

       103
       103
       +
          --add</literal> as a non root user (or without sudo) will not affect

     

       104
       104
       +
          configuration in <literal>/etc/nixos/configuration.nix</literal>

     

       65
       105
        
         </para>

     

       66
       106
        
        </note>

     

       67
       107
        
        <warning>

     

       68
       108
        
         <para>

     

       69
       69
       -
          It is generally safe to switch back and forth between channels. The only exception is that a newer NixOS may also have a newer Nix version, which may involve an upgrade of Nix’s database schema. This cannot be undone easily, so in that case you will not be able to go back to your original channel.

     

       109
       109
       +
          It is generally safe to switch back and forth between channels. The only

     

       110
       110
       +
          exception is that a newer NixOS may also have a newer Nix version, which may

     

       111
       111
       +
          involve an upgrade of Nix’s database schema. This cannot be undone easily,

     

       112
       112
       +
          so in that case you will not be able to go back to your original channel.

     

       70
       113
        
         </para>

     

       71
       114
        
        </warning>

     

       72
       115
        
        <section xml:id="sec-upgrading-automatic">

     

       73
       116
        
         <title>Automatic Upgrades</title>

     

       74
       117
        
       

     

       75
       118
        
         <para>

     

       76
       76
       -
          You can keep a NixOS system up-to-date automatically by adding the following to <filename>configuration.nix</filename>:

     

       119
       119
       +
          You can keep a NixOS system up-to-date automatically by adding the following

     

       120
       120
       +
          to <filename>configuration.nix</filename>:

     

       77
       121
        
       <programlisting>

     

       78
       122
        
       <xref linkend="opt-system.autoUpgrade.enable"/> = true;

     

       79
       123
        
       </programlisting>

     

       80
       80
       -
          This enables a periodically executed systemd service named <literal>nixos-upgrade.service</literal>. It runs <command>nixos-rebuild switch --upgrade</command> to upgrade NixOS to the latest version in the current channel. (To see when the service runs, see <command>systemctl list-timers</command>.) You can also specify a channel explicitly, e.g.

     

       124
       124
       +
          This enables a periodically executed systemd service named

     

       125
       125
       +
          <literal>nixos-upgrade.service</literal>. It runs <command>nixos-rebuild

     

       126
       126
       +
          switch --upgrade</command> to upgrade NixOS to the latest version in the

     

       127
       127
       +
          current channel. (To see when the service runs, see <command>systemctl

     

       128
       128
       +
          list-timers</command>.) You can also specify a channel explicitly, e.g.

     

       81
       129
        
       <programlisting>

     

       82
       130
        
       <xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-19.03;

     

       83
       131
        
       </programlisting>

+4 -1

nixos/doc/manual/man-configuration.xml

···

       14
       14
        
        <refsection>

     

       15
       15
        
         <title>Description</title>

     

       16
       16
        
         <para>

     

       17
       17
       -
          The file <filename>/etc/nixos/configuration.nix</filename> contains the declarative specification of your NixOS system configuration. The command <command>nixos-rebuild</command> takes this file and realises the system configuration specified therein.

     

       17
       17
       +
          The file <filename>/etc/nixos/configuration.nix</filename> contains the

     

       18
       18
       +
          declarative specification of your NixOS system configuration. The command

     

       19
       19
       +
          <command>nixos-rebuild</command> takes this file and realises the system

     

       20
       20
       +
          configuration specified therein.

     

       18
       21
        
         </para>

     

       19
       22
        
        </refsection>

     

       20
       23
        
        <refsection>

+29 -12

nixos/doc/manual/man-nixos-build-vms.xml

···

       24
       24
        
           

     

       25
       25
        
          <arg>

     

       26
       26
        
           <option>--help</option>

     

       27
       27
       -
          </arg>

     

       28
       28
       -
           

     

       29
       29
       -
          <arg>

     

       30
       30
       -
           <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>

     

       31
       31
       -
          </arg>

     

       32
       32
       -
           

     

       27
       27
       +
         </arg>

     

       28
       28
       +
       

     

       29
       29
       +
         <arg>

     

       30
       30
       +
           <option>--option</option>

     

       31
       31
       +
           <replaceable>name</replaceable>

     

       32
       32
       +
           <replaceable>value</replaceable>

     

       33
       33
       +
         </arg>

     

       34
       34
       +
       

     

       33
       35
        
          <arg choice="plain">

     

       34
       36
        
           <replaceable>network.nix</replaceable>

     

       35
       37
        
          </arg>

     
···

       38
       40
        
        <refsection>

     

       39
       41
        
         <title>Description</title>

     

       40
       42
        
         <para>

     

       41
       41
       -
          This command builds a network of QEMU-KVM virtual machines of a Nix expression specifying a network of NixOS machines. The virtual network can be started by executing the <filename>bin/run-vms</filename> shell script that is generated by this command. By default, a <filename>result</filename> symlink is produced that points to the generated virtual network.

     

       43
       43
       +
          This command builds a network of QEMU-KVM virtual machines of a Nix

     

       44
       44
       +
          expression specifying a network of NixOS machines. The virtual network can

     

       45
       45
       +
          be started by executing the <filename>bin/run-vms</filename> shell script

     

       46
       46
       +
          that is generated by this command. By default, a <filename>result</filename>

     

       47
       47
       +
          symlink is produced that points to the generated virtual network.

     

       42
       48
        
         </para>

     

       43
       49
        
         <para>

     

       44
       50
        
          A network Nix expression has the following structure:

     
···

       65
       71
        
           };

     

       66
       72
        
       }

     

       67
       73
        
       </screen>

     

       68
       68
       -
          Each attribute in the expression represents a machine in the network (e.g. <varname>test1</varname> and <varname>test2</varname>) referring to a function defining a NixOS configuration. In each NixOS configuration, two attributes have a special meaning. The <varname>deployment.targetHost</varname> specifies the address (domain name or IP address) of the system which is used by <command>ssh</command> to perform remote deployment operations. The <varname>nixpkgs.localSystem.system</varname> attribute can be used to specify an architecture for the target machine, such as <varname>i686-linux</varname> which builds a 32-bit NixOS configuration. Omitting this property will build the configuration for the same architecture as the host system.

     

       74
       74
       +
          Each attribute in the expression represents a machine in the network (e.g.

     

       75
       75
       +
          <varname>test1</varname> and <varname>test2</varname>) referring to a

     

       76
       76
       +
          function defining a NixOS configuration. In each NixOS configuration, two

     

       77
       77
       +
          attributes have a special meaning. The

     

       78
       78
       +
          <varname>deployment.targetHost</varname> specifies the address (domain name

     

       79
       79
       +
          or IP address) of the system which is used by <command>ssh</command> to

     

       80
       80
       +
          perform remote deployment operations. The

     

       81
       81
       +
          <varname>nixpkgs.localSystem.system</varname> attribute can be used to

     

       82
       82
       +
          specify an architecture for the target machine, such as

     

       83
       83
       +
          <varname>i686-linux</varname> which builds a 32-bit NixOS configuration.

     

       84
       84
       +
          Omitting this property will build the configuration for the same

     

       85
       85
       +
          architecture as the host system.

     

       69
       86
        
         </para>

     

       70
       87
        
        </refsection>

     

       71
       88
        
        <refsection>

     
···

       109
       126
        
            <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>

     

       110
       127
        
           </term>

     

       111
       128
        
           <listitem>

     

       112
       112
       -
            <para>

     

       113
       113
       -
             Set the Nix configuration option <replaceable>name</replaceable> to <replaceable>value</replaceable>. This overrides settings in the Nix configuration file (see <citerefentry>

     

       114
       114
       -
             <refentrytitle>nix.conf</refentrytitle>

     

       115
       115
       -
             <manvolnum>5</manvolnum></citerefentry>).

     

       129
       129
       +
            <para>Set the Nix configuration option

     

       130
       130
       +
             <replaceable>name</replaceable> to <replaceable>value</replaceable>.

     

       131
       131
       +
             This overrides settings in the Nix configuration file (see

     

       132
       132
       +
             <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).

     

       116
       133
        
            </para>

     

       117
       134
        
           </listitem>

     

       118
       135
        
          </varlistentry>

+15 -7

nixos/doc/manual/man-nixos-enter.xml

···

       34
       34
        
           </arg>

     

       35
       35
        
            <replaceable>shell-command</replaceable>

     

       36
       36
        
          </arg>

     

       37
       37
       -
           

     

       37
       37
       +
       

     

       38
       38
        
          <arg>

     

       39
       39
        
           <arg choice='plain'>

     

       40
       40
        
            <option>--silent</option>

     
···

       58
       58
        
        <refsection>

     

       59
       59
        
         <title>Description</title>

     

       60
       60
        
         <para>

     

       61
       61
       -
          This command runs a command in a NixOS chroot environment, that is, in a filesystem hierarchy previously prepared using <command>nixos-install</command>.

     

       61
       61
       +
          This command runs a command in a NixOS chroot environment, that is, in a

     

       62
       62
       +
          filesystem hierarchy previously prepared using

     

       63
       63
       +
          <command>nixos-install</command>.

     

       62
       64
        
         </para>

     

       63
       65
        
        </refsection>

     

       64
       66
        
        <refsection>

     
···

       73
       75
        
           </term>

     

       74
       76
        
           <listitem>

     

       75
       77
        
            <para>

     

       76
       76
       -
             The path to the NixOS system you want to enter. It defaults to <filename>/mnt</filename>.

     

       78
       78
       +
             The path to the NixOS system you want to enter. It defaults to

     

       79
       79
       +
             <filename>/mnt</filename>.

     

       77
       80
        
            </para>

     

       78
       81
        
           </listitem>

     

       79
       82
        
          </varlistentry>

     
···

       83
       86
        
           </term>

     

       84
       87
        
           <listitem>

     

       85
       88
        
            <para>

     

       86
       86
       -
             The NixOS system configuration to use. It defaults to <filename>/nix/var/nix/profiles/system</filename>. You can enter a previous NixOS configuration by specifying a path such as <filename>/nix/var/nix/profiles/system-106-link</filename>.

     

       89
       89
       +
             The NixOS system configuration to use. It defaults to

     

       90
       90
       +
             <filename>/nix/var/nix/profiles/system</filename>. You can enter a

     

       91
       91
       +
             previous NixOS configuration by specifying a path such as

     

       92
       92
       +
             <filename>/nix/var/nix/profiles/system-106-link</filename>.

     

       87
       93
        
            </para>

     

       88
       94
        
           </listitem>

     

       89
       95
        
          </varlistentry>

     
···

       106
       112
        
           </term>

     

       107
       113
        
           <listitem>

     

       108
       114
        
            <para>

     

       109
       109
       -
             Suppresses all output from the activation script of the target system.

     

       115
       115
       +
              Suppresses all output from the activation script of the target system.

     

       110
       116
        
            </para>

     

       111
       117
        
           </listitem>

     

       112
       118
        
          </varlistentry>

     
···

       116
       122
        
           </term>

     

       117
       123
        
           <listitem>

     

       118
       124
        
            <para>

     

       119
       119
       -
             Interpret the remaining arguments as the program name and arguments to be invoked. The program is not executed in a shell.

     

       125
       125
       +
             Interpret the remaining arguments as the program name and arguments to be

     

       126
       126
       +
             invoked. The program is not executed in a shell.

     

       120
       127
        
            </para>

     

       121
       128
        
           </listitem>

     

       122
       129
        
          </varlistentry>

     
···

       125
       132
        
        <refsection>

     

       126
       133
        
         <title>Examples</title>

     

       127
       134
        
         <para>

     

       128
       128
       -
          Start an interactive shell in the NixOS installation in <filename>/mnt</filename>:

     

       135
       135
       +
          Start an interactive shell in the NixOS installation in

     

       136
       136
       +
          <filename>/mnt</filename>:

     

       129
       137
        
         </para>

     

       130
       138
        
       <screen>

     

       131
       139
        
       # nixos-enter /mnt

+49 -15

nixos/doc/manual/man-nixos-generate-config.xml

···

       13
       13
        
        </refnamediv>

     

       14
       14
        
        <refsynopsisdiv>

     

       15
       15
        
         <cmdsynopsis>

     

       16
       16
       -
          <command>nixos-generate-config</command> 

     

       16
       16
       +
          <command>nixos-generate-config</command>

     

       17
       17
        
          <arg>

     

       18
       18
        
           <option>--force</option>

     

       19
       19
        
          </arg>

     

       20
       20
       -
           

     

       20
       20
       +
       

     

       21
       21
        
          <arg>

     

       22
       22
        
           <arg choice='plain'>

     

       23
       23
        
            <option>--root</option>

     

       24
       24
        
           </arg>

     

       25
       25
        
            <replaceable>root</replaceable>

     

       26
       26
        
          </arg>

     

       27
       27
       -
           

     

       27
       27
       +
       

     

       28
       28
        
          <arg>

     

       29
       29
        
           <arg choice='plain'>

     

       30
       30
        
            <option>--dir</option>

     
···

       44
       44
        
            </term>

     

       45
       45
        
            <listitem>

     

       46
       46
        
             <para>

     

       47
       47
       -
              This module sets NixOS configuration options based on your current hardware configuration. In particular, it sets the <option>fileSystem</option> option to reflect all currently mounted file systems, the <option>swapDevices</option> option to reflect active swap devices, and the <option>boot.initrd.*</option> options to ensure that the initial ramdisk contains any kernel modules necessary for mounting the root file system.

     

       47
       47
       +
              This module sets NixOS configuration options based on your current

     

       48
       48
       +
              hardware configuration. In particular, it sets the

     

       49
       49
       +
              <option>fileSystem</option> option to reflect all currently mounted file

     

       50
       50
       +
              systems, the <option>swapDevices</option> option to reflect active swap

     

       51
       51
       +
              devices, and the <option>boot.initrd.*</option> options to ensure that

     

       52
       52
       +
              the initial ramdisk contains any kernel modules necessary for mounting

     

       53
       53
       +
              the root file system.

     

       48
       54
        
             </para>

     

       49
       55
        
             <para>

     

       50
       50
       -
              If this file already exists, it is overwritten. Thus, you should not modify it manually. Rather, you should include it from your <filename>/etc/nixos/configuration.nix</filename>, and re-run <command>nixos-generate-config</command> to update it whenever your hardware configuration changes.

     

       56
       56
       +
              If this file already exists, it is overwritten. Thus, you should not

     

       57
       57
       +
              modify it manually. Rather, you should include it from your

     

       58
       58
       +
              <filename>/etc/nixos/configuration.nix</filename>, and re-run

     

       59
       59
       +
              <command>nixos-generate-config</command> to update it whenever your

     

       60
       60
       +
              hardware configuration changes.

     

       51
       61
        
             </para>

     

       52
       62
        
            </listitem>

     

       53
       63
        
           </varlistentry>

     
···

       57
       67
        
            </term>

     

       58
       68
        
            <listitem>

     

       59
       69
        
             <para>

     

       60
       60
       -
              This is the main NixOS system configuration module. If it already exists, it’s left unchanged. Otherwise, <command>nixos-generate-config</command> will write a template for you to customise.

     

       70
       70
       +
              This is the main NixOS system configuration module. If it already

     

       71
       71
       +
              exists, it’s left unchanged. Otherwise,

     

       72
       72
       +
              <command>nixos-generate-config</command> will write a template for you

     

       73
       73
       +
              to customise.

     

       61
       74
        
             </para>

     

       62
       75
        
            </listitem>

     

       63
       76
        
           </varlistentry>

     
···

       76
       89
        
           </term>

     

       77
       90
        
           <listitem>

     

       78
       91
        
            <para>

     

       79
       79
       -
             If this option is given, treat the directory <replaceable>root</replaceable> as the root of the file system. This means that configuration files will be written to <filename><replaceable>root</replaceable>/etc/nixos</filename>, and that any file systems outside of <replaceable>root</replaceable> are ignored for the purpose of generating the <option>fileSystems</option> option.

     

       92
       92
       +
             If this option is given, treat the directory

     

       93
       93
       +
             <replaceable>root</replaceable> as the root of the file system. This

     

       94
       94
       +
             means that configuration files will be written to

     

       95
       95
       +
             <filename><replaceable>root</replaceable>/etc/nixos</filename>, and that

     

       96
       96
       +
             any file systems outside of <replaceable>root</replaceable> are ignored

     

       97
       97
       +
             for the purpose of generating the <option>fileSystems</option> option.

     

       80
       98
        
            </para>

     

       81
       99
        
           </listitem>

     

       82
       100
        
          </varlistentry>

     
···

       86
       104
        
           </term>

     

       87
       105
        
           <listitem>

     

       88
       106
        
            <para>

     

       89
       89
       -
             If this option is given, write the configuration files to the directory <replaceable>dir</replaceable> instead of <filename>/etc/nixos</filename>.

     

       107
       107
       +
             If this option is given, write the configuration files to the directory

     

       108
       108
       +
             <replaceable>dir</replaceable> instead of

     

       109
       109
       +
             <filename>/etc/nixos</filename>.

     

       90
       110
        
            </para>

     

       91
       111
        
           </listitem>

     

       92
       112
        
          </varlistentry>

     
···

       96
       116
        
           </term>

     

       97
       117
        
           <listitem>

     

       98
       118
        
            <para>

     

       99
       99
       -
             Overwrite <filename>/etc/nixos/configuration.nix</filename> if it already exists.

     

       119
       119
       +
             Overwrite <filename>/etc/nixos/configuration.nix</filename> if it already

     

       120
       120
       +
             exists.

     

       100
       121
        
            </para>

     

       101
       122
        
           </listitem>

     

       102
       123
        
          </varlistentry>

     
···

       106
       127
        
           </term>

     

       107
       128
        
           <listitem>

     

       108
       129
        
            <para>

     

       109
       109
       -
             Omit everything concerning file systems and swap devices from the hardware configuration.

     

       130
       130
       +
             Omit everything concerning file systems and swap devices from the

     

       131
       131
       +
             hardware configuration.

     

       110
       132
        
            </para>

     

       111
       133
        
           </listitem>

     

       112
       134
        
          </varlistentry>

     
···

       116
       138
        
           </term>

     

       117
       139
        
           <listitem>

     

       118
       140
        
            <para>

     

       119
       119
       -
             Don't generate <filename>configuration.nix</filename> or <filename>hardware-configuration.nix</filename> and print the hardware configuration to stdout only.

     

       141
       141
       +
             Don't generate <filename>configuration.nix</filename> or

     

       142
       142
       +
             <filename>hardware-configuration.nix</filename> and print the hardware

     

       143
       143
       +
             configuration to stdout only.

     

       120
       144
        
            </para>

     

       121
       145
        
           </listitem>

     

       122
       146
        
          </varlistentry>

     
···

       125
       149
        
        <refsection>

     

       126
       150
        
         <title>Examples</title>

     

       127
       151
        
         <para>

     

       128
       128
       -
          This command is typically used during NixOS installation to write initial configuration modules. For example, if you created and mounted the target file systems on <filename>/mnt</filename> and <filename>/mnt/boot</filename>, you would run:

     

       152
       152
       +
          This command is typically used during NixOS installation to write initial

     

       153
       153
       +
          configuration modules. For example, if you created and mounted the target

     

       154
       154
       +
          file systems on <filename>/mnt</filename> and

     

       155
       155
       +
          <filename>/mnt/boot</filename>, you would run:

     

       129
       156
        
       <screen>

     

       130
       157
        
       <prompt>$ </prompt>nixos-generate-config --root /mnt

     

       131
       158
        
       </screen>

     

       132
       132
       -
          The resulting file <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might look like this:

     

       159
       159
       +
          The resulting file

     

       160
       160
       +
          <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might look

     

       161
       161
       +
          like this:

     

       133
       162
        
       <programlisting>

     

       134
       163
        
       # Do not modify this file!  It was generated by ‘nixos-generate-config’

     

       135
       164
        
       # and may be overwritten by future invocations.  Please make changes

     
···

       164
       193
        
         nix.maxJobs = 8;

     

       165
       194
        
       }

     

       166
       195
        
       </programlisting>

     

       167
       167
       -
          It will also create a basic <filename>/mnt/etc/nixos/configuration.nix</filename>, which you should edit to customise the logical configuration of your system. This file includes the result of the hardware scan as follows:

     

       196
       196
       +
          It will also create a basic

     

       197
       197
       +
          <filename>/mnt/etc/nixos/configuration.nix</filename>, which you should edit

     

       198
       198
       +
          to customise the logical configuration of your system. This file includes

     

       199
       199
       +
          the result of the hardware scan as follows:

     

       168
       200
        
       <programlisting>

     

       169
       201
        
         imports = [ ./hardware-configuration.nix ];

     

       170
       202
        
       </programlisting>

     
···

       174
       206
        
       <screen>

     

       175
       207
        
       <prompt>$ </prompt>nixos-generate-config

     

       176
       208
        
       </screen>

     

       177
       177
       -
          to update <filename>/etc/nixos/hardware-configuration.nix</filename>. Your <filename>/etc/nixos/configuration.nix</filename> will <emphasis>not</emphasis> be overwritten.

     

       209
       209
       +
          to update <filename>/etc/nixos/hardware-configuration.nix</filename>. Your

     

       210
       210
       +
          <filename>/etc/nixos/configuration.nix</filename> will

     

       211
       211
       +
          <emphasis>not</emphasis> be overwritten.

     

       178
       212
        
         </para>

     

       179
       213
        
        </refsection>

     

       180
       214
        
       </refentry>

+67 -28

nixos/doc/manual/man-nixos-install.xml

···

       13
       13
        
        </refnamediv>

     

       14
       14
        
        <refsynopsisdiv>

     

       15
       15
        
         <cmdsynopsis>

     

       16
       16
       -
          <command>nixos-install</command> 

     

       16
       16
       +
          <command>nixos-install</command>

     

       17
       17
        
          <arg>

     

       18
       18
        
           <arg choice='plain'>

     

       19
       19
        
            <option>-I</option>

     

       20
       20
        
           </arg>

     

       21
       21
        
            <replaceable>path</replaceable>

     

       22
       22
        
          </arg>

     

       23
       23
       -
           

     

       23
       23
       +
       

     

       24
       24
        
          <arg>

     

       25
       25
        
           <arg choice='plain'>

     

       26
       26
        
            <option>--root</option>

     

       27
       27
        
           </arg>

     

       28
       28
        
            <replaceable>root</replaceable>

     

       29
       29
        
          </arg>

     

       30
       30
       -
           

     

       30
       30
       +
       

     

       31
       31
        
          <arg>

     

       32
       32
        
           <arg choice='plain'>

     

       33
       33
        
            <option>--system</option>

     

       34
       34
        
           </arg>

     

       35
       35
        
            <replaceable>path</replaceable>

     

       36
       36
        
          </arg>

     

       37
       37
       -
           

     

       37
       37
       +
       

     

       38
       38
        
          <arg>

     

       39
       39
        
           <arg choice='plain'>

     

       40
       40
        
            <option>--no-channel-copy</option>

     

       41
       41
        
           </arg>

     

       42
       42
        
          </arg>

     

       43
       43
       -
           

     

       43
       43
       +
       

     

       44
       44
        
          <arg>

     

       45
       45
        
           <arg choice='plain'>

     

       46
       46
        
            <option>--no-root-passwd</option>

     

       47
       47
        
           </arg>

     

       48
       48
        
          </arg>

     

       49
       49
       -
           

     

       49
       49
       +
       

     

       50
       50
        
          <arg>

     

       51
       51
        
           <arg choice='plain'>

     

       52
       52
        
            <option>--no-bootloader</option>

     

       53
       53
        
           </arg>

     

       54
       54
        
          </arg>

     

       55
       55
       -
           

     

       55
       55
       +
       

     

       56
       56
        
          <arg>

     

       57
       57
       -
           <group choice='req'> 

     

       57
       57
       +
           <group choice='req'>

     

       58
       58
        
           <arg choice='plain'>

     

       59
       59
        
            <option>--max-jobs</option>

     

       60
       60
        
           </arg>

     

       61
       61
       -
            

     

       61
       61
       +
       

     

       62
       62
        
           <arg choice='plain'>

     

       63
       63
        
            <option>-j</option>

     

       64
       64
        
           </arg>

     

       65
       65
        
            </group> <replaceable>number</replaceable>

     

       66
       66
        
          </arg>

     

       67
       67
       -
           

     

       67
       67
       +
       

     

       68
       68
        
          <arg>

     

       69
       69
        
           <option>--cores</option> <replaceable>number</replaceable>

     

       70
       70
        
          </arg>

     

       71
       71
       -
           

     

       71
       71
       +
       

     

       72
       72
        
          <arg>

     

       73
       73
        
           <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>

     

       74
       74
        
          </arg>

     

       75
       75
       -
           

     

       75
       75
       +
       

     

       76
       76
        
          <arg>

     

       77
       77
        
           <arg choice='plain'>

     

       78
       78
        
            <option>--show-trace</option>

     

       79
       79
        
           </arg>

     

       80
       80
        
          </arg>

     

       81
       81
       -
           

     

       81
       81
       +
       

     

       82
       82
        
          <arg>

     

       83
       83
        
           <arg choice='plain'>

     

       84
       84
        
            <option>--help</option>

     
···

       89
       89
        
        <refsection>

     

       90
       90
        
         <title>Description</title>

     

       91
       91
        
         <para>

     

       92
       92
       -
          This command installs NixOS in the file system mounted on <filename>/mnt</filename>, based on the NixOS configuration specified in <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs the following steps:

     

       92
       92
       +
          This command installs NixOS in the file system mounted on

     

       93
       93
       +
          <filename>/mnt</filename>, based on the NixOS configuration specified in

     

       94
       94
       +
          <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs the

     

       95
       95
       +
          following steps:

     

       93
       96
        
          <itemizedlist>

     

       94
       97
        
           <listitem>

     

       95
       98
        
            <para>

     

       96
       96
       -
             It copies Nix and its dependencies to <filename>/mnt/nix/store</filename>.

     

       99
       99
       +
             It copies Nix and its dependencies to

     

       100
       100
       +
             <filename>/mnt/nix/store</filename>.

     

       97
       101
        
            </para>

     

       98
       102
        
           </listitem>

     

       99
       103
        
           <listitem>

     

       100
       104
        
            <para>

     

       101
       101
       -
             It runs Nix in <filename>/mnt</filename> to build the NixOS configuration specified in <filename>/mnt/etc/nixos/configuration.nix</filename>.

     

       105
       105
       +
             It runs Nix in <filename>/mnt</filename> to build the NixOS configuration

     

       106
       106
       +
             specified in <filename>/mnt/etc/nixos/configuration.nix</filename>.

     

       102
       107
        
            </para>

     

       103
       108
        
           </listitem>

     

       104
       109
        
           <listitem>

     

       105
       110
        
            <para>

     

       106
       106
       -
             It installs the GRUB boot loader on the device specified in the option <option>boot.loader.grub.device</option> (unless <option>--no-bootloader</option> is specified), and generates a GRUB configuration file that boots into the NixOS configuration just installed.

     

       111
       111
       +
             It installs the GRUB boot loader on the device specified in the option

     

       112
       112
       +
             <option>boot.loader.grub.device</option> (unless

     

       113
       113
       +
             <option>--no-bootloader</option> is specified), and generates a GRUB

     

       114
       114
       +
             configuration file that boots into the NixOS configuration just

     

       115
       115
       +
             installed.

     

       107
       116
        
            </para>

     

       108
       117
        
           </listitem>

     

       109
       118
        
           <listitem>

     

       110
       119
        
            <para>

     

       111
       111
       -
             It prompts you for a password for the root account (unless <option>--no-root-passwd</option> is specified).

     

       120
       120
       +
             It prompts you for a password for the root account (unless

     

       121
       121
       +
             <option>--no-root-passwd</option> is specified).

     

       112
       122
        
            </para>

     

       113
       123
        
           </listitem>

     

       114
       124
        
          </itemizedlist>

     

       115
       125
        
         </para>

     

       116
       126
        
         <para>

     

       117
       117
       -
          This command is idempotent: if it is interrupted or fails due to a temporary problem (e.g. a network issue), you can safely re-run it.

     

       127
       127
       +
          This command is idempotent: if it is interrupted or fails due to a temporary

     

       128
       128
       +
          problem (e.g. a network issue), you can safely re-run it.

     

       118
       129
        
         </para>

     

       119
       130
        
        </refsection>

     

       120
       131
        
        <refsection>

     
···

       129
       140
        
           </term>

     

       130
       141
        
           <listitem>

     

       131
       142
        
            <para>

     

       132
       132
       -
             Defaults to <filename>/mnt</filename>. If this option is given, treat the directory <replaceable>root</replaceable> as the root of the NixOS installation.

     

       143
       143
       +
             Defaults to <filename>/mnt</filename>. If this option is given, treat the

     

       144
       144
       +
             directory <replaceable>root</replaceable> as the root of the NixOS

     

       145
       145
       +
             installation.

     

       133
       146
        
            </para>

     

       134
       147
        
           </listitem>

     

       135
       148
        
          </varlistentry>

     
···

       139
       152
        
           </term>

     

       140
       153
        
           <listitem>

     

       141
       154
        
            <para>

     

       142
       142
       -
             If this option is provided, <command>nixos-install</command> will install the specified closure rather than attempt to build one from <filename>/mnt/etc/nixos/configuration.nix</filename>.

     

       155
       155
       +
             If this option is provided, <command>nixos-install</command> will install

     

       156
       156
       +
             the specified closure rather than attempt to build one from

     

       157
       157
       +
             <filename>/mnt/etc/nixos/configuration.nix</filename>.

     

       143
       158
        
            </para>

     

       144
       159
        
            <para>

     

       145
       145
       -
             The closure must be an appropriately configured NixOS system, with boot loader and partition configuration that fits the target host. Such a closure is typically obtained with a command such as <command>nix-build -I nixos-config=./configuration.nix '&lt;nixos&gt;' -A system --no-out-link</command>

     

       160
       160
       +
             The closure must be an appropriately configured NixOS system, with boot

     

       161
       161
       +
             loader and partition configuration that fits the target host. Such a

     

       162
       162
       +
             closure is typically obtained with a command such as <command>nix-build

     

       163
       163
       +
             -I nixos-config=./configuration.nix '&lt;nixos&gt;' -A system

     

       164
       164
       +
             --no-out-link</command>

     

       146
       165
        
            </para>

     

       147
       166
        
           </listitem>

     

       148
       167
        
          </varlistentry>

     
···

       152
       171
        
           </term>

     

       153
       172
        
           <listitem>

     

       154
       173
        
            <para>

     

       155
       155
       -
             Add a path to the Nix expression search path. This option may be given multiple times. See the NIX_PATH environment variable for information on the semantics of the Nix search path. Paths added through <replaceable>-I</replaceable> take precedence over NIX_PATH.

     

       174
       174
       +
             Add a path to the Nix expression search path. This option may be given

     

       175
       175
       +
             multiple times. See the NIX_PATH environment variable for information on

     

       176
       176
       +
             the semantics of the Nix search path. Paths added through

     

       177
       177
       +
             <replaceable>-I</replaceable> take precedence over NIX_PATH.

     

       156
       178
        
            </para>

     

       157
       179
        
           </listitem>

     

       158
       180
        
          </varlistentry>

     
···

       165
       187
        
           </term>

     

       166
       188
        
           <listitem>

     

       167
       189
        
            <para>

     

       168
       168
       -
             Sets the maximum number of build jobs that Nix will perform in parallel to the specified number. The default is <literal>1</literal>. A higher value is useful on SMP systems or to exploit I/O latency.

     

       190
       190
       +
             Sets the maximum number of build jobs that Nix will perform in parallel

     

       191
       191
       +
             to the specified number. The default is <literal>1</literal>. A higher

     

       192
       192
       +
             value is useful on SMP systems or to exploit I/O latency.

     

       169
       193
        
            </para>

     

       170
       194
        
           </listitem>

     

       171
       195
        
          </varlistentry>

     
···

       175
       199
        
           </term>

     

       176
       200
        
           <listitem>

     

       177
       201
        
            <para>

     

       178
       178
       -
             Sets the value of the <envar>NIX_BUILD_CORES</envar> environment variable in the invocation of builders. Builders can use this variable at their discretion to control the maximum amount of parallelism. For instance, in Nixpkgs, if the derivation attribute <varname>enableParallelBuilding</varname> is set to <literal>true</literal>, the builder passes the <option>-j<replaceable>N</replaceable></option> flag to GNU Make. The value <literal>0</literal> means that the builder should use all available CPU cores in the system.

     

       202
       202
       +
             Sets the value of the <envar>NIX_BUILD_CORES</envar> environment variable

     

       203
       203
       +
             in the invocation of builders. Builders can use this variable at their

     

       204
       204
       +
             discretion to control the maximum amount of parallelism. For instance, in

     

       205
       205
       +
             Nixpkgs, if the derivation attribute

     

       206
       206
       +
             <varname>enableParallelBuilding</varname> is set to

     

       207
       207
       +
             <literal>true</literal>, the builder passes the

     

       208
       208
       +
             <option>-j<replaceable>N</replaceable></option> flag to GNU Make. The

     

       209
       209
       +
             value <literal>0</literal> means that the builder should use all

     

       210
       210
       +
             available CPU cores in the system.

     

       179
       211
        
            </para>

     

       180
       212
        
           </listitem>

     

       181
       213
        
          </varlistentry>

     
···

       185
       217
        
           </term>

     

       186
       218
        
           <listitem>

     

       187
       219
        
            <para>

     

       188
       188
       -
             Set the Nix configuration option <replaceable>name</replaceable> to <replaceable>value</replaceable>.

     

       220
       220
       +
             Set the Nix configuration option <replaceable>name</replaceable> to

     

       221
       221
       +
             <replaceable>value</replaceable>.

     

       189
       222
        
            </para>

     

       190
       223
        
           </listitem>

     

       191
       224
        
          </varlistentry>

     
···

       195
       228
        
           </term>

     

       196
       229
        
           <listitem>

     

       197
       230
        
            <para>

     

       198
       198
       -
             Causes Nix to print out a stack trace in case of Nix expression evaluation errors.

     

       231
       231
       +
             Causes Nix to print out a stack trace in case of Nix expression

     

       232
       232
       +
             evaluation errors.

     

       199
       233
        
            </para>

     

       200
       234
        
           </listitem>

     

       201
       235
        
          </varlistentry>

     
···

       214
       248
        
        <refsection>

     

       215
       249
        
         <title>Examples</title>

     

       216
       250
        
         <para>

     

       217
       217
       -
          A typical NixOS installation is done by creating and mounting a file system on <filename>/mnt</filename>, generating a NixOS configuration in <filename>/mnt/etc/nixos/configuration.nix</filename>, and running <command>nixos-install</command>. For instance, if we want to install NixOS on an <literal>ext4</literal> file system created in <filename>/dev/sda1</filename>:

     

       251
       251
       +
          A typical NixOS installation is done by creating and mounting a file system

     

       252
       252
       +
          on <filename>/mnt</filename>, generating a NixOS configuration in

     

       253
       253
       +
          <filename>/mnt/etc/nixos/configuration.nix</filename>, and running

     

       254
       254
       +
          <command>nixos-install</command>. For instance, if we want to install NixOS

     

       255
       255
       +
          on an <literal>ext4</literal> file system created in

     

       256
       256
       +
          <filename>/dev/sda1</filename>:

     

       218
       257
        
       <screen>

     

       219
       258
        
       <prompt>$ </prompt>mkfs.ext4 /dev/sda1

     

       220
       259
        
       <prompt>$ </prompt>mount /dev/sda1 /mnt

+17 -10

nixos/doc/manual/man-nixos-option.xml

···

       13
       13
        
        </refnamediv>

     

       14
       14
        
        <refsynopsisdiv>

     

       15
       15
        
         <cmdsynopsis>

     

       16
       16
       -
          <command>nixos-option</command> 

     

       16
       16
       +
          <command>nixos-option</command>

     

       17
       17
        
          <arg>

     

       18
       18
        
           <option>-I</option> <replaceable>path</replaceable>

     

       19
       19
        
          </arg>

     

       20
       20
       -
           

     

       20
       20
       +
       

     

       21
       21
        
          <arg>

     

       22
       22
        
           <option>--verbose</option>

     

       23
       23
        
          </arg>

     

       24
       24
       -
           

     

       24
       24
       +
       

     

       25
       25
        
          <arg>

     

       26
       26
        
           <option>--xml</option>

     

       27
       27
        
          </arg>

     

       28
       28
       -
           

     

       28
       28
       +
       

     

       29
       29
        
          <arg choice="plain">

     

       30
       30
        
           <replaceable>option.name</replaceable>

     

       31
       31
        
          </arg>

     
···

       34
       34
        
        <refsection>

     

       35
       35
        
         <title>Description</title>

     

       36
       36
        
         <para>

     

       37
       37
       -
          This command evaluates the configuration specified in <filename>/etc/nixos/configuration.nix</filename> and returns the properties of the option name given as argument.

     

       37
       37
       +
          This command evaluates the configuration specified in

     

       38
       38
       +
          <filename>/etc/nixos/configuration.nix</filename> and returns the properties

     

       39
       39
       +
          of the option name given as argument.

     

       38
       40
        
         </para>

     

       39
       41
        
         <para>

     

       40
       40
       -
          When the option name is not an option, the command prints the list of attributes contained in the attribute set.

     

       42
       42
       +
          When the option name is not an option, the command prints the list of

     

       43
       43
       +
          attributes contained in the attribute set.

     

       41
       44
        
         </para>

     

       42
       45
        
        </refsection>

     

       43
       46
        
        <refsection>

     
···

       52
       55
        
           </term>

     

       53
       56
        
           <listitem>

     

       54
       57
        
            <para>

     

       55
       55
       -
             This option is passed to the underlying <command>nix-instantiate</command> invocation.

     

       58
       58
       +
             This option is passed to the underlying

     

       59
       59
       +
             <command>nix-instantiate</command> invocation.

     

       56
       60
        
            </para>

     

       57
       61
        
           </listitem>

     

       58
       62
        
          </varlistentry>

     
···

       62
       66
        
           </term>

     

       63
       67
        
           <listitem>

     

       64
       68
        
            <para>

     

       65
       65
       -
             This option enables verbose mode, which currently is just the Bash <command>set</command> <option>-x</option> debug mode.

     

       69
       69
       +
             This option enables verbose mode, which currently is just the Bash

     

       70
       70
       +
             <command>set</command> <option>-x</option> debug mode.

     

       66
       71
        
            </para>

     

       67
       72
        
           </listitem>

     

       68
       73
        
          </varlistentry>

     
···

       87
       92
        
           </term>

     

       88
       93
        
           <listitem>

     

       89
       94
        
            <para>

     

       90
       90
       -
             Path to the main NixOS configuration module. Defaults to <filename>/etc/nixos/configuration.nix</filename>.

     

       95
       95
       +
             Path to the main NixOS configuration module. Defaults to

     

       96
       96
       +
             <filename>/etc/nixos/configuration.nix</filename>.

     

       91
       97
        
            </para>

     

       92
       98
        
           </listitem>

     

       93
       99
        
          </varlistentry>

     
···

       124
       130
        
        <refsection>

     

       125
       131
        
         <title>Bugs</title>

     

       126
       132
        
         <para>

     

       127
       127
       -
          The author listed in the following section is wrong. If there is any other bug, please report to Nicolas Pierron.

     

       133
       133
       +
          The author listed in the following section is wrong. If there is any other

     

       134
       134
       +
          bug, please report to Nicolas Pierron.

     

       128
       135
        
         </para>

     

       129
       136
        
        </refsection>

     

       130
       137
        
       </refentry>

+219 -90

nixos/doc/manual/man-nixos-rebuild.xml

···

       7
       7
        
         <refmiscinfo class="source">NixOS</refmiscinfo>

     

       8
       8
        
       <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->

     

       9
       9
        
        </refmeta>

     

       10
       10
       +
       

     

       10
       11
        
        <refnamediv>

     

       11
       12
        
         <refname><command>nixos-rebuild</command>

     

       12
       13
        
         </refname><refpurpose>reconfigure a NixOS machine</refpurpose>

     

       13
       14
        
        </refnamediv>

     

       15
       15
       +
       

     

       14
       16
        
        <refsynopsisdiv>

     

       15
       17
        
         <cmdsynopsis>

     

       16
       16
       -
          <command>nixos-rebuild</command><group choice='req'> 

     

       18
       18
       +
          <command>nixos-rebuild</command><group choice='req'>

     

       17
       19
        
          <arg choice='plain'>

     

       18
       20
        
           <option>switch</option>

     

       19
       21
        
          </arg>

     

       20
       20
       -
           

     

       22
       22
       +
       

     

       21
       23
        
          <arg choice='plain'>

     

       22
       24
        
           <option>boot</option>

     

       23
       25
        
          </arg>

     

       24
       24
       -
           

     

       26
       26
       +
       

     

       25
       27
        
          <arg choice='plain'>

     

       26
       28
        
           <option>test</option>

     

       27
       29
        
          </arg>

     

       28
       28
       -
           

     

       30
       30
       +
       

     

       29
       31
        
          <arg choice='plain'>

     

       30
       32
        
           <option>build</option>

     

       31
       33
        
          </arg>

     

       32
       32
       -
           

     

       34
       34
       +
       

     

       33
       35
        
          <arg choice='plain'>

     

       34
       36
        
           <option>dry-build</option>

     

       35
       37
        
          </arg>

     

       36
       36
       -
           

     

       38
       38
       +
       

     

       37
       39
        
          <arg choice='plain'>

     

       38
       40
        
           <option>dry-activate</option>

     

       39
       41
        
          </arg>

     

       40
       40
       -
           

     

       42
       42
       +
       

     

       41
       43
        
          <arg choice='plain'>

     

       42
       44
        
           <option>edit</option>

     

       43
       45
        
          </arg>

     

       44
       44
       -
           

     

       46
       46
       +
       

     

       45
       47
        
          <arg choice='plain'>

     

       46
       48
        
           <option>build-vm</option>

     

       47
       49
        
          </arg>

     

       48
       48
       -
           

     

       50
       50
       +
       

     

       49
       51
        
          <arg choice='plain'>

     

       50
       52
        
           <option>build-vm-with-bootloader</option>

     

       51
       53
        
          </arg>

     
···

       54
       56
        
          <arg>

     

       55
       57
        
           <option>--upgrade</option>

     

       56
       58
        
          </arg>

     

       57
       57
       -
           

     

       59
       59
       +
       

     

       58
       60
        
          <arg>

     

       59
       61
        
           <option>--install-bootloader</option>

     

       60
       62
        
          </arg>

     

       61
       61
       -
           

     

       63
       63
       +
       

     

       62
       64
        
          <arg>

     

       63
       65
        
           <option>--no-build-nix</option>

     

       64
       66
        
          </arg>

     

       65
       65
       -
           

     

       67
       67
       +
       

     

       66
       68
        
          <arg>

     

       67
       69
        
           <option>--fast</option>

     

       68
       70
        
          </arg>

     

       69
       69
       -
           

     

       71
       71
       +
       

     

       70
       72
        
          <arg>

     

       71
       73
        
           <option>--rollback</option>

     

       72
       74
        
          </arg>

     

       73
       73
       -
           

     

       75
       75
       +
       

     

       74
       76
        
          <arg>

     

       75
       77
        
           <option>--builders</option> <replaceable>builder-spec</replaceable>

     

       76
       78
        
          </arg>

     

       79
       79
       +
       

     

       77
       80
        
          <sbr />

     

       78
       81
        
          <arg>

     

       79
       79
       -
           <group choice='req'> 

     

       82
       82
       +
           <group choice='req'>

     

       80
       83
        
           <arg choice='plain'>

     

       81
       84
        
            <option>--profile-name</option>

     

       82
       85
        
           </arg>

     

       83
       83
       -
            

     

       86
       86
       +
       

     

       84
       87
        
           <arg choice='plain'>

     

       85
       88
        
            <option>-p</option>

     

       86
       89
        
           </arg>

     
···

       90
       93
        
          <arg>

     

       91
       94
        
           <option>--show-trace</option>

     

       92
       95
        
          </arg>

     

       93
       93
       -
           

     

       94
       96
        
          <arg>

     

       95
       95
       -
           <option>-I</option> <replaceable>path</replaceable>

     

       97
       97
       +
           <option>-I</option>

     

       98
       98
       +
           <replaceable>path</replaceable>

     

       96
       99
        
          </arg>

     

       97
       97
       -
           

     

       98
       100
        
          <arg>

     

       99
       99
       -
           <group choice='req'> 

     

       100
       100
       -
           <arg choice='plain'>

     

       101
       101
       -
            <option>--verbose</option>

     

       102
       102
       -
           </arg>

     

       103
       103
       -
            

     

       104
       104
       -
           <arg choice='plain'>

     

       105
       105
       -
            <option>-v</option>

     

       106
       106
       -
           </arg>

     

       107
       107
       -
            </group>

     

       101
       101
       +
           <group choice='req'>

     

       102
       102
       +
            <arg choice='plain'><option>--verbose</option></arg>

     

       103
       103
       +
            <arg choice='plain'><option>-v</option></arg>

     

       104
       104
       +
           </group>

     

       108
       105
        
          </arg>

     

       109
       109
       -
           

     

       110
       106
        
          <arg>

     

       111
       111
       -
           <group choice='req'> 

     

       112
       112
       -
           <arg choice='plain'>

     

       113
       113
       -
            <option>--max-jobs</option>

     

       114
       114
       -
           </arg>

     

       115
       115
       -
            

     

       116
       116
       -
           <arg choice='plain'>

     

       117
       117
       -
            <option>-j</option>

     

       118
       118
       -
           </arg>

     

       119
       119
       -
            </group> <replaceable>number</replaceable>

     

       107
       107
       +
           <group choice='req'>

     

       108
       108
       +
            <arg choice='plain'><option>--max-jobs</option></arg>

     

       109
       109
       +
            <arg choice='plain'><option>-j</option></arg>

     

       110
       110
       +
           </group>

     

       111
       111
       +
           <replaceable>number</replaceable>

     

       120
       112
        
          </arg>

     

       121
       121
       -
           

     

       122
       113
        
          <arg>

     

       123
       123
       -
           <group choice='req'> 

     

       124
       124
       -
           <arg choice='plain'>

     

       125
       125
       -
            <option>--keep-failed</option>

     

       126
       126
       -
           </arg>

     

       127
       127
       -
            

     

       128
       128
       -
           <arg choice='plain'>

     

       129
       129
       -
            <option>-K</option>

     

       130
       130
       -
           </arg>

     

       131
       131
       -
            </group>

     

       114
       114
       +
           <group choice='req'>

     

       115
       115
       +
            <arg choice='plain'><option>--keep-failed</option></arg>

     

       116
       116
       +
            <arg choice='plain'><option>-K</option></arg>

     

       117
       117
       +
           </group>

     

       132
       118
        
          </arg>

     

       133
       133
       -
           

     

       134
       119
        
          <arg>

     

       135
       135
       -
           <group choice='req'> 

     

       136
       136
       -
           <arg choice='plain'>

     

       137
       137
       -
            <option>--keep-going</option>

     

       138
       138
       -
           </arg>

     

       139
       139
       -
            

     

       140
       140
       -
           <arg choice='plain'>

     

       141
       141
       -
            <option>-k</option>

     

       142
       142
       -
           </arg>

     

       143
       143
       -
            </group>

     

       120
       120
       +
           <group choice='req'>

     

       121
       121
       +
            <arg choice='plain'><option>--keep-going</option></arg>

     

       122
       122
       +
            <arg choice='plain'><option>-k</option></arg>

     

       123
       123
       +
           </group>

     

       144
       124
        
          </arg>

     

       145
       125
        
         </cmdsynopsis>

     

       146
       126
        
        </refsynopsisdiv>

     

       127
       127
       +
       

     

       147
       128
        
        <refsection>

     

       148
       129
        
         <title>Description</title>

     

       130
       130
       +
       

     

       149
       131
        
         <para>

     

       150
       150
       -
          This command updates the system so that it corresponds to the configuration specified in <filename>/etc/nixos/configuration.nix</filename>. Thus, every time you modify <filename>/etc/nixos/configuration.nix</filename> or any NixOS module, you must run <command>nixos-rebuild</command> to make the changes take effect. It builds the new system in <filename>/nix/store</filename>, runs its activation script, and stop and (re)starts any system services if needed. Please note that user services need to be started manually as they aren't detected by the activation script at the moment.

     

       132
       132
       +
          This command updates the system so that it corresponds to the configuration

     

       133
       133
       +
          specified in <filename>/etc/nixos/configuration.nix</filename>. Thus, every

     

       134
       134
       +
          time you modify <filename>/etc/nixos/configuration.nix</filename> or any

     

       135
       135
       +
          NixOS module, you must run <command>nixos-rebuild</command> to make the

     

       136
       136
       +
          changes take effect. It builds the new system in

     

       137
       137
       +
          <filename>/nix/store</filename>, runs its activation script, and stop and

     

       138
       138
       +
          (re)starts any system services if needed. Please note that user services need

     

       139
       139
       +
          to be started manually as they aren't detected by the activation script at the moment.

     

       151
       140
        
         </para>

     

       141
       141
       +
       

     

       152
       142
        
         <para>

     

       153
       153
       -
          This command has one required argument, which specifies the desired operation. It must be one of the following:

     

       143
       143
       +
          This command has one required argument, which specifies the desired

     

       144
       144
       +
          operation. It must be one of the following:

     

       145
       145
       +
       

     

       154
       146
        
          <variablelist>

     

       155
       147
        
           <varlistentry>

     

       156
       148
        
            <term>

     
···

       158
       150
        
            </term>

     

       159
       151
        
            <listitem>

     

       160
       152
        
             <para>

     

       161
       161
       -
              Build and activate the new configuration, and make it the boot default. That is, the configuration is added to the GRUB boot menu as the default menu entry, so that subsequent reboots will boot the system into the new configuration. Previous configurations activated with <command>nixos-rebuild switch</command> or <command>nixos-rebuild boot</command> remain available in the GRUB menu.

     

       153
       153
       +
              Build and activate the new configuration, and make it the boot default.

     

       154
       154
       +
              That is, the configuration is added to the GRUB boot menu as the default

     

       155
       155
       +
              menu entry, so that subsequent reboots will boot the system into the new

     

       156
       156
       +
              configuration. Previous configurations activated with

     

       157
       157
       +
              <command>nixos-rebuild switch</command> or <command>nixos-rebuild

     

       158
       158
       +
              boot</command> remain available in the GRUB menu.

     

       162
       159
        
             </para>

     

       163
       160
        
            </listitem>

     

       164
       161
        
           </varlistentry>

     

       162
       162
       +
       

     

       165
       163
        
           <varlistentry>

     

       166
       164
        
            <term>

     

       167
       165
        
             <option>boot</option>

     

       168
       166
        
            </term>

     

       169
       167
        
            <listitem>

     

       170
       168
        
             <para>

     

       171
       171
       -
              Build the new configuration and make it the boot default (as with <command>nixos-rebuild switch</command>), but do not activate it. That is, the system continues to run the previous configuration until the next reboot.

     

       169
       169
       +
              Build the new configuration and make it the boot default (as with

     

       170
       170
       +
              <command>nixos-rebuild switch</command>), but do not activate it. That

     

       171
       171
       +
              is, the system continues to run the previous configuration until the

     

       172
       172
       +
              next reboot.

     

       172
       173
        
             </para>

     

       173
       174
        
            </listitem>

     

       174
       175
        
           </varlistentry>

     

       176
       176
       +
       

     

       175
       177
        
           <varlistentry>

     

       176
       178
        
            <term>

     

       177
       179
        
             <option>test</option>

     

       178
       180
        
            </term>

     

       179
       181
        
            <listitem>

     

       180
       182
        
             <para>

     

       181
       181
       -
              Build and activate the new configuration, but do not add it to the GRUB boot menu. Thus, if you reboot the system (or if it crashes), you will automatically revert to the default configuration (i.e. the configuration resulting from the last call to <command>nixos-rebuild switch</command> or <command>nixos-rebuild boot</command>).

     

       183
       183
       +
              Build and activate the new configuration, but do not add it to the GRUB

     

       184
       184
       +
              boot menu. Thus, if you reboot the system (or if it crashes), you will

     

       185
       185
       +
              automatically revert to the default configuration (i.e. the

     

       186
       186
       +
              configuration resulting from the last call to <command>nixos-rebuild

     

       187
       187
       +
              switch</command> or <command>nixos-rebuild boot</command>).

     

       182
       188
        
             </para>

     

       183
       189
        
            </listitem>

     

       184
       190
        
           </varlistentry>

     

       191
       191
       +
       

     

       185
       192
        
           <varlistentry>

     

       186
       193
        
            <term>

     

       187
       194
        
             <option>build</option>

     

       188
       195
        
            </term>

     

       189
       196
        
            <listitem>

     

       190
       197
        
             <para>

     

       191
       191
       -
              Build the new configuration, but neither activate it nor add it to the GRUB boot menu. It leaves a symlink named <filename>result</filename> in the current directory, which points to the output of the top-level “system” derivation. This is essentially the same as doing

     

       198
       198
       +
              Build the new configuration, but neither activate it nor add it to the

     

       199
       199
       +
              GRUB boot menu. It leaves a symlink named <filename>result</filename> in

     

       200
       200
       +
              the current directory, which points to the output of the top-level

     

       201
       201
       +
              “system” derivation. This is essentially the same as doing

     

       192
       202
        
       <screen>

     

       193
       203
        
       <prompt>$ </prompt>nix-build /path/to/nixpkgs/nixos -A system

     

       194
       204
        
       </screen>

     

       195
       195
       -
              Note that you do not need to be <literal>root</literal> to run <command>nixos-rebuild build</command>.

     

       205
       205
       +
              Note that you do not need to be <literal>root</literal> to run

     

       206
       206
       +
              <command>nixos-rebuild build</command>.

     

       196
       207
        
             </para>

     

       197
       208
        
            </listitem>

     

       198
       209
        
           </varlistentry>

     

       210
       210
       +
       

     

       199
       211
        
           <varlistentry>

     

       200
       212
        
            <term>

     

       201
       213
        
             <option>dry-build</option>

     

       202
       214
        
            </term>

     

       203
       215
        
            <listitem>

     

       204
       216
        
             <para>

     

       205
       205
       -
              Show what store paths would be built or downloaded by any of the operations above, but otherwise do nothing.

     

       217
       217
       +
              Show what store paths would be built or downloaded by any of the

     

       218
       218
       +
              operations above, but otherwise do nothing.

     

       206
       219
        
             </para>

     

       207
       220
        
            </listitem>

     

       208
       221
        
           </varlistentry>

     

       222
       222
       +
       

     

       209
       223
        
           <varlistentry>

     

       210
       224
        
            <term>

     

       211
       225
        
             <option>dry-activate</option>

     

       212
       226
        
            </term>

     

       213
       227
        
            <listitem>

     

       214
       228
        
             <para>

     

       215
       215
       -
              Build the new configuration, but instead of activating it, show what changes would be performed by the activation (i.e. by <command>nixos-rebuild test</command>). For instance, this command will print which systemd units would be restarted. The list of changes is not guaranteed to be complete.

     

       229
       229
       +
              Build the new configuration, but instead of activating it, show what

     

       230
       230
       +
              changes would be performed by the activation (i.e. by

     

       231
       231
       +
              <command>nixos-rebuild test</command>). For instance, this command will

     

       232
       232
       +
              print which systemd units would be restarted. The list of changes is not

     

       233
       233
       +
              guaranteed to be complete.

     

       216
       234
        
             </para>

     

       217
       235
        
            </listitem>

     

       218
       236
        
           </varlistentry>

     

       237
       237
       +
       

     

       219
       238
        
           <varlistentry>

     

       220
       239
        
            <term>

     

       221
       240
        
             <option>edit</option>

     
···

       226
       245
        
             </para>

     

       227
       246
        
            </listitem>

     

       228
       247
        
           </varlistentry>

     

       248
       248
       +
       

     

       229
       249
        
           <varlistentry>

     

       230
       250
        
            <term>

     

       231
       251
        
             <option>build-vm</option>

     

       232
       252
        
            </term>

     

       233
       253
        
            <listitem>

     

       234
       254
        
             <para>

     

       235
       235
       -
              Build a script that starts a NixOS virtual machine with the desired configuration. It leaves a symlink <filename>result</filename> in the current directory that points (under <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>) at the script that starts the VM. Thus, to test a NixOS configuration in a virtual machine, you should do the following:

     

       255
       255
       +
              Build a script that starts a NixOS virtual machine with the desired

     

       256
       256
       +
              configuration. It leaves a symlink <filename>result</filename> in the

     

       257
       257
       +
              current directory that points (under

     

       258
       258
       +
              <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>)

     

       259
       259
       +
              at the script that starts the VM. Thus, to test a NixOS configuration in

     

       260
       260
       +
              a virtual machine, you should do the following:

     

       236
       261
        
       <screen>

     

       237
       262
        
       <prompt>$ </prompt>nixos-rebuild build-vm

     

       238
       263
        
       <prompt>$ </prompt>./result/bin/run-*-vm

     

       239
       264
        
       </screen>

     

       240
       265
        
             </para>

     

       266
       266
       +
       

     

       241
       267
        
             <para>

     

       242
       242
       -
              The VM is implemented using the <literal>qemu</literal> package. For best performance, you should load the <literal>kvm-intel</literal> or <literal>kvm-amd</literal> kernel modules to get hardware virtualisation.

     

       268
       268
       +
              The VM is implemented using the <literal>qemu</literal> package. For

     

       269
       269
       +
              best performance, you should load the <literal>kvm-intel</literal> or

     

       270
       270
       +
              <literal>kvm-amd</literal> kernel modules to get hardware

     

       271
       271
       +
              virtualisation.

     

       243
       272
        
             </para>

     

       273
       273
       +
       

     

       244
       274
        
             <para>

     

       245
       245
       -
              The VM mounts the Nix store of the host through the 9P file system. The host Nix store is read-only, so Nix commands that modify the Nix store will not work in the VM. This includes commands such as <command>nixos-rebuild</command>; to change the VM’s configuration, you must halt the VM and re-run the commands above.

     

       275
       275
       +
              The VM mounts the Nix store of the host through the 9P file system. The

     

       276
       276
       +
              host Nix store is read-only, so Nix commands that modify the Nix store

     

       277
       277
       +
              will not work in the VM. This includes commands such as

     

       278
       278
       +
              <command>nixos-rebuild</command>; to change the VM’s configuration,

     

       279
       279
       +
              you must halt the VM and re-run the commands above.

     

       246
       280
        
             </para>

     

       281
       281
       +
       

     

       247
       282
        
             <para>

     

       248
       248
       -
              The VM has its own <literal>ext3</literal> root file system, which is automatically created when the VM is first started, and is persistent across reboots of the VM. It is stored in <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.

     

       283
       283
       +
              The VM has its own <literal>ext3</literal> root file system, which is

     

       284
       284
       +
              automatically created when the VM is first started, and is persistent

     

       285
       285
       +
              across reboots of the VM. It is stored in

     

       286
       286
       +
              <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.

     

       249
       287
        
       <!-- The entire file system hierarchy of the host is available in

     

       250
       288
        
             the VM under <filename>/hostfs</filename>.-->

     

       251
       289
        
             </para>

     

       252
       290
        
            </listitem>

     

       253
       291
        
           </varlistentry>

     

       292
       292
       +
       

     

       254
       293
        
           <varlistentry>

     

       255
       294
        
            <term>

     

       256
       295
        
             <option>build-vm-with-bootloader</option>

     

       257
       296
        
            </term>

     

       258
       297
        
            <listitem>

     

       259
       298
        
             <para>

     

       260
       260
       -
              Like <option>build-vm</option>, but boots using the regular boot loader of your configuration (e.g., GRUB 1 or 2), rather than booting directly into the kernel and initial ramdisk of the system. This allows you to test whether the boot loader works correctly. However, it does not guarantee that your NixOS configuration will boot successfully on the host hardware (i.e., after running <command>nixos-rebuild switch</command>), because the hardware and boot loader configuration in the VM are different. The boot loader is installed on an automatically generated virtual disk containing a <filename>/boot</filename> partition, which is mounted read-only in the VM.

     

       299
       299
       +
              Like <option>build-vm</option>, but boots using the regular boot loader

     

       300
       300
       +
              of your configuration (e.g., GRUB 1 or 2), rather than booting directly

     

       301
       301
       +
              into the kernel and initial ramdisk of the system. This allows you to

     

       302
       302
       +
              test whether the boot loader works correctly. However, it does not

     

       303
       303
       +
              guarantee that your NixOS configuration will boot successfully on the

     

       304
       304
       +
              host hardware (i.e., after running <command>nixos-rebuild

     

       305
       305
       +
              switch</command>), because the hardware and boot loader configuration in

     

       306
       306
       +
              the VM are different. The boot loader is installed on an automatically

     

       307
       307
       +
              generated virtual disk containing a <filename>/boot</filename>

     

       308
       308
       +
              partition, which is mounted read-only in the VM.

     

       261
       309
        
             </para>

     

       262
       310
        
            </listitem>

     

       263
       311
        
           </varlistentry>

     

       264
       312
        
          </variablelist>

     

       265
       313
        
         </para>

     

       266
       314
        
        </refsection>

     

       315
       315
       +
       

     

       267
       316
        
        <refsection>

     

       268
       317
        
         <title>Options</title>

     

       269
       318
        
         <para>

     

       270
       319
        
          This command accepts the following options:

     

       271
       320
        
         </para>

     

       321
       321
       +
       

     

       272
       322
        
         <variablelist>

     

       273
       323
        
          <varlistentry>

     

       274
       324
        
           <term>

     
···

       280
       330
        
            </para>

     

       281
       331
        
           </listitem>

     

       282
       332
        
          </varlistentry>

     

       333
       333
       +
       

     

       283
       334
        
          <varlistentry>

     

       284
       335
        
           <term>

     

       285
       336
        
            <option>--install-bootloader</option>

     

       286
       337
        
           </term>

     

       287
       338
        
           <listitem>

     

       288
       339
        
            <para>

     

       289
       289
       -
             Causes the boot loader to be (re)installed on the device specified by the relevant configuration options.

     

       340
       340
       +
             Causes the boot loader to be (re)installed on the device specified by the

     

       341
       341
       +
             relevant configuration options.

     

       290
       342
        
            </para>

     

       291
       343
        
           </listitem>

     

       292
       344
        
          </varlistentry>

     

       345
       345
       +
       

     

       293
       346
        
          <varlistentry>

     

       294
       347
        
           <term>

     

       295
       348
        
            <option>--no-build-nix</option>

     

       296
       349
        
           </term>

     

       297
       350
        
           <listitem>

     

       298
       351
        
            <para>

     

       299
       299
       -
             Normally, <command>nixos-rebuild</command> first builds the <varname>nixUnstable</varname> attribute in Nixpkgs, and uses the resulting instance of the Nix package manager to build the new system configuration. This is necessary if the NixOS modules use features not provided by the currently installed version of Nix. This option disables building a new Nix.

     

       352
       352
       +
             Normally, <command>nixos-rebuild</command> first builds the

     

       353
       353
       +
             <varname>nixUnstable</varname> attribute in Nixpkgs, and uses the

     

       354
       354
       +
             resulting instance of the Nix package manager to build the new system

     

       355
       355
       +
             configuration. This is necessary if the NixOS modules use features not

     

       356
       356
       +
             provided by the currently installed version of Nix. This option disables

     

       357
       357
       +
             building a new Nix.

     

       300
       358
        
            </para>

     

       301
       359
        
           </listitem>

     

       302
       360
        
          </varlistentry>

     

       361
       361
       +
       

     

       303
       362
        
          <varlistentry>

     

       304
       363
        
           <term>

     

       305
       364
        
            <option>--fast</option>

     

       306
       365
        
           </term>

     

       307
       366
        
           <listitem>

     

       308
       367
        
            <para>

     

       309
       309
       -
             Equivalent to <option>--no-build-nix</option> <option>--show-trace</option>. This option is useful if you call <command>nixos-rebuild</command> frequently (e.g. if you’re hacking on a NixOS module).

     

       368
       368
       +
             Equivalent to <option>--no-build-nix</option>

     

       369
       369
       +
             <option>--show-trace</option>. This option is useful if you call

     

       370
       370
       +
             <command>nixos-rebuild</command> frequently (e.g. if you’re hacking on

     

       371
       371
       +
             a NixOS module).

     

       310
       372
        
            </para>

     

       311
       373
        
           </listitem>

     

       312
       374
        
          </varlistentry>

     

       375
       375
       +
       

     

       313
       376
        
          <varlistentry>

     

       314
       377
        
           <term>

     

       315
       378
        
            <option>--rollback</option>

     

       316
       379
        
           </term>

     

       317
       380
        
           <listitem>

     

       318
       381
        
            <para>

     

       319
       319
       -
             Instead of building a new configuration as specified by <filename>/etc/nixos/configuration.nix</filename>, roll back to the previous configuration. (The previous configuration is defined as the one before the “current” generation of the Nix profile <filename>/nix/var/nix/profiles/system</filename>.)

     

       382
       382
       +
             Instead of building a new configuration as specified by

     

       383
       383
       +
             <filename>/etc/nixos/configuration.nix</filename>, roll back to the

     

       384
       384
       +
             previous configuration. (The previous configuration is defined as the one

     

       385
       385
       +
             before the “current” generation of the Nix profile

     

       386
       386
       +
             <filename>/nix/var/nix/profiles/system</filename>.)

     

       320
       387
        
            </para>

     

       321
       388
        
           </listitem>

     

       322
       389
        
          </varlistentry>

     

       390
       390
       +
       

     

       323
       391
        
          <varlistentry>

     

       324
       392
        
           <term>

     

       325
       393
        
            <option>--builders</option> <replaceable>builder-spec</replaceable>

     

       326
       394
        
           </term>

     

       327
       395
        
           <listitem>

     

       328
       396
        
            <para>

     

       329
       329
       -
             Allow ad-hoc remote builders for building the new system. This requires the user executing <command>nixos-rebuild</command> (usually root) to be configured as a trusted user in the Nix daemon. This can be achieved by using the <literal>nix.trustedUsers</literal> NixOS option. Examples values for that option are described in the <literal>Remote builds chapter</literal> in the Nix manual, (i.e. <command>--builders "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string existing builders specified in <filename>/etc/nix/machines</filename> can be ignored: <command>--builders ""</command> for example when they are not reachable due to network connectivity.

     

       397
       397
       +
             Allow ad-hoc remote builders for building the new system. This requires

     

       398
       398
       +
             the user executing <command>nixos-rebuild</command> (usually root) to be

     

       399
       399
       +
             configured as a trusted user in the Nix daemon. This can be achieved by

     

       400
       400
       +
             using the <literal>nix.trustedUsers</literal> NixOS option. Examples

     

       401
       401
       +
             values for that option are described in the <literal>Remote builds

     

       402
       402
       +
             chapter</literal> in the Nix manual, (i.e. <command>--builders

     

       403
       403
       +
             "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string

     

       404
       404
       +
             existing builders specified in <filename>/etc/nix/machines</filename> can

     

       405
       405
       +
             be ignored: <command>--builders ""</command> for example when they are

     

       406
       406
       +
             not reachable due to network connectivity.

     

       330
       407
        
            </para>

     

       331
       408
        
           </listitem>

     

       332
       409
        
          </varlistentry>

     

       410
       410
       +
       

     

       333
       411
        
          <varlistentry>

     

       334
       412
        
           <term>

     

       335
       413
        
            <option>--profile-name</option>

     
···

       339
       417
        
           </term>

     

       340
       418
        
           <listitem>

     

       341
       419
        
            <para>

     

       342
       342
       -
             Instead of using the Nix profile <filename>/nix/var/nix/profiles/system</filename> to keep track of the current and previous system configurations, use <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>. When you use GRUB 2, for every system profile created with this flag, NixOS will create a submenu named “NixOS - Profile '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing the current and previous configurations of this profile.

     

       420
       420
       +
             Instead of using the Nix profile

     

       421
       421
       +
             <filename>/nix/var/nix/profiles/system</filename> to keep track of the

     

       422
       422
       +
             current and previous system configurations, use

     

       423
       423
       +
             <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>.

     

       424
       424
       +
             When you use GRUB 2, for every system profile created with this flag,

     

       425
       425
       +
             NixOS will create a submenu named “NixOS - Profile

     

       426
       426
       +
             '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing

     

       427
       427
       +
             the current and previous configurations of this profile.

     

       343
       428
        
            </para>

     

       344
       429
        
            <para>

     

       345
       345
       -
             For instance, if you want to test a configuration file named <filename>test.nix</filename> without affecting the default system profile, you would do:

     

       430
       430
       +
             For instance, if you want to test a configuration file named

     

       431
       431
       +
             <filename>test.nix</filename> without affecting the default system

     

       432
       432
       +
             profile, you would do:

     

       346
       433
        
       <screen>

     

       347
       434
        
       <prompt>$ </prompt>nixos-rebuild switch -p test -I nixos-config=./test.nix

     

       348
       435
        
       </screen>

     

       349
       349
       -
             The new configuration will appear in the GRUB 2 submenu “NixOS - Profile 'test'”.

     

       436
       436
       +
             The new configuration will appear in the GRUB 2 submenu “NixOS -

     

       437
       437
       +
             Profile 'test'”.

     

       350
       438
        
            </para>

     

       351
       439
        
           </listitem>

     

       352
       440
        
          </varlistentry>

     

       441
       441
       +
       

     

       353
       442
        
          <varlistentry>

     

       354
       443
        
           <term>

     

       355
       444
        
            <option>--build-host</option>

     

       356
       445
        
           </term>

     

       357
       446
        
           <listitem>

     

       358
       447
        
            <para>

     

       359
       359
       -
             Instead of building the new configuration locally, use the specified host to perform the build. The host needs to be accessible with ssh, and must be able to perform Nix builds. If the option <option>--target-host</option> is not set, the build will be copied back to the local machine when done.

     

       448
       448
       +
             Instead of building the new configuration locally, use the specified host

     

       449
       449
       +
             to perform the build. The host needs to be accessible with ssh, and must

     

       450
       450
       +
             be able to perform Nix builds. If the option

     

       451
       451
       +
             <option>--target-host</option> is not set, the build will be copied back

     

       452
       452
       +
             to the local machine when done.

     

       360
       453
        
            </para>

     

       361
       454
        
            <para>

     

       362
       362
       -
             Note that, if <option>--no-build-nix</option> is not specified, Nix will be built both locally and remotely. This is because the configuration will always be evaluated locally even though the building might be performed remotely.

     

       455
       455
       +
             Note that, if <option>--no-build-nix</option> is not specified, Nix will

     

       456
       456
       +
             be built both locally and remotely. This is because the configuration

     

       457
       457
       +
             will always be evaluated locally even though the building might be

     

       458
       458
       +
             performed remotely.

     

       363
       459
        
            </para>

     

       364
       460
        
            <para>

     

       365
       365
       -
             You can include a remote user name in the host name (<replaceable>user@host</replaceable>). You can also set ssh options by defining the <envar>NIX_SSHOPTS</envar> environment variable.

     

       461
       461
       +
             You can include a remote user name in the host name

     

       462
       462
       +
             (<replaceable>user@host</replaceable>). You can also set ssh options by

     

       463
       463
       +
             defining the <envar>NIX_SSHOPTS</envar> environment variable.

     

       366
       464
        
            </para>

     

       367
       465
        
           </listitem>

     

       368
       466
        
          </varlistentry>

     

       467
       467
       +
       

     

       369
       468
        
          <varlistentry>

     

       370
       469
        
           <term>

     

       371
       470
        
            <option>--target-host</option>

     

       372
       471
        
           </term>

     

       373
       472
        
           <listitem>

     

       374
       473
        
            <para>

     

       375
       375
       -
             Specifies the NixOS target host. By setting this to something other than <replaceable>localhost</replaceable>, the system activation will happen on the remote host instead of the local machine. The remote host needs to be accessible over ssh, and for the commands <option>switch</option>, <option>boot</option> and <option>test</option> you need root access.

     

       474
       474
       +
             Specifies the NixOS target host. By setting this to something other than

     

       475
       475
       +
             <replaceable>localhost</replaceable>, the system activation will happen

     

       476
       476
       +
             on the remote host instead of the local machine. The remote host needs to

     

       477
       477
       +
             be accessible over ssh, and for the commands <option>switch</option>,

     

       478
       478
       +
             <option>boot</option> and <option>test</option> you need root access.

     

       376
       479
        
            </para>

     

       480
       480
       +
       

     

       377
       481
        
            <para>

     

       378
       378
       -
             If <option>--build-host</option> is not explicitly specified, <option>--build-host</option> will implicitly be set to the same value as <option>--target-host</option>. So, if you only specify <option>--target-host</option> both building and activation will take place remotely (and no build artifacts will be copied to the local machine).

     

       482
       482
       +
             If <option>--build-host</option> is not explicitly specified,

     

       483
       483
       +
             <option>--build-host</option> will implicitly be set to the same value as

     

       484
       484
       +
             <option>--target-host</option>. So, if you only specify

     

       485
       485
       +
             <option>--target-host</option> both building and activation will take

     

       486
       486
       +
             place remotely (and no build artifacts will be copied to the local

     

       487
       487
       +
             machine).

     

       379
       488
        
            </para>

     

       489
       489
       +
       

     

       380
       490
        
            <para>

     

       381
       381
       -
             You can include a remote user name in the host name (<replaceable>user@host</replaceable>). You can also set ssh options by defining the <envar>NIX_SSHOPTS</envar> environment variable.

     

       491
       491
       +
             You can include a remote user name in the host name

     

       492
       492
       +
             (<replaceable>user@host</replaceable>). You can also set ssh options by

     

       493
       493
       +
             defining the <envar>NIX_SSHOPTS</envar> environment variable.

     

       382
       494
        
            </para>

     

       383
       495
        
           </listitem>

     

       384
       496
        
          </varlistentry>

     

       385
       497
        
         </variablelist>

     

       498
       498
       +
       

     

       386
       499
        
         <para>

     

       387
       387
       -
          In addition, <command>nixos-rebuild</command> accepts various Nix-related flags, including <option>--max-jobs</option> / <option>-j</option>, <option>--show-trace</option>, <option>--keep-failed</option>, <option>--keep-going</option> and <option>--verbose</option> / <option>-v</option>. See the Nix manual for details.

     

       500
       500
       +
          In addition, <command>nixos-rebuild</command> accepts various Nix-related

     

       501
       501
       +
          flags, including <option>--max-jobs</option> / <option>-j</option>,

     

       502
       502
       +
          <option>--show-trace</option>, <option>--keep-failed</option>,

     

       503
       503
       +
          <option>--keep-going</option> and <option>--verbose</option> /

     

       504
       504
       +
          <option>-v</option>. See the Nix manual for details.

     

       388
       505
        
         </para>

     

       389
       506
        
        </refsection>

     

       507
       507
       +
       

     

       390
       508
        
        <refsection>

     

       391
       509
        
         <title>Environment</title>

     

       510
       510
       +
       

     

       392
       511
        
         <variablelist>

     

       393
       512
        
          <varlistentry>

     

       394
       513
        
           <term>

     
···

       396
       515
        
           </term>

     

       397
       516
        
           <listitem>

     

       398
       517
        
            <para>

     

       399
       399
       -
             Path to the main NixOS configuration module. Defaults to <filename>/etc/nixos/configuration.nix</filename>.

     

       518
       518
       +
             Path to the main NixOS configuration module. Defaults to

     

       519
       519
       +
             <filename>/etc/nixos/configuration.nix</filename>.

     

       400
       520
        
            </para>

     

       401
       521
        
           </listitem>

     

       402
       522
        
          </varlistentry>

     

       523
       523
       +
       

     

       403
       524
        
          <varlistentry>

     

       404
       525
        
           <term>

     

       405
       526
        
            <envar>NIX_SSHOPTS</envar>

     

       406
       527
        
           </term>

     

       407
       528
        
           <listitem>

     

       408
       529
        
            <para>

     

       409
       409
       -
             Additional options to be passed to <command>ssh</command> on the command line.

     

       530
       530
       +
             Additional options to be passed to <command>ssh</command> on the command

     

       531
       531
       +
             line.

     

       410
       532
        
            </para>

     

       411
       533
        
           </listitem>

     

       412
       534
        
          </varlistentry>

     

       413
       535
        
         </variablelist>

     

       414
       536
        
        </refsection>

     

       537
       537
       +
       

     

       415
       538
        
        <refsection>

     

       416
       539
        
         <title>Files</title>

     

       540
       540
       +
       

     

       417
       541
        
         <variablelist>

     

       542
       542
       +
       

     

       418
       543
        
          <varlistentry>

     

       419
       544
        
           <term>

     

       420
       545
        
            <filename>/run/current-system</filename>

     
···

       425
       550
        
            </para>

     

       426
       551
        
           </listitem>

     

       427
       552
        
          </varlistentry>

     

       553
       553
       +
       

     

       428
       554
        
          <varlistentry>

     

       429
       555
        
           <term>

     

       430
       556
        
            <filename>/nix/var/nix/profiles/system</filename>

     

       431
       557
        
           </term>

     

       432
       558
        
           <listitem>

     

       433
       559
        
            <para>

     

       434
       434
       -
             The Nix profile that contains the current and previous system configurations. Used to generate the GRUB boot menu.

     

       560
       560
       +
             The Nix profile that contains the current and previous system

     

       561
       561
       +
             configurations. Used to generate the GRUB boot menu.

     

       435
       562
        
            </para>

     

       436
       563
        
           </listitem>

     

       437
       564
        
          </varlistentry>

     

       565
       565
       +
       

     

       438
       566
        
         </variablelist>

     

       439
       567
        
        </refsection>

     

       568
       568
       +
       

     

       440
       569
        
        <refsection>

     

       441
       570
        
         <title>Bugs</title>

     

       442
       571
        
         <para>

+17 -6

nixos/doc/manual/man-nixos-version.xml

···

       25
       25
        
        <refsection>

     

       26
       26
        
         <title>Description</title>

     

       27
       27
        
         <para>

     

       28
       28
       -
          This command shows the version of the currently active NixOS configuration. For example:

     

       28
       28
       +
          This command shows the version of the currently active NixOS configuration.

     

       29
       29
       +
          For example:

     

       29
       30
        
       <screen>$ nixos-version

     

       30
       31
        
       16.03.1011.6317da4 (Emu)

     

       31
       32
        
       </screen>

     
···

       37
       38
        
            </term>

     

       38
       39
        
            <listitem>

     

       39
       40
        
             <para>

     

       40
       40
       -
              The NixOS release, indicating the year and month in which it was released (e.g. March 2016).

     

       41
       41
       +
              The NixOS release, indicating the year and month in which it was

     

       42
       42
       +
              released (e.g. March 2016).

     

       41
       43
        
             </para>

     

       42
       44
        
            </listitem>

     

       43
       45
        
           </varlistentry>

     
···

       47
       49
        
            </term>

     

       48
       50
        
            <listitem>

     

       49
       51
        
             <para>

     

       50
       50
       -
              The number of commits in the Nixpkgs Git repository between the start of the release branch and the commit from which this version was built. This ensures that NixOS versions are monotonically increasing. It is <literal>git</literal> when the current NixOS configuration was built from a checkout of the Nixpkgs Git repository rather than from a NixOS channel.

     

       52
       52
       +
              The number of commits in the Nixpkgs Git repository between the start of

     

       53
       53
       +
              the release branch and the commit from which this version was built.

     

       54
       54
       +
              This ensures that NixOS versions are monotonically increasing. It is

     

       55
       55
       +
              <literal>git</literal> when the current NixOS configuration was built

     

       56
       56
       +
              from a checkout of the Nixpkgs Git repository rather than from a NixOS

     

       57
       57
       +
              channel.

     

       51
       58
        
             </para>

     

       52
       59
        
            </listitem>

     

       53
       60
        
           </varlistentry>

     
···

       57
       64
        
            </term>

     

       58
       65
        
            <listitem>

     

       59
       66
        
             <para>

     

       60
       60
       -
              The first 7 characters of the commit in the Nixpkgs Git repository from which this version was built.

     

       67
       67
       +
              The first 7 characters of the commit in the Nixpkgs Git repository from

     

       68
       68
       +
              which this version was built.

     

       61
       69
        
             </para>

     

       62
       70
        
            </listitem>

     

       63
       71
        
           </varlistentry>

     
···

       67
       75
        
            </term>

     

       68
       76
        
            <listitem>

     

       69
       77
        
             <para>

     

       70
       70
       -
              The code name of the NixOS release. The first letter of the code name indicates that this is the N'th stable NixOS release; for example, Emu is the fifth release.

     

       78
       78
       +
              The code name of the NixOS release. The first letter of the code name

     

       79
       79
       +
              indicates that this is the N'th stable NixOS release; for example, Emu

     

       80
       80
       +
              is the fifth release.

     

       71
       81
        
             </para>

     

       72
       82
        
            </listitem>

     

       73
       83
        
           </varlistentry>

     
···

       89
       99
        
           </term>

     

       90
       100
        
           <listitem>

     

       91
       101
        
            <para>

     

       92
       92
       -
             Show the full SHA1 hash of the Git commit from which this configuration was built, e.g.

     

       102
       102
       +
             Show the full SHA1 hash of the Git commit from which this configuration

     

       103
       103
       +
             was built, e.g.

     

       93
       104
        
       <screen>$ nixos-version --hash

     

       94
       105
        
       6317da40006f6bc2480c6781999c52d88dde2acf

     

       95
       106
        
       </screen>

+15 -6

nixos/doc/manual/manual.xml

···

       11
       11
        
        <preface xml:id="preface">

     

       12
       12
        
         <title>Preface</title>

     

       13
       13
        
         <para>

     

       14
       14
       -
          This manual describes how to install, use and extend NixOS, a Linux distribution based on the purely functional package management system Nix.

     

       14
       14
       +
          This manual describes how to install, use and extend NixOS, a Linux

     

       15
       15
       +
          distribution based on the purely functional package management system Nix.

     

       15
       16
        
         </para>

     

       16
       17
        
         <para>

     

       17
       17
       -
          If you encounter problems, please report them on the <literal

     

       18
       18
       -
           xlink:href="https://discourse.nixos.org">Discourse</literal> or on the <link

     

       19
       19
       -
           xlink:href="irc://irc.freenode.net/#nixos"> <literal>#nixos</literal> channel on Freenode</link>. Bugs should be reported in <link

     

       20
       20
       -
           xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’ GitHub issue tracker</link>.

     

       18
       18
       +
          If you encounter problems, please report them on the

     

       19
       19
       +
          <literal

     

       20
       20
       +
           xlink:href="https://discourse.nixos.org">Discourse</literal> or

     

       21
       21
       +
          on the <link

     

       22
       22
       +
           xlink:href="irc://irc.freenode.net/#nixos">

     

       23
       23
       +
          <literal>#nixos</literal> channel on Freenode</link>. Bugs should be

     

       24
       24
       +
          reported in

     

       25
       25
       +
          <link

     

       26
       26
       +
           xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’

     

       27
       27
       +
          GitHub issue tracker</link>.

     

       21
       28
        
         </para>

     

       22
       29
        
         <note>

     

       23
       30
        
          <para>

     

       24
       24
       -
           Commands prefixed with <literal>#</literal> have to be run as root, either requiring to login as root user or temporarily switching to it using <literal>sudo</literal> for example.

     

       31
       31
       +
           Commands prefixed with <literal>#</literal> have to be run as root, either

     

       32
       32
       +
           requiring to login as root user or temporarily switching to it using

     

       33
       33
       +
           <literal>sudo</literal> for example.

     

       25
       34
        
          </para>

     

       26
       35
        
         </note>

     

       27
       36
        
        </preface>

+2 -1

nixos/doc/manual/release-notes/release-notes.xml

···

       5
       5
        
                 xml:id="ch-release-notes">

     

       6
       6
        
        <title>Release Notes</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         This section lists the release notes for each stable version of NixOS and current unstable revision.

     

       8
       8
       +
         This section lists the release notes for each stable version of NixOS and

     

       9
       9
       +
         current unstable revision.

     

       9
       10
        
        </para>

     

       10
       11
        
        <xi:include href="rl-2003.xml" />

     

       11
       12
        
        <xi:include href="rl-1909.xml" />

+66 -17

nixos/doc/manual/release-notes/rl-1404.xml

···

       6
       6
        
        <title>Release 14.04 (“Baboon”, 2014/04/30)</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         This is the second stable release branch of NixOS. In addition to numerous new and upgraded packages and modules, this release has the following highlights:

     

       9
       9
       +
         This is the second stable release branch of NixOS. In addition to numerous

     

       10
       10
       +
         new and upgraded packages and modules, this release has the following

     

       11
       11
       +
         highlights:

     

       10
       12
        
         <itemizedlist>

     

       11
       13
        
          <listitem>

     

       12
       14
        
           <para>

     

       13
       13
       -
            Installation on UEFI systems is now supported. See <xref linkend="sec-installation"/> for details.

     

       15
       15
       +
            Installation on UEFI systems is now supported. See

     

       16
       16
       +
            <xref linkend="sec-installation"/> for details.

     

       14
       17
        
           </para>

     

       15
       18
        
          </listitem>

     

       16
       19
        
          <listitem>

     

       17
       20
        
           <para>

     

       18
       18
       -
            Systemd has been updated to version 212, which has <link xlink:href="http://cgit.freedesktop.org/systemd/systemd/plain/NEWS?id=v212">numerous improvements</link>. NixOS now automatically starts systemd user instances when you log in. You can define global user units through the <option>systemd.unit.*</option> options.

     

       21
       21
       +
            Systemd has been updated to version 212, which has

     

       22
       22
       +
            <link xlink:href="http://cgit.freedesktop.org/systemd/systemd/plain/NEWS?id=v212">numerous

     

       23
       23
       +
            improvements</link>. NixOS now automatically starts systemd user instances

     

       24
       24
       +
            when you log in. You can define global user units through the

     

       25
       25
       +
            <option>systemd.unit.*</option> options.

     

       19
       26
        
           </para>

     

       20
       27
        
          </listitem>

     

       21
       28
        
          <listitem>

     
···

       40
       47
        
          </listitem>

     

       41
       48
        
          <listitem>

     

       42
       49
        
           <para>

     

       43
       43
       -
            Nix has been updated to 1.7 (<link

     

       50
       50
       +
            Nix has been updated to 1.7

     

       51
       51
       +
            (<link

     

       44
       52
        
         xlink:href="http://nixos.org/nix/manual/#ssec-relnotes-1.7">details</link>).

     

       45
       53
        
           </para>

     

       46
       54
        
          </listitem>

     

       47
       55
        
          <listitem>

     

       48
       56
        
           <para>

     

       49
       49
       -
            NixOS now supports fully declarative management of users and groups. If you set <option>users.mutableUsers</option> to <literal>false</literal>, then the contents of <filename>/etc/passwd</filename> and <filename>/etc/group</filename> will be <link

     

       50
       50
       -
         xlink:href="https://www.usenix.org/legacy/event/lisa02/tech/full_papers/traugott/traugott_html/">congruent</link> to your NixOS configuration. For instance, if you remove a user from <option>users.extraUsers</option> and run <command>nixos-rebuild</command>, the user account will cease to exist. Also, imperative commands for managing users and groups, such as <command>useradd</command>, are no longer available. If <option>users.mutableUsers</option> is <literal>true</literal> (the default), then behaviour is unchanged from NixOS 13.10.

     

       57
       57
       +
            NixOS now supports fully declarative management of users and groups. If

     

       58
       58
       +
            you set <option>users.mutableUsers</option> to <literal>false</literal>,

     

       59
       59
       +
            then the contents of <filename>/etc/passwd</filename> and

     

       60
       60
       +
            <filename>/etc/group</filename> will be

     

       61
       61
       +
            <link

     

       62
       62
       +
         xlink:href="https://www.usenix.org/legacy/event/lisa02/tech/full_papers/traugott/traugott_html/">congruent</link>

     

       63
       63
       +
            to your NixOS configuration. For instance, if you remove a user from

     

       64
       64
       +
            <option>users.extraUsers</option> and run

     

       65
       65
       +
            <command>nixos-rebuild</command>, the user account will cease to exist.

     

       66
       66
       +
            Also, imperative commands for managing users and groups, such as

     

       67
       67
       +
            <command>useradd</command>, are no longer available. If

     

       68
       68
       +
            <option>users.mutableUsers</option> is <literal>true</literal> (the

     

       69
       69
       +
            default), then behaviour is unchanged from NixOS 13.10.

     

       51
       70
        
           </para>

     

       52
       71
        
          </listitem>

     

       53
       72
        
          <listitem>

     

       54
       73
        
           <para>

     

       55
       55
       -
            NixOS now has basic container support, meaning you can easily run a NixOS instance as a container in a NixOS host system. These containers are suitable for testing and experimentation but not production use, since they’re not fully isolated from the host. See <xref linkend="ch-containers"/> for details.

     

       74
       74
       +
            NixOS now has basic container support, meaning you can easily run a NixOS

     

       75
       75
       +
            instance as a container in a NixOS host system. These containers are

     

       76
       76
       +
            suitable for testing and experimentation but not production use, since

     

       77
       77
       +
            they’re not fully isolated from the host. See

     

       78
       78
       +
            <xref linkend="ch-containers"/> for details.

     

       56
       79
        
           </para>

     

       57
       80
        
          </listitem>

     

       58
       81
        
          <listitem>

     

       59
       82
        
           <para>

     

       60
       60
       -
            Systemd units provided by packages can now be overridden from the NixOS configuration. For instance, if a package <literal>foo</literal> provides systemd units, you can say:

     

       83
       83
       +
            Systemd units provided by packages can now be overridden from the NixOS

     

       84
       84
       +
            configuration. For instance, if a package <literal>foo</literal> provides

     

       85
       85
       +
            systemd units, you can say:

     

       61
       86
        
       <programlisting>

     

       62
       87
        
       systemd.packages = [ pkgs.foo ];

     

       63
       88
        
       </programlisting>

     

       64
       64
       -
            to enable those units. You can then set or override unit options in the usual way, e.g.

     

       89
       89
       +
            to enable those units. You can then set or override unit options in the

     

       90
       90
       +
            usual way, e.g.

     

       65
       91
        
       <programlisting>

     

       66
       92
        
       systemd.services.foo.wantedBy = [ "multi-user.target" ];

     

       67
       93
        
       systemd.services.foo.serviceConfig.MemoryLimit = "512M";

     
···

       72
       98
        
        </para>

     

       73
       99
        
       

     

       74
       100
        
        <para>

     

       75
       75
       -
         When upgrading from a previous release, please be aware of the following incompatible changes:

     

       101
       101
       +
         When upgrading from a previous release, please be aware of the following

     

       102
       102
       +
         incompatible changes:

     

       76
       103
        
         <itemizedlist>

     

       77
       104
        
          <listitem>

     

       78
       105
        
           <para>

     

       79
       79
       -
            Nixpkgs no longer exposes unfree packages by default. If your NixOS configuration requires unfree packages from Nixpkgs, you need to enable support for them explicitly by setting:

     

       106
       106
       +
            Nixpkgs no longer exposes unfree packages by default. If your NixOS

     

       107
       107
       +
            configuration requires unfree packages from Nixpkgs, you need to enable

     

       108
       108
       +
            support for them explicitly by setting:

     

       80
       109
        
       <programlisting>

     

       81
       110
        
       nixpkgs.config.allowUnfree = true;

     

       82
       111
        
       </programlisting>

     
···

       89
       118
        
          </listitem>

     

       90
       119
        
          <listitem>

     

       91
       120
        
           <para>

     

       92
       92
       -
            The Adobe Flash player is no longer enabled by default in the Firefox and Chromium wrappers. To enable it, you must set:

     

       121
       121
       +
            The Adobe Flash player is no longer enabled by default in the Firefox and

     

       122
       122
       +
            Chromium wrappers. To enable it, you must set:

     

       93
       123
        
       <programlisting>

     

       94
       124
        
       nixpkgs.config.allowUnfree = true;

     

       95
       125
        
       nixpkgs.config.firefox.enableAdobeFlash = true; # for Firefox

     
···

       99
       129
        
          </listitem>

     

       100
       130
        
          <listitem>

     

       101
       131
        
           <para>

     

       102
       102
       -
            The firewall is now enabled by default. If you don’t want this, you need to disable it explicitly:

     

       132
       132
       +
            The firewall is now enabled by default. If you don’t want this, you need

     

       133
       133
       +
            to disable it explicitly:

     

       103
       134
        
       <programlisting>

     

       104
       135
        
       networking.firewall.enable = false;

     

       105
       136
        
       </programlisting>

     
···

       107
       138
        
          </listitem>

     

       108
       139
        
          <listitem>

     

       109
       140
        
           <para>

     

       110
       110
       -
            The option <option>boot.loader.grub.memtest86</option> has been renamed to <option>boot.loader.grub.memtest86.enable</option>.

     

       141
       141
       +
            The option <option>boot.loader.grub.memtest86</option> has been renamed to

     

       142
       142
       +
            <option>boot.loader.grub.memtest86.enable</option>.

     

       111
       143
        
           </para>

     

       112
       144
        
          </listitem>

     

       113
       145
        
          <listitem>

     

       114
       146
        
           <para>

     

       115
       115
       -
            The <literal>mysql55</literal> service has been merged into the <literal>mysql</literal> service, which no longer sets a default for the option <option>services.mysql.package</option>.

     

       147
       147
       +
            The <literal>mysql55</literal> service has been merged into the

     

       148
       148
       +
            <literal>mysql</literal> service, which no longer sets a default for the

     

       149
       149
       +
            option <option>services.mysql.package</option>.

     

       116
       150
        
           </para>

     

       117
       151
        
          </listitem>

     

       118
       152
        
          <listitem>

     

       119
       153
        
           <para>

     

       120
       120
       -
            Package variants are now differentiated by suffixing the name, rather than the version. For instance, <filename>sqlite-3.8.4.3-interactive</filename> is now called <filename>sqlite-interactive-3.8.4.3</filename>. This ensures that <literal>nix-env -i sqlite</literal> is unambiguous, and that <literal>nix-env -u</literal> won’t “upgrade” <literal>sqlite</literal> to <literal>sqlite-interactive</literal> or vice versa. Notably, this change affects the Firefox wrapper (which provides plugins), as it is now called <literal>firefox-wrapper</literal>. So when using <command>nix-env</command>, you should do <literal>nix-env -e firefox; nix-env -i firefox-wrapper</literal> if you want to keep using the wrapper. This change does not affect declarative package management, since attribute names like <literal>pkgs.firefoxWrapper</literal> were already unambiguous.

     

       154
       154
       +
            Package variants are now differentiated by suffixing the name, rather than

     

       155
       155
       +
            the version. For instance, <filename>sqlite-3.8.4.3-interactive</filename>

     

       156
       156
       +
            is now called <filename>sqlite-interactive-3.8.4.3</filename>. This

     

       157
       157
       +
            ensures that <literal>nix-env -i sqlite</literal> is unambiguous, and that

     

       158
       158
       +
            <literal>nix-env -u</literal> won’t “upgrade”

     

       159
       159
       +
            <literal>sqlite</literal> to <literal>sqlite-interactive</literal> or vice

     

       160
       160
       +
            versa. Notably, this change affects the Firefox wrapper (which provides

     

       161
       161
       +
            plugins), as it is now called <literal>firefox-wrapper</literal>. So when

     

       162
       162
       +
            using <command>nix-env</command>, you should do <literal>nix-env -e

     

       163
       163
       +
            firefox; nix-env -i firefox-wrapper</literal> if you want to keep using

     

       164
       164
       +
            the wrapper. This change does not affect declarative package management,

     

       165
       165
       +
            since attribute names like <literal>pkgs.firefoxWrapper</literal> were

     

       166
       166
       +
            already unambiguous.

     

       121
       167
        
           </para>

     

       122
       168
        
          </listitem>

     

       123
       169
        
          <listitem>

     

       124
       170
        
           <para>

     

       125
       125
       -
            The symlink <filename>/etc/ca-bundle.crt</filename> is gone. Programs should instead use the environment variable <envar>OPENSSL_X509_CERT_FILE</envar> (which points to <filename>/etc/ssl/certs/ca-bundle.crt</filename>).

     

       171
       171
       +
            The symlink <filename>/etc/ca-bundle.crt</filename> is gone. Programs

     

       172
       172
       +
            should instead use the environment variable

     

       173
       173
       +
            <envar>OPENSSL_X509_CERT_FILE</envar> (which points to

     

       174
       174
       +
            <filename>/etc/ssl/certs/ca-bundle.crt</filename>).

     

       126
       175
        
           </para>

     

       127
       176
        
          </listitem>

     

       128
       177
        
         </itemizedlist>

+62 -19

nixos/doc/manual/release-notes/rl-1412.xml

···

       6
       6
        
        <title>Release 14.12 (“Caterpillar”, 2014/12/30)</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         In addition to numerous new and upgraded packages, this release has the following highlights:

     

       9
       9
       +
         In addition to numerous new and upgraded packages, this release has the

     

       10
       10
       +
         following highlights:

     

       10
       11
        
         <itemizedlist>

     

       11
       12
        
          <listitem>

     

       12
       13
        
           <para>

     

       13
       13
       -
            Systemd has been updated to version 217, which has numerous <link xlink:href="http://lists.freedesktop.org/archives/systemd-devel/2014-October/024662.html">improvements.</link>

     

       14
       14
       +
            Systemd has been updated to version 217, which has numerous

     

       15
       15
       +
            <link xlink:href="http://lists.freedesktop.org/archives/systemd-devel/2014-October/024662.html">improvements.</link>

     

       14
       16
        
           </para>

     

       15
       17
        
          </listitem>

     

       16
       18
        
          <listitem>

     

       17
       19
        
           <para>

     

       18
       18
       -
            <link xlink:href="https://www.mail-archive.com/nix-dev@lists.science.uu.nl/msg13957.html"> Nix has been updated to 1.8.</link>

     

       20
       20
       +
            <link xlink:href="https://www.mail-archive.com/nix-dev@lists.science.uu.nl/msg13957.html">

     

       21
       21
       +
            Nix has been updated to 1.8.</link>

     

       19
       22
        
           </para>

     

       20
       23
        
          </listitem>

     

       21
       24
        
          <listitem>

     
···

       35
       38
        
          </listitem>

     

       36
       39
        
          <listitem>

     

       37
       40
        
           <para>

     

       38
       38
       -
            If <option>users.mutableUsers</option> is enabled (the default), changes made to the declaration of a user or group will be correctly realised when running <command>nixos-rebuild</command>. For instance, removing a user specification from <filename>configuration.nix</filename> will cause the actual user account to be deleted. If <option>users.mutableUsers</option> is disabled, it is no longer necessary to specify UIDs or GIDs; if omitted, they are allocated dynamically.

     

       41
       41
       +
            If <option>users.mutableUsers</option> is enabled (the default), changes

     

       42
       42
       +
            made to the declaration of a user or group will be correctly realised when

     

       43
       43
       +
            running <command>nixos-rebuild</command>. For instance, removing a user

     

       44
       44
       +
            specification from <filename>configuration.nix</filename> will cause the

     

       45
       45
       +
            actual user account to be deleted. If <option>users.mutableUsers</option>

     

       46
       46
       +
            is disabled, it is no longer necessary to specify UIDs or GIDs; if

     

       47
       47
       +
            omitted, they are allocated dynamically.

     

       39
       48
        
           </para>

     

       40
       49
        
          </listitem>

     

       41
       50
        
         </itemizedlist>

     
···

       353
       362
        
        </para>

     

       354
       363
        
       

     

       355
       364
        
        <para>

     

       356
       356
       -
         When upgrading from a previous release, please be aware of the following incompatible changes:

     

       365
       365
       +
         When upgrading from a previous release, please be aware of the following

     

       366
       366
       +
         incompatible changes:

     

       357
       367
        
         <itemizedlist>

     

       358
       368
        
          <listitem>

     

       359
       369
        
           <para>

     

       360
       360
       -
            The default version of Apache httpd is now 2.4. If you use the <option>extraConfig</option> option to pass literal Apache configuration text, you may need to update it — see <link

     

       361
       361
       -
       xlink:href="http://httpd.apache.org/docs/2.4/upgrading.html">Apache’s documentation</link> for details. If you wish to continue to use httpd 2.2, add the following line to your NixOS configuration:

     

       370
       370
       +
            The default version of Apache httpd is now 2.4. If you use the

     

       371
       371
       +
            <option>extraConfig</option> option to pass literal Apache configuration

     

       372
       372
       +
            text, you may need to update it — see

     

       373
       373
       +
            <link

     

       374
       374
       +
       xlink:href="http://httpd.apache.org/docs/2.4/upgrading.html">Apache’s

     

       375
       375
       +
            documentation</link> for details. If you wish to continue to use httpd

     

       376
       376
       +
            2.2, add the following line to your NixOS configuration:

     

       362
       377
        
       <programlisting>

     

       363
       378
        
       services.httpd.package = pkgs.apacheHttpd_2_2;

     

       364
       379
        
       </programlisting>

     
···

       366
       381
        
          </listitem>

     

       367
       382
        
          <listitem>

     

       368
       383
        
           <para>

     

       369
       369
       -
            PHP 5.3 has been removed because it is no longer supported by the PHP project. A <link

     

       370
       370
       -
       xlink:href="http://php.net/migration54">migration guide</link> is available.

     

       384
       384
       +
            PHP 5.3 has been removed because it is no longer supported by the PHP

     

       385
       385
       +
            project. A <link

     

       386
       386
       +
       xlink:href="http://php.net/migration54">migration

     

       387
       387
       +
            guide</link> is available.

     

       371
       388
        
           </para>

     

       372
       389
        
          </listitem>

     

       373
       390
        
          <listitem>

     

       374
       391
        
           <para>

     

       375
       375
       -
            The host side of a container virtual Ethernet pair is now called <literal>ve-<replaceable>container-name</replaceable></literal> rather than <literal>c-<replaceable>container-name</replaceable></literal>.

     

       392
       392
       +
            The host side of a container virtual Ethernet pair is now called

     

       393
       393
       +
            <literal>ve-<replaceable>container-name</replaceable></literal> rather

     

       394
       394
       +
            than <literal>c-<replaceable>container-name</replaceable></literal>.

     

       376
       395
        
           </para>

     

       377
       396
        
          </listitem>

     

       378
       397
        
          <listitem>

     

       379
       398
        
           <para>

     

       380
       380
       -
            GNOME 3.10 support has been dropped. The default GNOME version is now 3.12.

     

       399
       399
       +
            GNOME 3.10 support has been dropped. The default GNOME version is now

     

       400
       400
       +
            3.12.

     

       381
       401
        
           </para>

     

       382
       402
        
          </listitem>

     

       383
       403
        
          <listitem>

     

       384
       404
        
           <para>

     

       385
       385
       -
            VirtualBox has been upgraded to 4.3.20 release. Users may be required to run <command>rm -rf /tmp/.vbox*</command>. The line <literal>imports = [ &lt;nixpkgs/nixos/modules/programs/virtualbox.nix&gt; ]</literal> is no longer necessary, use <literal>services.virtualboxHost.enable = true</literal> instead.

     

       405
       405
       +
            VirtualBox has been upgraded to 4.3.20 release. Users may be required to

     

       406
       406
       +
            run <command>rm -rf /tmp/.vbox*</command>. The line <literal>imports = [

     

       407
       407
       +
            &lt;nixpkgs/nixos/modules/programs/virtualbox.nix&gt; ]</literal> is no

     

       408
       408
       +
            longer necessary, use <literal>services.virtualboxHost.enable =

     

       409
       409
       +
            true</literal> instead.

     

       386
       410
        
           </para>

     

       387
       411
        
           <para>

     

       388
       388
       -
            Also, hardening mode is now enabled by default, which means that unless you want to use USB support, you no longer need to be a member of the <literal>vboxusers</literal> group.

     

       412
       412
       +
            Also, hardening mode is now enabled by default, which means that unless

     

       413
       413
       +
            you want to use USB support, you no longer need to be a member of the

     

       414
       414
       +
            <literal>vboxusers</literal> group.

     

       389
       415
        
           </para>

     

       390
       416
        
          </listitem>

     

       391
       417
        
          <listitem>

     

       392
       418
        
           <para>

     

       393
       393
       -
            Chromium has been updated to 39.0.2171.65. <option>enablePepperPDF</option> is now enabled by default. <literal>chromium*Wrapper</literal> packages no longer exist, because upstream removed NSAPI support. <literal>chromium-stable</literal> has been renamed to <literal>chromium</literal>.

     

       419
       419
       +
            Chromium has been updated to 39.0.2171.65.

     

       420
       420
       +
            <option>enablePepperPDF</option> is now enabled by default.

     

       421
       421
       +
            <literal>chromium*Wrapper</literal> packages no longer exist, because

     

       422
       422
       +
            upstream removed NSAPI support. <literal>chromium-stable</literal> has

     

       423
       423
       +
            been renamed to <literal>chromium</literal>.

     

       394
       424
        
           </para>

     

       395
       425
        
          </listitem>

     

       396
       426
        
          <listitem>

     

       397
       427
        
           <para>

     

       398
       398
       -
            Python packaging documentation is now part of nixpkgs manual. To override the python packages available to a custom python you now use <literal>pkgs.pythonFull.buildEnv.override</literal> instead of <literal>pkgs.pythonFull.override</literal>.

     

       428
       428
       +
            Python packaging documentation is now part of nixpkgs manual. To override

     

       429
       429
       +
            the python packages available to a custom python you now use

     

       430
       430
       +
            <literal>pkgs.pythonFull.buildEnv.override</literal> instead of

     

       431
       431
       +
            <literal>pkgs.pythonFull.override</literal>.

     

       399
       432
        
           </para>

     

       400
       433
        
          </listitem>

     

       401
       434
        
          <listitem>

     

       402
       435
        
           <para>

     

       403
       403
       -
            <literal>boot.resumeDevice = "8:6"</literal> is no longer supported. Most users will want to leave it undefined, which takes the swap partitions automatically. There is an evaluation assertion to ensure that the string starts with a slash.

     

       436
       436
       +
            <literal>boot.resumeDevice = "8:6"</literal> is no longer supported. Most

     

       437
       437
       +
            users will want to leave it undefined, which takes the swap partitions

     

       438
       438
       +
            automatically. There is an evaluation assertion to ensure that the string

     

       439
       439
       +
            starts with a slash.

     

       404
       440
        
           </para>

     

       405
       441
        
          </listitem>

     

       406
       442
        
          <listitem>

     

       407
       443
        
           <para>

     

       408
       408
       -
            The system-wide default timezone for NixOS installations changed from <literal>CET</literal> to <literal>UTC</literal>. To choose a different timezone for your system, configure <literal>time.timeZone</literal> in <literal>configuration.nix</literal>. A fairly complete list of possible values for that setting is available at <link

     

       444
       444
       +
            The system-wide default timezone for NixOS installations changed from

     

       445
       445
       +
            <literal>CET</literal> to <literal>UTC</literal>. To choose a different

     

       446
       446
       +
            timezone for your system, configure <literal>time.timeZone</literal> in

     

       447
       447
       +
            <literal>configuration.nix</literal>. A fairly complete list of possible

     

       448
       448
       +
            values for that setting is available at

     

       449
       449
       +
            <link

     

       409
       450
        
       xlink:href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones"/>.

     

       410
       451
        
           </para>

     

       411
       452
        
          </listitem>

     

       412
       453
        
          <listitem>

     

       413
       454
        
           <para>

     

       414
       414
       -
            GNU screen has been updated to 4.2.1, which breaks the ability to connect to sessions created by older versions of screen.

     

       455
       455
       +
            GNU screen has been updated to 4.2.1, which breaks the ability to connect

     

       456
       456
       +
            to sessions created by older versions of screen.

     

       415
       457
        
           </para>

     

       416
       458
        
          </listitem>

     

       417
       459
        
          <listitem>

     

       418
       460
        
           <para>

     

       419
       419
       -
            The Intel GPU driver was updated to the 3.x prerelease version (used by most distributions) and supports DRI3 now.

     

       461
       461
       +
            The Intel GPU driver was updated to the 3.x prerelease version (used by

     

       462
       462
       +
            most distributions) and supports DRI3 now.

     

       420
       463
        
           </para>

     

       421
       464
        
          </listitem>

     

       422
       465
        
         </itemizedlist>

+163 -45

nixos/doc/manual/release-notes/rl-1509.xml

···

       6
       6
        
        <title>Release 15.09 (“Dingo”, 2015/09/30)</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         In addition to numerous new and upgraded packages, this release has the following highlights:

     

       9
       9
       +
         In addition to numerous new and upgraded packages, this release has the

     

       10
       10
       +
         following highlights:

     

       10
       11
        
        </para>

     

       11
       12
        
       

     

       12
       13
        
        <itemizedlist>

     

       13
       14
        
         <listitem>

     

       14
       15
        
          <para>

     

       15
       15
       -
           The <link xlink:href="http://haskell.org/">Haskell</link> packages infrastructure has been re-designed from the ground up (&quot;Haskell NG&quot;). NixOS now distributes the latest version of every single package registered on <link

     

       16
       16
       -
           xlink:href="http://hackage.haskell.org/">Hackage</link> -- well in excess of 8,000 Haskell packages. Detailed instructions on how to use that infrastructure can be found in the <link

     

       17
       17
       -
           xlink:href="http://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure">User's Guide to the Haskell Infrastructure</link>. Users migrating from an earlier release may find helpful information below, in the list of backwards-incompatible changes. Furthermore, we distribute 51(!) additional Haskell package sets that provide every single <link

     

       18
       18
       -
           xlink:href="http://www.stackage.org/">LTS Haskell</link> release since version 0.0 as well as the most recent <link

     

       19
       19
       -
           xlink:href="http://www.stackage.org/">Stackage Nightly</link> snapshot. The announcement <link

     

       20
       20
       -
           xlink:href="https://nixos.org/nix-dev/2015-September/018138.html">&quot;Full Stackage Support in Nixpkgs&quot;</link> gives additional details.

     

       16
       16
       +
           The <link xlink:href="http://haskell.org/">Haskell</link> packages

     

       17
       17
       +
           infrastructure has been re-designed from the ground up (&quot;Haskell

     

       18
       18
       +
           NG&quot;). NixOS now distributes the latest version of every single package

     

       19
       19
       +
           registered on

     

       20
       20
       +
           <link

     

       21
       21
       +
           xlink:href="http://hackage.haskell.org/">Hackage</link> -- well

     

       22
       22
       +
           in excess of 8,000 Haskell packages. Detailed instructions on how to use

     

       23
       23
       +
           that infrastructure can be found in the

     

       24
       24
       +
           <link

     

       25
       25
       +
           xlink:href="http://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure">User's

     

       26
       26
       +
           Guide to the Haskell Infrastructure</link>. Users migrating from an earlier

     

       27
       27
       +
           release may find helpful information below, in the list of

     

       28
       28
       +
           backwards-incompatible changes. Furthermore, we distribute 51(!) additional

     

       29
       29
       +
           Haskell package sets that provide every single

     

       30
       30
       +
           <link

     

       31
       31
       +
           xlink:href="http://www.stackage.org/">LTS Haskell</link> release

     

       32
       32
       +
           since version 0.0 as well as the most recent

     

       33
       33
       +
           <link

     

       34
       34
       +
           xlink:href="http://www.stackage.org/">Stackage Nightly</link>

     

       35
       35
       +
           snapshot. The announcement

     

       36
       36
       +
           <link

     

       37
       37
       +
           xlink:href="https://nixos.org/nix-dev/2015-September/018138.html">&quot;Full

     

       38
       38
       +
           Stackage Support in Nixpkgs&quot;</link> gives additional details.

     

       21
       39
        
          </para>

     

       22
       40
        
         </listitem>

     

       23
       41
        
         <listitem>

     

       24
       42
        
          <para>

     

       25
       25
       -
           Nix has been updated to version 1.10, which among other improvements enables cryptographic signatures on binary caches for improved security.

     

       43
       43
       +
           Nix has been updated to version 1.10, which among other improvements

     

       44
       44
       +
           enables cryptographic signatures on binary caches for improved security.

     

       26
       45
        
          </para>

     

       27
       46
        
         </listitem>

     

       28
       47
        
         <listitem>

     
···

       31
       50
        
       <programlisting>

     

       32
       51
        
       system.autoUpgrade.enable = true;

     

       33
       52
        
       </programlisting>

     

       34
       34
       -
           This will cause the system to periodically check for updates in your current channel and run <command>nixos-rebuild</command>.

     

       53
       53
       +
           This will cause the system to periodically check for updates in your

     

       54
       54
       +
           current channel and run <command>nixos-rebuild</command>.

     

       35
       55
        
          </para>

     

       36
       56
        
         </listitem>

     

       37
       57
        
         <listitem>

     
···

       51
       71
        
         </listitem>

     

       52
       72
        
         <listitem>

     

       53
       73
        
          <para>

     

       54
       54
       -
           KDE 5 has been upgraded to KDE Frameworks 5.10, Plasma 5.3.2 and Applications 15.04.3. KDE 4 has been updated to kdelibs-4.14.10.

     

       74
       74
       +
           KDE 5 has been upgraded to KDE Frameworks 5.10, Plasma 5.3.2 and

     

       75
       75
       +
           Applications 15.04.3. KDE 4 has been updated to kdelibs-4.14.10.

     

       55
       76
        
          </para>

     

       56
       77
        
         </listitem>

     

       57
       78
        
         <listitem>

     
···

       403
       424
        
        </para>

     

       404
       425
        
       

     

       405
       426
        
        <para>

     

       406
       406
       -
         When upgrading from a previous release, please be aware of the following incompatible changes:

     

       427
       427
       +
         When upgrading from a previous release, please be aware of the following

     

       428
       428
       +
         incompatible changes:

     

       407
       429
        
         <itemizedlist>

     

       408
       430
        
          <listitem>

     

       409
       431
        
           <para>

     

       410
       410
       -
            <command>sshd</command> no longer supports DSA and ECDSA host keys by default. If you have existing systems with such host keys and want to continue to use them, please set

     

       432
       432
       +
            <command>sshd</command> no longer supports DSA and ECDSA host keys by

     

       433
       433
       +
            default. If you have existing systems with such host keys and want to

     

       434
       434
       +
            continue to use them, please set

     

       411
       435
        
       <programlisting>

     

       412
       436
        
       system.stateVersion = "14.12";

     

       413
       437
        
       </programlisting>

     

       414
       414
       -
            The new option <option>system.stateVersion</option> ensures that certain configuration changes that could break existing systems (such as the <command>sshd</command> host key setting) will maintain compatibility with the specified NixOS release. NixOps sets the state version of existing deployments automatically.

     

       438
       438
       +
            The new option <option>system.stateVersion</option> ensures that certain

     

       439
       439
       +
            configuration changes that could break existing systems (such as the

     

       440
       440
       +
            <command>sshd</command> host key setting) will maintain compatibility with

     

       441
       441
       +
            the specified NixOS release. NixOps sets the state version of existing

     

       442
       442
       +
            deployments automatically.

     

       415
       443
        
           </para>

     

       416
       444
        
          </listitem>

     

       417
       445
        
          <listitem>

     

       418
       446
        
           <para>

     

       419
       419
       -
            <command>cron</command> is no longer enabled by default, unless you have a non-empty <option>services.cron.systemCronJobs</option>. To force <command>cron</command> to be enabled, set <option>services.cron.enable = true</option>.

     

       447
       447
       +
            <command>cron</command> is no longer enabled by default, unless you have a

     

       448
       448
       +
            non-empty <option>services.cron.systemCronJobs</option>. To force

     

       449
       449
       +
            <command>cron</command> to be enabled, set <option>services.cron.enable =

     

       450
       450
       +
            true</option>.

     

       420
       451
        
           </para>

     

       421
       452
        
          </listitem>

     

       422
       453
        
          <listitem>

     

       423
       454
        
           <para>

     

       424
       424
       -
            Nix now requires binary caches to be cryptographically signed. If you have unsigned binary caches that you want to continue to use, you should set <option>nix.requireSignedBinaryCaches = false</option>.

     

       455
       455
       +
            Nix now requires binary caches to be cryptographically signed. If you have

     

       456
       456
       +
            unsigned binary caches that you want to continue to use, you should set

     

       457
       457
       +
            <option>nix.requireSignedBinaryCaches = false</option>.

     

       425
       458
        
           </para>

     

       426
       459
        
          </listitem>

     

       427
       460
        
          <listitem>

     

       428
       461
        
           <para>

     

       429
       429
       -
            Steam now doesn't need root rights to work. Instead of using <literal>*-steam-chrootenv</literal>, you should now just run <literal>steam</literal>. <literal>steamChrootEnv</literal> package was renamed to <literal>steam</literal>, and old <literal>steam</literal> package -- to <literal>steamOriginal</literal>.

     

       462
       462
       +
            Steam now doesn't need root rights to work. Instead of using

     

       463
       463
       +
            <literal>*-steam-chrootenv</literal>, you should now just run

     

       464
       464
       +
            <literal>steam</literal>. <literal>steamChrootEnv</literal> package was

     

       465
       465
       +
            renamed to <literal>steam</literal>, and old <literal>steam</literal>

     

       466
       466
       +
            package -- to <literal>steamOriginal</literal>.

     

       430
       467
        
           </para>

     

       431
       468
        
          </listitem>

     

       432
       469
        
          <listitem>

     

       433
       470
        
           <para>

     

       434
       434
       -
            CMPlayer has been renamed to bomi upstream. Package <literal>cmplayer</literal> was accordingly renamed to <literal>bomi</literal>

     

       471
       471
       +
            CMPlayer has been renamed to bomi upstream. Package

     

       472
       472
       +
            <literal>cmplayer</literal> was accordingly renamed to

     

       473
       473
       +
            <literal>bomi</literal>

     

       435
       474
        
           </para>

     

       436
       475
        
          </listitem>

     

       437
       476
        
          <listitem>

     

       438
       477
        
           <para>

     

       439
       439
       -
            Atom Shell has been renamed to Electron upstream. Package <literal>atom-shell</literal> was accordingly renamed to <literal>electron</literal>

     

       478
       478
       +
            Atom Shell has been renamed to Electron upstream. Package

     

       479
       479
       +
            <literal>atom-shell</literal> was accordingly renamed to

     

       480
       480
       +
            <literal>electron</literal>

     

       440
       481
        
           </para>

     

       441
       482
        
          </listitem>

     

       442
       483
        
          <listitem>

     

       443
       484
        
           <para>

     

       444
       444
       -
            Elm is not released on Hackage anymore. You should now use <literal>elmPackages.elm</literal> which contains the latest Elm platform.

     

       485
       485
       +
            Elm is not released on Hackage anymore. You should now use

     

       486
       486
       +
            <literal>elmPackages.elm</literal> which contains the latest Elm platform.

     

       445
       487
        
           </para>

     

       446
       488
        
          </listitem>

     

       447
       489
        
          <listitem>

     

       448
       490
        
           <para>

     

       449
       449
       -
            The CUPS printing service has been updated to version <literal>2.0.2</literal>. Furthermore its systemd service has been renamed to <literal>cups.service</literal>.

     

       491
       491
       +
            The CUPS printing service has been updated to version

     

       492
       492
       +
            <literal>2.0.2</literal>. Furthermore its systemd service has been renamed

     

       493
       493
       +
            to <literal>cups.service</literal>.

     

       450
       494
        
           </para>

     

       451
       495
        
           <para>

     

       452
       452
       -
            Local printers are no longer shared or advertised by default. This behavior can be changed by enabling <option>services.printing.defaultShared</option> or <option>services.printing.browsing</option> respectively.

     

       496
       496
       +
            Local printers are no longer shared or advertised by default. This

     

       497
       497
       +
            behavior can be changed by enabling

     

       498
       498
       +
            <option>services.printing.defaultShared</option> or

     

       499
       499
       +
            <option>services.printing.browsing</option> respectively.

     

       453
       500
        
           </para>

     

       454
       501
        
          </listitem>

     

       455
       502
        
          <listitem>

     

       456
       503
        
           <para>

     

       457
       457
       -
            The VirtualBox host and guest options have been named more consistently. They can now found in <option>virtualisation.virtualbox.host.*</option> instead of <option>services.virtualboxHost.*</option> and <option>virtualisation.virtualbox.guest.*</option> instead of <option>services.virtualboxGuest.*</option>.

     

       504
       504
       +
            The VirtualBox host and guest options have been named more consistently.

     

       505
       505
       +
            They can now found in <option>virtualisation.virtualbox.host.*</option>

     

       506
       506
       +
            instead of <option>services.virtualboxHost.*</option> and

     

       507
       507
       +
            <option>virtualisation.virtualbox.guest.*</option> instead of

     

       508
       508
       +
            <option>services.virtualboxGuest.*</option>.

     

       458
       509
        
           </para>

     

       459
       510
        
           <para>

     

       460
       460
       -
            Also, there now is support for the <literal>vboxsf</literal> file system using the <option>fileSystems</option> configuration attribute. An example of how this can be used in a configuration:

     

       511
       511
       +
            Also, there now is support for the <literal>vboxsf</literal> file system

     

       512
       512
       +
            using the <option>fileSystems</option> configuration attribute. An example

     

       513
       513
       +
            of how this can be used in a configuration:

     

       461
       514
        
       <programlisting>

     

       462
       515
        
       fileSystems."/shiny" = {

     

       463
       516
        
         device = "myshinysharedfolder";

     
···

       468
       521
        
          </listitem>

     

       469
       522
        
          <listitem>

     

       470
       523
        
           <para>

     

       471
       471
       -
            &quot;<literal>nix-env -qa</literal>&quot; no longer discovers Haskell packages by name. The only packages visible in the global scope are <literal>ghc</literal>, <literal>cabal-install</literal>, and <literal>stack</literal>, but all other packages are hidden. The reason for this inconvenience is the sheer size of the Haskell package set. Name-based lookups are expensive, and most <literal>nix-env -qa</literal> operations would become much slower if we'd add the entire Hackage database into the top level attribute set. Instead, the list of Haskell packages can be displayed by running:

     

       524
       524
       +
            &quot;<literal>nix-env -qa</literal>&quot; no longer discovers Haskell

     

       525
       525
       +
            packages by name. The only packages visible in the global scope are

     

       526
       526
       +
            <literal>ghc</literal>, <literal>cabal-install</literal>, and

     

       527
       527
       +
            <literal>stack</literal>, but all other packages are hidden. The reason

     

       528
       528
       +
            for this inconvenience is the sheer size of the Haskell package set.

     

       529
       529
       +
            Name-based lookups are expensive, and most <literal>nix-env -qa</literal>

     

       530
       530
       +
            operations would become much slower if we'd add the entire Hackage

     

       531
       531
       +
            database into the top level attribute set. Instead, the list of Haskell

     

       532
       532
       +
            packages can be displayed by running:

     

       472
       533
        
           </para>

     

       473
       534
        
       <programlisting>

     

       474
       535
        
       nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A haskellPackages

     
···

       480
       541
        
       nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA haskellPackages.pandoc

     

       481
       542
        
       </programlisting>

     

       482
       543
        
           <para>

     

       483
       483
       -
            Installing Haskell <emphasis>libraries</emphasis> this way, however, is no longer supported. See the next item for more details.

     

       544
       544
       +
            Installing Haskell <emphasis>libraries</emphasis> this way, however, is no

     

       545
       545
       +
            longer supported. See the next item for more details.

     

       484
       546
        
           </para>

     

       485
       547
        
          </listitem>

     

       486
       548
        
          <listitem>

     

       487
       549
        
           <para>

     

       488
       488
       -
            Previous versions of NixOS came with a feature called <literal>ghc-wrapper</literal>, a small script that allowed GHC to transparently pick up on libraries installed in the user's profile. This feature has been deprecated; <literal>ghc-wrapper</literal> was removed from the distribution. The proper way to register Haskell libraries with the compiler now is the <literal>haskellPackages.ghcWithPackages</literal> function. The <link

     

       489
       489
       -
           xlink:href="http://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure">User's Guide to the Haskell Infrastructure</link> provides more information about this subject.

     

       550
       550
       +
            Previous versions of NixOS came with a feature called

     

       551
       551
       +
            <literal>ghc-wrapper</literal>, a small script that allowed GHC to

     

       552
       552
       +
            transparently pick up on libraries installed in the user's profile. This

     

       553
       553
       +
            feature has been deprecated; <literal>ghc-wrapper</literal> was removed

     

       554
       554
       +
            from the distribution. The proper way to register Haskell libraries with

     

       555
       555
       +
            the compiler now is the <literal>haskellPackages.ghcWithPackages</literal>

     

       556
       556
       +
            function. The

     

       557
       557
       +
            <link

     

       558
       558
       +
           xlink:href="http://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure">User's

     

       559
       559
       +
            Guide to the Haskell Infrastructure</link> provides more information about

     

       560
       560
       +
            this subject.

     

       490
       561
        
           </para>

     

       491
       562
        
          </listitem>

     

       492
       563
        
          <listitem>

     

       493
       564
        
           <para>

     

       494
       494
       -
            All Haskell builds that have been generated with version 1.x of the <literal>cabal2nix</literal> utility are now invalid and need to be re-generated with a current version of <literal>cabal2nix</literal> to function. The most recent version of this tool can be installed by running <literal>nix-env -i cabal2nix</literal>.

     

       565
       565
       +
            All Haskell builds that have been generated with version 1.x of the

     

       566
       566
       +
            <literal>cabal2nix</literal> utility are now invalid and need to be

     

       567
       567
       +
            re-generated with a current version of <literal>cabal2nix</literal> to

     

       568
       568
       +
            function. The most recent version of this tool can be installed by running

     

       569
       569
       +
            <literal>nix-env -i cabal2nix</literal>.

     

       495
       570
        
           </para>

     

       496
       571
        
          </listitem>

     

       497
       572
        
          <listitem>

     

       498
       573
        
           <para>

     

       499
       499
       -
            The <literal>haskellPackages</literal> set in Nixpkgs used to have a function attribute called <literal>extension</literal> that users could override in their <literal>~/.nixpkgs/config.nix</literal> files to configure additional attributes, etc. That function still exists, but it's now called <literal>overrides</literal>.

     

       574
       574
       +
            The <literal>haskellPackages</literal> set in Nixpkgs used to have a

     

       575
       575
       +
            function attribute called <literal>extension</literal> that users could

     

       576
       576
       +
            override in their <literal>~/.nixpkgs/config.nix</literal> files to

     

       577
       577
       +
            configure additional attributes, etc. That function still exists, but it's

     

       578
       578
       +
            now called <literal>overrides</literal>.

     

       500
       579
        
           </para>

     

       501
       580
        
          </listitem>

     

       502
       581
        
          <listitem>

     

       503
       582
        
           <para>

     

       504
       504
       -
            The OpenBLAS library has been updated to version <literal>0.2.14</literal>. Support for the <literal>x86_64-darwin</literal> platform was added. Dynamic architecture detection was enabled; OpenBLAS now selects microarchitecture-optimized routines at runtime, so optimal performance is achieved without the need to rebuild OpenBLAS locally. OpenBLAS has replaced ATLAS in most packages which use an optimized BLAS or LAPACK implementation.

     

       583
       583
       +
            The OpenBLAS library has been updated to version

     

       584
       584
       +
            <literal>0.2.14</literal>. Support for the

     

       585
       585
       +
            <literal>x86_64-darwin</literal> platform was added. Dynamic architecture

     

       586
       586
       +
            detection was enabled; OpenBLAS now selects microarchitecture-optimized

     

       587
       587
       +
            routines at runtime, so optimal performance is achieved without the need

     

       588
       588
       +
            to rebuild OpenBLAS locally. OpenBLAS has replaced ATLAS in most packages

     

       589
       589
       +
            which use an optimized BLAS or LAPACK implementation.

     

       505
       590
        
           </para>

     

       506
       591
        
          </listitem>

     

       507
       592
        
          <listitem>

     

       508
       593
        
           <para>

     

       509
       509
       -
            The <literal>phpfpm</literal> is now using the default PHP version (<literal>pkgs.php</literal>) instead of PHP 5.4 (<literal>pkgs.php54</literal>).

     

       594
       594
       +
            The <literal>phpfpm</literal> is now using the default PHP version

     

       595
       595
       +
            (<literal>pkgs.php</literal>) instead of PHP 5.4

     

       596
       596
       +
            (<literal>pkgs.php54</literal>).

     

       510
       597
        
           </para>

     

       511
       598
        
          </listitem>

     

       512
       599
        
          <listitem>

     

       513
       600
        
           <para>

     

       514
       514
       -
            The <literal>locate</literal> service no longer indexes the Nix store by default, preventing packages with potentially numerous versions from cluttering the output. Indexing the store can be activated by setting <option>services.locate.includeStore = true</option>.

     

       601
       601
       +
            The <literal>locate</literal> service no longer indexes the Nix store by

     

       602
       602
       +
            default, preventing packages with potentially numerous versions from

     

       603
       603
       +
            cluttering the output. Indexing the store can be activated by setting

     

       604
       604
       +
            <option>services.locate.includeStore = true</option>.

     

       515
       605
        
           </para>

     

       516
       606
        
          </listitem>

     

       517
       607
        
          <listitem>

     

       518
       608
        
           <para>

     

       519
       519
       -
            The Nix expression search path (<envar>NIX_PATH</envar>) no longer contains <filename>/etc/nixos/nixpkgs</filename> by default. You can override <envar>NIX_PATH</envar> by setting <option>nix.nixPath</option>.

     

       609
       609
       +
            The Nix expression search path (<envar>NIX_PATH</envar>) no longer

     

       610
       610
       +
            contains <filename>/etc/nixos/nixpkgs</filename> by default. You can

     

       611
       611
       +
            override <envar>NIX_PATH</envar> by setting <option>nix.nixPath</option>.

     

       520
       612
        
           </para>

     

       521
       613
        
          </listitem>

     

       522
       614
        
          <listitem>

     

       523
       615
        
           <para>

     

       524
       524
       -
            Python 2.6 has been marked as broken (as it no longer receives security updates from upstream).

     

       616
       616
       +
            Python 2.6 has been marked as broken (as it no longer receives security

     

       617
       617
       +
            updates from upstream).

     

       525
       618
        
           </para>

     

       526
       619
        
          </listitem>

     

       527
       620
        
          <listitem>

     

       528
       621
        
           <para>

     

       529
       529
       -
            Any use of module arguments such as <varname>pkgs</varname> to access library functions, or to define <literal>imports</literal> attributes will now lead to an infinite loop at the time of the evaluation.

     

       622
       622
       +
            Any use of module arguments such as <varname>pkgs</varname> to access

     

       623
       623
       +
            library functions, or to define <literal>imports</literal> attributes will

     

       624
       624
       +
            now lead to an infinite loop at the time of the evaluation.

     

       530
       625
        
           </para>

     

       531
       626
        
           <para>

     

       532
       532
       -
            In case of an infinite loop, use the <command>--show-trace</command> command line argument and read the line just above the error message.

     

       627
       627
       +
            In case of an infinite loop, use the <command>--show-trace</command>

     

       628
       628
       +
            command line argument and read the line just above the error message.

     

       533
       629
        
       <screen>

     

       534
       630
        
       <prompt>$ </prompt>nixos-rebuild build --show-trace

     

       535
       631
        
       …

     
···

       538
       634
        
       </screen>

     

       539
       635
        
           </para>

     

       540
       636
        
           <para>

     

       541
       541
       -
            Any use of <literal>pkgs.lib</literal>, should be replaced by <varname>lib</varname>, after adding it as argument of the module. The following module

     

       637
       637
       +
            Any use of <literal>pkgs.lib</literal>, should be replaced by

     

       638
       638
       +
            <varname>lib</varname>, after adding it as argument of the module. The

     

       639
       639
       +
            following module

     

       542
       640
        
       <programlisting>

     

       543
       641
        
       { config, pkgs, ... }:

     

       544
       642
        
       

     
···

       566
       664
        
       </programlisting>

     

       567
       665
        
           </para>

     

       568
       666
        
           <para>

     

       569
       569
       -
            When <varname>pkgs</varname> is used to download other projects to import their modules, and only in such cases, it should be replaced by <literal>(import &lt;nixpkgs&gt; {})</literal>. The following module

     

       667
       667
       +
            When <varname>pkgs</varname> is used to download other projects to import

     

       668
       668
       +
            their modules, and only in such cases, it should be replaced by

     

       669
       669
       +
            <literal>(import &lt;nixpkgs&gt; {})</literal>. The following module

     

       570
       670
        
       <programlisting>

     

       571
       671
        
       { config, pkgs, ... }:

     

       572
       672
        
       

     
···

       606
       706
        
         <itemizedlist>

     

       607
       707
        
          <listitem>

     

       608
       708
        
           <para>

     

       609
       609
       -
            The nixos and nixpkgs channels were unified, so one <emphasis>can</emphasis> use <literal>nix-env -iA nixos.bash</literal> instead of <literal>nix-env -iA nixos.pkgs.bash</literal>. See <link xlink:href="https://github.com/NixOS/nixpkgs/commit/2cd7c1f198">the commit</link> for details.

     

       709
       709
       +
            The nixos and nixpkgs channels were unified, so one

     

       710
       710
       +
            <emphasis>can</emphasis> use <literal>nix-env -iA nixos.bash</literal>

     

       711
       711
       +
            instead of <literal>nix-env -iA nixos.pkgs.bash</literal>. See

     

       712
       712
       +
            <link xlink:href="https://github.com/NixOS/nixpkgs/commit/2cd7c1f198">the

     

       713
       713
       +
            commit</link> for details.

     

       610
       714
        
           </para>

     

       611
       715
        
          </listitem>

     

       612
       716
        
          <listitem>

     

       613
       717
        
           <para>

     

       614
       614
       -
            Users running an SSH server who worry about the quality of their <literal>/etc/ssh/moduli</literal> file with respect to the <link

     

       615
       615
       -
             xlink:href="https://stribika.github.io/2015/01/04/secure-secure-shell.html">vulnerabilities discovered in the Diffie-Hellman key exchange</link> can now replace OpenSSH's default version with one they generated themselves using the new <option>services.openssh.moduliFile</option> option.

     

       718
       718
       +
            Users running an SSH server who worry about the quality of their

     

       719
       719
       +
            <literal>/etc/ssh/moduli</literal> file with respect to the

     

       720
       720
       +
            <link

     

       721
       721
       +
             xlink:href="https://stribika.github.io/2015/01/04/secure-secure-shell.html">vulnerabilities

     

       722
       722
       +
            discovered in the Diffie-Hellman key exchange</link> can now replace

     

       723
       723
       +
            OpenSSH's default version with one they generated themselves using the new

     

       724
       724
       +
            <option>services.openssh.moduliFile</option> option.

     

       616
       725
        
           </para>

     

       617
       726
        
          </listitem>

     

       618
       727
        
          <listitem>

     

       619
       728
        
           <para>

     

       620
       620
       -
            A newly packaged TeX Live 2015 is provided in <literal>pkgs.texlive</literal>, split into 6500 nix packages. For basic user documentation see <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-15.09/pkgs/tools/typesetting/tex/texlive/default.nix#L1"

     

       621
       621
       -
             >the source</link>. Beware of <link xlink:href="https://github.com/NixOS/nixpkgs/issues/9757"

     

       622
       622
       -
             >an issue</link> when installing a too large package set. The plan is to deprecate and maybe delete the original TeX packages until the next release.

     

       729
       729
       +
            A newly packaged TeX Live 2015 is provided in

     

       730
       730
       +
            <literal>pkgs.texlive</literal>, split into 6500 nix packages. For basic

     

       731
       731
       +
            user documentation see

     

       732
       732
       +
            <link xlink:href="https://github.com/NixOS/nixpkgs/blob/release-15.09/pkgs/tools/typesetting/tex/texlive/default.nix#L1"

     

       733
       733
       +
             >the

     

       734
       734
       +
            source</link>. Beware of

     

       735
       735
       +
            <link xlink:href="https://github.com/NixOS/nixpkgs/issues/9757"

     

       736
       736
       +
             >an

     

       737
       737
       +
            issue</link> when installing a too large package set. The plan is to

     

       738
       738
       +
            deprecate and maybe delete the original TeX packages until the next

     

       739
       739
       +
            release.

     

       623
       740
        
           </para>

     

       624
       741
        
          </listitem>

     

       625
       742
        
          <listitem>

     

       626
       743
        
           <para>

     

       627
       627
       -
            <option>buildEnv.env</option> on all Python interpreters is now available for nix-shell interoperability.

     

       744
       744
       +
            <option>buildEnv.env</option> on all Python interpreters is now available

     

       745
       745
       +
            for nix-shell interoperability.

     

       628
       746
        
           </para>

     

       629
       747
        
          </listitem>

     

       630
       748
        
         </itemizedlist>

+164 -41

nixos/doc/manual/release-notes/rl-1603.xml

···

       6
       6
        
        <title>Release 16.03 (“Emu”, 2016/03/31)</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         In addition to numerous new and upgraded packages, this release has the following highlights:

     

       9
       9
       +
         In addition to numerous new and upgraded packages, this release has the

     

       10
       10
       +
         following highlights:

     

       10
       11
        
        </para>

     

       11
       12
        
       

     

       12
       13
        
        <itemizedlist>

     

       13
       14
        
         <listitem>

     

       14
       15
        
          <para>

     

       15
       15
       -
           Systemd 229, bringing <link

     

       16
       16
       -
           xlink:href="https://github.com/systemd/systemd/blob/v229/NEWS">numerous improvements</link> over 217.

     

       16
       16
       +
           Systemd 229, bringing

     

       17
       17
       +
           <link

     

       18
       18
       +
           xlink:href="https://github.com/systemd/systemd/blob/v229/NEWS">numerous

     

       19
       19
       +
           improvements</link> over 217.

     

       17
       20
        
          </para>

     

       18
       21
        
         </listitem>

     

       19
       22
        
         <listitem>

     
···

       23
       26
        
         </listitem>

     

       24
       27
        
         <listitem>

     

       25
       28
        
          <para>

     

       26
       26
       -
           GCC 5.3 (was 4.9). Note that GCC 5 <link

     

       27
       27
       -
           xlink:href="https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html">changes the C++ ABI in an incompatible way</link>; this may cause problems if you try to link objects compiled with different versions of GCC.

     

       29
       29
       +
           GCC 5.3 (was 4.9). Note that GCC 5

     

       30
       30
       +
           <link

     

       31
       31
       +
           xlink:href="https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html">changes

     

       32
       32
       +
           the C++ ABI in an incompatible way</link>; this may cause problems if you

     

       33
       33
       +
           try to link objects compiled with different versions of GCC.

     

       28
       34
        
          </para>

     

       29
       35
        
         </listitem>

     

       30
       36
        
         <listitem>

     
···

       39
       45
        
         </listitem>

     

       40
       46
        
         <listitem>

     

       41
       47
        
          <para>

     

       42
       42
       -
           Improved support for ensuring <link

     

       43
       43
       -
           xlink:href="https://reproducible-builds.org/">bitwise reproducible builds</link>. For example, <literal>stdenv</literal> now sets the environment variable <envar

     

       44
       44
       -
           xlink:href="https://reproducible-builds.org/specs/source-date-epoch/">SOURCE_DATE_EPOCH</envar> to a deterministic value, and Nix has <link

     

       45
       45
       -
           xlink:href="http://nixos.org/nix/manual/#ssec-relnotes-1.11">gained an option</link> to repeat a build a number of times to test determinism. An ongoing project, the goal of exact reproducibility is to allow binaries to be verified independently (e.g., a user might only trust binaries that appear in three independent binary caches).

     

       48
       48
       +
           Improved support for ensuring

     

       49
       49
       +
           <link

     

       50
       50
       +
           xlink:href="https://reproducible-builds.org/">bitwise

     

       51
       51
       +
           reproducible builds</link>. For example, <literal>stdenv</literal> now sets

     

       52
       52
       +
           the environment variable

     

       53
       53
       +
           <envar

     

       54
       54
       +
           xlink:href="https://reproducible-builds.org/specs/source-date-epoch/">SOURCE_DATE_EPOCH</envar>

     

       55
       55
       +
           to a deterministic value, and Nix has

     

       56
       56
       +
           <link

     

       57
       57
       +
           xlink:href="http://nixos.org/nix/manual/#ssec-relnotes-1.11">gained

     

       58
       58
       +
           an option</link> to repeat a build a number of times to test determinism.

     

       59
       59
       +
           An ongoing project, the goal of exact reproducibility is to allow binaries

     

       60
       60
       +
           to be verified independently (e.g., a user might only trust binaries that

     

       61
       61
       +
           appear in three independent binary caches).

     

       46
       62
        
          </para>

     

       47
       63
        
         </listitem>

     

       48
       64
        
         <listitem>

     
···

       319
       335
        
        </para>

     

       320
       336
        
       

     

       321
       337
        
        <para>

     

       322
       322
       -
         When upgrading from a previous release, please be aware of the following incompatible changes:

     

       338
       338
       +
         When upgrading from a previous release, please be aware of the following

     

       339
       339
       +
         incompatible changes:

     

       323
       340
        
        </para>

     

       324
       341
        
       

     

       325
       342
        
        <itemizedlist>

     

       326
       343
        
         <listitem>

     

       327
       344
        
          <para>

     

       328
       328
       -
           We no longer produce graphical ISO images and VirtualBox images for <literal>i686-linux</literal>. A minimal ISO image is still provided.

     

       345
       345
       +
           We no longer produce graphical ISO images and VirtualBox images for

     

       346
       346
       +
           <literal>i686-linux</literal>. A minimal ISO image is still provided.

     

       329
       347
        
          </para>

     

       330
       348
        
         </listitem>

     

       331
       349
        
         <listitem>

     

       332
       350
        
          <para>

     

       333
       333
       -
           Firefox and similar browsers are now <emphasis>wrapped by default</emphasis>. The package and attribute names are plain <literal>firefox</literal> or <literal>midori</literal>, etc. Backward-compatibility attributes were set up, but note that <command>nix-env -u</command> will <emphasis>not</emphasis> update your current <literal>firefox-with-plugins</literal>; you have to uninstall it and install <literal>firefox</literal> instead.

     

       351
       351
       +
           Firefox and similar browsers are now <emphasis>wrapped by

     

       352
       352
       +
           default</emphasis>. The package and attribute names are plain

     

       353
       353
       +
           <literal>firefox</literal> or <literal>midori</literal>, etc.

     

       354
       354
       +
           Backward-compatibility attributes were set up, but note that

     

       355
       355
       +
           <command>nix-env -u</command> will <emphasis>not</emphasis> update your

     

       356
       356
       +
           current <literal>firefox-with-plugins</literal>; you have to uninstall it

     

       357
       357
       +
           and install <literal>firefox</literal> instead.

     

       334
       358
        
          </para>

     

       335
       359
        
         </listitem>

     

       336
       360
        
         <listitem>

     

       337
       361
        
          <para>

     

       338
       338
       -
           <command>wmiiSnap</command> has been replaced with <command>wmii_hg</command>, but <command>services.xserver.windowManager.wmii.enable</command> has been updated respectively so this only affects you if you have explicitly installed <command>wmiiSnap</command>.

     

       362
       362
       +
           <command>wmiiSnap</command> has been replaced with

     

       363
       363
       +
           <command>wmii_hg</command>, but

     

       364
       364
       +
           <command>services.xserver.windowManager.wmii.enable</command> has been

     

       365
       365
       +
           updated respectively so this only affects you if you have explicitly

     

       366
       366
       +
           installed <command>wmiiSnap</command>.

     

       339
       367
        
          </para>

     

       340
       368
        
         </listitem>

     

       341
       369
        
         <listitem>

     

       342
       370
        
          <para>

     

       343
       343
       -
           <literal>jobs</literal> NixOS option has been removed. It served as compatibility layer between Upstart jobs and SystemD services. All services have been rewritten to use <literal>systemd.services</literal>

     

       371
       371
       +
           <literal>jobs</literal> NixOS option has been removed. It served as

     

       372
       372
       +
           compatibility layer between Upstart jobs and SystemD services. All services

     

       373
       373
       +
           have been rewritten to use <literal>systemd.services</literal>

     

       344
       374
        
          </para>

     

       345
       375
        
         </listitem>

     

       346
       376
        
         <listitem>

     

       347
       377
        
          <para>

     

       348
       348
       -
           <command>wmiimenu</command> is removed, as it has been removed by the developers upstream. Use <command>wimenu</command> from the <command>wmii-hg</command> package.

     

       378
       378
       +
           <command>wmiimenu</command> is removed, as it has been removed by the

     

       379
       379
       +
           developers upstream. Use <command>wimenu</command> from the

     

       380
       380
       +
           <command>wmii-hg</command> package.

     

       349
       381
        
          </para>

     

       350
       382
        
         </listitem>

     

       351
       383
        
         <listitem>

     

       352
       384
        
          <para>

     

       353
       353
       -
           Gitit is no longer automatically added to the module list in NixOS and as such there will not be any manual entries for it. You will need to add an import statement to your NixOS configuration in order to use it, e.g.

     

       385
       385
       +
           Gitit is no longer automatically added to the module list in NixOS and as

     

       386
       386
       +
           such there will not be any manual entries for it. You will need to add an

     

       387
       387
       +
           import statement to your NixOS configuration in order to use it, e.g.

     

       354
       388
        
       <programlisting><![CDATA[

     

       355
       389
        
       {

     

       356
       390
        
         imports = [ <nixpkgs/nixos/modules/services/misc/gitit.nix> ];

     
···

       361
       395
        
         </listitem>

     

       362
       396
        
         <listitem>

     

       363
       397
        
          <para>

     

       364
       364
       -
           <command>nginx</command> does not accept flags for enabling and disabling modules anymore. Instead it accepts <literal>modules</literal> argument, which is a list of modules to be built in. All modules now reside in <literal>nginxModules</literal> set. Example configuration:

     

       398
       398
       +
           <command>nginx</command> does not accept flags for enabling and disabling

     

       399
       399
       +
           modules anymore. Instead it accepts <literal>modules</literal> argument,

     

       400
       400
       +
           which is a list of modules to be built in. All modules now reside in

     

       401
       401
       +
           <literal>nginxModules</literal> set. Example configuration:

     

       365
       402
        
       <programlisting><![CDATA[

     

       366
       403
        
       nginx.override {

     

       367
       404
        
         modules = [ nginxModules.rtmp nginxModules.dav nginxModules.moreheaders ];

     
···

       371
       408
        
         </listitem>

     

       372
       409
        
         <listitem>

     

       373
       410
        
          <para>

     

       374
       374
       -
           <command>s3sync</command> is removed, as it hasn't been developed by upstream for 4 years and only runs with ruby 1.8. For an actively-developer alternative look at <command>tarsnap</command> and others.

     

       411
       411
       +
           <command>s3sync</command> is removed, as it hasn't been developed by

     

       412
       412
       +
           upstream for 4 years and only runs with ruby 1.8. For an actively-developer

     

       413
       413
       +
           alternative look at <command>tarsnap</command> and others.

     

       375
       414
        
          </para>

     

       376
       415
        
         </listitem>

     

       377
       416
        
         <listitem>

     

       378
       417
        
          <para>

     

       379
       379
       -
           <command>ruby_1_8</command> has been removed as it's not supported from upstream anymore and probably contains security issues.

     

       418
       418
       +
           <command>ruby_1_8</command> has been removed as it's not supported from

     

       419
       419
       +
           upstream anymore and probably contains security issues.

     

       380
       420
        
          </para>

     

       381
       421
        
         </listitem>

     

       382
       422
        
         <listitem>

     

       383
       423
        
          <para>

     

       384
       384
       -
           <literal>tidy-html5</literal> package is removed. Upstream only provided <literal>(lib)tidy5</literal> during development, and now they went back to <literal>(lib)tidy</literal> to work as a drop-in replacement of the original package that has been unmaintained for years. You can (still) use the <literal>html-tidy</literal> package, which got updated to a stable release from this new upstream.

     

       424
       424
       +
           <literal>tidy-html5</literal> package is removed. Upstream only provided

     

       425
       425
       +
           <literal>(lib)tidy5</literal> during development, and now they went back to

     

       426
       426
       +
           <literal>(lib)tidy</literal> to work as a drop-in replacement of the

     

       427
       427
       +
           original package that has been unmaintained for years. You can (still) use

     

       428
       428
       +
           the <literal>html-tidy</literal> package, which got updated to a stable

     

       429
       429
       +
           release from this new upstream.

     

       385
       430
        
          </para>

     

       386
       431
        
         </listitem>

     

       387
       432
        
         <listitem>

     

       388
       433
        
          <para>

     

       389
       389
       -
           <literal>extraDeviceOptions</literal> argument is removed from <literal>bumblebee</literal> package. Instead there are now two separate arguments: <literal>extraNvidiaDeviceOptions</literal> and <literal>extraNouveauDeviceOptions</literal> for setting extra X11 options for nvidia and nouveau drivers, respectively.

     

       434
       434
       +
           <literal>extraDeviceOptions</literal> argument is removed from

     

       435
       435
       +
           <literal>bumblebee</literal> package. Instead there are now two separate

     

       436
       436
       +
           arguments: <literal>extraNvidiaDeviceOptions</literal> and

     

       437
       437
       +
           <literal>extraNouveauDeviceOptions</literal> for setting extra X11 options

     

       438
       438
       +
           for nvidia and nouveau drivers, respectively.

     

       390
       439
        
          </para>

     

       391
       440
        
         </listitem>

     

       392
       441
        
         <listitem>

     

       393
       442
        
          <para>

     

       394
       394
       -
           The <literal>Ctrl+Alt+Backspace</literal> key combination no longer kills the X server by default. There's a new option <option>services.xserver.enableCtrlAltBackspace</option> allowing to enable the combination again.

     

       443
       443
       +
           The <literal>Ctrl+Alt+Backspace</literal> key combination no longer kills

     

       444
       444
       +
           the X server by default. There's a new option

     

       445
       445
       +
           <option>services.xserver.enableCtrlAltBackspace</option> allowing to enable

     

       446
       446
       +
           the combination again.

     

       395
       447
        
          </para>

     

       396
       448
        
         </listitem>

     

       397
       449
        
         <listitem>

     

       398
       450
        
          <para>

     

       399
       399
       -
           <literal>emacsPackagesNg</literal> now contains all packages from the ELPA, MELPA, and MELPA Stable repositories.

     

       451
       451
       +
           <literal>emacsPackagesNg</literal> now contains all packages from the ELPA,

     

       452
       452
       +
           MELPA, and MELPA Stable repositories.

     

       400
       453
        
          </para>

     

       401
       454
        
         </listitem>

     

       402
       455
        
         <listitem>

     

       403
       456
        
          <para>

     

       404
       404
       -
           Data directory for Postfix MTA server is moved from <filename>/var/postfix</filename> to <filename>/var/lib/postfix</filename>. Old configurations are migrated automatically. <literal>service.postfix</literal> module has also received many improvements, such as correct directories' access rights, new <literal>aliasFiles</literal> and <literal>mapFiles</literal> options and more.

     

       457
       457
       +
           Data directory for Postfix MTA server is moved from

     

       458
       458
       +
           <filename>/var/postfix</filename> to <filename>/var/lib/postfix</filename>.

     

       459
       459
       +
           Old configurations are migrated automatically.

     

       460
       460
       +
           <literal>service.postfix</literal> module has also received many

     

       461
       461
       +
           improvements, such as correct directories' access rights, new

     

       462
       462
       +
           <literal>aliasFiles</literal> and <literal>mapFiles</literal> options and

     

       463
       463
       +
           more.

     

       405
       464
        
          </para>

     

       406
       465
        
         </listitem>

     

       407
       466
        
         <listitem>

     

       408
       467
        
          <para>

     

       409
       409
       -
           Filesystem options should now be configured as a list of strings, not a comma-separated string. The old style will continue to work, but print a warning, until the 16.09 release. An example of the new style:

     

       468
       468
       +
           Filesystem options should now be configured as a list of strings, not a

     

       469
       469
       +
           comma-separated string. The old style will continue to work, but print a

     

       470
       470
       +
           warning, until the 16.09 release. An example of the new style:

     

       410
       471
        
       <programlisting>

     

       411
       472
        
       fileSystems."/example" = {

     

       412
       473
        
         device = "/dev/sdc";

     
···

       418
       479
        
         </listitem>

     

       419
       480
        
         <listitem>

     

       420
       481
        
          <para>

     

       421
       421
       -
           CUPS, installed by <literal>services.printing</literal> module, now has its data directory in <filename>/var/lib/cups</filename>. Old configurations from <filename>/etc/cups</filename> are moved there automatically, but there might be problems. Also configuration options <literal>services.printing.cupsdConf</literal> and <literal>services.printing.cupsdFilesConf</literal> were removed because they had been allowing one to override configuration variables required for CUPS to work at all on NixOS. For most use cases, <literal>services.printing.extraConf</literal> and new option <literal>services.printing.extraFilesConf</literal> should be enough; if you encounter a situation when they are not, please file a bug.

     

       482
       482
       +
           CUPS, installed by <literal>services.printing</literal> module, now has its

     

       483
       483
       +
           data directory in <filename>/var/lib/cups</filename>. Old configurations

     

       484
       484
       +
           from <filename>/etc/cups</filename> are moved there automatically, but

     

       485
       485
       +
           there might be problems. Also configuration options

     

       486
       486
       +
           <literal>services.printing.cupsdConf</literal> and

     

       487
       487
       +
           <literal>services.printing.cupsdFilesConf</literal> were removed because

     

       488
       488
       +
           they had been allowing one to override configuration variables required for

     

       489
       489
       +
           CUPS to work at all on NixOS. For most use cases,

     

       490
       490
       +
           <literal>services.printing.extraConf</literal> and new option

     

       491
       491
       +
           <literal>services.printing.extraFilesConf</literal> should be enough; if

     

       492
       492
       +
           you encounter a situation when they are not, please file a bug.

     

       422
       493
        
          </para>

     

       423
       494
        
          <para>

     

       424
       424
       -
           There are also Gutenprint improvements; in particular, a new option <literal>services.printing.gutenprint</literal> is added to enable automatic updating of Gutenprint PPMs; it's greatly recommended to enable it instead of adding <literal>gutenprint</literal> to the <literal>drivers</literal> list.

     

       495
       495
       +
           There are also Gutenprint improvements; in particular, a new option

     

       496
       496
       +
           <literal>services.printing.gutenprint</literal> is added to enable

     

       497
       497
       +
           automatic updating of Gutenprint PPMs; it's greatly recommended to enable

     

       498
       498
       +
           it instead of adding <literal>gutenprint</literal> to the

     

       499
       499
       +
           <literal>drivers</literal> list.

     

       425
       500
        
          </para>

     

       426
       501
        
         </listitem>

     

       427
       502
        
         <listitem>

     

       428
       503
        
          <para>

     

       429
       429
       -
           <literal>services.xserver.vaapiDrivers</literal> has been removed. Use <literal>hardware.opengl.extraPackages{,32}</literal> instead. You can also specify VDPAU drivers there.

     

       504
       504
       +
           <literal>services.xserver.vaapiDrivers</literal> has been removed. Use

     

       505
       505
       +
           <literal>hardware.opengl.extraPackages{,32}</literal> instead. You can also

     

       506
       506
       +
           specify VDPAU drivers there.

     

       430
       507
        
          </para>

     

       431
       508
        
         </listitem>

     

       432
       509
        
         <listitem>

     

       433
       510
        
          <para>

     

       434
       434
       -
           <literal>programs.ibus</literal> moved to <literal>i18n.inputMethod.ibus</literal>. The option <literal>programs.ibus.plugins</literal> changed to <literal>i18n.inputMethod.ibus.engines</literal> and the option to enable ibus changed from <literal>programs.ibus.enable</literal> to <literal>i18n.inputMethod.enabled</literal>. <literal>i18n.inputMethod.enabled</literal> should be set to the used input method name, <literal>"ibus"</literal> for ibus. An example of the new style:

     

       511
       511
       +
           <literal>programs.ibus</literal> moved to

     

       512
       512
       +
           <literal>i18n.inputMethod.ibus</literal>. The option

     

       513
       513
       +
           <literal>programs.ibus.plugins</literal> changed to

     

       514
       514
       +
           <literal>i18n.inputMethod.ibus.engines</literal> and the option to enable

     

       515
       515
       +
           ibus changed from <literal>programs.ibus.enable</literal> to

     

       516
       516
       +
           <literal>i18n.inputMethod.enabled</literal>.

     

       517
       517
       +
           <literal>i18n.inputMethod.enabled</literal> should be set to the used input

     

       518
       518
       +
           method name, <literal>"ibus"</literal> for ibus. An example of the new

     

       519
       519
       +
           style:

     

       435
       520
        
       <programlisting>

     

       436
       521
        
       i18n.inputMethod.enabled = "ibus";

     

       437
       522
        
       i18n.inputMethod.ibus.engines = with pkgs.ibus-engines; [ anthy mozc ];

     
···

       445
       530
        
         </listitem>

     

       446
       531
        
         <listitem>

     

       447
       532
        
          <para>

     

       448
       448
       -
           <literal>services.udev.extraRules</literal> option now writes rules to <filename>99-local.rules</filename> instead of <filename>10-local.rules</filename>. This makes all the user rules apply after others, so their results wouldn't be overriden by anything else.

     

       533
       533
       +
           <literal>services.udev.extraRules</literal> option now writes rules to

     

       534
       534
       +
           <filename>99-local.rules</filename> instead of

     

       535
       535
       +
           <filename>10-local.rules</filename>. This makes all the user rules apply

     

       536
       536
       +
           after others, so their results wouldn't be overriden by anything else.

     

       449
       537
        
          </para>

     

       450
       538
        
         </listitem>

     

       451
       539
        
         <listitem>

     

       452
       540
        
          <para>

     

       453
       453
       -
           Large parts of the <literal>services.gitlab</literal> module has been been rewritten. There are new configuration options available. The <literal>stateDir</literal> option was renamned to <literal>statePath</literal> and the <literal>satellitesDir</literal> option was removed. Please review the currently available options.

     

       541
       541
       +
           Large parts of the <literal>services.gitlab</literal> module has been been

     

       542
       542
       +
           rewritten. There are new configuration options available. The

     

       543
       543
       +
           <literal>stateDir</literal> option was renamned to

     

       544
       544
       +
           <literal>statePath</literal> and the <literal>satellitesDir</literal>

     

       545
       545
       +
           option was removed. Please review the currently available options.

     

       454
       546
        
          </para>

     

       455
       547
        
         </listitem>

     

       456
       548
        
         <listitem>

     

       457
       549
        
          <para>

     

       458
       458
       -
           The option <option>services.nsd.zones.&lt;name&gt;.data</option> no longer interpret the dollar sign ($) as a shell variable, as such it should not be escaped anymore. Thus the following zone data:

     

       550
       550
       +
           The option <option>services.nsd.zones.&lt;name&gt;.data</option> no longer

     

       551
       551
       +
           interpret the dollar sign ($) as a shell variable, as such it should not be

     

       552
       552
       +
           escaped anymore. Thus the following zone data:

     

       459
       553
        
          </para>

     

       460
       554
        
       <programlisting>

     

       461
       555
        
       \$ORIGIN example.com.

     
···

       473
       567
        
         </listitem>

     

       474
       568
        
         <listitem>

     

       475
       569
        
          <para>

     

       476
       476
       -
           <literal>service.syncthing.dataDir</literal> options now has to point to exact folder where syncthing is writing to. Example configuration should look something like:

     

       570
       570
       +
           <literal>service.syncthing.dataDir</literal> options now has to point to

     

       571
       571
       +
           exact folder where syncthing is writing to. Example configuration should

     

       572
       572
       +
           look something like:

     

       477
       573
        
          </para>

     

       478
       574
        
       <programlisting>

     

       479
       575
        
       services.syncthing = {

     
···

       485
       581
        
         </listitem>

     

       486
       582
        
         <listitem>

     

       487
       583
        
          <para>

     

       488
       488
       -
           <literal>networking.firewall.allowPing</literal> is now enabled by default. Users are encouraged to configure an appropriate rate limit for their machines using the Kernel interface at <filename>/proc/sys/net/ipv4/icmp_ratelimit</filename> and <filename>/proc/sys/net/ipv6/icmp/ratelimit</filename> or using the firewall itself, i.e. by setting the NixOS option <literal>networking.firewall.pingLimit</literal>.

     

       584
       584
       +
           <literal>networking.firewall.allowPing</literal> is now enabled by default.

     

       585
       585
       +
           Users are encouraged to configure an appropriate rate limit for their

     

       586
       586
       +
           machines using the Kernel interface at

     

       587
       587
       +
           <filename>/proc/sys/net/ipv4/icmp_ratelimit</filename> and

     

       588
       588
       +
           <filename>/proc/sys/net/ipv6/icmp/ratelimit</filename> or using the

     

       589
       589
       +
           firewall itself, i.e. by setting the NixOS option

     

       590
       590
       +
           <literal>networking.firewall.pingLimit</literal>.

     

       489
       591
        
          </para>

     

       490
       592
        
         </listitem>

     

       491
       593
        
         <listitem>

     

       492
       594
        
          <para>

     

       493
       493
       -
           Systems with some broadcom cards used to result into a generated config that is no longer accepted. If you get errors like

     

       595
       595
       +
           Systems with some broadcom cards used to result into a generated config

     

       596
       596
       +
           that is no longer accepted. If you get errors like

     

       494
       597
        
       <screen>error: path ‘/nix/store/*-broadcom-sta-*’ does not exist and cannot be created</screen>

     

       495
       495
       -
           you should either re-run <command>nixos-generate-config</command> or manually replace <literal>"${config.boot.kernelPackages.broadcom_sta}"</literal> by <literal>config.boot.kernelPackages.broadcom_sta</literal> in your <filename>/etc/nixos/hardware-configuration.nix</filename>. More discussion is on <link xlink:href="https://github.com/NixOS/nixpkgs/pull/12595"> the github issue</link>.

     

       598
       598
       +
           you should either re-run <command>nixos-generate-config</command> or

     

       599
       599
       +
           manually replace

     

       600
       600
       +
           <literal>"${config.boot.kernelPackages.broadcom_sta}"</literal> by

     

       601
       601
       +
           <literal>config.boot.kernelPackages.broadcom_sta</literal> in your

     

       602
       602
       +
           <filename>/etc/nixos/hardware-configuration.nix</filename>. More discussion

     

       603
       603
       +
           is on <link xlink:href="https://github.com/NixOS/nixpkgs/pull/12595"> the

     

       604
       604
       +
           github issue</link>.

     

       496
       605
        
          </para>

     

       497
       606
        
         </listitem>

     

       498
       607
        
         <listitem>

     

       499
       608
        
          <para>

     

       500
       500
       -
           The <literal>services.xserver.startGnuPGAgent</literal> option has been removed. GnuPG 2.1.x changed the way the gpg-agent works, and that new approach no longer requires (or even supports) the "start everything as a child of the agent" scheme we've implemented in NixOS for older versions. To configure the gpg-agent for your X session, add the following code to <filename>~/.bashrc</filename> or some file that’s sourced when your shell is started:

     

       609
       609
       +
           The <literal>services.xserver.startGnuPGAgent</literal> option has been

     

       610
       610
       +
           removed. GnuPG 2.1.x changed the way the gpg-agent works, and that new

     

       611
       611
       +
           approach no longer requires (or even supports) the "start everything as a

     

       612
       612
       +
           child of the agent" scheme we've implemented in NixOS for older versions.

     

       613
       613
       +
           To configure the gpg-agent for your X session, add the following code to

     

       614
       614
       +
           <filename>~/.bashrc</filename> or some file that’s sourced when your

     

       615
       615
       +
           shell is started:

     

       501
       616
        
       <programlisting>

     

       502
       617
        
       GPG_TTY=$(tty)

     

       503
       618
        
       export GPG_TTY

     

       504
       619
        
           </programlisting>

     

       505
       505
       -
           If you want to use gpg-agent for SSH, too, add the following to your session initialization (e.g. <literal>displayManager.sessionCommands</literal>)

     

       620
       620
       +
           If you want to use gpg-agent for SSH, too, add the following to your

     

       621
       621
       +
           session initialization (e.g.

     

       622
       622
       +
           <literal>displayManager.sessionCommands</literal>)

     

       506
       623
        
       <programlisting>

     

       507
       624
        
       gpg-connect-agent /bye

     

       508
       625
        
       unset SSH_AGENT_PID

     
···

       512
       629
        
       <programlisting>

     

       513
       630
        
       enable-ssh-support

     

       514
       631
        
           </programlisting>

     

       515
       515
       -
           is included in your <filename>~/.gnupg/gpg-agent.conf</filename>. You will need to use <command>ssh-add</command> to re-add your ssh keys. If gpg’s automatic transformation of the private keys to the new format fails, you will need to re-import your private keyring as well:

     

       632
       632
       +
           is included in your <filename>~/.gnupg/gpg-agent.conf</filename>. You will

     

       633
       633
       +
           need to use <command>ssh-add</command> to re-add your ssh keys. If gpg’s

     

       634
       634
       +
           automatic transformation of the private keys to the new format fails, you

     

       635
       635
       +
           will need to re-import your private keyring as well:

     

       516
       636
        
       <programlisting>

     

       517
       637
        
       gpg --import ~/.gnupg/secring.gpg

     

       518
       638
        
           </programlisting>

     

       519
       519
       -
           The <command>gpg-agent(1)</command> man page has more details about this subject, i.e. in the "EXAMPLES" section.

     

       639
       639
       +
           The <command>gpg-agent(1)</command> man page has more details about this

     

       640
       640
       +
           subject, i.e. in the "EXAMPLES" section.

     

       520
       641
        
          </para>

     

       521
       642
        
         </listitem>

     

       522
       643
        
        </itemizedlist>

     
···

       540
       661
        
          </listitem>

     

       541
       662
        
          <listitem>

     

       542
       663
        
           <para>

     

       543
       543
       -
            Input method support was improved. New NixOS modules (fcitx, nabi and uim), fcitx engines (chewing, hangul, m17n, mozc and table-other) and ibus engines (hangul and m17n) have been added.

     

       664
       664
       +
            Input method support was improved. New NixOS modules (fcitx, nabi and

     

       665
       665
       +
            uim), fcitx engines (chewing, hangul, m17n, mozc and table-other) and ibus

     

       666
       666
       +
            engines (hangul and m17n) have been added.

     

       544
       667
        
           </para>

     

       545
       668
        
          </listitem>

     

       546
       669
        
         </itemizedlist>

+126 -35

nixos/doc/manual/release-notes/rl-1609.xml

···

       6
       6
        
        <title>Release 16.09 (“Flounder”, 2016/09/30)</title>

     

       7
       7
        
       

     

       8
       8
        
        <para>

     

       9
       9
       -
         In addition to numerous new and upgraded packages, this release has the following highlights:

     

       9
       9
       +
         In addition to numerous new and upgraded packages, this release has the

     

       10
       10
       +
         following highlights:

     

       10
       11
        
        </para>

     

       11
       12
        
       

     

       12
       13
        
        <itemizedlist>

     

       13
       14
        
         <listitem>

     

       14
       15
        
          <para>

     

       15
       15
       -
           Many NixOS configurations and Nix packages now use significantly less disk space, thanks to the <link

     

       16
       16
       -
           xlink:href="https://github.com/NixOS/nixpkgs/issues/7117">extensive work on closure size reduction</link>. For example, the closure size of a minimal NixOS container went down from ~424 MiB in 16.03 to ~212 MiB in 16.09, while the closure size of Firefox went from ~651 MiB to ~259 MiB.

     

       16
       16
       +
           Many NixOS configurations and Nix packages now use significantly less disk

     

       17
       17
       +
           space, thanks to the

     

       18
       18
       +
           <link

     

       19
       19
       +
           xlink:href="https://github.com/NixOS/nixpkgs/issues/7117">extensive

     

       20
       20
       +
           work on closure size reduction</link>. For example, the closure size of a

     

       21
       21
       +
           minimal NixOS container went down from ~424 MiB in 16.03 to ~212 MiB in

     

       22
       22
       +
           16.09, while the closure size of Firefox went from ~651 MiB to ~259 MiB.

     

       17
       23
        
          </para>

     

       18
       24
        
         </listitem>

     

       19
       25
        
         <listitem>

     

       20
       26
        
          <para>

     

       21
       21
       -
           To improve security, packages are now <link

     

       22
       22
       -
           xlink:href="https://github.com/NixOS/nixpkgs/pull/12895">built using various hardening features</link>. See the Nixpkgs manual for more information.

     

       27
       27
       +
           To improve security, packages are now

     

       28
       28
       +
           <link

     

       29
       29
       +
           xlink:href="https://github.com/NixOS/nixpkgs/pull/12895">built

     

       30
       30
       +
           using various hardening features</link>. See the Nixpkgs manual for more

     

       31
       31
       +
           information.

     

       23
       32
        
          </para>

     

       24
       33
        
         </listitem>

     

       25
       34
        
         <listitem>

     

       26
       35
        
          <para>

     

       27
       36
        
           Support for PXE netboot. See <xref

     

       28
       28
       -
           linkend="sec-booting-from-pxe" /> for documentation.

     

       37
       37
       +
           linkend="sec-booting-from-pxe" />

     

       38
       38
       +
           for documentation.

     

       29
       39
        
          </para>

     

       30
       40
        
         </listitem>

     

       31
       41
        
         <listitem>

     

       32
       42
        
          <para>

     

       33
       33
       -
           X.org server 1.18. If you use the <literal>ati_unfree</literal> driver, 1.17 is still used due to an ABI incompatibility.

     

       43
       43
       +
           X.org server 1.18. If you use the <literal>ati_unfree</literal> driver,

     

       44
       44
       +
           1.17 is still used due to an ABI incompatibility.

     

       34
       45
        
          </para>

     

       35
       46
        
         </listitem>

     

       36
       47
        
         <listitem>

     

       37
       48
        
          <para>

     

       38
       38
       -
           This release is based on Glibc 2.24, GCC 5.4.0 and systemd 231. The default Linux kernel remains 4.4.

     

       49
       49
       +
           This release is based on Glibc 2.24, GCC 5.4.0 and systemd 231. The default

     

       50
       50
       +
           Linux kernel remains 4.4.

     

       39
       51
        
          </para>

     

       40
       52
        
         </listitem>

     

       41
       53
        
        </itemizedlist>

     
···

       53
       65
        
        </itemizedlist>

     

       54
       66
        
       

     

       55
       67
        
        <para>

     

       56
       56
       -
         When upgrading from a previous release, please be aware of the following incompatible changes:

     

       68
       68
       +
         When upgrading from a previous release, please be aware of the following

     

       69
       69
       +
         incompatible changes:

     

       57
       70
        
        </para>

     

       58
       71
        
       

     

       59
       72
        
        <itemizedlist>

     

       60
       73
        
         <listitem>

     

       61
       74
        
          <para>

     

       62
       62
       -
           A large number of packages have been converted to use the multiple outputs feature of Nix to greatly reduce the amount of required disk space, as mentioned above. This may require changes to any custom packages to make them build again; see the relevant chapter in the Nixpkgs manual for more information. (Additional caveat to packagers: some packaging conventions related to multiple-output packages <link xlink:href="https://github.com/NixOS/nixpkgs/pull/14766">were changed</link> late (August 2016) in the release cycle and differ from the initial introduction of multiple outputs.)

     

       75
       75
       +
           A large number of packages have been converted to use the multiple outputs

     

       76
       76
       +
           feature of Nix to greatly reduce the amount of required disk space, as

     

       77
       77
       +
           mentioned above. This may require changes to any custom packages to make

     

       78
       78
       +
           them build again; see the relevant chapter in the Nixpkgs manual for more

     

       79
       79
       +
           information. (Additional caveat to packagers: some packaging conventions

     

       80
       80
       +
           related to multiple-output packages

     

       81
       81
       +
           <link xlink:href="https://github.com/NixOS/nixpkgs/pull/14766">were

     

       82
       82
       +
           changed</link> late (August 2016) in the release cycle and differ from the

     

       83
       83
       +
           initial introduction of multiple outputs.)

     

       63
       84
        
          </para>

     

       64
       85
        
         </listitem>

     

       65
       86
        
         <listitem>

     

       66
       87
        
          <para>

     

       67
       67
       -
           Previous versions of Nixpkgs had support for all versions of the LTS Haskell package set. That support has been dropped. The previously provided <literal>haskell.packages.lts-x_y</literal> package sets still exist in name to aviod breaking user code, but these package sets don't actually contain the versions mandated by the corresponding LTS release. Instead, our package set it loosely based on the latest available LTS release, i.e. LTS 7.x at the time of this writing. New releases of NixOS and Nixpkgs will drop those old names entirely. <link

     

       68
       68
       -
           xlink:href="https://nixos.org/nix-dev/2016-June/020585.html">The motivation for this change</link> has been discussed at length on the <literal>nix-dev</literal> mailing list and in <link

     

       69
       69
       -
           xlink:href="https://github.com/NixOS/nixpkgs/issues/14897">Github issue #14897</link>. Development strategies for Haskell hackers who want to rely on Nix and NixOS have been described in <link

     

       70
       70
       -
           xlink:href="https://nixos.org/nix-dev/2016-June/020642.html">another nix-dev article</link>.

     

       88
       88
       +
           Previous versions of Nixpkgs had support for all versions of the LTS

     

       89
       89
       +
           Haskell package set. That support has been dropped. The previously provided

     

       90
       90
       +
           <literal>haskell.packages.lts-x_y</literal> package sets still exist in

     

       91
       91
       +
           name to aviod breaking user code, but these package sets don't actually

     

       92
       92
       +
           contain the versions mandated by the corresponding LTS release. Instead,

     

       93
       93
       +
           our package set it loosely based on the latest available LTS release, i.e.

     

       94
       94
       +
           LTS 7.x at the time of this writing. New releases of NixOS and Nixpkgs will

     

       95
       95
       +
           drop those old names entirely.

     

       96
       96
       +
           <link

     

       97
       97
       +
           xlink:href="https://nixos.org/nix-dev/2016-June/020585.html">The

     

       98
       98
       +
           motivation for this change</link> has been discussed at length on the

     

       99
       99
       +
           <literal>nix-dev</literal> mailing list and in

     

       100
       100
       +
           <link

     

       101
       101
       +
           xlink:href="https://github.com/NixOS/nixpkgs/issues/14897">Github

     

       102
       102
       +
           issue #14897</link>. Development strategies for Haskell hackers who want to

     

       103
       103
       +
           rely on Nix and NixOS have been described in

     

       104
       104
       +
           <link

     

       105
       105
       +
           xlink:href="https://nixos.org/nix-dev/2016-June/020642.html">another

     

       106
       106
       +
           nix-dev article</link>.

     

       71
       107
        
          </para>

     

       72
       108
        
         </listitem>

     

       73
       109
        
         <listitem>

     

       74
       110
        
          <para>

     

       75
       75
       -
           Shell aliases for systemd sub-commands <link xlink:href="https://github.com/NixOS/nixpkgs/pull/15598">were dropped</link>: <command>start</command>, <command>stop</command>, <command>restart</command>, <command>status</command>.

     

       111
       111
       +
           Shell aliases for systemd sub-commands

     

       112
       112
       +
           <link xlink:href="https://github.com/NixOS/nixpkgs/pull/15598">were

     

       113
       113
       +
           dropped</link>: <command>start</command>, <command>stop</command>,

     

       114
       114
       +
           <command>restart</command>, <command>status</command>.

     

       76
       115
        
          </para>

     

       77
       116
        
         </listitem>

     

       78
       117
        
         <listitem>

     

       79
       118
        
          <para>

     

       80
       80
       -
           Redis now binds to 127.0.0.1 only instead of listening to all network interfaces. This is the default behavior of Redis 3.2

     

       119
       119
       +
           Redis now binds to 127.0.0.1 only instead of listening to all network

     

       120
       120
       +
           interfaces. This is the default behavior of Redis 3.2

     

       81
       121
        
          </para>

     

       82
       122
        
         </listitem>

     

       83
       123
        
         <listitem>

     

       84
       124
        
          <para>

     

       85
       85
       -
           <literal>/var/empty</literal> is now immutable. Activation script runs <command>chattr +i</command> to forbid any modifications inside the folder. See <link xlink:href="https://github.com/NixOS/nixpkgs/pull/18365"> the pull request</link> for what bugs this caused.

     

       125
       125
       +
           <literal>/var/empty</literal> is now immutable. Activation script runs

     

       126
       126
       +
           <command>chattr +i</command> to forbid any modifications inside the folder.

     

       127
       127
       +
           See <link xlink:href="https://github.com/NixOS/nixpkgs/pull/18365"> the

     

       128
       128
       +
           pull request</link> for what bugs this caused.

     

       86
       129
        
          </para>

     

       87
       130
        
         </listitem>

     

       88
       131
        
         <listitem>

     

       89
       132
        
          <para>

     

       90
       90
       -
           Gitlab's maintainance script <command>gitlab-runner</command> was removed and split up into the more clearer <command>gitlab-run</command> and <command>gitlab-rake</command> scripts, because <command>gitlab-runner</command> is a component of Gitlab CI.

     

       133
       133
       +
           Gitlab's maintainance script <command>gitlab-runner</command> was removed

     

       134
       134
       +
           and split up into the more clearer <command>gitlab-run</command> and

     

       135
       135
       +
           <command>gitlab-rake</command> scripts, because

     

       136
       136
       +
           <command>gitlab-runner</command> is a component of Gitlab CI.

     

       91
       137
        
          </para>

     

       92
       138
        
         </listitem>

     

       93
       139
        
         <listitem>

     

       94
       140
        
          <para>

     

       95
       95
       -
           <literal>services.xserver.libinput.accelProfile</literal> default changed from <literal>flat</literal> to <literal>adaptive</literal>, as per <link xlink:href="https://wayland.freedesktop.org/libinput/doc/latest/group__config.html#gad63796972347f318b180e322e35cee79"> official documentation</link>.

     

       141
       141
       +
           <literal>services.xserver.libinput.accelProfile</literal> default changed

     

       142
       142
       +
           from <literal>flat</literal> to <literal>adaptive</literal>, as per

     

       143
       143
       +
           <link xlink:href="https://wayland.freedesktop.org/libinput/doc/latest/group__config.html#gad63796972347f318b180e322e35cee79">

     

       144
       144
       +
           official documentation</link>.

     

       96
       145
        
          </para>

     

       97
       146
        
         </listitem>

     

       98
       147
        
         <listitem>

     

       99
       148
        
          <para>

     

       100
       100
       -
           <literal>fonts.fontconfig.ultimate.rendering</literal> was removed because our presets were obsolete for some time. New presets are hardcoded into FreeType; you can select a preset via <literal>fonts.fontconfig.ultimate.preset</literal>. You can customize those presets via ordinary environment variables, using <literal>environment.variables</literal>.

     

       149
       149
       +
           <literal>fonts.fontconfig.ultimate.rendering</literal> was removed because

     

       150
       150
       +
           our presets were obsolete for some time. New presets are hardcoded into

     

       151
       151
       +
           FreeType; you can select a preset via

     

       152
       152
       +
           <literal>fonts.fontconfig.ultimate.preset</literal>. You can customize

     

       153
       153
       +
           those presets via ordinary environment variables, using

     

       154
       154
       +
           <literal>environment.variables</literal>.

     

       101
       155
        
          </para>

     

       102
       156
        
         </listitem>

     

       103
       157
        
         <listitem>

     

       104
       158
        
          <para>

     

       105
       105
       -
           The <literal>audit</literal> service is no longer enabled by default. Use <literal>security.audit.enable = true</literal> to explicitly enable it.

     

       159
       159
       +
           The <literal>audit</literal> service is no longer enabled by default. Use

     

       160
       160
       +
           <literal>security.audit.enable = true</literal> to explicitly enable it.

     

       106
       161
        
          </para>

     

       107
       162
        
         </listitem>

     

       108
       163
        
         <listitem>

     

       109
       164
        
          <para>

     

       110
       110
       -
           <literal>pkgs.linuxPackages.virtualbox</literal> now contains only the kernel modules instead of the VirtualBox user space binaries. If you want to reference the user space binaries, you have to use the new <literal>pkgs.virtualbox</literal> instead.

     

       165
       165
       +
           <literal>pkgs.linuxPackages.virtualbox</literal> now contains only the

     

       166
       166
       +
           kernel modules instead of the VirtualBox user space binaries. If you want

     

       167
       167
       +
           to reference the user space binaries, you have to use the new

     

       168
       168
       +
           <literal>pkgs.virtualbox</literal> instead.

     

       111
       169
        
          </para>

     

       112
       170
        
         </listitem>

     

       113
       171
        
         <listitem>

     

       114
       172
        
          <para>

     

       115
       115
       -
           <literal>goPackages</literal> was replaced with separated Go applications in appropriate <literal>nixpkgs</literal> categories. Each Go package uses its own dependency set. There's also a new <literal>go2nix</literal> tool introduced to generate a Go package definition from its Go source automatically.

     

       173
       173
       +
           <literal>goPackages</literal> was replaced with separated Go applications

     

       174
       174
       +
           in appropriate <literal>nixpkgs</literal> categories. Each Go package uses

     

       175
       175
       +
           its own dependency set. There's also a new <literal>go2nix</literal> tool

     

       176
       176
       +
           introduced to generate a Go package definition from its Go source

     

       177
       177
       +
           automatically.

     

       116
       178
        
          </para>

     

       117
       179
        
         </listitem>

     

       118
       180
        
         <listitem>

     

       119
       181
        
          <para>

     

       120
       120
       -
           <literal>services.mongodb.extraConfig</literal> configuration format was changed to YAML.

     

       182
       182
       +
           <literal>services.mongodb.extraConfig</literal> configuration format was

     

       183
       183
       +
           changed to YAML.

     

       121
       184
        
          </para>

     

       122
       185
        
         </listitem>

     

       123
       186
        
         <listitem>

     
···

       134
       197
        
        <itemizedlist>

     

       135
       198
        
         <listitem>

     

       136
       199
        
          <para>

     

       137
       137
       -
           Revamped grsecurity/PaX support. There is now only a single general-purpose distribution kernel and the configuration interface has been streamlined. Desktop users should be able to simply set

     

       200
       200
       +
           Revamped grsecurity/PaX support. There is now only a single general-purpose

     

       201
       201
       +
           distribution kernel and the configuration interface has been streamlined.

     

       202
       202
       +
           Desktop users should be able to simply set

     

       138
       203
        
       <programlisting>security.grsecurity.enable = true</programlisting>

     

       139
       139
       -
           to get a reasonably secure system without having to sacrifice too much functionality.

     

       204
       204
       +
           to get a reasonably secure system without having to sacrifice too much

     

       205
       205
       +
           functionality.

     

       140
       206
        
          </para>

     

       141
       207
        
         </listitem>

     

       142
       208
        
         <listitem>

     

       143
       209
        
          <para>

     

       144
       144
       -
           Special filesystems, like <literal>/proc</literal>, <literal>/run</literal> and others, now have the same mount options as recommended by systemd and are unified across different places in NixOS. Mount options are updated during <command>nixos-rebuild switch</command> if possible. One benefit from this is improved security — most such filesystems are now mounted with <literal>noexec</literal>, <literal>nodev</literal> and/or <literal>nosuid</literal> options.

     

       210
       210
       +
           Special filesystems, like <literal>/proc</literal>, <literal>/run</literal>

     

       211
       211
       +
           and others, now have the same mount options as recommended by systemd and

     

       212
       212
       +
           are unified across different places in NixOS. Mount options are updated

     

       213
       213
       +
           during <command>nixos-rebuild switch</command> if possible. One benefit

     

       214
       214
       +
           from this is improved security — most such filesystems are now mounted

     

       215
       215
       +
           with <literal>noexec</literal>, <literal>nodev</literal> and/or

     

       216
       216
       +
           <literal>nosuid</literal> options.

     

       145
       217
        
          </para>

     

       146
       218
        
         </listitem>

     

       147
       219
        
         <listitem>

     

       148
       220
        
          <para>

     

       149
       149
       -
           The reverse path filter was interfering with DHCPv4 server operation in the past. An exception for DHCPv4 and a new option to log packets that were dropped due to the reverse path filter was added (<literal>networking.firewall.logReversePathDrops</literal>) for easier debugging.

     

       221
       221
       +
           The reverse path filter was interfering with DHCPv4 server operation in the

     

       222
       222
       +
           past. An exception for DHCPv4 and a new option to log packets that were

     

       223
       223
       +
           dropped due to the reverse path filter was added

     

       224
       224
       +
           (<literal>networking.firewall.logReversePathDrops</literal>) for easier

     

       225
       225
       +
           debugging.

     

       150
       226
        
          </para>

     

       151
       227
        
         </listitem>

     

       152
       228
        
         <listitem>

     

       153
       229
        
          <para>

     

       154
       154
       -
           Containers configuration within <literal>containers.&lt;name&gt;.config</literal> is <link

     

       155
       155
       -
         xlink:href="https://github.com/NixOS/nixpkgs/pull/17365">now properly typed and checked</link>. In particular, partial configurations are merged correctly.

     

       230
       230
       +
           Containers configuration within

     

       231
       231
       +
           <literal>containers.&lt;name&gt;.config</literal> is

     

       232
       232
       +
           <link

     

       233
       233
       +
         xlink:href="https://github.com/NixOS/nixpkgs/pull/17365">now

     

       234
       234
       +
           properly typed and checked</link>. In particular, partial configurations

     

       235
       235
       +
           are merged correctly.

     

       156
       236
        
          </para>

     

       157
       237
        
         </listitem>

     

       158
       238
        
         <listitem>

     

       159
       239
        
          <para>

     

       160
       160
       -
           The directory container setuid wrapper programs, <filename>/var/setuid-wrappers</filename>, <link

     

       161
       161
       -
           xlink:href="https://github.com/NixOS/nixpkgs/pull/18124">is now updated atomically to prevent failures if the switch to a new configuration is interrupted.</link>

     

       240
       240
       +
           The directory container setuid wrapper programs,

     

       241
       241
       +
           <filename>/var/setuid-wrappers</filename>,

     

       242
       242
       +
           <link

     

       243
       243
       +
           xlink:href="https://github.com/NixOS/nixpkgs/pull/18124">is now

     

       244
       244
       +
           updated atomically to prevent failures if the switch to a new configuration

     

       245
       245
       +
           is interrupted.</link>

     

       162
       246
        
          </para>

     

       163
       247
        
         </listitem>

     

       164
       248
        
         <listitem>

     

       165
       249
        
          <para>

     

       166
       166
       -
           <literal>services.xserver.startGnuPGAgent</literal> has been removed due to GnuPG 2.1.x bump. See <link

     

       167
       167
       -
               xlink:href="https://github.com/NixOS/nixpkgs/commit/5391882ebd781149e213e8817fba6ac3c503740c"> how to achieve similar behavior</link>. You might need to <literal>pkill gpg-agent</literal> after the upgrade to prevent a stale agent being in the way.

     

       250
       250
       +
           <literal>services.xserver.startGnuPGAgent</literal> has been removed due to

     

       251
       251
       +
           GnuPG 2.1.x bump. See

     

       252
       252
       +
           <link

     

       253
       253
       +
               xlink:href="https://github.com/NixOS/nixpkgs/commit/5391882ebd781149e213e8817fba6ac3c503740c">

     

       254
       254
       +
           how to achieve similar behavior</link>. You might need to <literal>pkill

     

       255
       255
       +
           gpg-agent</literal> after the upgrade to prevent a stale agent being in the

     

       256
       256
       +
           way.

     

       168
       257
        
          </para>

     

       169
       258
        
         </listitem>

     

       170
       259
        
         <listitem>

     

       171
       260
        
          <para>

     

       172
       172
       -
           <link xlink:href="https://github.com/NixOS/nixpkgs/commit/e561edc322d275c3687fec431935095cfc717147"> Declarative users could share the uid due to the bug in the script handling conflict resolution. </link>

     

       261
       261
       +
           <link xlink:href="https://github.com/NixOS/nixpkgs/commit/e561edc322d275c3687fec431935095cfc717147">

     

       262
       262
       +
           Declarative users could share the uid due to the bug in the script handling

     

       263
       263
       +
           conflict resolution. </link>

     

       173
       264
        
          </para>

     

       174
       265
        
         </listitem>

     

       175
       266
        
         <listitem>

+148 -45

nixos/doc/manual/release-notes/rl-1703.xml

···

       13
       13
        
         <title>Highlights</title>

     

       14
       14
        
       

     

       15
       15
        
         <para>

     

       16
       16
       -
          In addition to numerous new and upgraded packages, this release has the following highlights:

     

       16
       16
       +
          In addition to numerous new and upgraded packages, this release has the

     

       17
       17
       +
          following highlights:

     

       17
       18
        
         </para>

     

       18
       19
        
       

     

       19
       20
        
         <itemizedlist>

     

       20
       21
        
          <listitem>

     

       21
       22
        
           <para>

     

       22
       22
       -
            Nixpkgs is now extensible through overlays. See the <link

     

       23
       23
       -
           xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install">Nixpkgs manual</link> for more information.

     

       23
       23
       +
            Nixpkgs is now extensible through overlays. See the

     

       24
       24
       +
            <link

     

       25
       25
       +
           xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install">Nixpkgs

     

       26
       26
       +
            manual</link> for more information.

     

       24
       27
        
           </para>

     

       25
       28
        
          </listitem>

     

       26
       29
        
          <listitem>

     

       27
       30
        
           <para>

     

       28
       28
       -
            This release is based on Glibc 2.25, GCC 5.4.0 and systemd 232. The default Linux kernel is 4.9 and Nix is at 1.11.8.

     

       31
       31
       +
            This release is based on Glibc 2.25, GCC 5.4.0 and systemd 232. The

     

       32
       32
       +
            default Linux kernel is 4.9 and Nix is at 1.11.8.

     

       29
       33
        
           </para>

     

       30
       34
        
          </listitem>

     

       31
       35
        
          <listitem>

     

       32
       36
        
           <para>

     

       33
       33
       -
            The default desktop environment now is KDE's Plasma 5. KDE 4 has been removed

     

       37
       37
       +
            The default desktop environment now is KDE's Plasma 5. KDE 4 has been

     

       38
       38
       +
            removed

     

       34
       39
        
           </para>

     

       35
       40
        
          </listitem>

     

       36
       41
        
          <listitem>

     
···

       40
       45
        
          </listitem>

     

       41
       46
        
          <listitem>

     

       42
       47
        
           <para>

     

       43
       43
       -
            X.org server uses branch 1.19. Due to ABI incompatibilities, <literal>ati_unfree</literal> keeps forcing 1.17 and <literal>amdgpu-pro</literal> starts forcing 1.18.

     

       48
       48
       +
            X.org server uses branch 1.19. Due to ABI incompatibilities,

     

       49
       49
       +
            <literal>ati_unfree</literal> keeps forcing 1.17 and

     

       50
       50
       +
            <literal>amdgpu-pro</literal> starts forcing 1.18.

     

       44
       51
        
           </para>

     

       45
       52
        
          </listitem>

     

       46
       53
        
          <listitem>

     

       47
       54
        
           <para>

     

       48
       48
       -
            Cross compilation has been rewritten. See the nixpkgs manual for details. The most obvious breaking change is that in derivations there is no <literal>.nativeDrv</literal> nor <literal>.crossDrv</literal> are now cross by default, not native.

     

       55
       55
       +
            Cross compilation has been rewritten. See the nixpkgs manual for details.

     

       56
       56
       +
            The most obvious breaking change is that in derivations there is no

     

       57
       57
       +
            <literal>.nativeDrv</literal> nor <literal>.crossDrv</literal> are now

     

       58
       58
       +
            cross by default, not native.

     

       49
       59
        
           </para>

     

       50
       60
        
          </listitem>

     

       51
       61
        
          <listitem>

     

       52
       62
        
           <para>

     

       53
       53
       -
            The <literal>overridePackages</literal> function has been rewritten to be replaced by <link

     

       54
       54
       -
           xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install"> overlays</link>

     

       63
       63
       +
            The <literal>overridePackages</literal> function has been rewritten to be

     

       64
       64
       +
            replaced by

     

       65
       65
       +
            <link

     

       66
       66
       +
           xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install">

     

       67
       67
       +
            overlays</link>

     

       55
       68
        
           </para>

     

       56
       69
        
          </listitem>

     

       57
       70
        
          <listitem>

     

       58
       71
        
           <para>

     

       59
       59
       -
            Packages in nixpkgs can be marked as insecure through listed vulnerabilities. See the <link

     

       60
       60
       -
           xlink:href="https://nixos.org/nixpkgs/manual/#sec-allow-insecure">Nixpkgs manual</link> for more information.

     

       72
       72
       +
            Packages in nixpkgs can be marked as insecure through listed

     

       73
       73
       +
            vulnerabilities. See the

     

       74
       74
       +
            <link

     

       75
       75
       +
           xlink:href="https://nixos.org/nixpkgs/manual/#sec-allow-insecure">Nixpkgs

     

       76
       76
       +
            manual</link> for more information.

     

       61
       77
        
           </para>

     

       62
       78
        
          </listitem>

     

       63
       79
        
          <listitem>

     
···

       496
       512
        
         <title>Backward Incompatibilities</title>

     

       497
       513
        
       

     

       498
       514
        
         <para>

     

       499
       499
       -
          When upgrading from a previous release, please be aware of the following incompatible changes:

     

       515
       515
       +
          When upgrading from a previous release, please be aware of the following

     

       516
       516
       +
          incompatible changes:

     

       500
       517
        
         </para>

     

       501
       518
        
       

     

       502
       519
        
         <itemizedlist>

     

       503
       520
        
          <listitem>

     

       504
       521
        
           <para>

     

       505
       505
       -
            Derivations have no <literal>.nativeDrv</literal> nor <literal>.crossDrv</literal> and are now cross by default, not native.

     

       522
       522
       +
            Derivations have no <literal>.nativeDrv</literal> nor

     

       523
       523
       +
            <literal>.crossDrv</literal> and are now cross by default, not native.

     

       506
       524
        
           </para>

     

       507
       525
        
          </listitem>

     

       508
       526
        
          <listitem>

     

       509
       527
        
           <para>

     

       510
       510
       -
            <literal>stdenv.overrides</literal> is now expected to take <literal>self</literal> and <literal>super</literal> arguments. See <literal>lib.trivial.extends</literal> for what those parameters represent.

     

       528
       528
       +
            <literal>stdenv.overrides</literal> is now expected to take

     

       529
       529
       +
            <literal>self</literal> and <literal>super</literal> arguments. See

     

       530
       530
       +
            <literal>lib.trivial.extends</literal> for what those parameters

     

       531
       531
       +
            represent.

     

       511
       532
        
           </para>

     

       512
       533
        
          </listitem>

     

       513
       534
        
          <listitem>

     

       514
       535
        
           <para>

     

       515
       515
       -
            <literal>ansible</literal> now defaults to ansible version 2 as version 1 has been removed due to a serious <link

     

       516
       516
       -
             xlink:href="https://www.computest.nl/advisories/CT-2017-0109_Ansible.txt"> vulnerability</link> unpatched by upstream.

     

       536
       536
       +
            <literal>ansible</literal> now defaults to ansible version 2 as version 1

     

       537
       537
       +
            has been removed due to a serious

     

       538
       538
       +
            <link

     

       539
       539
       +
             xlink:href="https://www.computest.nl/advisories/CT-2017-0109_Ansible.txt">

     

       540
       540
       +
            vulnerability</link> unpatched by upstream.

     

       517
       541
        
           </para>

     

       518
       542
        
          </listitem>

     

       519
       543
        
          <listitem>

     

       520
       544
        
           <para>

     

       521
       521
       -
            <literal>gnome</literal> alias has been removed along with <literal>gtk</literal>, <literal>gtkmm</literal> and several others. Now you need to use versioned attributes, like <literal>gnome3</literal>.

     

       545
       545
       +
            <literal>gnome</literal> alias has been removed along with

     

       546
       546
       +
            <literal>gtk</literal>, <literal>gtkmm</literal> and several others. Now

     

       547
       547
       +
            you need to use versioned attributes, like <literal>gnome3</literal>.

     

       522
       548
        
           </para>

     

       523
       549
        
          </listitem>

     

       524
       550
        
          <listitem>

     

       525
       551
        
           <para>

     

       526
       526
       -
            The attribute name of the Radicale daemon has been changed from <literal>pythonPackages.radicale</literal> to <literal>radicale</literal>.

     

       552
       552
       +
            The attribute name of the Radicale daemon has been changed from

     

       553
       553
       +
            <literal>pythonPackages.radicale</literal> to <literal>radicale</literal>.

     

       527
       554
        
           </para>

     

       528
       555
        
          </listitem>

     

       529
       556
        
          <listitem>

     

       530
       557
        
           <para>

     

       531
       531
       -
            The <literal>stripHash</literal> bash function in <literal>stdenv</literal> changed according to its documentation; it now outputs the stripped name to <literal>stdout</literal> instead of putting it in the variable <literal>strippedName</literal>.

     

       558
       558
       +
            The <literal>stripHash</literal> bash function in

     

       559
       559
       +
            <literal>stdenv</literal> changed according to its documentation; it now

     

       560
       560
       +
            outputs the stripped name to <literal>stdout</literal> instead of putting

     

       561
       561
       +
            it in the variable <literal>strippedName</literal>.

     

       532
       562
        
           </para>

     

       533
       563
        
          </listitem>

     

       534
       564
        
          <listitem>

     

       535
       565
        
           <para>

     

       536
       536
       -
            PHP now scans for extra configuration .ini files in /etc/php.d instead of /etc. This prevents accidentally loading non-PHP .ini files that may be in /etc.

     

       566
       566
       +
            PHP now scans for extra configuration .ini files in /etc/php.d instead of

     

       567
       567
       +
            /etc. This prevents accidentally loading non-PHP .ini files that may be in

     

       568
       568
       +
            /etc.

     

       537
       569
        
           </para>

     

       538
       570
        
          </listitem>

     

       539
       571
        
          <listitem>

     

       540
       572
        
           <para>

     

       541
       541
       -
            Two lone top-level dict dbs moved into <literal>dictdDBs</literal>. This affects: <literal>dictdWordnet</literal> which is now at <literal>dictdDBs.wordnet</literal> and <literal>dictdWiktionary</literal> which is now at <literal>dictdDBs.wiktionary</literal>

     

       573
       573
       +
            Two lone top-level dict dbs moved into <literal>dictdDBs</literal>. This

     

       574
       574
       +
            affects: <literal>dictdWordnet</literal> which is now at

     

       575
       575
       +
            <literal>dictdDBs.wordnet</literal> and <literal>dictdWiktionary</literal>

     

       576
       576
       +
            which is now at <literal>dictdDBs.wiktionary</literal>

     

       542
       577
        
           </para>

     

       543
       578
        
          </listitem>

     

       544
       579
        
          <listitem>

     

       545
       580
        
           <para>

     

       546
       546
       -
            Parsoid service now uses YAML configuration format. <literal>service.parsoid.interwikis</literal> is now called <literal>service.parsoid.wikis</literal> and is a list of either API URLs or attribute sets as specified in parsoid's documentation.

     

       581
       581
       +
            Parsoid service now uses YAML configuration format.

     

       582
       582
       +
            <literal>service.parsoid.interwikis</literal> is now called

     

       583
       583
       +
            <literal>service.parsoid.wikis</literal> and is a list of either API URLs

     

       584
       584
       +
            or attribute sets as specified in parsoid's documentation.

     

       547
       585
        
           </para>

     

       548
       586
        
          </listitem>

     

       549
       587
        
          <listitem>

     

       550
       588
        
           <para>

     

       551
       551
       -
            <literal>Ntpd</literal> was replaced by <literal>systemd-timesyncd</literal> as the default service to synchronize system time with a remote NTP server. The old behavior can be restored by setting <literal>services.ntp.enable</literal> to <literal>true</literal>. Upstream time servers for all NTP implementations are now configured using <literal>networking.timeServers</literal>.

     

       589
       589
       +
            <literal>Ntpd</literal> was replaced by

     

       590
       590
       +
            <literal>systemd-timesyncd</literal> as the default service to synchronize

     

       591
       591
       +
            system time with a remote NTP server. The old behavior can be restored by

     

       592
       592
       +
            setting <literal>services.ntp.enable</literal> to <literal>true</literal>.

     

       593
       593
       +
            Upstream time servers for all NTP implementations are now configured using

     

       594
       594
       +
            <literal>networking.timeServers</literal>.

     

       552
       595
        
           </para>

     

       553
       596
        
          </listitem>

     

       554
       597
        
          <listitem>

     

       555
       598
        
           <para>

     

       556
       556
       -
            <literal>service.nylon</literal> is now declared using named instances. As an example:

     

       599
       599
       +
            <literal>service.nylon</literal> is now declared using named instances. As

     

       600
       600
       +
            an example:

     

       557
       601
        
       <programlisting>

     

       558
       602
        
         services.nylon = {

     

       559
       603
        
           enable = true;

     
···

       576
       620
        
          </listitem>

     

       577
       621
        
          <listitem>

     

       578
       622
        
           <para>

     

       579
       579
       -
            <literal>overridePackages</literal> function no longer exists. It is replaced by <link

     

       580
       580
       -
           xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install"> overlays</link>. For example, the following code:

     

       623
       623
       +
            <literal>overridePackages</literal> function no longer exists. It is

     

       624
       624
       +
            replaced by

     

       625
       625
       +
            <link

     

       626
       626
       +
           xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install">

     

       627
       627
       +
            overlays</link>. For example, the following code:

     

       581
       628
        
       <programlisting>

     

       582
       629
        
       let

     

       583
       630
        
         pkgs = import &lt;nixpkgs&gt; {};

     
···

       595
       642
        
          </listitem>

     

       596
       643
        
          <listitem>

     

       597
       644
        
           <para>

     

       598
       598
       -
            Autoloading connection tracking helpers is now disabled by default. This default was also changed in the Linux kernel and is considered insecure if not configured properly in your firewall. If you need connection tracking helpers (i.e. for active FTP) please enable <literal>networking.firewall.autoLoadConntrackHelpers</literal> and tune <literal>networking.firewall.connectionTrackingModules</literal> to suit your needs.

     

       645
       645
       +
            Autoloading connection tracking helpers is now disabled by default. This

     

       646
       646
       +
            default was also changed in the Linux kernel and is considered insecure if

     

       647
       647
       +
            not configured properly in your firewall. If you need connection tracking

     

       648
       648
       +
            helpers (i.e. for active FTP) please enable

     

       649
       649
       +
            <literal>networking.firewall.autoLoadConntrackHelpers</literal> and tune

     

       650
       650
       +
            <literal>networking.firewall.connectionTrackingModules</literal> to suit

     

       651
       651
       +
            your needs.

     

       599
       652
        
           </para>

     

       600
       653
        
          </listitem>

     

       601
       654
        
          <listitem>

     

       602
       655
        
           <para>

     

       603
       603
       -
            <literal>local_recipient_maps</literal> is not set to empty value by Postfix service. It's an insecure default as stated by Postfix documentation. Those who want to retain this setting need to set it via <literal>services.postfix.extraConfig</literal>.

     

       656
       656
       +
            <literal>local_recipient_maps</literal> is not set to empty value by

     

       657
       657
       +
            Postfix service. It's an insecure default as stated by Postfix

     

       658
       658
       +
            documentation. Those who want to retain this setting need to set it via

     

       659
       659
       +
            <literal>services.postfix.extraConfig</literal>.

     

       604
       660
        
           </para>

     

       605
       661
        
          </listitem>

     

       606
       662
        
          <listitem>

     

       607
       663
        
           <para>

     

       608
       608
       -
            Iputils no longer provide ping6 and traceroute6. The functionality of these tools has been integrated into ping and traceroute respectively. To enforce an address family the new flags <literal>-4</literal> and <literal>-6</literal> have been added. One notable incompatibility is that specifying an interface (for link-local IPv6 for instance) is no longer done with the <literal>-I</literal> flag, but by encoding the interface into the address (<literal>ping fe80::1%eth0</literal>).

     

       664
       664
       +
            Iputils no longer provide ping6 and traceroute6. The functionality of

     

       665
       665
       +
            these tools has been integrated into ping and traceroute respectively. To

     

       666
       666
       +
            enforce an address family the new flags <literal>-4</literal> and

     

       667
       667
       +
            <literal>-6</literal> have been added. One notable incompatibility is that

     

       668
       668
       +
            specifying an interface (for link-local IPv6 for instance) is no longer

     

       669
       669
       +
            done with the <literal>-I</literal> flag, but by encoding the interface

     

       670
       670
       +
            into the address (<literal>ping fe80::1%eth0</literal>).

     

       609
       671
        
           </para>

     

       610
       672
        
          </listitem>

     

       611
       673
        
          <listitem>

     

       612
       674
        
           <para>

     

       613
       613
       -
            The socket handling of the <literal>services.rmilter</literal> module has been fixed and refactored. As rmilter doesn't support binding to more than one socket, the options <literal>bindUnixSockets</literal> and <literal>bindInetSockets</literal> have been replaced by <literal>services.rmilter.bindSocket.*</literal>. The default is still a unix socket in <literal>/run/rmilter/rmilter.sock</literal>. Refer to the options documentation for more information.

     

       675
       675
       +
            The socket handling of the <literal>services.rmilter</literal> module has

     

       676
       676
       +
            been fixed and refactored. As rmilter doesn't support binding to more than

     

       677
       677
       +
            one socket, the options <literal>bindUnixSockets</literal> and

     

       678
       678
       +
            <literal>bindInetSockets</literal> have been replaced by

     

       679
       679
       +
            <literal>services.rmilter.bindSocket.*</literal>. The default is still a

     

       680
       680
       +
            unix socket in <literal>/run/rmilter/rmilter.sock</literal>. Refer to the

     

       681
       681
       +
            options documentation for more information.

     

       614
       682
        
           </para>

     

       615
       683
        
          </listitem>

     

       616
       684
        
          <listitem>

     

       617
       685
        
           <para>

     

       618
       618
       -
            The <literal>fetch*</literal> functions no longer support md5, please use sha256 instead.

     

       686
       686
       +
            The <literal>fetch*</literal> functions no longer support md5, please use

     

       687
       687
       +
            sha256 instead.

     

       619
       688
        
           </para>

     

       620
       689
        
          </listitem>

     

       621
       690
        
          <listitem>

     

       622
       691
        
           <para>

     

       623
       623
       -
            The dnscrypt-proxy module interface has been streamlined around the <option>extraArgs</option> option. Where possible, legacy option declarations are mapped to <option>extraArgs</option> but will emit warnings. The <option>resolverList</option> has been outright removed: to use an unlisted resolver, use the <option>customResolver</option> option.

     

       692
       692
       +
            The dnscrypt-proxy module interface has been streamlined around the

     

       693
       693
       +
            <option>extraArgs</option> option. Where possible, legacy option

     

       694
       694
       +
            declarations are mapped to <option>extraArgs</option> but will emit

     

       695
       695
       +
            warnings. The <option>resolverList</option> has been outright removed: to

     

       696
       696
       +
            use an unlisted resolver, use the <option>customResolver</option> option.

     

       624
       697
        
           </para>

     

       625
       698
        
          </listitem>

     

       626
       699
        
          <listitem>

     

       627
       700
        
           <para>

     

       628
       628
       -
            torbrowser now stores local state under <filename>~/.local/share/tor-browser</filename> by default. Any browser profile data from the old location, <filename>~/.torbrowser4</filename>, must be migrated manually.

     

       701
       701
       +
            torbrowser now stores local state under

     

       702
       702
       +
            <filename>~/.local/share/tor-browser</filename> by default. Any browser

     

       703
       703
       +
            profile data from the old location, <filename>~/.torbrowser4</filename>,

     

       704
       704
       +
            must be migrated manually.

     

       629
       705
        
           </para>

     

       630
       706
        
          </listitem>

     

       631
       707
        
          <listitem>

     

       632
       708
        
           <para>

     

       633
       633
       -
            The ihaskell, monetdb, offlineimap and sitecopy services have been removed.

     

       709
       709
       +
            The ihaskell, monetdb, offlineimap and sitecopy services have been

     

       710
       710
       +
            removed.

     

       634
       711
        
           </para>

     

       635
       712
        
          </listitem>

     

       636
       713
        
         </itemizedlist>

     
···

       646
       723
        
         <itemizedlist>

     

       647
       724
        
          <listitem>

     

       648
       725
        
           <para>

     

       649
       649
       -
            Module type system have a new extensible option types feature that allow to extend certain types, such as enum, through multiple option declarations of the same option across multiple modules.

     

       726
       726
       +
            Module type system have a new extensible option types feature that allow

     

       727
       727
       +
            to extend certain types, such as enum, through multiple option

     

       728
       728
       +
            declarations of the same option across multiple modules.

     

       650
       729
        
           </para>

     

       651
       730
        
          </listitem>

     

       652
       731
        
          <listitem>

     

       653
       732
        
           <para>

     

       654
       654
       -
            <literal>jre</literal> now defaults to GTK UI by default. This improves visual consistency and makes Java follow system font style, improving the situation on HighDPI displays. This has a cost of increased closure size; for server and other headless workloads it's recommended to use <literal>jre_headless</literal>.

     

       733
       733
       +
            <literal>jre</literal> now defaults to GTK UI by default. This improves

     

       734
       734
       +
            visual consistency and makes Java follow system font style, improving the

     

       735
       735
       +
            situation on HighDPI displays. This has a cost of increased closure size;

     

       736
       736
       +
            for server and other headless workloads it's recommended to use

     

       737
       737
       +
            <literal>jre_headless</literal>.

     

       655
       738
        
           </para>

     

       656
       739
        
          </listitem>

     

       657
       740
        
          <listitem>

     
···

       661
       744
        
          </listitem>

     

       662
       745
        
          <listitem>

     

       663
       746
        
           <para>

     

       664
       664
       -
            The Python 2.7 interpreter does not use modules anymore. Instead, all CPython interpreters now include the whole standard library except for `tkinter`, which is available in the Python package set.

     

       747
       747
       +
            The Python 2.7 interpreter does not use modules anymore. Instead, all

     

       748
       748
       +
            CPython interpreters now include the whole standard library except for

     

       749
       749
       +
            `tkinter`, which is available in the Python package set.

     

       665
       750
        
           </para>

     

       666
       751
        
          </listitem>

     

       667
       752
        
          <listitem>

     

       668
       753
        
           <para>

     

       669
       669
       -
            Python 2.7, 3.5 and 3.6 are now built deterministically and 3.4 mostly. Minor modifications had to be made to the interpreters in order to generate deterministic bytecode. This has security implications and is relevant for those using Python in a <literal>nix-shell</literal>. See the Nixpkgs manual for details.

     

       754
       754
       +
            Python 2.7, 3.5 and 3.6 are now built deterministically and 3.4 mostly.

     

       755
       755
       +
            Minor modifications had to be made to the interpreters in order to

     

       756
       756
       +
            generate deterministic bytecode. This has security implications and is

     

       757
       757
       +
            relevant for those using Python in a <literal>nix-shell</literal>. See the

     

       758
       758
       +
            Nixpkgs manual for details.

     

       670
       759
        
           </para>

     

       671
       760
        
          </listitem>

     

       672
       761
        
          <listitem>

     

       673
       762
        
           <para>

     

       674
       674
       -
            The Python package sets now use a fixed-point combinator and the sets are available as attributes of the interpreters.

     

       763
       763
       +
            The Python package sets now use a fixed-point combinator and the sets are

     

       764
       764
       +
            available as attributes of the interpreters.

     

       675
       765
        
           </para>

     

       676
       766
        
          </listitem>

     

       677
       767
        
          <listitem>

     

       678
       768
        
           <para>

     

       679
       679
       -
            The Python function <literal>buildPythonPackage</literal> has been improved and can be used to build from Setuptools source, Flit source, and precompiled Wheels.

     

       769
       769
       +
            The Python function <literal>buildPythonPackage</literal> has been

     

       770
       770
       +
            improved and can be used to build from Setuptools source, Flit source, and

     

       771
       771
       +
            precompiled Wheels.

     

       680
       772
        
           </para>

     

       681
       773
        
          </listitem>

     

       682
       774
        
          <listitem>

     

       683
       775
        
           <para>

     

       684
       684
       -
            When adding new or updating current Python libraries, the expressions should be put in separate files in <literal>pkgs/development/python-modules</literal> and called from <literal>python-packages.nix</literal>.

     

       776
       776
       +
            When adding new or updating current Python libraries, the expressions

     

       777
       777
       +
            should be put in separate files in

     

       778
       778
       +
            <literal>pkgs/development/python-modules</literal> and called from

     

       779
       779
       +
            <literal>python-packages.nix</literal>.

     

       685
       780
        
           </para>

     

       686
       781
        
          </listitem>

     

       687
       782
        
          <listitem>

     

       688
       783
        
           <para>

     

       689
       689
       -
            The dnscrypt-proxy service supports synchronizing the list of public resolvers without working DNS resolution. This fixes issues caused by the resolver list becoming outdated. It also improves the viability of DNSCrypt only configurations.

     

       784
       784
       +
            The dnscrypt-proxy service supports synchronizing the list of public

     

       785
       785
       +
            resolvers without working DNS resolution. This fixes issues caused by the

     

       786
       786
       +
            resolver list becoming outdated. It also improves the viability of

     

       787
       787
       +
            DNSCrypt only configurations.

     

       690
       788
        
           </para>

     

       691
       789
        
          </listitem>

     

       692
       790
        
          <listitem>

     

       693
       791
        
           <para>

     

       694
       694
       -
            Containers using bridged networking no longer lose their connection after changes to the host networking.

     

       792
       792
       +
            Containers using bridged networking no longer lose their connection after

     

       793
       793
       +
            changes to the host networking.

     

       695
       794
        
           </para>

     

       696
       795
        
          </listitem>

     

       697
       796
        
          <listitem>

     
···

       701
       800
        
          </listitem>

     

       702
       801
        
          <listitem>

     

       703
       802
        
           <para>

     

       704
       704
       -
            The bind DNS utilities (e.g. dig) have been split into their own output and are now also available in <literal>pkgs.dnsutils</literal> and it is no longer necessary to pull in all of <literal>bind</literal> to use them.

     

       803
       803
       +
            The bind DNS utilities (e.g. dig) have been split into their own output

     

       804
       804
       +
            and are now also available in <literal>pkgs.dnsutils</literal> and it is

     

       805
       805
       +
            no longer necessary to pull in all of <literal>bind</literal> to use them.

     

       705
       806
        
           </para>

     

       706
       807
        
          </listitem>

     

       707
       808
        
          <listitem>

     

       708
       809
        
           <para>

     

       709
       709
       -
            Per-user configuration was moved from <filename>~/.nixpkgs</filename> to <filename>~/.config/nixpkgs</filename>. The former is still valid for <filename>config.nix</filename> for backwards compatibility.

     

       810
       810
       +
            Per-user configuration was moved from <filename>~/.nixpkgs</filename> to

     

       811
       811
       +
            <filename>~/.config/nixpkgs</filename>. The former is still valid for

     

       812
       812
       +
            <filename>config.nix</filename> for backwards compatibility.

     

       710
       813
        
           </para>

     

       711
       814
        
          </listitem>

     

       712
       815
        
         </itemizedlist>

+227 -65

nixos/doc/manual/release-notes/rl-1709.xml

···

       13
       13
        
         <title>Highlights</title>

     

       14
       14
        
       

     

       15
       15
        
         <para>

     

       16
       16
       -
          In addition to numerous new and upgraded packages, this release has the following highlights:

     

       16
       16
       +
          In addition to numerous new and upgraded packages, this release has the

     

       17
       17
       +
          following highlights:

     

       17
       18
        
         </para>

     

       18
       19
        
       

     

       19
       20
        
         <itemizedlist>

     

       20
       21
        
          <listitem>

     

       21
       22
        
           <para>

     

       22
       22
       -
            The GNOME version is now 3.24. KDE Plasma was upgraded to 5.10, KDE Applications to 17.08.1 and KDE Frameworks to 5.37.

     

       23
       23
       +
            The GNOME version is now 3.24. KDE Plasma was upgraded to 5.10, KDE

     

       24
       24
       +
            Applications to 17.08.1 and KDE Frameworks to 5.37.

     

       23
       25
        
           </para>

     

       24
       26
        
          </listitem>

     

       25
       27
        
          <listitem>

     

       26
       28
        
           <para>

     

       27
       27
       -
            The user handling now keeps track of deallocated UIDs/GIDs. When a user or group is revived, this allows it to be allocated the UID/GID it had before. A consequence is that UIDs and GIDs are no longer reused.

     

       29
       29
       +
            The user handling now keeps track of deallocated UIDs/GIDs. When a user or

     

       30
       30
       +
            group is revived, this allows it to be allocated the UID/GID it had

     

       31
       31
       +
            before. A consequence is that UIDs and GIDs are no longer reused.

     

       28
       32
        
           </para>

     

       29
       33
        
          </listitem>

     

       30
       34
        
          <listitem>

     

       31
       35
        
           <para>

     

       32
       32
       -
            The module option <option>services.xserver.xrandrHeads</option> now causes the first head specified in this list to be set as the primary head. Apart from that, it's now possible to also set additional options by using an attribute set, for example:

     

       36
       36
       +
            The module option <option>services.xserver.xrandrHeads</option> now causes

     

       37
       37
       +
            the first head specified in this list to be set as the primary head. Apart

     

       38
       38
       +
            from that, it's now possible to also set additional options by using an

     

       39
       39
       +
            attribute set, for example:

     

       33
       40
        
       <programlisting>

     

       34
       41
        
       { services.xserver.xrandrHeads = [

     

       35
       42
        
           "HDMI-0"

     
···

       43
       50
        
         ];

     

       44
       51
        
       }

     

       45
       52
        
       </programlisting>

     

       46
       46
       -
            This will set the <literal>DVI-0</literal> output to be the primary head, even though <literal>HDMI-0</literal> is the first head in the list.

     

       53
       53
       +
            This will set the <literal>DVI-0</literal> output to be the primary head,

     

       54
       54
       +
            even though <literal>HDMI-0</literal> is the first head in the list.

     

       47
       55
        
           </para>

     

       48
       56
        
          </listitem>

     

       49
       57
        
          <listitem>

     

       50
       58
        
           <para>

     

       51
       51
       -
            The handling of SSL in the <literal>services.nginx</literal> module has been cleaned up, renaming the misnamed <literal>enableSSL</literal> to <literal>onlySSL</literal> which reflects its original intention. This is not to be used with the already existing <literal>forceSSL</literal> which creates a second non-SSL virtual host redirecting to the SSL virtual host. This by chance had worked earlier due to specific implementation details. In case you had specified both please remove the <literal>enableSSL</literal> option to keep the previous behaviour.

     

       59
       59
       +
            The handling of SSL in the <literal>services.nginx</literal> module has

     

       60
       60
       +
            been cleaned up, renaming the misnamed <literal>enableSSL</literal> to

     

       61
       61
       +
            <literal>onlySSL</literal> which reflects its original intention. This is

     

       62
       62
       +
            not to be used with the already existing <literal>forceSSL</literal> which

     

       63
       63
       +
            creates a second non-SSL virtual host redirecting to the SSL virtual host.

     

       64
       64
       +
            This by chance had worked earlier due to specific implementation details.

     

       65
       65
       +
            In case you had specified both please remove the

     

       66
       66
       +
            <literal>enableSSL</literal> option to keep the previous behaviour.

     

       52
       67
        
           </para>

     

       53
       68
        
           <para>

     

       54
       54
       -
            Another <literal>addSSL</literal> option has been introduced to configure both a non-SSL virtual host and an SSL virtual host with the same configuration.

     

       69
       69
       +
            Another <literal>addSSL</literal> option has been introduced to configure

     

       70
       70
       +
            both a non-SSL virtual host and an SSL virtual host with the same

     

       71
       71
       +
            configuration.

     

       55
       72
        
           </para>

     

       56
       73
        
           <para>

     

       57
       57
       -
            Options to configure <literal>resolver</literal> options and <literal>upstream</literal> blocks have been introduced. See their information for further details.

     

       74
       74
       +
            Options to configure <literal>resolver</literal> options and

     

       75
       75
       +
            <literal>upstream</literal> blocks have been introduced. See their

     

       76
       76
       +
            information for further details.

     

       58
       77
        
           </para>

     

       59
       78
        
           <para>

     

       60
       60
       -
            The <literal>port</literal> option has been replaced by a more generic <literal>listen</literal> option which makes it possible to specify multiple addresses, ports and SSL configs dependant on the new SSL handling mentioned above.

     

       79
       79
       +
            The <literal>port</literal> option has been replaced by a more generic

     

       80
       80
       +
            <literal>listen</literal> option which makes it possible to specify

     

       81
       81
       +
            multiple addresses, ports and SSL configs dependant on the new SSL

     

       82
       82
       +
            handling mentioned above.

     

       61
       83
        
           </para>

     

       62
       84
        
          </listitem>

     

       63
       85
        
         </itemizedlist>

     
···

       446
       468
        
         <title>Backward Incompatibilities</title>

     

       447
       469
        
       

     

       448
       470
        
         <para>

     

       449
       449
       -
          When upgrading from a previous release, please be aware of the following incompatible changes:

     

       471
       471
       +
          When upgrading from a previous release, please be aware of the following

     

       472
       472
       +
          incompatible changes:

     

       450
       473
        
         </para>

     

       451
       474
        
       

     

       452
       475
        
         <itemizedlist>

     

       453
       476
        
          <listitem>

     

       454
       477
        
           <para>

     

       455
       455
       -
            <emphasis role="strong"> In an Qemu-based virtualization environment, the network interface names changed from i.e. <literal>enp0s3</literal> to <literal>ens3</literal>. </emphasis>

     

       478
       478
       +
            <emphasis role="strong"> In an Qemu-based virtualization environment, the

     

       479
       479
       +
            network interface names changed from i.e. <literal>enp0s3</literal> to

     

       480
       480
       +
            <literal>ens3</literal>. </emphasis>

     

       456
       481
        
           </para>

     

       457
       482
        
           <para>

     

       458
       458
       -
            This is due to a kernel configuration change. The new naming is consistent with those of other Linux distributions with systemd. See <link xlink:href="https://github.com/NixOS/nixpkgs/issues/29197">#29197</link> for more information.

     

       483
       483
       +
            This is due to a kernel configuration change. The new naming is consistent

     

       484
       484
       +
            with those of other Linux distributions with systemd. See

     

       485
       485
       +
            <link xlink:href="https://github.com/NixOS/nixpkgs/issues/29197">#29197</link>

     

       486
       486
       +
            for more information.

     

       459
       487
        
           </para>

     

       460
       488
        
           <para>

     

       461
       461
       -
            A machine is affected if the <literal>virt-what</literal> tool either returns <literal>qemu</literal> or <literal>kvm</literal> <emphasis>and</emphasis> has interface names used in any part of its NixOS configuration, in particular if a static network configuration with <literal>networking.interfaces</literal> is used.

     

       489
       489
       +
            A machine is affected if the <literal>virt-what</literal> tool either

     

       490
       490
       +
            returns <literal>qemu</literal> or <literal>kvm</literal>

     

       491
       491
       +
            <emphasis>and</emphasis> has interface names used in any part of its NixOS

     

       492
       492
       +
            configuration, in particular if a static network configuration with

     

       493
       493
       +
            <literal>networking.interfaces</literal> is used.

     

       462
       494
        
           </para>

     

       463
       495
        
           <para>

     

       464
       496
        
            Before rebooting affected machines, please ensure:

     

       465
       497
        
            <itemizedlist>

     

       466
       498
        
             <listitem>

     

       467
       499
        
              <para>

     

       468
       468
       -
               Change the interface names in your NixOS configuration. The first interface will be called <literal>ens3</literal>, the second one <literal>ens8</literal> and starting from there incremented by 1.

     

       500
       500
       +
               Change the interface names in your NixOS configuration. The first

     

       501
       501
       +
               interface will be called <literal>ens3</literal>, the second one

     

       502
       502
       +
               <literal>ens8</literal> and starting from there incremented by 1.

     

       469
       503
        
              </para>

     

       470
       504
        
             </listitem>

     

       471
       505
        
             <listitem>

     

       472
       506
        
              <para>

     

       473
       473
       -
               After changing the interface names, rebuild your system with <literal>nixos-rebuild boot</literal> to activate the new configuration after a reboot. If you switch to the new configuration right away you might lose network connectivity! If using <literal>nixops</literal>, deploy with <literal>nixops deploy --force-reboot</literal>.

     

       507
       507
       +
               After changing the interface names, rebuild your system with

     

       508
       508
       +
               <literal>nixos-rebuild boot</literal> to activate the new configuration

     

       509
       509
       +
               after a reboot. If you switch to the new configuration right away you

     

       510
       510
       +
               might lose network connectivity! If using <literal>nixops</literal>,

     

       511
       511
       +
               deploy with <literal>nixops deploy --force-reboot</literal>.

     

       474
       512
        
              </para>

     

       475
       513
        
             </listitem>

     

       476
       514
        
            </itemizedlist>

     
···

       478
       516
        
          </listitem>

     

       479
       517
        
          <listitem>

     

       480
       518
        
           <para>

     

       481
       481
       -
            The following changes apply if the <literal>stateVersion</literal> is changed to 17.09 or higher. For <literal>stateVersion = "17.03"</literal> or lower the old behavior is preserved.

     

       519
       519
       +
            The following changes apply if the <literal>stateVersion</literal> is

     

       520
       520
       +
            changed to 17.09 or higher. For <literal>stateVersion = "17.03"</literal>

     

       521
       521
       +
            or lower the old behavior is preserved.

     

       482
       522
        
           </para>

     

       483
       523
        
           <itemizedlist>

     

       484
       524
        
            <listitem>

     

       485
       525
        
             <para>

     

       486
       486
       -
              The <literal>postgres</literal> default version was changed from 9.5 to 9.6.

     

       526
       526
       +
              The <literal>postgres</literal> default version was changed from 9.5 to

     

       527
       527
       +
              9.6.

     

       487
       528
        
             </para>

     

       488
       529
        
            </listitem>

     

       489
       530
        
            <listitem>

     

       490
       531
        
             <para>

     

       491
       491
       -
              The <literal>postgres</literal> superuser name has changed from <literal>root</literal> to <literal>postgres</literal> to more closely follow what other Linux distributions are doing.

     

       532
       532
       +
              The <literal>postgres</literal> superuser name has changed from

     

       533
       533
       +
              <literal>root</literal> to <literal>postgres</literal> to more closely

     

       534
       534
       +
              follow what other Linux distributions are doing.

     

       492
       535
        
             </para>

     

       493
       536
        
            </listitem>

     

       494
       537
        
            <listitem>

     

       495
       538
        
             <para>

     

       496
       496
       -
              The <literal>postgres</literal> default <literal>dataDir</literal> has changed from <literal>/var/db/postgres</literal> to <literal>/var/lib/postgresql/$psqlSchema</literal> where $psqlSchema is 9.6 for example.

     

       539
       539
       +
              The <literal>postgres</literal> default <literal>dataDir</literal> has

     

       540
       540
       +
              changed from <literal>/var/db/postgres</literal> to

     

       541
       541
       +
              <literal>/var/lib/postgresql/$psqlSchema</literal> where $psqlSchema is

     

       542
       542
       +
              9.6 for example.

     

       497
       543
        
             </para>

     

       498
       544
        
            </listitem>

     

       499
       545
        
            <listitem>

     

       500
       546
        
             <para>

     

       501
       501
       -
              The <literal>mysql</literal> default <literal>dataDir</literal> has changed from <literal>/var/mysql</literal> to <literal>/var/lib/mysql</literal>.

     

       547
       547
       +
              The <literal>mysql</literal> default <literal>dataDir</literal> has

     

       548
       548
       +
              changed from <literal>/var/mysql</literal> to

     

       549
       549
       +
              <literal>/var/lib/mysql</literal>.

     

       502
       550
        
             </para>

     

       503
       551
        
            </listitem>

     

       504
       552
        
            <listitem>

     

       505
       553
        
             <para>

     

       506
       506
       -
              Radicale's default package has changed from 1.x to 2.x. Instructions to migrate can be found <link xlink:href="http://radicale.org/1to2/"> here </link>. It is also possible to use the newer version by setting the <literal>package</literal> to <literal>radicale2</literal>, which is done automatically when <literal>stateVersion</literal> is 17.09 or higher. The <literal>extraArgs</literal> option has been added to allow passing the data migration arguments specified in the instructions; see the <filename xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/radicale.nix">radicale.nix</filename> NixOS test for an example migration.

     

       554
       554
       +
              Radicale's default package has changed from 1.x to 2.x. Instructions to

     

       555
       555
       +
              migrate can be found <link xlink:href="http://radicale.org/1to2/"> here

     

       556
       556
       +
              </link>. It is also possible to use the newer version by setting the

     

       557
       557
       +
              <literal>package</literal> to <literal>radicale2</literal>, which is

     

       558
       558
       +
              done automatically when <literal>stateVersion</literal> is 17.09 or

     

       559
       559
       +
              higher. The <literal>extraArgs</literal> option has been added to allow

     

       560
       560
       +
              passing the data migration arguments specified in the instructions; see

     

       561
       561
       +
              the

     

       562
       562
       +
              <filename xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/radicale.nix">radicale.nix</filename>

     

       563
       563
       +
              NixOS test for an example migration.

     

       507
       564
        
             </para>

     

       508
       565
        
            </listitem>

     

       509
       566
        
           </itemizedlist>

     

       510
       567
        
          </listitem>

     

       511
       568
        
          <listitem>

     

       512
       569
        
           <para>

     

       513
       513
       -
            The <literal>aiccu</literal> package was removed. This is due to SixXS <link xlink:href="https://www.sixxs.net/main/"> sunsetting</link> its IPv6 tunnel.

     

       570
       570
       +
            The <literal>aiccu</literal> package was removed. This is due to SixXS

     

       571
       571
       +
            <link xlink:href="https://www.sixxs.net/main/"> sunsetting</link> its IPv6

     

       572
       572
       +
            tunnel.

     

       514
       573
        
           </para>

     

       515
       574
        
          </listitem>

     

       516
       575
        
          <listitem>

     

       517
       576
        
           <para>

     

       518
       518
       -
            The <literal>fanctl</literal> package and <literal>fan</literal> module have been removed due to the developers not upstreaming their iproute2 patches and lagging with compatibility to recent iproute2 versions.

     

       577
       577
       +
            The <literal>fanctl</literal> package and <literal>fan</literal> module

     

       578
       578
       +
            have been removed due to the developers not upstreaming their iproute2

     

       579
       579
       +
            patches and lagging with compatibility to recent iproute2 versions.

     

       519
       580
        
           </para>

     

       520
       581
        
          </listitem>

     

       521
       582
        
          <listitem>

     

       522
       583
        
           <para>

     

       523
       523
       -
            Top-level <literal>idea</literal> package collection was renamed. All JetBrains IDEs are now at <literal>jetbrains</literal>.

     

       584
       584
       +
            Top-level <literal>idea</literal> package collection was renamed. All

     

       585
       585
       +
            JetBrains IDEs are now at <literal>jetbrains</literal>.

     

       524
       586
        
           </para>

     

       525
       587
        
          </listitem>

     

       526
       588
        
          <listitem>

     

       527
       589
        
           <para>

     

       528
       528
       -
            <literal>flexget</literal>'s state database cannot be upgraded to its new internal format, requiring removal of any existing <literal>db-config.sqlite</literal> which will be automatically recreated.

     

       590
       590
       +
            <literal>flexget</literal>'s state database cannot be upgraded to its new

     

       591
       591
       +
            internal format, requiring removal of any existing

     

       592
       592
       +
            <literal>db-config.sqlite</literal> which will be automatically recreated.

     

       529
       593
        
           </para>

     

       530
       594
        
          </listitem>

     

       531
       595
        
          <listitem>

     

       532
       596
        
           <para>

     

       533
       533
       -
            The <literal>ipfs</literal> service now doesn't ignore the <literal>dataDir</literal> option anymore. If you've ever set this option to anything other than the default you'll have to either unset it (so the default gets used) or migrate the old data manually with

     

       597
       597
       +
            The <literal>ipfs</literal> service now doesn't ignore the

     

       598
       598
       +
            <literal>dataDir</literal> option anymore. If you've ever set this option

     

       599
       599
       +
            to anything other than the default you'll have to either unset it (so the

     

       600
       600
       +
            default gets used) or migrate the old data manually with

     

       534
       601
        
       <programlisting>

     

       535
       602
        
       dataDir=&lt;valueOfDataDir&gt;

     

       536
       603
        
       mv /var/lib/ipfs/.ipfs/* $dataDir

     
···

       540
       607
        
          </listitem>

     

       541
       608
        
          <listitem>

     

       542
       609
        
           <para>

     

       543
       543
       -
            The <literal>caddy</literal> service was previously using an extra <literal>.caddy</literal> directory in the data directory specified with the <literal>dataDir</literal> option. The contents of the <literal>.caddy</literal> directory are now expected to be in the <literal>dataDir</literal>.

     

       610
       610
       +
            The <literal>caddy</literal> service was previously using an extra

     

       611
       611
       +
            <literal>.caddy</literal> directory in the data directory specified with

     

       612
       612
       +
            the <literal>dataDir</literal> option. The contents of the

     

       613
       613
       +
            <literal>.caddy</literal> directory are now expected to be in the

     

       614
       614
       +
            <literal>dataDir</literal>.

     

       544
       615
        
           </para>

     

       545
       616
        
          </listitem>

     

       546
       617
        
          <listitem>

     

       547
       618
        
           <para>

     

       548
       548
       -
            The <literal>ssh-agent</literal> user service is not started by default anymore. Use <literal>programs.ssh.startAgent</literal> to enable it if needed. There is also a new <literal>programs.gnupg.agent</literal> module that creates a <literal>gpg-agent</literal> user service. It can also serve as a SSH agent if <literal>enableSSHSupport</literal> is set.

     

       619
       619
       +
            The <literal>ssh-agent</literal> user service is not started by default

     

       620
       620
       +
            anymore. Use <literal>programs.ssh.startAgent</literal> to enable it if

     

       621
       621
       +
            needed. There is also a new <literal>programs.gnupg.agent</literal> module

     

       622
       622
       +
            that creates a <literal>gpg-agent</literal> user service. It can also

     

       623
       623
       +
            serve as a SSH agent if <literal>enableSSHSupport</literal> is set.

     

       549
       624
        
           </para>

     

       550
       625
        
          </listitem>

     

       551
       626
        
          <listitem>

     

       552
       627
        
           <para>

     

       553
       553
       -
            The <literal>services.tinc.networks.&lt;name&gt;.listenAddress</literal> option had a misleading name that did not correspond to its behavior. It now correctly defines the ip to listen for incoming connections on. To keep the previous behaviour, use <literal>services.tinc.networks.&lt;name&gt;.bindToAddress</literal> instead. Refer to the description of the options for more details.

     

       628
       628
       +
            The <literal>services.tinc.networks.&lt;name&gt;.listenAddress</literal>

     

       629
       629
       +
            option had a misleading name that did not correspond to its behavior. It

     

       630
       630
       +
            now correctly defines the ip to listen for incoming connections on. To

     

       631
       631
       +
            keep the previous behaviour, use

     

       632
       632
       +
            <literal>services.tinc.networks.&lt;name&gt;.bindToAddress</literal>

     

       633
       633
       +
            instead. Refer to the description of the options for more details.

     

       554
       634
        
           </para>

     

       555
       635
        
          </listitem>

     

       556
       636
        
          <listitem>

     

       557
       637
        
           <para>

     

       558
       558
       -
            <literal>tlsdate</literal> package and module were removed. This is due to the project being dead and not building with openssl 1.1.

     

       638
       638
       +
            <literal>tlsdate</literal> package and module were removed. This is due to

     

       639
       639
       +
            the project being dead and not building with openssl 1.1.

     

       559
       640
        
           </para>

     

       560
       641
        
          </listitem>

     

       561
       642
        
          <listitem>

     

       562
       643
        
           <para>

     

       563
       563
       -
            <literal>wvdial</literal> package and module were removed. This is due to the project being dead and not building with openssl 1.1.

     

       644
       644
       +
            <literal>wvdial</literal> package and module were removed. This is due to

     

       645
       645
       +
            the project being dead and not building with openssl 1.1.

     

       564
       646
        
           </para>

     

       565
       647
        
          </listitem>

     

       566
       648
        
          <listitem>

     

       567
       649
        
           <para>

     

       568
       568
       -
            <literal>cc-wrapper</literal>'s setup-hook now exports a number of environment variables corresponding to binutils binaries, (e.g. <envar>LD</envar>, <envar>STRIP</envar>, <envar>RANLIB</envar>, etc). This is done to prevent packages' build systems guessing, which is harder to predict, especially when cross-compiling. However, some packages have broken due to this—their build systems either not supporting, or claiming to support without adequate testing, taking such environment variables as parameters.

     

       650
       650
       +
            <literal>cc-wrapper</literal>'s setup-hook now exports a number of

     

       651
       651
       +
            environment variables corresponding to binutils binaries, (e.g.

     

       652
       652
       +
            <envar>LD</envar>, <envar>STRIP</envar>, <envar>RANLIB</envar>, etc). This

     

       653
       653
       +
            is done to prevent packages' build systems guessing, which is harder to

     

       654
       654
       +
            predict, especially when cross-compiling. However, some packages have

     

       655
       655
       +
            broken due to this—their build systems either not supporting, or

     

       656
       656
       +
            claiming to support without adequate testing, taking such environment

     

       657
       657
       +
            variables as parameters.

     

       569
       658
        
           </para>

     

       570
       659
        
          </listitem>

     

       571
       660
        
          <listitem>

     

       572
       661
        
           <para>

     

       573
       573
       -
            <literal>services.firefox.syncserver</literal> now runs by default as a non-root user. To accomodate this change, the default sqlite database location has also been changed. Migration should work automatically. Refer to the description of the options for more details.

     

       662
       662
       +
            <literal>services.firefox.syncserver</literal> now runs by default as a

     

       663
       663
       +
            non-root user. To accomodate this change, the default sqlite database

     

       664
       664
       +
            location has also been changed. Migration should work automatically. Refer

     

       665
       665
       +
            to the description of the options for more details.

     

       574
       666
        
           </para>

     

       575
       667
        
          </listitem>

     

       576
       668
        
          <listitem>

     

       577
       669
        
           <para>

     

       578
       578
       -
            The <literal>compiz</literal> window manager and package was removed. The system support had been broken for several years.

     

       670
       670
       +
            The <literal>compiz</literal> window manager and package was removed. The

     

       671
       671
       +
            system support had been broken for several years.

     

       579
       672
        
           </para>

     

       580
       673
        
          </listitem>

     

       581
       674
        
          <listitem>

     

       582
       675
        
           <para>

     

       583
       583
       -
            Touchpad support should now be enabled through <literal>libinput</literal> as <literal>synaptics</literal> is now deprecated. See the option <literal>services.xserver.libinput.enable</literal>.

     

       676
       676
       +
            Touchpad support should now be enabled through <literal>libinput</literal>

     

       677
       677
       +
            as <literal>synaptics</literal> is now deprecated. See the option

     

       678
       678
       +
            <literal>services.xserver.libinput.enable</literal>.

     

       584
       679
        
           </para>

     

       585
       680
        
          </listitem>

     

       586
       681
        
          <listitem>

     

       587
       682
        
           <para>

     

       588
       588
       -
            grsecurity/PaX support has been dropped, following upstream's decision to cease free support. See <link xlink:href="https://grsecurity.net/passing_the_baton.php"> upstream's announcement</link> for more information. No complete replacement for grsecurity/PaX is available presently.

     

       683
       683
       +
            grsecurity/PaX support has been dropped, following upstream's decision to

     

       684
       684
       +
            cease free support. See

     

       685
       685
       +
            <link xlink:href="https://grsecurity.net/passing_the_baton.php">

     

       686
       686
       +
            upstream's announcement</link> for more information. No complete

     

       687
       687
       +
            replacement for grsecurity/PaX is available presently.

     

       589
       688
        
           </para>

     

       590
       689
        
          </listitem>

     

       591
       690
        
          <listitem>

     

       592
       691
        
           <para>

     

       593
       593
       -
            <literal>services.mysql</literal> now has declarative configuration of databases and users with the <literal>ensureDatabases</literal> and <literal>ensureUsers</literal> options.

     

       692
       692
       +
            <literal>services.mysql</literal> now has declarative configuration of

     

       693
       693
       +
            databases and users with the <literal>ensureDatabases</literal> and

     

       694
       694
       +
            <literal>ensureUsers</literal> options.

     

       594
       695
        
           </para>

     

       595
       696
        
           <para>

     

       596
       596
       -
            These options will never delete existing databases and users, especially not when the value of the options are changed.

     

       697
       697
       +
            These options will never delete existing databases and users, especially

     

       698
       698
       +
            not when the value of the options are changed.

     

       597
       699
        
           </para>

     

       598
       700
        
           <para>

     

       599
       599
       -
            The MySQL users will be identified using <link xlink:href="https://mariadb.com/kb/en/library/authentication-plugin-unix-socket/"> Unix socket authentication</link>. This authenticates the Unix user with the same name only, and that without the need for a password.

     

       701
       701
       +
            The MySQL users will be identified using

     

       702
       702
       +
            <link xlink:href="https://mariadb.com/kb/en/library/authentication-plugin-unix-socket/">

     

       703
       703
       +
            Unix socket authentication</link>. This authenticates the Unix user with

     

       704
       704
       +
            the same name only, and that without the need for a password.

     

       600
       705
        
           </para>

     

       601
       706
        
           <para>

     

       602
       602
       -
            If you have previously created a MySQL <literal>root</literal> user <emphasis>with a password</emphasis>, you will need to add <literal>root</literal> user for unix socket authentication before using the new options. This can be done by running the following SQL script:

     

       707
       707
       +
            If you have previously created a MySQL <literal>root</literal> user

     

       708
       708
       +
            <emphasis>with a password</emphasis>, you will need to add

     

       709
       709
       +
            <literal>root</literal> user for unix socket authentication before using

     

       710
       710
       +
            the new options. This can be done by running the following SQL script:

     

       603
       711
        
       <programlisting language="sql">

     

       604
       712
        
       CREATE USER 'root'@'%' IDENTIFIED BY '';

     

       605
       713
        
       GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;

     
···

       612
       720
        
          </listitem>

     

       613
       721
        
          <listitem>

     

       614
       722
        
           <para>

     

       615
       615
       -
            <literal>services.mysqlBackup</literal> now works by default without any user setup, including for users other than <literal>mysql</literal>.

     

       723
       723
       +
            <literal>services.mysqlBackup</literal> now works by default without any

     

       724
       724
       +
            user setup, including for users other than <literal>mysql</literal>.

     

       616
       725
        
           </para>

     

       617
       726
        
           <para>

     

       618
       618
       -
            By default, the <literal>mysql</literal> user is no longer the user which performs the backup. Instead a system account <literal>mysqlbackup</literal> is used.

     

       727
       727
       +
            By default, the <literal>mysql</literal> user is no longer the user which

     

       728
       728
       +
            performs the backup. Instead a system account

     

       729
       729
       +
            <literal>mysqlbackup</literal> is used.

     

       619
       730
        
           </para>

     

       620
       731
        
           <para>

     

       621
       621
       -
            The <literal>mysqlBackup</literal> service is also now using systemd timers instead of <literal>cron</literal>.

     

       732
       732
       +
            The <literal>mysqlBackup</literal> service is also now using systemd

     

       733
       733
       +
            timers instead of <literal>cron</literal>.

     

       622
       734
        
           </para>

     

       623
       735
        
           <para>

     

       624
       624
       -
            Therefore, the <literal>services.mysqlBackup.period</literal> option no longer exists, and has been replaced with <literal>services.mysqlBackup.calendar</literal>, which is in the format of <link

     

       736
       736
       +
            Therefore, the <literal>services.mysqlBackup.period</literal> option no

     

       737
       737
       +
            longer exists, and has been replaced with

     

       738
       738
       +
            <literal>services.mysqlBackup.calendar</literal>, which is in the format

     

       739
       739
       +
            of

     

       740
       740
       +
            <link

     

       625
       741
        
             xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.time.html#Calendar%20Events">systemd.time(7)</link>.

     

       626
       742
        
           </para>

     

       627
       743
        
           <para>

     

       628
       628
       -
            If you expect to be sent an e-mail when the backup fails, consider using a script which monitors the systemd journal for errors. Regretfully, at present there is no built-in functionality for this.

     

       744
       744
       +
            If you expect to be sent an e-mail when the backup fails, consider using a

     

       745
       745
       +
            script which monitors the systemd journal for errors. Regretfully, at

     

       746
       746
       +
            present there is no built-in functionality for this.

     

       629
       747
        
           </para>

     

       630
       748
        
           <para>

     

       631
       631
       -
            You can check that backups still work by running <command>systemctl start mysql-backup</command> then <command>systemctl status mysql-backup</command>.

     

       749
       749
       +
            You can check that backups still work by running <command>systemctl start

     

       750
       750
       +
            mysql-backup</command> then <command>systemctl status

     

       751
       751
       +
            mysql-backup</command>.

     

       632
       752
        
           </para>

     

       633
       753
        
          </listitem>

     

       634
       754
        
          <listitem>

     

       635
       755
        
           <para>

     

       636
       636
       -
            Templated systemd services e.g <literal>container@name</literal> are now handled currectly when switching to a new configuration, resulting in them being reloaded.

     

       756
       756
       +
            Templated systemd services e.g <literal>container@name</literal> are now

     

       757
       757
       +
            handled currectly when switching to a new configuration, resulting in them

     

       758
       758
       +
            being reloaded.

     

       637
       759
        
           </para>

     

       638
       760
        
          </listitem>

     

       639
       761
        
          <listitem>

     

       640
       762
        
           <para>

     

       641
       641
       -
            Steam: the <literal>newStdcpp</literal> parameter was removed and should not be needed anymore.

     

       763
       763
       +
            Steam: the <literal>newStdcpp</literal> parameter was removed and should

     

       764
       764
       +
            not be needed anymore.

     

       642
       765
        
           </para>

     

       643
       766
        
          </listitem>

     

       644
       767
        
          <listitem>

     

       645
       768
        
           <para>

     

       646
       646
       -
            Redis has been updated to version 4 which mandates a cluster mass-restart, due to changes in the network handling, in order to ensure compatibility with networks NATing traffic.

     

       769
       769
       +
            Redis has been updated to version 4 which mandates a cluster mass-restart,

     

       770
       770
       +
            due to changes in the network handling, in order to ensure compatibility

     

       771
       771
       +
            with networks NATing traffic.

     

       647
       772
        
           </para>

     

       648
       773
        
          </listitem>

     

       649
       774
        
         </itemizedlist>

     
···

       659
       784
        
         <itemizedlist>

     

       660
       785
        
          <listitem>

     

       661
       786
        
           <para>

     

       662
       662
       -
            Modules can now be disabled by using <link

     

       663
       663
       -
             xlink:href="https://nixos.org/nixpkgs/manual/#sec-replace-modules"> disabledModules</link>, allowing another to take it's place. This can be used to import a set of modules from another channel while keeping the rest of the system on a stable release.

     

       787
       787
       +
            Modules can now be disabled by using

     

       788
       788
       +
            <link

     

       789
       789
       +
             xlink:href="https://nixos.org/nixpkgs/manual/#sec-replace-modules">

     

       790
       790
       +
            disabledModules</link>, allowing another to take it's place. This can be

     

       791
       791
       +
            used to import a set of modules from another channel while keeping the

     

       792
       792
       +
            rest of the system on a stable release.

     

       664
       793
        
           </para>

     

       665
       794
        
          </listitem>

     

       666
       795
        
          <listitem>

     

       667
       796
        
           <para>

     

       668
       668
       -
            Updated to FreeType 2.7.1, including a new TrueType engine. The new engine replaces the Infinality engine which was the default in NixOS. The default font rendering settings are now provided by fontconfig-penultimate, replacing fontconfig-ultimate; the new defaults are less invasive and provide rendering that is more consistent with other systems and hopefully with each font designer's intent. Some system-wide configuration has been removed from the Fontconfig NixOS module where user Fontconfig settings are available.

     

       797
       797
       +
            Updated to FreeType 2.7.1, including a new TrueType engine. The new engine

     

       798
       798
       +
            replaces the Infinality engine which was the default in NixOS. The default

     

       799
       799
       +
            font rendering settings are now provided by fontconfig-penultimate,

     

       800
       800
       +
            replacing fontconfig-ultimate; the new defaults are less invasive and

     

       801
       801
       +
            provide rendering that is more consistent with other systems and hopefully

     

       802
       802
       +
            with each font designer's intent. Some system-wide configuration has been

     

       803
       803
       +
            removed from the Fontconfig NixOS module where user Fontconfig settings

     

       804
       804
       +
            are available.

     

       669
       805
        
           </para>

     

       670
       806
        
          </listitem>

     

       671
       807
        
          <listitem>

     

       672
       808
        
           <para>

     

       673
       673
       -
            ZFS/SPL have been updated to 0.7.0, <literal>zfsUnstable, splUnstable</literal> have therefore been removed.

     

       809
       809
       +
            ZFS/SPL have been updated to 0.7.0, <literal>zfsUnstable,

     

       810
       810
       +
            splUnstable</literal> have therefore been removed.

     

       674
       811
        
           </para>

     

       675
       812
        
          </listitem>

     

       676
       813
        
          <listitem>

     

       677
       814
        
           <para>

     

       678
       678
       -
            The <option>time.timeZone</option> option now allows the value <literal>null</literal> in addition to timezone strings. This value allows changing the timezone of a system imperatively using <command>timedatectl set-timezone</command>. The default timezone is still UTC.

     

       815
       815
       +
            The <option>time.timeZone</option> option now allows the value

     

       816
       816
       +
            <literal>null</literal> in addition to timezone strings. This value allows

     

       817
       817
       +
            changing the timezone of a system imperatively using <command>timedatectl

     

       818
       818
       +
            set-timezone</command>. The default timezone is still UTC.

     

       679
       819
        
           </para>

     

       680
       820
        
          </listitem>

     

       681
       821
        
          <listitem>

     

       682
       822
        
           <para>

     

       683
       683
       -
            Nixpkgs overlays may now be specified with a file as well as a directory. The value of <literal>&lt;nixpkgs-overlays></literal> may be a file, and <filename>~/.config/nixpkgs/overlays.nix</filename> can be used instead of the <filename>~/.config/nixpkgs/overlays</filename> directory.

     

       823
       823
       +
            Nixpkgs overlays may now be specified with a file as well as a directory.

     

       824
       824
       +
            The value of <literal>&lt;nixpkgs-overlays></literal> may be a file, and

     

       825
       825
       +
            <filename>~/.config/nixpkgs/overlays.nix</filename> can be used instead of

     

       826
       826
       +
            the <filename>~/.config/nixpkgs/overlays</filename> directory.

     

       684
       827
        
           </para>

     

       685
       828
        
           <para>

     

       686
       829
        
            See the overlays chapter of the Nixpkgs manual for more details.

     
···

       688
       831
        
          </listitem>

     

       689
       832
        
          <listitem>

     

       690
       833
        
           <para>

     

       691
       691
       -
            Definitions for <filename>/etc/hosts</filename> can now be specified declaratively with <literal>networking.hosts</literal>.

     

       834
       834
       +
            Definitions for <filename>/etc/hosts</filename> can now be specified

     

       835
       835
       +
            declaratively with <literal>networking.hosts</literal>.

     

       692
       836
        
           </para>

     

       693
       837
        
          </listitem>

     

       694
       838
        
          <listitem>

     

       695
       839
        
           <para>

     

       696
       696
       -
            Two new options have been added to the installer loader, in addition to the default having changed. The kernel log verbosity has been lowered to the upstream default for the default options, in order to not spam the console when e.g. joining a network.

     

       840
       840
       +
            Two new options have been added to the installer loader, in addition to

     

       841
       841
       +
            the default having changed. The kernel log verbosity has been lowered to

     

       842
       842
       +
            the upstream default for the default options, in order to not spam the

     

       843
       843
       +
            console when e.g. joining a network.

     

       697
       844
        
           </para>

     

       698
       845
        
           <para>

     

       699
       699
       -
            This therefore leads to adding a new <literal>debug</literal> option to set the log level to the previous verbose mode, to make debugging easier, but still accessible easily.

     

       846
       846
       +
            This therefore leads to adding a new <literal>debug</literal> option to

     

       847
       847
       +
            set the log level to the previous verbose mode, to make debugging easier,

     

       848
       848
       +
            but still accessible easily.

     

       700
       849
        
           </para>

     

       701
       850
        
           <para>

     

       702
       702
       -
            Additionally a <literal>copytoram</literal> option has been added, which makes it possible to remove the install medium after booting. This allows tethering from your phone after booting from it.

     

       851
       851
       +
            Additionally a <literal>copytoram</literal> option has been added, which

     

       852
       852
       +
            makes it possible to remove the install medium after booting. This allows

     

       853
       853
       +
            tethering from your phone after booting from it.

     

       703
       854
        
           </para>

     

       704
       855
        
          </listitem>

     

       705
       856
        
          <listitem>

     

       706
       857
        
           <para>

     

       707
       707
       -
            <literal>services.gitlab-runner.configOptions</literal> has been added to specify the configuration of gitlab-runners declaratively.

     

       858
       858
       +
            <literal>services.gitlab-runner.configOptions</literal> has been added to

     

       859
       859
       +
            specify the configuration of gitlab-runners declaratively.

     

       708
       860
        
           </para>

     

       709
       861
        
          </listitem>

     

       710
       862
        
          <listitem>

     

       711
       863
        
           <para>

     

       712
       712
       -
            <literal>services.jenkins.plugins</literal> has been added to install plugins easily, this can be generated with jenkinsPlugins2nix.

     

       864
       864
       +
            <literal>services.jenkins.plugins</literal> has been added to install

     

       865
       865
       +
            plugins easily, this can be generated with jenkinsPlugins2nix.

     

       713
       866
        
           </para>

     

       714
       867
        
          </listitem>

     

       715
       868
        
          <listitem>

     

       716
       869
        
           <para>

     

       717
       717
       -
            <literal>services.postfix.config</literal> has been added to specify the main.cf with NixOS options. Additionally other options have been added to the postfix module and has been improved further.

     

       870
       870
       +
            <literal>services.postfix.config</literal> has been added to specify the

     

       871
       871
       +
            main.cf with NixOS options. Additionally other options have been added to

     

       872
       872
       +
            the postfix module and has been improved further.

     

       718
       873
        
           </para>

     

       719
       874
        
          </listitem>

     

       720
       875
        
          <listitem>

     

       721
       876
        
           <para>

     

       722
       722
       -
            The GitLab package and module have been updated to the latest 10.0 release.

     

       877
       877
       +
            The GitLab package and module have been updated to the latest 10.0

     

       878
       878
       +
            release.

     

       723
       879
        
           </para>

     

       724
       880
        
          </listitem>

     

       725
       881
        
          <listitem>

     

       726
       882
        
           <para>

     

       727
       727
       -
            The <literal>systemd-boot</literal> boot loader now lists the NixOS version, kernel version and build date of all bootable generations.

     

       883
       883
       +
            The <literal>systemd-boot</literal> boot loader now lists the NixOS

     

       884
       884
       +
            version, kernel version and build date of all bootable generations.

     

       728
       885
        
           </para>

     

       729
       886
        
          </listitem>

     

       730
       887
        
          <listitem>

     

       731
       888
        
           <para>

     

       732
       732
       -
            The dnscrypt-proxy service now defaults to using a random upstream resolver, selected from the list of public non-logging resolvers with DNSSEC support. Existing configurations can be migrated to this mode of operation by omitting the <option>services.dnscrypt-proxy.resolverName</option> option or setting it to <literal>"random"</literal>.

     

       889
       889
       +
            The dnscrypt-proxy service now defaults to using a random upstream

     

       890
       890
       +
            resolver, selected from the list of public non-logging resolvers with

     

       891
       891
       +
            DNSSEC support. Existing configurations can be migrated to this mode of

     

       892
       892
       +
            operation by omitting the

     

       893
       893
       +
            <option>services.dnscrypt-proxy.resolverName</option> option or setting it

     

       894
       894
       +
            to <literal>"random"</literal>.

     

       733
       895
        
           </para>

     

       734
       896
        
          </listitem>

     

       735
       897
        
         </itemizedlist>

+210 -56

nixos/doc/manual/release-notes/rl-1803.xml

···

       13
       13
        
         <title>Highlights</title>

     

       14
       14
        
       

     

       15
       15
        
         <para>

     

       16
       16
       -
          In addition to numerous new and upgraded packages, this release has the following highlights:

     

       16
       16
       +
          In addition to numerous new and upgraded packages, this release has the

     

       17
       17
       +
          following highlights:

     

       17
       18
        
         </para>

     

       18
       19
        
       

     

       19
       20
        
         <itemizedlist>

     
···

       24
       25
        
          </listitem>

     

       25
       26
        
          <listitem>

     

       26
       27
        
           <para>

     

       27
       27
       -
            Platform support: x86_64-linux and x86_64-darwin since release time (the latter isn't NixOS, really). Binaries for aarch64-linux are available, but no channel exists yet, as it's waiting for some test fixes, etc.

     

       28
       28
       +
            Platform support: x86_64-linux and x86_64-darwin since release time (the

     

       29
       29
       +
            latter isn't NixOS, really). Binaries for aarch64-linux are available, but

     

       30
       30
       +
            no channel exists yet, as it's waiting for some test fixes, etc.

     

       28
       31
        
           </para>

     

       29
       32
        
          </listitem>

     

       30
       33
        
          <listitem>

     

       31
       34
        
           <para>

     

       32
       32
       -
            Nix now defaults to 2.0; see its <link xlink:href="https://nixos.org/nix/manual/#ssec-relnotes-2.0">release notes</link>.

     

       35
       35
       +
            Nix now defaults to 2.0; see its

     

       36
       36
       +
            <link xlink:href="https://nixos.org/nix/manual/#ssec-relnotes-2.0">release

     

       37
       37
       +
            notes</link>.

     

       33
       38
        
           </para>

     

       34
       39
        
          </listitem>

     

       35
       40
        
          <listitem>

     

       36
       41
        
           <para>

     

       37
       37
       -
            Core version changes: linux: 4.9 -> 4.14, glibc: 2.25 -> 2.26, gcc: 6 -> 7, systemd: 234 -> 237.

     

       42
       42
       +
            Core version changes: linux: 4.9 -> 4.14, glibc: 2.25 -> 2.26, gcc: 6 ->

     

       43
       43
       +
            7, systemd: 234 -> 237.

     

       38
       44
        
           </para>

     

       39
       45
        
          </listitem>

     

       40
       46
        
          <listitem>

     

       41
       47
        
           <para>

     

       42
       42
       -
            Desktop version changes: gnome: 3.24 -> 3.26, (KDE) plasma-desktop: 5.10 -> 5.12.

     

       48
       48
       +
            Desktop version changes: gnome: 3.24 -> 3.26, (KDE) plasma-desktop: 5.10

     

       49
       49
       +
            -> 5.12.

     

       43
       50
        
           </para>

     

       44
       51
        
          </listitem>

     

       45
       52
        
          <listitem>

     

       46
       53
        
           <para>

     

       47
       47
       -
            MariaDB 10.2, updated from 10.1, is now the default MySQL implementation. While upgrading a few changes have been made to the infrastructure involved:

     

       54
       54
       +
            MariaDB 10.2, updated from 10.1, is now the default MySQL implementation.

     

       55
       55
       +
            While upgrading a few changes have been made to the infrastructure

     

       56
       56
       +
            involved:

     

       48
       57
        
            <itemizedlist>

     

       49
       58
        
             <listitem>

     

       50
       59
        
              <para>

     

       51
       51
       -
               <literal>libmysql</literal> has been deprecated, please use <literal>mysql.connector-c</literal> instead, a compatibility passthru has been added to the MySQL packages.

     

       60
       60
       +
               <literal>libmysql</literal> has been deprecated, please use

     

       61
       61
       +
               <literal>mysql.connector-c</literal> instead, a compatibility passthru

     

       62
       62
       +
               has been added to the MySQL packages.

     

       52
       63
        
              </para>

     

       53
       64
        
             </listitem>

     

       54
       65
        
             <listitem>

     

       55
       66
        
              <para>

     

       56
       56
       -
               The <literal>mysql57</literal> package has a new <literal>static</literal> output containing the static libraries including <literal>libmysqld.a</literal>

     

       67
       67
       +
               The <literal>mysql57</literal> package has a new

     

       68
       68
       +
               <literal>static</literal> output containing the static libraries

     

       69
       69
       +
               including <literal>libmysqld.a</literal>

     

       57
       70
        
              </para>

     

       58
       71
        
             </listitem>

     

       59
       72
        
            </itemizedlist>

     
···

       390
       403
        
         <title>Backward Incompatibilities</title>

     

       391
       404
        
       

     

       392
       405
        
         <para>

     

       393
       393
       -
          When upgrading from a previous release, please be aware of the following incompatible changes:

     

       406
       406
       +
          When upgrading from a previous release, please be aware of the following

     

       407
       407
       +
          incompatible changes:

     

       394
       408
        
         </para>

     

       395
       409
        
       

     

       396
       410
        
         <itemizedlist>

     
···

       401
       415
        
          </listitem>

     

       402
       416
        
          <listitem>

     

       403
       417
        
           <para>

     

       404
       404
       -
            Dollar signs in options under <option>services.postfix</option> are passed verbatim to Postfix, which will interpret them as the beginning of a parameter expression. This was already true for string-valued options in the previous release, but not for list-valued options. If you need to pass literal dollar signs through Postfix, double them.

     

       418
       418
       +
            Dollar signs in options under <option>services.postfix</option> are passed

     

       419
       419
       +
            verbatim to Postfix, which will interpret them as the beginning of a

     

       420
       420
       +
            parameter expression. This was already true for string-valued options in

     

       421
       421
       +
            the previous release, but not for list-valued options. If you need to pass

     

       422
       422
       +
            literal dollar signs through Postfix, double them.

     

       405
       423
        
           </para>

     

       406
       424
        
          </listitem>

     

       407
       425
        
          <listitem>

     

       408
       426
        
           <para>

     

       409
       409
       -
            The <literal>postage</literal> package (for web-based PostgreSQL administration) has been renamed to <literal>pgmanage</literal>. The corresponding module has also been renamed. To migrate please rename all <option>services.postage</option> options to <option>services.pgmanage</option>.

     

       427
       427
       +
            The <literal>postage</literal> package (for web-based PostgreSQL

     

       428
       428
       +
            administration) has been renamed to <literal>pgmanage</literal>. The

     

       429
       429
       +
            corresponding module has also been renamed. To migrate please rename all

     

       430
       430
       +
            <option>services.postage</option> options to

     

       431
       431
       +
            <option>services.pgmanage</option>.

     

       410
       432
        
           </para>

     

       411
       433
        
          </listitem>

     

       412
       434
        
          <listitem>

     

       413
       435
        
           <para>

     

       414
       414
       -
            Package attributes starting with a digit have been prefixed with an underscore sign. This is to avoid quoting in the configuration and other issues with command-line tools like <literal>nix-env</literal>. The change affects the following packages:

     

       436
       436
       +
            Package attributes starting with a digit have been prefixed with an

     

       437
       437
       +
            underscore sign. This is to avoid quoting in the configuration and other

     

       438
       438
       +
            issues with command-line tools like <literal>nix-env</literal>. The change

     

       439
       439
       +
            affects the following packages:

     

       415
       440
        
            <itemizedlist>

     

       416
       441
        
             <listitem>

     

       417
       442
        
              <para>

     

       418
       418
       -
               <literal>2048-in-terminal</literal> → <literal>_2048-in-terminal</literal>

     

       443
       443
       +
               <literal>2048-in-terminal</literal> →

     

       444
       444
       +
               <literal>_2048-in-terminal</literal>

     

       419
       445
        
              </para>

     

       420
       446
        
             </listitem>

     

       421
       447
        
             <listitem>

     

       422
       448
        
              <para>

     

       423
       423
       -
               <literal>90secondportraits</literal> → <literal>_90secondportraits</literal>

     

       449
       449
       +
               <literal>90secondportraits</literal> →

     

       450
       450
       +
               <literal>_90secondportraits</literal>

     

       424
       451
        
              </para>

     

       425
       452
        
             </listitem>

     

       426
       453
        
             <listitem>

     
···

       438
       465
        
          </listitem>

     

       439
       466
        
          <listitem>

     

       440
       467
        
           <para>

     

       441
       441
       -
            <emphasis role="strong"> The OpenSSH service no longer enables support for DSA keys by default, which could cause a system lock out. Update your keys or, unfavorably, re-enable DSA support manually. </emphasis>

     

       468
       468
       +
            <emphasis role="strong"> The OpenSSH service no longer enables support for

     

       469
       469
       +
            DSA keys by default, which could cause a system lock out. Update your keys

     

       470
       470
       +
            or, unfavorably, re-enable DSA support manually. </emphasis>

     

       442
       471
        
           </para>

     

       443
       472
        
           <para>

     

       444
       444
       -
            DSA support was <link xlink:href="https://www.openssh.com/legacy.html">deprecated in OpenSSH 7.0</link>, due to it being too weak. To re-enable support, add <literal>PubkeyAcceptedKeyTypes +ssh-dss</literal> to the end of your <option>services.openssh.extraConfig</option>.

     

       473
       473
       +
            DSA support was

     

       474
       474
       +
            <link xlink:href="https://www.openssh.com/legacy.html">deprecated in

     

       475
       475
       +
            OpenSSH 7.0</link>, due to it being too weak. To re-enable support, add

     

       476
       476
       +
            <literal>PubkeyAcceptedKeyTypes +ssh-dss</literal> to the end of your

     

       477
       477
       +
            <option>services.openssh.extraConfig</option>.

     

       445
       478
        
           </para>

     

       446
       479
        
           <para>

     

       447
       447
       -
            After updating the keys to be stronger, anyone still on a pre-17.03 version is safe to jump to 17.03, as vetted <link xlink:href="https://search.nix.gsc.io/?q=stateVersion">here</link>.

     

       480
       480
       +
            After updating the keys to be stronger, anyone still on a pre-17.03

     

       481
       481
       +
            version is safe to jump to 17.03, as vetted

     

       482
       482
       +
            <link xlink:href="https://search.nix.gsc.io/?q=stateVersion">here</link>.

     

       448
       483
        
           </para>

     

       449
       484
        
          </listitem>

     

       450
       485
        
          <listitem>

     

       451
       486
        
           <para>

     

       452
       452
       -
            The <literal>openssh</literal> package now includes Kerberos support by default; the <literal>openssh_with_kerberos</literal> package is now a deprecated alias. If you do not want Kerberos support, you can do <literal>openssh.override { withKerberos = false; }</literal>. Note, this also applies to the <literal>openssh_hpn</literal> package.

     

       487
       487
       +
            The <literal>openssh</literal> package now includes Kerberos support by

     

       488
       488
       +
            default; the <literal>openssh_with_kerberos</literal> package is now a

     

       489
       489
       +
            deprecated alias. If you do not want Kerberos support, you can do

     

       490
       490
       +
            <literal>openssh.override { withKerberos = false; }</literal>. Note, this

     

       491
       491
       +
            also applies to the <literal>openssh_hpn</literal> package.

     

       453
       492
        
           </para>

     

       454
       493
        
          </listitem>

     

       455
       494
        
          <listitem>

     

       456
       495
        
           <para>

     

       457
       457
       -
            <literal>cc-wrapper</literal> has been split in two; there is now also a <literal>bintools-wrapper</literal>. The most commonly used files in <filename>nix-support</filename> are now split between the two wrappers. Some commonly used ones, like <filename>nix-support/dynamic-linker</filename>, are duplicated for backwards compatability, even though they rightly belong only in <literal>bintools-wrapper</literal>. Other more obscure ones are just moved.

     

       496
       496
       +
            <literal>cc-wrapper</literal> has been split in two; there is now also a

     

       497
       497
       +
            <literal>bintools-wrapper</literal>. The most commonly used files in

     

       498
       498
       +
            <filename>nix-support</filename> are now split between the two wrappers.

     

       499
       499
       +
            Some commonly used ones, like

     

       500
       500
       +
            <filename>nix-support/dynamic-linker</filename>, are duplicated for

     

       501
       501
       +
            backwards compatability, even though they rightly belong only in

     

       502
       502
       +
            <literal>bintools-wrapper</literal>. Other more obscure ones are just

     

       503
       503
       +
            moved.

     

       458
       504
        
           </para>

     

       459
       505
        
          </listitem>

     

       460
       506
        
          <listitem>

     

       461
       507
        
           <para>

     

       462
       462
       -
            The propagation logic has been changed. The new logic, along with new types of dependencies that go with, is thoroughly documented in the "Specifying dependencies" section of the "Standard Environment" chapter of the nixpkgs manual.

     

       508
       508
       +
            The propagation logic has been changed. The new logic, along with new

     

       509
       509
       +
            types of dependencies that go with, is thoroughly documented in the

     

       510
       510
       +
            "Specifying dependencies" section of the "Standard Environment" chapter of

     

       511
       511
       +
            the nixpkgs manual.

     

       463
       512
        
       <!-- That's <xref linkend="ssec-stdenv-attributes"> were we to merge the manuals. -->

     

       464
       464
       -
            The old logic isn't but is easy to describe: dependencies were propagated as the same type of dependency no matter what. In practice, that means that many <function>propagatedNativeBuildInputs</function> should instead be <function>propagatedBuildInputs</function>. Thankfully, that was and is the least used type of dependency. Also, it means that some <function>propagatedBuildInputs</function> should instead be <function>depsTargetTargetPropagated</function>. Other types dependencies should be unaffected.

     

       513
       513
       +
            The old logic isn't but is easy to describe: dependencies were propagated

     

       514
       514
       +
            as the same type of dependency no matter what. In practice, that means

     

       515
       515
       +
            that many <function>propagatedNativeBuildInputs</function> should instead

     

       516
       516
       +
            be <function>propagatedBuildInputs</function>. Thankfully, that was and is

     

       517
       517
       +
            the least used type of dependency. Also, it means that some

     

       518
       518
       +
            <function>propagatedBuildInputs</function> should instead be

     

       519
       519
       +
            <function>depsTargetTargetPropagated</function>. Other types dependencies

     

       520
       520
       +
            should be unaffected.

     

       465
       521
        
           </para>

     

       466
       522
        
          </listitem>

     

       467
       523
        
          <listitem>

     

       468
       524
        
           <para>

     

       469
       469
       -
            <literal>lib.addPassthru drv passthru</literal> is removed. Use <literal>lib.extendDerivation true passthru drv</literal> instead.

     

       525
       525
       +
            <literal>lib.addPassthru drv passthru</literal> is removed. Use

     

       526
       526
       +
            <literal>lib.extendDerivation true passthru drv</literal> instead.

     

       470
       527
        
           </para>

     

       471
       528
        
          </listitem>

     

       472
       529
        
          <listitem>

     

       473
       530
        
           <para>

     

       474
       474
       -
            The <literal>memcached</literal> service no longer accept dynamic socket paths via <option>services.memcached.socket</option>. Unix sockets can be still enabled by <option>services.memcached.enableUnixSocket</option> and will be accessible at <literal>/run/memcached/memcached.sock</literal>.

     

       531
       531
       +
            The <literal>memcached</literal> service no longer accept dynamic socket

     

       532
       532
       +
            paths via <option>services.memcached.socket</option>. Unix sockets can be

     

       533
       533
       +
            still enabled by <option>services.memcached.enableUnixSocket</option> and

     

       534
       534
       +
            will be accessible at <literal>/run/memcached/memcached.sock</literal>.

     

       475
       535
        
           </para>

     

       476
       536
        
          </listitem>

     

       477
       537
        
          <listitem>

     

       478
       538
        
           <para>

     

       479
       479
       -
            The <varname>hardware.amdHybridGraphics.disable</varname> option was removed for lack of a maintainer. If you still need this module, you may wish to include a copy of it from an older version of nixos in your imports.

     

       539
       539
       +
            The <varname>hardware.amdHybridGraphics.disable</varname> option was

     

       540
       540
       +
            removed for lack of a maintainer. If you still need this module, you may

     

       541
       541
       +
            wish to include a copy of it from an older version of nixos in your

     

       542
       542
       +
            imports.

     

       480
       543
        
           </para>

     

       481
       544
        
          </listitem>

     

       482
       545
        
          <listitem>

     

       483
       546
        
           <para>

     

       484
       484
       -
            The merging of config options for <varname>services.postfix.config</varname> was buggy. Previously, if other options in the Postfix module like <varname>services.postfix.useSrs</varname> were set and the user set config options that were also set by such options, the resulting config wouldn't include all options that were needed. They are now merged correctly. If config options need to be overridden, <literal>lib.mkForce</literal> or <literal>lib.mkOverride</literal> can be used.

     

       547
       547
       +
            The merging of config options for

     

       548
       548
       +
            <varname>services.postfix.config</varname> was buggy. Previously, if other

     

       549
       549
       +
            options in the Postfix module like

     

       550
       550
       +
            <varname>services.postfix.useSrs</varname> were set and the user set

     

       551
       551
       +
            config options that were also set by such options, the resulting config

     

       552
       552
       +
            wouldn't include all options that were needed. They are now merged

     

       553
       553
       +
            correctly. If config options need to be overridden,

     

       554
       554
       +
            <literal>lib.mkForce</literal> or <literal>lib.mkOverride</literal> can be

     

       555
       555
       +
            used.

     

       485
       556
        
           </para>

     

       486
       557
        
          </listitem>

     

       487
       558
        
          <listitem>

     

       488
       559
        
           <para>

     

       489
       489
       -
            The following changes apply if the <literal>stateVersion</literal> is changed to 18.03 or higher. For <literal>stateVersion = "17.09"</literal> or lower the old behavior is preserved.

     

       560
       560
       +
            The following changes apply if the <literal>stateVersion</literal> is

     

       561
       561
       +
            changed to 18.03 or higher. For <literal>stateVersion = "17.09"</literal>

     

       562
       562
       +
            or lower the old behavior is preserved.

     

       490
       563
        
           </para>

     

       491
       564
        
           <itemizedlist>

     

       492
       565
        
            <listitem>

     

       493
       566
        
             <para>

     

       494
       494
       -
              <literal>matrix-synapse</literal> uses postgresql by default instead of sqlite. Migration instructions can be found <link xlink:href="https://github.com/matrix-org/synapse/blob/master/docs/postgres.rst#porting-from-sqlite"> here </link>.

     

       567
       567
       +
              <literal>matrix-synapse</literal> uses postgresql by default instead of

     

       568
       568
       +
              sqlite. Migration instructions can be found

     

       569
       569
       +
              <link xlink:href="https://github.com/matrix-org/synapse/blob/master/docs/postgres.rst#porting-from-sqlite">

     

       570
       570
       +
              here </link>.

     

       495
       571
        
             </para>

     

       496
       572
        
            </listitem>

     

       497
       573
        
           </itemizedlist>

     

       498
       574
        
          </listitem>

     

       499
       575
        
          <listitem>

     

       500
       576
        
           <para>

     

       501
       501
       -
            The <literal>jid</literal> package has been removed, due to maintenance overhead of a go package having non-versioned dependencies.

     

       577
       577
       +
            The <literal>jid</literal> package has been removed, due to maintenance

     

       578
       578
       +
            overhead of a go package having non-versioned dependencies.

     

       502
       579
        
           </para>

     

       503
       580
        
          </listitem>

     

       504
       581
        
          <listitem>

     

       505
       582
        
           <para>

     

       506
       506
       -
            When using <option>services.xserver.libinput</option> (enabled by default in GNOME), it now handles all input devices, not just touchpads. As a result, you might need to re-evaluate any custom Xorg configuration. In particular, <literal>Option "XkbRules" "base"</literal> may result in broken keyboard layout.

     

       583
       583
       +
            When using <option>services.xserver.libinput</option> (enabled by default

     

       584
       584
       +
            in GNOME), it now handles all input devices, not just touchpads. As a

     

       585
       585
       +
            result, you might need to re-evaluate any custom Xorg configuration. In

     

       586
       586
       +
            particular, <literal>Option "XkbRules" "base"</literal> may result in

     

       587
       587
       +
            broken keyboard layout.

     

       507
       588
        
           </para>

     

       508
       589
        
          </listitem>

     

       509
       590
        
          <listitem>

     

       510
       591
        
           <para>

     

       511
       511
       -
            The <literal>attic</literal> package was removed. A maintained fork called <link xlink:href="https://www.borgbackup.org/">Borg</link> should be used instead. Migration instructions can be found <link xlink:href="http://borgbackup.readthedocs.io/en/stable/usage/upgrade.html#attic-and-borg-0-xx-to-borg-1-x">here</link>.

     

       592
       592
       +
            The <literal>attic</literal> package was removed. A maintained fork called

     

       593
       593
       +
            <link xlink:href="https://www.borgbackup.org/">Borg</link> should be used

     

       594
       594
       +
            instead. Migration instructions can be found

     

       595
       595
       +
            <link xlink:href="http://borgbackup.readthedocs.io/en/stable/usage/upgrade.html#attic-and-borg-0-xx-to-borg-1-x">here</link>.

     

       512
       596
        
           </para>

     

       513
       597
        
          </listitem>

     

       514
       598
        
          <listitem>

     
···

       517
       601
        
            <itemizedlist>

     

       518
       602
        
             <listitem>

     

       519
       603
        
              <para>

     

       520
       520
       -
               The package <literal>pkgs.piwik</literal> was renamed to <literal>pkgs.matomo</literal>.

     

       604
       604
       +
               The package <literal>pkgs.piwik</literal> was renamed to

     

       605
       605
       +
               <literal>pkgs.matomo</literal>.

     

       521
       606
        
              </para>

     

       522
       607
        
             </listitem>

     

       523
       608
        
             <listitem>

     

       524
       609
        
              <para>

     

       525
       525
       -
               The service <literal>services.piwik</literal> was renamed to <literal>services.matomo</literal>.

     

       610
       610
       +
               The service <literal>services.piwik</literal> was renamed to

     

       611
       611
       +
               <literal>services.matomo</literal>.

     

       526
       612
        
              </para>

     

       527
       613
        
             </listitem>

     

       528
       614
        
             <listitem>

     

       529
       615
        
              <para>

     

       530
       530
       -
               The data directory <filename>/var/lib/piwik</filename> was renamed to <filename>/var/lib/matomo</filename>. All files will be moved automatically on first startup, but you might need to adjust your backup scripts.

     

       616
       616
       +
               The data directory <filename>/var/lib/piwik</filename> was renamed to

     

       617
       617
       +
               <filename>/var/lib/matomo</filename>. All files will be moved

     

       618
       618
       +
               automatically on first startup, but you might need to adjust your

     

       619
       619
       +
               backup scripts.

     

       531
       620
        
              </para>

     

       532
       621
        
             </listitem>

     

       533
       622
        
             <listitem>

     

       534
       623
        
              <para>

     

       535
       535
       -
               The default <option>serverName</option> for the nginx configuration changed from <literal>piwik.${config.networking.hostName}</literal> to <literal>matomo.${config.networking.hostName}.${config.networking.domain}</literal> if <option>config.networking.domain</option> is set, <literal>matomo.${config.networking.hostName}</literal> if it is not set. If you change your <option>serverName</option>, remember you'll need to update the <literal>trustedHosts[]</literal> array in <filename>/var/lib/matomo/config/config.ini.php</filename> as well.

     

       624
       624
       +
               The default <option>serverName</option> for the nginx configuration

     

       625
       625
       +
               changed from <literal>piwik.${config.networking.hostName}</literal> to

     

       626
       626
       +
               <literal>matomo.${config.networking.hostName}.${config.networking.domain}</literal>

     

       627
       627
       +
               if <option>config.networking.domain</option> is set,

     

       628
       628
       +
               <literal>matomo.${config.networking.hostName}</literal> if it is not

     

       629
       629
       +
               set. If you change your <option>serverName</option>, remember you'll

     

       630
       630
       +
               need to update the <literal>trustedHosts[]</literal> array in

     

       631
       631
       +
               <filename>/var/lib/matomo/config/config.ini.php</filename> as well.

     

       536
       632
        
              </para>

     

       537
       633
        
             </listitem>

     

       538
       634
        
             <listitem>

     

       539
       635
        
              <para>

     

       540
       540
       -
               The <literal>piwik</literal> user was renamed to <literal>matomo</literal>. The service will adjust ownership automatically for files in the data directory. If you use unix socket authentication, remember to give the new <literal>matomo</literal> user access to the database and to change the <literal>username</literal> to <literal>matomo</literal> in the <literal>[database]</literal> section of <filename>/var/lib/matomo/config/config.ini.php</filename>.

     

       636
       636
       +
               The <literal>piwik</literal> user was renamed to

     

       637
       637
       +
               <literal>matomo</literal>. The service will adjust ownership

     

       638
       638
       +
               automatically for files in the data directory. If you use unix socket

     

       639
       639
       +
               authentication, remember to give the new <literal>matomo</literal> user

     

       640
       640
       +
               access to the database and to change the <literal>username</literal> to

     

       641
       641
       +
               <literal>matomo</literal> in the <literal>[database]</literal> section

     

       642
       642
       +
               of <filename>/var/lib/matomo/config/config.ini.php</filename>.

     

       541
       643
        
              </para>

     

       542
       644
        
             </listitem>

     

       543
       645
        
             <listitem>

     

       544
       646
        
              <para>

     

       545
       545
       -
               If you named your database `piwik`, you might want to rename it to `matomo` to keep things clean, but this is neither enforced nor required.

     

       647
       647
       +
               If you named your database `piwik`, you might want to rename it to

     

       648
       648
       +
               `matomo` to keep things clean, but this is neither enforced nor

     

       649
       649
       +
               required.

     

       546
       650
        
              </para>

     

       547
       651
        
             </listitem>

     

       548
       652
        
            </itemizedlist>

     
···

       550
       654
        
          </listitem>

     

       551
       655
        
          <listitem>

     

       552
       656
        
           <para>

     

       553
       553
       -
            <literal>nodejs-4_x</literal> is end-of-life. <literal>nodejs-4_x</literal>, <literal>nodejs-slim-4_x</literal> and <literal>nodePackages_4_x</literal> are removed.

     

       657
       657
       +
            <literal>nodejs-4_x</literal> is end-of-life.

     

       658
       658
       +
            <literal>nodejs-4_x</literal>, <literal>nodejs-slim-4_x</literal> and

     

       659
       659
       +
            <literal>nodePackages_4_x</literal> are removed.

     

       554
       660
        
           </para>

     

       555
       661
        
          </listitem>

     

       556
       662
        
          <listitem>

     

       557
       663
        
           <para>

     

       558
       558
       -
            The <literal>pump.io</literal> NixOS module was removed. It is now maintained as an <link xlink:href="https://github.com/rvl/pump.io-nixos">external module</link>.

     

       664
       664
       +
            The <literal>pump.io</literal> NixOS module was removed. It is now

     

       665
       665
       +
            maintained as an

     

       666
       666
       +
            <link xlink:href="https://github.com/rvl/pump.io-nixos">external

     

       667
       667
       +
            module</link>.

     

       559
       668
        
           </para>

     

       560
       669
        
          </listitem>

     

       561
       670
        
          <listitem>

     

       562
       671
        
           <para>

     

       563
       563
       -
            The Prosody XMPP server has received a major update. The following modules were renamed:

     

       672
       672
       +
            The Prosody XMPP server has received a major update. The following modules

     

       673
       673
       +
            were renamed:

     

       564
       674
        
            <itemizedlist>

     

       565
       675
        
             <listitem>

     

       566
       676
        
              <para>

     

       567
       567
       -
               <option>services.prosody.modules.httpserver</option> is now <option>services.prosody.modules.http_files</option>

     

       677
       677
       +
               <option>services.prosody.modules.httpserver</option> is now

     

       678
       678
       +
               <option>services.prosody.modules.http_files</option>

     

       568
       679
        
              </para>

     

       569
       680
        
             </listitem>

     

       570
       681
        
             <listitem>

     

       571
       682
        
              <para>

     

       572
       572
       -
               <option>services.prosody.modules.console</option> is now <option>services.prosody.modules.admin_telnet</option>

     

       683
       683
       +
               <option>services.prosody.modules.console</option> is now

     

       684
       684
       +
               <option>services.prosody.modules.admin_telnet</option>

     

       573
       685
        
              </para>

     

       574
       686
        
             </listitem>

     

       575
       687
        
            </itemizedlist>

     

       576
       688
        
           </para>

     

       577
       689
        
           <para>

     

       578
       578
       -
            Many new modules are now core modules, most notably <option>services.prosody.modules.carbons</option> and <option>services.prosody.modules.mam</option>.

     

       690
       690
       +
            Many new modules are now core modules, most notably

     

       691
       691
       +
            <option>services.prosody.modules.carbons</option> and

     

       692
       692
       +
            <option>services.prosody.modules.mam</option>.

     

       579
       693
        
           </para>

     

       580
       694
        
           <para>

     

       581
       581
       -
            The better-performing <literal>libevent</literal> backend is now enabled by default.

     

       695
       695
       +
            The better-performing <literal>libevent</literal> backend is now enabled

     

       696
       696
       +
            by default.

     

       582
       697
        
           </para>

     

       583
       698
        
           <para>

     

       584
       584
       -
            <literal>withCommunityModules</literal> now passes through the modules to <option>services.prosody.extraModules</option>. Use <literal>withOnlyInstalledCommunityModules</literal> for modules that should not be enabled directly, e.g <literal>lib_ldap</literal>.

     

       699
       699
       +
            <literal>withCommunityModules</literal> now passes through the modules to

     

       700
       700
       +
            <option>services.prosody.extraModules</option>. Use

     

       701
       701
       +
            <literal>withOnlyInstalledCommunityModules</literal> for modules that

     

       702
       702
       +
            should not be enabled directly, e.g <literal>lib_ldap</literal>.

     

       585
       703
        
           </para>

     

       586
       704
        
          </listitem>

     

       587
       705
        
          <listitem>

     

       588
       706
        
           <para>

     

       589
       589
       -
            All prometheus exporter modules are now defined as submodules. The exporters are configured using <literal>services.prometheus.exporters</literal>.

     

       707
       707
       +
            All prometheus exporter modules are now defined as submodules. The

     

       708
       708
       +
            exporters are configured using

     

       709
       709
       +
            <literal>services.prometheus.exporters</literal>.

     

       590
       710
        
           </para>

     

       591
       711
        
          </listitem>

     

       592
       712
        
         </itemizedlist>

     
···

       602
       722
        
         <itemizedlist>

     

       603
       723
        
          <listitem>

     

       604
       724
        
           <para>

     

       605
       605
       -
            ZNC option <option>services.znc.mutable</option> now defaults to <literal>true</literal>. That means that old configuration is not overwritten by default when update to the znc options are made.

     

       725
       725
       +
            ZNC option <option>services.znc.mutable</option> now defaults to

     

       726
       726
       +
            <literal>true</literal>. That means that old configuration is not

     

       727
       727
       +
            overwritten by default when update to the znc options are made.

     

       606
       728
        
           </para>

     

       607
       729
        
          </listitem>

     

       608
       730
        
          <listitem>

     

       609
       731
        
           <para>

     

       610
       610
       -
            The option <option>networking.wireless.networks.&lt;name&gt;.auth</option> has been added for wireless networks with WPA-Enterprise authentication. There is also a new <option>extraConfig</option> option to directly configure <literal>wpa_supplicant</literal> and <option>hidden</option> to connect to hidden networks.

     

       732
       732
       +
            The option <option>networking.wireless.networks.&lt;name&gt;.auth</option>

     

       733
       733
       +
            has been added for wireless networks with WPA-Enterprise authentication.

     

       734
       734
       +
            There is also a new <option>extraConfig</option> option to directly

     

       735
       735
       +
            configure <literal>wpa_supplicant</literal> and <option>hidden</option> to

     

       736
       736
       +
            connect to hidden networks.

     

       611
       737
        
           </para>

     

       612
       738
        
          </listitem>

     

       613
       739
        
          <listitem>

     

       614
       740
        
           <para>

     

       615
       615
       -
            In the module <option>networking.interfaces.&lt;name&gt;</option> the following options have been removed:

     

       741
       741
       +
            In the module <option>networking.interfaces.&lt;name&gt;</option> the

     

       742
       742
       +
            following options have been removed:

     

       616
       743
        
            <itemizedlist>

     

       617
       744
        
             <listitem>

     

       618
       745
        
              <para>

     
···

       640
       767
        
              </para>

     

       641
       768
        
             </listitem>

     

       642
       769
        
            </itemizedlist>

     

       643
       643
       -
            To assign static addresses to an interface the options <option>ipv4.addresses</option> and <option>ipv6.addresses</option> should be used instead. The options <option>ip4</option> and <option>ip6</option> have been renamed to <option>ipv4.addresses</option> <option>ipv6.addresses</option> respectively. The new options <option>ipv4.routes</option> and <option>ipv6.routes</option> have been added to set up static routing.

     

       770
       770
       +
            To assign static addresses to an interface the options

     

       771
       771
       +
            <option>ipv4.addresses</option> and <option>ipv6.addresses</option> should

     

       772
       772
       +
            be used instead. The options <option>ip4</option> and <option>ip6</option>

     

       773
       773
       +
            have been renamed to <option>ipv4.addresses</option>

     

       774
       774
       +
            <option>ipv6.addresses</option> respectively. The new options

     

       775
       775
       +
            <option>ipv4.routes</option> and <option>ipv6.routes</option> have been

     

       776
       776
       +
            added to set up static routing.

     

       644
       777
        
           </para>

     

       645
       778
        
          </listitem>

     

       646
       779
        
          <listitem>

     

       647
       780
        
           <para>

     

       648
       648
       -
            The option <option>services.logstash.listenAddress</option> is now <literal>127.0.0.1</literal> by default. Previously the default behaviour was to listen on all interfaces.

     

       781
       781
       +
            The option <option>services.logstash.listenAddress</option> is now

     

       782
       782
       +
            <literal>127.0.0.1</literal> by default. Previously the default behaviour

     

       783
       783
       +
            was to listen on all interfaces.

     

       649
       784
        
           </para>

     

       650
       785
        
          </listitem>

     

       651
       786
        
          <listitem>

     

       652
       787
        
           <para>

     

       653
       653
       -
            <literal>services.btrfs.autoScrub</literal> has been added, to periodically check btrfs filesystems for data corruption. If there's a correct copy available, it will automatically repair corrupted blocks.

     

       788
       788
       +
            <literal>services.btrfs.autoScrub</literal> has been added, to

     

       789
       789
       +
            periodically check btrfs filesystems for data corruption. If there's a

     

       790
       790
       +
            correct copy available, it will automatically repair corrupted blocks.

     

       654
       791
        
           </para>

     

       655
       792
        
          </listitem>

     

       656
       793
        
          <listitem>

     

       657
       794
        
           <para>

     

       658
       658
       -
            <literal>displayManager.lightdm.greeters.gtk.clock-format.</literal> has been added, the clock format string (as expected by strftime, e.g. <literal>%H:%M</literal>) to use with the lightdm gtk greeter panel.

     

       795
       795
       +
            <literal>displayManager.lightdm.greeters.gtk.clock-format.</literal> has

     

       796
       796
       +
            been added, the clock format string (as expected by strftime, e.g.

     

       797
       797
       +
            <literal>%H:%M</literal>) to use with the lightdm gtk greeter panel.

     

       659
       798
        
           </para>

     

       660
       799
        
           <para>

     

       661
       800
        
            If set to null the default clock format is used.

     
···

       663
       802
        
          </listitem>

     

       664
       803
        
          <listitem>

     

       665
       804
        
           <para>

     

       666
       666
       -
            <literal>displayManager.lightdm.greeters.gtk.indicators</literal> has been added, a list of allowed indicator modules to use with the lightdm gtk greeter panel.

     

       805
       805
       +
            <literal>displayManager.lightdm.greeters.gtk.indicators</literal> has been

     

       806
       806
       +
            added, a list of allowed indicator modules to use with the lightdm gtk

     

       807
       807
       +
            greeter panel.

     

       667
       808
        
           </para>

     

       668
       809
        
           <para>

     

       669
       669
       -
            Built-in indicators include <literal>~a11y</literal>, <literal>~language</literal>, <literal>~session</literal>, <literal>~power</literal>, <literal>~clock</literal>, <literal>~host</literal>, <literal>~spacer</literal>. Unity indicators can be represented by short name (e.g. <literal>sound</literal>, <literal>power</literal>), service file name, or absolute path.

     

       810
       810
       +
            Built-in indicators include <literal>~a11y</literal>,

     

       811
       811
       +
            <literal>~language</literal>, <literal>~session</literal>,

     

       812
       812
       +
            <literal>~power</literal>, <literal>~clock</literal>,

     

       813
       813
       +
            <literal>~host</literal>, <literal>~spacer</literal>. Unity indicators can

     

       814
       814
       +
            be represented by short name (e.g. <literal>sound</literal>,

     

       815
       815
       +
            <literal>power</literal>), service file name, or absolute path.

     

       670
       816
        
           </para>

     

       671
       817
        
           <para>

     

       672
       818
        
            If set to <literal>null</literal> the default indicators are used.

     
···

       688
       834
        
          </listitem>

     

       689
       835
        
          <listitem>

     

       690
       836
        
           <para>

     

       691
       691
       -
            The NixOS test driver supports user services declared by <literal>systemd.user.services</literal>. The methods <literal>waitForUnit</literal>, <literal>getUnitInfo</literal>, <literal>startJob</literal> and <literal>stopJob</literal> provide an optional <literal>$user</literal> argument for that purpose.

     

       837
       837
       +
            The NixOS test driver supports user services declared by

     

       838
       838
       +
            <literal>systemd.user.services</literal>. The methods

     

       839
       839
       +
            <literal>waitForUnit</literal>, <literal>getUnitInfo</literal>,

     

       840
       840
       +
            <literal>startJob</literal> and <literal>stopJob</literal> provide an

     

       841
       841
       +
            optional <literal>$user</literal> argument for that purpose.

     

       692
       842
        
           </para>

     

       693
       843
        
          </listitem>

     

       694
       844
        
          <listitem>

     

       695
       845
        
           <para>

     

       696
       696
       -
            Enabling bash completion on NixOS, <literal>programs.bash.enableCompletion</literal>, will now also enable completion for the Nix command line tools by installing the <link xlink:href="https://github.com/hedning/nix-bash-completions">nix-bash-completions</link> package.

     

       846
       846
       +
            Enabling bash completion on NixOS,

     

       847
       847
       +
            <literal>programs.bash.enableCompletion</literal>, will now also enable

     

       848
       848
       +
            completion for the Nix command line tools by installing the

     

       849
       849
       +
            <link xlink:href="https://github.com/hedning/nix-bash-completions">nix-bash-completions</link>

     

       850
       850
       +
            package.

     

       697
       851
        
           </para>

     

       698
       852
        
          </listitem>

     

       699
       853
        
         </itemizedlist>

+242 -69

nixos/doc/manual/release-notes/rl-1809.xml

···

       13
       13
        
         <title>Highlights</title>

     

       14
       14
        
       

     

       15
       15
        
         <para>

     

       16
       16
       -
          In addition to numerous new and upgraded packages, this release has the following notable updates:

     

       16
       16
       +
          In addition to numerous new and upgraded packages, this release has the

     

       17
       17
       +
          following notable updates:

     

       17
       18
        
         </para>

     

       18
       19
        
       

     

       19
       20
        
         <itemizedlist>

     
···

       24
       25
        
          </listitem>

     

       25
       26
        
          <listitem>

     

       26
       27
        
           <para>

     

       27
       27
       -
            Platform support: x86_64-linux and x86_64-darwin as always. Support for aarch64-linux is as with the previous releases, not equivalent to the x86-64-linux release, but with efforts to reach parity.

     

       28
       28
       +
            Platform support: x86_64-linux and x86_64-darwin as always. Support for

     

       29
       29
       +
            aarch64-linux is as with the previous releases, not equivalent to the

     

       30
       30
       +
            x86-64-linux release, but with efforts to reach parity.

     

       28
       31
        
           </para>

     

       29
       32
        
          </listitem>

     

       30
       33
        
          <listitem>

     

       31
       34
        
           <para>

     

       32
       32
       -
            Nix has been updated to 2.1; see its <link xlink:href="https://nixos.org/nix/manual/#ssec-relnotes-2.1">release notes</link>.

     

       35
       35
       +
            Nix has been updated to 2.1; see its

     

       36
       36
       +
            <link xlink:href="https://nixos.org/nix/manual/#ssec-relnotes-2.1">release

     

       37
       37
       +
            notes</link>.

     

       33
       38
        
           </para>

     

       34
       39
        
          </listitem>

     

       35
       40
        
          <listitem>

     

       36
       41
        
           <para>

     

       37
       37
       -
            Core versions: linux: 4.14 LTS (unchanged), glibc: 2.26 → 2.27, gcc: 7 (unchanged), systemd: 237 → 239.

     

       42
       42
       +
            Core versions: linux: 4.14 LTS (unchanged), glibc: 2.26 → 2.27, gcc: 7

     

       43
       43
       +
            (unchanged), systemd: 237 → 239.

     

       38
       44
        
           </para>

     

       39
       45
        
          </listitem>

     

       40
       46
        
          <listitem>

     

       41
       47
        
           <para>

     

       42
       42
       -
            Desktop version changes: gnome: 3.26 → 3.28, (KDE) plasma-desktop: 5.12 → 5.13.

     

       48
       48
       +
            Desktop version changes: gnome: 3.26 → 3.28, (KDE) plasma-desktop: 5.12

     

       49
       49
       +
            → 5.13.

     

       43
       50
        
           </para>

     

       44
       51
        
          </listitem>

     

       45
       52
        
         </itemizedlist>

     
···

       51
       58
        
         <itemizedlist>

     

       52
       59
        
          <listitem>

     

       53
       60
        
           <para>

     

       54
       54
       -
            Support for wrapping binaries using <literal>firejail</literal> has been added through <varname>programs.firejail.wrappedBinaries</varname>.

     

       61
       61
       +
            Support for wrapping binaries using <literal>firejail</literal> has been

     

       62
       62
       +
            added through <varname>programs.firejail.wrappedBinaries</varname>.

     

       55
       63
        
           </para>

     

       56
       64
        
           <para>

     

       57
       65
        
            For example

     
···

       66
       74
        
       };

     

       67
       75
        
       </programlisting>

     

       68
       76
        
           <para>

     

       69
       69
       -
            This will place <literal>firefox</literal> and <literal>mpv</literal> binaries in the global path wrapped by firejail.

     

       77
       77
       +
            This will place <literal>firefox</literal> and <literal>mpv</literal>

     

       78
       78
       +
            binaries in the global path wrapped by firejail.

     

       70
       79
        
           </para>

     

       71
       80
        
          </listitem>

     

       72
       81
        
          <listitem>

     

       73
       82
        
           <para>

     

       74
       74
       -
            User channels are now in the default <literal>NIX_PATH</literal>, allowing users to use their personal <command>nix-channel</command> defined channels in <command>nix-build</command> and <command>nix-shell</command> commands, as well as in imports like <code>import &lt;mychannel&gt;</code>.

     

       83
       83
       +
            User channels are now in the default <literal>NIX_PATH</literal>, allowing

     

       84
       84
       +
            users to use their personal <command>nix-channel</command> defined

     

       85
       85
       +
            channels in <command>nix-build</command> and <command>nix-shell</command>

     

       86
       86
       +
            commands, as well as in imports like <code>import

     

       87
       87
       +
            &lt;mychannel&gt;</code>.

     

       75
       88
        
           </para>

     

       76
       89
        
           <para>

     

       77
       90
        
            For example

     
···

       101
       114
        
         <itemizedlist>

     

       102
       115
        
          <listitem>

     

       103
       116
        
           <para>

     

       104
       104
       -
            The <varname>services.cassandra</varname> module has been reworked and was rewritten from scratch. The service has succeeding tests for the versions 2.1, 2.2, 3.0 and 3.11 of <link

     

       105
       105
       -
            xlink:href="https://cassandra.apache.org/">Apache Cassandra</link>.

     

       117
       117
       +
            The <varname>services.cassandra</varname> module has been reworked and was

     

       118
       118
       +
            rewritten from scratch. The service has succeeding tests for the versions

     

       119
       119
       +
            2.1, 2.2, 3.0 and 3.11 of

     

       120
       120
       +
            <link

     

       121
       121
       +
            xlink:href="https://cassandra.apache.org/">Apache

     

       122
       122
       +
            Cassandra</link>.

     

       106
       123
        
           </para>

     

       107
       124
        
          </listitem>

     

       108
       125
        
          <listitem>

     

       109
       126
        
           <para>

     

       110
       110
       -
            There is a new <varname>services.foundationdb</varname> module for deploying <link xlink:href="https://www.foundationdb.org">FoundationDB</link> clusters.

     

       127
       127
       +
            There is a new <varname>services.foundationdb</varname> module for

     

       128
       128
       +
            deploying

     

       129
       129
       +
            <link xlink:href="https://www.foundationdb.org">FoundationDB</link>

     

       130
       130
       +
            clusters.

     

       111
       131
        
           </para>

     

       112
       132
        
          </listitem>

     

       113
       133
        
          <listitem>

     

       114
       134
        
           <para>

     

       115
       115
       -
            When enabled the <literal>iproute2</literal> will copy the files expected by ip route (e.g., <filename>rt_tables</filename>) in <filename>/etc/iproute2</filename>. This allows to write aliases for routing tables for instance.

     

       135
       135
       +
            When enabled the <literal>iproute2</literal> will copy the files expected

     

       136
       136
       +
            by ip route (e.g., <filename>rt_tables</filename>) in

     

       137
       137
       +
            <filename>/etc/iproute2</filename>. This allows to write aliases for

     

       138
       138
       +
            routing tables for instance.

     

       116
       139
        
           </para>

     

       117
       140
        
          </listitem>

     

       118
       141
        
          <listitem>

     

       119
       142
        
           <para>

     

       120
       120
       -
            <varname>services.strongswan-swanctl</varname> is a modern replacement for <varname>services.strongswan</varname>. You can use either one of them to setup IPsec VPNs but not both at the same time.

     

       143
       143
       +
            <varname>services.strongswan-swanctl</varname> is a modern replacement for

     

       144
       144
       +
            <varname>services.strongswan</varname>. You can use either one of them to

     

       145
       145
       +
            setup IPsec VPNs but not both at the same time.

     

       121
       146
        
           </para>

     

       122
       147
        
           <para>

     

       123
       123
       -
            <varname>services.strongswan-swanctl</varname> uses the <link xlink:href="https://wiki.strongswan.org/projects/strongswan/wiki/swanctl">swanctl</link> command which uses the modern <link xlink:href="https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md">vici</link> <emphasis>Versatile IKE Configuration Interface</emphasis>. The deprecated <literal>ipsec</literal> command used in <varname>services.strongswan</varname> is using the legacy <link xlink:href="https://github.com/strongswan/strongswan/blob/master/README_LEGACY.md">stroke configuration interface</link>.

     

       148
       148
       +
            <varname>services.strongswan-swanctl</varname> uses the

     

       149
       149
       +
            <link xlink:href="https://wiki.strongswan.org/projects/strongswan/wiki/swanctl">swanctl</link>

     

       150
       150
       +
            command which uses the modern

     

       151
       151
       +
            <link xlink:href="https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md">vici</link>

     

       152
       152
       +
            <emphasis>Versatile IKE Configuration Interface</emphasis>. The deprecated

     

       153
       153
       +
            <literal>ipsec</literal> command used in

     

       154
       154
       +
            <varname>services.strongswan</varname> is using the legacy

     

       155
       155
       +
            <link xlink:href="https://github.com/strongswan/strongswan/blob/master/README_LEGACY.md">stroke

     

       156
       156
       +
            configuration interface</link>.

     

       124
       157
        
           </para>

     

       125
       158
        
          </listitem>

     

       126
       159
        
          <listitem>

     

       127
       160
        
           <para>

     

       128
       128
       -
            The new <varname>services.elasticsearch-curator</varname> service periodically curates or manages, your Elasticsearch indices and snapshots.

     

       161
       161
       +
            The new <varname>services.elasticsearch-curator</varname> service

     

       162
       162
       +
            periodically curates or manages, your Elasticsearch indices and snapshots.

     

       129
       163
        
           </para>

     

       130
       164
        
          </listitem>

     

       131
       165
        
         </itemizedlist>

     
···

       436
       470
        
         <title>Backward Incompatibilities</title>

     

       437
       471
        
       

     

       438
       472
        
         <para>

     

       439
       439
       -
          When upgrading from a previous release, please be aware of the following incompatible changes:

     

       473
       473
       +
          When upgrading from a previous release, please be aware of the following

     

       474
       474
       +
          incompatible changes:

     

       440
       475
        
         </para>

     

       441
       476
        
       

     

       442
       477
        
         <itemizedlist>

     

       443
       478
        
          <listitem>

     

       444
       479
        
           <para>

     

       445
       445
       -
            Some licenses that were incorrectly not marked as unfree now are. This is the case for:

     

       480
       480
       +
            Some licenses that were incorrectly not marked as unfree now are. This is

     

       481
       481
       +
            the case for:

     

       446
       482
        
            <itemizedlist>

     

       447
       483
        
             <listitem>

     

       448
       484
        
              <para>

     

       449
       449
       -
               cc-by-nc-sa-20: Creative Commons Attribution Non Commercial Share Alike 2.0

     

       485
       485
       +
               cc-by-nc-sa-20: Creative Commons Attribution Non Commercial Share Alike

     

       486
       486
       +
               2.0

     

       450
       487
        
              </para>

     

       451
       488
        
             </listitem>

     

       452
       489
        
             <listitem>

     

       453
       490
        
              <para>

     

       454
       454
       -
               cc-by-nc-sa-25: Creative Commons Attribution Non Commercial Share Alike 2.5

     

       491
       491
       +
               cc-by-nc-sa-25: Creative Commons Attribution Non Commercial Share Alike

     

       492
       492
       +
               2.5

     

       455
       493
        
              </para>

     

       456
       494
        
             </listitem>

     

       457
       495
        
             <listitem>

     

       458
       496
        
              <para>

     

       459
       459
       -
               cc-by-nc-sa-30: Creative Commons Attribution Non Commercial Share Alike 3.0

     

       497
       497
       +
               cc-by-nc-sa-30: Creative Commons Attribution Non Commercial Share Alike

     

       498
       498
       +
               3.0

     

       460
       499
        
              </para>

     

       461
       500
        
             </listitem>

     

       462
       501
        
             <listitem>

     

       463
       502
        
              <para>

     

       464
       464
       -
               cc-by-nc-sa-40: Creative Commons Attribution Non Commercial Share Alike 4.0

     

       503
       503
       +
               cc-by-nc-sa-40: Creative Commons Attribution Non Commercial Share Alike

     

       504
       504
       +
               4.0

     

       465
       505
        
              </para>

     

       466
       506
        
             </listitem>

     

       467
       507
        
             <listitem>

     
···

       479
       519
        
          </listitem>

     

       480
       520
        
          <listitem>

     

       481
       521
        
           <para>

     

       482
       482
       -
            The deprecated <varname>services.cassandra</varname> module has seen a complete rewrite. (See above.)

     

       522
       522
       +
            The deprecated <varname>services.cassandra</varname> module has seen a

     

       523
       523
       +
            complete rewrite. (See above.)

     

       483
       524
        
           </para>

     

       484
       525
        
          </listitem>

     

       485
       526
        
          <listitem>

     

       486
       527
        
           <para>

     

       487
       487
       -
            <literal>lib.strict</literal> is removed. Use <literal>builtins.seq</literal> instead.

     

       528
       528
       +
            <literal>lib.strict</literal> is removed. Use

     

       529
       529
       +
            <literal>builtins.seq</literal> instead.

     

       488
       530
        
           </para>

     

       489
       531
        
          </listitem>

     

       490
       532
        
          <listitem>

     

       491
       533
        
           <para>

     

       492
       492
       -
            The <literal>clementine</literal> package points now to the free derivation. <literal>clementineFree</literal> is removed now and <literal>clementineUnfree</literal> points to the package which is bundled with the unfree <literal>libspotify</literal> package.

     

       534
       534
       +
            The <literal>clementine</literal> package points now to the free

     

       535
       535
       +
            derivation. <literal>clementineFree</literal> is removed now and

     

       536
       536
       +
            <literal>clementineUnfree</literal> points to the package which is bundled

     

       537
       537
       +
            with the unfree <literal>libspotify</literal> package.

     

       493
       538
        
           </para>

     

       494
       539
        
          </listitem>

     

       495
       540
        
          <listitem>

     

       496
       541
        
           <para>

     

       497
       497
       -
            The <literal>netcat</literal> package is now taken directly from OpenBSD's <literal>libressl</literal>, instead of relying on Debian's fork. The new version should be very close to the old version, but there are some minor differences. Importantly, flags like -b, -q, -C, and -Z are no longer accepted by the nc command.

     

       542
       542
       +
            The <literal>netcat</literal> package is now taken directly from OpenBSD's

     

       543
       543
       +
            <literal>libressl</literal>, instead of relying on Debian's fork. The new

     

       544
       544
       +
            version should be very close to the old version, but there are some minor

     

       545
       545
       +
            differences. Importantly, flags like -b, -q, -C, and -Z are no longer

     

       546
       546
       +
            accepted by the nc command.

     

       498
       547
        
           </para>

     

       499
       548
        
          </listitem>

     

       500
       549
        
          <listitem>

     

       501
       550
        
           <para>

     

       502
       502
       -
            The <varname>services.docker-registry.extraConfig</varname> object doesn't contain environment variables anymore. Instead it needs to provide an object structure that can be mapped onto the YAML configuration defined in <link xlink:href="https://github.com/docker/distribution/blob/v2.6.2/docs/configuration.md">the <varname>docker/distribution</varname> docs</link>.

     

       551
       551
       +
            The <varname>services.docker-registry.extraConfig</varname> object doesn't

     

       552
       552
       +
            contain environment variables anymore. Instead it needs to provide an

     

       553
       553
       +
            object structure that can be mapped onto the YAML configuration defined in

     

       554
       554
       +
            <link xlink:href="https://github.com/docker/distribution/blob/v2.6.2/docs/configuration.md">the

     

       555
       555
       +
            <varname>docker/distribution</varname> docs</link>.

     

       503
       556
        
           </para>

     

       504
       557
        
          </listitem>

     

       505
       558
        
          <listitem>

     

       506
       559
        
           <para>

     

       507
       507
       -
            <literal>gnucash</literal> has changed from version 2.4 to 3.x. If you've been using <literal>gnucash</literal> (version 2.4) instead of <literal>gnucash26</literal> (version 2.6) you must open your Gnucash data file(s) with <literal>gnucash26</literal> and then save them to upgrade the file format. Then you may use your data file(s) with Gnucash 3.x. See the upgrade <link xlink:href="https://wiki.gnucash.org/wiki/FAQ#Using_Different_Versions.2C_Up_And_Downgrade">documentation</link>. Gnucash 2.4 is still available under the attribute <literal>gnucash24</literal>.

     

       560
       560
       +
            <literal>gnucash</literal> has changed from version 2.4 to 3.x. If you've

     

       561
       561
       +
            been using <literal>gnucash</literal> (version 2.4) instead of

     

       562
       562
       +
            <literal>gnucash26</literal> (version 2.6) you must open your Gnucash data

     

       563
       563
       +
            file(s) with <literal>gnucash26</literal> and then save them to upgrade

     

       564
       564
       +
            the file format. Then you may use your data file(s) with Gnucash 3.x. See

     

       565
       565
       +
            the upgrade

     

       566
       566
       +
            <link xlink:href="https://wiki.gnucash.org/wiki/FAQ#Using_Different_Versions.2C_Up_And_Downgrade">documentation</link>.

     

       567
       567
       +
            Gnucash 2.4 is still available under the attribute

     

       568
       568
       +
            <literal>gnucash24</literal>.

     

       508
       569
        
           </para>

     

       509
       570
        
          </listitem>

     

       510
       571
        
          <listitem>

     

       511
       572
        
           <para>

     

       512
       512
       -
            <varname>services.munge</varname> now runs as user (and group) <literal>munge</literal> instead of root. Make sure the key file is accessible to the daemon.

     

       573
       573
       +
            <varname>services.munge</varname> now runs as user (and group)

     

       574
       574
       +
            <literal>munge</literal> instead of root. Make sure the key file is

     

       575
       575
       +
            accessible to the daemon.

     

       513
       576
        
           </para>

     

       514
       577
        
          </listitem>

     

       515
       578
        
          <listitem>

     

       516
       579
        
           <para>

     

       517
       517
       -
            <varname>dockerTools.buildImage</varname> now uses <literal>null</literal> as default value for <varname>tag</varname>, which indicates that the nix output hash will be used as tag.

     

       580
       580
       +
            <varname>dockerTools.buildImage</varname> now uses <literal>null</literal>

     

       581
       581
       +
            as default value for <varname>tag</varname>, which indicates that the nix

     

       582
       582
       +
            output hash will be used as tag.

     

       518
       583
        
           </para>

     

       519
       584
        
          </listitem>

     

       520
       585
        
          <listitem>

     

       521
       586
        
           <para>

     

       522
       522
       -
            The ELK stack: <varname>elasticsearch</varname>, <varname>logstash</varname> and <varname>kibana</varname> has been upgraded from 2.* to 6.3.*. The 2.* versions have been <link xlink:href="https://www.elastic.co/support/eol">unsupported since last year</link> so they have been removed. You can still use the 5.* versions under the names <varname>elasticsearch5</varname>, <varname>logstash5</varname> and <varname>kibana5</varname>.

     

       587
       587
       +
            The ELK stack: <varname>elasticsearch</varname>,

     

       588
       588
       +
            <varname>logstash</varname> and <varname>kibana</varname> has been

     

       589
       589
       +
            upgraded from 2.* to 6.3.*. The 2.* versions have been

     

       590
       590
       +
            <link xlink:href="https://www.elastic.co/support/eol">unsupported since

     

       591
       591
       +
            last year</link> so they have been removed. You can still use the 5.*

     

       592
       592
       +
            versions under the names <varname>elasticsearch5</varname>,

     

       593
       593
       +
            <varname>logstash5</varname> and <varname>kibana5</varname>.

     

       523
       594
        
           </para>

     

       524
       595
        
           <para>

     

       525
       525
       -
            The elastic beats: <varname>filebeat</varname>, <varname>heartbeat</varname>, <varname>metricbeat</varname> and <varname>packetbeat</varname> have had the same treatment: they now target 6.3.* as well. The 5.* versions are available under the names: <varname>filebeat5</varname>, <varname>heartbeat5</varname>, <varname>metricbeat5</varname> and <varname>packetbeat5</varname>

     

       596
       596
       +
            The elastic beats: <varname>filebeat</varname>,

     

       597
       597
       +
            <varname>heartbeat</varname>, <varname>metricbeat</varname> and

     

       598
       598
       +
            <varname>packetbeat</varname> have had the same treatment: they now target

     

       599
       599
       +
            6.3.* as well. The 5.* versions are available under the names:

     

       600
       600
       +
            <varname>filebeat5</varname>, <varname>heartbeat5</varname>,

     

       601
       601
       +
            <varname>metricbeat5</varname> and <varname>packetbeat5</varname>

     

       526
       602
        
           </para>

     

       527
       603
        
           <para>

     

       528
       528
       -
            The ELK-6.3 stack now comes with <link xlink:href="https://www.elastic.co/products/x-pack/open">X-Pack by default</link>. Since X-Pack is licensed under the <link xlink:href="https://github.com/elastic/elasticsearch/blob/master/licenses/ELASTIC-LICENSE.txt">Elastic License</link> the ELK packages now have an unfree license. To use them you need to specify <literal>allowUnfree = true;</literal> in your nixpkgs configuration.

     

       604
       604
       +
            The ELK-6.3 stack now comes with

     

       605
       605
       +
            <link xlink:href="https://www.elastic.co/products/x-pack/open">X-Pack by

     

       606
       606
       +
            default</link>. Since X-Pack is licensed under the

     

       607
       607
       +
            <link xlink:href="https://github.com/elastic/elasticsearch/blob/master/licenses/ELASTIC-LICENSE.txt">Elastic

     

       608
       608
       +
            License</link> the ELK packages now have an unfree license. To use them

     

       609
       609
       +
            you need to specify <literal>allowUnfree = true;</literal> in your nixpkgs

     

       610
       610
       +
            configuration.

     

       529
       611
        
           </para>

     

       530
       612
        
           <para>

     

       531
       531
       -
            Fortunately there is also a free variant of the ELK stack without X-Pack. The packages are available under the names: <varname>elasticsearch-oss</varname>, <varname>logstash-oss</varname> and <varname>kibana-oss</varname>.

     

       613
       613
       +
            Fortunately there is also a free variant of the ELK stack without X-Pack.

     

       614
       614
       +
            The packages are available under the names:

     

       615
       615
       +
            <varname>elasticsearch-oss</varname>, <varname>logstash-oss</varname> and

     

       616
       616
       +
            <varname>kibana-oss</varname>.

     

       532
       617
        
           </para>

     

       533
       618
        
          </listitem>

     

       534
       619
        
          <listitem>

     

       535
       620
        
           <para>

     

       536
       536
       -
            Options <literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.ramfsMountPoint</literal> <literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.storage.mountPoint</literal> were removed. <literal>luksroot.nix</literal> module never supported more than one YubiKey at a time anyway, hence those options never had any effect. You should be able to remove them from your config without any issues.

     

       621
       621
       +
            Options

     

       622
       622
       +
            <literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.ramfsMountPoint</literal>

     

       623
       623
       +
            <literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.storage.mountPoint</literal>

     

       624
       624
       +
            were removed. <literal>luksroot.nix</literal> module never supported more

     

       625
       625
       +
            than one YubiKey at a time anyway, hence those options never had any

     

       626
       626
       +
            effect. You should be able to remove them from your config without any

     

       627
       627
       +
            issues.

     

       537
       628
        
           </para>

     

       538
       629
        
          </listitem>

     

       539
       630
        
          <listitem>

     

       540
       631
        
           <para>

     

       541
       541
       -
            <literal>stdenv.system</literal> and <literal>system</literal> in nixpkgs now refer to the host platform instead of the build platform. For native builds this is not change, let alone a breaking one. For cross builds, it is a breaking change, and <literal>stdenv.buildPlatform.system</literal> can be used instead for the old behavior. They should be using that anyways for clarity.

     

       632
       632
       +
            <literal>stdenv.system</literal> and <literal>system</literal> in nixpkgs

     

       633
       633
       +
            now refer to the host platform instead of the build platform. For native

     

       634
       634
       +
            builds this is not change, let alone a breaking one. For cross builds, it

     

       635
       635
       +
            is a breaking change, and <literal>stdenv.buildPlatform.system</literal>

     

       636
       636
       +
            can be used instead for the old behavior. They should be using that

     

       637
       637
       +
            anyways for clarity.

     

       542
       638
        
           </para>

     

       543
       639
        
          </listitem>

     

       544
       640
        
          <listitem>

     

       545
       641
        
           <para>

     

       546
       546
       -
            Groups <literal>kvm</literal> and <literal>render</literal> are introduced now, as systemd requires them.

     

       642
       642
       +
            Groups <literal>kvm</literal> and <literal>render</literal> are introduced

     

       643
       643
       +
            now, as systemd requires them.

     

       547
       644
        
           </para>

     

       548
       645
        
          </listitem>

     

       549
       646
        
         </itemizedlist>

     
···

       559
       656
        
         <itemizedlist>

     

       560
       657
        
          <listitem>

     

       561
       658
        
           <para>

     

       562
       562
       -
            <literal>dockerTools.pullImage</literal> relies on image digest instead of image tag to download the image. The <literal>sha256</literal> of a pulled image has to be updated.

     

       659
       659
       +
            <literal>dockerTools.pullImage</literal> relies on image digest instead of

     

       660
       660
       +
            image tag to download the image. The <literal>sha256</literal> of a pulled

     

       661
       661
       +
            image has to be updated.

     

       563
       662
        
           </para>

     

       564
       663
        
          </listitem>

     

       565
       664
        
          <listitem>

     

       566
       665
        
           <para>

     

       567
       567
       -
            <literal>lib.attrNamesToStr</literal> has been deprecated. Use more specific concatenation (<literal>lib.concat(Map)StringsSep</literal>) instead.

     

       666
       666
       +
            <literal>lib.attrNamesToStr</literal> has been deprecated. Use more

     

       667
       667
       +
            specific concatenation (<literal>lib.concat(Map)StringsSep</literal>)

     

       668
       668
       +
            instead.

     

       568
       669
        
           </para>

     

       569
       670
        
          </listitem>

     

       570
       671
        
          <listitem>

     

       571
       672
        
           <para>

     

       572
       572
       -
            <literal>lib.addErrorContextToAttrs</literal> has been deprecated. Use <literal>builtins.addErrorContext</literal> directly.

     

       673
       673
       +
            <literal>lib.addErrorContextToAttrs</literal> has been deprecated. Use

     

       674
       674
       +
            <literal>builtins.addErrorContext</literal> directly.

     

       573
       675
        
           </para>

     

       574
       676
        
          </listitem>

     

       575
       677
        
          <listitem>

     

       576
       678
        
           <para>

     

       577
       577
       -
            <literal>lib.showVal</literal> has been deprecated. Use <literal>lib.traceSeqN</literal> instead.

     

       679
       679
       +
            <literal>lib.showVal</literal> has been deprecated. Use

     

       680
       680
       +
            <literal>lib.traceSeqN</literal> instead.

     

       578
       681
        
           </para>

     

       579
       682
        
          </listitem>

     

       580
       683
        
          <listitem>

     

       581
       684
        
           <para>

     

       582
       582
       -
            <literal>lib.traceXMLVal</literal> has been deprecated. Use <literal>lib.traceValFn builtins.toXml</literal> instead.

     

       685
       685
       +
            <literal>lib.traceXMLVal</literal> has been deprecated. Use

     

       686
       686
       +
            <literal>lib.traceValFn builtins.toXml</literal> instead.

     

       583
       687
        
           </para>

     

       584
       688
        
          </listitem>

     

       585
       689
        
          <listitem>

     

       586
       690
        
           <para>

     

       587
       587
       -
            <literal>lib.traceXMLValMarked</literal> has been deprecated. Use <literal>lib.traceValFn (x: str + builtins.toXML x)</literal> instead.

     

       691
       691
       +
            <literal>lib.traceXMLValMarked</literal> has been deprecated. Use

     

       692
       692
       +
            <literal>lib.traceValFn (x: str + builtins.toXML x)</literal> instead.

     

       588
       693
        
           </para>

     

       589
       694
        
          </listitem>

     

       590
       695
        
          <listitem>

     

       591
       696
        
           <para>

     

       592
       592
       -
            The <literal>pkgs</literal> argument to NixOS modules can now be set directly using <literal>nixpkgs.pkgs</literal>. Previously, only the <literal>system</literal>, <literal>config</literal> and <literal>overlays</literal> arguments could be used to influence <literal>pkgs</literal>.

     

       697
       697
       +
            The <literal>pkgs</literal> argument to NixOS modules can now be set

     

       698
       698
       +
            directly using <literal>nixpkgs.pkgs</literal>. Previously, only the

     

       699
       699
       +
            <literal>system</literal>, <literal>config</literal> and

     

       700
       700
       +
            <literal>overlays</literal> arguments could be used to influence

     

       701
       701
       +
            <literal>pkgs</literal>.

     

       593
       702
        
           </para>

     

       594
       703
        
          </listitem>

     

       595
       704
        
          <listitem>

     

       596
       705
        
           <para>

     

       597
       597
       -
            A NixOS system can now be constructed more easily based on a preexisting invocation of Nixpkgs. For example:

     

       706
       706
       +
            A NixOS system can now be constructed more easily based on a preexisting

     

       707
       707
       +
            invocation of Nixpkgs. For example:

     

       598
       708
        
       <programlisting>

     

       599
       709
        
       inherit (pkgs.nixos {

     

       600
       710
        
         boot.loader.grub.enable = false;

     

       601
       711
        
         fileSystems."/".device = "/dev/xvda1";

     

       602
       712
        
       }) toplevel kernel initialRamdisk manual;

     

       603
       713
        
             </programlisting>

     

       604
       604
       -
            This benefits evaluation performance, lets you write Nixpkgs packages that depend on NixOS images and is consistent with a deployment architecture that would be centered around Nixpkgs overlays.

     

       714
       714
       +
            This benefits evaluation performance, lets you write Nixpkgs packages that

     

       715
       715
       +
            depend on NixOS images and is consistent with a deployment architecture

     

       716
       716
       +
            that would be centered around Nixpkgs overlays.

     

       605
       717
        
           </para>

     

       606
       718
        
          </listitem>

     

       607
       719
        
          <listitem>

     

       608
       720
        
           <para>

     

       609
       609
       -
            <literal>lib.traceValIfNot</literal> has been deprecated. Use <literal>if/then/else</literal> and <literal>lib.traceValSeq</literal> instead.

     

       721
       721
       +
            <literal>lib.traceValIfNot</literal> has been deprecated. Use

     

       722
       722
       +
            <literal>if/then/else</literal> and <literal>lib.traceValSeq</literal>

     

       723
       723
       +
            instead.

     

       610
       724
        
           </para>

     

       611
       725
        
          </listitem>

     

       612
       726
        
          <listitem>

     

       613
       727
        
           <para>

     

       614
       614
       -
            <literal>lib.traceCallXml</literal> has been deprecated. Please complain if you use the function regularly.

     

       728
       728
       +
            <literal>lib.traceCallXml</literal> has been deprecated. Please complain

     

       729
       729
       +
            if you use the function regularly.

     

       615
       730
        
           </para>

     

       616
       731
        
          </listitem>

     

       617
       732
        
          <listitem>

     

       618
       733
        
           <para>

     

       619
       619
       -
            The attribute <literal>lib.nixpkgsVersion</literal> has been deprecated in favor of <literal>lib.version</literal>. Please refer to the discussion in <link xlink:href="https://github.com/NixOS/nixpkgs/pull/39416#discussion_r183845745">NixOS/nixpkgs#39416</link> for further reference.

     

       734
       734
       +
            The attribute <literal>lib.nixpkgsVersion</literal> has been deprecated in

     

       735
       735
       +
            favor of <literal>lib.version</literal>. Please refer to the discussion in

     

       736
       736
       +
            <link xlink:href="https://github.com/NixOS/nixpkgs/pull/39416#discussion_r183845745">NixOS/nixpkgs#39416</link>

     

       737
       737
       +
            for further reference.

     

       620
       738
        
           </para>

     

       621
       739
        
          </listitem>

     

       622
       740
        
          <listitem>

     

       623
       741
        
           <para>

     

       624
       624
       -
            <literal>lib.recursiveUpdateUntil</literal> was not acting according to its specification. It has been fixed to act according to the docstring, and a test has been added.

     

       742
       742
       +
            <literal>lib.recursiveUpdateUntil</literal> was not acting according to

     

       743
       743
       +
            its specification. It has been fixed to act according to the docstring,

     

       744
       744
       +
            and a test has been added.

     

       625
       745
        
           </para>

     

       626
       746
        
          </listitem>

     

       627
       747
        
          <listitem>

     
···

       635
       755
        
             </term>

     

       636
       756
        
             <listitem>

     

       637
       757
        
              <para>

     

       638
       638
       -
               Puts the generated Diffie-Hellman parameters into the Nix store instead of managing them in a stateful manner in <filename class="directory">/var/lib/dhparams</filename>.

     

       758
       758
       +
               Puts the generated Diffie-Hellman parameters into the Nix store instead

     

       759
       759
       +
               of managing them in a stateful manner in

     

       760
       760
       +
               <filename class="directory">/var/lib/dhparams</filename>.

     

       639
       761
        
              </para>

     

       640
       762
        
             </listitem>

     

       641
       763
        
            </varlistentry>

     
···

       645
       767
        
             </term>

     

       646
       768
        
             <listitem>

     

       647
       769
        
              <para>

     

       648
       648
       -
               The default bit size to use for the generated Diffie-Hellman parameters.

     

       770
       770
       +
               The default bit size to use for the generated Diffie-Hellman

     

       771
       771
       +
               parameters.

     

       649
       772
        
              </para>

     

       650
       773
        
             </listitem>

     

       651
       774
        
            </varlistentry>

     

       652
       775
        
           </variablelist>

     

       653
       776
        
           <note>

     

       654
       777
        
            <para>

     

       655
       655
       -
             The path to the actual generated parameter files should now be queried using <literal>config.security.dhparams.params.<replaceable>name</replaceable>.path</literal> because it might be either in the Nix store or in a directory configured by <option>security.dhparams.path</option>.

     

       778
       778
       +
             The path to the actual generated parameter files should now be queried

     

       779
       779
       +
             using

     

       780
       780
       +
             <literal>config.security.dhparams.params.<replaceable>name</replaceable>.path</literal>

     

       781
       781
       +
             because it might be either in the Nix store or in a directory configured

     

       782
       782
       +
             by <option>security.dhparams.path</option>.

     

       656
       783
        
            </para>

     

       657
       784
        
           </note>

     

       658
       785
        
           <note>

     

       659
       786
        
            <title>For developers:</title>

     

       660
       787
        
            <para>

     

       661
       661
       -
             Module implementers should not set a specific bit size in order to let users configure it by themselves if they want to have a different bit size than the default (2048).

     

       788
       788
       +
             Module implementers should not set a specific bit size in order to let

     

       789
       789
       +
             users configure it by themselves if they want to have a different bit

     

       790
       790
       +
             size than the default (2048).

     

       662
       791
        
            </para>

     

       663
       792
        
            <para>

     

       664
       793
        
             An example usage of this would be:

     
···

       677
       806
        
          </listitem>

     

       678
       807
        
          <listitem>

     

       679
       808
        
           <para>

     

       680
       680
       -
            <literal>networking.networkmanager.useDnsmasq</literal> has been deprecated. Use <literal>networking.networkmanager.dns</literal> instead.

     

       809
       809
       +
            <literal>networking.networkmanager.useDnsmasq</literal> has been

     

       810
       810
       +
            deprecated. Use <literal>networking.networkmanager.dns</literal> instead.

     

       681
       811
        
           </para>

     

       682
       812
        
          </listitem>

     

       683
       813
        
          <listitem>

     

       684
       814
        
           <para>

     

       685
       685
       -
            The Kubernetes package has been bumped to major version 1.11. Please consult the <link xlink:href="https://github.com/kubernetes/kubernetes/blob/release-1.11/CHANGELOG-1.11.md">release notes</link> for details on new features and api changes.

     

       815
       815
       +
            The Kubernetes package has been bumped to major version 1.11. Please

     

       816
       816
       +
            consult the

     

       817
       817
       +
            <link xlink:href="https://github.com/kubernetes/kubernetes/blob/release-1.11/CHANGELOG-1.11.md">release

     

       818
       818
       +
            notes</link> for details on new features and api changes.

     

       686
       819
        
           </para>

     

       687
       820
        
          </listitem>

     

       688
       821
        
          <listitem>

     

       689
       822
        
           <para>

     

       690
       690
       -
            The option <varname>services.kubernetes.apiserver.admissionControl</varname> was renamed to <varname>services.kubernetes.apiserver.enableAdmissionPlugins</varname>.

     

       823
       823
       +
            The option

     

       824
       824
       +
            <varname>services.kubernetes.apiserver.admissionControl</varname> was

     

       825
       825
       +
            renamed to

     

       826
       826
       +
            <varname>services.kubernetes.apiserver.enableAdmissionPlugins</varname>.

     

       691
       827
        
           </para>

     

       692
       828
        
          </listitem>

     

       693
       829
        
          <listitem>

     

       694
       830
        
           <para>

     

       695
       695
       -
            Recommended way to access the Kubernetes Dashboard is via HTTPS (TLS) Therefore; public service port for the dashboard has changed to 443 (container port 8443) and scheme to https.

     

       831
       831
       +
            Recommended way to access the Kubernetes Dashboard is via HTTPS (TLS)

     

       832
       832
       +
            Therefore; public service port for the dashboard has changed to 443

     

       833
       833
       +
            (container port 8443) and scheme to https.

     

       696
       834
        
           </para>

     

       697
       835
        
          </listitem>

     

       698
       836
        
          <listitem>

     

       699
       837
        
           <para>

     

       700
       700
       -
            The option <varname>services.kubernetes.apiserver.address</varname> was renamed to <varname>services.kubernetes.apiserver.bindAddress</varname>. Note that the default value has changed from 127.0.0.1 to 0.0.0.0.

     

       838
       838
       +
            The option <varname>services.kubernetes.apiserver.address</varname> was

     

       839
       839
       +
            renamed to <varname>services.kubernetes.apiserver.bindAddress</varname>.

     

       840
       840
       +
            Note that the default value has changed from 127.0.0.1 to 0.0.0.0.

     

       701
       841
        
           </para>

     

       702
       842
        
          </listitem>

     

       703
       843
        
          <listitem>

     

       704
       844
        
           <para>

     

       705
       705
       -
            The option <varname>services.kubernetes.apiserver.publicAddress</varname> was not used and thus has been removed.

     

       845
       845
       +
            The option <varname>services.kubernetes.apiserver.publicAddress</varname>

     

       846
       846
       +
            was not used and thus has been removed.

     

       706
       847
        
           </para>

     

       707
       848
        
          </listitem>

     

       708
       849
        
          <listitem>

     

       709
       850
        
           <para>

     

       710
       710
       -
            The option <varname>services.kubernetes.addons.dashboard.enableRBAC</varname> was renamed to <varname>services.kubernetes.addons.dashboard.rbac.enable</varname>.

     

       851
       851
       +
            The option

     

       852
       852
       +
            <varname>services.kubernetes.addons.dashboard.enableRBAC</varname> was

     

       853
       853
       +
            renamed to

     

       854
       854
       +
            <varname>services.kubernetes.addons.dashboard.rbac.enable</varname>.

     

       711
       855
        
           </para>

     

       712
       856
        
          </listitem>

     

       713
       857
        
          <listitem>

     

       714
       858
        
           <para>

     

       715
       715
       -
            The Kubernetes Dashboard now has only minimal RBAC permissions by default. If dashboard cluster-admin rights are desired, set <varname>services.kubernetes.addons.dashboard.rbac.clusterAdmin</varname> to true. On existing clusters, in order for the revocation of privileges to take effect, the current ClusterRoleBinding for kubernetes-dashboard must be manually removed: <literal>kubectl delete clusterrolebinding kubernetes-dashboard</literal>

     

       859
       859
       +
            The Kubernetes Dashboard now has only minimal RBAC permissions by default.

     

       860
       860
       +
            If dashboard cluster-admin rights are desired, set

     

       861
       861
       +
            <varname>services.kubernetes.addons.dashboard.rbac.clusterAdmin</varname>

     

       862
       862
       +
            to true. On existing clusters, in order for the revocation of privileges

     

       863
       863
       +
            to take effect, the current ClusterRoleBinding for kubernetes-dashboard

     

       864
       864
       +
            must be manually removed: <literal>kubectl delete clusterrolebinding

     

       865
       865
       +
            kubernetes-dashboard</literal>

     

       716
       866
        
           </para>

     

       717
       867
        
          </listitem>

     

       718
       868
        
          <listitem>

     

       719
       869
        
           <para>

     

       720
       720
       -
            The <varname>programs.screen</varname> module provides allows to configure <literal>/etc/screenrc</literal>, however the module behaved fairly counterintuitive as the config exists, but the package wasn't available. Since 18.09 <literal>pkgs.screen</literal> will be added to <literal>environment.systemPackages</literal>.

     

       870
       870
       +
            The <varname>programs.screen</varname> module provides allows to configure

     

       871
       871
       +
            <literal>/etc/screenrc</literal>, however the module behaved fairly

     

       872
       872
       +
            counterintuitive as the config exists, but the package wasn't available.

     

       873
       873
       +
            Since 18.09 <literal>pkgs.screen</literal> will be added to

     

       874
       874
       +
            <literal>environment.systemPackages</literal>.

     

       721
       875
        
           </para>

     

       722
       876
        
          </listitem>

     

       723
       877
        
          <listitem>

     

       724
       878
        
           <para>

     

       725
       725
       -
            The module <option>services.networking.hostapd</option> now uses WPA2 by default.

     

       879
       879
       +
            The module <option>services.networking.hostapd</option> now uses WPA2 by

     

       880
       880
       +
            default.

     

       726
       881
        
           </para>

     

       727
       882
        
          </listitem>

     

       728
       883
        
          <listitem>

     

       729
       884
        
           <para>

     

       730
       730
       -
            <varname>s6Dns</varname>, <varname>s6Networking</varname>, <varname>s6LinuxUtils</varname> and <varname>s6PortableUtils</varname> renamed to <varname>s6-dns</varname>, <varname>s6-networking</varname>, <varname>s6-linux-utils</varname> and <varname>s6-portable-utils</varname> respectively.

     

       885
       885
       +
            <varname>s6Dns</varname>, <varname>s6Networking</varname>,

     

       886
       886
       +
            <varname>s6LinuxUtils</varname> and <varname>s6PortableUtils</varname>

     

       887
       887
       +
            renamed to <varname>s6-dns</varname>, <varname>s6-networking</varname>,

     

       888
       888
       +
            <varname>s6-linux-utils</varname> and <varname>s6-portable-utils</varname>

     

       889
       889
       +
            respectively.

     

       731
       890
        
           </para>

     

       732
       891
        
          </listitem>

     

       733
       892
        
          <listitem>

     

       734
       893
        
           <para>

     

       735
       735
       -
            The module option <option>nix.useSandbox</option> is now defaulted to <literal>true</literal>.

     

       894
       894
       +
            The module option <option>nix.useSandbox</option> is now defaulted to

     

       895
       895
       +
            <literal>true</literal>.

     

       736
       896
        
           </para>

     

       737
       897
        
          </listitem>

     

       738
       898
        
          <listitem>

     

       739
       899
        
           <para>

     

       740
       740
       -
            The config activation script of <literal>nixos-rebuild</literal> now <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemctl.html#Manager%20Lifecycle%20Commands">reloads</link> all user units for each authenticated user.

     

       900
       900
       +
            The config activation script of <literal>nixos-rebuild</literal> now

     

       901
       901
       +
            <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemctl.html#Manager%20Lifecycle%20Commands">reloads</link>

     

       902
       902
       +
            all user units for each authenticated user.

     

       741
       903
        
           </para>

     

       742
       904
        
          </listitem>

     

       743
       905
        
          <listitem>

     

       744
       906
        
           <para>

     

       745
       745
       -
            The default display manager is now LightDM. To use SLiM set <literal>services.xserver.displayManager.slim.enable</literal> to <literal>true</literal>.

     

       907
       907
       +
            The default display manager is now LightDM. To use SLiM set

     

       908
       908
       +
            <literal>services.xserver.displayManager.slim.enable</literal> to

     

       909
       909
       +
            <literal>true</literal>.

     

       746
       910
        
           </para>

     

       747
       911
        
          </listitem>

     

       748
       912
        
          <listitem>

     

       749
       913
        
           <para>

     

       750
       750
       -
            NixOS option descriptions are now automatically broken up into individual paragraphs if the text contains two consecutive newlines, so it's no longer necessary to use <code>&lt;/para&gt;&lt;para&gt;</code> to start a new paragraph.

     

       914
       914
       +
            NixOS option descriptions are now automatically broken up into individual

     

       915
       915
       +
            paragraphs if the text contains two consecutive newlines, so it's no

     

       916
       916
       +
            longer necessary to use <code>&lt;/para&gt;&lt;para&gt;</code> to start a

     

       917
       917
       +
            new paragraph.

     

       751
       918
        
           </para>

     

       752
       919
        
          </listitem>

     

       753
       920
        
          <listitem>

     

       754
       921
        
           <para>

     

       755
       755
       -
            Top-level <literal>buildPlatform</literal>, <literal>hostPlatform</literal>, and <literal>targetPlatform</literal> in Nixpkgs are deprecated. Please use their equivalents in <literal>stdenv</literal> instead: <literal>stdenv.buildPlatform</literal>, <literal>stdenv.hostPlatform</literal>, and <literal>stdenv.targetPlatform</literal>.

     

       922
       922
       +
            Top-level <literal>buildPlatform</literal>,

     

       923
       923
       +
            <literal>hostPlatform</literal>, and <literal>targetPlatform</literal> in

     

       924
       924
       +
            Nixpkgs are deprecated. Please use their equivalents in

     

       925
       925
       +
            <literal>stdenv</literal> instead:

     

       926
       926
       +
            <literal>stdenv.buildPlatform</literal>,

     

       927
       927
       +
            <literal>stdenv.hostPlatform</literal>, and

     

       928
       928
       +
            <literal>stdenv.targetPlatform</literal>.

     

       756
       929
        
           </para>

     

       757
       930
        
          </listitem>

     

       758
       931
        
         </itemizedlist>

+366 -82

nixos/doc/manual/release-notes/rl-1903.xml

···

       13
       13
        
         <title>Highlights</title>

     

       14
       14
        
       

     

       15
       15
        
         <para>

     

       16
       16
       -
          In addition to numerous new and upgraded packages, this release has the following highlights:

     

       16
       16
       +
          In addition to numerous new and upgraded packages, this release has the

     

       17
       17
       +
          following highlights:

     

       17
       18
        
         </para>

     

       18
       19
        
       

     

       19
       20
        
         <itemizedlist>

     
···

       24
       25
        
          </listitem>

     

       25
       26
        
          <listitem>

     

       26
       27
        
           <para>

     

       27
       27
       -
            The default Python 3 interpreter is now CPython 3.7 instead of CPython 3.6.

     

       28
       28
       +
            The default Python 3 interpreter is now CPython 3.7 instead of CPython

     

       29
       29
       +
            3.6.

     

       28
       30
        
           </para>

     

       29
       31
        
          </listitem>

     

       30
       32
        
          <listitem>

     

       31
       33
        
           <para>

     

       32
       32
       -
            Added the Pantheon desktop environment. It can be enabled through <varname>services.xserver.desktopManager.pantheon.enable</varname>.

     

       34
       34
       +
            Added the Pantheon desktop environment. It can be enabled through

     

       35
       35
       +
            <varname>services.xserver.desktopManager.pantheon.enable</varname>.

     

       33
       36
        
           </para>

     

       34
       37
        
           <note>

     

       35
       38
        
            <para>

     

       36
       36
       -
             By default, <varname>services.xserver.desktopManager.pantheon</varname> enables LightDM as a display manager, as pantheon's screen locking implementation relies on it.

     

       39
       39
       +
             By default, <varname>services.xserver.desktopManager.pantheon</varname>

     

       40
       40
       +
             enables LightDM as a display manager, as pantheon's screen locking

     

       41
       41
       +
             implementation relies on it.

     

       37
       42
        
            </para>

     

       38
       43
        
            <para>

     

       39
       39
       -
             Because of that it is recommended to leave LightDM enabled. If you'd like to disable it anyway, set <option>services.xserver.displayManager.lightdm.enable</option> to <literal>false</literal> and enable your preferred display manager.

     

       44
       44
       +
             Because of that it is recommended to leave LightDM enabled. If you'd like

     

       45
       45
       +
             to disable it anyway, set

     

       46
       46
       +
             <option>services.xserver.displayManager.lightdm.enable</option> to

     

       47
       47
       +
             <literal>false</literal> and enable your preferred display manager.

     

       40
       48
        
            </para>

     

       41
       49
        
           </note>

     

       42
       50
        
           <para>

     

       43
       43
       -
            Also note that Pantheon's LightDM greeter is not enabled by default, because it has numerous issues in NixOS and isn't optimal for use here yet.

     

       51
       51
       +
            Also note that Pantheon's LightDM greeter is not enabled by default,

     

       52
       52
       +
            because it has numerous issues in NixOS and isn't optimal for use here

     

       53
       53
       +
            yet.

     

       44
       54
        
           </para>

     

       45
       55
        
          </listitem>

     

       46
       56
        
          <listitem>

     

       47
       57
        
           <para>

     

       48
       48
       -
            A major refactoring of the Kubernetes module has been completed. Refactorings primarily focus on decoupling components and enhancing security. Two-way TLS and RBAC has been enabled by default for all components, which slightly changes the way the module is configured. See: <xref linkend="sec-kubernetes"/> for details.

     

       58
       58
       +
            A major refactoring of the Kubernetes module has been completed.

     

       59
       59
       +
            Refactorings primarily focus on decoupling components and enhancing

     

       60
       60
       +
            security. Two-way TLS and RBAC has been enabled by default for all

     

       61
       61
       +
            components, which slightly changes the way the module is configured. See:

     

       62
       62
       +
            <xref linkend="sec-kubernetes"/> for details.

     

       49
       63
        
           </para>

     

       50
       64
        
          </listitem>

     

       51
       65
        
          <listitem>

     

       52
       52
       -
           <para>

     

       53
       53
       -
            There is now a set of <option>confinement</option> options for <option>systemd.services</option>, which allows to restrict services into a <citerefentry>

     

       54
       54
       -
            <refentrytitle>chroot</refentrytitle>

     

       55
       55
       -
            <manvolnum>2</manvolnum> </citerefentry>ed environment that only contains the store paths from the runtime closure of the service.

     

       56
       56
       -
           </para>

     

       66
       66
       +
            <para>

     

       67
       67
       +
              There is now a set of <option>confinement</option> options for

     

       68
       68
       +
              <option>systemd.services</option>, which allows to restrict services

     

       69
       69
       +
              into a <citerefentry>

     

       70
       70
       +
               <refentrytitle>chroot</refentrytitle>

     

       71
       71
       +
               <manvolnum>2</manvolnum>

     

       72
       72
       +
             </citerefentry>ed environment that only contains the store paths from

     

       73
       73
       +
             the runtime closure of the service.

     

       74
       74
       +
            </para>

     

       57
       75
        
          </listitem>

     

       58
       76
        
         </itemizedlist>

     

       59
       77
        
        </section>

     
···

       77
       95
        
          </listitem>

     

       78
       96
        
          <listitem>

     

       79
       97
        
           <para>

     

       80
       80
       -
            There is a new <varname>security.googleOsLogin</varname> module for using <link xlink:href="https://cloud.google.com/compute/docs/instances/managing-instance-access">OS Login</link> to manage SSH access to Google Compute Engine instances, which supersedes the imperative and broken <literal>google-accounts-daemon</literal> used in <literal>nixos/modules/virtualisation/google-compute-config.nix</literal>.

     

       98
       98
       +
            There is a new <varname>security.googleOsLogin</varname> module for using

     

       99
       99
       +
            <link xlink:href="https://cloud.google.com/compute/docs/instances/managing-instance-access">OS

     

       100
       100
       +
            Login</link> to manage SSH access to Google Compute Engine instances,

     

       101
       101
       +
            which supersedes the imperative and broken

     

       102
       102
       +
            <literal>google-accounts-daemon</literal> used in

     

       103
       103
       +
            <literal>nixos/modules/virtualisation/google-compute-config.nix</literal>.

     

       81
       104
        
           </para>

     

       82
       105
        
          </listitem>

     

       83
       106
        
          <listitem>

     
···

       87
       110
        
          </listitem>

     

       88
       111
        
          <listitem>

     

       89
       112
        
           <para>

     

       90
       90
       -
            There is a new <varname>services.cockroachdb</varname> module for running CockroachDB databases. NixOS now ships with CockroachDB 2.1.x as well, available on <literal>x86_64-linux</literal> and <literal>aarch64-linux</literal>.

     

       113
       113
       +
            There is a new <varname>services.cockroachdb</varname> module for running

     

       114
       114
       +
            CockroachDB databases. NixOS now ships with CockroachDB 2.1.x as well,

     

       115
       115
       +
            available on <literal>x86_64-linux</literal> and

     

       116
       116
       +
            <literal>aarch64-linux</literal>.

     

       91
       117
        
           </para>

     

       92
       118
        
          </listitem>

     

       93
       119
        
         </itemizedlist>

     
···

       100
       126
        
          </listitem>

     

       101
       127
        
          <listitem>

     

       102
       128
        
           <para>

     

       103
       103
       -
            The <link xlink:href="https://duo.com/docs/duounix">PAM module for Duo Security</link> has been enabled for use. One can configure it using the <option>security.duosec</option> options along with the corresponding PAM option in <option>security.pam.services.&lt;name?&gt;.duoSecurity.enable</option>.

     

       129
       129
       +
            The <link xlink:href="https://duo.com/docs/duounix">PAM module for Duo

     

       130
       130
       +
            Security</link> has been enabled for use. One can configure it using the

     

       131
       131
       +
            <option>security.duosec</option> options along with the corresponding PAM

     

       132
       132
       +
            option in

     

       133
       133
       +
            <option>security.pam.services.&lt;name?&gt;.duoSecurity.enable</option>.

     

       104
       134
        
           </para>

     

       105
       135
        
          </listitem>

     

       106
       136
        
         </itemizedlist>

     
···

       114
       144
        
         <title>Backward Incompatibilities</title>

     

       115
       145
        
       

     

       116
       146
        
         <para>

     

       117
       117
       -
          When upgrading from a previous release, please be aware of the following incompatible changes:

     

       147
       147
       +
          When upgrading from a previous release, please be aware of the following

     

       148
       148
       +
          incompatible changes:

     

       118
       149
        
         </para>

     

       119
       150
        
       

     

       120
       151
        
         <itemizedlist>

     
···

       125
       156
        
           <itemizedlist>

     

       126
       157
        
            <listitem>

     

       127
       158
        
             <para>

     

       128
       128
       -
              For users of NixOS 18.03 and 19.03, NixOS defaults to Nix 2.0, but supports using Nix 1.11 by setting <literal>nix.package = pkgs.nix1;</literal>. If this option is set to a Nix 1.11 package, you will need to either unset the option or upgrade it to Nix 2.0.

     

       159
       159
       +
              For users of NixOS 18.03 and 19.03, NixOS defaults to Nix 2.0, but

     

       160
       160
       +
              supports using Nix 1.11 by setting <literal>nix.package =

     

       161
       161
       +
              pkgs.nix1;</literal>. If this option is set to a Nix 1.11 package, you

     

       162
       162
       +
              will need to either unset the option or upgrade it to Nix 2.0.

     

       129
       163
        
             </para>

     

       130
       164
        
            </listitem>

     

       131
       165
        
            <listitem>

     

       132
       166
        
             <para>

     

       133
       133
       -
              For users of NixOS 17.09, you will first need to upgrade Nix by setting <literal>nix.package = pkgs.nixStable2;</literal> and run <command>nixos-rebuild switch</command> as the <literal>root</literal> user.

     

       167
       167
       +
              For users of NixOS 17.09, you will first need to upgrade Nix by setting

     

       168
       168
       +
              <literal>nix.package = pkgs.nixStable2;</literal> and run

     

       169
       169
       +
              <command>nixos-rebuild switch</command> as the <literal>root</literal>

     

       170
       170
       +
              user.

     

       134
       171
        
             </para>

     

       135
       172
        
            </listitem>

     

       136
       173
        
            <listitem>

     

       137
       174
        
             <para>

     

       138
       138
       -
              For users of a daemon-less Nix installation on Linux or macOS, you can upgrade Nix by running <command>curl https://nixos.org/nix/install | sh</command>, or prior to doing a channel update, running <command>nix-env -iA nix</command>.

     

       175
       175
       +
              For users of a daemon-less Nix installation on Linux or macOS, you can

     

       176
       176
       +
              upgrade Nix by running <command>curl https://nixos.org/nix/install |

     

       177
       177
       +
              sh</command>, or prior to doing a channel update, running

     

       178
       178
       +
              <command>nix-env -iA nix</command>.

     

       139
       179
        
             </para>

     

       140
       180
        
             <para>

     

       141
       141
       -
              If you have already run a channel update and Nix is no longer able to evaluate Nixpkgs, the error message printed should provide adequate directions for upgrading Nix.

     

       181
       181
       +
              If you have already run a channel update and Nix is no longer able to

     

       182
       182
       +
              evaluate Nixpkgs, the error message printed should provide adequate

     

       183
       183
       +
              directions for upgrading Nix.

     

       142
       184
        
             </para>

     

       143
       185
        
            </listitem>

     

       144
       186
        
            <listitem>

     

       145
       187
        
             <para>

     

       146
       146
       -
              For users of the Nix daemon on macOS, you can upgrade Nix by running <command>sudo -i sh -c 'nix-channel --update &amp;&amp; nix-env -iA nixpkgs.nix'; sudo launchctl stop org.nixos.nix-daemon; sudo launchctl start org.nixos.nix-daemon</command>.

     

       188
       188
       +
              For users of the Nix daemon on macOS, you can upgrade Nix by running

     

       189
       189
       +
              <command>sudo -i sh -c 'nix-channel --update &amp;&amp; nix-env -iA

     

       190
       190
       +
              nixpkgs.nix'; sudo launchctl stop org.nixos.nix-daemon; sudo launchctl

     

       191
       191
       +
              start org.nixos.nix-daemon</command>.

     

       147
       192
        
             </para>

     

       148
       193
        
            </listitem>

     

       149
       194
        
           </itemizedlist>

     

       150
       195
        
          </listitem>

     

       151
       196
        
          <listitem>

     

       152
       197
        
           <para>

     

       153
       153
       -
            The <varname>buildPythonPackage</varname> function now sets <varname>strictDeps = true</varname> to help distinguish between native and non-native dependencies in order to improve cross-compilation compatibility. Note however that this may break user expressions.

     

       198
       198
       +
            The <varname>buildPythonPackage</varname> function now sets

     

       199
       199
       +
            <varname>strictDeps = true</varname> to help distinguish between native

     

       200
       200
       +
            and non-native dependencies in order to improve cross-compilation

     

       201
       201
       +
            compatibility. Note however that this may break user expressions.

     

       154
       202
        
           </para>

     

       155
       203
        
          </listitem>

     

       156
       204
        
          <listitem>

     

       157
       205
        
           <para>

     

       158
       158
       -
            The <varname>buildPythonPackage</varname> function now sets <varname>LANG = C.UTF-8</varname> to enable Unicode support. The <varname>glibcLocales</varname> package is no longer needed as a build input.

     

       206
       206
       +
            The <varname>buildPythonPackage</varname> function now sets <varname>LANG

     

       207
       207
       +
            = C.UTF-8</varname> to enable Unicode support. The

     

       208
       208
       +
            <varname>glibcLocales</varname> package is no longer needed as a build

     

       209
       209
       +
            input.

     

       159
       210
        
           </para>

     

       160
       211
        
          </listitem>

     

       161
       212
        
          <listitem>

     

       162
       213
        
           <para>

     

       163
       163
       -
            The Syncthing state and configuration data has been moved from <varname>services.syncthing.dataDir</varname> to the newly defined <varname>services.syncthing.configDir</varname>, which default to <literal>/var/lib/syncthing/.config/syncthing</literal>. This change makes possible to share synced directories using ACLs without Syncthing resetting the permission on every start.

     

       214
       214
       +
            The Syncthing state and configuration data has been moved from

     

       215
       215
       +
            <varname>services.syncthing.dataDir</varname> to the newly defined

     

       216
       216
       +
            <varname>services.syncthing.configDir</varname>, which default to

     

       217
       217
       +
            <literal>/var/lib/syncthing/.config/syncthing</literal>. This change makes

     

       218
       218
       +
            possible to share synced directories using ACLs without Syncthing

     

       219
       219
       +
            resetting the permission on every start.

     

       164
       220
        
           </para>

     

       165
       221
        
          </listitem>

     

       166
       222
        
          <listitem>

     

       167
       223
        
           <para>

     

       168
       168
       -
            The <literal>ntp</literal> module now has sane default restrictions. If you're relying on the previous defaults, which permitted all queries and commands from all firewall-permitted sources, you can set <varname>services.ntp.restrictDefault</varname> and <varname>services.ntp.restrictSource</varname> to <literal>[]</literal>.

     

       224
       224
       +
            The <literal>ntp</literal> module now has sane default restrictions. If

     

       225
       225
       +
            you're relying on the previous defaults, which permitted all queries and

     

       226
       226
       +
            commands from all firewall-permitted sources, you can set

     

       227
       227
       +
            <varname>services.ntp.restrictDefault</varname> and

     

       228
       228
       +
            <varname>services.ntp.restrictSource</varname> to <literal>[]</literal>.

     

       169
       229
        
           </para>

     

       170
       230
        
          </listitem>

     

       171
       231
        
          <listitem>

     

       172
       232
        
           <para>

     

       173
       173
       -
            Package <varname>rabbitmq_server</varname> is renamed to <varname>rabbitmq-server</varname>.

     

       233
       233
       +
            Package <varname>rabbitmq_server</varname> is renamed to

     

       234
       234
       +
            <varname>rabbitmq-server</varname>.

     

       174
       235
        
           </para>

     

       175
       236
        
          </listitem>

     

       176
       237
        
          <listitem>

     

       177
       238
        
           <para>

     

       178
       178
       -
            The <literal>light</literal> module no longer uses setuid binaries, but udev rules. As a consequence users of that module have to belong to the <literal>video</literal> group in order to use the executable (i.e. <literal>users.users.yourusername.extraGroups = ["video"];</literal>).

     

       239
       239
       +
            The <literal>light</literal> module no longer uses setuid binaries, but

     

       240
       240
       +
            udev rules. As a consequence users of that module have to belong to the

     

       241
       241
       +
            <literal>video</literal> group in order to use the executable (i.e.

     

       242
       242
       +
            <literal>users.users.yourusername.extraGroups = ["video"];</literal>).

     

       179
       243
        
           </para>

     

       180
       244
        
          </listitem>

     

       181
       245
        
          <listitem>

     

       182
       246
        
           <para>

     

       183
       183
       -
            Buildbot now supports Python 3 and its packages have been moved to <literal>pythonPackages</literal>. The options <option>services.buildbot-master.package</option> and <option>services.buildbot-worker.package</option> can be used to select the Python 2 or 3 version of the package.

     

       247
       247
       +
            Buildbot now supports Python 3 and its packages have been moved to

     

       248
       248
       +
            <literal>pythonPackages</literal>. The options

     

       249
       249
       +
            <option>services.buildbot-master.package</option> and

     

       250
       250
       +
            <option>services.buildbot-worker.package</option> can be used to select

     

       251
       251
       +
            the Python 2 or 3 version of the package.

     

       184
       252
        
           </para>

     

       185
       253
        
          </listitem>

     

       186
       254
        
          <listitem>

     

       187
       255
        
           <para>

     

       188
       188
       -
            Options <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.userName</literal> and <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.modulePackages</literal> were removed. They were never used for anything and can therefore safely be removed.

     

       256
       256
       +
            Options

     

       257
       257
       +
            <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.userName</literal>

     

       258
       258
       +
            and

     

       259
       259
       +
            <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.modulePackages</literal>

     

       260
       260
       +
            were removed. They were never used for anything and can therefore safely

     

       261
       261
       +
            be removed.

     

       189
       262
        
           </para>

     

       190
       263
        
          </listitem>

     

       191
       264
        
          <listitem>

     

       192
       265
        
           <para>

     

       193
       193
       -
            Package <literal>wasm</literal> has been renamed <literal>proglodyte-wasm</literal>. The package <literal>wasm</literal> will be pointed to <literal>ocamlPackages.wasm</literal> in 19.09, so make sure to update your configuration if you want to keep <literal>proglodyte-wasm</literal>

     

       266
       266
       +
            Package <literal>wasm</literal> has been renamed

     

       267
       267
       +
            <literal>proglodyte-wasm</literal>. The package <literal>wasm</literal>

     

       268
       268
       +
            will be pointed to <literal>ocamlPackages.wasm</literal> in 19.09, so make

     

       269
       269
       +
            sure to update your configuration if you want to keep

     

       270
       270
       +
            <literal>proglodyte-wasm</literal>

     

       194
       271
        
           </para>

     

       195
       272
        
          </listitem>

     

       196
       273
        
          <listitem>

     

       197
       274
        
           <para>

     

       198
       198
       -
            When the <literal>nixpkgs.pkgs</literal> option is set, NixOS will no longer ignore the <literal>nixpkgs.overlays</literal> option. The old behavior can be recovered by setting <literal>nixpkgs.overlays = lib.mkForce [];</literal>.

     

       275
       275
       +
            When the <literal>nixpkgs.pkgs</literal> option is set, NixOS will no

     

       276
       276
       +
            longer ignore the <literal>nixpkgs.overlays</literal> option. The old

     

       277
       277
       +
            behavior can be recovered by setting <literal>nixpkgs.overlays =

     

       278
       278
       +
            lib.mkForce [];</literal>.

     

       199
       279
        
           </para>

     

       200
       280
        
          </listitem>

     

       201
       281
        
          <listitem>

     

       202
       282
        
           <para>

     

       203
       203
       -
            OpenSMTPD has been upgraded to version 6.4.0p1. This release makes backwards-incompatible changes to the configuration file format. See <command>man smtpd.conf</command> for more information on the new file format.

     

       283
       283
       +
            OpenSMTPD has been upgraded to version 6.4.0p1. This release makes

     

       284
       284
       +
            backwards-incompatible changes to the configuration file format. See

     

       285
       285
       +
            <command>man smtpd.conf</command> for more information on the new file

     

       286
       286
       +
            format.

     

       204
       287
        
           </para>

     

       205
       288
        
          </listitem>

     

       206
       289
        
          <listitem>

     

       207
       290
        
           <para>

     

       208
       208
       -
            The versioned <varname>postgresql</varname> have been renamed to use underscore number seperators. For example, <varname>postgresql96</varname> has been renamed to <varname>postgresql_9_6</varname>.

     

       291
       291
       +
            The versioned <varname>postgresql</varname> have been renamed to use

     

       292
       292
       +
            underscore number seperators. For example, <varname>postgresql96</varname>

     

       293
       293
       +
            has been renamed to <varname>postgresql_9_6</varname>.

     

       209
       294
        
           </para>

     

       210
       295
        
          </listitem>

     

       211
       296
        
          <listitem>

     

       212
       297
        
           <para>

     

       213
       213
       -
            Package <literal>consul-ui</literal> and passthrough <literal>consul.ui</literal> have been removed. The package <literal>consul</literal> now uses upstream releases that vendor the UI into the binary. See <link xlink:href="https://github.com/NixOS/nixpkgs/pull/48714#issuecomment-433454834">#48714</link> for details.

     

       298
       298
       +
            Package <literal>consul-ui</literal> and passthrough

     

       299
       299
       +
            <literal>consul.ui</literal> have been removed. The package

     

       300
       300
       +
            <literal>consul</literal> now uses upstream releases that vendor the UI

     

       301
       301
       +
            into the binary. See

     

       302
       302
       +
            <link xlink:href="https://github.com/NixOS/nixpkgs/pull/48714#issuecomment-433454834">#48714</link>

     

       303
       303
       +
            for details.

     

       214
       304
        
           </para>

     

       215
       305
        
          </listitem>

     

       216
       306
        
          <listitem>

     

       217
       307
        
           <para>

     

       218
       218
       -
            Slurm introduces the new option <literal>services.slurm.stateSaveLocation</literal>, which is now set to <literal>/var/spool/slurm</literal> by default (instead of <literal>/var/spool</literal>). Make sure to move all files to the new directory or to set the option accordingly.

     

       308
       308
       +
            Slurm introduces the new option

     

       309
       309
       +
            <literal>services.slurm.stateSaveLocation</literal>, which is now set to

     

       310
       310
       +
            <literal>/var/spool/slurm</literal> by default (instead of

     

       311
       311
       +
            <literal>/var/spool</literal>). Make sure to move all files to the new

     

       312
       312
       +
            directory or to set the option accordingly.

     

       219
       313
        
           </para>

     

       220
       314
        
           <para>

     

       221
       221
       -
            The slurmctld now runs as user <literal>slurm</literal> instead of <literal>root</literal>. If you want to keep slurmctld running as <literal>root</literal>, set <literal>services.slurm.user = root</literal>.

     

       315
       315
       +
            The slurmctld now runs as user <literal>slurm</literal> instead of

     

       316
       316
       +
            <literal>root</literal>. If you want to keep slurmctld running as

     

       317
       317
       +
            <literal>root</literal>, set <literal>services.slurm.user =

     

       318
       318
       +
            root</literal>.

     

       222
       319
        
           </para>

     

       223
       320
        
           <para>

     

       224
       224
       -
            The options <literal>services.slurm.nodeName</literal> and <literal>services.slurm.partitionName</literal> are now sets of strings to correctly reflect that fact that each of these options can occour more than once in the configuration.

     

       321
       321
       +
            The options <literal>services.slurm.nodeName</literal> and

     

       322
       322
       +
            <literal>services.slurm.partitionName</literal> are now sets of strings to

     

       323
       323
       +
            correctly reflect that fact that each of these options can occour more

     

       324
       324
       +
            than once in the configuration.

     

       225
       325
        
           </para>

     

       226
       326
        
          </listitem>

     

       227
       327
        
          <listitem>

     

       228
       328
        
           <para>

     

       229
       229
       -
            The <literal>solr</literal> package has been upgraded from 4.10.3 to 7.5.0 and has undergone some major changes. The <literal>services.solr</literal> module has been updated to reflect these changes. Please review http://lucene.apache.org/solr/ carefully before upgrading.

     

       329
       329
       +
            The <literal>solr</literal> package has been upgraded from 4.10.3 to 7.5.0

     

       330
       330
       +
            and has undergone some major changes. The <literal>services.solr</literal>

     

       331
       331
       +
            module has been updated to reflect these changes. Please review

     

       332
       332
       +
            http://lucene.apache.org/solr/ carefully before upgrading.

     

       230
       333
        
           </para>

     

       231
       334
        
          </listitem>

     

       232
       335
        
          <listitem>

     

       233
       336
        
           <para>

     

       234
       234
       -
            Package <literal>ckb</literal> is renamed to <literal>ckb-next</literal>, and options <literal>hardware.ckb.*</literal> are renamed to <literal>hardware.ckb-next.*</literal>.

     

       337
       337
       +
            Package <literal>ckb</literal> is renamed to <literal>ckb-next</literal>,

     

       338
       338
       +
            and options <literal>hardware.ckb.*</literal> are renamed to

     

       339
       339
       +
            <literal>hardware.ckb-next.*</literal>.

     

       235
       340
        
           </para>

     

       236
       341
        
          </listitem>

     

       237
       342
        
          <listitem>

     

       238
       343
        
           <para>

     

       239
       239
       -
            The option <literal>services.xserver.displayManager.job.logToFile</literal> which was previously set to <literal>true</literal> when using the display managers <literal>lightdm</literal>, <literal>sddm</literal> or <literal>xpra</literal> has been reset to the default value (<literal>false</literal>).

     

       344
       344
       +
            The option

     

       345
       345
       +
            <literal>services.xserver.displayManager.job.logToFile</literal> which was

     

       346
       346
       +
            previously set to <literal>true</literal> when using the display managers

     

       347
       347
       +
            <literal>lightdm</literal>, <literal>sddm</literal> or

     

       348
       348
       +
            <literal>xpra</literal> has been reset to the default value

     

       349
       349
       +
            (<literal>false</literal>).

     

       240
       350
        
           </para>

     

       241
       351
        
          </listitem>

     

       242
       352
        
          <listitem>

     

       243
       353
        
           <para>

     

       244
       244
       -
            Network interface indiscriminate NixOS firewall options (<literal>networking.firewall.allow*</literal>) are now preserved when also setting interface specific rules such as <literal>networking.firewall.interfaces.en0.allow*</literal>. These rules continue to use the pseudo device "default" (<literal>networking.firewall.interfaces.default.*</literal>), and assigning to this pseudo device will override the (<literal>networking.firewall.allow*</literal>) options.

     

       354
       354
       +
            Network interface indiscriminate NixOS firewall options

     

       355
       355
       +
            (<literal>networking.firewall.allow*</literal>) are now preserved when

     

       356
       356
       +
            also setting interface specific rules such as

     

       357
       357
       +
            <literal>networking.firewall.interfaces.en0.allow*</literal>. These rules

     

       358
       358
       +
            continue to use the pseudo device "default"

     

       359
       359
       +
            (<literal>networking.firewall.interfaces.default.*</literal>), and

     

       360
       360
       +
            assigning to this pseudo device will override the

     

       361
       361
       +
            (<literal>networking.firewall.allow*</literal>) options.

     

       245
       362
        
           </para>

     

       246
       363
        
          </listitem>

     

       247
       364
        
          <listitem>

     

       248
       365
        
           <para>

     

       249
       249
       -
            The <literal>nscd</literal> service now disables all caching of <literal>passwd</literal> and <literal>group</literal> databases by default. This was interferring with the correct functioning of the <literal>libnss_systemd.so</literal> module which is used by <literal>systemd</literal> to manage uids and usernames in the presence of <literal>DynamicUser=</literal> in systemd services. This was already the default behaviour in presence of <literal>services.sssd.enable = true</literal> because nscd caching would interfere with <literal>sssd</literal> in unpredictable ways as well. Because we're using nscd not for caching, but for convincing glibc to find NSS modules in the nix store instead of an absolute path, we have decided to disable caching globally now, as it's usually not the behaviour the user wants and can lead to surprising behaviour. Furthermore, negative caching of host lookups is also disabled now by default. This should fix the issue of dns lookups failing in the presence of an unreliable network.

     

       366
       366
       +
            The <literal>nscd</literal> service now disables all caching of

     

       367
       367
       +
            <literal>passwd</literal> and <literal>group</literal> databases by

     

       368
       368
       +
            default. This was interferring with the correct functioning of the

     

       369
       369
       +
            <literal>libnss_systemd.so</literal> module which is used by

     

       370
       370
       +
            <literal>systemd</literal> to manage uids and usernames in the presence of

     

       371
       371
       +
            <literal>DynamicUser=</literal> in systemd services. This was already the

     

       372
       372
       +
            default behaviour in presence of <literal>services.sssd.enable =

     

       373
       373
       +
            true</literal> because nscd caching would interfere with

     

       374
       374
       +
            <literal>sssd</literal> in unpredictable ways as well. Because we're using

     

       375
       375
       +
            nscd not for caching, but for convincing glibc to find NSS modules in the

     

       376
       376
       +
            nix store instead of an absolute path, we have decided to disable caching

     

       377
       377
       +
            globally now, as it's usually not the behaviour the user wants and can

     

       378
       378
       +
            lead to surprising behaviour. Furthermore, negative caching of host

     

       379
       379
       +
            lookups is also disabled now by default. This should fix the issue of dns

     

       380
       380
       +
            lookups failing in the presence of an unreliable network.

     

       250
       381
        
           </para>

     

       251
       382
        
           <para>

     

       252
       252
       -
            If the old behaviour is desired, this can be restored by setting the <literal>services.nscd.config</literal> option with the desired caching parameters.

     

       383
       383
       +
            If the old behaviour is desired, this can be restored by setting the

     

       384
       384
       +
            <literal>services.nscd.config</literal> option with the desired caching

     

       385
       385
       +
            parameters.

     

       253
       386
        
       <programlisting>

     

       254
       387
        
            services.nscd.config =

     

       255
       388
        
            ''

     
···

       283
       416
        
            shared                  hosts           yes

     

       284
       417
        
            '';

     

       285
       418
        
            </programlisting>

     

       286
       286
       -
            See <link xlink:href="https://github.com/NixOS/nixpkgs/pull/50316">#50316</link> for details.

     

       419
       419
       +
            See

     

       420
       420
       +
            <link xlink:href="https://github.com/NixOS/nixpkgs/pull/50316">#50316</link>

     

       421
       421
       +
            for details.

     

       287
       422
        
           </para>

     

       288
       423
        
          </listitem>

     

       289
       424
        
          <listitem>

     

       290
       425
        
           <para>

     

       291
       291
       -
            GitLab Shell previously used the nix store paths for the <literal>gitlab-shell</literal> command in its <literal>authorized_keys</literal> file, which might stop working after garbage collection. To circumvent that, we regenerated that file on each startup. As <literal>gitlab-shell</literal> has now been changed to use <literal>/var/run/current-system/sw/bin/gitlab-shell</literal>, this is not necessary anymore, but there might be leftover lines with a nix store path. Regenerate the <literal>authorized_keys</literal> file via <command>sudo -u git -H gitlab-rake gitlab:shell:setup</command> in that case.

     

       426
       426
       +
            GitLab Shell previously used the nix store paths for the

     

       427
       427
       +
            <literal>gitlab-shell</literal> command in its

     

       428
       428
       +
            <literal>authorized_keys</literal> file, which might stop working after

     

       429
       429
       +
            garbage collection. To circumvent that, we regenerated that file on each

     

       430
       430
       +
            startup. As <literal>gitlab-shell</literal> has now been changed to use

     

       431
       431
       +
            <literal>/var/run/current-system/sw/bin/gitlab-shell</literal>, this is

     

       432
       432
       +
            not necessary anymore, but there might be leftover lines with a nix store

     

       433
       433
       +
            path. Regenerate the <literal>authorized_keys</literal> file via

     

       434
       434
       +
            <command>sudo -u git -H gitlab-rake gitlab:shell:setup</command> in that

     

       435
       435
       +
            case.

     

       292
       436
        
           </para>

     

       293
       437
        
          </listitem>

     

       294
       438
        
          <listitem>

     

       295
       439
        
           <para>

     

       296
       296
       -
            The <literal>pam_unix</literal> account module is now loaded with its control field set to <literal>required</literal> instead of <literal>sufficient</literal>, so that later PAM account modules that might do more extensive checks are being executed. Previously, the whole account module verification was exited prematurely in case a nss module provided the account name to <literal>pam_unix</literal>. The LDAP and SSSD NixOS modules already add their NSS modules when enabled. In case your setup breaks due to some later PAM account module previosuly shadowed, or failing NSS lookups, please file a bug. You can get back the old behaviour by manually setting <literal>

     

       440
       440
       +
            The <literal>pam_unix</literal> account module is now loaded with its

     

       441
       441
       +
            control field set to <literal>required</literal> instead of

     

       442
       442
       +
            <literal>sufficient</literal>, so that later PAM account modules that

     

       443
       443
       +
            might do more extensive checks are being executed. Previously, the whole

     

       444
       444
       +
            account module verification was exited prematurely in case a nss module

     

       445
       445
       +
            provided the account name to <literal>pam_unix</literal>. The LDAP and

     

       446
       446
       +
            SSSD NixOS modules already add their NSS modules when enabled. In case

     

       447
       447
       +
            your setup breaks due to some later PAM account module previosuly

     

       448
       448
       +
            shadowed, or failing NSS lookups, please file a bug. You can get back the

     

       449
       449
       +
            old behaviour by manually setting <literal>

     

       297
       450
        
       <![CDATA[security.pam.services.<name?>.text]]>

     

       298
       451
        
            </literal>.

     

       299
       452
        
           </para>

     

       300
       453
        
          </listitem>

     

       301
       454
        
          <listitem>

     

       302
       455
        
           <para>

     

       303
       303
       -
            The <literal>pam_unix</literal> password module is now loaded with its control field set to <literal>sufficient</literal> instead of <literal>required</literal>, so that password managed only by later PAM password modules are being executed. Previously, for example, changing an LDAP account's password through PAM was not possible: the whole password module verification was exited prematurely by <literal>pam_unix</literal>, preventing <literal>pam_ldap</literal> to manage the password as it should.

     

       456
       456
       +
            The <literal>pam_unix</literal> password module is now loaded with its

     

       457
       457
       +
            control field set to <literal>sufficient</literal> instead of

     

       458
       458
       +
            <literal>required</literal>, so that password managed only by later PAM

     

       459
       459
       +
            password modules are being executed. Previously, for example, changing an

     

       460
       460
       +
            LDAP account's password through PAM was not possible: the whole password

     

       461
       461
       +
            module verification was exited prematurely by <literal>pam_unix</literal>,

     

       462
       462
       +
            preventing <literal>pam_ldap</literal> to manage the password as it

     

       463
       463
       +
            should.

     

       304
       464
        
           </para>

     

       305
       465
        
          </listitem>

     

       306
       466
        
          <listitem>

     

       307
       467
        
           <para>

     

       308
       308
       -
            <literal>fish</literal> has been upgraded to 3.0. It comes with a number of improvements and backwards incompatible changes. See the <literal>fish</literal> <link xlink:href="https://github.com/fish-shell/fish-shell/releases/tag/3.0.0">release notes</link> for more information.

     

       468
       468
       +
            <literal>fish</literal> has been upgraded to 3.0. It comes with a number

     

       469
       469
       +
            of improvements and backwards incompatible changes. See the

     

       470
       470
       +
            <literal>fish</literal>

     

       471
       471
       +
            <link xlink:href="https://github.com/fish-shell/fish-shell/releases/tag/3.0.0">release

     

       472
       472
       +
            notes</link> for more information.

     

       309
       473
        
           </para>

     

       310
       474
        
          </listitem>

     

       311
       475
        
          <listitem>

     

       312
       476
        
           <para>

     

       313
       313
       -
            The ibus-table input method has had a change in config format, which causes all previous settings to be lost. See <link xlink:href="https://github.com/mike-fabian/ibus-table/commit/f9195f877c5212fef0dfa446acb328c45ba5852b">this commit message</link> for details.

     

       477
       477
       +
            The ibus-table input method has had a change in config format, which

     

       478
       478
       +
            causes all previous settings to be lost. See

     

       479
       479
       +
            <link xlink:href="https://github.com/mike-fabian/ibus-table/commit/f9195f877c5212fef0dfa446acb328c45ba5852b">this

     

       480
       480
       +
            commit message</link> for details.

     

       314
       481
        
           </para>

     

       315
       482
        
          </listitem>

     

       316
       483
        
          <listitem>

     

       317
       484
        
           <para>

     

       318
       318
       -
            NixOS module system type <literal>types.optionSet</literal> and <literal>lib.mkOption</literal> argument <literal>options</literal> are deprecated. Use <literal>types.submodule</literal> instead. (<link xlink:href="https://github.com/NixOS/nixpkgs/pull/54637">#54637</link>)

     

       485
       485
       +
            NixOS module system type <literal>types.optionSet</literal> and

     

       486
       486
       +
            <literal>lib.mkOption</literal> argument <literal>options</literal> are

     

       487
       487
       +
            deprecated. Use <literal>types.submodule</literal> instead.

     

       488
       488
       +
            (<link xlink:href="https://github.com/NixOS/nixpkgs/pull/54637">#54637</link>)

     

       319
       489
        
           </para>

     

       320
       490
        
          </listitem>

     

       321
       491
        
          <listitem>

     

       322
       492
        
           <para>

     

       323
       323
       -
            <literal>matrix-synapse</literal> has been updated to version 0.99. It will <link xlink:href="https://github.com/matrix-org/synapse/pull/4509">no longer generate a self-signed certificate on first launch</link> and will be <link xlink:href="https://matrix.org/blog/2019/02/05/synapse-0-99-0/">the last version to accept self-signed certificates</link>. As such, it is now recommended to use a proper certificate verified by a root CA (for example Let's Encrypt). The new <link linkend="module-services-matrix">manual chapter on Matrix</link> contains a working example of using nginx as a reverse proxy in front of <literal>matrix-synapse</literal>, using Let's Encrypt certificates.

     

       493
       493
       +
            <literal>matrix-synapse</literal> has been updated to version 0.99. It

     

       494
       494
       +
            will <link xlink:href="https://github.com/matrix-org/synapse/pull/4509">no

     

       495
       495
       +
            longer generate a self-signed certificate on first launch</link> and will

     

       496
       496
       +
            be

     

       497
       497
       +
            <link xlink:href="https://matrix.org/blog/2019/02/05/synapse-0-99-0/">the

     

       498
       498
       +
            last version to accept self-signed certificates</link>. As such, it is now

     

       499
       499
       +
            recommended to use a proper certificate verified by a root CA (for example

     

       500
       500
       +
            Let's Encrypt). The new <link linkend="module-services-matrix">manual

     

       501
       501
       +
            chapter on Matrix</link> contains a working example of using nginx as a

     

       502
       502
       +
            reverse proxy in front of <literal>matrix-synapse</literal>, using Let's

     

       503
       503
       +
            Encrypt certificates.

     

       324
       504
        
           </para>

     

       325
       505
        
          </listitem>

     

       326
       506
        
          <listitem>

     

       327
       507
        
           <para>

     

       328
       328
       -
            <literal>mailutils</literal> now works by default when <literal>sendmail</literal> is not in a setuid wrapper. As a consequence, the <literal>sendmailPath</literal> argument, having lost its main use, has been removed.

     

       508
       508
       +
            <literal>mailutils</literal> now works by default when

     

       509
       509
       +
            <literal>sendmail</literal> is not in a setuid wrapper. As a consequence,

     

       510
       510
       +
            the <literal>sendmailPath</literal> argument, having lost its main use,

     

       511
       511
       +
            has been removed.

     

       329
       512
        
           </para>

     

       330
       513
        
          </listitem>

     

       331
       514
        
          <listitem>

     

       332
       515
        
           <para>

     

       333
       333
       -
            <literal>graylog</literal> has been upgraded from version 2.* to 3.*. Some setups making use of extraConfig (especially those exposing Graylog via reverse proxies) need to be updated as upstream removed/replaced some settings. See <link xlink:href="http://docs.graylog.org/en/3.0/pages/upgrade/graylog-3.0.html#simplified-http-interface-configuration">Upgrading Graylog</link> for details.

     

       516
       516
       +
            <literal>graylog</literal> has been upgraded from version 2.* to 3.*. Some

     

       517
       517
       +
            setups making use of extraConfig (especially those exposing Graylog via

     

       518
       518
       +
            reverse proxies) need to be updated as upstream removed/replaced some

     

       519
       519
       +
            settings. See

     

       520
       520
       +
            <link xlink:href="http://docs.graylog.org/en/3.0/pages/upgrade/graylog-3.0.html#simplified-http-interface-configuration">Upgrading

     

       521
       521
       +
            Graylog</link> for details.

     

       334
       522
        
           </para>

     

       335
       523
        
          </listitem>

     

       336
       524
        
          <listitem>

     

       337
       525
        
           <para>

     

       338
       338
       -
            The option <literal>users.ldap.bind.password</literal> was renamed to <literal>users.ldap.bind.passwordFile</literal>, and needs to be readable by the <literal>nslcd</literal> user. Same applies to the new <literal>users.ldap.daemon.rootpwmodpwFile</literal> option.

     

       526
       526
       +
             The option <literal>users.ldap.bind.password</literal> was renamed to <literal>users.ldap.bind.passwordFile</literal>,

     

       527
       527
       +
             and needs to be readable by the <literal>nslcd</literal> user.

     

       528
       528
       +
             Same applies to the new <literal>users.ldap.daemon.rootpwmodpwFile</literal> option.

     

       339
       529
        
           </para>

     

       340
       530
        
          </listitem>

     

       341
       531
        
          <listitem>

     

       342
       342
       -
           <para>

     

       343
       343
       -
            <literal>nodejs-6_x</literal> is end-of-life. <literal>nodejs-6_x</literal>, <literal>nodejs-slim-6_x</literal> and <literal>nodePackages_6_x</literal> are removed.

     

       344
       344
       -
           </para>

     

       532
       532
       +
            <para>

     

       533
       533
       +
              <literal>nodejs-6_x</literal> is end-of-life.

     

       534
       534
       +
              <literal>nodejs-6_x</literal>, <literal>nodejs-slim-6_x</literal> and

     

       535
       535
       +
              <literal>nodePackages_6_x</literal> are removed.

     

       536
       536
       +
            </para>

     

       345
       537
        
          </listitem>

     

       346
       538
        
         </itemizedlist>

     

       347
       539
        
        </section>

     
···

       356
       548
        
         <itemizedlist>

     

       357
       549
        
          <listitem>

     

       358
       550
        
           <para>

     

       359
       359
       -
            The <option>services.matomo</option> module gained the option <option>services.matomo.package</option> which determines the used Matomo version.

     

       551
       551
       +
            The <option>services.matomo</option> module gained the option

     

       552
       552
       +
            <option>services.matomo.package</option> which determines the used Matomo

     

       553
       553
       +
            version.

     

       360
       554
        
           </para>

     

       361
       555
        
           <para>

     

       362
       362
       -
            The Matomo module now also comes with the systemd service <literal>matomo-archive-processing.service</literal> and a timer that automatically triggers archive processing every hour. This means that you can safely <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour"> disable browser triggers for Matomo archiving </link> at <literal>Administration > System > General Settings</literal>.

     

       556
       556
       +
            The Matomo module now also comes with the systemd service

     

       557
       557
       +
            <literal>matomo-archive-processing.service</literal> and a timer that

     

       558
       558
       +
            automatically triggers archive processing every hour. This means that you

     

       559
       559
       +
            can safely

     

       560
       560
       +
            <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour">

     

       561
       561
       +
            disable browser triggers for Matomo archiving </link> at

     

       562
       562
       +
            <literal>Administration > System > General Settings</literal>.

     

       363
       563
        
           </para>

     

       364
       564
        
           <para>

     

       365
       365
       -
            Additionally, you can enable to <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs"> delete old visitor logs </link> at <literal>Administration > System > Privacy</literal>, but make sure that you run <literal>systemctl start matomo-archive-processing.service</literal> at least once without errors if you have already collected data before, so that the reports get archived before the source data gets deleted.

     

       565
       565
       +
            Additionally, you can enable to

     

       566
       566
       +
            <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs">

     

       567
       567
       +
            delete old visitor logs </link> at <literal>Administration > System >

     

       568
       568
       +
            Privacy</literal>, but make sure that you run <literal>systemctl start

     

       569
       569
       +
            matomo-archive-processing.service</literal> at least once without errors

     

       570
       570
       +
            if you have already collected data before, so that the reports get

     

       571
       571
       +
            archived before the source data gets deleted.

     

       366
       572
        
           </para>

     

       367
       573
        
          </listitem>

     

       368
       574
        
          <listitem>

     

       369
       575
        
           <para>

     

       370
       370
       -
            <literal>composableDerivation</literal> along with supporting library functions has been removed.

     

       576
       576
       +
            <literal>composableDerivation</literal> along with supporting library

     

       577
       577
       +
            functions has been removed.

     

       371
       578
        
           </para>

     

       372
       579
        
          </listitem>

     

       373
       580
        
          <listitem>

     

       374
       581
        
           <para>

     

       375
       375
       -
            The deprecated <literal>truecrypt</literal> package has been removed and <literal>truecrypt</literal> attribute is now an alias for <literal>veracrypt</literal>. VeraCrypt is backward-compatible with TrueCrypt volumes. Note that <literal>cryptsetup</literal> also supports loading TrueCrypt volumes.

     

       582
       582
       +
            The deprecated <literal>truecrypt</literal> package has been removed and

     

       583
       583
       +
            <literal>truecrypt</literal> attribute is now an alias for

     

       584
       584
       +
            <literal>veracrypt</literal>. VeraCrypt is backward-compatible with

     

       585
       585
       +
            TrueCrypt volumes. Note that <literal>cryptsetup</literal> also supports

     

       586
       586
       +
            loading TrueCrypt volumes.

     

       376
       587
        
           </para>

     

       377
       588
        
          </listitem>

     

       378
       589
        
          <listitem>

     

       379
       590
        
           <para>

     

       380
       380
       -
            The Kubernetes DNS addons, kube-dns, has been replaced with CoreDNS. This change is made in accordance with Kubernetes making CoreDNS the official default starting from <link xlink:href="https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md#sig-cluster-lifecycle">Kubernetes v1.11</link>. Please beware that upgrading DNS-addon on existing clusters might induce minor downtime while the DNS-addon terminates and re-initializes. Also note that the DNS-service now runs with 2 pod replicas by default. The desired number of replicas can be configured using: <option>services.kubernetes.addons.dns.replicas</option>.

     

       591
       591
       +
            The Kubernetes DNS addons, kube-dns, has been replaced with CoreDNS. This

     

       592
       592
       +
            change is made in accordance with Kubernetes making CoreDNS the official

     

       593
       593
       +
            default starting from

     

       594
       594
       +
            <link xlink:href="https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md#sig-cluster-lifecycle">Kubernetes

     

       595
       595
       +
            v1.11</link>. Please beware that upgrading DNS-addon on existing clusters

     

       596
       596
       +
            might induce minor downtime while the DNS-addon terminates and

     

       597
       597
       +
            re-initializes. Also note that the DNS-service now runs with 2 pod

     

       598
       598
       +
            replicas by default. The desired number of replicas can be configured

     

       599
       599
       +
            using: <option>services.kubernetes.addons.dns.replicas</option>.

     

       381
       600
        
           </para>

     

       382
       601
        
          </listitem>

     

       383
       602
        
          <listitem>

     

       384
       603
        
           <para>

     

       385
       385
       -
            The quassel-webserver package and module was removed from nixpkgs due to the lack of maintainers.

     

       604
       604
       +
            The quassel-webserver package and module was removed from nixpkgs due to

     

       605
       605
       +
            the lack of maintainers.

     

       386
       606
        
           </para>

     

       387
       607
        
          </listitem>

     

       388
       608
        
          <listitem>

     

       389
       609
        
           <para>

     

       390
       390
       -
            The manual gained a <link linkend="module-services-matrix"> new chapter on self-hosting <literal>matrix-synapse</literal> and <literal>riot-web</literal> </link>, the most prevalent server and client implementations for the <link xlink:href="https://matrix.org/">Matrix</link> federated communication network.

     

       610
       610
       +
            The manual gained a <link linkend="module-services-matrix"> new chapter on

     

       611
       611
       +
            self-hosting <literal>matrix-synapse</literal> and

     

       612
       612
       +
            <literal>riot-web</literal> </link>, the most prevalent server and client

     

       613
       613
       +
            implementations for the

     

       614
       614
       +
            <link xlink:href="https://matrix.org/">Matrix</link> federated

     

       615
       615
       +
            communication network.

     

       391
       616
        
           </para>

     

       392
       617
        
          </listitem>

     

       393
       618
        
          <listitem>

     

       394
       619
        
           <para>

     

       395
       395
       -
            The astah-community package was removed from nixpkgs due to it being discontinued and the downloads not being available anymore.

     

       620
       620
       +
            The astah-community package was removed from nixpkgs due to it being

     

       621
       621
       +
            discontinued and the downloads not being available anymore.

     

       396
       622
        
           </para>

     

       397
       623
        
          </listitem>

     

       398
       624
        
          <listitem>

     

       399
       625
        
           <para>

     

       400
       400
       -
            The httpd service now saves log files with a .log file extension by default for easier integration with the logrotate service.

     

       626
       626
       +
            The httpd service now saves log files with a .log file extension by

     

       627
       627
       +
            default for easier integration with the logrotate service.

     

       401
       628
        
           </para>

     

       402
       629
        
          </listitem>

     

       403
       630
        
          <listitem>

     

       404
       631
        
           <para>

     

       405
       405
       -
            The owncloud server packages and httpd subservice module were removed from nixpkgs due to the lack of maintainers.

     

       632
       632
       +
            The owncloud server packages and httpd subservice module were removed from

     

       633
       633
       +
            nixpkgs due to the lack of maintainers.

     

       406
       634
        
           </para>

     

       407
       635
        
          </listitem>

     

       408
       636
        
          <listitem>

     

       409
       637
        
           <para>

     

       410
       410
       -
            It is possible now to uze ZRAM devices as general purpose ephemeral block devices, not only as swap. Using more than 1 device as ZRAM swap is no longer recommended, but is still possible by setting <literal>zramSwap.swapDevices</literal> explicitly.

     

       638
       638
       +
            It is possible now to uze ZRAM devices as general purpose ephemeral block

     

       639
       639
       +
            devices, not only as swap. Using more than 1 device as ZRAM swap is no

     

       640
       640
       +
            longer recommended, but is still possible by setting

     

       641
       641
       +
            <literal>zramSwap.swapDevices</literal> explicitly.

     

       411
       642
        
           </para>

     

       412
       643
        
           <para>

     

       413
       644
        
            ZRAM algorithm can be changed now.

     

       414
       645
        
           </para>

     

       415
       646
        
           <para>

     

       416
       416
       -
            Changes to ZRAM algorithm are applied during <literal>nixos-rebuild switch</literal>, so make sure you have enough swap space on disk to survive ZRAM device rebuild. Alternatively, use <literal>nixos-rebuild boot; reboot</literal>.

     

       647
       647
       +
            Changes to ZRAM algorithm are applied during <literal>nixos-rebuild

     

       648
       648
       +
            switch</literal>, so make sure you have enough swap space on disk to

     

       649
       649
       +
            survive ZRAM device rebuild. Alternatively, use <literal>nixos-rebuild

     

       650
       650
       +
            boot; reboot</literal>.

     

       417
       651
        
           </para>

     

       418
       652
        
          </listitem>

     

       419
       653
        
          <listitem>

     

       420
       654
        
           <para>

     

       421
       421
       -
            Flat volumes are now disabled by default in <literal>hardware.pulseaudio</literal>. This has been done to prevent applications, which are unaware of this feature, setting their volumes to 100% on startup causing harm to your audio hardware and potentially your ears.

     

       655
       655
       +
            Flat volumes are now disabled by default in

     

       656
       656
       +
            <literal>hardware.pulseaudio</literal>. This has been done to prevent

     

       657
       657
       +
            applications, which are unaware of this feature, setting their volumes to

     

       658
       658
       +
            100% on startup causing harm to your audio hardware and potentially your

     

       659
       659
       +
            ears.

     

       422
       660
        
           </para>

     

       423
       661
        
           <note>

     

       424
       662
        
            <para>

     

       425
       425
       -
             With this change application specific volumes are relative to the master volume which can be adjusted independently, whereas before they were absolute; meaning that in effect, it scaled the device-volume with the volume of the loudest application.

     

       663
       663
       +
             With this change application specific volumes are relative to the master

     

       664
       664
       +
             volume which can be adjusted independently, whereas before they were

     

       665
       665
       +
             absolute; meaning that in effect, it scaled the device-volume with the

     

       666
       666
       +
             volume of the loudest application.

     

       426
       667
        
            </para>

     

       427
       668
        
           </note>

     

       428
       669
        
          </listitem>

     

       429
       670
        
          <listitem>

     

       430
       671
        
           <para>

     

       431
       431
       -
            The <link xlink:href="https://github.com/DanielAdolfsson/ndppd"><literal>ndppd</literal></link> module now supports <link linkend="opt-services.ndppd.enable">all config options</link> provided by the current upstream version as service options. Additionally the <literal>ndppd</literal> package doesn't contain the systemd unit configuration from upstream anymore, the unit is completely configured by the NixOS module now.

     

       672
       672
       +
            The

     

       673
       673
       +
            <link xlink:href="https://github.com/DanielAdolfsson/ndppd"><literal>ndppd</literal></link>

     

       674
       674
       +
            module now supports <link linkend="opt-services.ndppd.enable">all config

     

       675
       675
       +
            options</link> provided by the current upstream version as service

     

       676
       676
       +
            options. Additionally the <literal>ndppd</literal> package doesn't contain

     

       677
       677
       +
            the systemd unit configuration from upstream anymore, the unit is

     

       678
       678
       +
            completely configured by the NixOS module now.

     

       432
       679
        
           </para>

     

       433
       680
        
          </listitem>

     

       434
       681
        
          <listitem>

     

       435
       682
        
           <para>

     

       436
       436
       -
            New installs of NixOS will default to the Redmine 4.x series unless otherwise specified in <literal>services.redmine.package</literal> while existing installs of NixOS will default to the Redmine 3.x series.

     

       683
       683
       +
            New installs of NixOS will default to the Redmine 4.x series unless

     

       684
       684
       +
            otherwise specified in <literal>services.redmine.package</literal> while

     

       685
       685
       +
            existing installs of NixOS will default to the Redmine 3.x series.

     

       437
       686
        
           </para>

     

       438
       687
        
          </listitem>

     

       439
       688
        
          <listitem>

     

       440
       689
        
           <para>

     

       441
       441
       -
            The <link linkend="opt-services.grafana.enable">Grafana module</link> now supports declarative <link xlink:href="http://docs.grafana.org/administration/provisioning/">datasource and dashboard</link> provisioning.

     

       690
       690
       +
            The <link linkend="opt-services.grafana.enable">Grafana module</link> now

     

       691
       691
       +
            supports declarative

     

       692
       692
       +
            <link xlink:href="http://docs.grafana.org/administration/provisioning/">datasource

     

       693
       693
       +
            and dashboard</link> provisioning.

     

       442
       694
        
           </para>

     

       443
       695
        
          </listitem>

     

       444
       696
        
          <listitem>

     

       445
       697
        
           <para>

     

       446
       446
       -
            The use of insecure ports on kubernetes has been deprecated. Thus options: <varname>services.kubernetes.apiserver.port</varname> and <varname>services.kubernetes.controllerManager.port</varname> has been renamed to <varname>.insecurePort</varname>, and default of both options has changed to 0 (disabled).

     

       698
       698
       +
            The use of insecure ports on kubernetes has been deprecated. Thus options:

     

       699
       699
       +
            <varname>services.kubernetes.apiserver.port</varname> and

     

       700
       700
       +
            <varname>services.kubernetes.controllerManager.port</varname> has been

     

       701
       701
       +
            renamed to <varname>.insecurePort</varname>, and default of both options

     

       702
       702
       +
            has changed to 0 (disabled).

     

       447
       703
        
           </para>

     

       448
       704
        
          </listitem>

     

       449
       705
        
          <listitem>

     

       450
       706
        
           <para>

     

       451
       451
       -
            Note that the default value of <varname>services.kubernetes.apiserver.bindAddress</varname> has changed from 127.0.0.1 to 0.0.0.0, allowing the apiserver to be accessible from outside the master node itself. If the apiserver insecurePort is enabled, it is strongly recommended to only bind on the loopback interface. See: <varname>services.kubernetes.apiserver.insecurebindAddress</varname>.

     

       707
       707
       +
            Note that the default value of

     

       708
       708
       +
            <varname>services.kubernetes.apiserver.bindAddress</varname> has changed

     

       709
       709
       +
            from 127.0.0.1 to 0.0.0.0, allowing the apiserver to be accessible from

     

       710
       710
       +
            outside the master node itself. If the apiserver insecurePort is enabled,

     

       711
       711
       +
            it is strongly recommended to only bind on the loopback interface. See:

     

       712
       712
       +
            <varname>services.kubernetes.apiserver.insecurebindAddress</varname>.

     

       452
       713
        
           </para>

     

       453
       714
        
          </listitem>

     

       454
       715
        
          <listitem>

     

       455
       716
        
           <para>

     

       456
       456
       -
            The option <varname>services.kubernetes.apiserver.allowPrivileged</varname> and <varname>services.kubernetes.kubelet.allowPrivileged</varname> now defaults to false. Disallowing privileged containers on the cluster.

     

       717
       717
       +
            The option

     

       718
       718
       +
            <varname>services.kubernetes.apiserver.allowPrivileged</varname> and

     

       719
       719
       +
            <varname>services.kubernetes.kubelet.allowPrivileged</varname> now

     

       720
       720
       +
            defaults to false. Disallowing privileged containers on the cluster.

     

       457
       721
        
           </para>

     

       458
       722
        
          </listitem>

     

       459
       723
        
          <listitem>

     

       460
       724
        
           <para>

     

       461
       461
       -
            The kubernetes module does no longer add the kubernetes package to <varname>environment.systemPackages</varname> implicitly.

     

       725
       725
       +
            The kubernetes module does no longer add the kubernetes package to

     

       726
       726
       +
            <varname>environment.systemPackages</varname> implicitly.

     

       462
       727
        
           </para>

     

       463
       728
        
          </listitem>

     

       464
       729
        
          <listitem>

     

       465
       730
        
           <para>

     

       466
       466
       -
            The <literal>intel</literal> driver has been removed from the default list of <link linkend="opt-services.xserver.videoDrivers">X.org video drivers</link>. The <literal>modesetting</literal> driver should take over automatically, it is better maintained upstream and has less problems with advanced X11 features. This can lead to a change in the output names used by <literal>xrandr</literal>. Some performance regressions on some GPU models might happen. Some OpenCL and VA-API applications might also break (Beignet seems to provide OpenCL support with <literal>modesetting</literal> driver, too). Kernel mode setting API does not support backlight control, so <literal>xbacklight</literal> tool will not work; backlight level can be controlled directly via <literal>/sys/</literal> or with <literal>brightnessctl</literal>. Users who need this functionality more than multi-output XRandR are advised to add `intel` to `videoDrivers` and report an issue (or provide additional details in an existing one)

     

       731
       731
       +
            The <literal>intel</literal> driver has been removed from the default list

     

       732
       732
       +
            of <link linkend="opt-services.xserver.videoDrivers">X.org video

     

       733
       733
       +
            drivers</link>. The <literal>modesetting</literal> driver should take over

     

       734
       734
       +
            automatically, it is better maintained upstream and has less problems with

     

       735
       735
       +
            advanced X11 features. This can lead to a change in the output names used

     

       736
       736
       +
            by <literal>xrandr</literal>. Some performance regressions on some GPU

     

       737
       737
       +
            models might happen. Some OpenCL and VA-API applications might also break

     

       738
       738
       +
            (Beignet seems to provide OpenCL support with

     

       739
       739
       +
            <literal>modesetting</literal> driver, too). Kernel mode setting API does

     

       740
       740
       +
            not support backlight control, so <literal>xbacklight</literal> tool will

     

       741
       741
       +
            not work; backlight level can be controlled directly via

     

       742
       742
       +
            <literal>/sys/</literal> or with <literal>brightnessctl</literal>. Users

     

       743
       743
       +
            who need this functionality more than multi-output XRandR are advised to

     

       744
       744
       +
            add `intel` to `videoDrivers` and report an issue (or provide additional

     

       745
       745
       +
            details in an existing one)

     

       467
       746
        
           </para>

     

       468
       747
        
          </listitem>

     

       469
       748
        
          <listitem>

     

       470
       749
        
           <para>

     

       471
       471
       -
            Openmpi has been updated to version 4.0.0, which removes some deprecated MPI-1 symbols. This may break some older applications that still rely on those symbols. An upgrade guide can be found <link xlink:href="https://www.open-mpi.org/faq/?category=mpi-removed">here</link>.

     

       750
       750
       +
            Openmpi has been updated to version 4.0.0, which removes some deprecated

     

       751
       751
       +
            MPI-1 symbols. This may break some older applications that still rely on

     

       752
       752
       +
            those symbols. An upgrade guide can be found

     

       753
       753
       +
            <link xlink:href="https://www.open-mpi.org/faq/?category=mpi-removed">here</link>.

     

       472
       754
        
           </para>

     

       473
       755
        
           <para>

     

       474
       474
       -
            The nginx package now relies on OpenSSL 1.1 and supports TLS 1.3 by default. You can set the protocols used by the nginx service using <xref linkend="opt-services.nginx.sslProtocols"/>.

     

       756
       756
       +
            The nginx package now relies on OpenSSL 1.1 and supports TLS 1.3 by

     

       757
       757
       +
            default. You can set the protocols used by the nginx service using

     

       758
       758
       +
            <xref linkend="opt-services.nginx.sslProtocols"/>.

     

       475
       759
        
           </para>

     

       476
       760
        
          </listitem>

     

       477
       761
        
          <listitem>

+406 -325

nixos/doc/manual/release-notes/rl-1909.xml

···

       13
       13
        
         <title>Highlights</title>

     

       14
       14
        
       

     

       15
       15
        
         <para>

     

       16
       16
       -
          In addition to numerous new and upgraded packages, this release has the following highlights:

     

       16
       16
       +
          In addition to numerous new and upgraded packages, this release has the

     

       17
       17
       +
          following highlights:

     

       17
       18
        
         </para>

     

       18
       19
        
       

     

       19
       20
        
         <itemizedlist>

     
···

       33
       34
        
           </para>

     

       34
       35
        
          </listitem>

     

       35
       36
        
          <listitem>

     

       36
       36
       -
           <para>

     

       37
       37
       -
            The binfmt module is now easier to use. Additional systems can be added through <option>boot.binfmt.emulatedSystems</option>. For instance, <literal>boot.binfmt.emulatedSystems = [ "wasm32-wasi" "x86_64-windows" "aarch64-linux" ];</literal> will set up binfmt interpreters for each of those listed systems.

     

       38
       38
       -
           </para>

     

       37
       37
       +
            <para>

     

       38
       38
       +
              The binfmt module is now easier to use. Additional systems can

     

       39
       39
       +
              be added through <option>boot.binfmt.emulatedSystems</option>.

     

       40
       40
       +
              For instance, <literal>boot.binfmt.emulatedSystems = [

     

       41
       41
       +
              "wasm32-wasi" "x86_64-windows" "aarch64-linux" ];</literal> will

     

       42
       42
       +
              set up binfmt interpreters for each of those listed systems.

     

       43
       43
       +
            </para>

     

       39
       44
        
          </listitem>

     

       40
       45
        
          <listitem>

     

       41
       41
       -
           <para>

     

       42
       42
       -
            The installer now uses a less privileged <literal>nixos</literal> user whereas before we logged in as root. To gain root privileges use <literal>sudo -i</literal> without a password.

     

       46
       46
       +
            <para>

     

       47
       47
       +
            The installer now uses a less privileged <literal>nixos</literal> user whereas before we logged in as root.

     

       48
       48
       +
            To gain root privileges use <literal>sudo -i</literal> without a password.

     

       43
       49
        
           </para>

     

       44
       50
        
          </listitem>

     

       45
       51
        
          <listitem>

     

       46
       52
        
           <para>

     

       47
       47
       -
            We've updated to Xfce 4.14, which brings a new module <option>services.xserver.desktopManager.xfce4-14</option>. If you'd like to upgrade, please switch from the <option>services.xserver.desktopManager.xfce</option> module as it will be deprecated in a future release. They're incompatibilities with the current Xfce module; it doesn't support <option>thunarPlugins</option> and it isn't recommended to use <option>services.xserver.desktopManager.xfce</option> and <option>services.xserver.desktopManager.xfce4-14</option> simultaneously or to downgrade from Xfce 4.14 after upgrading.

     

       53
       53
       +
             We've updated to Xfce 4.14, which brings a new module <option>services.xserver.desktopManager.xfce4-14</option>.

     

       54
       54
       +
             If you'd like to upgrade, please switch from the <option>services.xserver.desktopManager.xfce</option> module as it

     

       55
       55
       +
             will be deprecated in a future release. They're incompatibilities with the current Xfce module; it doesn't support

     

       56
       56
       +
             <option>thunarPlugins</option> and it isn't recommended to use <option>services.xserver.desktopManager.xfce</option>

     

       57
       57
       +
             and <option>services.xserver.desktopManager.xfce4-14</option> simultaneously or to downgrade from Xfce 4.14 after upgrading.

     

       48
       58
        
           </para>

     

       49
       59
        
          </listitem>

     

       50
       60
        
          <listitem>

     

       51
       61
        
           <para>

     

       52
       52
       -
            The GNOME 3 desktop manager module sports an interface to enable/disable core services, applications, and optional GNOME packages like games.

     

       53
       53
       -
            <itemizedlist>

     

       54
       54
       -
             <para>

     

       55
       55
       -
              This can be achieved with the following options which the desktop manager default enables, excluding <literal>games</literal>.

     

       56
       56
       -
             </para>

     

       57
       57
       -
             <listitem>

     

       58
       58
       -
              <para>

     

       59
       59
       -
               <xref linkend="opt-services.gnome3.core-os-services.enable"/>

     

       60
       60
       -
              </para>

     

       61
       61
       -
             </listitem>

     

       62
       62
       -
             <listitem>

     

       63
       63
       -
              <para>

     

       64
       64
       -
               <xref linkend="opt-services.gnome3.core-shell.enable"/>

     

       65
       65
       -
              </para>

     

       66
       66
       -
             </listitem>

     

       67
       67
       -
             <listitem>

     

       68
       68
       -
              <para>

     

       69
       69
       -
               <xref linkend="opt-services.gnome3.core-utilities.enable"/>

     

       70
       70
       -
              </para>

     

       71
       71
       -
             </listitem>

     

       72
       72
       -
             <listitem>

     

       73
       73
       -
              <para>

     

       74
       74
       -
               <xref linkend="opt-services.gnome3.games.enable"/>

     

       75
       75
       -
              </para>

     

       76
       76
       -
             </listitem>

     

       77
       77
       -
            </itemizedlist>

     

       78
       78
       -
            With these options we hope to give users finer grained control over their systems. Prior to this change you'd either have to manually disable options or use <option>environment.gnome3.excludePackages</option> which only excluded the optional applications. <option>environment.gnome3.excludePackages</option> is now unguarded, it can exclude any package installed with <option>environment.systemPackages</option> in the GNOME 3 module.

     

       62
       62
       +
             The GNOME 3 desktop manager module sports an interface to enable/disable core services, applications, and optional GNOME packages

     

       63
       63
       +
             like games.

     

       64
       64
       +
             <itemizedlist>

     

       65
       65
       +
             <para>This can be achieved with the following options which the desktop manager default enables, excluding <literal>games</literal>.</para>

     

       66
       66
       +
             <listitem><para><xref linkend="opt-services.gnome3.core-os-services.enable"/></para></listitem>

     

       67
       67
       +
             <listitem><para><xref linkend="opt-services.gnome3.core-shell.enable"/></para></listitem>

     

       68
       68
       +
             <listitem><para><xref linkend="opt-services.gnome3.core-utilities.enable"/></para></listitem>

     

       69
       69
       +
             <listitem><para><xref linkend="opt-services.gnome3.games.enable"/></para></listitem>

     

       70
       70
       +
             </itemizedlist>

     

       71
       71
       +
             With these options we hope to give users finer grained control over their systems. Prior to this change you'd either have to manually

     

       72
       72
       +
             disable options or use <option>environment.gnome3.excludePackages</option> which only excluded the optional applications.

     

       73
       73
       +
             <option>environment.gnome3.excludePackages</option> is now unguarded, it can exclude any package installed with <option>environment.systemPackages</option>

     

       74
       74
       +
             in the GNOME 3 module.

     

       79
       75
        
           </para>

     

       80
       76
        
          </listitem>

     

       81
       77
        
          <listitem>

     

       82
       78
        
           <para>

     

       83
       83
       -
            Orthogonal to the previous changes to the GNOME 3 desktop manager module, we've updated all default services and applications to match as close as possible to a default reference GNOME 3 experience.

     

       79
       79
       +
            Orthogonal to the previous changes to the GNOME 3 desktop manager module, we've updated all default services and applications

     

       80
       80
       +
            to match as close as possible to a default reference GNOME 3 experience.

     

       84
       81
        
           </para>

     

       85
       85
       -
           <bridgehead>The following changes were enacted in <option>services.gnome3.core-utilities.enable</option>

     

       86
       86
       -
           </bridgehead>

     

       82
       82
       +
       

     

       83
       83
       +
           <bridgehead>The following changes were enacted in <option>services.gnome3.core-utilities.enable</option></bridgehead>

     

       84
       84
       +
       

     

       87
       85
        
           <itemizedlist>

     

       88
       86
        
            <title>Applications removed from defaults:</title>

     

       89
       89
       -
            <listitem>

     

       90
       90
       -
             <para>

     

       91
       91
       -
              <literal>accerciser</literal>

     

       92
       92
       -
             </para>

     

       93
       93
       -
            </listitem>

     

       94
       94
       -
            <listitem>

     

       95
       95
       -
             <para>

     

       96
       96
       -
              <literal>dconf-editor</literal>

     

       97
       97
       -
             </para>

     

       98
       98
       -
            </listitem>

     

       99
       99
       -
            <listitem>

     

       100
       100
       -
             <para>

     

       101
       101
       -
              <literal>evolution</literal>

     

       102
       102
       -
             </para>

     

       103
       103
       -
            </listitem>

     

       104
       104
       -
            <listitem>

     

       105
       105
       -
             <para>

     

       106
       106
       -
              <literal>gnome-documents</literal>

     

       107
       107
       -
             </para>

     

       108
       108
       -
            </listitem>

     

       109
       109
       -
            <listitem>

     

       110
       110
       -
             <para>

     

       111
       111
       -
              <literal>gnome-nettool</literal>

     

       112
       112
       -
             </para>

     

       113
       113
       -
            </listitem>

     

       114
       114
       -
            <listitem>

     

       115
       115
       -
             <para>

     

       116
       116
       -
              <literal>gnome-power-manager</literal>

     

       117
       117
       -
             </para>

     

       118
       118
       -
            </listitem>

     

       119
       119
       -
            <listitem>

     

       120
       120
       -
             <para>

     

       121
       121
       -
              <literal>gnome-todo</literal>

     

       122
       122
       -
             </para>

     

       123
       123
       -
            </listitem>

     

       124
       124
       -
            <listitem>

     

       125
       125
       -
             <para>

     

       126
       126
       -
              <literal>gnome-tweaks</literal>

     

       127
       127
       -
             </para>

     

       128
       128
       -
            </listitem>

     

       129
       129
       -
            <listitem>

     

       130
       130
       -
             <para>

     

       131
       131
       -
              <literal>gnome-usage</literal>

     

       132
       132
       -
             </para>

     

       133
       133
       -
            </listitem>

     

       134
       134
       -
            <listitem>

     

       135
       135
       -
             <para>

     

       136
       136
       -
              <literal>gucharmap</literal>

     

       137
       137
       -
             </para>

     

       138
       138
       -
            </listitem>

     

       139
       139
       -
            <listitem>

     

       140
       140
       -
             <para>

     

       141
       141
       -
              <literal>nautilus-sendto</literal>

     

       142
       142
       -
             </para>

     

       143
       143
       -
            </listitem>

     

       144
       144
       -
            <listitem>

     

       145
       145
       -
             <para>

     

       146
       146
       -
              <literal>vinagre</literal>

     

       147
       147
       -
             </para>

     

       148
       148
       -
            </listitem>

     

       87
       87
       +
            <listitem><para><literal>accerciser</literal></para></listitem>

     

       88
       88
       +
            <listitem><para><literal>dconf-editor</literal></para></listitem>

     

       89
       89
       +
            <listitem><para><literal>evolution</literal></para></listitem>

     

       90
       90
       +
            <listitem><para><literal>gnome-documents</literal></para></listitem>

     

       91
       91
       +
            <listitem><para><literal>gnome-nettool</literal></para></listitem>

     

       92
       92
       +
            <listitem><para><literal>gnome-power-manager</literal></para></listitem>

     

       93
       93
       +
            <listitem><para><literal>gnome-todo</literal></para></listitem>

     

       94
       94
       +
            <listitem><para><literal>gnome-tweaks</literal></para></listitem>

     

       95
       95
       +
            <listitem><para><literal>gnome-usage</literal></para></listitem>

     

       96
       96
       +
            <listitem><para><literal>gucharmap</literal></para></listitem>

     

       97
       97
       +
            <listitem><para><literal>nautilus-sendto</literal></para></listitem>

     

       98
       98
       +
            <listitem><para><literal>vinagre</literal></para></listitem>

     

       149
       99
        
           </itemizedlist>

     

       150
       100
        
           <itemizedlist>

     

       151
       101
        
            <title>Applications added to defaults:</title>

     

       152
       152
       -
            <listitem>

     

       153
       153
       -
             <para>

     

       154
       154
       -
              <literal>cheese</literal>

     

       155
       155
       -
             </para>

     

       156
       156
       -
            </listitem>

     

       157
       157
       -
            <listitem>

     

       158
       158
       -
             <para>

     

       159
       159
       -
              <literal>geary</literal>

     

       160
       160
       -
             </para>

     

       161
       161
       -
            </listitem>

     

       102
       102
       +
            <listitem><para><literal>cheese</literal></para></listitem>

     

       103
       103
       +
            <listitem><para><literal>geary</literal></para></listitem>

     

       162
       104
        
           </itemizedlist>

     

       163
       163
       -
           <bridgehead>The following changes were enacted in <option>services.gnome3.core-shell.enable</option>

     

       164
       164
       -
           </bridgehead>

     

       105
       105
       +
       

     

       106
       106
       +
           <bridgehead>The following changes were enacted in <option>services.gnome3.core-shell.enable</option></bridgehead>

     

       107
       107
       +
       

     

       165
       108
        
           <itemizedlist>

     

       166
       109
        
            <title>Applications added to defaults:</title>

     

       167
       167
       -
            <listitem>

     

       168
       168
       -
             <para>

     

       169
       169
       -
              <literal>gnome-color-manager</literal>

     

       170
       170
       -
             </para>

     

       171
       171
       -
            </listitem>

     

       172
       172
       -
            <listitem>

     

       173
       173
       -
             <para>

     

       174
       174
       -
              <literal>orca</literal>

     

       175
       175
       -
             </para>

     

       176
       176
       -
            </listitem>

     

       110
       110
       +
            <listitem><para><literal>gnome-color-manager</literal></para></listitem>

     

       111
       111
       +
            <listitem><para><literal>orca</literal></para></listitem>

     

       177
       112
        
           </itemizedlist>

     

       178
       113
        
           <itemizedlist>

     

       179
       114
        
            <title>Services enabled:</title>

     

       180
       180
       -
            <listitem>

     

       181
       181
       -
             <para>

     

       182
       182
       -
              <option>services.avahi.enable</option>

     

       183
       183
       -
             </para>

     

       184
       184
       -
            </listitem>

     

       115
       115
       +
            <listitem><para><option>services.avahi.enable</option></para></listitem>

     

       185
       116
        
           </itemizedlist>

     

       186
       117
        
          </listitem>

     

       187
       118
        
         </itemizedlist>

     
···

       206
       137
        
          </listitem>

     

       207
       138
        
          <listitem>

     

       208
       139
        
           <para>

     

       209
       209
       -
            The new <varname>hardware.printers</varname> module allows to declaratively configure CUPS printers via the <varname>ensurePrinters</varname> and <varname>ensureDefaultPrinter</varname> options. <varname>ensurePrinters</varname> will never delete existing printers, but will make sure that the given printers are configured as declared.

     

       140
       140
       +
            The new <varname>hardware.printers</varname> module allows to declaratively configure CUPS printers

     

       141
       141
       +
            via the <varname>ensurePrinters</varname> and

     

       142
       142
       +
            <varname>ensureDefaultPrinter</varname> options.

     

       143
       143
       +
            <varname>ensurePrinters</varname> will never delete existing printers,

     

       144
       144
       +
            but will make sure that the given printers are configured as declared.

     

       210
       145
        
           </para>

     

       211
       146
        
          </listitem>

     

       212
       147
        
          <listitem>

     

       213
       148
        
           <para>

     

       214
       214
       -
            There is a new <xref linkend="opt-services.system-config-printer.enable"/> and <xref linkend="opt-programs.system-config-printer.enable"/> module for the program of the same name. If you previously had <literal>system-config-printer</literal> enabled through some other means you should migrate to using one of these modules.

     

       149
       149
       +
            There is a new <xref linkend="opt-services.system-config-printer.enable"/> and <xref linkend="opt-programs.system-config-printer.enable"/> module

     

       150
       150
       +
            for the program of the same name. If you previously had <literal>system-config-printer</literal> enabled through some other

     

       151
       151
       +
            means you should migrate to using one of these modules.

     

       215
       152
        
           </para>

     

       216
       153
        
           <itemizedlist>

     

       217
       217
       -
            <para>

     

       218
       218
       -
             If you're a user of the following desktopManager modules no action is needed:

     

       219
       219
       -
            </para>

     

       154
       154
       +
            <para>If you're a user of the following desktopManager modules no action is needed:</para>

     

       220
       155
        
            <listitem>

     

       221
       221
       -
             <para>

     

       222
       222
       -
              <option>services.xserver.desktopManager.plasma5</option>

     

       223
       223
       -
             </para>

     

       156
       156
       +
             <para><option>services.xserver.desktopManager.plasma5</option></para>

     

       224
       157
        
            </listitem>

     

       225
       158
        
            <listitem>

     

       226
       226
       -
             <para>

     

       227
       227
       -
              <option>services.xserver.desktopManager.gnome3</option>

     

       228
       228
       -
             </para>

     

       159
       159
       +
             <para><option>services.xserver.desktopManager.gnome3</option></para>

     

       229
       160
        
            </listitem>

     

       230
       161
        
            <listitem>

     

       231
       231
       -
             <para>

     

       232
       232
       -
              <option>services.xserver.desktopManager.pantheon</option>

     

       233
       233
       -
             </para>

     

       162
       162
       +
             <para><option>services.xserver.desktopManager.pantheon</option></para>

     

       234
       163
        
            </listitem>

     

       235
       164
        
            <listitem>

     

       236
       236
       -
             <para>

     

       237
       237
       -
              <option>services.xserver.desktopManager.mate</option>

     

       238
       238
       -
             </para>

     

       165
       165
       +
             <para><option>services.xserver.desktopManager.mate</option></para>

     

       239
       166
        
             <para>

     

       240
       240
       -
              Note Mate uses <literal>programs.system-config-printer</literal> as it doesn't use it as a service, but its graphical interface directly.

     

       167
       167
       +
              Note Mate uses <literal>programs.system-config-printer</literal> as it doesn't

     

       168
       168
       +
              use it as a service, but its graphical interface directly.

     

       241
       169
        
             </para>

     

       242
       170
        
            </listitem>

     

       243
       171
        
           </itemizedlist>

     

       244
       172
        
          </listitem>

     

       245
       173
        
         </itemizedlist>

     

       174
       174
       +
       

     

       246
       175
        
        </section>

     

       247
       176
        
       

     

       248
       177
        
        <section xmlns="http://docbook.org/ns/docbook"

     
···

       253
       182
        
         <title>Backward Incompatibilities</title>

     

       254
       183
        
       

     

       255
       184
        
         <para>

     

       256
       256
       -
          When upgrading from a previous release, please be aware of the following incompatible changes:

     

       185
       185
       +
          When upgrading from a previous release, please be aware of the following

     

       186
       186
       +
          incompatible changes:

     

       257
       187
        
         </para>

     

       258
       188
        
       

     

       259
       189
        
         <itemizedlist>

     

       260
       190
        
          <listitem>

     

       261
       191
        
           <para>

     

       262
       262
       -
            Buildbot no longer supports Python 2, as support was dropped upstream in version 2.0.0. Configurations may need to be modified to make them compatible with Python 3.

     

       192
       192
       +
            Buildbot no longer supports Python 2, as support was dropped upstream in

     

       193
       193
       +
            version 2.0.0. Configurations may need to be modified to make them

     

       194
       194
       +
            compatible with Python 3.

     

       263
       195
        
           </para>

     

       264
       196
        
          </listitem>

     

       265
       197
        
          <listitem>

     

       266
       198
        
           <para>

     

       267
       267
       -
            PostgreSQL now uses <filename class="directory">/run/postgresql</filename> as its socket directory instead of <filename class="directory">/tmp</filename>. So if you run an application like eg. Nextcloud, where you need to use the Unix socket path as the database host name, you need to change it accordingly.

     

       199
       199
       +
            PostgreSQL now uses

     

       200
       200
       +
            <filename class="directory">/run/postgresql</filename> as its socket

     

       201
       201
       +
            directory instead of <filename class="directory">/tmp</filename>. So

     

       202
       202
       +
            if you run an application like eg. Nextcloud, where you need to use

     

       203
       203
       +
            the Unix socket path as the database host name, you need to change it

     

       204
       204
       +
            accordingly.

     

       268
       205
        
           </para>

     

       269
       206
        
          </listitem>

     

       270
       207
        
          <listitem>

     
···

       274
       211
        
          </listitem>

     

       275
       212
        
          <listitem>

     

       276
       213
        
           <para>

     

       277
       277
       -
            The options <option>services.prometheus.alertmanager.user</option> and <option>services.prometheus.alertmanager.group</option> have been removed because the alertmanager service is now using systemd's <link

     

       278
       278
       -
            xlink:href="http://0pointer.net/blog/dynamic-users-with-systemd.html"> DynamicUser mechanism</link> which obviates these options.

     

       214
       214
       +
            The options <option>services.prometheus.alertmanager.user</option> and

     

       215
       215
       +
            <option>services.prometheus.alertmanager.group</option> have been removed

     

       216
       216
       +
            because the alertmanager service is now using systemd's <link

     

       217
       217
       +
            xlink:href="http://0pointer.net/blog/dynamic-users-with-systemd.html">

     

       218
       218
       +
            DynamicUser mechanism</link> which obviates these options.

     

       279
       219
        
           </para>

     

       280
       220
        
          </listitem>

     

       281
       221
        
          <listitem>

     

       282
       222
        
           <para>

     

       283
       283
       -
            The NetworkManager systemd unit was renamed back from network-manager.service to NetworkManager.service for better compatibility with other applications expecting this name. The same applies to ModemManager where modem-manager.service is now called ModemManager.service again.

     

       223
       223
       +
            The NetworkManager systemd unit was renamed back from network-manager.service to

     

       224
       224
       +
            NetworkManager.service for better compatibility with other applications expecting this name.

     

       225
       225
       +
            The same applies to ModemManager where modem-manager.service is now called ModemManager.service again.

     

       284
       226
        
           </para>

     

       285
       227
        
          </listitem>

     

       286
       228
        
          <listitem>

     

       287
       229
        
           <para>

     

       288
       288
       -
            The <option>services.nzbget.configFile</option> and <option>services.nzbget.openFirewall</option> options were removed as they are managed internally by the nzbget. The <option>services.nzbget.dataDir</option> option hadn't actually been used by the module for some time and so was removed as cleanup.

     

       230
       230
       +
            The <option>services.nzbget.configFile</option> and <option>services.nzbget.openFirewall</option>

     

       231
       231
       +
            options were removed as they are managed internally by the nzbget. The

     

       232
       232
       +
            <option>services.nzbget.dataDir</option> option hadn't actually been used by

     

       233
       233
       +
            the module for some time and so was removed as cleanup.

     

       289
       234
        
           </para>

     

       290
       235
        
          </listitem>

     

       291
       236
        
          <listitem>

     

       292
       237
        
           <para>

     

       293
       293
       -
            The <option>services.mysql.pidDir</option> option was removed, as it was only used by the wordpress apache-httpd service to wait for mysql to have started up. This can be accomplished by either describing a dependency on mysql.service (preferred) or waiting for the (hardcoded) <filename>/run/mysqld/mysql.sock</filename> file to appear.

     

       238
       238
       +
            The <option>services.mysql.pidDir</option> option was removed, as it was only used by the wordpress

     

       239
       239
       +
            apache-httpd service to wait for mysql to have started up.

     

       240
       240
       +
            This can be accomplished by either describing a dependency on mysql.service (preferred)

     

       241
       241
       +
            or waiting for the (hardcoded) <filename>/run/mysqld/mysql.sock</filename> file to appear.

     

       294
       242
        
           </para>

     

       295
       243
        
          </listitem>

     

       296
       244
        
          <listitem>

     

       297
       245
        
           <para>

     

       298
       298
       -
            The <option>services.emby.enable</option> module has been removed, see <option>services.jellyfin.enable</option> instead for a free software fork of Emby. See the Jellyfin documentation: <link xlink:href="https://jellyfin.readthedocs.io/en/latest/administrator-docs/migrate-from-emby/"> Migrating from Emby to Jellyfin </link>

     

       246
       246
       +
            The <option>services.emby.enable</option> module has been removed, see

     

       247
       247
       +
            <option>services.jellyfin.enable</option> instead for a free software fork of Emby.

     

       248
       248
       +
       

     

       249
       249
       +
            See the Jellyfin documentation:

     

       250
       250
       +
            <link xlink:href="https://jellyfin.readthedocs.io/en/latest/administrator-docs/migrate-from-emby/">

     

       251
       251
       +
              Migrating from Emby to Jellyfin

     

       252
       252
       +
            </link>

     

       299
       253
        
           </para>

     

       300
       254
        
          </listitem>

     

       301
       255
        
          <listitem>

     

       302
       302
       -
           <para>

     

       303
       303
       -
            IPv6 Privacy Extensions are now enabled by default for undeclared interfaces. The previous behaviour was quite misleading — even though the default value for <option>networking.interfaces.*.preferTempAddress</option> was <literal>true</literal>, undeclared interfaces would not prefer temporary addresses. Now, interfaces not mentioned in the config will prefer temporary addresses. EUI64 addresses can still be set as preferred by explicitly setting the option to <literal>false</literal> for the interface in question.

     

       256
       256
       +
            <para>

     

       257
       257
       +
            IPv6 Privacy Extensions are now enabled by default for undeclared

     

       258
       258
       +
            interfaces. The previous behaviour was quite misleading — even though

     

       259
       259
       +
            the default value for

     

       260
       260
       +
            <option>networking.interfaces.*.preferTempAddress</option> was

     

       261
       261
       +
            <literal>true</literal>, undeclared interfaces would not prefer temporary

     

       262
       262
       +
            addresses. Now, interfaces not mentioned in the config will prefer

     

       263
       263
       +
            temporary addresses. EUI64 addresses can still be set as preferred by

     

       264
       264
       +
            explicitly setting the option to <literal>false</literal> for the

     

       265
       265
       +
            interface in question.

     

       304
       266
        
           </para>

     

       305
       267
        
          </listitem>

     

       306
       268
        
          <listitem>

     

       307
       269
        
           <para>

     

       308
       308
       -
            Since Bittorrent Sync was superseded by Resilio Sync in 2016, the <literal>bittorrentSync</literal>, <literal>bittorrentSync14</literal>, and <literal>bittorrentSync16</literal> packages have been removed in favor of <literal>resilio-sync</literal>.

     

       270
       270
       +
            Since Bittorrent Sync was superseded by Resilio Sync in 2016, the

     

       271
       271
       +
            <literal>bittorrentSync</literal>, <literal>bittorrentSync14</literal>,

     

       272
       272
       +
            and <literal>bittorrentSync16</literal> packages have been removed in

     

       273
       273
       +
            favor of <literal>resilio-sync</literal>.

     

       309
       274
        
           </para>

     

       310
       275
        
           <para>

     

       311
       311
       -
            The corresponding module, <option>services.btsync</option> has been replaced by the <option>services.resilio</option> module.

     

       276
       276
       +
            The corresponding module, <option>services.btsync</option> has been

     

       277
       277
       +
            replaced by the <option>services.resilio</option> module.

     

       312
       278
        
           </para>

     

       313
       279
        
          </listitem>

     

       314
       280
        
          <listitem>

     

       315
       281
        
           <para>

     

       316
       316
       -
            The httpd service no longer attempts to start the postgresql service. If you have come to depend on this behaviour then you can preserve the behavior with the following configuration: <literal>systemd.services.httpd.after = [ "postgresql.service" ];</literal>

     

       282
       282
       +
            The httpd service no longer attempts to start the postgresql service. If you have come to depend

     

       283
       283
       +
            on this behaviour then you can preserve the behavior with the following configuration:

     

       284
       284
       +
            <literal>systemd.services.httpd.after = [ "postgresql.service" ];</literal>

     

       317
       285
        
           </para>

     

       318
       286
        
           <para>

     

       319
       319
       -
            The option <option>services.httpd.extraSubservices</option> has been marked as deprecated. You may still use this feature, but it will be removed in a future release of NixOS. You are encouraged to convert any httpd subservices you may have written to a full NixOS module.

     

       287
       287
       +
            The option <option>services.httpd.extraSubservices</option> has been

     

       288
       288
       +
            marked as deprecated. You may still use this feature, but it will be

     

       289
       289
       +
            removed in a future release of NixOS. You are encouraged to convert any

     

       290
       290
       +
            httpd subservices you may have written to a full NixOS module.

     

       320
       291
        
           </para>

     

       321
       292
        
           <para>

     

       322
       322
       -
            Most of the httpd subservices packaged with NixOS have been replaced with full NixOS modules including LimeSurvey, WordPress, and Zabbix. These modules can be enabled using the <option>services.limesurvey.enable</option>, <option>services.mediawiki.enable</option>, <option>services.wordpress.enable</option>, and <option>services.zabbixWeb.enable</option> options.

     

       293
       293
       +
            Most of the httpd subservices packaged with NixOS have been replaced with

     

       294
       294
       +
            full NixOS modules including LimeSurvey, WordPress, and Zabbix. These

     

       295
       295
       +
            modules can be enabled using the <option>services.limesurvey.enable</option>,

     

       296
       296
       +
            <option>services.mediawiki.enable</option>, <option>services.wordpress.enable</option>,

     

       297
       297
       +
            and <option>services.zabbixWeb.enable</option> options.

     

       323
       298
        
           </para>

     

       324
       299
        
          </listitem>

     

       325
       300
        
          <listitem>

     

       326
       301
        
           <para>

     

       327
       327
       -
            The option <option>systemd.network.networks.&lt;name&gt;.routes.*.routeConfig.GatewayOnlink</option> was renamed to <option>systemd.network.networks.&lt;name&gt;.routes.*.routeConfig.GatewayOnLink</option> (capital <literal>L</literal>). This follows <link xlink:href="https://github.com/systemd/systemd/commit/9cb8c5593443d24c19e40bfd4fc06d672f8c554c"> upstreams renaming </link> of the setting.

     

       302
       302
       +
            The option <option>systemd.network.networks.&lt;name&gt;.routes.*.routeConfig.GatewayOnlink</option>

     

       303
       303
       +
            was renamed to <option>systemd.network.networks.&lt;name&gt;.routes.*.routeConfig.GatewayOnLink</option>

     

       304
       304
       +
            (capital <literal>L</literal>). This follows

     

       305
       305
       +
            <link xlink:href="https://github.com/systemd/systemd/commit/9cb8c5593443d24c19e40bfd4fc06d672f8c554c">

     

       306
       306
       +
             upstreams renaming

     

       307
       307
       +
            </link> of the setting.

     

       328
       308
        
           </para>

     

       329
       309
        
          </listitem>

     

       330
       310
        
          <listitem>

     

       331
       311
        
           <para>

     

       332
       332
       -
            As of this release the NixOps feature <literal>autoLuks</literal> is deprecated. It no longer works with our systemd version without manual intervention.

     

       312
       312
       +
            As of this release the NixOps feature <literal>autoLuks</literal> is deprecated. It no longer works

     

       313
       313
       +
            with our systemd version without manual intervention.

     

       333
       314
        
           </para>

     

       334
       315
        
           <para>

     

       335
       335
       -
            Whenever the usage of the module is detected the evaluation will fail with a message explaining why and how to deal with the situation.

     

       316
       316
       +
            Whenever the usage of the module is detected the evaluation will fail with a message

     

       317
       317
       +
            explaining why and how to deal with the situation.

     

       336
       318
        
           </para>

     

       337
       319
        
           <para>

     

       338
       338
       -
            A new knob named <literal>nixops.enableDeprecatedAutoLuks</literal> has been introduced to disable the eval failure and to acknowledge the notice was received and read. If you plan on using the feature please note that it might break with subsequent updates.

     

       320
       320
       +
            A new knob named <literal>nixops.enableDeprecatedAutoLuks</literal>

     

       321
       321
       +
            has been introduced to disable the eval failure and to acknowledge the notice was received and read.

     

       322
       322
       +
            If you plan on using the feature please note that it might break with subsequent updates.

     

       339
       323
        
           </para>

     

       340
       324
        
           <para>

     

       341
       341
       -
            Make sure you set the <literal>_netdev</literal> option for each of the file systems referring to block devices provided by the autoLuks module. Not doing this might render the system in a state where it doesn't boot anymore.

     

       325
       325
       +
            Make sure you set the <literal>_netdev</literal> option for each of the file systems referring to block

     

       326
       326
       +
            devices provided by the autoLuks module. Not doing this might render the system in a

     

       327
       327
       +
            state where it doesn't boot anymore.

     

       342
       328
        
           </para>

     

       343
       329
        
           <para>

     

       344
       344
       -
            If you are actively using the <literal>autoLuks</literal> module please let us know in <link xlink:href="https://github.com/NixOS/nixpkgs/issues/62211">issue #62211</link>.

     

       330
       330
       +
            If you are actively using the <literal>autoLuks</literal> module please let us know in

     

       331
       331
       +
            <link xlink:href="https://github.com/NixOS/nixpkgs/issues/62211">issue #62211</link>.

     

       345
       332
        
           </para>

     

       346
       333
        
          </listitem>

     

       347
       334
        
          <listitem>

     

       348
       335
        
           <para>

     

       349
       349
       -
            The setopt declarations will be evaluated at the end of <literal>/etc/zshrc</literal>, so any code in <xref linkend="opt-programs.zsh.interactiveShellInit" />, <xref linkend="opt-programs.zsh.loginShellInit" /> and <xref linkend="opt-programs.zsh.promptInit" /> may break if it relies on those options being set.

     

       336
       336
       +
            The setopt declarations will be evaluated at the end of <literal>/etc/zshrc</literal>, so any code in <xref linkend="opt-programs.zsh.interactiveShellInit" />,

     

       337
       337
       +
            <xref linkend="opt-programs.zsh.loginShellInit" /> and <xref linkend="opt-programs.zsh.promptInit" /> may break if it relies on those options being set.

     

       350
       338
        
           </para>

     

       351
       339
        
          </listitem>

     

       352
       340
        
          <listitem>

     

       353
       341
        
           <para>

     

       354
       354
       -
            The <literal>prometheus-nginx-exporter</literal> package now uses the offical exporter provided by NGINX Inc. Its metrics are differently structured and are incompatible to the old ones. For information about the metrics, have a look at the <link xlink:href="https://github.com/nginxinc/nginx-prometheus-exporter">official repo</link>.

     

       342
       342
       +
             The <literal>prometheus-nginx-exporter</literal> package now uses the offical exporter provided by NGINX Inc.

     

       343
       343
       +
             Its metrics are differently structured and are incompatible to the old ones. For information about the metrics,

     

       344
       344
       +
             have a look at the <link xlink:href="https://github.com/nginxinc/nginx-prometheus-exporter">official repo</link>.

     

       355
       345
        
           </para>

     

       356
       346
        
          </listitem>

     

       357
       347
        
          <listitem>

     

       358
       348
        
           <para>

     

       359
       359
       -
            The <literal>shibboleth-sp</literal> package has been updated to version 3. It is largely backward compatible, for further information refer to the <link xlink:href="https://wiki.shibboleth.net/confluence/display/SP3/ReleaseNotes">release notes</link> and <link xlink:href="https://wiki.shibboleth.net/confluence/display/SP3/UpgradingFromV2">upgrade guide</link>.

     

       360
       360
       -
           </para>

     

       361
       361
       -
           <para>

     

       362
       362
       -
            Nodejs 8 is scheduled EOL under the lifetime of 19.09 and has been dropped.

     

       349
       349
       +
            The <literal>shibboleth-sp</literal> package has been updated to version 3.

     

       350
       350
       +
            It is largely backward compatible, for further information refer to the

     

       351
       351
       +
            <link xlink:href="https://wiki.shibboleth.net/confluence/display/SP3/ReleaseNotes">release notes</link>

     

       352
       352
       +
            and <link xlink:href="https://wiki.shibboleth.net/confluence/display/SP3/UpgradingFromV2">upgrade guide</link>.

     

       363
       353
        
           </para>

     

       354
       354
       +
            <para>

     

       355
       355
       +
              Nodejs 8 is scheduled EOL under the lifetime of 19.09 and has been dropped.

     

       356
       356
       +
            </para>

     

       364
       357
        
          </listitem>

     

       365
       358
        
          <listitem>

     

       366
       366
       -
           <para>

     

       367
       367
       -
            By default, prometheus exporters are now run with <literal>DynamicUser</literal> enabled. Exporters that need a real user, now run under a seperate user and group which follow the pattern <literal>&lt;exporter-name&gt;-exporter</literal>, instead of the previous default <literal>nobody</literal> and <literal>nogroup</literal>. Only some exporters are affected by the latter, namely the exporters <literal>dovecot</literal>, <literal>node</literal>, <literal>postfix</literal> and <literal>varnish</literal>.

     

       368
       368
       -
           </para>

     

       359
       359
       +
            <para>

     

       360
       360
       +
              By default, prometheus exporters are now run with <literal>DynamicUser</literal> enabled.

     

       361
       361
       +
              Exporters that need a real user, now run under a seperate user and group which follow the pattern <literal>&lt;exporter-name&gt;-exporter</literal>, instead of the previous default <literal>nobody</literal> and <literal>nogroup</literal>.

     

       362
       362
       +
              Only some exporters are affected by the latter, namely the exporters <literal>dovecot</literal>, <literal>node</literal>, <literal>postfix</literal> and <literal>varnish</literal>.

     

       363
       363
       +
            </para>

     

       369
       364
        
          </listitem>

     

       370
       365
        
          <listitem>

     

       371
       371
       -
           <para>

     

       372
       372
       -
            The <literal>ibus-qt</literal> package is not installed by default anymore when <xref linkend="opt-i18n.inputMethod.enabled" /> is set to <literal>ibus</literal>. If IBus support in Qt 4.x applications is required, add the <literal>ibus-qt</literal> package to your <xref linkend="opt-environment.systemPackages" /> manually.

     

       373
       373
       -
           </para>

     

       366
       366
       +
            <para>

     

       367
       367
       +
              The <literal>ibus-qt</literal> package is not installed by default anymore when <xref linkend="opt-i18n.inputMethod.enabled" /> is set to <literal>ibus</literal>.

     

       368
       368
       +
              If IBus support in Qt 4.x applications is required, add the <literal>ibus-qt</literal> package to your <xref linkend="opt-environment.systemPackages" /> manually.

     

       369
       369
       +
            </para>

     

       374
       370
        
          </listitem>

     

       375
       371
        
          <listitem>

     

       376
       376
       -
           <para>

     

       377
       377
       -
            The CUPS Printing service now uses socket-based activation by default, only starting when needed. The previous behavior can be restored by setting <option>services.cups.startWhenNeeded</option> to <literal>false</literal>.

     

       378
       378
       -
           </para>

     

       372
       372
       +
            <para>

     

       373
       373
       +
              The CUPS Printing service now uses socket-based activation by

     

       374
       374
       +
              default, only starting when needed. The previous behavior can

     

       375
       375
       +
              be restored by setting

     

       376
       376
       +
              <option>services.cups.startWhenNeeded</option> to

     

       377
       377
       +
              <literal>false</literal>.

     

       378
       378
       +
            </para>

     

       379
       379
        
          </listitem>

     

       380
       380
        
          <listitem>

     

       381
       381
       -
           <para>

     

       382
       382
       -
            The <option>services.systemhealth</option> module has been removed from nixpkgs due to lack of maintainer.

     

       383
       383
       -
           </para>

     

       381
       381
       +
            <para>

     

       382
       382
       +
              The <option>services.systemhealth</option> module has been removed from nixpkgs due to lack of maintainer.

     

       383
       383
       +
            </para>

     

       384
       384
        
          </listitem>

     

       385
       385
        
          <listitem>

     

       386
       386
       -
           <para>

     

       387
       387
       -
            The <option>services.mantisbt</option> module has been removed from nixpkgs due to lack of maintainer.

     

       388
       388
       -
           </para>

     

       386
       386
       +
            <para>

     

       387
       387
       +
              The <option>services.mantisbt</option> module has been removed from nixpkgs due to lack of maintainer.

     

       388
       388
       +
            </para>

     

       389
       389
        
          </listitem>

     

       390
       390
        
          <listitem>

     

       391
       391
       -
           <para>

     

       392
       392
       -
            Squid 3 has been removed and the <option>squid</option> derivation now refers to Squid 4.

     

       393
       393
       -
           </para>

     

       391
       391
       +
            <para>

     

       392
       392
       +
              Squid 3 has been removed and the <option>squid</option> derivation now refers to Squid 4.

     

       393
       393
       +
            </para>

     

       394
       394
        
          </listitem>

     

       395
       395
        
          <listitem>

     

       396
       396
       -
           <para>

     

       397
       397
       -
            The <option>services.pdns-recursor.extraConfig</option> option has been replaced by <option>services.pdns-recursor.settings</option>. The new option allows setting extra configuration while being better type-checked and mergeable.

     

       398
       398
       -
           </para>

     

       396
       396
       +
            <para>

     

       397
       397
       +
              The <option>services.pdns-recursor.extraConfig</option> option has been replaced by

     

       398
       398
       +
              <option>services.pdns-recursor.settings</option>. The new option allows setting extra

     

       399
       399
       +
              configuration while being better type-checked and mergeable.

     

       400
       400
       +
            </para>

     

       399
       401
        
          </listitem>

     

       400
       402
        
          <listitem>

     

       401
       403
        
           <para>

     

       402
       402
       -
            No service depends on <literal>keys.target</literal> anymore which is a systemd target that indicates if all <link xlink:href="https://nixos.org/nixops/manual/#idm140737322342384">NixOps keys</link> were successfully uploaded. Instead, <literal>&lt;key-name&gt;-key.service</literal> should be used to define a dependency of a key in a service. The full issue behind the <literal>keys.target</literal> dependency is described at <link xlink:href="https://github.com/NixOS/nixpkgs/issues/67265">NixOS/nixpkgs#67265</link>.

     

       404
       404
       +
            No service depends on <literal>keys.target</literal> anymore which is a systemd

     

       405
       405
       +
            target that indicates if all <link xlink:href="https://nixos.org/nixops/manual/#idm140737322342384">NixOps keys</link> were successfully uploaded.

     

       406
       406
       +
            Instead, <literal>&lt;key-name&gt;-key.service</literal> should be used to define

     

       407
       407
       +
            a dependency of a key in a service. The full issue behind the <literal>keys.target</literal>

     

       408
       408
       +
            dependency is described at <link xlink:href="https://github.com/NixOS/nixpkgs/issues/67265">NixOS/nixpkgs#67265</link>.

     

       403
       409
        
           </para>

     

       404
       410
        
           <para>

     

       405
       411
        
            The following services are affected by this:

     

       406
       412
        
            <itemizedlist>

     

       407
       407
       -
             <listitem>

     

       408
       408
       -
              <para>

     

       409
       409
       -
               <link linkend="opt-services.dovecot2.enable"><literal>services.dovecot2</literal></link>

     

       410
       410
       -
              </para>

     

       411
       411
       -
             </listitem>

     

       412
       412
       -
             <listitem>

     

       413
       413
       -
              <para>

     

       414
       414
       -
               <link linkend="opt-services.nsd.enable"><literal>services.nsd</literal></link>

     

       415
       415
       -
              </para>

     

       416
       416
       -
             </listitem>

     

       417
       417
       -
             <listitem>

     

       418
       418
       -
              <para>

     

       419
       419
       -
               <link linkend="opt-services.softether.enable"><literal>services.softether</literal></link>

     

       420
       420
       -
              </para>

     

       421
       421
       -
             </listitem>

     

       422
       422
       -
             <listitem>

     

       423
       423
       -
              <para>

     

       424
       424
       -
               <link linkend="opt-services.strongswan.enable"><literal>services.strongswan</literal></link>

     

       425
       425
       -
              </para>

     

       426
       426
       -
             </listitem>

     

       427
       427
       -
             <listitem>

     

       428
       428
       -
              <para>

     

       429
       429
       -
               <link linkend="opt-services.strongswan-swanctl.enable"><literal>services.strongswan-swanctl</literal></link>

     

       430
       430
       -
              </para>

     

       431
       431
       -
             </listitem>

     

       432
       432
       -
             <listitem>

     

       433
       433
       -
              <para>

     

       434
       434
       -
               <link linkend="opt-services.httpd.enable"><literal>services.httpd</literal></link>

     

       435
       435
       -
              </para>

     

       436
       436
       -
             </listitem>

     

       413
       413
       +
             <listitem><para><link linkend="opt-services.dovecot2.enable"><literal>services.dovecot2</literal></link></para></listitem>

     

       414
       414
       +
             <listitem><para><link linkend="opt-services.nsd.enable"><literal>services.nsd</literal></link></para></listitem>

     

       415
       415
       +
             <listitem><para><link linkend="opt-services.softether.enable"><literal>services.softether</literal></link></para></listitem>

     

       416
       416
       +
             <listitem><para><link linkend="opt-services.strongswan.enable"><literal>services.strongswan</literal></link></para></listitem>

     

       417
       417
       +
             <listitem><para><link linkend="opt-services.strongswan-swanctl.enable"><literal>services.strongswan-swanctl</literal></link></para></listitem>

     

       418
       418
       +
             <listitem><para><link linkend="opt-services.httpd.enable"><literal>services.httpd</literal></link></para></listitem>

     

       437
       419
        
            </itemizedlist>

     

       438
       420
        
           </para>

     

       439
       421
        
          </listitem>

     

       440
       422
        
          <listitem>

     

       441
       441
       -
           <para>

     

       442
       442
       -
            The <option>security.acme.directory</option> option has been replaced by a read-only <option>security.acme.certs.&lt;cert&gt;.directory</option> option for each certificate you define. This will be a subdirectory of <literal>/var/lib/acme</literal>. You can use this read-only option to figure out where the certificates are stored for a specific certificate. For example, the <option>services.nginx.virtualhosts.&lt;name&gt;.enableACME</option> option will use this directory option to find the certs for the virtual host.

     

       443
       443
       -
           </para>

     

       444
       444
       -
           <para>

     

       445
       445
       -
            <option>security.acme.preDelay</option> and <option>security.acme.activationDelay</option> options have been removed. To execute a service before certificates are provisioned or renewed add a <literal>RequiredBy=acme-${cert}.service</literal> to any service.

     

       446
       446
       -
           </para>

     

       447
       447
       -
           <para>

     

       448
       448
       -
            Furthermore, the acme module will not automatically add a dependency on <literal>lighttpd.service</literal> anymore. If you are using certficates provided by letsencrypt for lighttpd, then you should depend on the certificate service <literal>acme-${cert}.service></literal> manually.

     

       449
       449
       -
           </para>

     

       450
       450
       -
           <para>

     

       451
       451
       -
            For nginx, the dependencies are still automatically managed when <option>services.nginx.virtualhosts.&lt;name&gt;.enableACME</option> is enabled just like before. What changed is that nginx now directly depends on the specific certificates that it needs, instead of depending on the catch-all <literal>acme-certificates.target</literal>. This target unit was also removed from the codebase. This will mean nginx will no longer depend on certificates it isn't explicitly managing and fixes a bug with certificate renewal ordering racing with nginx restarting which could lead to nginx getting in a broken state as described at <link xlink:href="https://github.com/NixOS/nixpkgs/issues/60180">NixOS/nixpkgs#60180</link>.

     

       452
       452
       -
           </para>

     

       423
       423
       +
            <para>

     

       424
       424
       +
              The <option>security.acme.directory</option> option has been replaced by a read-only <option>security.acme.certs.&lt;cert&gt;.directory</option> option for each certificate you define. This will be

     

       425
       425
       +
              a subdirectory of <literal>/var/lib/acme</literal>. You can use this read-only option to figure out where the certificates are stored for a specific certificate. For example,

     

       426
       426
       +
              the <option>services.nginx.virtualhosts.&lt;name&gt;.enableACME</option>  option will use this directory option to find the certs for the virtual host.

     

       427
       427
       +
            </para>

     

       428
       428
       +
            <para>

     

       429
       429
       +
              <option>security.acme.preDelay</option> and <option>security.acme.activationDelay</option> options have been removed. To execute a service before certificates

     

       430
       430
       +
              are provisioned or renewed add a <literal>RequiredBy=acme-${cert}.service</literal> to any service.

     

       431
       431
       +
            </para>

     

       432
       432
       +
            <para>

     

       433
       433
       +
              Furthermore, the acme module will not automatically add a dependency on <literal>lighttpd.service</literal> anymore. If you are using certficates provided by letsencrypt

     

       434
       434
       +
              for lighttpd, then you should depend on the certificate service <literal>acme-${cert}.service></literal> manually.

     

       435
       435
       +
            </para>

     

       436
       436
       +
            <para>

     

       437
       437
       +
              For nginx, the dependencies are still automatically managed when <option>services.nginx.virtualhosts.&lt;name&gt;.enableACME</option> is enabled just like before. What changed is that nginx now directly depends on the specific certificates that it needs,

     

       438
       438
       +
              instead of depending on the catch-all <literal>acme-certificates.target</literal>. This target unit was also removed from the codebase.

     

       439
       439
       +
              This will mean nginx will no longer depend on certificates it isn't explicitly managing and fixes a bug with certificate renewal

     

       440
       440
       +
              ordering racing with nginx restarting which could lead to nginx getting in a broken state as described at

     

       441
       441
       +
               <link xlink:href="https://github.com/NixOS/nixpkgs/issues/60180">NixOS/nixpkgs#60180</link>.

     

       442
       442
       +
            </para>

     

       453
       443
        
          </listitem>

     

       454
       444
        
          <listitem>

     

       455
       455
       -
           <para>

     

       456
       456
       -
            The old deprecated <literal>emacs</literal> package sets have been dropped. What used to be called <literal>emacsPackagesNg</literal> is now simply called <literal>emacsPackages</literal>.

     

       457
       457
       -
           </para>

     

       445
       445
       +
            <para>

     

       446
       446
       +
              The old deprecated <literal>emacs</literal> package sets have been dropped.

     

       447
       447
       +
              What used to be called <literal>emacsPackagesNg</literal> is now simply called <literal>emacsPackages</literal>.

     

       448
       448
       +
            </para>

     

       458
       449
        
          </listitem>

     

       459
       450
        
          <listitem>

     

       460
       460
       -
           <para>

     

       461
       461
       -
            <option>services.xserver.desktopManager.xterm</option> is now disabled by default if <literal>stateVersion</literal> is 19.09 or higher. Previously the xterm desktopManager was enabled when xserver was enabled, but it isn't useful for all people so it didn't make sense to have any desktopManager enabled default.

     

       462
       462
       -
           </para>

     

       451
       451
       +
            <para>

     

       452
       452
       +
              <option>services.xserver.desktopManager.xterm</option> is now disabled by default if <literal>stateVersion</literal> is 19.09 or higher.

     

       453
       453
       +
              Previously the xterm desktopManager was enabled when xserver was enabled, but it isn't useful for all people so it didn't make sense to

     

       454
       454
       +
              have any desktopManager enabled default.

     

       455
       455
       +
            </para>

     

       463
       456
        
          </listitem>

     

       464
       457
        
          <listitem>

     

       465
       458
        
           <para>

     

       466
       466
       -
            The WeeChat plugin <literal>pkgs.weechatScripts.weechat-xmpp</literal> has been removed as it doesn't receive any updates from upstream and depends on outdated Python2-based modules.

     

       459
       459
       +
            The WeeChat plugin <literal>pkgs.weechatScripts.weechat-xmpp</literal> has been removed as it doesn't receive

     

       460
       460
       +
            any updates from upstream and depends on outdated Python2-based modules.

     

       467
       461
        
           </para>

     

       468
       462
        
          </listitem>

     

       469
       463
        
          <listitem>

     

       470
       464
        
           <para>

     

       471
       471
       -
            Old unsupported versions (<literal>logstash5</literal>, <literal>kibana5</literal>, <literal>filebeat5</literal>, <literal>heartbeat5</literal>, <literal>metricbeat5</literal>, <literal>packetbeat5</literal>) of the ELK-stack and Elastic beats have been removed.

     

       465
       465
       +
            Old unsupported versions (<literal>logstash5</literal>,

     

       466
       466
       +
            <literal>kibana5</literal>,

     

       467
       467
       +
            <literal>filebeat5</literal>,

     

       468
       468
       +
            <literal>heartbeat5</literal>,

     

       469
       469
       +
            <literal>metricbeat5</literal>,

     

       470
       470
       +
            <literal>packetbeat5</literal>) of the ELK-stack and Elastic beats have been removed.

     

       472
       471
        
           </para>

     

       473
       472
        
          </listitem>

     

       474
       473
        
          <listitem>

     

       475
       474
        
           <para>

     

       476
       476
       -
            For NixOS 19.03, both Prometheus 1 and 2 were available to allow for a seamless transition from version 1 to 2 with existing setups. Because Prometheus 1 is no longer developed, it was removed. Prometheus 2 is now configured with <literal>services.prometheus</literal>.

     

       475
       475
       +
            For NixOS 19.03, both Prometheus 1 and 2 were available to allow for

     

       476
       476
       +
            a seamless transition from version 1 to 2 with existing setups.

     

       477
       477
       +
            Because Prometheus 1 is no longer developed, it was removed.

     

       478
       478
       +
            Prometheus 2 is now configured with <literal>services.prometheus</literal>.

     

       477
       479
        
           </para>

     

       478
       480
        
          </listitem>

     

       479
       481
        
          <listitem>

     

       480
       480
       -
           <para>

     

       481
       481
       -
            Citrix Receiver (<literal>citrix_receiver</literal>) has been dropped in favor of Citrix Workspace (<literal>citrix_workspace</literal>).

     

       482
       482
       -
           </para>

     

       482
       482
       +
            <para>

     

       483
       483
       +
              Citrix Receiver (<literal>citrix_receiver</literal>) has been dropped in favor of Citrix Workspace

     

       484
       484
       +
              (<literal>citrix_workspace</literal>).

     

       485
       485
       +
            </para>

     

       483
       486
        
          </listitem>

     

       484
       487
        
         </itemizedlist>

     

       485
       488
        
        </section>

     
···

       494
       497
        
         <itemizedlist>

     

       495
       498
        
          <listitem>

     

       496
       499
        
           <para>

     

       497
       497
       -
            The <option>documentation</option> module gained an option named <option>documentation.nixos.includeAllModules</option> which makes the generated <citerefentry>

     

       500
       500
       +
            The <option>documentation</option> module gained an option named

     

       501
       501
       +
            <option>documentation.nixos.includeAllModules</option> which makes the

     

       502
       502
       +
            generated <citerefentry>

     

       498
       503
        
            <refentrytitle>configuration.nix</refentrytitle>

     

       499
       499
       -
            <manvolnum>5</manvolnum></citerefentry> manual page include all options from all NixOS modules included in a given <literal>configuration.nix</literal> configuration file. Currently, it is set to <literal>false</literal> by default as enabling it frequently prevents evaluation. But the plan is to eventually have it set to <literal>true</literal> by default. Please set it to <literal>true</literal> now in your <literal>configuration.nix</literal> and fix all the bugs it uncovers.

     

       504
       504
       +
            <manvolnum>5</manvolnum></citerefentry> manual page include all options

     

       505
       505
       +
            from all NixOS modules included in a given

     

       506
       506
       +
            <literal>configuration.nix</literal> configuration file. Currently, it is

     

       507
       507
       +
            set to <literal>false</literal> by default as enabling it frequently

     

       508
       508
       +
            prevents evaluation. But the plan is to eventually have it set to

     

       509
       509
       +
            <literal>true</literal> by default. Please set it to

     

       510
       510
       +
            <literal>true</literal> now in your <literal>configuration.nix</literal>

     

       511
       511
       +
            and fix all the bugs it uncovers.

     

       500
       512
        
           </para>

     

       501
       513
        
          </listitem>

     

       502
       514
        
          <listitem>

     

       503
       515
        
           <para>

     

       504
       504
       -
            The <literal>vlc</literal> package gained support for Chromecast streaming, enabled by default. TCP port 8010 must be open for it to work, so something like <literal>networking.firewall.allowedTCPPorts = [ 8010 ];</literal> may be required in your configuration. Also consider enabling <link xlink:href="https://nixos.wiki/wiki/Accelerated_Video_Playback"> Accelerated Video Playback</link> for better transcoding performance.

     

       516
       516
       +
            The <literal>vlc</literal> package gained support for Chromecast

     

       517
       517
       +
            streaming, enabled by default. TCP port 8010 must be open for it to work,

     

       518
       518
       +
            so something like <literal>networking.firewall.allowedTCPPorts = [ 8010

     

       519
       519
       +
            ];</literal> may be required in your configuration. Also consider enabling

     

       520
       520
       +
            <link xlink:href="https://nixos.wiki/wiki/Accelerated_Video_Playback">

     

       521
       521
       +
            Accelerated Video Playback</link> for better transcoding performance.

     

       505
       522
        
           </para>

     

       506
       523
        
          </listitem>

     

       507
       524
        
          <listitem>

     

       508
       525
        
           <para>

     

       509
       509
       -
            The following changes apply if the <literal>stateVersion</literal> is changed to 19.09 or higher. For <literal>stateVersion = "19.03"</literal> or lower the old behavior is preserved.

     

       526
       526
       +
            The following changes apply if the <literal>stateVersion</literal> is

     

       527
       527
       +
            changed to 19.09 or higher. For <literal>stateVersion = "19.03"</literal>

     

       528
       528
       +
            or lower the old behavior is preserved.

     

       510
       529
        
           </para>

     

       511
       530
        
           <itemizedlist>

     

       512
       531
        
            <listitem>

     

       513
       532
        
             <para>

     

       514
       514
       -
              <literal>solr.package</literal> defaults to <literal>pkgs.solr_8</literal>.

     

       533
       533
       +
              <literal>solr.package</literal> defaults to

     

       534
       534
       +
              <literal>pkgs.solr_8</literal>.

     

       515
       535
        
             </para>

     

       516
       536
        
            </listitem>

     

       517
       537
        
           </itemizedlist>

     

       518
       538
        
          </listitem>

     

       519
       539
        
          <listitem>

     

       520
       540
        
           <para>

     

       521
       521
       -
            The <literal>hunspellDicts.fr-any</literal> dictionary now ships with <literal>fr_FR.{aff,dic}</literal> which is linked to <literal>fr-toutesvariantes.{aff,dic}</literal>.

     

       541
       541
       +
            The <literal>hunspellDicts.fr-any</literal> dictionary now ships with <literal>fr_FR.{aff,dic}</literal>

     

       542
       542
       +
            which is linked to <literal>fr-toutesvariantes.{aff,dic}</literal>.

     

       522
       543
        
           </para>

     

       523
       544
        
          </listitem>

     

       524
       545
        
          <listitem>

     

       525
       546
        
           <para>

     

       526
       526
       -
            The <literal>mysql</literal> service now runs as <literal>mysql</literal> user. Previously, systemd did execute it as root, and mysql dropped privileges itself. This includes <literal>ExecStartPre=</literal> and <literal>ExecStartPost=</literal> phases. To accomplish that, runtime and data directory setup was delegated to RuntimeDirectory and tmpfiles.

     

       547
       547
       +
            The <literal>mysql</literal> service now runs as <literal>mysql</literal>

     

       548
       548
       +
            user. Previously, systemd did execute it as root, and mysql dropped privileges

     

       549
       549
       +
            itself.

     

       550
       550
       +
            This includes <literal>ExecStartPre=</literal> and

     

       551
       551
       +
            <literal>ExecStartPost=</literal> phases.

     

       552
       552
       +
            To accomplish that, runtime and data directory setup was delegated to

     

       553
       553
       +
            RuntimeDirectory and tmpfiles.

     

       527
       554
        
           </para>

     

       528
       555
        
          </listitem>

     

       529
       556
        
          <listitem>

     

       530
       557
        
           <para>

     

       531
       531
       -
            With the upgrade to systemd version 242 the <literal>systemd-timesyncd</literal> service is no longer using <literal>DynamicUser=yes</literal>. In order for the upgrade to work we rely on an activation script to move the state from the old to the new directory. The older directory (prior <literal>19.09</literal>) was <literal>/var/lib/private/systemd/timesync</literal>.

     

       558
       558
       +
            With the upgrade to systemd version 242 the <literal>systemd-timesyncd</literal>

     

       559
       559
       +
            service is no longer using <literal>DynamicUser=yes</literal>. In order for the

     

       560
       560
       +
            upgrade to work we rely on an activation script to move the state from the old

     

       561
       561
       +
            to the new directory. The older directory (prior <literal>19.09</literal>) was

     

       562
       562
       +
            <literal>/var/lib/private/systemd/timesync</literal>.

     

       532
       563
        
           </para>

     

       533
       564
        
           <para>

     

       534
       534
       -
            As long as the <literal>system.config.stateVersion</literal> is below <literal>19.09</literal> the state folder will migrated to its proper location (<literal>/var/lib/systemd/timesync</literal>), if required.

     

       565
       565
       +
            As long as the <literal>system.config.stateVersion</literal> is below

     

       566
       566
       +
            <literal>19.09</literal> the state folder will migrated to its proper location

     

       567
       567
       +
            (<literal>/var/lib/systemd/timesync</literal>), if required.

     

       535
       568
        
           </para>

     

       536
       569
        
          </listitem>

     

       537
       570
        
          <listitem>

     

       538
       571
        
           <para>

     

       539
       539
       -
            The package <literal>avahi</literal> is now built to look up service definitions from <literal>/etc/avahi/services</literal> instead of its output directory in the nix store. Accordingly the module <option>avahi</option> now supports custom service definitions via <option>services.avahi.extraServiceFiles</option>, which are then placed in the aforementioned directory. See <citerefentry>

     

       540
       540
       -
            <refentrytitle>avahi.service</refentrytitle>

     

       541
       541
       -
            <manvolnum>5</manvolnum> </citerefentry> for more information on custom service definitions.

     

       572
       572
       +
            The package <literal>avahi</literal> is now built to look up service

     

       573
       573
       +
            definitions from <literal>/etc/avahi/services</literal> instead of its

     

       574
       574
       +
            output directory in the nix store. Accordingly the module

     

       575
       575
       +
            <option>avahi</option> now supports custom service definitions via

     

       576
       576
       +
            <option>services.avahi.extraServiceFiles</option>, which are then placed

     

       577
       577
       +
            in the aforementioned directory. See <citerefentry>

     

       578
       578
       +
            <refentrytitle>avahi.service</refentrytitle><manvolnum>5</manvolnum>

     

       579
       579
       +
            </citerefentry> for more information on custom service definitions.

     

       542
       580
        
           </para>

     

       543
       581
        
          </listitem>

     

       544
       582
        
          <listitem>

     

       545
       583
        
           <para>

     

       546
       546
       -
            Since version 0.1.19, <literal>cargo-vendor</literal> honors package includes that are specified in the <filename>Cargo.toml</filename> file of Rust crates. <literal>rustPlatform.buildRustPackage</literal> uses <literal>cargo-vendor</literal> to collect and build dependent crates. Since this change in <literal>cargo-vendor</literal> changes the set of vendored files for most Rust packages, the hash that use used to verify the dependencies, <literal>cargoSha256</literal>, also changes.

     

       584
       584
       +
            Since version 0.1.19, <literal>cargo-vendor</literal> honors package

     

       585
       585
       +
            includes that are specified in the <filename>Cargo.toml</filename>

     

       586
       586
       +
            file of Rust crates. <literal>rustPlatform.buildRustPackage</literal> uses

     

       587
       587
       +
            <literal>cargo-vendor</literal> to collect and build dependent crates.

     

       588
       588
       +
            Since this change in <literal>cargo-vendor</literal> changes the set of

     

       589
       589
       +
            vendored files for most Rust packages, the hash that use used to verify

     

       590
       590
       +
            the dependencies, <literal>cargoSha256</literal>, also changes.

     

       547
       591
        
           </para>

     

       548
       592
        
           <para>

     

       549
       549
       -
            The <literal>cargoSha256</literal> hashes of all in-tree derivations that use <literal>buildRustPackage</literal> have been updated to reflect this change. However, third-party derivations that use <literal>buildRustPackage</literal> may have to be updated as well.

     

       593
       593
       +
            The <literal>cargoSha256</literal> hashes of all in-tree derivations that

     

       594
       594
       +
            use <literal>buildRustPackage</literal> have been updated to reflect this

     

       595
       595
       +
            change. However, third-party derivations that use

     

       596
       596
       +
            <literal>buildRustPackage</literal> may have to be updated as well.

     

       550
       597
        
           </para>

     

       551
       598
        
          </listitem>

     

       552
       599
        
          <listitem>

     

       553
       600
        
           <para>

     

       554
       554
       -
            The <literal>consul</literal> package was upgraded past version <literal>1.5</literal>, so its deprecated legacy UI is no longer available.

     

       601
       601
       +
            The <literal>consul</literal> package was upgraded past version <literal>1.5</literal>,

     

       602
       602
       +
            so its deprecated legacy UI is no longer available.

     

       555
       603
        
           </para>

     

       556
       604
        
          </listitem>

     

       557
       605
        
          <listitem>

     

       558
       606
        
           <para>

     

       559
       559
       -
            The default resample-method for PulseAudio has been changed from the upstream default <literal>speex-float-1</literal> to <literal>speex-float-5</literal>. Be aware that low-powered ARM-based and MIPS-based boards will struggle with this so you'll need to set <option>hardware.pulseaudio.daemon.config.resample-method</option> back to <literal>speex-float-1</literal>.

     

       607
       607
       +
            The default resample-method for PulseAudio has been changed from the upstream default <literal>speex-float-1</literal>

     

       608
       608
       +
            to <literal>speex-float-5</literal>. Be aware that low-powered ARM-based and MIPS-based boards will struggle with this

     

       609
       609
       +
            so you'll need to set <option>hardware.pulseaudio.daemon.config.resample-method</option> back to <literal>speex-float-1</literal>.

     

       560
       610
        
           </para>

     

       561
       611
        
          </listitem>

     

       562
       612
        
          <listitem>

     

       563
       613
        
           <para>

     

       564
       564
       -
            The <literal>phabricator</literal> package and associated <literal>httpd.extraSubservice</literal>, as well as the <literal>phd</literal> service have been removed from nixpkgs due to lack of maintainer.

     

       614
       614
       +
            The <literal>phabricator</literal> package and associated <literal>httpd.extraSubservice</literal>, as well as the

     

       615
       615
       +
            <literal>phd</literal> service have been removed from nixpkgs due to lack of maintainer.

     

       565
       616
        
           </para>

     

       566
       617
        
          </listitem>

     

       567
       618
        
          <listitem>

     
···

       576
       627
        
          </listitem>

     

       577
       628
        
          <listitem>

     

       578
       629
        
           <para>

     

       579
       579
       -
            The <literal>foswiki</literal> package and associated <literal>httpd.extraSubservice</literal> have been removed from nixpkgs due to lack of maintainer.

     

       630
       630
       +
            The <literal>foswiki</literal> package and associated <literal>httpd.extraSubservice</literal> have been removed

     

       631
       631
       +
            from nixpkgs due to lack of maintainer.

     

       580
       632
        
           </para>

     

       581
       633
        
          </listitem>

     

       582
       634
        
          <listitem>

     
···

       586
       638
        
          </listitem>

     

       587
       639
        
          <listitem>

     

       588
       640
        
           <para>

     

       589
       589
       -
            It's now possible to change configuration in <link linkend="opt-services.nextcloud.enable">services.nextcloud</link> after the initial deploy since all config parameters are persisted in an additional config file generated by the module. Previously core configuration like database parameters were set using their imperative installer after creating <literal>/var/lib/nextcloud</literal>.

     

       641
       641
       +
            It's now possible to change configuration in

     

       642
       642
       +
            <link linkend="opt-services.nextcloud.enable">services.nextcloud</link> after the initial deploy

     

       643
       643
       +
            since all config parameters are persisted in an additional config file generated by the module.

     

       644
       644
       +
            Previously core configuration like database parameters were set using their imperative

     

       645
       645
       +
            installer after creating <literal>/var/lib/nextcloud</literal>.

     

       590
       646
        
           </para>

     

       591
       647
        
          </listitem>

     

       592
       648
        
          <listitem>

     

       593
       649
        
           <para>

     

       594
       594
       -
            There exists now <literal>lib.forEach</literal>, which is like <literal>map</literal>, but with arguments flipped. When mapping function body spans many lines (or has nested <literal>map</literal>s), it is often hard to follow which list is modified.

     

       650
       650
       +
            There exists now <literal>lib.forEach</literal>, which is like <literal>map</literal>, but with

     

       651
       651
       +
            arguments flipped. When mapping function body spans many lines (or has nested

     

       652
       652
       +
            <literal>map</literal>s), it is often hard to follow which list is modified.

     

       595
       653
        
           </para>

     

       596
       654
        
           <para>

     

       597
       597
       -
            Previous solution to this problem was either to use <literal>lib.flip map</literal> idiom or extract that anonymous mapping function to a named one. Both can still be used but <literal>lib.forEach</literal> is preferred over <literal>lib.flip map</literal>.

     

       655
       655
       +
            Previous solution to this problem was either to use <literal>lib.flip map</literal>

     

       656
       656
       +
            idiom or extract that anonymous mapping function to a named one. Both can still be used

     

       657
       657
       +
            but <literal>lib.forEach</literal> is preferred over <literal>lib.flip map</literal>.

     

       598
       658
        
           </para>

     

       599
       659
        
           <para>

     

       600
       600
       -
            The <literal>/etc/sysctl.d/nixos.conf</literal> file containing all the options set via <link linkend="opt-boot.kernel.sysctl">boot.kernel.sysctl</link> was moved to <literal>/etc/sysctl.d/60-nixos.conf</literal>, as <citerefentry>

     

       601
       601
       -
            <refentrytitle>sysctl.d</refentrytitle>

     

       602
       602
       -
            <manvolnum>5</manvolnum></citerefentry> recommends prefixing all filenames in <literal>/etc/sysctl.d</literal> with a two-digit number and a dash to simplify the ordering of the files.

     

       660
       660
       +
             The <literal>/etc/sysctl.d/nixos.conf</literal> file containing all the options set via

     

       661
       661
       +
             <link linkend="opt-boot.kernel.sysctl">boot.kernel.sysctl</link> was moved to

     

       662
       662
       +
             <literal>/etc/sysctl.d/60-nixos.conf</literal>, as

     

       663
       663
       +
             <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>

     

       664
       664
       +
             recommends prefixing all filenames in <literal>/etc/sysctl.d</literal> with a

     

       665
       665
       +
             two-digit number and a dash to simplify the ordering of the files.

     

       603
       666
        
           </para>

     

       604
       667
        
          </listitem>

     

       605
       668
        
          <listitem>

     

       606
       669
        
           <para>

     

       607
       607
       -
            We now install the sysctl snippets shipped with systemd.

     

       608
       608
       -
            <itemizedlist>

     

       670
       670
       +
             We now install the sysctl snippets shipped with systemd.

     

       671
       671
       +
           <itemizedlist>

     

       672
       672
       +
            <para>This enables:</para>

     

       673
       673
       +
            <listitem>

     

       674
       674
       +
             <para>Loose reverse path filtering</para>

     

       675
       675
       +
            </listitem>

     

       676
       676
       +
            <listitem>

     

       677
       677
       +
             <para>Source route filtering</para>

     

       678
       678
       +
            </listitem>

     

       679
       679
       +
            <listitem>

     

       609
       680
        
             <para>

     

       610
       610
       -
              This enables:

     

       681
       681
       +
              <literal>fq_codel</literal> as a packet scheduler (this helps to fight bufferbloat)

     

       611
       682
        
             </para>

     

       612
       612
       -
             <listitem>

     

       613
       613
       -
              <para>

     

       614
       614
       -
               Loose reverse path filtering

     

       615
       615
       -
              </para>

     

       616
       616
       -
             </listitem>

     

       617
       617
       -
             <listitem>

     

       618
       618
       -
              <para>

     

       619
       619
       -
               Source route filtering

     

       620
       620
       -
              </para>

     

       621
       621
       -
             </listitem>

     

       622
       622
       -
             <listitem>

     

       623
       623
       -
              <para>

     

       624
       624
       -
               <literal>fq_codel</literal> as a packet scheduler (this helps to fight bufferbloat)

     

       625
       625
       -
              </para>

     

       626
       626
       -
             </listitem>

     

       627
       627
       -
            </itemizedlist>

     

       628
       628
       -
            This also configures the kernel to pass coredumps to <literal>systemd-coredump</literal>, and restricts the SysRq key combinations to the sync command only. These sysctl snippets can be found in <literal>/etc/sysctl.d/50-*.conf</literal>, and overridden via <link linkend="opt-boot.kernel.sysctl">boot.kernel.sysctl</link> (which will place the parameters in <literal>/etc/sysctl.d/60-nixos.conf</literal>).

     

       629
       629
       -
           </para>

     

       683
       683
       +
            </listitem>

     

       684
       684
       +
           </itemizedlist>

     

       685
       685
       +
            This also configures the kernel to pass coredumps to <literal>systemd-coredump</literal>,

     

       686
       686
       +
            and restricts the SysRq key combinations to the sync command only.

     

       687
       687
       +
            These sysctl snippets can be found in <literal>/etc/sysctl.d/50-*.conf</literal>,

     

       688
       688
       +
            and overridden via <link linkend="opt-boot.kernel.sysctl">boot.kernel.sysctl</link>

     

       689
       689
       +
            (which will place the parameters in <literal>/etc/sysctl.d/60-nixos.conf</literal>).

     

       690
       690
       +
            </para>

     

       630
       691
        
          </listitem>

     

       631
       692
        
          <listitem>

     

       632
       693
        
           <para>

     

       633
       633
       -
            Coredumps are now acquired by <literal>systemd-coredump</literal> by default. <literal>systemd-coredump</literal> behaviour can still be modified via <option>systemd.coredump.extraConfig</option>. To stick to the old behaviour (having the kernel dump to a file called <literal>core</literal> in the working directory), without piping it through <literal>systemd-coredump</literal>, set <option>boot.kernel.sysctl."kernel.core_pattern"</option> to <literal>"core"</literal>.

     

       694
       694
       +
             Coredumps are now acquired by <literal>systemd-coredump</literal> by default.

     

       695
       695
       +
             <literal>systemd-coredump</literal> behaviour can still be modified via

     

       696
       696
       +
             <option>systemd.coredump.extraConfig</option>.

     

       697
       697
       +
             To stick to the old behaviour (having the kernel dump to a file called <literal>core</literal>

     

       698
       698
       +
             in the working directory), without piping it through <literal>systemd-coredump</literal>, set

     

       699
       699
       +
             <option>boot.kernel.sysctl."kernel.core_pattern"</option> to <literal>"core"</literal>.

     

       634
       700
        
           </para>

     

       635
       701
        
          </listitem>

     

       636
       702
        
          <listitem>

     

       637
       703
        
           <para>

     

       638
       638
       -
            <literal>systemd.packages</literal> option now also supports generators and shutdown scripts. Old <literal>systemd.generator-packages</literal> option has been removed.

     

       704
       704
       +
            <literal>systemd.packages</literal> option now also supports generators and

     

       705
       705
       +
            shutdown scripts. Old <literal>systemd.generator-packages</literal> option has

     

       706
       706
       +
            been removed.

     

       639
       707
        
           </para>

     

       640
       708
        
          </listitem>

     

       641
       709
        
          <listitem>

     

       642
       710
        
           <para>

     

       643
       643
       -
            The <literal>rmilter</literal> package was removed with associated module and options due deprecation by upstream developer. Use <literal>rspamd</literal> in proxy mode instead.

     

       711
       711
       +
            The <literal>rmilter</literal> package was removed with associated module and options due deprecation by upstream developer.

     

       712
       712
       +
            Use <literal>rspamd</literal> in proxy mode instead.

     

       644
       713
        
           </para>

     

       645
       714
        
          </listitem>

     

       646
       715
        
          <listitem>

     

       647
       716
        
           <para>

     

       648
       648
       -
            systemd cgroup accounting via the <link linkend="opt-systemd.enableCgroupAccounting">systemd.enableCgroupAccounting</link> option is now enabled by default. It now also enables the more recent Block IO and IP accounting features.

     

       717
       717
       +
             systemd cgroup accounting via the

     

       718
       718
       +
             <link linkend="opt-systemd.enableCgroupAccounting">systemd.enableCgroupAccounting</link>

     

       719
       719
       +
             option is now enabled by default. It now also enables the more recent Block IO and IP accounting

     

       720
       720
       +
             features.

     

       649
       721
        
           </para>

     

       650
       722
        
          </listitem>

     

       651
       723
        
          <listitem>

     

       652
       724
        
           <para>

     

       653
       653
       -
            We no longer enable custom font rendering settings with <option>fonts.fontconfig.penultimate.enable</option> by default. The defaults from fontconfig are sufficient.

     

       725
       725
       +
            We no longer enable custom font rendering settings with <option>fonts.fontconfig.penultimate.enable</option> by default.

     

       726
       726
       +
            The defaults from fontconfig are sufficient.

     

       654
       727
        
           </para>

     

       655
       728
        
          </listitem>

     

       656
       729
        
          <listitem>

     

       657
       730
        
           <para>

     

       658
       658
       -
            The <literal>crashplan</literal> package and the <literal>crashplan</literal> service have been removed from nixpkgs due to crashplan shutting down the service, while the <literal>crashplansb</literal> package and <literal>crashplan-small-business</literal> service have been removed from nixpkgs due to lack of maintainer.

     

       731
       731
       +
             The <literal>crashplan</literal> package and the

     

       732
       732
       +
             <literal>crashplan</literal> service have been removed from nixpkgs due to

     

       733
       733
       +
             crashplan shutting down the service, while the <literal>crashplansb</literal>

     

       734
       734
       +
             package and <literal>crashplan-small-business</literal> service have been

     

       735
       735
       +
             removed from nixpkgs due to lack of maintainer.

     

       659
       736
        
           </para>

     

       660
       737
        
           <para>

     

       661
       661
       -
            The <link linkend="opt-services.redis.enable">redis module</link> was hardcoded to use the <literal>redis</literal> user, <filename class="directory">/run/redis</filename> as runtime directory and <filename class="directory">/var/lib/redis</filename> as state directory. Note that the NixOS module for Redis now disables kernel support for Transparent Huge Pages (THP), because this features causes major performance problems for Redis, e.g. (https://redis.io/topics/latency).

     

       738
       738
       +
             The <link linkend="opt-services.redis.enable">redis module</link> was hardcoded to use the <literal>redis</literal> user,

     

       739
       739
       +
             <filename class="directory">/run/redis</filename> as runtime directory and

     

       740
       740
       +
             <filename class="directory">/var/lib/redis</filename> as state directory.

     

       741
       741
       +
             Note that the NixOS module for Redis now disables kernel support for Transparent Huge Pages (THP),

     

       742
       742
       +
             because this features causes major performance problems for Redis,

     

       743
       743
       +
             e.g. (https://redis.io/topics/latency).

     

       662
       744
        
           </para>

     

       663
       745
        
          </listitem>

     

       664
       746
        
          <listitem>

     

       665
       747
        
           <para>

     

       666
       748
        
            Using <option>fonts.enableDefaultFonts</option> adds a default emoji font <literal>noto-fonts-emoji</literal>.

     

       667
       749
        
            <itemizedlist>

     

       668
       668
       -
             <para>

     

       669
       669
       -
              Users of the following options will have this enabled by default:

     

       670
       670
       -
             </para>

     

       750
       750
       +
             <para>Users of the following options will have this enabled by default:</para>

     

       671
       751
        
             <listitem>

     

       672
       672
       -
              <para>

     

       673
       673
       -
               <option>services.xserver.enable</option>

     

       674
       674
       -
              </para>

     

       752
       752
       +
              <para><option>services.xserver.enable</option></para>

     

       675
       753
        
             </listitem>

     

       676
       754
        
             <listitem>

     

       677
       677
       -
              <para>

     

       678
       678
       -
               <option>programs.sway.enable</option>

     

       679
       679
       -
              </para>

     

       755
       755
       +
              <para><option>programs.sway.enable</option></para>

     

       680
       756
        
             </listitem>

     

       681
       757
        
             <listitem>

     

       682
       682
       -
              <para>

     

       683
       683
       -
               <option>programs.way-cooler.enable</option>

     

       684
       684
       -
              </para>

     

       758
       758
       +
              <para><option>programs.way-cooler.enable</option></para>

     

       685
       759
        
             </listitem>

     

       686
       760
        
             <listitem>

     

       687
       687
       -
              <para>

     

       688
       688
       -
               <option>services.xrdp.enable</option>

     

       689
       689
       -
              </para>

     

       761
       761
       +
              <para><option>services.xrdp.enable</option></para>

     

       690
       762
        
             </listitem>

     

       691
       763
        
            </itemizedlist>

     

       692
       764
        
           </para>

     

       693
       765
        
          </listitem>

     

       694
       766
        
          <listitem>

     

       695
       695
       -
           <para>

     

       696
       696
       -
            The <literal>altcoins</literal> categorization of packages has been removed. You now access these packages at the top level, ie. <literal>nix-shell -p dogecoin</literal> instead of <literal>nix-shell -p altcoins.dogecoin</literal>, etc.

     

       697
       697
       -
           </para>

     

       767
       767
       +
            <para>

     

       768
       768
       +
              The <literal>altcoins</literal> categorization of packages has

     

       769
       769
       +
              been removed. You now access these packages at the top level,

     

       770
       770
       +
              ie. <literal>nix-shell -p dogecoin</literal> instead of

     

       771
       771
       +
              <literal>nix-shell -p altcoins.dogecoin</literal>, etc.

     

       772
       772
       +
            </para>

     

       698
       773
        
          </listitem>

     

       699
       774
        
          <listitem>

     

       700
       700
       -
           <para>

     

       701
       701
       -
            Ceph has been upgraded to v14.2.1. See the <link xlink:href="https://ceph.com/releases/v14-2-0-nautilus-released/">release notes</link> for details. The mgr dashboard as well as osds backed by loop-devices is no longer explicitly supported by the package and module. Note: There's been some issues with python-cherrypy, which is used by the dashboard and prometheus mgr modules (and possibly others), hence 0000-dont-check-cherrypy-version.patch.

     

       702
       702
       -
           </para>

     

       703
       703
       -
          </listitem>

     

       704
       704
       -
          <listitem>

     

       705
       705
       -
           <para>

     

       706
       706
       -
            <literal>pkgs.weechat</literal> is now compiled against <literal>pkgs.python3</literal>. Weechat also recommends <link xlink:href="https://weechat.org/scripts/python3/">to use Python3 in their docs.</link>

     

       707
       707
       -
           </para>

     

       708
       708
       -
          </listitem>

     

       775
       775
       +
            <para>

     

       776
       776
       +
              Ceph has been upgraded to v14.2.1.

     

       777
       777
       +
              See the <link xlink:href="https://ceph.com/releases/v14-2-0-nautilus-released/">release notes</link> for details.

     

       778
       778
       +
              The mgr dashboard as well as osds backed by loop-devices is no longer explicitly supported by the package and module.

     

       779
       779
       +
              Note: There's been some issues with python-cherrypy, which is used by the dashboard

     

       780
       780
       +
              and prometheus mgr modules (and possibly others), hence 0000-dont-check-cherrypy-version.patch.

     

       781
       781
       +
            </para>

     

       782
       782
       +
           </listitem>

     

       783
       783
       +
           <listitem>

     

       784
       784
       +
            <para>

     

       785
       785
       +
             <literal>pkgs.weechat</literal> is now compiled against <literal>pkgs.python3</literal>.

     

       786
       786
       +
             Weechat also recommends <link xlink:href="https://weechat.org/scripts/python3/">to use Python3

     

       787
       787
       +
             in their docs.</link>

     

       788
       788
       +
            </para>

     

       789
       789
       +
           </listitem>

     

       709
       790
        
         </itemizedlist>

     

       710
       791
        
        </section>

     

       711
       792
        
       </section>

+5 -2

nixos/doc/manual/release-notes/rl-2003.xml

···

       13
       13
        
         <title>Highlights</title>

     

       14
       14
        
       

     

       15
       15
        
         <para>

     

       16
       16
       -
          In addition to numerous new and upgraded packages, this release has the following highlights:

     

       16
       16
       +
          In addition to numerous new and upgraded packages, this release has the

     

       17
       17
       +
          following highlights:

     

       17
       18
        
         </para>

     

       18
       19
        
       

     

       19
       20
        
         <itemizedlist>

     
···

       41
       42
        
           <para />

     

       42
       43
        
          </listitem>

     

       43
       44
        
         </itemizedlist>

     

       45
       45
       +
       

     

       44
       46
        
        </section>

     

       45
       47
        
       

     

       46
       48
        
        <section xmlns="http://docbook.org/ns/docbook"

     
···

       51
       53
        
         <title>Backward Incompatibilities</title>

     

       52
       54
        
       

     

       53
       55
        
         <para>

     

       54
       54
       -
          When upgrading from a previous release, please be aware of the following incompatible changes:

     

       56
       56
       +
          When upgrading from a previous release, please be aware of the following

     

       57
       57
       +
          incompatible changes:

     

       55
       58
        
         </para>

     

       56
       59
        
       

     

       57
       60
        
         <itemizedlist>

+54 -20

nixos/modules/i18n/input-method/default.xml

···

       5
       5
        
                xml:id="module-services-input-methods">

     

       6
       6
        
        <title>Input Methods</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         Input methods are an operating system component that allows any data, such as keyboard strokes or mouse movements, to be received as input. In this way users can enter characters and symbols not found on their input devices. Using an input method is obligatory for any language that has more graphemes than there are keys on the keyboard.

     

       8
       8
       +
         Input methods are an operating system component that allows any data, such as

     

       9
       9
       +
         keyboard strokes or mouse movements, to be received as input. In this way

     

       10
       10
       +
         users can enter characters and symbols not found on their input devices.

     

       11
       11
       +
         Using an input method is obligatory for any language that has more graphemes

     

       12
       12
       +
         than there are keys on the keyboard.

     

       9
       13
        
        </para>

     

       10
       14
        
        <para>

     

       11
       15
        
         The following input methods are available in NixOS:

     
···

       36
       40
        
         <title>IBus</title>

     

       37
       41
        
       

     

       38
       42
        
         <para>

     

       39
       39
       -
          IBus is an Intelligent Input Bus. It provides full featured and user friendly input method user interface.

     

       43
       43
       +
          IBus is an Intelligent Input Bus. It provides full featured and user

     

       44
       44
       +
          friendly input method user interface.

     

       40
       45
        
         </para>

     

       41
       46
        
       

     

       42
       47
        
         <para>

     
···

       51
       56
        
       </programlisting>

     

       52
       57
        
       

     

       53
       58
        
         <para>

     

       54
       54
       -
          <literal>i18n.inputMethod.ibus.engines</literal> is optional and can be used to add extra IBus engines.

     

       59
       59
       +
          <literal>i18n.inputMethod.ibus.engines</literal> is optional and can be used

     

       60
       60
       +
          to add extra IBus engines.

     

       55
       61
        
         </para>

     

       56
       62
        
       

     

       57
       63
        
         <para>

     
···

       61
       67
        
         <itemizedlist>

     

       62
       68
        
          <listitem>

     

       63
       69
        
           <para>

     

       64
       64
       -
            Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a system for Japanese input method. It converts Hiragana text to Kana Kanji mixed text.

     

       70
       70
       +
            Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a system for

     

       71
       71
       +
            Japanese input method. It converts Hiragana text to Kana Kanji mixed text.

     

       65
       72
        
           </para>

     

       66
       73
        
          </listitem>

     

       67
       74
        
          <listitem>

     
···

       71
       78
        
          </listitem>

     

       72
       79
        
          <listitem>

     

       73
       80
        
           <para>

     

       74
       74
       -
            m17n (<literal>ibus-engines.m17n</literal>): m17n is an input method that uses input methods and corresponding icons in the m17n database.

     

       81
       81
       +
            m17n (<literal>ibus-engines.m17n</literal>): m17n is an input method that

     

       82
       82
       +
            uses input methods and corresponding icons in the m17n database.

     

       75
       83
        
           </para>

     

       76
       84
        
          </listitem>

     

       77
       85
        
          <listitem>

     

       78
       86
        
           <para>

     

       79
       79
       -
            mozc (<literal>ibus-engines.mozc</literal>): A Japanese input method from Google.

     

       87
       87
       +
            mozc (<literal>ibus-engines.mozc</literal>): A Japanese input method from

     

       88
       88
       +
            Google.

     

       80
       89
        
           </para>

     

       81
       90
        
          </listitem>

     

       82
       91
        
          <listitem>

     

       83
       92
        
           <para>

     

       84
       84
       -
            Table (<literal>ibus-engines.table</literal>): An input method that load tables of input methods.

     

       93
       93
       +
            Table (<literal>ibus-engines.table</literal>): An input method that load

     

       94
       94
       +
            tables of input methods.

     

       85
       95
        
           </para>

     

       86
       96
        
          </listitem>

     

       87
       97
        
          <listitem>

     

       88
       98
        
           <para>

     

       89
       89
       -
            table-others (<literal>ibus-engines.table-others</literal>): Various table-based input methods. To use this, and any other table-based input methods, it must appear in the list of engines along with <literal>table</literal>. For example:

     

       99
       99
       +
            table-others (<literal>ibus-engines.table-others</literal>): Various

     

       100
       100
       +
            table-based input methods. To use this, and any other table-based input

     

       101
       101
       +
            methods, it must appear in the list of engines along with

     

       102
       102
       +
            <literal>table</literal>. For example:

     

       90
       103
        
       <programlisting>

     

       91
       104
        
       ibus.engines = with pkgs.ibus-engines; [ table table-others ];

     

       92
       105
        
       </programlisting>

     
···

       95
       108
        
         </itemizedlist>

     

       96
       109
        
       

     

       97
       110
        
         <para>

     

       98
       98
       -
          To use any input method, the package must be added in the configuration, as shown above, and also (after running <literal>nixos-rebuild</literal>) the input method must be added from IBus' preference dialog.

     

       111
       111
       +
          To use any input method, the package must be added in the configuration, as

     

       112
       112
       +
          shown above, and also (after running <literal>nixos-rebuild</literal>) the

     

       113
       113
       +
          input method must be added from IBus' preference dialog.

     

       99
       114
        
         </para>

     

       100
       115
        
       

     

       101
       116
        
         <simplesect xml:id="module-services-input-methods-troubleshooting">

     

       102
       117
        
          <title>Troubleshooting</title>

     

       103
       118
        
          <para>

     

       104
       104
       -
           If IBus works in some applications but not others, a likely cause of this is that IBus is depending on a different version of <literal>glib</literal> to what the applications are depending on. This can be checked by running <literal>nix-store -q --requisites &lt;path&gt; | grep glib</literal>, where <literal>&lt;path&gt;</literal> is the path of either IBus or an application in the Nix store. The <literal>glib</literal> packages must match exactly. If they do not, uninstalling and reinstalling the application is a likely fix.

     

       119
       119
       +
           If IBus works in some applications but not others, a likely cause of this

     

       120
       120
       +
           is that IBus is depending on a different version of <literal>glib</literal>

     

       121
       121
       +
           to what the applications are depending on. This can be checked by running

     

       122
       122
       +
           <literal>nix-store -q --requisites &lt;path&gt; | grep glib</literal>,

     

       123
       123
       +
           where <literal>&lt;path&gt;</literal> is the path of either IBus or an

     

       124
       124
       +
           application in the Nix store. The <literal>glib</literal> packages must

     

       125
       125
       +
           match exactly. If they do not, uninstalling and reinstalling the

     

       126
       126
       +
           application is a likely fix.

     

       105
       127
        
          </para>

     

       106
       128
        
         </simplesect>

     

       107
       129
        
        </section>

     
···

       109
       131
        
         <title>Fcitx</title>

     

       110
       132
        
       

     

       111
       133
        
         <para>

     

       112
       112
       -
          Fcitx is an input method framework with extension support. It has three built-in Input Method Engine, Pinyin, QuWei and Table-based input methods.

     

       134
       134
       +
          Fcitx is an input method framework with extension support. It has three

     

       135
       135
       +
          built-in Input Method Engine, Pinyin, QuWei and Table-based input methods.

     

       113
       136
        
         </para>

     

       114
       137
        
       

     

       115
       138
        
         <para>

     
···

       124
       147
        
       </programlisting>

     

       125
       148
        
       

     

       126
       149
        
         <para>

     

       127
       127
       -
          <literal>i18n.inputMethod.fcitx.engines</literal> is optional and can be used to add extra Fcitx engines.

     

       150
       150
       +
          <literal>i18n.inputMethod.fcitx.engines</literal> is optional and can be

     

       151
       151
       +
          used to add extra Fcitx engines.

     

       128
       152
        
         </para>

     

       129
       153
        
       

     

       130
       154
        
         <para>

     
···

       134
       158
        
         <itemizedlist>

     

       135
       159
        
          <listitem>

     

       136
       160
        
           <para>

     

       137
       137
       -
            Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a system for Japanese input method. It converts Hiragana text to Kana Kanji mixed text.

     

       161
       161
       +
            Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a system for

     

       162
       162
       +
            Japanese input method. It converts Hiragana text to Kana Kanji mixed text.

     

       138
       163
        
           </para>

     

       139
       164
        
          </listitem>

     

       140
       165
        
          <listitem>

     

       141
       166
        
           <para>

     

       142
       142
       -
            Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is an intelligent Zhuyin input method. It is one of the most popular input methods among Traditional Chinese Unix users.

     

       167
       167
       +
            Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is an

     

       168
       168
       +
            intelligent Zhuyin input method. It is one of the most popular input

     

       169
       169
       +
            methods among Traditional Chinese Unix users.

     

       143
       170
        
           </para>

     

       144
       171
        
          </listitem>

     

       145
       172
        
          <listitem>

     
···

       154
       181
        
          </listitem>

     

       155
       182
        
          <listitem>

     

       156
       183
        
           <para>

     

       157
       157
       -
            m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input method that uses input methods and corresponding icons in the m17n database.

     

       184
       184
       +
            m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input method that

     

       185
       185
       +
            uses input methods and corresponding icons in the m17n database.

     

       158
       186
        
           </para>

     

       159
       187
        
          </listitem>

     

       160
       188
        
          <listitem>

     

       161
       189
        
           <para>

     

       162
       162
       -
            mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input method from Google.

     

       190
       190
       +
            mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input method from

     

       191
       191
       +
            Google.

     

       163
       192
        
           </para>

     

       164
       193
        
          </listitem>

     

       165
       194
        
          <listitem>

     

       166
       195
        
           <para>

     

       167
       167
       -
            table-others (<literal>fcitx-engines.table-others</literal>): Various table-based input methods.

     

       196
       196
       +
            table-others (<literal>fcitx-engines.table-others</literal>): Various

     

       197
       197
       +
            table-based input methods.

     

       168
       198
        
           </para>

     

       169
       199
        
          </listitem>

     

       170
       200
        
         </itemizedlist>

     
···

       173
       203
        
         <title>Nabi</title>

     

       174
       204
        
       

     

       175
       205
        
         <para>

     

       176
       176
       -
          Nabi is an easy to use Korean X input method. It allows you to enter phonetic Korean characters (hangul) and pictographic Korean characters (hanja).

     

       206
       206
       +
          Nabi is an easy to use Korean X input method. It allows you to enter

     

       207
       207
       +
          phonetic Korean characters (hangul) and pictographic Korean characters

     

       208
       208
       +
          (hanja).

     

       177
       209
        
         </para>

     

       178
       210
        
       

     

       179
       211
        
         <para>

     
···

       190
       222
        
         <title>Uim</title>

     

       191
       223
        
       

     

       192
       224
        
         <para>

     

       193
       193
       -
          Uim (short for "universal input method") is a multilingual input method framework. Applications can use it through so-called bridges.

     

       225
       225
       +
          Uim (short for "universal input method") is a multilingual input method

     

       226
       226
       +
          framework. Applications can use it through so-called bridges.

     

       194
       227
        
         </para>

     

       195
       228
        
       

     

       196
       229
        
         <para>

     
···

       204
       237
        
       </programlisting>

     

       205
       238
        
       

     

       206
       239
        
         <para>

     

       207
       207
       -
          Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"/> option can be used to choose uim toolbar.

     

       240
       240
       +
          Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"/> option can be

     

       241
       241
       +
          used to choose uim toolbar.

     

       208
       242
        
         </para>

     

       209
       243
        
        </section>

     

       210
       244
        
       </chapter>

+24 -9

nixos/modules/programs/digitalbitbox/doc.xml

···

       8
       8
        
         Digital Bitbox is a hardware wallet and second-factor authenticator.

     

       9
       9
        
        </para>

     

       10
       10
        
        <para>

     

       11
       11
       -
         The <literal>digitalbitbox</literal> programs module may be installed by setting <literal>programs.digitalbitbox</literal> to <literal>true</literal> in a manner similar to

     

       11
       11
       +
         The <literal>digitalbitbox</literal> programs module may be installed by

     

       12
       12
       +
         setting <literal>programs.digitalbitbox</literal> to <literal>true</literal>

     

       13
       13
       +
         in a manner similar to

     

       12
       14
        
       <programlisting>

     

       13
       15
        
       <xref linkend="opt-programs.digitalbitbox.enable"/> = true;

     

       14
       16
        
       </programlisting>

     

       15
       15
       -
         and bundles the <literal>digitalbitbox</literal> package (see <xref

     

       16
       16
       -
             linkend="sec-digitalbitbox-package" />), which contains the <literal>dbb-app</literal> and <literal>dbb-cli</literal> binaries, along with the hardware module (see <xref

     

       17
       17
       -
             linkend="sec-digitalbitbox-hardware-module" />) which sets up the necessary udev rules to access the device.

     

       17
       17
       +
         and bundles the <literal>digitalbitbox</literal> package (see

     

       18
       18
       +
         <xref

     

       19
       19
       +
             linkend="sec-digitalbitbox-package" />), which contains the

     

       20
       20
       +
         <literal>dbb-app</literal> and <literal>dbb-cli</literal> binaries, along

     

       21
       21
       +
         with the hardware module (see

     

       22
       22
       +
         <xref

     

       23
       23
       +
             linkend="sec-digitalbitbox-hardware-module" />) which sets up the

     

       24
       24
       +
         necessary udev rules to access the device.

     

       18
       25
        
        </para>

     

       19
       26
        
        <para>

     

       20
       20
       -
         Enabling the digitalbitbox module is pretty much the easiest way to get a Digital Bitbox device working on your system.

     

       27
       27
       +
         Enabling the digitalbitbox module is pretty much the easiest way to get a

     

       28
       28
       +
         Digital Bitbox device working on your system.

     

       21
       29
        
        </para>

     

       22
       30
        
        <para>

     

       23
       23
       -
         For more information, see <link xlink:href="https://digitalbitbox.com/start_linux" />.

     

       31
       31
       +
         For more information, see

     

       32
       32
       +
         <link xlink:href="https://digitalbitbox.com/start_linux" />.

     

       24
       33
        
        </para>

     

       25
       34
        
        <section xml:id="sec-digitalbitbox-package">

     

       26
       35
        
         <title>Package</title>

     

       27
       36
        
       

     

       28
       37
        
         <para>

     

       29
       29
       -
          The binaries, <literal>dbb-app</literal> (a GUI tool) and <literal>dbb-cli</literal> (a CLI tool), are available through the <literal>digitalbitbox</literal> package which could be installed as follows:

     

       38
       38
       +
          The binaries, <literal>dbb-app</literal> (a GUI tool) and

     

       39
       39
       +
          <literal>dbb-cli</literal> (a CLI tool), are available through the

     

       40
       40
       +
          <literal>digitalbitbox</literal> package which could be installed as

     

       41
       41
       +
          follows:

     

       30
       42
        
       <programlisting>

     

       31
       43
        
       <xref linkend="opt-environment.systemPackages"/> = [

     

       32
       44
        
         pkgs.digitalbitbox

     
···

       38
       50
        
         <title>Hardware</title>

     

       39
       51
        
       

     

       40
       52
        
         <para>

     

       41
       41
       -
          The digitalbitbox hardware package enables the udev rules for Digital Bitbox devices and may be installed as follows:

     

       53
       53
       +
          The digitalbitbox hardware package enables the udev rules for Digital Bitbox

     

       54
       54
       +
          devices and may be installed as follows:

     

       42
       55
        
       <programlisting>

     

       43
       56
        
       <xref linkend="opt-hardware.digitalbitbox.enable"/> = true;

     

       44
       57
        
       </programlisting>

     

       45
       58
        
         </para>

     

       46
       59
        
       

     

       47
       60
        
         <para>

     

       48
       48
       -
          In order to alter the udev rules, one may provide different values for the <literal>udevRule51</literal> and <literal>udevRule52</literal> attributes by means of overriding as follows:

     

       61
       61
       +
          In order to alter the udev rules, one may provide different values for the

     

       62
       62
       +
          <literal>udevRule51</literal> and <literal>udevRule52</literal> attributes

     

       63
       63
       +
          by means of overriding as follows:

     

       49
       64
        
       <programlisting>

     

       50
       65
        
       programs.digitalbitbox = {

     

       51
       66
        
         <link linkend="opt-programs.digitalbitbox.enable">enable</link> = true;

+9 -4

nixos/modules/programs/plotinus.xml

···

       5
       5
        
                xml:id="module-program-plotinus">

     

       6
       6
        
        <title>Plotinus</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         <emphasis>Source:</emphasis> <filename>modules/programs/plotinus.nix</filename>

     

       8
       8
       +
         <emphasis>Source:</emphasis>

     

       9
       9
       +
         <filename>modules/programs/plotinus.nix</filename>

     

       9
       10
        
        </para>

     

       10
       11
        
        <para>

     

       11
       11
       -
         <emphasis>Upstream documentation:</emphasis> <link xlink:href="https://github.com/p-e-w/plotinus"/>

     

       12
       12
       +
         <emphasis>Upstream documentation:</emphasis>

     

       13
       13
       +
         <link xlink:href="https://github.com/p-e-w/plotinus"/>

     

       12
       14
        
        </para>

     

       13
       15
        
        <para>

     

       14
       16
        
         Plotinus is a searchable command palette in every modern GTK application.

     

       15
       17
        
        </para>

     

       16
       18
        
        <para>

     

       17
       17
       -
         When in a GTK 3 application and Plotinus is enabled, you can press <literal>Ctrl+Shift+P</literal> to open the command palette. The command palette provides a searchable list of of all menu items in the application.

     

       19
       19
       +
         When in a GTK 3 application and Plotinus is enabled, you can press

     

       20
       20
       +
         <literal>Ctrl+Shift+P</literal> to open the command palette. The command

     

       21
       21
       +
         palette provides a searchable list of of all menu items in the application.

     

       18
       22
        
        </para>

     

       19
       23
        
        <para>

     

       20
       20
       -
         To enable Plotinus, add the following to your <filename>configuration.nix</filename>:

     

       24
       24
       +
         To enable Plotinus, add the following to your

     

       25
       25
       +
         <filename>configuration.nix</filename>:

     

       21
       26
        
       <programlisting>

     

       22
       27
        
       <xref linkend="opt-programs.plotinus.enable"/> = true;

     

       23
       28
        
       </programlisting>

+49 -13

nixos/modules/programs/zsh/oh-my-zsh.xml

···

       5
       5
        
                xml:id="module-programs-zsh-ohmyzsh">

     

       6
       6
        
        <title>Oh my ZSH</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         <literal><link xlink:href="https://ohmyz.sh/">oh-my-zsh</link></literal> is a framework to manage your <link xlink:href="https://www.zsh.org/">ZSH</link> configuration including completion scripts for several CLI tools or custom prompt themes.

     

       8
       8
       +
         <literal><link xlink:href="https://ohmyz.sh/">oh-my-zsh</link></literal> is a

     

       9
       9
       +
         framework to manage your <link xlink:href="https://www.zsh.org/">ZSH</link>

     

       10
       10
       +
         configuration including completion scripts for several CLI tools or custom

     

       11
       11
       +
         prompt themes.

     

       9
       12
        
        </para>

     

       10
       13
        
        <section xml:id="module-programs-oh-my-zsh-usage">

     

       11
       14
        
         <title>Basic usage</title>

     

       12
       15
        
       

     

       13
       16
        
         <para>

     

       14
       14
       -
          The module uses the <literal>oh-my-zsh</literal> package with all available features. The initial setup using Nix expressions is fairly similar to the configuration format of <literal>oh-my-zsh</literal>.

     

       17
       17
       +
          The module uses the <literal>oh-my-zsh</literal> package with all available

     

       18
       18
       +
          features. The initial setup using Nix expressions is fairly similar to the

     

       19
       19
       +
          configuration format of <literal>oh-my-zsh</literal>.

     

       15
       20
        
       <programlisting>

     

       16
       21
        
       {

     

       17
       22
        
         programs.zsh.ohMyZsh = {

     
···

       21
       26
        
         };

     

       22
       27
        
       }

     

       23
       28
        
       </programlisting>

     

       24
       24
       -
          For a detailed explanation of these arguments please refer to the <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal> docs</link>.

     

       29
       29
       +
          For a detailed explanation of these arguments please refer to the

     

       30
       30
       +
          <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal>

     

       31
       31
       +
          docs</link>.

     

       25
       32
        
         </para>

     

       26
       33
        
       

     

       27
       34
        
         <para>

     

       28
       28
       -
          The expression generates the needed configuration and writes it into your <literal>/etc/zshrc</literal>.

     

       35
       35
       +
          The expression generates the needed configuration and writes it into your

     

       36
       36
       +
          <literal>/etc/zshrc</literal>.

     

       29
       37
        
         </para>

     

       30
       38
        
        </section>

     

       31
       39
        
        <section xml:id="module-programs-oh-my-zsh-additions">

     

       32
       40
        
         <title>Custom additions</title>

     

       33
       41
        
       

     

       34
       42
        
         <para>

     

       35
       35
       -
          Sometimes third-party or custom scripts such as a modified theme may be needed. <literal>oh-my-zsh</literal> provides the <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link> environment variable for this which points to a directory with additional scripts.

     

       43
       43
       +
          Sometimes third-party or custom scripts such as a modified theme may be

     

       44
       44
       +
          needed. <literal>oh-my-zsh</literal> provides the

     

       45
       45
       +
          <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link>

     

       46
       46
       +
          environment variable for this which points to a directory with additional

     

       47
       47
       +
          scripts.

     

       36
       48
        
         </para>

     

       37
       49
        
       

     

       38
       50
        
         <para>

     
···

       48
       60
        
         <title>Custom environments</title>

     

       49
       61
        
       

     

       50
       62
        
         <para>

     

       51
       51
       -
          There are several extensions for <literal>oh-my-zsh</literal> packaged in <literal>nixpkgs</literal>. One of them is <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link> which bundles completion scripts and a plugin for <literal>oh-my-zsh</literal>.

     

       63
       63
       +
          There are several extensions for <literal>oh-my-zsh</literal> packaged in

     

       64
       64
       +
          <literal>nixpkgs</literal>. One of them is

     

       65
       65
       +
          <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>

     

       66
       66
       +
          which bundles completion scripts and a plugin for

     

       67
       67
       +
          <literal>oh-my-zsh</literal>.

     

       52
       68
        
         </para>

     

       53
       69
        
       

     

       54
       70
        
         <para>

     

       55
       55
       -
          Rather than using a single mutable path for <literal>ZSH_CUSTOM</literal>, it's also possible to generate this path from a list of Nix packages:

     

       71
       71
       +
          Rather than using a single mutable path for <literal>ZSH_CUSTOM</literal>,

     

       72
       72
       +
          it's also possible to generate this path from a list of Nix packages:

     

       56
       73
        
       <programlisting>

     

       57
       74
        
       { pkgs, ... }:

     

       58
       75
        
       {

     
···

       62
       79
        
         ];

     

       63
       80
        
       }

     

       64
       81
        
       </programlisting>

     

       65
       65
       -
          Internally a single store path will be created using <literal>buildEnv</literal>. Please refer to the docs of <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link> for further reference.

     

       82
       82
       +
          Internally a single store path will be created using

     

       83
       83
       +
          <literal>buildEnv</literal>. Please refer to the docs of

     

       84
       84
       +
          <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link>

     

       85
       85
       +
          for further reference.

     

       66
       86
        
         </para>

     

       67
       87
        
       

     

       68
       88
        
         <para>

     

       69
       69
       -
          <emphasis>Please keep in mind that this is not compatible with <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an immutable store path while <literal>custom</literal> shall remain mutable! An evaluation failure will be thrown if both <literal>custom</literal> and <literal>customPkgs</literal> are set.</emphasis>

     

       89
       89
       +
          <emphasis>Please keep in mind that this is not compatible with

     

       90
       90
       +
          <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an immutable

     

       91
       91
       +
          store path while <literal>custom</literal> shall remain mutable! An

     

       92
       92
       +
          evaluation failure will be thrown if both <literal>custom</literal> and

     

       93
       93
       +
          <literal>customPkgs</literal> are set.</emphasis>

     

       70
       94
        
         </para>

     

       71
       95
        
        </section>

     

       72
       96
        
        <section xml:id="module-programs-oh-my-zsh-packaging-customizations">

     

       73
       97
        
         <title>Package your own customizations</title>

     

       74
       98
        
       

     

       75
       99
        
         <para>

     

       76
       76
       -
          If third-party customizations (e.g. new themes) are supposed to be added to <literal>oh-my-zsh</literal> there are several pitfalls to keep in mind:

     

       100
       100
       +
          If third-party customizations (e.g. new themes) are supposed to be added to

     

       101
       101
       +
          <literal>oh-my-zsh</literal> there are several pitfalls to keep in mind:

     

       77
       102
        
         </para>

     

       78
       103
        
       

     

       79
       104
        
         <itemizedlist>

     

       80
       105
        
          <listitem>

     

       81
       106
        
           <para>

     

       82
       82
       -
            To comply with the default structure of <literal>ZSH</literal> the entire output needs to be written to <literal>$out/share/zsh.</literal>

     

       107
       107
       +
            To comply with the default structure of <literal>ZSH</literal> the entire

     

       108
       108
       +
            output needs to be written to <literal>$out/share/zsh.</literal>

     

       83
       109
        
           </para>

     

       84
       110
        
          </listitem>

     

       85
       111
        
          <listitem>

     

       86
       112
        
           <para>

     

       87
       87
       -
            Completion scripts are supposed to be stored at <literal>$out/share/zsh/site-functions</literal>. This directory is part of the <literal><link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html">fpath</link></literal> and the package should be compatible with pure <literal>ZSH</literal> setups. The module will automatically link the contents of <literal>site-functions</literal> to completions directory in the proper store path.

     

       113
       113
       +
            Completion scripts are supposed to be stored at

     

       114
       114
       +
            <literal>$out/share/zsh/site-functions</literal>. This directory is part

     

       115
       115
       +
            of the

     

       116
       116
       +
            <literal><link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html">fpath</link></literal>

     

       117
       117
       +
            and the package should be compatible with pure <literal>ZSH</literal>

     

       118
       118
       +
            setups. The module will automatically link the contents of

     

       119
       119
       +
            <literal>site-functions</literal> to completions directory in the proper

     

       120
       120
       +
            store path.

     

       88
       121
        
           </para>

     

       89
       122
        
          </listitem>

     

       90
       123
        
          <listitem>

     

       91
       124
        
           <para>

     

       92
       92
       -
            The <literal>plugins</literal> directory needs the structure <literal>pluginname/pluginname.plugin.zsh</literal> as structured in the <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream repo.</link>

     

       125
       125
       +
            The <literal>plugins</literal> directory needs the structure

     

       126
       126
       +
            <literal>pluginname/pluginname.plugin.zsh</literal> as structured in the

     

       127
       127
       +
            <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream

     

       128
       128
       +
            repo.</link>

     

       93
       129
        
           </para>

     

       94
       130
        
          </listitem>

     

       95
       131
        
         </itemizedlist>

+23 -7

nixos/modules/security/acme.xml

···

       5
       5
        
                xml:id="module-security-acme">

     

       6
       6
        
        <title>SSL/TLS Certificates with ACME</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         NixOS supports automatic domain validation &amp; certificate retrieval and renewal using the ACME protocol. This is currently only implemented by and for Let's Encrypt. The alternative ACME client <literal>simp_le</literal> is used under the hood.

     

       8
       8
       +
         NixOS supports automatic domain validation &amp; certificate retrieval and

     

       9
       9
       +
         renewal using the ACME protocol. This is currently only implemented by and

     

       10
       10
       +
         for Let's Encrypt. The alternative ACME client <literal>simp_le</literal> is

     

       11
       11
       +
         used under the hood.

     

       9
       12
        
        </para>

     

       10
       13
        
        <section xml:id="module-security-acme-prerequisites">

     

       11
       14
        
         <title>Prerequisites</title>

     

       12
       15
        
       

     

       13
       16
        
         <para>

     

       14
       14
       -
          You need to have a running HTTP server for verification. The server must have a webroot defined that can serve <filename>.well-known/acme-challenge</filename>. This directory must be writeable by the user that will run the ACME client.

     

       17
       17
       +
          You need to have a running HTTP server for verification. The server must

     

       18
       18
       +
          have a webroot defined that can serve

     

       19
       19
       +
          <filename>.well-known/acme-challenge</filename>. This directory must be

     

       20
       20
       +
          writeable by the user that will run the ACME client.

     

       15
       21
        
         </para>

     

       16
       22
        
       

     

       17
       23
        
         <para>

     
···

       39
       45
        
         <title>Configuring</title>

     

       40
       46
        
       

     

       41
       47
        
         <para>

     

       42
       42
       -
          To enable ACME certificate retrieval &amp; renewal for a certificate for <literal>foo.example.com</literal>, add the following in your <filename>configuration.nix</filename>:

     

       48
       48
       +
          To enable ACME certificate retrieval &amp; renewal for a certificate for

     

       49
       49
       +
          <literal>foo.example.com</literal>, add the following in your

     

       50
       50
       +
          <filename>configuration.nix</filename>:

     

       43
       51
        
       <programlisting>

     

       44
       52
        
       <xref linkend="opt-security.acme.certs"/>."foo.example.com" = {

     

       45
       53
        
         <link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/www/challenges";

     
···

       49
       57
        
         </para>

     

       50
       58
        
       

     

       51
       59
        
         <para>

     

       52
       52
       -
          The private key <filename>key.pem</filename> and certificate <filename>fullchain.pem</filename> will be put into <filename>/var/lib/acme/foo.example.com</filename>.

     

       60
       60
       +
          The private key <filename>key.pem</filename> and certificate

     

       61
       61
       +
          <filename>fullchain.pem</filename> will be put into

     

       62
       62
       +
          <filename>/var/lib/acme/foo.example.com</filename>.

     

       53
       63
        
         </para>

     

       54
       54
       -
       

     

       55
       64
        
         <para>

     

       56
       56
       -
          Refer to <xref linkend="ch-options" /> for all available configuration options for the <link linkend="opt-security.acme.certs">security.acme</link> module.

     

       65
       65
       +
          Refer to <xref linkend="ch-options" /> for all available configuration

     

       66
       66
       +
          options for the <link linkend="opt-security.acme.certs">security.acme</link>

     

       67
       67
       +
          module.

     

       57
       68
        
         </para>

     

       58
       69
        
        </section>

     

       59
       70
        
        <section xml:id="module-security-acme-nginx">

     

       60
       71
        
         <title>Using ACME certificates in Nginx</title>

     

       61
       72
        
       

     

       62
       73
        
         <para>

     

       63
       63
       -
          NixOS supports fetching ACME certificates for you by setting <literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;</literal> in a virtualHost config. We first create self-signed placeholder certificates in place of the real ACME certs. The placeholder certs are overwritten when the ACME certs arrive. For <literal>foo.example.com</literal> the config would look like.

     

       74
       74
       +
          NixOS supports fetching ACME certificates for you by setting

     

       75
       75
       +
          <literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link>

     

       76
       76
       +
          = true;</literal> in a virtualHost config. We first create self-signed

     

       77
       77
       +
          placeholder certificates in place of the real ACME certs. The placeholder

     

       78
       78
       +
          certs are overwritten when the ACME certs arrive. For

     

       79
       79
       +
          <literal>foo.example.com</literal> the config would look like.

     

       64
       80
        
         </para>

     

       65
       81
        
       

     

       66
       82
        
       <programlisting>

+8 -3

nixos/modules/security/hidepid.xml

···

       9
       9
        
       <programlisting>

     

       10
       10
        
       <xref linkend="opt-security.hideProcessInformation"/> = true;

     

       11
       11
        
       </programlisting>

     

       12
       12
       -
         ensures that access to process information is restricted to the owning user. This implies, among other things, that command-line arguments remain private. Unless your deployment relies on unprivileged users being able to inspect the process information of other users, this option should be safe to enable.

     

       12
       12
       +
         ensures that access to process information is restricted to the owning user.

     

       13
       13
       +
         This implies, among other things, that command-line arguments remain private.

     

       14
       14
       +
         Unless your deployment relies on unprivileged users being able to inspect the

     

       15
       15
       +
         process information of other users, this option should be safe to enable.

     

       13
       16
        
        </para>

     

       14
       17
        
        <para>

     

       15
       15
       -
         Members of the <literal>proc</literal> group are exempt from process information hiding.

     

       18
       18
       +
         Members of the <literal>proc</literal> group are exempt from process

     

       19
       19
       +
         information hiding.

     

       16
       20
        
        </para>

     

       17
       21
        
        <para>

     

       18
       18
       -
         To allow a service <replaceable>foo</replaceable> to run without process information hiding, set

     

       22
       22
       +
         To allow a service <replaceable>foo</replaceable> to run without process

     

       23
       23
       +
         information hiding, set

     

       19
       24
        
       <programlisting>

     

       20
       25
        
       <link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.<replaceable>foo</replaceable>.serviceConfig</link>.SupplementaryGroups = [ "proc" ];

     

       21
       26
        
       </programlisting>

+158 -39

nixos/modules/services/databases/foundationdb.xml

···

       5
       5
        
                xml:id="module-services-foundationdb">

     

       6
       6
        
        <title>FoundationDB</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         <emphasis>Source:</emphasis> <filename>modules/services/databases/foundationdb.nix</filename>

     

       8
       8
       +
         <emphasis>Source:</emphasis>

     

       9
       9
       +
         <filename>modules/services/databases/foundationdb.nix</filename>

     

       9
       10
        
        </para>

     

       10
       11
        
        <para>

     

       11
       11
       -
         <emphasis>Upstream documentation:</emphasis> <link xlink:href="https://apple.github.io/foundationdb/"/>

     

       12
       12
       +
         <emphasis>Upstream documentation:</emphasis>

     

       13
       13
       +
         <link xlink:href="https://apple.github.io/foundationdb/"/>

     

       12
       14
        
        </para>

     

       13
       15
        
        <para>

     

       14
       16
        
         <emphasis>Maintainer:</emphasis> Austin Seipp

     
···

       17
       19
        
         <emphasis>Available version(s):</emphasis> 5.1.x, 5.2.x, 6.0.x

     

       18
       20
        
        </para>

     

       19
       21
        
        <para>

     

       20
       20
       -
         FoundationDB (or "FDB") is an open source, distributed, transactional key-value store.

     

       22
       22
       +
         FoundationDB (or "FDB") is an open source, distributed, transactional

     

       23
       23
       +
         key-value store.

     

       21
       24
        
        </para>

     

       22
       25
        
        <section xml:id="module-services-foundationdb-configuring">

     

       23
       26
        
         <title>Configuring and basic setup</title>

     

       24
       27
        
       

     

       25
       28
        
         <para>

     

       26
       26
       -
          To enable FoundationDB, add the following to your <filename>configuration.nix</filename>:

     

       29
       29
       +
          To enable FoundationDB, add the following to your

     

       30
       30
       +
          <filename>configuration.nix</filename>:

     

       27
       31
        
       <programlisting>

     

       28
       32
        
       services.foundationdb.enable = true;

     

       29
       33
        
       services.foundationdb.package = pkgs.foundationdb52; # FoundationDB 5.2.x

     
···

       31
       35
        
         </para>

     

       32
       36
        
       

     

       33
       37
        
         <para>

     

       34
       34
       -
          The <option>services.foundationdb.package</option> option is required, and must always be specified. Due to the fact FoundationDB network protocols and on-disk storage formats may change between (major) versions, and upgrades must be explicitly handled by the user, you must always manually specify this yourself so that the NixOS module will use the proper version. Note that minor, bugfix releases are always compatible.

     

       38
       38
       +
          The <option>services.foundationdb.package</option> option is required, and

     

       39
       39
       +
          must always be specified. Due to the fact FoundationDB network protocols and

     

       40
       40
       +
          on-disk storage formats may change between (major) versions, and upgrades

     

       41
       41
       +
          must be explicitly handled by the user, you must always manually specify

     

       42
       42
       +
          this yourself so that the NixOS module will use the proper version. Note

     

       43
       43
       +
          that minor, bugfix releases are always compatible.

     

       35
       44
        
         </para>

     

       36
       45
        
       

     

       37
       46
        
         <para>

     

       38
       38
       -
          After running <command>nixos-rebuild</command>, you can verify whether FoundationDB is running by executing <command>fdbcli</command> (which is added to <option>environment.systemPackages</option>):

     

       47
       47
       +
          After running <command>nixos-rebuild</command>, you can verify whether

     

       48
       48
       +
          FoundationDB is running by executing <command>fdbcli</command> (which is

     

       49
       49
       +
          added to <option>environment.systemPackages</option>):

     

       39
       50
        
       <screen>

     

       40
       51
        
       <prompt>$ </prompt>sudo -u foundationdb fdbcli

     

       41
       52
        
       Using cluster file `/etc/foundationdb/fdb.cluster'.

     
···

       66
       77
        
         </para>

     

       67
       78
        
       

     

       68
       79
        
         <para>

     

       69
       69
       -
          You can also write programs using the available client libraries. For example, the following Python program can be run in order to grab the cluster status, as a quick example. (This example uses <command>nix-shell</command> shebang support to automatically supply the necessary Python modules).

     

       80
       80
       +
          You can also write programs using the available client libraries. For

     

       81
       81
       +
          example, the following Python program can be run in order to grab the

     

       82
       82
       +
          cluster status, as a quick example. (This example uses

     

       83
       83
       +
          <command>nix-shell</command> shebang support to automatically supply the

     

       84
       84
       +
          necessary Python modules).

     

       70
       85
        
       <screen>

     

       71
       86
        
       <prompt>a@link> </prompt>cat fdb-status.py

     

       72
       87
        
       #! /usr/bin/env nix-shell

     
···

       96
       111
        
         </para>

     

       97
       112
        
       

     

       98
       113
        
         <para>

     

       99
       99
       -
          FoundationDB is run under the <command>foundationdb</command> user and group by default, but this may be changed in the NixOS configuration. The systemd unit <command>foundationdb.service</command> controls the <command>fdbmonitor</command> process.

     

       114
       114
       +
          FoundationDB is run under the <command>foundationdb</command> user and group

     

       115
       115
       +
          by default, but this may be changed in the NixOS configuration. The systemd

     

       116
       116
       +
          unit <command>foundationdb.service</command> controls the

     

       117
       117
       +
          <command>fdbmonitor</command> process.

     

       100
       118
        
         </para>

     

       101
       119
        
       

     

       102
       120
        
         <para>

     

       103
       103
       -
          By default, the NixOS module for FoundationDB creates a single SSD-storage based database for development and basic usage. This storage engine is designed for SSDs and will perform poorly on HDDs; however it can handle far more data than the alternative "memory" engine and is a better default choice for most deployments. (Note that you can change the storage backend on-the-fly for a given FoundationDB cluster using <command>fdbcli</command>.)

     

       121
       121
       +
          By default, the NixOS module for FoundationDB creates a single SSD-storage

     

       122
       122
       +
          based database for development and basic usage. This storage engine is

     

       123
       123
       +
          designed for SSDs and will perform poorly on HDDs; however it can handle far

     

       124
       124
       +
          more data than the alternative "memory" engine and is a better default

     

       125
       125
       +
          choice for most deployments. (Note that you can change the storage backend

     

       126
       126
       +
          on-the-fly for a given FoundationDB cluster using

     

       127
       127
       +
          <command>fdbcli</command>.)

     

       104
       128
        
         </para>

     

       105
       129
        
       

     

       106
       130
        
         <para>

     

       107
       107
       -
          Furthermore, only 1 server process and 1 backup agent are started in the default configuration. See below for more on scaling to increase this.

     

       131
       131
       +
          Furthermore, only 1 server process and 1 backup agent are started in the

     

       132
       132
       +
          default configuration. See below for more on scaling to increase this.

     

       108
       133
        
         </para>

     

       109
       134
        
       

     

       110
       135
        
         <para>

     

       111
       111
       -
          FoundationDB stores all data for all server processes under <filename>/var/lib/foundationdb</filename>. You can override this using <option>services.foundationdb.dataDir</option>, e.g.

     

       136
       136
       +
          FoundationDB stores all data for all server processes under

     

       137
       137
       +
          <filename>/var/lib/foundationdb</filename>. You can override this using

     

       138
       138
       +
          <option>services.foundationdb.dataDir</option>, e.g.

     

       112
       139
        
       <programlisting>

     

       113
       140
        
       services.foundationdb.dataDir = "/data/fdb";

     

       114
       141
        
       </programlisting>

     

       115
       142
        
         </para>

     

       116
       143
        
       

     

       117
       144
        
         <para>

     

       118
       118
       -
          Similarly, logs are stored under <filename>/var/log/foundationdb</filename> by default, and there is a corresponding <option>services.foundationdb.logDir</option> as well.

     

       145
       145
       +
          Similarly, logs are stored under <filename>/var/log/foundationdb</filename>

     

       146
       146
       +
          by default, and there is a corresponding

     

       147
       147
       +
          <option>services.foundationdb.logDir</option> as well.

     

       119
       148
        
         </para>

     

       120
       149
        
        </section>

     

       121
       150
        
        <section xml:id="module-services-foundationdb-scaling">

     

       122
       151
        
         <title>Scaling processes and backup agents</title>

     

       123
       152
        
       

     

       124
       153
        
         <para>

     

       125
       125
       -
          Scaling the number of server processes is quite easy; simply specify <option>services.foundationdb.serverProcesses</option> to be the number of FoundationDB worker processes that should be started on the machine.

     

       154
       154
       +
          Scaling the number of server processes is quite easy; simply specify

     

       155
       155
       +
          <option>services.foundationdb.serverProcesses</option> to be the number of

     

       156
       156
       +
          FoundationDB worker processes that should be started on the machine.

     

       126
       157
        
         </para>

     

       127
       158
        
       

     

       128
       159
        
         <para>

     

       129
       129
       -
          FoundationDB worker processes typically require 4GB of RAM per-process at minimum for good performance, so this option is set to 1 by default since the maximum amount of RAM is unknown. You're advised to abide by this restriction, so pick a number of processes so that each has 4GB or more.

     

       160
       160
       +
          FoundationDB worker processes typically require 4GB of RAM per-process at

     

       161
       161
       +
          minimum for good performance, so this option is set to 1 by default since

     

       162
       162
       +
          the maximum amount of RAM is unknown. You're advised to abide by this

     

       163
       163
       +
          restriction, so pick a number of processes so that each has 4GB or more.

     

       130
       164
        
         </para>

     

       131
       165
        
       

     

       132
       166
        
         <para>

     

       133
       133
       -
          A similar option exists in order to scale backup agent processes, <option>services.foundationdb.backupProcesses</option>. Backup agents are not as performance/RAM sensitive, so feel free to experiment with the number of available backup processes.

     

       167
       167
       +
          A similar option exists in order to scale backup agent processes,

     

       168
       168
       +
          <option>services.foundationdb.backupProcesses</option>. Backup agents are

     

       169
       169
       +
          not as performance/RAM sensitive, so feel free to experiment with the number

     

       170
       170
       +
          of available backup processes.

     

       134
       171
        
         </para>

     

       135
       172
        
        </section>

     

       136
       173
        
        <section xml:id="module-services-foundationdb-clustering">

     

       137
       174
        
         <title>Clustering</title>

     

       138
       175
        
       

     

       139
       176
        
         <para>

     

       140
       140
       -
          FoundationDB on NixOS works similarly to other Linux systems, so this section will be brief. Please refer to the full FoundationDB documentation for more on clustering.

     

       177
       177
       +
          FoundationDB on NixOS works similarly to other Linux systems, so this

     

       178
       178
       +
          section will be brief. Please refer to the full FoundationDB documentation

     

       179
       179
       +
          for more on clustering.

     

       141
       180
        
         </para>

     

       142
       181
        
       

     

       143
       182
        
         <para>

     

       144
       144
       -
          FoundationDB organizes clusters using a set of <emphasis>coordinators</emphasis>, which are just specially-designated worker processes. By default, every installation of FoundationDB on NixOS will start as its own individual cluster, with a single coordinator: the first worker process on <command>localhost</command>.

     

       183
       183
       +
          FoundationDB organizes clusters using a set of

     

       184
       184
       +
          <emphasis>coordinators</emphasis>, which are just specially-designated

     

       185
       185
       +
          worker processes. By default, every installation of FoundationDB on NixOS

     

       186
       186
       +
          will start as its own individual cluster, with a single coordinator: the

     

       187
       187
       +
          first worker process on <command>localhost</command>.

     

       145
       188
        
         </para>

     

       146
       189
        
       

     

       147
       190
        
         <para>

     

       148
       148
       -
          Coordinators are specified globally using the <command>/etc/foundationdb/fdb.cluster</command> file, which all servers and client applications will use to find and join coordinators. Note that this file <emphasis>can not</emphasis> be managed by NixOS so easily: FoundationDB is designed so that it will rewrite the file at runtime for all clients and nodes when cluster coordinators change, with clients transparently handling this without intervention. It is fundamentally a mutable file, and you should not try to manage it in any way in NixOS.

     

       191
       191
       +
          Coordinators are specified globally using the

     

       192
       192
       +
          <command>/etc/foundationdb/fdb.cluster</command> file, which all servers and

     

       193
       193
       +
          client applications will use to find and join coordinators. Note that this

     

       194
       194
       +
          file <emphasis>can not</emphasis> be managed by NixOS so easily:

     

       195
       195
       +
          FoundationDB is designed so that it will rewrite the file at runtime for all

     

       196
       196
       +
          clients and nodes when cluster coordinators change, with clients

     

       197
       197
       +
          transparently handling this without intervention. It is fundamentally a

     

       198
       198
       +
          mutable file, and you should not try to manage it in any way in NixOS.

     

       149
       199
        
         </para>

     

       150
       200
        
       

     

       151
       201
        
         <para>

     
···

       166
       216
        
         </itemizedlist>

     

       167
       217
        
       

     

       168
       218
        
         <para>

     

       169
       169
       -
          A node must already be a member of the cluster in order to properly be promoted to a coordinator, so you must always add it first if you wish to promote it.

     

       219
       219
       +
          A node must already be a member of the cluster in order to properly be

     

       220
       220
       +
          promoted to a coordinator, so you must always add it first if you wish to

     

       221
       221
       +
          promote it.

     

       170
       222
        
         </para>

     

       171
       223
        
       

     

       172
       224
        
         <para>

     
···

       181
       233
        
          </listitem>

     

       182
       234
        
          <listitem>

     

       183
       235
        
           <para>

     

       184
       184
       -
            Copy the <command>/etc/foundationdb/fdb.cluster</command> file from this server to all the other servers. Restart FoundationDB on all of these other servers, so they join the cluster.

     

       236
       236
       +
            Copy the <command>/etc/foundationdb/fdb.cluster</command> file from this

     

       237
       237
       +
            server to all the other servers. Restart FoundationDB on all of these

     

       238
       238
       +
            other servers, so they join the cluster.

     

       185
       239
        
           </para>

     

       186
       240
        
          </listitem>

     

       187
       241
        
          <listitem>

     

       188
       242
        
           <para>

     

       189
       189
       -
            All of these servers are now connected and working together in the cluster, under the chosen coordinator.

     

       243
       243
       +
            All of these servers are now connected and working together in the

     

       244
       244
       +
            cluster, under the chosen coordinator.

     

       190
       245
        
           </para>

     

       191
       246
        
          </listitem>

     

       192
       247
        
         </itemizedlist>

     

       193
       248
        
       

     

       194
       249
        
         <para>

     

       195
       195
       -
          At this point, you can add as many nodes as you want by just repeating the above steps. By default there will still be a single coordinator: you can use <command>fdbcli</command> to change this and add new coordinators.

     

       250
       250
       +
          At this point, you can add as many nodes as you want by just repeating the

     

       251
       251
       +
          above steps. By default there will still be a single coordinator: you can

     

       252
       252
       +
          use <command>fdbcli</command> to change this and add new coordinators.

     

       196
       253
        
         </para>

     

       197
       254
        
       

     

       198
       255
        
         <para>

     

       199
       199
       -
          As a convenience, FoundationDB can automatically assign coordinators based on the redundancy mode you wish to achieve for the cluster. Once all the nodes have been joined, simply set the replication policy, and then issue the <command>coordinators auto</command> command

     

       256
       256
       +
          As a convenience, FoundationDB can automatically assign coordinators based

     

       257
       257
       +
          on the redundancy mode you wish to achieve for the cluster. Once all the

     

       258
       258
       +
          nodes have been joined, simply set the replication policy, and then issue

     

       259
       259
       +
          the <command>coordinators auto</command> command

     

       200
       260
        
         </para>

     

       201
       261
        
       

     

       202
       262
        
         <para>

     

       203
       203
       -
          For example, assuming we have 3 nodes available, we can enable double redundancy mode, then auto-select coordinators. For double redundancy, 3 coordinators is ideal: therefore FoundationDB will make <emphasis>every</emphasis> node a coordinator automatically:

     

       263
       263
       +
          For example, assuming we have 3 nodes available, we can enable double

     

       264
       264
       +
          redundancy mode, then auto-select coordinators. For double redundancy, 3

     

       265
       265
       +
          coordinators is ideal: therefore FoundationDB will make

     

       266
       266
       +
          <emphasis>every</emphasis> node a coordinator automatically:

     

       204
       267
        
         </para>

     

       205
       268
        
       

     

       206
       269
        
       <screen>

     
···

       209
       272
        
       </screen>

     

       210
       273
        
       

     

       211
       274
        
         <para>

     

       212
       212
       -
          This will transparently update all the servers within seconds, and appropriately rewrite the <command>fdb.cluster</command> file, as well as informing all client processes to do the same.

     

       275
       275
       +
          This will transparently update all the servers within seconds, and

     

       276
       276
       +
          appropriately rewrite the <command>fdb.cluster</command> file, as well as

     

       277
       277
       +
          informing all client processes to do the same.

     

       213
       278
        
         </para>

     

       214
       279
        
        </section>

     

       215
       280
        
        <section xml:id="module-services-foundationdb-connectivity">

     

       216
       281
        
         <title>Client connectivity</title>

     

       217
       282
        
       

     

       218
       283
        
         <para>

     

       219
       219
       -
          By default, all clients must use the current <command>fdb.cluster</command> file to access a given FoundationDB cluster. This file is located by default in <command>/etc/foundationdb/fdb.cluster</command> on all machines with the FoundationDB service enabled, so you may copy the active one from your cluster to a new node in order to connect, if it is not part of the cluster.

     

       284
       284
       +
          By default, all clients must use the current <command>fdb.cluster</command>

     

       285
       285
       +
          file to access a given FoundationDB cluster. This file is located by default

     

       286
       286
       +
          in <command>/etc/foundationdb/fdb.cluster</command> on all machines with the

     

       287
       287
       +
          FoundationDB service enabled, so you may copy the active one from your

     

       288
       288
       +
          cluster to a new node in order to connect, if it is not part of the cluster.

     

       220
       289
        
         </para>

     

       221
       290
        
        </section>

     

       222
       291
        
        <section xml:id="module-services-foundationdb-authorization">

     

       223
       292
        
         <title>Client authorization and TLS</title>

     

       224
       293
        
       

     

       225
       294
        
         <para>

     

       226
       226
       -
          By default, any user who can connect to a FoundationDB process with the correct cluster configuration can access anything. FoundationDB uses a pluggable design to transport security, and out of the box it supports a LibreSSL-based plugin for TLS support. This plugin not only does in-flight encryption, but also performs client authorization based on the given endpoint's certificate chain. For example, a FoundationDB server may be configured to only accept client connections over TLS, where the client TLS certificate is from organization <emphasis>Acme Co</emphasis> in the <emphasis>Research and Development</emphasis> unit.

     

       295
       295
       +
          By default, any user who can connect to a FoundationDB process with the

     

       296
       296
       +
          correct cluster configuration can access anything. FoundationDB uses a

     

       297
       297
       +
          pluggable design to transport security, and out of the box it supports a

     

       298
       298
       +
          LibreSSL-based plugin for TLS support. This plugin not only does in-flight

     

       299
       299
       +
          encryption, but also performs client authorization based on the given

     

       300
       300
       +
          endpoint's certificate chain. For example, a FoundationDB server may be

     

       301
       301
       +
          configured to only accept client connections over TLS, where the client TLS

     

       302
       302
       +
          certificate is from organization <emphasis>Acme Co</emphasis> in the

     

       303
       303
       +
          <emphasis>Research and Development</emphasis> unit.

     

       227
       304
        
         </para>

     

       228
       305
        
       

     

       229
       306
        
         <para>

     

       230
       230
       -
          Configuring TLS with FoundationDB is done using the <option>services.foundationdb.tls</option> options in order to control the peer verification string, as well as the certificate and its private key.

     

       307
       307
       +
          Configuring TLS with FoundationDB is done using the

     

       308
       308
       +
          <option>services.foundationdb.tls</option> options in order to control the

     

       309
       309
       +
          peer verification string, as well as the certificate and its private key.

     

       231
       310
        
         </para>

     

       232
       311
        
       

     

       233
       312
        
         <para>

     

       234
       234
       -
          Note that the certificate and its private key must be accessible to the FoundationDB user account that the server runs under. These files are also NOT managed by NixOS, as putting them into the store may reveal private information.

     

       313
       313
       +
          Note that the certificate and its private key must be accessible to the

     

       314
       314
       +
          FoundationDB user account that the server runs under. These files are also

     

       315
       315
       +
          NOT managed by NixOS, as putting them into the store may reveal private

     

       316
       316
       +
          information.

     

       235
       317
        
         </para>

     

       236
       318
        
       

     

       237
       319
        
         <para>

     

       238
       238
       -
          After you have a key and certificate file in place, it is not enough to simply set the NixOS module options -- you must also configure the <command>fdb.cluster</command> file to specify that a given set of coordinators use TLS. This is as simple as adding the suffix <command>:tls</command> to your cluster coordinator configuration, after the port number. For example, assuming you have a coordinator on localhost with the default configuration, simply specifying:

     

       320
       320
       +
          After you have a key and certificate file in place, it is not enough to

     

       321
       321
       +
          simply set the NixOS module options -- you must also configure the

     

       322
       322
       +
          <command>fdb.cluster</command> file to specify that a given set of

     

       323
       323
       +
          coordinators use TLS. This is as simple as adding the suffix

     

       324
       324
       +
          <command>:tls</command> to your cluster coordinator configuration, after the

     

       325
       325
       +
          port number. For example, assuming you have a coordinator on localhost with

     

       326
       326
       +
          the default configuration, simply specifying:

     

       239
       327
        
         </para>

     

       240
       328
        
       

     

       241
       329
        
       <programlisting>

     
···

       250
       338
        
         <title>Backups and Disaster Recovery</title>

     

       251
       339
        
       

     

       252
       340
        
         <para>

     

       253
       253
       -
          The usual rules for doing FoundationDB backups apply on NixOS as written in the FoundationDB manual. However, one important difference is the security profile for NixOS: by default, the <command>foundationdb</command> systemd unit uses <emphasis>Linux namespaces</emphasis> to restrict write access to the system, except for the log directory, data directory, and the <command>/etc/foundationdb/</command> directory. This is enforced by default and cannot be disabled.

     

       341
       341
       +
          The usual rules for doing FoundationDB backups apply on NixOS as written in

     

       342
       342
       +
          the FoundationDB manual. However, one important difference is the security

     

       343
       343
       +
          profile for NixOS: by default, the <command>foundationdb</command> systemd

     

       344
       344
       +
          unit uses <emphasis>Linux namespaces</emphasis> to restrict write access to

     

       345
       345
       +
          the system, except for the log directory, data directory, and the

     

       346
       346
       +
          <command>/etc/foundationdb/</command> directory. This is enforced by default

     

       347
       347
       +
          and cannot be disabled.

     

       254
       348
        
         </para>

     

       255
       349
        
       

     

       256
       350
        
         <para>

     

       257
       257
       -
          However, a side effect of this is that the <command>fdbbackup</command> command doesn't work properly for local filesystem backups: FoundationDB uses a server process alongside the database processes to perform backups and copy the backups to the filesystem. As a result, this process is put under the restricted namespaces above: the backup process can only write to a limited number of paths.

     

       351
       351
       +
          However, a side effect of this is that the <command>fdbbackup</command>

     

       352
       352
       +
          command doesn't work properly for local filesystem backups: FoundationDB

     

       353
       353
       +
          uses a server process alongside the database processes to perform backups

     

       354
       354
       +
          and copy the backups to the filesystem. As a result, this process is put

     

       355
       355
       +
          under the restricted namespaces above: the backup process can only write to

     

       356
       356
       +
          a limited number of paths.

     

       258
       357
        
         </para>

     

       259
       358
        
       

     

       260
       359
        
         <para>

     

       261
       261
       -
          In order to allow flexible backup locations on local disks, the FoundationDB NixOS module supports a <option>services.foundationdb.extraReadWritePaths</option> option. This option takes a list of paths, and adds them to the systemd unit, allowing the processes inside the service to write (and read) the specified directories.

     

       360
       360
       +
          In order to allow flexible backup locations on local disks, the FoundationDB

     

       361
       361
       +
          NixOS module supports a

     

       362
       362
       +
          <option>services.foundationdb.extraReadWritePaths</option> option. This

     

       363
       363
       +
          option takes a list of paths, and adds them to the systemd unit, allowing

     

       364
       364
       +
          the processes inside the service to write (and read) the specified

     

       365
       365
       +
          directories.

     

       262
       366
        
         </para>

     

       263
       367
        
       

     

       264
       368
        
         <para>

     

       265
       265
       -
          For example, to create backups in <command>/opt/fdb-backups</command>, first set up the paths in the module options:

     

       369
       369
       +
          For example, to create backups in <command>/opt/fdb-backups</command>, first

     

       370
       370
       +
          set up the paths in the module options:

     

       266
       371
        
         </para>

     

       267
       372
        
       

     

       268
       373
        
       <programlisting>

     
···

       270
       375
        
       </programlisting>

     

       271
       376
        
       

     

       272
       377
        
         <para>

     

       273
       273
       -
          Restart the FoundationDB service, and it will now be able to write to this directory (even if it does not yet exist.) Note: this path <emphasis>must</emphasis> exist before restarting the unit. Otherwise, systemd will not include it in the private FoundationDB namespace (and it will not add it dynamically at runtime).

     

       378
       378
       +
          Restart the FoundationDB service, and it will now be able to write to this

     

       379
       379
       +
          directory (even if it does not yet exist.) Note: this path

     

       380
       380
       +
          <emphasis>must</emphasis> exist before restarting the unit. Otherwise,

     

       381
       381
       +
          systemd will not include it in the private FoundationDB namespace (and it

     

       382
       382
       +
          will not add it dynamically at runtime).

     

       274
       383
        
         </para>

     

       275
       384
        
       

     

       276
       385
        
         <para>

     
···

       286
       395
        
         <title>Known limitations</title>

     

       287
       396
        
       

     

       288
       397
        
         <para>

     

       289
       289
       -
          The FoundationDB setup for NixOS should currently be considered beta. FoundationDB is not new software, but the NixOS compilation and integration has only undergone fairly basic testing of all the available functionality.

     

       398
       398
       +
          The FoundationDB setup for NixOS should currently be considered beta.

     

       399
       399
       +
          FoundationDB is not new software, but the NixOS compilation and integration

     

       400
       400
       +
          has only undergone fairly basic testing of all the available functionality.

     

       290
       401
        
         </para>

     

       291
       402
        
       

     

       292
       403
        
         <itemizedlist>

     

       293
       404
        
          <listitem>

     

       294
       405
        
           <para>

     

       295
       295
       -
            There is no way to specify individual parameters for individual <command>fdbserver</command> processes. Currently, all server processes inherit all the global <command>fdbmonitor</command> settings.

     

       406
       406
       +
            There is no way to specify individual parameters for individual

     

       407
       407
       +
            <command>fdbserver</command> processes. Currently, all server processes

     

       408
       408
       +
            inherit all the global <command>fdbmonitor</command> settings.

     

       296
       409
        
           </para>

     

       297
       410
        
          </listitem>

     

       298
       411
        
          <listitem>

     
···

       311
       424
        
         <title>Options</title>

     

       312
       425
        
       

     

       313
       426
        
         <para>

     

       314
       314
       -
          NixOS's FoundationDB module allows you to configure all of the most relevant configuration options for <command>fdbmonitor</command>, matching it quite closely. A complete list of options for the FoundationDB module may be found <link linkend="opt-services.foundationdb.enable">here</link>. You should also read the FoundationDB documentation as well.

     

       427
       427
       +
          NixOS's FoundationDB module allows you to configure all of the most relevant

     

       428
       428
       +
          configuration options for <command>fdbmonitor</command>, matching it quite

     

       429
       429
       +
          closely. A complete list of options for the FoundationDB module may be found

     

       430
       430
       +
          <link linkend="opt-services.foundationdb.enable">here</link>. You should

     

       431
       431
       +
          also read the FoundationDB documentation as well.

     

       315
       432
        
         </para>

     

       316
       433
        
        </section>

     

       317
       434
        
        <section xml:id="module-services-foundationdb-full-docs">

     

       318
       435
        
         <title>Full documentation</title>

     

       319
       436
        
       

     

       320
       437
        
         <para>

     

       321
       321
       -
          FoundationDB is a complex piece of software, and requires careful administration to properly use. Full documentation for administration can be found here: <link xlink:href="https://apple.github.io/foundationdb/"/>.

     

       438
       438
       +
          FoundationDB is a complex piece of software, and requires careful

     

       439
       439
       +
          administration to properly use. Full documentation for administration can be

     

       440
       440
       +
          found here: <link xlink:href="https://apple.github.io/foundationdb/"/>.

     

       322
       441
        
         </para>

     

       323
       442
        
        </section>

     

       324
       443
        
       </chapter>

+26 -13

nixos/modules/services/databases/postgresql.xml

···

       7
       7
        
       <!-- FIXME: render nicely -->

     

       8
       8
        
       <!-- FIXME: source can be added automatically -->

     

       9
       9
        
        <para>

     

       10
       10
       -
         <emphasis>Source:</emphasis> <filename>modules/services/databases/postgresql.nix</filename>

     

       10
       10
       +
         <emphasis>Source:</emphasis>

     

       11
       11
       +
         <filename>modules/services/databases/postgresql.nix</filename>

     

       11
       12
        
        </para>

     

       12
       13
        
        <para>

     

       13
       13
       -
         <emphasis>Upstream documentation:</emphasis> <link xlink:href="http://www.postgresql.org/docs/"/>

     

       14
       14
       +
         <emphasis>Upstream documentation:</emphasis>

     

       15
       15
       +
         <link xlink:href="http://www.postgresql.org/docs/"/>

     

       14
       16
        
        </para>

     

       15
       17
        
       <!-- FIXME: more stuff, like maintainer? -->

     

       16
       18
        
        <para>

     
···

       21
       23
        
         <title>Configuring</title>

     

       22
       24
        
       

     

       23
       25
        
         <para>

     

       24
       24
       -
          To enable PostgreSQL, add the following to your <filename>configuration.nix</filename>:

     

       26
       26
       +
          To enable PostgreSQL, add the following to your

     

       27
       27
       +
          <filename>configuration.nix</filename>:

     

       25
       28
        
       <programlisting>

     

       26
       29
        
       <xref linkend="opt-services.postgresql.enable"/> = true;

     

       27
       30
        
       <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;

     

       28
       31
        
       </programlisting>

     

       29
       29
       -
          Note that you are required to specify the desired version of PostgreSQL (e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for <xref linkend="opt-services.postgresql.package"/> such as the most recent release of PostgreSQL.

     

       32
       32
       +
          Note that you are required to specify the desired version of PostgreSQL

     

       33
       33
       +
          (e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your

     

       34
       34
       +
          PostgreSQL version requires a database dump and reload (see below), NixOS

     

       35
       35
       +
          cannot provide a default value for

     

       36
       36
       +
          <xref linkend="opt-services.postgresql.package"/> such as the most recent

     

       37
       37
       +
          release of PostgreSQL.

     

       30
       38
        
         </para>

     

       31
       39
        
       

     

       32
       40
        
       <!--

     
···

       43
       51
        
       -->

     

       44
       52
        
       

     

       45
       53
        
         <para>

     

       46
       46
       -
          By default, PostgreSQL stores its databases in <filename>/var/lib/postgresql/$psqlSchema</filename>. You can override this using <xref linkend="opt-services.postgresql.dataDir"/>, e.g.

     

       54
       54
       +
          By default, PostgreSQL stores its databases in

     

       55
       55
       +
          <filename>/var/lib/postgresql/$psqlSchema</filename>. You can override this using

     

       56
       56
       +
          <xref linkend="opt-services.postgresql.dataDir"/>, e.g.

     

       47
       57
        
       <programlisting>

     

       48
       58
        
       <xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql";

     

       49
       59
        
       </programlisting>

     
···

       60
       70
        
         <title>Options</title>

     

       61
       71
        
       

     

       62
       72
        
         <para>

     

       63
       63
       -
          A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>.

     

       73
       73
       +
          A complete list of options for the PostgreSQL module may be found

     

       74
       74
       +
          <link linkend="opt-services.postgresql.enable">here</link>.

     

       64
       75
        
         </para>

     

       65
       76
        
        </section>

     

       66
       77
        
        <section xml:id="module-services-postgres-plugins">

     

       67
       78
        
         <title>Plugins</title>

     

       68
       79
        
       

     

       69
       80
        
         <para>

     

       70
       70
       -
          Plugins collection for each PostgreSQL version can be accessed with <literal>.pkgs</literal>. For example, for <literal>pkgs.postgresql_11</literal> package, its plugin collection is accessed by <literal>pkgs.postgresql_11.pkgs</literal>:

     

       81
       81
       +
          Plugins collection for each PostgreSQL version can be accessed with

     

       82
       82
       +
          <literal>.pkgs</literal>. For example, for

     

       83
       83
       +
          <literal>pkgs.postgresql_11</literal> package, its plugin collection is

     

       84
       84
       +
          accessed by <literal>pkgs.postgresql_11.pkgs</literal>:

     

       71
       85
        
       <screen>

     

       72
       86
        
       <prompt>$ </prompt>nix repl '&lt;nixpkgs&gt;'

     

       73
       87
        
       

     
···

       84
       98
        
       ...

     

       85
       99
        
       </screen>

     

       86
       100
        
         </para>

     

       87
       87
       -
       

     

       88
       101
        
         <para>

     

       89
       89
       -
          To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:

     

       102
       102
       +
           To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:

     

       90
       103
        
       <programlisting>

     

       91
       104
        
       <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;

     

       92
       105
        
       <xref linkend="opt-services.postgresql.extraPlugins"/> = with pkgs.postgresql_11.pkgs; [

     
···

       95
       108
        
       ];

     

       96
       109
        
       </programlisting>

     

       97
       110
        
         </para>

     

       98
       98
       -
       

     

       99
       111
        
         <para>

     

       100
       100
       -
          You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using function <literal>.withPackages</literal>. For example, creating a custom PostgreSQL package in an overlay can look like:

     

       112
       112
       +
          You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using

     

       113
       113
       +
          function <literal>.withPackages</literal>. For example, creating a custom

     

       114
       114
       +
          PostgreSQL package in an overlay can look like:

     

       101
       115
        
       <programlisting>

     

       102
       116
        
       self: super: {

     

       103
       117
        
         postgresql_custom = self.postgresql_11.withPackages (ps: [

     
···

       107
       121
        
       }

     

       108
       122
        
       </programlisting>

     

       109
       123
        
         </para>

     

       110
       110
       -
       

     

       111
       124
        
         <para>

     

       112
       112
       -
          Here's a recipe on how to override a particular plugin through an overlay:

     

       125
       125
       +
           Here's a recipe on how to override a particular plugin through an overlay:

     

       113
       126
        
       <programlisting>

     

       114
       127
        
       self: super: {

     

       115
       128
        
         postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {

+18 -7

nixos/modules/services/desktops/flatpak.xml

···

       5
       5
        
                xml:id="module-services-flatpak">

     

       6
       6
        
        <title>Flatpak</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         <emphasis>Source:</emphasis> <filename>modules/services/desktop/flatpak.nix</filename>

     

       8
       8
       +
         <emphasis>Source:</emphasis>

     

       9
       9
       +
         <filename>modules/services/desktop/flatpak.nix</filename>

     

       9
       10
        
        </para>

     

       10
       11
        
        <para>

     

       11
       11
       -
         <emphasis>Upstream documentation:</emphasis> <link xlink:href="https://github.com/flatpak/flatpak/wiki"/>

     

       12
       12
       +
         <emphasis>Upstream documentation:</emphasis>

     

       13
       13
       +
         <link xlink:href="https://github.com/flatpak/flatpak/wiki"/>

     

       12
       14
        
        </para>

     

       13
       15
        
        <para>

     

       14
       14
       -
         Flatpak is a system for building, distributing, and running sandboxed desktop applications on Linux.

     

       16
       16
       +
         Flatpak is a system for building, distributing, and running sandboxed desktop

     

       17
       17
       +
         applications on Linux.

     

       15
       18
        
        </para>

     

       16
       19
        
        <para>

     

       17
       17
       -
         To enable Flatpak, add the following to your <filename>configuration.nix</filename>:

     

       20
       20
       +
         To enable Flatpak, add the following to your

     

       21
       21
       +
         <filename>configuration.nix</filename>:

     

       18
       22
        
       <programlisting>

     

       19
       23
        
         <xref linkend="opt-services.flatpak.enable"/> = true;

     

       20
       24
        
       </programlisting>

     

       21
       25
        
        </para>

     

       22
       26
        
        <para>

     

       23
       23
       -
         For the sandboxed apps to work correctly, desktop integration portals need to be installed. If you run GNOME, this will be handled automatically for you; in other cases, you will need to add something like the following to your <filename>configuration.nix</filename>:

     

       27
       27
       +
         For the sandboxed apps to work correctly, desktop integration portals need to

     

       28
       28
       +
         be installed. If you run GNOME, this will be handled automatically for you;

     

       29
       29
       +
         in other cases, you will need to add something like the following to your

     

       30
       30
       +
         <filename>configuration.nix</filename>:

     

       24
       31
        
       <programlisting>

     

       25
       32
        
         <xref linkend="opt-xdg.portal.extraPortals"/> = [ pkgs.xdg-desktop-portal-gtk ];

     

       26
       33
        
       </programlisting>

     

       27
       34
        
        </para>

     

       28
       35
        
        <para>

     

       29
       29
       -
         Then, you will need to add a repository, for example, <link xlink:href="https://github.com/flatpak/flatpak/wiki">Flathub</link>, either using the following commands:

     

       36
       36
       +
         Then, you will need to add a repository, for example,

     

       37
       37
       +
         <link xlink:href="https://github.com/flatpak/flatpak/wiki">Flathub</link>,

     

       38
       38
       +
         either using the following commands:

     

       30
       39
        
       <screen>

     

       31
       40
        
       <prompt>$ </prompt>flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

     

       32
       41
        
       <prompt>$ </prompt>flatpak update

     

       33
       42
        
       </screen>

     

       34
       34
       -
         or by opening the <link xlink:href="https://flathub.org/repo/flathub.flatpakrepo">repository file</link> in GNOME Software.

     

       43
       43
       +
         or by opening the

     

       44
       44
       +
         <link xlink:href="https://flathub.org/repo/flathub.flatpakrepo">repository

     

       45
       45
       +
         file</link> in GNOME Software.

     

       35
       46
        
        </para>

     

       36
       47
        
        <para>

     

       37
       48
        
         Finally, you can search and install programs:

+170 -51

nixos/modules/services/editors/emacs.xml

···

       12
       12
        
             Adam Hoese @adisbladis

     

       13
       13
        
         -->

     

       14
       14
        
        <para>

     

       15
       15
       -
         <link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> is an extensible, customizable, self-documenting real-time display editor — and more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp programming language with extensions to support text editing.

     

       15
       15
       +
         <link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> is an

     

       16
       16
       +
         extensible, customizable, self-documenting real-time display editor — and

     

       17
       17
       +
         more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp

     

       18
       18
       +
         programming language with extensions to support text editing.

     

       16
       19
        
        </para>

     

       17
       20
        
        <para>

     

       18
       18
       -
         Emacs runs within a graphical desktop environment using the X Window System, but works equally well on a text terminal. Under <productname>macOS</productname>, a "Mac port" edition is available, which uses Apple's native GUI frameworks.

     

       21
       21
       +
         Emacs runs within a graphical desktop environment using the X Window System,

     

       22
       22
       +
         but works equally well on a text terminal. Under

     

       23
       23
       +
         <productname>macOS</productname>, a "Mac port" edition is available, which

     

       24
       24
       +
         uses Apple's native GUI frameworks.

     

       19
       25
        
        </para>

     

       20
       26
        
        <para>

     

       21
       21
       -
         <productname>Nixpkgs</productname> provides a superior environment for running <application>Emacs</application>. It's simple to create custom builds by overriding the default packages. Chaotic collections of Emacs Lisp code and extensions can be brought under control using declarative package management. <productname>NixOS</productname> even provides a <command>systemd</command> user service for automatically starting the Emacs daemon.

     

       27
       27
       +
         <productname>Nixpkgs</productname> provides a superior environment for

     

       28
       28
       +
         running <application>Emacs</application>. It's simple to create custom builds

     

       29
       29
       +
         by overriding the default packages. Chaotic collections of Emacs Lisp code

     

       30
       30
       +
         and extensions can be brought under control using declarative package

     

       31
       31
       +
         management. <productname>NixOS</productname> even provides a

     

       32
       32
       +
         <command>systemd</command> user service for automatically starting the Emacs

     

       33
       33
       +
         daemon.

     

       22
       34
        
        </para>

     

       23
       35
        
        <section xml:id="module-services-emacs-installing">

     

       24
       36
        
         <title>Installing <application>Emacs</application></title>

     

       25
       37
        
       

     

       26
       38
        
         <para>

     

       27
       27
       -
          Emacs can be installed in the normal way for Nix (see <xref linkend="sec-package-management" />). In addition, a NixOS <emphasis>service</emphasis> can be enabled.

     

       39
       39
       +
          Emacs can be installed in the normal way for Nix (see

     

       40
       40
       +
          <xref linkend="sec-package-management" />). In addition, a NixOS

     

       41
       41
       +
          <emphasis>service</emphasis> can be enabled.

     

       28
       42
        
         </para>

     

       29
       43
        
       

     

       30
       44
        
         <section xml:id="module-services-emacs-releases">

     

       31
       45
        
          <title>The Different Releases of Emacs</title>

     

       32
       46
        
       

     

       33
       47
        
          <para>

     

       34
       34
       -
           <productname>Nixpkgs</productname> defines several basic Emacs packages. The following are attributes belonging to the <varname>pkgs</varname> set:

     

       48
       48
       +
           <productname>Nixpkgs</productname> defines several basic Emacs packages.

     

       49
       49
       +
           The following are attributes belonging to the <varname>pkgs</varname> set:

     

       35
       50
        
           <variablelist>

     

       36
       51
        
            <varlistentry>

     

       37
       52
        
             <term>

     
···

       42
       57
        
             </term>

     

       43
       58
        
             <listitem>

     

       44
       59
        
              <para>

     

       45
       45
       -
               The latest stable version of Emacs 25 using the <link

     

       46
       46
       -
                       xlink:href="http://www.gtk.org">GTK 2</link> widget toolkit.

     

       60
       60
       +
               The latest stable version of Emacs 25 using the

     

       61
       61
       +
               <link

     

       62
       62
       +
                       xlink:href="http://www.gtk.org">GTK 2</link>

     

       63
       63
       +
               widget toolkit.

     

       47
       64
        
              </para>

     

       48
       65
        
             </listitem>

     

       49
       66
        
            </varlistentry>

     
···

       66
       83
        
             </term>

     

       67
       84
        
             <listitem>

     

       68
       85
        
              <para>

     

       69
       69
       -
               Emacs 25 with the "Mac port" patches, providing a more native look and feel under macOS.

     

       86
       86
       +
               Emacs 25 with the "Mac port" patches, providing a more native look and

     

       87
       87
       +
               feel under macOS.

     

       70
       88
        
              </para>

     

       71
       89
        
             </listitem>

     

       72
       90
        
            </varlistentry>

     
···

       74
       92
        
          </para>

     

       75
       93
        
       

     

       76
       94
        
          <para>

     

       77
       77
       -
           If those aren't suitable, then the following imitation Emacs editors are also available in Nixpkgs: <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>, <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>, <link xlink:href="http://yi-editor.github.io/">Yi</link>, <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>.

     

       95
       95
       +
           If those aren't suitable, then the following imitation Emacs editors are

     

       96
       96
       +
           also available in Nixpkgs:

     

       97
       97
       +
           <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>,

     

       98
       98
       +
           <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>,

     

       99
       99
       +
           <link xlink:href="http://yi-editor.github.io/">Yi</link>,

     

       100
       100
       +
           <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>.

     

       78
       101
        
          </para>

     

       79
       102
        
         </section>

     

       80
       103
        
       

     
···

       82
       105
        
          <title>Adding Packages to Emacs</title>

     

       83
       106
        
       

     

       84
       107
        
          <para>

     

       85
       85
       -
           Emacs includes an entire ecosystem of functionality beyond text editing, including a project planner, mail and news reader, debugger interface, calendar, and more.

     

       108
       108
       +
           Emacs includes an entire ecosystem of functionality beyond text editing,

     

       109
       109
       +
           including a project planner, mail and news reader, debugger interface,

     

       110
       110
       +
           calendar, and more.

     

       86
       111
        
          </para>

     

       87
       112
        
       

     

       88
       113
        
          <para>

     

       89
       89
       -
           Most extensions are gotten with the Emacs packaging system (<filename>package.el</filename>) from <link

     

       90
       90
       -
               xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive (<acronym>ELPA</acronym>)</link>, <link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>, <link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is regularly updated to mirror all these archives.

     

       114
       114
       +
           Most extensions are gotten with the Emacs packaging system

     

       115
       115
       +
           (<filename>package.el</filename>) from

     

       116
       116
       +
           <link

     

       117
       117
       +
               xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive

     

       118
       118
       +
           (<acronym>ELPA</acronym>)</link>,

     

       119
       119
       +
           <link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>,

     

       120
       120
       +
           <link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and

     

       121
       121
       +
           <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is

     

       122
       122
       +
           regularly updated to mirror all these archives.

     

       91
       123
        
          </para>

     

       92
       124
        
       

     

       93
       125
        
          <para>

     

       94
       94
       -
           Under NixOS, you can continue to use <function>package-list-packages</function> and <function>package-install</function> to install packages. You can also declare the set of Emacs packages you need using the derivations from Nixpkgs. The rest of this section discusses declarative installation of Emacs packages through nixpkgs.

     

       126
       126
       +
           Under NixOS, you can continue to use

     

       127
       127
       +
           <function>package-list-packages</function> and

     

       128
       128
       +
           <function>package-install</function> to install packages. You can also

     

       129
       129
       +
           declare the set of Emacs packages you need using the derivations from

     

       130
       130
       +
           Nixpkgs. The rest of this section discusses declarative installation of

     

       131
       131
       +
           Emacs packages through nixpkgs.

     

       95
       132
        
          </para>

     

       96
       133
        
       

     

       97
       134
        
          <para>

     

       98
       98
       -
           The first step to declare the list of packages you want in your Emacs installation is to create a dedicated derivation. This can be done in a dedicated <filename>emacs.nix</filename> file such as:

     

       135
       135
       +
           The first step to declare the list of packages you want in your Emacs

     

       136
       136
       +
           installation is to create a dedicated derivation. This can be done in a

     

       137
       137
       +
           dedicated <filename>emacs.nix</filename> file such as:

     

       99
       138
        
           <example xml:id="ex-emacsNix">

     

       100
       139
        
            <title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>

     

       101
       140
        
       <programlisting language="nix">

     
···

       137
       176
        
           <calloutlist>

     

       138
       177
        
            <callout arearefs="ex-emacsNix-1">

     

       139
       178
        
             <para>

     

       140
       140
       -
              The first non-comment line in this file (<literal>{ pkgs ? ... }</literal>) indicates that the whole file represents a function.

     

       179
       179
       +
              The first non-comment line in this file (<literal>{ pkgs ? ...

     

       180
       180
       +
              }</literal>) indicates that the whole file represents a function.

     

       141
       181
        
             </para>

     

       142
       182
        
            </callout>

     

       143
       183
        
            <callout arearefs="ex-emacsNix-2">

     

       144
       184
        
             <para>

     

       145
       145
       -
              The <varname>let</varname> expression below defines a <varname>myEmacs</varname> binding pointing to the current stable version of Emacs. This binding is here to separate the choice of the Emacs binary from the specification of the required packages.

     

       185
       185
       +
              The <varname>let</varname> expression below defines a

     

       186
       186
       +
              <varname>myEmacs</varname> binding pointing to the current stable

     

       187
       187
       +
              version of Emacs. This binding is here to separate the choice of the

     

       188
       188
       +
              Emacs binary from the specification of the required packages.

     

       146
       189
        
             </para>

     

       147
       190
        
            </callout>

     

       148
       191
        
            <callout arearefs="ex-emacsNix-3">

     

       149
       192
        
             <para>

     

       150
       150
       -
              This generates an <varname>emacsWithPackages</varname> function. It takes a single argument: a function from a package set to a list of packages (the packages that will be available in Emacs).

     

       193
       193
       +
              This generates an <varname>emacsWithPackages</varname> function. It

     

       194
       194
       +
              takes a single argument: a function from a package set to a list of

     

       195
       195
       +
              packages (the packages that will be available in Emacs).

     

       151
       196
        
             </para>

     

       152
       197
        
            </callout>

     

       153
       198
        
            <callout arearefs="ex-emacsNix-4">

     

       154
       199
        
             <para>

     

       155
       155
       -
              The rest of the file specifies the list of packages to install. In the example, two packages (<varname>magit</varname> and <varname>zerodark-theme</varname>) are taken from MELPA stable.

     

       200
       200
       +
              The rest of the file specifies the list of packages to install. In the

     

       201
       201
       +
              example, two packages (<varname>magit</varname> and

     

       202
       202
       +
              <varname>zerodark-theme</varname>) are taken from MELPA stable.

     

       156
       203
        
             </para>

     

       157
       204
        
            </callout>

     

       158
       205
        
            <callout arearefs="ex-emacsNix-5">

     

       159
       206
        
             <para>

     

       160
       160
       -
              Two packages (<varname>undo-tree</varname> and <varname>zoom-frm</varname>) are taken from MELPA.

     

       207
       207
       +
              Two packages (<varname>undo-tree</varname> and

     

       208
       208
       +
              <varname>zoom-frm</varname>) are taken from MELPA.

     

       161
       209
        
             </para>

     

       162
       210
        
            </callout>

     

       163
       211
        
            <callout arearefs="ex-emacsNix-6">

     
···

       167
       215
        
            </callout>

     

       168
       216
        
            <callout arearefs="ex-emacsNix-7">

     

       169
       217
        
             <para>

     

       170
       170
       -
              <varname>notmuch</varname> is taken from a nixpkgs derivation which contains an Emacs mode.

     

       218
       218
       +
              <varname>notmuch</varname> is taken from a nixpkgs derivation which

     

       219
       219
       +
              contains an Emacs mode.

     

       171
       220
        
             </para>

     

       172
       221
        
            </callout>

     

       173
       222
        
           </calloutlist>

     

       174
       223
        
          </para>

     

       175
       224
        
       

     

       176
       225
        
          <para>

     

       177
       177
       -
           The result of this configuration will be an <command>emacs</command> command which launches Emacs with all of your chosen packages in the <varname>load-path</varname>.

     

       226
       226
       +
           The result of this configuration will be an <command>emacs</command>

     

       227
       227
       +
           command which launches Emacs with all of your chosen packages in the

     

       228
       228
       +
           <varname>load-path</varname>.

     

       178
       229
        
          </para>

     

       179
       230
        
       

     

       180
       231
        
          <para>

     
···

       183
       234
        
       <prompt>$ </prompt>nix-build emacs.nix

     

       184
       235
        
       <prompt>$ </prompt>./result/bin/emacs -q

     

       185
       236
        
       </screen>

     

       186
       186
       -
           and then typing <literal>M-x package-initialize</literal>. Check that you can use all the packages you want in this Emacs instance. For example, try switching to the zerodark theme through <literal>M-x load-theme &lt;RET&gt; zerodark &lt;RET&gt; y</literal>.

     

       237
       237
       +
           and then typing <literal>M-x package-initialize</literal>. Check that you

     

       238
       238
       +
           can use all the packages you want in this Emacs instance. For example, try

     

       239
       239
       +
           switching to the zerodark theme through <literal>M-x load-theme &lt;RET&gt;

     

       240
       240
       +
           zerodark &lt;RET&gt; y</literal>.

     

       187
       241
        
          </para>

     

       188
       242
        
       

     

       189
       243
        
          <tip>

     

       190
       244
        
           <para>

     

       191
       191
       -
            A few popular extensions worth checking out are: auctex, company, edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile, and yasnippet.

     

       245
       245
       +
            A few popular extensions worth checking out are: auctex, company,

     

       246
       246
       +
            edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile,

     

       247
       247
       +
            and yasnippet.

     

       192
       248
        
           </para>

     

       193
       249
        
          </tip>

     

       194
       250
        
       

     

       195
       251
        
          <para>

     

       196
       196
       -
           The list of available packages in the various ELPA repositories can be seen with the following commands:

     

       252
       252
       +
           The list of available packages in the various ELPA repositories can be seen

     

       253
       253
       +
           with the following commands:

     

       197
       254
        
           <example xml:id="module-services-emacs-querying-packages">

     

       198
       255
        
            <title>Querying Emacs packages</title>

     

       199
       256
        
       <programlisting><![CDATA[

     
···

       206
       263
        
          </para>

     

       207
       264
        
       

     

       208
       265
        
          <para>

     

       209
       209
       -
           If you are on NixOS, you can install this particular Emacs for all users by adding it to the list of system packages (see <xref linkend="sec-declarative-package-mgmt" />). Simply modify your file <filename>configuration.nix</filename> to make it contain:

     

       266
       266
       +
           If you are on NixOS, you can install this particular Emacs for all users by

     

       267
       267
       +
           adding it to the list of system packages (see

     

       268
       268
       +
           <xref linkend="sec-declarative-package-mgmt" />). Simply modify your file

     

       269
       269
       +
           <filename>configuration.nix</filename> to make it contain:

     

       210
       270
        
           <example xml:id="module-services-emacs-configuration-nix">

     

       211
       271
        
            <title>Custom Emacs in <filename>configuration.nix</filename></title>

     

       212
       272
        
       <programlisting><![CDATA[

     
···

       221
       281
        
          </para>

     

       222
       282
        
       

     

       223
       283
        
          <para>

     

       224
       224
       -
           In this case, the next <command>nixos-rebuild switch</command> will take care of adding your <command>emacs</command> to the <varname>PATH</varname> environment variable (see <xref linkend="sec-changing-config" />).

     

       284
       284
       +
           In this case, the next <command>nixos-rebuild switch</command> will take

     

       285
       285
       +
           care of adding your <command>emacs</command> to the <varname>PATH</varname>

     

       286
       286
       +
           environment variable (see <xref linkend="sec-changing-config" />).

     

       225
       287
        
          </para>

     

       226
       288
        
       

     

       227
       289
        
       <!-- fixme: i think the following is better done with config.nix

     
···

       229
       291
        
       -->

     

       230
       292
        
       

     

       231
       293
        
          <para>

     

       232
       232
       -
           If you are not on NixOS or want to install this particular Emacs only for yourself, you can do so by adding it to your <filename>~/.config/nixpkgs/config.nix</filename> (see <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs manual</link>):

     

       294
       294
       +
           If you are not on NixOS or want to install this particular Emacs only for

     

       295
       295
       +
           yourself, you can do so by adding it to your

     

       296
       296
       +
           <filename>~/.config/nixpkgs/config.nix</filename> (see

     

       297
       297
       +
           <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs

     

       298
       298
       +
           manual</link>):

     

       233
       299
        
           <example xml:id="module-services-emacs-config-nix">

     

       234
       300
        
            <title>Custom Emacs in <filename>~/.config/nixpkgs/config.nix</filename></title>

     

       235
       301
        
       <programlisting><![CDATA[

     
···

       243
       309
        
          </para>

     

       244
       310
        
       

     

       245
       311
        
          <para>

     

       246
       246
       -
           In this case, the next <literal>nix-env -f '&lt;nixpkgs&gt;' -iA myemacs</literal> will take care of adding your emacs to the <varname>PATH</varname> environment variable.

     

       312
       312
       +
           In this case, the next <literal>nix-env -f '&lt;nixpkgs&gt;' -iA

     

       313
       313
       +
           myemacs</literal> will take care of adding your emacs to the

     

       314
       314
       +
           <varname>PATH</varname> environment variable.

     

       247
       315
        
          </para>

     

       248
       316
        
         </section>

     

       249
       317
        
       

     
···

       251
       319
        
          <title>Advanced Emacs Configuration</title>

     

       252
       320
        
       

     

       253
       321
        
          <para>

     

       254
       254
       -
           If you want, you can tweak the Emacs package itself from your <filename>emacs.nix</filename>. For example, if you want to have a GTK 3-based Emacs instead of the default GTK 2-based binary and remove the automatically generated <filename>emacs.desktop</filename> (useful is you only use <command>emacsclient</command>), you can change your file <filename>emacs.nix</filename> in this way:

     

       322
       322
       +
           If you want, you can tweak the Emacs package itself from your

     

       323
       323
       +
           <filename>emacs.nix</filename>. For example, if you want to have a

     

       324
       324
       +
           GTK 3-based Emacs instead of the default GTK 2-based binary and remove the

     

       325
       325
       +
           automatically generated <filename>emacs.desktop</filename> (useful is you

     

       326
       326
       +
           only use <command>emacsclient</command>), you can change your file

     

       327
       327
       +
           <filename>emacs.nix</filename> in this way:

     

       255
       328
        
          </para>

     

       256
       329
        
       

     

       257
       330
        
          <example xml:id="ex-emacsGtk3Nix">

     
···

       275
       348
        
          </example>

     

       276
       349
        
       

     

       277
       350
        
          <para>

     

       278
       278
       -
           After building this file as shown in <xref linkend="ex-emacsNix" />, you will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.

     

       351
       351
       +
           After building this file as shown in <xref linkend="ex-emacsNix" />, you

     

       352
       352
       +
           will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.

     

       279
       353
        
          </para>

     

       280
       354
        
         </section>

     

       281
       355
        
        </section>

     
···

       283
       357
        
         <title>Running Emacs as a Service</title>

     

       284
       358
        
       

     

       285
       359
        
         <para>

     

       286
       286
       -
          <productname>NixOS</productname> provides an optional <command>systemd</command> service which launches <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html"> Emacs daemon </link> with the user's login session.

     

       360
       360
       +
          <productname>NixOS</productname> provides an optional

     

       361
       361
       +
          <command>systemd</command> service which launches

     

       362
       362
       +
          <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">

     

       363
       363
       +
          Emacs daemon </link> with the user's login session.

     

       287
       364
        
         </para>

     

       288
       365
        
       

     

       289
       366
        
         <para>

     

       290
       290
       -
          <emphasis>Source:</emphasis> <filename>modules/services/editors/emacs.nix</filename>

     

       367
       367
       +
          <emphasis>Source:</emphasis>

     

       368
       368
       +
          <filename>modules/services/editors/emacs.nix</filename>

     

       291
       369
        
         </para>

     

       292
       370
        
       

     

       293
       371
        
         <section xml:id="module-services-emacs-enabling">

     

       294
       372
        
          <title>Enabling the Service</title>

     

       295
       373
        
       

     

       296
       374
        
          <para>

     

       297
       297
       -
           To install and enable the <command>systemd</command> user service for Emacs daemon, add the following to your <filename>configuration.nix</filename>:

     

       375
       375
       +
           To install and enable the <command>systemd</command> user service for Emacs

     

       376
       376
       +
           daemon, add the following to your <filename>configuration.nix</filename>:

     

       298
       377
        
       <programlisting>

     

       299
       378
        
       <xref linkend="opt-services.emacs.enable"/> = true;

     

       300
       379
        
       <xref linkend="opt-services.emacs.package"/> = import /home/cassou/.emacs.d { pkgs = pkgs; };

     
···

       302
       381
        
          </para>

     

       303
       382
        
       

     

       304
       383
        
          <para>

     

       305
       305
       -
           The <varname>services.emacs.package</varname> option allows a custom derivation to be used, for example, one created by <function>emacsWithPackages</function>.

     

       384
       384
       +
           The <varname>services.emacs.package</varname> option allows a custom

     

       385
       385
       +
           derivation to be used, for example, one created by

     

       386
       386
       +
           <function>emacsWithPackages</function>.

     

       306
       387
        
          </para>

     

       307
       388
        
       

     

       308
       389
        
          <para>

     

       309
       309
       -
           Ensure that the Emacs server is enabled for your user's Emacs configuration, either by customizing the <varname>server-mode</varname> variable, or by adding <literal>(server-start)</literal> to <filename>~/.emacs.d/init.el</filename>.

     

       390
       390
       +
           Ensure that the Emacs server is enabled for your user's Emacs

     

       391
       391
       +
           configuration, either by customizing the <varname>server-mode</varname>

     

       392
       392
       +
           variable, or by adding <literal>(server-start)</literal> to

     

       393
       393
       +
           <filename>~/.emacs.d/init.el</filename>.

     

       310
       394
        
          </para>

     

       311
       395
        
       

     

       312
       396
        
          <para>

     
···

       324
       408
        
          <title>Starting the client</title>

     

       325
       409
        
       

     

       326
       410
        
          <para>

     

       327
       327
       -
           Ensure that the emacs server is enabled, either by customizing the <varname>server-mode</varname> variable, or by adding <literal>(server-start)</literal> to <filename>~/.emacs</filename>.

     

       411
       411
       +
           Ensure that the emacs server is enabled, either by customizing the

     

       412
       412
       +
           <varname>server-mode</varname> variable, or by adding

     

       413
       413
       +
           <literal>(server-start)</literal> to <filename>~/.emacs</filename>.

     

       328
       414
        
          </para>

     

       329
       415
        
       

     

       330
       416
        
          <para>

     
···

       343
       429
        
       <!--<title><command>emacsclient</command> as the Default Editor</title>-->

     

       344
       430
        
       

     

       345
       431
        
          <para>

     

       346
       346
       -
           If <xref linkend="opt-services.emacs.defaultEditor"/> is <literal>true</literal>, the <varname>EDITOR</varname> variable will be set to a wrapper script which launches <command>emacsclient</command>.

     

       432
       432
       +
           If <xref linkend="opt-services.emacs.defaultEditor"/> is

     

       433
       433
       +
           <literal>true</literal>, the <varname>EDITOR</varname> variable will be set

     

       434
       434
       +
           to a wrapper script which launches <command>emacsclient</command>.

     

       347
       435
        
          </para>

     

       348
       436
        
       

     

       349
       437
        
          <para>

     

       350
       350
       -
           Any setting of <varname>EDITOR</varname> in the shell config files will override <varname>services.emacs.defaultEditor</varname>. To make sure <varname>EDITOR</varname> refers to the Emacs wrapper script, remove any existing <varname>EDITOR</varname> assignment from <filename>.profile</filename>, <filename>.bashrc</filename>, <filename>.zshenv</filename> or any other shell config file.

     

       438
       438
       +
           Any setting of <varname>EDITOR</varname> in the shell config files will

     

       439
       439
       +
           override <varname>services.emacs.defaultEditor</varname>. To make sure

     

       440
       440
       +
           <varname>EDITOR</varname> refers to the Emacs wrapper script, remove any

     

       441
       441
       +
           existing <varname>EDITOR</varname> assignment from

     

       442
       442
       +
           <filename>.profile</filename>, <filename>.bashrc</filename>,

     

       443
       443
       +
           <filename>.zshenv</filename> or any other shell config file.

     

       351
       444
        
          </para>

     

       352
       445
        
       

     

       353
       446
        
          <para>

     

       354
       354
       -
           If you have formed certain bad habits when editing files, these can be corrected with a shell alias to the wrapper script:

     

       447
       447
       +
           If you have formed certain bad habits when editing files, these can be

     

       448
       448
       +
           corrected with a shell alias to the wrapper script:

     

       355
       449
        
       <programlisting>alias vi=$EDITOR</programlisting>

     

       356
       450
        
          </para>

     

       357
       451
        
         </section>

     
···

       360
       454
        
          <title>Per-User Enabling of the Service</title>

     

       361
       455
        
       

     

       362
       456
        
          <para>

     

       363
       363
       -
           In general, <command>systemd</command> user services are globally enabled by symlinks in <filename>/etc/systemd/user</filename>. In the case where Emacs daemon is not wanted for all users, it is possible to install the service but not globally enable it:

     

       457
       457
       +
           In general, <command>systemd</command> user services are globally enabled

     

       458
       458
       +
           by symlinks in <filename>/etc/systemd/user</filename>. In the case where

     

       459
       459
       +
           Emacs daemon is not wanted for all users, it is possible to install the

     

       460
       460
       +
           service but not globally enable it:

     

       364
       461
        
       <programlisting>

     

       365
       462
        
       <xref linkend="opt-services.emacs.enable"/> = false;

     

       366
       463
        
       <xref linkend="opt-services.emacs.install"/> = true;

     
···

       368
       465
        
          </para>

     

       369
       466
        
       

     

       370
       467
        
          <para>

     

       371
       371
       -
           To enable the <command>systemd</command> user service for just the currently logged in user, run:

     

       468
       468
       +
           To enable the <command>systemd</command> user service for just the

     

       469
       469
       +
           currently logged in user, run:

     

       372
       470
        
       <programlisting>systemctl --user enable emacs</programlisting>

     

       373
       373
       -
           This will add the symlink <filename>~/.config/systemd/user/emacs.service</filename>.

     

       471
       471
       +
           This will add the symlink

     

       472
       472
       +
           <filename>~/.config/systemd/user/emacs.service</filename>.

     

       374
       473
        
          </para>

     

       375
       474
        
         </section>

     

       376
       475
        
        </section>

     
···

       378
       477
        
         <title>Configuring Emacs</title>

     

       379
       478
        
       

     

       380
       479
        
         <para>

     

       381
       381
       -
          The Emacs init file should be changed to load the extension packages at startup:

     

       480
       480
       +
          The Emacs init file should be changed to load the extension packages at

     

       481
       481
       +
          startup:

     

       382
       482
        
          <example xml:id="module-services-emacs-package-initialisation">

     

       383
       483
        
           <title>Package initialization in <filename>.emacs</filename></title>

     

       384
       484
        
       <programlisting><![CDATA[

     
···

       394
       494
        
         </para>

     

       395
       495
        
       

     

       396
       496
        
         <para>

     

       397
       397
       -
          After the declarative emacs package configuration has been tested, previously downloaded packages can be cleaned up by removing <filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you forgot a package).

     

       497
       497
       +
          After the declarative emacs package configuration has been tested,

     

       498
       498
       +
          previously downloaded packages can be cleaned up by removing

     

       499
       499
       +
          <filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you

     

       500
       500
       +
          forgot a package).

     

       398
       501
        
         </para>

     

       399
       502
        
       

     

       400
       503
        
       <!--

     
···

       406
       509
        
          <title>A Major Mode for Nix Expressions</title>

     

       407
       510
        
       

     

       408
       511
        
          <para>

     

       409
       409
       -
           Of interest may be <varname>melpaPackages.nix-mode</varname>, which provides syntax highlighting for the Nix language. This is particularly convenient if you regularly edit Nix files.

     

       512
       512
       +
           Of interest may be <varname>melpaPackages.nix-mode</varname>, which

     

       513
       513
       +
           provides syntax highlighting for the Nix language. This is particularly

     

       514
       514
       +
           convenient if you regularly edit Nix files.

     

       410
       515
        
          </para>

     

       411
       516
        
         </section>

     

       412
       517
        
       

     
···

       414
       519
        
          <title>Accessing man pages</title>

     

       415
       520
        
       

     

       416
       521
        
          <para>

     

       417
       417
       -
           You can use <function>woman</function> to get completion of all available man pages. For example, type <literal>M-x woman &lt;RET&gt; nixos-rebuild &lt;RET&gt;.</literal>

     

       522
       522
       +
           You can use <function>woman</function> to get completion of all available

     

       523
       523
       +
           man pages. For example, type <literal>M-x woman &lt;RET&gt; nixos-rebuild

     

       524
       524
       +
           &lt;RET&gt;.</literal>

     

       418
       525
        
          </para>

     

       419
       526
        
         </section>

     

       420
       527
        
       

     
···

       422
       529
        
          <title>Editing DocBook 5 XML Documents</title>

     

       423
       530
        
       

     

       424
       531
        
          <para>

     

       425
       425
       -
           Emacs includes <link

     

       426
       426
       -
             xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>, a major-mode for validating and editing XML documents. When editing DocBook 5.0 documents, such as <link linkend="book-nixos-manual">this one</link>, nXML needs to be configured with the relevant schema, which is not included.

     

       532
       532
       +
           Emacs includes

     

       533
       533
       +
           <link

     

       534
       534
       +
             xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>,

     

       535
       535
       +
           a major-mode for validating and editing XML documents. When editing DocBook

     

       536
       536
       +
           5.0 documents, such as <link linkend="book-nixos-manual">this one</link>,

     

       537
       537
       +
           nXML needs to be configured with the relevant schema, which is not

     

       538
       538
       +
           included.

     

       427
       539
        
          </para>

     

       428
       540
        
       

     

       429
       541
        
          <para>

     

       430
       430
       -
           To install the DocBook 5.0 schemas, either add <varname>pkgs.docbook5</varname> to <xref linkend="opt-environment.systemPackages"/> (<link

     

       431
       431
       -
             linkend="sec-declarative-package-mgmt">NixOS</link>), or run <literal>nix-env -f '&lt;nixpkgs&gt;' -iA docbook5</literal> (<link linkend="sec-ad-hoc-packages">Nix</link>).

     

       542
       542
       +
           To install the DocBook 5.0 schemas, either add

     

       543
       543
       +
           <varname>pkgs.docbook5</varname> to

     

       544
       544
       +
           <xref linkend="opt-environment.systemPackages"/>

     

       545
       545
       +
           (<link

     

       546
       546
       +
             linkend="sec-declarative-package-mgmt">NixOS</link>), or run

     

       547
       547
       +
           <literal>nix-env -f '&lt;nixpkgs&gt;' -iA docbook5</literal>

     

       548
       548
       +
           (<link linkend="sec-ad-hoc-packages">Nix</link>).

     

       432
       549
        
          </para>

     

       433
       550
        
       

     

       434
       551
        
          <para>

     

       435
       435
       -
           Then customize the variable <varname>rng-schema-locating-files</varname> to include <filename>~/.emacs.d/schemas.xml</filename> and put the following text into that file:

     

       552
       552
       +
           Then customize the variable <varname>rng-schema-locating-files</varname> to

     

       553
       553
       +
           include <filename>~/.emacs.d/schemas.xml</filename> and put the following

     

       554
       554
       +
           text into that file:

     

       436
       555
        
           <example xml:id="ex-emacs-docbook-xml">

     

       437
       556
        
            <title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title>

     

       438
       557
        
       <programlisting language="xml"><![CDATA[

+8 -2

nixos/modules/services/hardware/trezord.xml

···

       5
       5
        
                xml:id="trezor">

     

       6
       6
        
        <title>Trezor</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         Trezor is an open-source cryptocurrency hardware wallet and security token allowing secure storage of private keys.

     

       8
       8
       +
         Trezor is an open-source cryptocurrency hardware wallet and security token

     

       9
       9
       +
         allowing secure storage of private keys.

     

       9
       10
        
        </para>

     

       10
       11
        
        <para>

     

       11
       11
       -
         It offers advanced features such U2F two-factor authorization, SSH login through <link xlink:href="https://wiki.trezor.io/Apps:SSH_agent">Trezor SSH agent</link>, <link xlink:href="https://wiki.trezor.io/GPG">GPG</link> and a <link xlink:href="https://wiki.trezor.io/Trezor_Password_Manager">password manager</link>. For more information, guides and documentation, see <link xlink:href="https://wiki.trezor.io"/>.

     

       12
       12
       +
         It offers advanced features such U2F two-factor authorization, SSH login

     

       13
       13
       +
         through

     

       14
       14
       +
         <link xlink:href="https://wiki.trezor.io/Apps:SSH_agent">Trezor SSH agent</link>,

     

       15
       15
       +
         <link xlink:href="https://wiki.trezor.io/GPG">GPG</link> and a

     

       16
       16
       +
         <link xlink:href="https://wiki.trezor.io/Trezor_Password_Manager">password manager</link>.

     

       17
       17
       +
         For more information, guides and documentation, see <link xlink:href="https://wiki.trezor.io"/>.

     

       12
       18
        
        </para>

     

       13
       19
        
        <para>

     

       14
       20
        
         To enable Trezor support, add the following to your <filename>configuration.nix</filename>:

+26 -8

nixos/modules/services/misc/gitlab.xml

···

       11
       11
        
         <title>Prerequisites</title>

     

       12
       12
        
       

     

       13
       13
        
         <para>

     

       14
       14
       -
          The gitlab service exposes only an Unix socket at <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to configure a webserver to proxy HTTP requests to the socket.

     

       14
       14
       +
          The gitlab service exposes only an Unix socket at

     

       15
       15
       +
          <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to

     

       16
       16
       +
          configure a webserver to proxy HTTP requests to the socket.

     

       15
       17
        
         </para>

     

       16
       18
        
       

     

       17
       19
        
         <para>

     

       18
       18
       -
          For instance, the following configuration could be used to use nginx as frontend proxy:

     

       20
       20
       +
          For instance, the following configuration could be used to use nginx as

     

       21
       21
       +
          frontend proxy:

     

       19
       22
        
       <programlisting>

     

       20
       23
        
       <link linkend="opt-services.nginx.enable">services.nginx</link> = {

     

       21
       24
        
         <link linkend="opt-services.nginx.enable">enable</link> = true;

     
···

       36
       39
        
         <title>Configuring</title>

     

       37
       40
        
       

     

       38
       41
        
         <para>

     

       39
       39
       -
          Gitlab depends on both PostgreSQL and Redis and will automatically enable both services. In the case of PostgreSQL, a database and a role will be created.

     

       42
       42
       +
          Gitlab depends on both PostgreSQL and Redis and will automatically enable

     

       43
       43
       +
          both services. In the case of PostgreSQL, a database and a role will be

     

       44
       44
       +
          created.

     

       40
       45
        
         </para>

     

       41
       46
        
       

     

       42
       47
        
         <para>

     

       43
       43
       -
          The default state dir is <literal>/var/gitlab/state</literal>. This is where all data like the repositories and uploads will be stored.

     

       48
       48
       +
          The default state dir is <literal>/var/gitlab/state</literal>. This is where

     

       49
       49
       +
          all data like the repositories and uploads will be stored.

     

       44
       50
        
         </para>

     

       45
       51
        
       

     

       46
       52
        
         <para>

     
···

       79
       85
        
         </para>

     

       80
       86
        
       

     

       81
       87
        
         <para>

     

       82
       82
       -
          If you're setting up a new Gitlab instance, generate new secrets. You for instance use <literal>tr -dc A-Za-z0-9 &lt; /dev/urandom | head -c 128 &gt; /var/keys/gitlab/db</literal> to generate a new db secret. Make sure the files can be read by, and only by, the user specified by <link

     

       83
       83
       -
          linkend="opt-services.gitlab.user">services.gitlab.user</link>. Gitlab encrypts sensitive data stored in the database. If you're restoring an existing Gitlab instance, you must specify the secrets secret from <literal>config/secrets.yml</literal> located in your Gitlab state folder.

     

       88
       88
       +
          If you're setting up a new Gitlab instance, generate new

     

       89
       89
       +
          secrets. You for instance use <literal>tr -dc A-Za-z0-9 &lt;

     

       90
       90
       +
          /dev/urandom | head -c 128 &gt; /var/keys/gitlab/db</literal> to

     

       91
       91
       +
          generate a new db secret. Make sure the files can be read by, and

     

       92
       92
       +
          only by, the user specified by <link

     

       93
       93
       +
          linkend="opt-services.gitlab.user">services.gitlab.user</link>. Gitlab

     

       94
       94
       +
          encrypts sensitive data stored in the database. If you're restoring

     

       95
       95
       +
          an existing Gitlab instance, you must specify the secrets secret

     

       96
       96
       +
          from <literal>config/secrets.yml</literal> located in your Gitlab

     

       97
       97
       +
          state folder.

     

       84
       98
        
         </para>

     

       85
       99
        
       

     

       86
       100
        
         <para>

     

       87
       87
       -
          Refer to <xref linkend="ch-options" /> for all available configuration options for the <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.

     

       101
       101
       +
          Refer to <xref linkend="ch-options" /> for all available configuration

     

       102
       102
       +
          options for the

     

       103
       103
       +
          <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.

     

       88
       104
        
         </para>

     

       89
       105
        
        </section>

     

       90
       106
        
        <section xml:id="module-services-gitlab-maintenance">

     

       91
       107
        
         <title>Maintenance</title>

     

       92
       108
        
       

     

       93
       109
        
         <para>

     

       94
       94
       -
          You can run Gitlab's rake tasks with <literal>gitlab-rake</literal> which will be available on the system when gitlab is enabled. You will have to run the command as the user that you configured to run gitlab with.

     

       110
       110
       +
          You can run Gitlab's rake tasks with <literal>gitlab-rake</literal> which

     

       111
       111
       +
          will be available on the system when gitlab is enabled. You will have to run

     

       112
       112
       +
          the command as the user that you configured to run gitlab with.

     

       95
       113
        
         </para>

     

       96
       114
        
       

     

       97
       115
        
         <para>

+56 -18

nixos/modules/services/misc/taskserver/doc.xml

···

       4
       4
        
           xml:id="module-taskserver">

     

       5
       5
        
        <title>Taskserver</title>

     

       6
       6
        
        <para>

     

       7
       7
       -
         Taskserver is the server component of <link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and open source todo list application.

     

       7
       7
       +
         Taskserver is the server component of

     

       8
       8
       +
         <link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and

     

       9
       9
       +
         open source todo list application.

     

       8
       10
        
        </para>

     

       9
       11
        
        <para>

     

       10
       10
       -
         <emphasis>Upstream documentation:</emphasis> <link xlink:href="https://taskwarrior.org/docs/#taskd"/>

     

       12
       12
       +
         <emphasis>Upstream documentation:</emphasis>

     

       13
       13
       +
         <link xlink:href="https://taskwarrior.org/docs/#taskd"/>

     

       11
       14
        
        </para>

     

       12
       15
        
        <section xml:id="module-services-taskserver-configuration">

     

       13
       16
        
         <title>Configuration</title>

     

       14
       17
        
       

     

       15
       18
        
         <para>

     

       16
       16
       -
          Taskserver does all of its authentication via TLS using client certificates, so you either need to roll your own CA or purchase a certificate from a known CA, which allows creation of client certificates. These certificates are usually advertised as <quote>server certificates</quote>.

     

       19
       19
       +
          Taskserver does all of its authentication via TLS using client certificates,

     

       20
       20
       +
          so you either need to roll your own CA or purchase a certificate from a

     

       21
       21
       +
          known CA, which allows creation of client certificates. These certificates

     

       22
       22
       +
          are usually advertised as <quote>server certificates</quote>.

     

       17
       23
        
         </para>

     

       18
       24
        
       

     

       19
       25
        
         <para>

     

       20
       20
       -
          So in order to make it easier to handle your own CA, there is a helper tool called <command>nixos-taskserver</command> which manages the custom CA along with Taskserver organisations, users and groups.

     

       26
       26
       +
          So in order to make it easier to handle your own CA, there is a helper tool

     

       27
       27
       +
          called <command>nixos-taskserver</command> which manages the custom CA along

     

       28
       28
       +
          with Taskserver organisations, users and groups.

     

       21
       29
        
         </para>

     

       22
       30
        
       

     

       23
       31
        
         <para>

     

       24
       24
       -
          While the client certificates in Taskserver only authenticate whether a user is allowed to connect, every user has its own UUID which identifies it as an entity.

     

       32
       32
       +
          While the client certificates in Taskserver only authenticate whether a user

     

       33
       33
       +
          is allowed to connect, every user has its own UUID which identifies it as an

     

       34
       34
       +
          entity.

     

       25
       35
        
         </para>

     

       26
       36
        
       

     

       27
       37
        
         <para>

     

       28
       28
       -
          With <command>nixos-taskserver</command> the client certificate is created along with the UUID of the user, so it handles all of the credentials needed in order to setup the Taskwarrior client to work with a Taskserver.

     

       38
       38
       +
          With <command>nixos-taskserver</command> the client certificate is created

     

       39
       39
       +
          along with the UUID of the user, so it handles all of the credentials needed

     

       40
       40
       +
          in order to setup the Taskwarrior client to work with a Taskserver.

     

       29
       41
        
         </para>

     

       30
       42
        
        </section>

     

       31
       43
        
        <section xml:id="module-services-taskserver-nixos-taskserver-tool">

     

       32
       44
        
         <title>The nixos-taskserver tool</title>

     

       33
       45
        
       

     

       34
       46
        
         <para>

     

       35
       35
       -
          Because Taskserver by default only provides scripts to setup users imperatively, the <command>nixos-taskserver</command> tool is used for addition and deletion of organisations along with users and groups defined by <xref linkend="opt-services.taskserver.organisations"/> and as well for imperative set up.

     

       47
       47
       +
          Because Taskserver by default only provides scripts to setup users

     

       48
       48
       +
          imperatively, the <command>nixos-taskserver</command> tool is used for

     

       49
       49
       +
          addition and deletion of organisations along with users and groups defined

     

       50
       50
       +
          by <xref linkend="opt-services.taskserver.organisations"/> and as well for

     

       51
       51
       +
          imperative set up.

     

       36
       52
        
         </para>

     

       37
       53
        
       

     

       38
       54
        
         <para>

     

       39
       39
       -
          The tool is designed to not interfere if the command is used to manually set up some organisations, users or groups.

     

       55
       55
       +
          The tool is designed to not interfere if the command is used to manually set

     

       56
       56
       +
          up some organisations, users or groups.

     

       40
       57
        
         </para>

     

       41
       58
        
       

     

       42
       59
        
         <para>

     

       43
       43
       -
          For example if you add a new organisation using <command>nixos-taskserver org add foo</command>, the organisation is not modified and deleted no matter what you define in <option>services.taskserver.organisations</option>, even if you're adding the same organisation in that option.

     

       60
       60
       +
          For example if you add a new organisation using <command>nixos-taskserver

     

       61
       61
       +
          org add foo</command>, the organisation is not modified and deleted no

     

       62
       62
       +
          matter what you define in

     

       63
       63
       +
          <option>services.taskserver.organisations</option>, even if you're adding

     

       64
       64
       +
          the same organisation in that option.

     

       44
       65
        
         </para>

     

       45
       66
        
       

     

       46
       67
        
         <para>

     

       47
       47
       -
          The tool is modelled to imitate the official <command>taskd</command> command, documentation for each subcommand can be shown by using the <option>--help</option> switch.

     

       68
       68
       +
          The tool is modelled to imitate the official <command>taskd</command>

     

       69
       69
       +
          command, documentation for each subcommand can be shown by using the

     

       70
       70
       +
          <option>--help</option> switch.

     

       48
       71
        
         </para>

     

       49
       72
        
        </section>

     

       50
       73
        
        <section xml:id="module-services-taskserver-declarative-ca-management">

     

       51
       74
        
         <title>Declarative/automatic CA management</title>

     

       52
       75
        
       

     

       53
       76
        
         <para>

     

       54
       54
       -
          Everything is done according to what you specify in the module options, however in order to set up a Taskwarrior client for synchronisation with a Taskserver instance, you have to transfer the keys and certificates to the client machine.

     

       77
       77
       +
          Everything is done according to what you specify in the module options,

     

       78
       78
       +
          however in order to set up a Taskwarrior client for synchronisation with a

     

       79
       79
       +
          Taskserver instance, you have to transfer the keys and certificates to the

     

       80
       80
       +
          client machine.

     

       55
       81
        
         </para>

     

       56
       82
        
       

     

       57
       83
        
         <para>

     

       58
       58
       -
          This is done using <command>nixos-taskserver user export $orgname $username</command> which is printing a shell script fragment to stdout which can either be used verbatim or adjusted to import the user on the client machine.

     

       84
       84
       +
          This is done using <command>nixos-taskserver user export $orgname

     

       85
       85
       +
          $username</command> which is printing a shell script fragment to stdout

     

       86
       86
       +
          which can either be used verbatim or adjusted to import the user on the

     

       87
       87
       +
          client machine.

     

       59
       88
        
         </para>

     

       60
       89
        
       

     

       61
       90
        
         <para>

     
···

       68
       97
        
         <link linkend="opt-services.taskserver.organisations._name_.users">services.taskserver.organisations.my-company.users</link> = [ "alice" ];

     

       69
       98
        
       }

     

       70
       99
        
       </screen>

     

       71
       71
       -
          This creates an organisation called <literal>my-company</literal> with the user <literal>alice</literal>.

     

       100
       100
       +
          This creates an organisation called <literal>my-company</literal> with the

     

       101
       101
       +
          user <literal>alice</literal>.

     

       72
       102
        
         </para>

     

       73
       103
        
       

     

       74
       104
        
         <para>

     

       75
       75
       -
          Now in order to import the <literal>alice</literal> user to another machine <literal>alicebox</literal>, all we need to do is something like this:

     

       105
       105
       +
          Now in order to import the <literal>alice</literal> user to another machine

     

       106
       106
       +
          <literal>alicebox</literal>, all we need to do is something like this:

     

       76
       107
        
       <screen>

     

       77
       108
        
       <prompt>$ </prompt>ssh server nixos-taskserver user export my-company alice | sh

     

       78
       109
        
       </screen>

     

       79
       79
       -
          Of course, if no SSH daemon is available on the server you can also copy &amp; paste it directly into a shell.

     

       110
       110
       +
          Of course, if no SSH daemon is available on the server you can also copy

     

       111
       111
       +
          &amp; paste it directly into a shell.

     

       80
       112
        
         </para>

     

       81
       113
        
       

     

       82
       114
        
         <para>

     

       83
       83
       -
          After this step the user should be set up and you can start synchronising your tasks for the first time with <command>task sync init</command> on <literal>alicebox</literal>.

     

       115
       115
       +
          After this step the user should be set up and you can start synchronising

     

       116
       116
       +
          your tasks for the first time with <command>task sync init</command> on

     

       117
       117
       +
          <literal>alicebox</literal>.

     

       84
       118
        
         </para>

     

       85
       119
        
       

     

       86
       120
        
         <para>

     

       87
       87
       -
          Subsequent synchronisation requests merely require the command <command>task sync</command> after that stage.

     

       121
       121
       +
          Subsequent synchronisation requests merely require the command <command>task

     

       122
       122
       +
          sync</command> after that stage.

     

       88
       123
        
         </para>

     

       89
       124
        
        </section>

     

       90
       125
        
        <section xml:id="module-services-taskserver-manual-ca-management">

     

       91
       126
        
         <title>Manual CA management</title>

     

       92
       127
        
       

     

       93
       128
        
         <para>

     

       94
       94
       -
          If you set any options within <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*, <command>nixos-taskserver</command> won't issue certificates, but you can still use it for adding or removing user accounts.

     

       129
       129
       +
          If you set any options within

     

       130
       130
       +
          <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,

     

       131
       131
       +
          <command>nixos-taskserver</command> won't issue certificates, but you can

     

       132
       132
       +
          still use it for adding or removing user accounts.

     

       95
       133
        
         </para>

     

       96
       134
        
        </section>

     

       97
       135
        
       </chapter>

+16 -5

nixos/modules/services/misc/weechat.xml

···

       5
       5
        
                xml:id="module-services-weechat">

     

       6
       6
        
        <title>WeeChat</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         <link xlink:href="https://weechat.org/">WeeChat</link> is a fast and extensible IRC client.

     

       8
       8
       +
         <link xlink:href="https://weechat.org/">WeeChat</link> is a fast and

     

       9
       9
       +
         extensible IRC client.

     

       9
       10
        
        </para>

     

       10
       11
        
        <section xml:id="module-services-weechat-basic-usage">

     

       11
       12
        
         <title>Basic Usage</title>

     

       12
       13
        
       

     

       13
       14
        
         <para>

     

       14
       14
       -
          By default, the module creates a <literal><link xlink:href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</link></literal> unit which runs the chat client in a detached <literal><link xlink:href="https://www.gnu.org/software/screen/">screen</link></literal> session.

     

       15
       15
       +
          By default, the module creates a

     

       16
       16
       +
          <literal><link xlink:href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</link></literal>

     

       17
       17
       +
          unit which runs the chat client in a detached

     

       18
       18
       +
          <literal><link xlink:href="https://www.gnu.org/software/screen/">screen</link></literal>

     

       19
       19
       +
          session.

     

       15
       20
        
         </para>

     

       16
       21
        
       

     

       17
       22
        
         <para>

     
···

       26
       31
        
         </para>

     

       27
       32
        
       

     

       28
       33
        
         <para>

     

       29
       29
       -
          The service is managed by a dedicated user named <literal>weechat</literal> in the state directory <literal>/var/lib/weechat</literal>.

     

       34
       34
       +
          The service is managed by a dedicated user named <literal>weechat</literal>

     

       35
       35
       +
          in the state directory <literal>/var/lib/weechat</literal>.

     

       30
       36
        
         </para>

     

       31
       37
        
        </section>

     

       32
       38
        
        <section xml:id="module-services-weechat-reattach">

     

       33
       39
        
         <title>Re-attaching to WeeChat</title>

     

       34
       40
        
       

     

       35
       41
        
         <para>

     

       36
       36
       -
          WeeChat runs in a screen session owned by a dedicated user. To explicitly allow your another user to attach to this session, the <literal>screenrc</literal> needs to be tweaked by adding <link xlink:href="https://www.gnu.org/software/screen/manual/html_node/Multiuser.html#Multiuser">multiuser</link> support:

     

       42
       42
       +
          WeeChat runs in a screen session owned by a dedicated user. To explicitly

     

       43
       43
       +
          allow your another user to attach to this session, the

     

       44
       44
       +
          <literal>screenrc</literal> needs to be tweaked by adding

     

       45
       45
       +
          <link xlink:href="https://www.gnu.org/software/screen/manual/html_node/Multiuser.html#Multiuser">multiuser</link>

     

       46
       46
       +
          support:

     

       37
       47
        
       <programlisting>

     

       38
       48
        
       {

     

       39
       49
        
         <link linkend="opt-programs.screen.screenrc">programs.screen.screenrc</link> = ''

     
···

       49
       59
        
         </para>

     

       50
       60
        
       

     

       51
       61
        
         <para>

     

       52
       52
       -
          <emphasis>The session name can be changed using <link linkend="opt-services.weechat.sessionName">services.weechat.sessionName.</link></emphasis>

     

       62
       62
       +
          <emphasis>The session name can be changed using

     

       63
       63
       +
          <link linkend="opt-services.weechat.sessionName">services.weechat.sessionName.</link></emphasis>

     

       53
       64
        
         </para>

     

       54
       65
        
        </section>

     

       55
       66
        
       </chapter>

+39 -12

nixos/modules/services/monitoring/prometheus/exporters.xml

···

       5
       5
        
                xml:id="module-services-prometheus-exporters">

     

       6
       6
        
        <title>Prometheus exporters</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         Prometheus exporters provide metrics for the <link xlink:href="https://prometheus.io">prometheus monitoring system</link>.

     

       8
       8
       +
         Prometheus exporters provide metrics for the

     

       9
       9
       +
         <link xlink:href="https://prometheus.io">prometheus monitoring system</link>.

     

       9
       10
        
        </para>

     

       10
       11
        
        <section xml:id="module-services-prometheus-exporters-configuration">

     

       11
       12
        
         <title>Configuration</title>

     

       12
       13
        
       

     

       13
       14
        
         <para>

     

       14
       14
       -
          One of the most common exporters is the <link xlink:href="https://github.com/prometheus/node_exporter">node exporter</link>, it provides hardware and OS metrics from the host it's running on. The exporter could be configured as follows:

     

       15
       15
       +
          One of the most common exporters is the

     

       16
       16
       +
          <link xlink:href="https://github.com/prometheus/node_exporter">node

     

       17
       17
       +
          exporter</link>, it provides hardware and OS metrics from the host it's

     

       18
       18
       +
          running on. The exporter could be configured as follows:

     

       15
       19
        
       <programlisting>

     

       16
       20
        
         services.prometheus.exporters.node = {

     

       17
       21
        
           enable = true;

     
···

       26
       30
        
           firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";

     

       27
       31
        
         };

     

       28
       32
        
       </programlisting>

     

       29
       29
       -
          It should now serve all metrics from the collectors that are explicitly enabled and the ones that are <link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled by default</link>, via http under <literal>/metrics</literal>. In this example the firewall should just allow incoming connections to the exporter's port on the bridge interface <literal>br0</literal> (this would have to be configured seperately of course). For more information about configuration see <literal>man configuration.nix</literal> or search through the <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available options</link>.

     

       33
       33
       +
          It should now serve all metrics from the collectors that are explicitly

     

       34
       34
       +
          enabled and the ones that are

     

       35
       35
       +
          <link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled

     

       36
       36
       +
          by default</link>, via http under <literal>/metrics</literal>. In this

     

       37
       37
       +
          example the firewall should just allow incoming connections to the

     

       38
       38
       +
          exporter's port on the bridge interface <literal>br0</literal> (this would

     

       39
       39
       +
          have to be configured seperately of course). For more information about

     

       40
       40
       +
          configuration see <literal>man configuration.nix</literal> or search through

     

       41
       41
       +
          the

     

       42
       42
       +
          <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available

     

       43
       43
       +
          options</link>.

     

       30
       44
        
         </para>

     

       31
       45
        
        </section>

     

       32
       46
        
        <section xml:id="module-services-prometheus-exporters-new-exporter">

     

       33
       47
        
         <title>Adding a new exporter</title>

     

       34
       48
        
       

     

       35
       49
        
         <para>

     

       36
       36
       -
          To add a new exporter, it has to be packaged first (see <literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for examples), then a module can be added. The postfix exporter is used in this example:

     

       50
       50
       +
          To add a new exporter, it has to be packaged first (see

     

       51
       51
       +
          <literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for

     

       52
       52
       +
          examples), then a module can be added. The postfix exporter is used in this

     

       53
       53
       +
          example:

     

       37
       54
        
         </para>

     

       38
       55
        
       

     

       39
       56
        
         <itemizedlist>

     

       40
       57
        
          <listitem>

     

       41
       58
        
           <para>

     

       42
       42
       -
            Some default options for all exporters are provided by <literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>:

     

       59
       59
       +
            Some default options for all exporters are provided by

     

       60
       60
       +
            <literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>:

     

       43
       61
        
           </para>

     

       44
       62
        
          </listitem>

     

       45
       63
        
          <listitem override='none'>

     
···

       88
       106
        
          </listitem>

     

       89
       107
        
          <listitem>

     

       90
       108
        
           <para>

     

       91
       91
       -
            As there is already a package available, the module can now be added. This is accomplished by adding a new file to the <literal>nixos/modules/services/monitoring/prometheus/exporters/</literal> directory, which will be called postfix.nix and contains all exporter specific options and configuration:

     

       109
       109
       +
            As there is already a package available, the module can now be added. This

     

       110
       110
       +
            is accomplished by adding a new file to the

     

       111
       111
       +
            <literal>nixos/modules/services/monitoring/prometheus/exporters/</literal>

     

       112
       112
       +
            directory, which will be called postfix.nix and contains all exporter

     

       113
       113
       +
            specific options and configuration:

     

       92
       114
        
       <programlisting>

     

       93
       115
        
       # nixpgs/nixos/modules/services/prometheus/exporters/postfix.nix

     

       94
       116
        
       { config, lib, pkgs, options }:

     
···

       155
       177
        
          </listitem>

     

       156
       178
        
          <listitem>

     

       157
       179
        
           <para>

     

       158
       158
       -
            This should already be enough for the postfix exporter. Additionally one could now add assertions and conditional default values. This can be done in the 'meta-module' that combines all exporter definitions and generates the submodules: <literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>

     

       180
       180
       +
            This should already be enough for the postfix exporter. Additionally one

     

       181
       181
       +
            could now add assertions and conditional default values. This can be done

     

       182
       182
       +
            in the 'meta-module' that combines all exporter definitions and generates

     

       183
       183
       +
            the submodules:

     

       184
       184
       +
            <literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>

     

       159
       185
        
           </para>

     

       160
       186
        
          </listitem>

     

       161
       187
        
         </itemizedlist>

     

       162
       188
        
        </section>

     

       163
       189
        
        <section xml:id="module-services-prometheus-exporters-update-exporter-module">

     

       164
       190
        
         <title>Updating an exporter module</title>

     

       165
       165
       -
       

     

       166
       166
       -
         <para>

     

       167
       167
       -
          Should an exporter option change at some point, it is possible to add information about the change to the exporter definition similar to <literal>nixpkgs/nixos/modules/rename.nix</literal>:

     

       191
       191
       +
          <para>

     

       192
       192
       +
            Should an exporter option change at some point, it is possible to add

     

       193
       193
       +
            information about the change to the exporter definition similar to

     

       194
       194
       +
            <literal>nixpkgs/nixos/modules/rename.nix</literal>:

     

       168
       195
        
       <programlisting>

     

       169
       196
        
       { config, lib, pkgs, options }:

     

       170
       197
        
       

     
···

       195
       222
        
         ];

     

       196
       223
        
       }

     

       197
       224
        
       </programlisting>

     

       198
       198
       -
         </para>

     

       199
       199
       -
        </section>

     

       225
       225
       +
           </para>

     

       226
       226
       +
         </section>

     

       200
       227
        
       </chapter>

+11 -3

nixos/modules/services/networking/dnscrypt-proxy.xml

···

       5
       5
        
                xml:id="sec-dnscrypt-proxy">

     

       6
       6
        
        <title>DNSCrypt client proxy</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         The DNSCrypt client proxy relays DNS queries to a DNSCrypt enabled upstream resolver. The traffic between the client and the upstream resolver is encrypted and authenticated, mitigating the risk of MITM attacks, DNS poisoning attacks, and third-party snooping (assuming the upstream is trustworthy).

     

       8
       8
       +
         The DNSCrypt client proxy relays DNS queries to a DNSCrypt enabled upstream

     

       9
       9
       +
         resolver. The traffic between the client and the upstream resolver is

     

       10
       10
       +
         encrypted and authenticated, mitigating the risk of MITM attacks, DNS

     

       11
       11
       +
         poisoning attacks, and third-party snooping (assuming the upstream is

     

       12
       12
       +
         trustworthy).

     

       9
       13
        
        </para>

     

       10
       14
        
        <sect1 xml:id="sec-dnscrypt-proxy-configuration">

     

       11
       15
        
         <title>Basic configuration</title>

     
···

       18
       22
        
         </para>

     

       19
       23
        
       

     

       20
       24
        
         <para>

     

       21
       21
       -
          Enabling the client proxy does not alter the system nameserver; to relay local queries, prepend <literal>127.0.0.1</literal> to <option>networking.nameservers</option>.

     

       25
       25
       +
          Enabling the client proxy does not alter the system nameserver; to relay

     

       26
       26
       +
          local queries, prepend <literal>127.0.0.1</literal> to

     

       27
       27
       +
          <option>networking.nameservers</option>.

     

       22
       28
        
         </para>

     

       23
       29
        
        </sect1>

     

       24
       30
        
        <sect1 xml:id="sec-dnscrypt-proxy-forwarder">

     

       25
       31
        
         <title>As a forwarder for another DNS client</title>

     

       26
       32
        
       

     

       27
       33
        
         <para>

     

       28
       28
       -
          To run the DNSCrypt proxy client as a forwarder for another DNS client, change the default proxy listening port to a non-standard value and point the other client to it:

     

       34
       34
       +
          To run the DNSCrypt proxy client as a forwarder for another DNS client,

     

       35
       35
       +
          change the default proxy listening port to a non-standard value and point

     

       36
       36
       +
          the other client to it:

     

       29
       37
        
       <programlisting>

     

       30
       38
        
       <xref linkend="opt-services.dnscrypt-proxy.localPort"/> = 43;

     

       31
       39
        
       </programlisting>

+45 -11

nixos/modules/services/web-apps/matomo-doc.xml

···

       5
       5
        
                xml:id="module-services-matomo">

     

       6
       6
        
        <title>Matomo</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         Matomo is a real-time web analytics application. This module configures php-fpm as backend for Matomo, optionally configuring an nginx vhost as well.

     

       8
       8
       +
         Matomo is a real-time web analytics application. This module configures

     

       9
       9
       +
         php-fpm as backend for Matomo, optionally configuring an nginx vhost as well.

     

       9
       10
        
        </para>

     

       10
       11
        
        <para>

     

       11
       11
       -
         An automatic setup is not suported by Matomo, so you need to configure Matomo itself in the browser-based Matomo setup.

     

       12
       12
       +
         An automatic setup is not suported by Matomo, so you need to configure Matomo

     

       13
       13
       +
         itself in the browser-based Matomo setup.

     

       12
       14
        
        </para>

     

       13
       15
        
        <section xml:id="module-services-matomo-database-setup">

     

       14
       16
        
         <title>Database Setup</title>

     

       15
       17
        
       

     

       16
       18
        
         <para>

     

       17
       17
       -
          You also need to configure a MariaDB or MySQL database and -user for Matomo yourself, and enter those credentials in your browser. You can use passwordless database authentication via the UNIX_SOCKET authentication plugin with the following SQL commands:

     

       19
       19
       +
          You also need to configure a MariaDB or MySQL database and -user for Matomo

     

       20
       20
       +
          yourself, and enter those credentials in your browser. You can use

     

       21
       21
       +
          passwordless database authentication via the UNIX_SOCKET authentication

     

       22
       22
       +
          plugin with the following SQL commands:

     

       18
       23
        
       <programlisting>

     

       19
       24
        
       # For MariaDB

     

       20
       25
        
       INSTALL PLUGIN unix_socket SONAME 'auth_socket';

     
···

       28
       33
        
       CREATE USER 'matomo'@'localhost' IDENTIFIED WITH auth_socket;

     

       29
       34
        
       GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';

     

       30
       35
        
       </programlisting>

     

       31
       31
       -
          Then fill in <literal>matomo</literal> as database user and database name, and leave the password field blank. This authentication works by allowing only the <literal>matomo</literal> unix user to authenticate as the <literal>matomo</literal> database user (without needing a password), but no other users. For more information on passwordless login, see <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/" />.

     

       36
       36
       +
          Then fill in <literal>matomo</literal> as database user and database name,

     

       37
       37
       +
          and leave the password field blank. This authentication works by allowing

     

       38
       38
       +
          only the <literal>matomo</literal> unix user to authenticate as the

     

       39
       39
       +
          <literal>matomo</literal> database user (without needing a password), but no

     

       40
       40
       +
          other users. For more information on passwordless login, see

     

       41
       41
       +
          <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/" />.

     

       32
       42
        
         </para>

     

       33
       43
        
       

     

       34
       44
        
         <para>

     

       35
       35
       -
          Of course, you can use password based authentication as well, e.g. when the database is not on the same host.

     

       45
       45
       +
          Of course, you can use password based authentication as well, e.g. when the

     

       46
       46
       +
          database is not on the same host.

     

       36
       47
        
         </para>

     

       37
       48
        
        </section>

     

       38
       49
        
        <section xml:id="module-services-matomo-archive-processing">

     

       39
       50
        
         <title>Archive Processing</title>

     

       40
       51
        
       

     

       41
       52
        
         <para>

     

       42
       42
       -
          This module comes with the systemd service <literal>matomo-archive-processing.service</literal> and a timer that automatically triggers archive processing every hour. This means that you can safely <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour"> disable browser triggers for Matomo archiving </link> at <literal>Administration > System > General Settings</literal>.

     

       53
       53
       +
          This module comes with the systemd service

     

       54
       54
       +
          <literal>matomo-archive-processing.service</literal> and a timer that

     

       55
       55
       +
          automatically triggers archive processing every hour. This means that you

     

       56
       56
       +
          can safely

     

       57
       57
       +
          <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour">

     

       58
       58
       +
          disable browser triggers for Matomo archiving </link> at

     

       59
       59
       +
          <literal>Administration > System > General Settings</literal>.

     

       43
       60
        
         </para>

     

       44
       61
        
       

     

       45
       62
        
         <para>

     

       46
       46
       -
          With automatic archive processing, you can now also enable to <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs"> delete old visitor logs </link> at <literal>Administration > System > Privacy</literal>, but make sure that you run <literal>systemctl start matomo-archive-processing.service</literal> at least once without errors if you have already collected data before, so that the reports get archived before the source data gets deleted.

     

       63
       63
       +
          With automatic archive processing, you can now also enable to

     

       64
       64
       +
          <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs">

     

       65
       65
       +
          delete old visitor logs </link> at <literal>Administration > System >

     

       66
       66
       +
          Privacy</literal>, but make sure that you run <literal>systemctl start

     

       67
       67
       +
          matomo-archive-processing.service</literal> at least once without errors if

     

       68
       68
       +
          you have already collected data before, so that the reports get archived

     

       69
       69
       +
          before the source data gets deleted.

     

       47
       70
        
         </para>

     

       48
       71
        
        </section>

     

       49
       72
        
        <section xml:id="module-services-matomo-backups">

     

       50
       73
        
         <title>Backup</title>

     

       51
       74
        
       

     

       52
       75
        
         <para>

     

       53
       53
       -
          You only need to take backups of your MySQL database and the <filename>/var/lib/matomo/config/config.ini.php</filename> file. Use a user in the <literal>matomo</literal> group or root to access the file. For more information, see <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" />.

     

       76
       76
       +
          You only need to take backups of your MySQL database and the

     

       77
       77
       +
          <filename>/var/lib/matomo/config/config.ini.php</filename> file. Use a user

     

       78
       78
       +
          in the <literal>matomo</literal> group or root to access the file. For more

     

       79
       79
       +
          information, see

     

       80
       80
       +
          <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" />.

     

       54
       81
        
         </para>

     

       55
       82
        
        </section>

     

       56
       83
        
        <section xml:id="module-services-matomo-issues">

     
···

       59
       86
        
         <itemizedlist>

     

       60
       87
        
          <listitem>

     

       61
       88
        
           <para>

     

       62
       62
       -
            Matomo's file integrity check will warn you. This is due to the patches necessary for NixOS, you can safely ignore this.

     

       89
       89
       +
            Matomo's file integrity check will warn you. This is due to the patches

     

       90
       90
       +
            necessary for NixOS, you can safely ignore this.

     

       63
       91
        
           </para>

     

       64
       92
        
          </listitem>

     

       65
       93
        
          <listitem>

     

       66
       94
        
           <para>

     

       67
       67
       -
            Matomo will warn you that the JavaScript tracker is not writable. This is because it's located in the read-only nix store. You can safely ignore this, unless you need a plugin that needs JavaScript tracker access.

     

       95
       95
       +
            Matomo will warn you that the JavaScript tracker is not writable. This is

     

       96
       96
       +
            because it's located in the read-only nix store. You can safely ignore

     

       97
       97
       +
            this, unless you need a plugin that needs JavaScript tracker access.

     

       68
       98
        
           </para>

     

       69
       99
        
          </listitem>

     

       70
       100
        
         </itemizedlist>

     
···

       73
       103
        
         <title>Using other Web Servers than nginx</title>

     

       74
       104
        
       

     

       75
       105
        
         <para>

     

       76
       76
       -
          You can use other web servers by forwarding calls for <filename>index.php</filename> and <filename>piwik.php</filename> to the <literal>/run/phpfpm-matomo.sock</literal> fastcgi unix socket. You can use the nginx configuration in the module code as a reference to what else should be configured.

     

       106
       106
       +
          You can use other web servers by forwarding calls for

     

       107
       107
       +
          <filename>index.php</filename> and <filename>piwik.php</filename> to the

     

       108
       108
       +
          <literal>/run/phpfpm-matomo.sock</literal> fastcgi unix socket. You can use

     

       109
       109
       +
          the nginx configuration in the module code as a reference to what else

     

       110
       110
       +
          should be configured.

     

       77
       111
        
         </para>

     

       78
       112
        
        </section>

     

       79
       113
        
       </chapter>

+41 -14

nixos/modules/services/web-apps/nextcloud.xml

···

       5
       5
        
                xml:id="module-services-nextcloud">

     

       6
       6
        
        <title>Nextcloud</title>

     

       7
       7
        
        <para>

     

       8
       8
       -
         <link xlink:href="https://nextcloud.com/">Nextcloud</link> is an open-source, self-hostable cloud platform. The server setup can be automated using <link linkend="opt-services.nextcloud.enable">services.nextcloud</link>. A desktop client is packaged at <literal>pkgs.nextcloud-client</literal>.

     

       8
       8
       +
         <link xlink:href="https://nextcloud.com/">Nextcloud</link> is an open-source,

     

       9
       9
       +
         self-hostable cloud platform. The server setup can be automated using

     

       10
       10
       +
         <link linkend="opt-services.nextcloud.enable">services.nextcloud</link>. A

     

       11
       11
       +
         desktop client is packaged at <literal>pkgs.nextcloud-client</literal>.

     

       9
       12
        
        </para>

     

       10
       13
        
        <section xml:id="module-services-nextcloud-basic-usage">

     

       11
       14
        
         <title>Basic usage</title>

     

       12
       15
        
       

     

       13
       16
        
         <para>

     

       14
       14
       -
          Nextcloud is a PHP-based application which requires an HTTP server (<literal><link linkend="opt-services.nextcloud.enable">services.nextcloud</link></literal> optionally supports <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>) and a database (it's recommended to use <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>).

     

       17
       17
       +
          Nextcloud is a PHP-based application which requires an HTTP server

     

       18
       18
       +
          (<literal><link linkend="opt-services.nextcloud.enable">services.nextcloud</link></literal>

     

       19
       19
       +
          optionally supports

     

       20
       20
       +
          <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>)

     

       21
       21
       +
          and a database (it's recommended to use

     

       22
       22
       +
          <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>).

     

       15
       23
        
         </para>

     

       16
       24
        
       

     

       17
       25
        
         <para>

     
···

       53
       61
        
         </para>

     

       54
       62
        
       

     

       55
       63
        
         <para>

     

       56
       56
       -
          The options <literal>hostName</literal> and <literal>nginx.enable</literal> are used internally to configure an HTTP server using <literal><link xlink:href="https://php-fpm.org/">PHP-FPM</link></literal> and <literal>nginx</literal>. The <literal>config</literal> attribute set is used by the imperative installer and all values are written to an additional file to ensure that changes can be applied by changing the module's options.

     

       64
       64
       +
          The options <literal>hostName</literal> and <literal>nginx.enable</literal>

     

       65
       65
       +
          are used internally to configure an HTTP server using

     

       66
       66
       +
          <literal><link xlink:href="https://php-fpm.org/">PHP-FPM</link></literal>

     

       67
       67
       +
          and <literal>nginx</literal>. The <literal>config</literal> attribute set is

     

       68
       68
       +
          used by the imperative installer and all values are written to an additional file

     

       69
       69
       +
          to ensure that changes can be applied by changing the module's options.

     

       57
       70
        
         </para>

     

       58
       71
        
       

     

       59
       72
        
         <para>

     

       60
       60
       -
          In case the application serves multiple domains (those are checked with <literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>) it's needed to add them to <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>.

     

       73
       73
       +
          In case the application serves multiple domains (those are checked with

     

       74
       74
       +
          <literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>)

     

       75
       75
       +
          it's needed to add them to

     

       76
       76
       +
          <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>.

     

       61
       77
        
         </para>

     

       62
       78
        
       

     

       63
       79
        
         <para>

     

       64
       64
       -
          Auto updates for Nextcloud apps can be enabled using <literal><link linkend="opt-services.nextcloud.autoUpdateApps.enable">services.nextcloud.autoUpdateApps</link></literal>.

     

       65
       65
       -
         </para>

     

       80
       80
       +
          Auto updates for Nextcloud apps can be enabled using

     

       81
       81
       +
          <literal><link linkend="opt-services.nextcloud.autoUpdateApps.enable">services.nextcloud.autoUpdateApps</link></literal>.

     

       82
       82
       +
       </para>

     

       83
       83
       +
       

     

       66
       84
        
        </section>

     

       67
       85
        
        <section xml:id="module-services-nextcloud-pitfalls-during-upgrade">

     

       68
       86
        
         <title>Pitfalls</title>

     

       69
       87
        
       

     

       70
       88
        
         <para>

     

       71
       71
       -
          Unfortunately Nextcloud appears to be very stateful when it comes to managing its own configuration. The config file lives in the home directory of the <literal>nextcloud</literal> user (by default <literal>/var/lib/nextcloud/config/config.php</literal>) and is also used to track several states of the application (e.g. whether installed or not).

     

       89
       89
       +
          Unfortunately Nextcloud appears to be very stateful when it comes to

     

       90
       90
       +
          managing its own configuration. The config file lives in the home directory

     

       91
       91
       +
          of the <literal>nextcloud</literal> user (by default

     

       92
       92
       +
          <literal>/var/lib/nextcloud/config/config.php</literal>) and is also used to

     

       93
       93
       +
          track several states of the application (e.g. whether installed or not).

     

       72
       94
        
         </para>

     

       73
       95
        
       

     

       74
       96
        
         <para>

     

       75
       75
       -
          All configuration parameters are also stored in <literal>/var/lib/nextcloud/config/override.config.php</literal> which is generated by the module and linked from the store to ensure that all values from <literal>config.php</literal> can be modified by the module. However <literal>config.php</literal> manages the application's state and shouldn't be touched manually because of that.

     

       97
       97
       +
          All configuration parameters are also stored in

     

       98
       98
       +
          <literal>/var/lib/nextcloud/config/override.config.php</literal> which is generated by

     

       99
       99
       +
          the module and linked from the store to ensure that all values from <literal>config.php</literal>

     

       100
       100
       +
          can be modified by the module.

     

       101
       101
       +
          However <literal>config.php</literal> manages the application's state and shouldn't be touched

     

       102
       102
       +
          manually because of that.

     

       76
       103
        
         </para>

     

       77
       104
        
       

     

       78
       105
        
         <warning>

     

       79
       79
       -
          <para>

     

       80
       80
       -
           Don't delete <literal>config.php</literal>! This file tracks the application's state and a deletion can cause unwanted side-effects!

     

       81
       81
       -
          </para>

     

       106
       106
       +
          <para>Don't delete <literal>config.php</literal>! This file

     

       107
       107
       +
          tracks the application's state and a deletion can cause unwanted

     

       108
       108
       +
          side-effects!</para>

     

       82
       109
        
         </warning>

     

       83
       110
        
       

     

       84
       111
        
         <warning>

     

       85
       85
       -
          <para>

     

       86
       86
       -
           Don't rerun <literal>nextcloud-occ maintenance:install</literal>! This command tries to install the application and can cause unwanted side-effects!

     

       87
       87
       -
          </para>

     

       112
       112
       +
          <para>Don't rerun <literal>nextcloud-occ

     

       113
       113
       +
          maintenance:install</literal>! This command tries to install the application

     

       114
       114
       +
          and can cause unwanted side-effects!</para>

     

       88
       115
        
         </warning>

     

       89
       116
        
        </section>

     

       90
       117
        
       </chapter>