commit a099ca45054940b63b1615920de158ebafb25ea8 · pyrox.dev/nixpkgs

+65

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-boot-problems">

     

       6
       +
       

     

       7
       +
       <title>Boot Problems</title>

     

       8
       +
       

     

       9
       +
       <para>If NixOS fails to boot, there are a number of kernel command

     

       10
       +
       line parameters that may help you to identify or fix the issue.  You

     

       11
       +
       can add these parameters in the GRUB boot menu by pressing “e” to

     

       12
       +
       modify the selected boot entry and editing the line starting with

     

       13
       +
       <literal>linux</literal>.  The following are some useful kernel command

     

       14
       +
       line parameters that are recognised by the NixOS boot scripts or by

     

       15
       +
       systemd:

     

       16
       +
       

     

       17
       +
       <variablelist>

     

       18
       +
       

     

       19
       +
         <varlistentry><term><literal>boot.shell_on_fail</literal></term>

     

       20
       +
           <listitem><para>Start a root shell if something goes wrong in

     

       21
       +
           stage 1 of the boot process (the initial ramdisk).  This is

     

       22
       +
           disabled by default because there is no authentication for the

     

       23
       +
           root shell.</para></listitem>

     

       24
       +
         </varlistentry>

     

       25
       +
       

     

       26
       +
         <varlistentry><term><literal>boot.debug1</literal></term>

     

       27
       +
           <listitem><para>Start an interactive shell in stage 1 before

     

       28
       +
           anything useful has been done.  That is, no modules have been

     

       29
       +
           loaded and no file systems have been mounted, except for

     

       30
       +
           <filename>/proc</filename> and

     

       31
       +
           <filename>/sys</filename>.</para></listitem>

     

       32
       +
         </varlistentry>

     

       33
       +
       

     

       34
       +
         <varlistentry><term><literal>boot.trace</literal></term>

     

       35
       +
           <listitem><para>Print every shell command executed by the stage 1

     

       36
       +
           and 2 boot scripts.</para></listitem>

     

       37
       +
         </varlistentry>

     

       38
       +
       

     

       39
       +
         <varlistentry><term><literal>single</literal></term>

     

       40
       +
           <listitem><para>Boot into rescue mode (a.k.a. single user mode).

     

       41
       +
           This will cause systemd to start nothing but the unit

     

       42
       +
           <literal>rescue.target</literal>, which runs

     

       43
       +
           <command>sulogin</command> to prompt for the root password and

     

       44
       +
           start a root login shell.  Exiting the shell causes the system to

     

       45
       +
           continue with the normal boot process.</para></listitem>

     

       46
       +
         </varlistentry>

     

       47
       +
       

     

       48
       +
         <varlistentry><term><literal>systemd.log_level=debug systemd.log_target=console</literal></term>

     

       49
       +
           <listitem><para>Make systemd very verbose and send log messages to

     

       50
       +
           the console instead of the journal.</para></listitem>

     

       51
       +
         </varlistentry>

     

       52
       +
       

     

       53
       +
       </variablelist>

     

       54
       +
       

     

       55
       +
       For more parameters recognised by systemd, see

     

       56
       +
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>

     

       57
       +
       

     

       58
       +
       <para>If no login prompts or X11 login screens appear (e.g. due to

     

       59
       +
       hanging dependencies), you can press Alt+ArrowUp.  If you’re lucky,

     

       60
       +
       this will start rescue mode (described above).  (Also note that since

     

       61
       +
       most units have a 90-second timeout before systemd gives up on them,

     

       62
       +
       the <command>agetty</command> login prompts should appear eventually

     

       63
       +
       unless something is very wrong.)</para>

     

       64
       +
       

     

       65
       +
       </section>

+62

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

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

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

     

       6
       +
       

     

       7
       +
       <title>Cleaning the Nix Store</title>

     

       8
       +
       

     

       9
       +
       <para>Nix has a purely functional model, meaning that packages are

     

       10
       +
       never upgraded in place.  Instead new versions of packages end up in a

     

       11
       +
       different location in the Nix store (<filename>/nix/store</filename>).

     

       12
       +
       You should periodically run Nix’s <emphasis>garbage

     

       13
       +
       collector</emphasis> to remove old, unreferenced packages.  This is

     

       14
       +
       easy:

     

       15
       +
       

     

       16
       +
       <screen>

     

       17
       +
       $ nix-collect-garbage

     

       18
       +
       </screen>

     

       19
       +
       

     

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

     

       21
       +
       background:

     

       22
       +
       

     

       23
       +
       <screen>

     

       24
       +
       $ systemctl start nix-gc.service

     

       25
       +
       </screen>

     

       26
       +
       

     

       27
       +
       You can tell NixOS in <filename>configuration.nix</filename> to run

     

       28
       +
       this unit automatically at certain points in time, for instance, every

     

       29
       +
       night at 03:15:

     

       30
       +
       

     

       31
       +
       <programlisting>

     

       32
       +
       nix.gc.automatic = true;

     

       33
       +
       nix.gc.dates = "03:15";

     

       34
       +
       </programlisting>

     

       35
       +
       

     

       36
       +
       </para>

     

       37
       +
       

     

       38
       +
       <para>The commands above do not remove garbage collector roots, such

     

       39
       +
       as old system configurations.  Thus they do not remove the ability to

     

       40
       +
       roll back to previous configurations.  The following command deletes

     

       41
       +
       old roots, removing the ability to roll back to them:

     

       42
       +
       <screen>

     

       43
       +
       $ nix-collect-garbage -d

     

       44
       +
       </screen>

     

       45
       +
       You can also do this for specific profiles, e.g.

     

       46
       +
       <screen>

     

       47
       +
       $ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old

     

       48
       +
       </screen>

     

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

     

       50
       +
       <filename>/nix/var/nix/profiles/system</filename>.</para>

     

       51
       +
       

     

       52
       +
       <para>Another way to reclaim disk space (often as much as 40% of the

     

       53
       +
       size of the Nix store) is to run Nix’s store optimiser, which seeks

     

       54
       +
       out identical files in the store and replaces them with hard links to

     

       55
       +
       a single copy.

     

       56
       +
       <screen>

     

       57
       +
       $ nix-store --optimise

     

       58
       +
       </screen>

     

       59
       +
       Since this command needs to read the entire Nix store, it can take

     

       60
       +
       quite a while to finish.</para>

     

       61
       +
       

     

       62
       +
       </chapter>

+50

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

···

       1
       +
       <section  xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                 version="5.0"

     

       5
       +
                 xml:id="sec-container-networking">

     

       6
       +
       

     

       7
       +
       

     

       8
       +
       <title>Container Networking</title>

     

       9
       +
       

     

       10
       +
       <para>When you create a container using <literal>nixos-container

     

       11
       +
       create</literal>, it gets it own private IPv4 address in the range

     

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

     

       13
       +
       address as follows:

     

       14
       +
       

     

       15
       +
       <screen>

     

       16
       +
       $ nixos-container show-ip foo

     

       17
       +
       10.233.4.2

     

       18
       +
       

     

       19
       +
       $ ping -c1 10.233.4.2

     

       20
       +
       64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms

     

       21
       +
       </screen>

     

       22
       +
       

     

       23
       +
       </para>

     

       24
       +
       

     

       25
       +
       <para>Networking is implemented using a pair of virtual Ethernet

     

       26
       +
       devices. The network interface in the container is called

     

       27
       +
       <literal>eth0</literal>, while the matching interface in the host is

     

       28
       +
       called <literal>ve-<replaceable>container-name</replaceable></literal>

     

       29
       +
       (e.g., <literal>ve-foo</literal>).  The container has its own network

     

       30
       +
       namespace and the <literal>CAP_NET_ADMIN</literal> capability, so it

     

       31
       +
       can perform arbitrary network configuration such as setting up

     

       32
       +
       firewall rules, without affecting or having access to the host’s

     

       33
       +
       network.</para>

     

       34
       +
       

     

       35
       +
       <para>By default, containers cannot talk to the outside network. If

     

       36
       +
       you want that, you should set up Network Address Translation (NAT)

     

       37
       +
       rules on the host to rewrite container traffic to use your external

     

       38
       +
       IP address. This can be accomplished using the following configuration

     

       39
       +
       on the host:

     

       40
       +
       

     

       41
       +
       <programlisting>

     

       42
       +
       networking.nat.enable = true;

     

       43
       +
       networking.nat.internalInterfaces = ["ve-+"];

     

       44
       +
       networking.nat.externalInterface = "eth0";

     

       45
       +
       </programlisting>

     

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

     

       47
       +
       external interface. Note that <literal>ve-+</literal> is a wildcard

     

       48
       +
       that matches all container interfaces.</para>

     

       49
       +
       

     

       50
       +
       </section>

+34

nixos/doc/manual/administration/containers.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

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

     

       6
       +
       

     

       7
       +
       <title>Container Management</title>

     

       8
       +
       

     

       9
       +
       <para>NixOS allows you to easily run other NixOS instances as

     

       10
       +
       <emphasis>containers</emphasis>. Containers are a light-weight

     

       11
       +
       approach to virtualisation that runs software in the container at the

     

       12
       +
       same speed as in the host system. NixOS containers share the Nix store

     

       13
       +
       of the host, making container creation very efficient.</para>

     

       14
       +
       

     

       15
       +
       <warning><para>Currently, NixOS containers are not perfectly isolated

     

       16
       +
       from the host system. This means that a user with root access to the

     

       17
       +
       container can do things that affect the host. So you should not give

     

       18
       +
       container root access to untrusted users.</para></warning>

     

       19
       +
       

     

       20
       +
       <para>NixOS containers can be created in two ways: imperatively, using

     

       21
       +
       the command <command>nixos-container</command>, and declaratively, by

     

       22
       +
       specifying them in your <filename>configuration.nix</filename>. The

     

       23
       +
       declarative approach implies that containers get upgraded along with

     

       24
       +
       your host system when you run <command>nixos-rebuild</command>, which

     

       25
       +
       is often not what you want. By contrast, in the imperative approach,

     

       26
       +
       containers are configured and updated independently from the host

     

       27
       +
       system.</para>

     

       28
       +
       

     

       29
       +
       <xi:include href="imperative-containers.xml" />

     

       30
       +
       <xi:include href="declarative-containers.xml" />

     

       31
       +
       <xi:include href="container-networking.xml" />

     

       32
       +
       

     

       33
       +
       </chapter>

     

       34
       +

+75

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

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

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

     

       6
       +
       

     

       7
       +
       <title>Control Groups</title>

     

       8
       +
       

     

       9
       +
       <para>To keep track of the processes in a running system, systemd uses

     

       10
       +
       <emphasis>control groups</emphasis> (cgroups).  A control group is a

     

       11
       +
       set of processes used to allocate resources such as CPU, memory or I/O

     

       12
       +
       bandwidth.  There can be multiple control group hierarchies, allowing

     

       13
       +
       each kind of resource to be managed independently.</para>

     

       14
       +
       

     

       15
       +
       <para>The command <command>systemd-cgls</command> lists all control

     

       16
       +
       groups in the <literal>systemd</literal> hierarchy, which is what

     

       17
       +
       systemd uses to keep track of the processes belonging to each service

     

       18
       +
       or user session:

     

       19
       +
       

     

       20
       +
       <screen>

     

       21
       +
       $ systemd-cgls

     

       22
       +
       ├─user

     

       23
       +
       │ └─eelco

     

       24
       +
       │   └─c1

     

       25
       +
       │     ├─ 2567 -:0

     

       26
       +
       │     ├─ 2682 kdeinit4: kdeinit4 Running...

     

       27
       +
       │     ├─ <replaceable>...</replaceable>

     

       28
       +
       │     └─10851 sh -c less -R

     

       29
       +
       └─system

     

       30
       +
         ├─httpd.service

     

       31
       +
         │ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH

     

       32
       +
         │ └─<replaceable>...</replaceable>

     

       33
       +
         ├─dhcpcd.service

     

       34
       +
         │ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf

     

       35
       +
         └─ <replaceable>...</replaceable>

     

       36
       +
       </screen>

     

       37
       +
       

     

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

     

       39
       +
       the CPU hierarchy, which allows per-cgroup CPU scheduling priorities.

     

       40
       +
       By default, every systemd service gets its own CPU cgroup, while all

     

       41
       +
       user sessions are in the top-level CPU cgroup.  This ensures, for

     

       42
       +
       instance, that a thousand run-away processes in the

     

       43
       +
       <literal>httpd.service</literal> cgroup cannot starve the CPU for one

     

       44
       +
       process in the <literal>postgresql.service</literal> cgroup.  (By

     

       45
       +
       contrast, it they were in the same cgroup, then the PostgreSQL process

     

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

     

       47
       +
       CPU share in <filename>configuration.nix</filename>:

     

       48
       +
       

     

       49
       +
       <programlisting>

     

       50
       +
       systemd.services.httpd.serviceConfig.CPUShares = 512;

     

       51
       +
       </programlisting>

     

       52
       +
       

     

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

     

       54
       +
       CPU allocation of the <literal>httpd.service</literal> cgroup.</para>

     

       55
       +
       

     

       56
       +
       <para>There also is a <literal>memory</literal> hierarchy that

     

       57
       +
       controls memory allocation limits; by default, all processes are in

     

       58
       +
       the top-level cgroup, so any service or session can exhaust all

     

       59
       +
       available memory.  Per-cgroup memory limits can be specified in

     

       60
       +
       <filename>configuration.nix</filename>; for instance, to limit

     

       61
       +
       <literal>httpd.service</literal> to 512 MiB of RAM (excluding swap)

     

       62
       +
       and 640 MiB of RAM (including swap):

     

       63
       +
       

     

       64
       +
       <programlisting>

     

       65
       +
       systemd.services.httpd.serviceConfig.MemoryLimit = "512M";

     

       66
       +
       systemd.services.httpd.serviceConfig.ControlGroupAttribute = [ "memory.memsw.limit_in_bytes 640M" ];

     

       67
       +
       </programlisting>

     

       68
       +
       

     

       69
       +
       </para>

     

       70
       +
       

     

       71
       +
       <para>The command <command>systemd-cgtop</command> shows a

     

       72
       +
       continuously updated list of all cgroups with their CPU and memory

     

       73
       +
       usage.</para>

     

       74
       +
       

     

       75
       +
       </chapter>

+52

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

···

       1
       +
       <section  xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                 version="5.0"

     

       5
       +
                 xml:id="sec-declarative-containers">

     

       6
       +
       

     

       7
       +
       <title>Declarative Container Specification</title>

     

       8
       +
       

     

       9
       +
       <para>You can also specify containers and their configuration in the

     

       10
       +
       host’s <filename>configuration.nix</filename>.  For example, the

     

       11
       +
       following specifies that there shall be a container named

     

       12
       +
       <literal>database</literal> running PostgreSQL:

     

       13
       +
       

     

       14
       +
       <programlisting>

     

       15
       +
       containers.database =

     

       16
       +
         { config =

     

       17
       +
             { config, pkgs, ... }:

     

       18
       +
             { services.postgresql.enable = true;

     

       19
       +
               services.postgresql.package = pkgs.postgresql92;

     

       20
       +
             };

     

       21
       +
         };

     

       22
       +
       </programlisting>

     

       23
       +
       

     

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

     

       25
       +
       be built and started. If the container was already running, it will be

     

       26
       +
       updated in place, without rebooting.</para>

     

       27
       +
       

     

       28
       +
       <para>By default, declarative containers share the network namespace

     

       29
       +
       of the host, meaning that they can listen on (privileged)

     

       30
       +
       ports. However, they cannot change the network configuration. You can

     

       31
       +
       give a container its own network as follows:

     

       32
       +
       

     

       33
       +
       <programlisting>

     

       34
       +
       containers.database =

     

       35
       +
         { privateNetwork = true;

     

       36
       +
           hostAddress = "192.168.100.10";

     

       37
       +
           localAddress = "192.168.100.11";

     

       38
       +
         };

     

       39
       +
       </programlisting>

     

       40
       +
       

     

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

     

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

     

       43
       +
       virtual Ethernet interface on the host with IP address

     

       44
       +
       <literal>192.168.100.10</literal>.  (See the next section for details

     

       45
       +
       on container networking.)</para>

     

       46
       +
       

     

       47
       +
       <para>To disable the container, just remove it from

     

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

     

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

     

       50
       +
       the container in <literal>/var/lib/containers</literal>.</para>

     

       51
       +
       

     

       52
       +
       </section>

+124

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

···

       1
       +
       <section  xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                 version="5.0"

     

       5
       +
                 xml:id="sec-imperative-containers">

     

       6
       +
       

     

       7
       +
       <title>Imperative Container Management</title>

     

       8
       +
       

     

       9
       +
       <para>We’ll cover imperative container management using

     

       10
       +
       <command>nixos-container</command> first. You create a container with

     

       11
       +
       identifier <literal>foo</literal> as follows:

     

       12
       +
       

     

       13
       +
       <screen>

     

       14
       +
       $ nixos-container create foo

     

       15
       +
       </screen>

     

       16
       +
       

     

       17
       +
       This creates the container’s root directory in

     

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

     

       19
       +
       file in <filename>/etc/containers/foo.conf</filename>. It also builds

     

       20
       +
       the container’s initial system configuration and stores it in

     

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

     

       22
       +
       can modify the initial configuration of the container on the command

     

       23
       +
       line. For instance, to create a container that has

     

       24
       +
       <command>sshd</command> running, with the given public key for

     

       25
       +
       <literal>root</literal>:

     

       26
       +
       

     

       27
       +
       <screen>

     

       28
       +
       $ nixos-container create foo --config 'services.openssh.enable = true; \

     

       29
       +
         users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];'

     

       30
       +
       </screen>

     

       31
       +
       

     

       32
       +
       </para>

     

       33
       +
       

     

       34
       +
       <para>Creating a container does not start it. To start the container,

     

       35
       +
       run:

     

       36
       +
       

     

       37
       +
       <screen>

     

       38
       +
       $ nixos-container start foo

     

       39
       +
       </screen>

     

       40
       +
       

     

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

     

       42
       +
       reached <literal>multi-user.target</literal>. On the host, the

     

       43
       +
       container runs within a systemd unit called

     

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

     

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

     

       46
       +
       <command>systemctl</command>:

     

       47
       +
       

     

       48
       +
       <screen>

     

       49
       +
       $ systemctl status container@foo

     

       50
       +
       </screen>

     

       51
       +
       

     

       52
       +
       </para>

     

       53
       +
       

     

       54
       +
       <para>If the container has started succesfully, you can log in as

     

       55
       +
       root using the <command>root-login</command> operation:

     

       56
       +
       

     

       57
       +
       <screen>

     

       58
       +
       $ nixos-container root-login foo

     

       59
       +
       [root@foo:~]#

     

       60
       +
       </screen>

     

       61
       +
       

     

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

     

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

     

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

     

       65
       +
       the host:

     

       66
       +
       

     

       67
       +
       <screen>

     

       68
       +
       $ nixos-container login foo

     

       69
       +
       foo login: alice

     

       70
       +
       Password: ***

     

       71
       +
       </screen>

     

       72
       +
       

     

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

     

       74
       +
       commands in the container:

     

       75
       +
       

     

       76
       +
       <screen>

     

       77
       +
       $ nixos-container run foo -- uname -a

     

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

     

       79
       +
       </screen>

     

       80
       +
       

     

       81
       +
       </para>

     

       82
       +
       

     

       83
       +
       <para>There are several ways to change the configuration of the

     

       84
       +
       container. First, on the host, you can edit

     

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

     

       86
       +
       and run

     

       87
       +
       

     

       88
       +
       <screen>

     

       89
       +
       $ nixos-container update foo

     

       90
       +
       </screen>

     

       91
       +
       

     

       92
       +
       This will build and activate the new configuration. You can also

     

       93
       +
       specify a new configuration on the command line:

     

       94
       +
       

     

       95
       +
       <screen>

     

       96
       +
       $ nixos-container update foo --config 'services.httpd.enable = true; \

     

       97
       +
         services.httpd.adminAddr = "foo@example.org";'

     

       98
       +
       

     

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

     

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

     

       101
       +
       </screen>

     

       102
       +
       

     

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

     

       104
       +
       <filename>/etc/nixos/configuration.nix</filename>.</para>

     

       105
       +
       

     

       106
       +
       <para>Alternatively, you can change the configuration from within the

     

       107
       +
       container itself by running <command>nixos-rebuild switch</command>

     

       108
       +
       inside the container. Note that the container by default does not have

     

       109
       +
       a copy of the NixOS channel, so you should run <command>nix-channel

     

       110
       +
       --update</command> first.</para>

     

       111
       +
       

     

       112
       +
       <para>Containers can be stopped and started using

     

       113
       +
       <literal>nixos-container stop</literal> and <literal>nixos-container

     

       114
       +
       start</literal>, respectively, or by using

     

       115
       +
       <command>systemctl</command> on the container’s service unit. To

     

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

     

       117
       +
       

     

       118
       +
       <screen>

     

       119
       +
       $ nixos-container destroy foo

     

       120
       +
       </screen>

     

       121
       +
       

     

       122
       +
       </para>

     

       123
       +
       

     

       124
       +
       </section>

+52

nixos/doc/manual/administration/logging.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

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

     

       6
       +
       

     

       7
       +
       <title>Logging</title>

     

       8
       +
       

     

       9
       +
       <para>System-wide logging is provided by systemd’s

     

       10
       +
       <emphasis>journal</emphasis>, which subsumes traditional logging

     

       11
       +
       daemons such as syslogd and klogd.  Log entries are kept in binary

     

       12
       +
       files in <filename>/var/log/journal/</filename>.  The command

     

       13
       +
       <literal>journalctl</literal> allows you to see the contents of the

     

       14
       +
       journal.  For example,

     

       15
       +
       

     

       16
       +
       <screen>

     

       17
       +
       $ journalctl -b

     

       18
       +
       </screen>

     

       19
       +
       

     

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

     

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

     

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

     

       23
       +
       output to messages of interest.  For instance, to get all messages

     

       24
       +
       from PostgreSQL:

     

       25
       +
       

     

       26
       +
       <screen>

     

       27
       +
       $ journalctl -u postgresql.service

     

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

     

       29
       +
       ...

     

       30
       +
       Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG:  database system is shut down

     

       31
       +
       -- Reboot --

     

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

     

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

     

       34
       +
       </screen>

     

       35
       +
       

     

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

     

       37
       +
       “critical” severity level:

     

       38
       +
       

     

       39
       +
       <screen>

     

       40
       +
       $ journalctl -b -p crit

     

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

     

       42
       +
       Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1)

     

       43
       +
       </screen>

     

       44
       +
       

     

       45
       +
       </para>

     

       46
       +
       

     

       47
       +
       <para>The system journal is readable by root and by users in the

     

       48
       +
       <literal>wheel</literal> and <literal>systemd-journal</literal>

     

       49
       +
       groups.  All users have a private journal that can be read using

     

       50
       +
       <command>journalctl</command>.</para>

     

       51
       +
       

     

       52
       +
       </chapter>

+18

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-maintenance-mode">

     

       6
       +
       

     

       7
       +
       <title>Maintenance Mode</title>

     

       8
       +
       

     

       9
       +
       <para>You can enter rescue mode by running:

     

       10
       +
       

     

       11
       +
       <screen>

     

       12
       +
       $ systemctl rescue</screen>

     

       13
       +
       

     

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

     

       15
       +
       stop (almost) all system services.  To get out of maintenance mode,

     

       16
       +
       just exit from the rescue shell.</para>

     

       17
       +
       

     

       18
       +
       </section>

+33

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-nix-network-issues">

     

       6
       +
       

     

       7
       +
       <title>Network Problems</title>

     

       8
       +
       

     

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

     

       10
       +
       optimise building a package from source into downloading it as a

     

       11
       +
       pre-built binary.  That is, whenever a command like

     

       12
       +
       <command>nixos-rebuild</command> needs a path in the Nix store, Nix

     

       13
       +
       will try to download that path from the Internet rather than build it

     

       14
       +
       from source.  The default binary cache is

     

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

     

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

     

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

     

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

     

       19
       +
       

     

       20
       +
       <screen>

     

       21
       +
       $ nixos-rebuild switch --option use-binary-caches false

     

       22
       +
       </screen>

     

       23
       +
       

     

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

     

       25
       +
       it instead:

     

       26
       +
       

     

       27
       +
       <screen>

     

       28
       +
       $ nixos-rebuild switch --option binary-caches http://my-cache.example.org/

     

       29
       +
       </screen>

     

       30
       +
       

     

       31
       +
       </para>

     

       32
       +
       

     

       33
       +
       </section>

+44

nixos/doc/manual/administration/rebooting.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-rebooting">

     

       6
       +
       

     

       7
       +
       <title>Rebooting and Shutting Down</title>

     

       8
       +
       

     

       9
       +
       <para>The system can be shut down (and automatically powered off) by

     

       10
       +
       doing:

     

       11
       +
       

     

       12
       +
       <screen>

     

       13
       +
       $ shutdown

     

       14
       +
       </screen>

     

       15
       +
       

     

       16
       +
       This is equivalent to running <command>systemctl

     

       17
       +
       poweroff</command>.</para>

     

       18
       +
       

     

       19
       +
       <para>To reboot the system, run

     

       20
       +
       

     

       21
       +
       <screen>

     

       22
       +
       $ reboot

     

       23
       +
       </screen>

     

       24
       +
       

     

       25
       +
       which is equivalent to <command>systemctl reboot</command>.

     

       26
       +
       Alternatively, you can quickly reboot the system using

     

       27
       +
       <literal>kexec</literal>, which bypasses the BIOS by directly loading

     

       28
       +
       the new kernel into memory:

     

       29
       +
       

     

       30
       +
       <screen>

     

       31
       +
       $ systemctl kexec

     

       32
       +
       </screen>

     

       33
       +
       

     

       34
       +
       </para>

     

       35
       +
       

     

       36
       +
       <para>The machine can be suspended to RAM (if supported) using

     

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

     

       38
       +
       <command>systemctl hibernate</command>.</para>

     

       39
       +
       

     

       40
       +
       <para>These commands can be run by any user who is logged in locally,

     

       41
       +
       i.e. on a virtual console or in X11; otherwise, the user is asked for

     

       42
       +
       authentication.</para>

     

       43
       +
       

     

       44
       +
       </chapter>

+48

nixos/doc/manual/administration/rollback.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-rollback">

     

       6
       +
       

     

       7
       +
       <title>Rolling Back Configuration Changes</title>

     

       8
       +
       

     

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

     

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

     

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

     

       12
       +
       previous configuration.</para>

     

       13
       +
       

     

       14
       +
       <para>First, the GRUB boot manager allows you to boot into any

     

       15
       +
       previous configuration that hasn’t been garbage-collected.  These

     

       16
       +
       configurations can be found under the GRUB submenu “NixOS - All

     

       17
       +
       configurations”.  This is especially useful if the new configuration

     

       18
       +
       fails to boot.  After the system has booted, you can make the selected

     

       19
       +
       configuration the default for subsequent boots:

     

       20
       +
       

     

       21
       +
       <screen>

     

       22
       +
       $ /run/current-system/bin/switch-to-configuration boot</screen>

     

       23
       +
       

     

       24
       +
       </para>

     

       25
       +
       

     

       26
       +
       <para>Second, you can switch to the previous configuration in a running

     

       27
       +
       system:

     

       28
       +
       

     

       29
       +
       <screen>

     

       30
       +
       $ nixos-rebuild switch --rollback</screen>

     

       31
       +
       

     

       32
       +
       This is equivalent to running:

     

       33
       +
       

     

       34
       +
       <screen>

     

       35
       +
       $ /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>

     

       36
       +
       

     

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

     

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

     

       39
       +
       

     

       40
       +
       <screen>

     

       41
       +
       $ ls -l /nix/var/nix/profiles/system-*-link

     

       42
       +
       <replaceable>...</replaceable>

     

       43
       +
       lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055

     

       44
       +
       </screen>

     

       45
       +
       

     

       46
       +
       </para>

     

       47
       +
       

     

       48
       +
       </section>

+24

nixos/doc/manual/administration/running.xml

···

       1
       +
       <part xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
             version="5.0"

     

       5
       +
             xml:id="ch-running">

     

       6
       +
       

     

       7
       +
       <title>Administration</title>

     

       8
       +
       

     

       9
       +
       <partintro>

     

       10
       +
       <para>This chapter describes various aspects of managing a running

     

       11
       +
       NixOS system, such as how to use the <command>systemd</command>

     

       12
       +
       service manager.</para>

     

       13
       +
       </partintro>

     

       14
       +
       

     

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

     

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

     

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

     

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

     

       19
       +
       <xi:include href="logging.xml" />

     

       20
       +
       <xi:include href="cleaning-store.xml" />

     

       21
       +
       <xi:include href="containers.xml" />

     

       22
       +
       <xi:include href="troubleshooting.xml" />

     

       23
       +
       

     

       24
       +
       </part>

+83

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

···

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

     

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

     

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

     

       4
       +
                version="5.0"

     

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

     

       6
       +
       

     

       7
       +
       <title>Service Management</title>

     

       8
       +
       

     

       9
       +
       <para>In NixOS, all system services are started and monitored using

     

       10
       +
       the systemd program.  Systemd is the “init” process of the system

     

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

     

       12
       +
       so-called “units”, which can be things like system services

     

       13
       +
       (programs), but also mount points, swap files, devices, targets

     

       14
       +
       (groups of units) and more.  Units can have complex dependencies; for

     

       15
       +
       instance, one unit can require that another unit must be successfully

     

       16
       +
       started before the first unit can be started.  When the system boots,

     

       17
       +
       it starts a unit named <literal>default.target</literal>; the

     

       18
       +
       dependencies of this unit cause all system services to be started,

     

       19
       +
       file systems to be mounted, swap files to be activated, and so

     

       20
       +
       on.</para>

     

       21
       +
       

     

       22
       +
       <para>The command <command>systemctl</command> is the main way to

     

       23
       +
       interact with <command>systemd</command>.  Without any arguments, it

     

       24
       +
       shows the status of active units:

     

       25
       +
       

     

       26
       +
       <screen>

     

       27
       +
       $ systemctl

     

       28
       +
       -.mount          loaded active mounted   /

     

       29
       +
       swapfile.swap    loaded active active    /swapfile

     

       30
       +
       sshd.service     loaded active running   SSH Daemon

     

       31
       +
       graphical.target loaded active active    Graphical Interface

     

       32
       +
       <replaceable>...</replaceable>

     

       33
       +
       </screen>

     

       34
       +
       

     

       35
       +
       </para>

     

       36
       +
       

     

       37
       +
       <para>You can ask for detailed status information about a unit, for

     

       38
       +
       instance, the PostgreSQL database service:

     

       39
       +
       

     

       40
       +
       <screen>

     

       41
       +
       $ systemctl status postgresql.service

     

       42
       +
       postgresql.service - PostgreSQL Server

     

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

     

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

     

       45
       +
               Main PID: 2390 (postgres)

     

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

     

       47
       +
                         ├─2390 postgres

     

       48
       +
                         ├─2418 postgres: writer process

     

       49
       +
                         ├─2419 postgres: wal writer process

     

       50
       +
                         ├─2420 postgres: autovacuum launcher process

     

       51
       +
                         ├─2421 postgres: stats collector process

     

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

     

       53
       +
       

     

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

     

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

     

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

     

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

     

       58
       +
       </screen>

     

       59
       +
       

     

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

     

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

     

       62
       +
       messages from the service.

     

       63
       +
       

     

       64
       +
       </para>

     

       65
       +
       

     

       66
       +
       <para>Units can be stopped, started or restarted:

     

       67
       +
       

     

       68
       +
       <screen>

     

       69
       +
       $ systemctl stop postgresql.service

     

       70
       +
       $ systemctl start postgresql.service

     

       71
       +
       $ systemctl restart postgresql.service

     

       72
       +
       </screen>

     

       73
       +
       

     

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

     

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

     

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

     

       77
       +
       necessary).</para>

     

       78
       +
       

     

       79
       +
       <!-- - cgroups: each service and user session is a cgroup

     

       80
       +
       

     

       81
       +
       - cgroup resource management -->

     

       82
       +
       

     

       83
       +
       </chapter>

+37

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-nix-store-corruption">

     

       6
       +
       

     

       7
       +
       <title>Nix Store Corruption</title>

     

       8
       +
       

     

       9
       +
       <para>After a system crash, it’s possible for files in the Nix store

     

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

     

       11
       +
       tendency to replace un-synced files with zero bytes.)  NixOS tries

     

       12
       +
       hard to prevent this from happening: it performs a

     

       13
       +
       <command>sync</command> before switching to a new configuration, and

     

       14
       +
       Nix’s database is fully transactional.  If corruption still occurs,

     

       15
       +
       you may be able to fix it automatically.</para>

     

       16
       +
       

     

       17
       +
       <para>If the corruption is in a path in the closure of the NixOS

     

       18
       +
       system configuration, you can fix it by doing

     

       19
       +
       

     

       20
       +
       <screen>

     

       21
       +
       $ nixos-rebuild switch --repair

     

       22
       +
       </screen>

     

       23
       +
       

     

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

     

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

     

       26
       +
       the path is rebuilt or redownloaded.</para>

     

       27
       +
       

     

       28
       +
       <para>You can also scan the entire Nix store for corrupt paths:

     

       29
       +
       

     

       30
       +
       <screen>

     

       31
       +
       $ nix-store --verify --check-contents --repair

     

       32
       +
       </screen>

     

       33
       +
       

     

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

     

       35
       +
       binary cache; otherwise, they cannot be repaired.</para>

     

       36
       +
       

     

       37
       +
       </section>

+18

nixos/doc/manual/administration/troubleshooting.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

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

     

       6
       +
       

     

       7
       +
       <title>Troubleshooting</title>

     

       8
       +
       

     

       9
       +
       <para>This chapter describes solutions to common problems you might

     

       10
       +
       encounter when you manage your NixOS system.</para>

     

       11
       +
       

     

       12
       +
       <xi:include href="boot-problems.xml" />

     

       13
       +
       <xi:include href="maintenance-mode.xml" />

     

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

     

       15
       +
       <xi:include href="store-corruption.xml" />

     

       16
       +
       <xi:include href="network-problems.xml" />

     

       17
       +
       

     

       18
       +
       </chapter>

+53

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

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

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

     

       6
       +
       

     

       7
       +
       <title>User Sessions</title>

     

       8
       +
       

     

       9
       +
       <para>Systemd keeps track of all users who are logged into the system

     

       10
       +
       (e.g. on a virtual console or remotely via SSH).  The command

     

       11
       +
       <command>loginctl</command> allows querying and manipulating user

     

       12
       +
       sessions.  For instance, to list all user sessions:

     

       13
       +
       

     

       14
       +
       <screen>

     

       15
       +
       $ loginctl

     

       16
       +
          SESSION        UID USER             SEAT

     

       17
       +
               c1        500 eelco            seat0

     

       18
       +
               c3          0 root             seat0

     

       19
       +
               c4        500 alice

     

       20
       +
       </screen>

     

       21
       +
       

     

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

     

       23
       +
       logged in remotely.  (“Seats” are essentially the combinations of

     

       24
       +
       displays and input devices attached to the system; usually, there is

     

       25
       +
       only one seat.)  To get information about a session:

     

       26
       +
       

     

       27
       +
       <screen>

     

       28
       +
       $ loginctl session-status c3

     

       29
       +
       c3 - root (0)

     

       30
       +
                  Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago

     

       31
       +
                 Leader: 2536 (login)

     

       32
       +
                   Seat: seat0; vc3

     

       33
       +
                    TTY: /dev/tty3

     

       34
       +
                Service: login; type tty; class user

     

       35
       +
                  State: online

     

       36
       +
                 CGroup: name=systemd:/user/root/c3

     

       37
       +
                         ├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login --

     

       38
       +
                         ├─10339 -bash

     

       39
       +
                         └─10355 w3m nixos.org

     

       40
       +
       </screen>

     

       41
       +
       

     

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

     

       43
       +
       lists the processes belonging to this session.  Since systemd keeps

     

       44
       +
       track of this, you can terminate a session in a way that ensures that

     

       45
       +
       all the session’s processes are gone:

     

       46
       +
       

     

       47
       +
       <screen>

     

       48
       +
       $ loginctl terminate-session c3

     

       49
       +
       </screen>

     

       50
       +
       

     

       51
       +
       </para>

     

       52
       +
       

     

       53
       +
       </chapter>

-1563

nixos/doc/manual/configuration.xml

···

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

     

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

     

       3
       -
                xml:id="ch-configuration">

     

       4
       -
       

     

       5
       -
       <title>Configuring NixOS</title>

     

       6
       -
       

     

       7
       -
       <para>This chapter describes how to configure various aspects of a

     

       8
       -
       NixOS machine through the configuration file

     

       9
       -
       <filename>/etc/nixos/configuration.nix</filename>.  As described in

     

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

     

       11
       -
       effect after you run <command>nixos-rebuild</command>.</para>

     

       12
       -
       

     

       13
       -
       

     

       14
       -
       <!--===============================================================-->

     

       15
       -
       

     

       16
       -
       <section xml:id="sec-configuration-syntax"><title>Configuration syntax</title>

     

       17
       -
       

     

       18
       -
       <section><title>The basics</title>

     

       19
       -
       

     

       20
       -
       <para>The NixOS configuration file

     

       21
       -
       <filename>/etc/nixos/configuration.nix</filename> is actually a

     

       22
       -
       <emphasis>Nix expression</emphasis>, which is the Nix package

     

       23
       -
       manager’s purely functional language for describing how to build

     

       24
       -
       packages and configurations.  This means you have all the expressive

     

       25
       -
       power of that language at your disposal, including the ability to

     

       26
       -
       abstract over common patterns, which is very useful when managing

     

       27
       -
       complex systems.  The syntax and semantics of the Nix language are

     

       28
       -
       fully described in the <link

     

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

     

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

     

       31
       -
       constructs useful in NixOS configuration files.</para>

     

       32
       -
       

     

       33
       -
       <para>The NixOS configuration file generally looks like this:

     

       34
       -
       

     

       35
       -
       <programlisting>

     

       36
       -
       { config, pkgs, ... }:

     

       37
       -
       

     

       38
       -
       { <replaceable>option definitions</replaceable>

     

       39
       -
       }

     

       40
       -
       </programlisting>

     

       41
       -
       

     

       42
       -
       The first line (<literal>{ config, pkgs, ... }:</literal>) denotes

     

       43
       -
       that this is actually a function that takes at least the two arguments

     

       44
       -
        <varname>config</varname> and <varname>pkgs</varname>.  (These are

     

       45
       -
       explained later.)  The function returns a <emphasis>set</emphasis> of

     

       46
       -
       option definitions (<literal>{ <replaceable>...</replaceable> }</literal>).  These definitions have the

     

       47
       -
       form <literal><replaceable>name</replaceable> =

     

       48
       -
       <replaceable>value</replaceable></literal>, where

     

       49
       -
       <replaceable>name</replaceable> is the name of an option and

     

       50
       -
       <replaceable>value</replaceable> is its value.  For example,

     

       51
       -
       

     

       52
       -
       <programlisting>

     

       53
       -
       { config, pkgs, ... }:

     

       54
       -
       

     

       55
       -
       { services.httpd.enable = true;

     

       56
       -
         services.httpd.adminAddr = "alice@example.org";

     

       57
       -
         services.httpd.documentRoot = "/webroot";

     

       58
       -
       }

     

       59
       -
       </programlisting>

     

       60
       -
       

     

       61
       -
       defines a configuration with three option definitions that together

     

       62
       -
       enable the Apache HTTP Server with <filename>/webroot</filename> as

     

       63
       -
       the document root.</para>

     

       64
       -
       

     

       65
       -
       <para>Sets can be nested, and in fact dots in option names are

     

       66
       -
       shorthand for defining a set containing another set.  For instance,

     

       67
       -
       <option>services.httpd.enable</option> defines a set named

     

       68
       -
       <varname>services</varname> that contains a set named

     

       69
       -
       <varname>httpd</varname>, which in turn contains an option definition

     

       70
       -
       named <varname>enable</varname> with value <literal>true</literal>.

     

       71
       -
       This means that the example above can also be written as:

     

       72
       -
       

     

       73
       -
       <programlisting>

     

       74
       -
       { config, pkgs, ... }:

     

       75
       -
       

     

       76
       -
       { services = {

     

       77
       -
           httpd = {

     

       78
       -
             enable = true;

     

       79
       -
             adminAddr = "alice@example.org";

     

       80
       -
             documentRoot = "/webroot";

     

       81
       -
           };

     

       82
       -
         };

     

       83
       -
       }

     

       84
       -
       </programlisting>

     

       85
       -
       

     

       86
       -
       which may be more convenient if you have lots of option definitions

     

       87
       -
       that share the same prefix (such as

     

       88
       -
       <literal>services.httpd</literal>).</para>

     

       89
       -
       

     

       90
       -
       <para>NixOS checks your option definitions for correctness.  For

     

       91
       -
       instance, if you try to define an option that doesn’t exist (that is,

     

       92
       -
       doesn’t have a corresponding <emphasis>option declaration</emphasis>),

     

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

     

       94
       -
       <screen>

     

       95
       -
       The option `services.httpd.enabl' defined in `/etc/nixos/configuration.nix' does not exist.

     

       96
       -
       </screen>

     

       97
       -
       Likewise, values in option definitions must have a correct type.  For

     

       98
       -
       instance, <option>services.httpd.enable</option> must be a Boolean

     

       99
       -
       (<literal>true</literal> or <literal>false</literal>).  Trying to give

     

       100
       -
       it a value of another type, such as a string, will cause an error:

     

       101
       -
       <screen>

     

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

     

       103
       -
       </screen>

     

       104
       -
       

     

       105
       -
       </para>

     

       106
       -
       

     

       107
       -
       <para>Options have various types of values.  The most important are:

     

       108
       -
       

     

       109
       -
       <variablelist>

     

       110
       -
         <varlistentry>

     

       111
       -
           <term>Strings</term>

     

       112
       -
           <listitem>

     

       113
       -
             <para>Strings are enclosed in double quotes, e.g.

     

       114
       -
       

     

       115
       -
       <programlisting>

     

       116
       -
       networking.hostName = "dexter";

     

       117
       -
       </programlisting>

     

       118
       -
       

     

       119
       -
             Special characters can be escaped by prefixing them with a

     

       120
       -
             backslash (e.g. <literal>\"</literal>).</para>

     

       121
       -
       

     

       122
       -
             <para>Multi-line strings can be enclosed in <emphasis>double

     

       123
       -
             single quotes</emphasis>, e.g.

     

       124
       -
       

     

       125
       -
       <programlisting>

     

       126
       -
       networking.extraHosts =

     

       127
       -
         ''

     

       128
       -
           127.0.0.2 other-localhost

     

       129
       -
           10.0.0.1 server

     

       130
       -
         '';

     

       131
       -
       </programlisting>

     

       132
       -
       

     

       133
       -
             The main difference is that preceding whitespace is

     

       134
       -
             automatically stripped from each line, and that characters like

     

       135
       -
             <literal>"</literal> and <literal>\</literal> are not special

     

       136
       -
             (making it more convenient for including things like shell

     

       137
       -
             code).</para>

     

       138
       -
           </listitem>

     

       139
       -
         </varlistentry>

     

       140
       -
       

     

       141
       -
         <varlistentry>

     

       142
       -
           <term>Booleans</term>

     

       143
       -
           <listitem>

     

       144
       -
             <para>These can be <literal>true</literal> or

     

       145
       -
             <literal>false</literal>, e.g.

     

       146
       -
       

     

       147
       -
       <programlisting>

     

       148
       -
       networking.firewall.enable = true;

     

       149
       -
       networking.firewall.allowPing = false;

     

       150
       -
       </programlisting>

     

       151
       -
             </para>

     

       152
       -
           </listitem>

     

       153
       -
         </varlistentry>

     

       154
       -
       

     

       155
       -
         <varlistentry>

     

       156
       -
           <term>Integers</term>

     

       157
       -
           <listitem>

     

       158
       -
             <para>For example,

     

       159
       -
       

     

       160
       -
       <programlisting>

     

       161
       -
       boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;

     

       162
       -
       </programlisting>

     

       163
       -
       

     

       164
       -
             (Note that here the attribute name

     

       165
       -
             <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in

     

       166
       -
             quotes to prevent it from being interpreted as a set named

     

       167
       -
             <literal>net</literal> containing a set named

     

       168
       -
             <literal>ipv4</literal>, and so on.  This is because it’s not a

     

       169
       -
             NixOS option but the literal name of a Linux kernel

     

       170
       -
             setting.)</para>

     

       171
       -
           </listitem>

     

       172
       -
         </varlistentry>

     

       173
       -
       

     

       174
       -
         <varlistentry>

     

       175
       -
           <term>Sets</term>

     

       176
       -
           <listitem>

     

       177
       -
             <para>Sets were introduced above.  They are name/value pairs

     

       178
       -
             enclosed in braces, as in the option definition

     

       179
       -
       

     

       180
       -
       <programlisting>

     

       181
       -
       fileSystems."/boot" =

     

       182
       -
         { device = "/dev/sda1";

     

       183
       -
           fsType = "ext4";

     

       184
       -
           options = "rw,data=ordered,relatime";

     

       185
       -
         };

     

       186
       -
       </programlisting>

     

       187
       -
             </para>

     

       188
       -
           </listitem>

     

       189
       -
         </varlistentry>

     

       190
       -
       

     

       191
       -
         <varlistentry>

     

       192
       -
           <term>Lists</term>

     

       193
       -
           <listitem>

     

       194
       -
             <para>The important thing to note about lists is that list

     

       195
       -
             elements are separated by whitespace, like this:

     

       196
       -
       

     

       197
       -
       <programlisting>

     

       198
       -
       boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];

     

       199
       -
       </programlisting>

     

       200
       -
       

     

       201
       -
             List elements can be any other type, e.g. sets:

     

       202
       -
       

     

       203
       -
       <programlisting>

     

       204
       -
       swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];

     

       205
       -
       </programlisting>

     

       206
       -
             </para>

     

       207
       -
           </listitem>

     

       208
       -
         </varlistentry>

     

       209
       -
       

     

       210
       -
         <varlistentry>

     

       211
       -
           <term>Packages</term>

     

       212
       -
           <listitem>

     

       213
       -
             <para>Usually, the packages you need are already part of the Nix

     

       214
       -
             Packages collection, which is a set that can be accessed through

     

       215
       -
             the function argument <varname>pkgs</varname>.  Typical uses:

     

       216
       -
       

     

       217
       -
       <programlisting>

     

       218
       -
       environment.systemPackages =

     

       219
       -
         [ pkgs.thunderbird

     

       220
       -
           pkgs.emacs

     

       221
       -
         ];

     

       222
       -
       

     

       223
       -
       postgresql.package = pkgs.postgresql90;

     

       224
       -
       </programlisting>

     

       225
       -
       

     

       226
       -
             The latter option definition changes the default PostgreSQL

     

       227
       -
             package used by NixOS’s PostgreSQL service to 9.0.  For more

     

       228
       -
             information on packages, including how to add new ones, see

     

       229
       -
             <xref linkend="sec-custom-packages"/>.</para>

     

       230
       -
           </listitem>

     

       231
       -
         </varlistentry>

     

       232
       -
       

     

       233
       -
       </variablelist>

     

       234
       -
       

     

       235
       -
       </para>

     

       236
       -
       

     

       237
       -
       </section>

     

       238
       -
       

     

       239
       -
       

     

       240
       -
       <section xml:id="sec-module-abstractions"><title>Abstractions</title>

     

       241
       -
       

     

       242
       -
       <para>If you find yourself repeating yourself over and over, it’s time

     

       243
       -
       to abstract.  Take, for instance, this Apache HTTP Server configuration:

     

       244
       -
       

     

       245
       -
       <programlisting>

     

       246
       -
       {

     

       247
       -
         services.httpd.virtualHosts =

     

       248
       -
           [ { hostName = "example.org";

     

       249
       -
               documentRoot = "/webroot";

     

       250
       -
               adminAddr = "alice@example.org";

     

       251
       -
               enableUserDir = true;

     

       252
       -
             }

     

       253
       -
             { hostName = "example.org";

     

       254
       -
               documentRoot = "/webroot";

     

       255
       -
               adminAddr = "alice@example.org";

     

       256
       -
               enableUserDir = true;

     

       257
       -
               enableSSL = true;

     

       258
       -
               sslServerCert = "/root/ssl-example-org.crt";

     

       259
       -
               sslServerKey = "/root/ssl-example-org.key";

     

       260
       -
             }

     

       261
       -
           ];

     

       262
       -
       }

     

       263
       -
       </programlisting>

     

       264
       -
       

     

       265
       -
       It defines two virtual hosts with nearly identical configuration; the

     

       266
       -
       only difference is that the second one has SSL enabled.  To prevent

     

       267
       -
       this duplication, we can use a <literal>let</literal>:

     

       268
       -
       

     

       269
       -
       <programlisting>

     

       270
       -
       let

     

       271
       -
         exampleOrgCommon =

     

       272
       -
           { hostName = "example.org";

     

       273
       -
             documentRoot = "/webroot";

     

       274
       -
             adminAddr = "alice@example.org";

     

       275
       -
             enableUserDir = true;

     

       276
       -
           };

     

       277
       -
       in

     

       278
       -
       {

     

       279
       -
         services.httpd.virtualHosts =

     

       280
       -
           [ exampleOrgCommon

     

       281
       -
             (exampleOrgCommon // {

     

       282
       -
               enableSSL = true;

     

       283
       -
               sslServerCert = "/root/ssl-example-org.crt";

     

       284
       -
               sslServerKey = "/root/ssl-example-org.key";

     

       285
       -
             })

     

       286
       -
           ];

     

       287
       -
       }

     

       288
       -
       </programlisting>

     

       289
       -
       

     

       290
       -
       The <literal>let exampleOrgCommon =

     

       291
       -
       <replaceable>...</replaceable></literal> defines a variable named

     

       292
       -
       <literal>exampleOrgCommon</literal>.  The <literal>//</literal>

     

       293
       -
       operator merges two attribute sets, so the configuration of the second

     

       294
       -
       virtual host is the set <literal>exampleOrgCommon</literal> extended

     

       295
       -
       with the SSL options.</para>

     

       296
       -
       

     

       297
       -
       <para>You can write a <literal>let</literal> wherever an expression is

     

       298
       -
       allowed.  Thus, you also could have written:

     

       299
       -
       

     

       300
       -
       <programlisting>

     

       301
       -
       {

     

       302
       -
         services.httpd.virtualHosts =

     

       303
       -
           let exampleOrgCommon = <replaceable>...</replaceable>; in

     

       304
       -
           [ exampleOrgCommon

     

       305
       -
             (exampleOrgCommon // { <replaceable>...</replaceable> })

     

       306
       -
           ];

     

       307
       -
       }

     

       308
       -
       </programlisting>

     

       309
       -
       

     

       310
       -
       but not <literal>{ let exampleOrgCommon =

     

       311
       -
       <replaceable>...</replaceable>; in <replaceable>...</replaceable>;

     

       312
       -
       }</literal> since attributes (as opposed to attribute values) are not

     

       313
       -
       expressions.</para>

     

       314
       -
       

     

       315
       -
       <para><emphasis>Functions</emphasis> provide another method of

     

       316
       -
       abstraction.  For instance, suppose that we want to generate lots of

     

       317
       -
       different virtual hosts, all with identical configuration except for

     

       318
       -
       the host name.  This can be done as follows:

     

       319
       -
       

     

       320
       -
       <programlisting>

     

       321
       -
       {

     

       322
       -
         services.httpd.virtualHosts =

     

       323
       -
           let

     

       324
       -
             makeVirtualHost = name:

     

       325
       -
               { hostName = name;

     

       326
       -
                 documentRoot = "/webroot";

     

       327
       -
                 adminAddr = "alice@example.org";

     

       328
       -
               };

     

       329
       -
           in

     

       330
       -
             [ (makeVirtualHost "example.org")

     

       331
       -
               (makeVirtualHost "example.com")

     

       332
       -
               (makeVirtualHost "example.gov")

     

       333
       -
               (makeVirtualHost "example.nl")

     

       334
       -
             ];

     

       335
       -
       }

     

       336
       -
       </programlisting>

     

       337
       -
       

     

       338
       -
       Here, <varname>makeVirtualHost</varname> is a function that takes a

     

       339
       -
       single argument <literal>name</literal> and returns the configuration

     

       340
       -
       for a virtual host.  That function is then called for several names to

     

       341
       -
       produce the list of virtual host configurations.</para>

     

       342
       -
       

     

       343
       -
       <para>We can further improve on this by using the function

     

       344
       -
       <varname>map</varname>, which applies another function to every

     

       345
       -
       element in a list:

     

       346
       -
       

     

       347
       -
       <programlisting>

     

       348
       -
       {

     

       349
       -
         services.httpd.virtualHosts =

     

       350
       -
           let

     

       351
       -
             makeVirtualHost = <replaceable>...</replaceable>;

     

       352
       -
           in map makeVirtualHost

     

       353
       -
             [ "example.org" "example.com" "example.gov" "example.nl" ];

     

       354
       -
       }

     

       355
       -
       </programlisting>

     

       356
       -
       

     

       357
       -
       (The function <literal>map</literal> is called a

     

       358
       -
       <emphasis>higher-order function</emphasis> because it takes another

     

       359
       -
       function as an argument.)</para>

     

       360
       -
       

     

       361
       -
       <para>What if you need more than one argument, for instance, if we

     

       362
       -
       want to use a different <literal>documentRoot</literal> for each

     

       363
       -
       virtual host?  Then we can make <varname>makeVirtualHost</varname> a

     

       364
       -
       function that takes a <emphasis>set</emphasis> as its argument, like this:

     

       365
       -
       

     

       366
       -
       <programlisting>

     

       367
       -
       {

     

       368
       -
         services.httpd.virtualHosts =

     

       369
       -
           let

     

       370
       -
             makeVirtualHost = { name, root }:

     

       371
       -
               { hostName = name;

     

       372
       -
                 documentRoot = root;

     

       373
       -
                 adminAddr = "alice@example.org";

     

       374
       -
               };

     

       375
       -
           in map makeVirtualHost

     

       376
       -
             [ { name = "example.org"; root = "/sites/example.org"; }

     

       377
       -
               { name = "example.com"; root = "/sites/example.com"; }

     

       378
       -
               { name = "example.gov"; root = "/sites/example.gov"; }

     

       379
       -
               { name = "example.nl"; root = "/sites/example.nl"; }

     

       380
       -
             ];

     

       381
       -
       }

     

       382
       -
       </programlisting>

     

       383
       -
       

     

       384
       -
       But in this case (where every root is a subdirectory of

     

       385
       -
       <filename>/sites</filename> named after the virtual host), it would

     

       386
       -
       have been shorter to define <varname>makeVirtualHost</varname> as

     

       387
       -
       <programlisting>

     

       388
       -
       makeVirtualHost = name:

     

       389
       -
         { hostName = name;

     

       390
       -
           documentRoot = "/sites/${name}";

     

       391
       -
           adminAddr = "alice@example.org";

     

       392
       -
         };

     

       393
       -
       </programlisting>

     

       394
       -
       

     

       395
       -
       Here, the construct

     

       396
       -
       <literal>${<replaceable>...</replaceable>}</literal> allows the result

     

       397
       -
       of an expression to be spliced into a string.</para>

     

       398
       -
       

     

       399
       -
       </section>

     

       400
       -
       

     

       401
       -
       

     

       402
       -
       <section xml:id="sec-modularity"><title>Modularity</title>

     

       403
       -
       

     

       404
       -
       <para>The NixOS configuration mechanism is modular.  If your

     

       405
       -
       <filename>configuration.nix</filename> becomes too big, you can split

     

       406
       -
       it into multiple files.  Likewise, if you have multiple NixOS

     

       407
       -
       configurations (e.g. for different computers) with some commonality,

     

       408
       -
       you can move the common configuration into a shared file.</para>

     

       409
       -
       

     

       410
       -
       <para>Modules have exactly the same syntax as

     

       411
       -
       <filename>configuration.nix</filename>.  In fact,

     

       412
       -
       <filename>configuration.nix</filename> is itself a module.  You can

     

       413
       -
       use other modules by including them from

     

       414
       -
       <filename>configuration.nix</filename>, e.g.:

     

       415
       -
       

     

       416
       -
       <programlisting>

     

       417
       -
       { config, pkgs, ... }:

     

       418
       -
       

     

       419
       -
       { imports = [ ./vpn.nix ./kde.nix ];

     

       420
       -
         services.httpd.enable = true;

     

       421
       -
         environment.systemPackages = [ pkgs.emacs ];

     

       422
       -
         <replaceable>...</replaceable>

     

       423
       -
       }

     

       424
       -
       </programlisting>

     

       425
       -
       

     

       426
       -
       Here, we include two modules from the same directory,

     

       427
       -
       <filename>vpn.nix</filename> and <filename>kde.nix</filename>.  The

     

       428
       -
       latter might look like this:

     

       429
       -
       

     

       430
       -
       <programlisting>

     

       431
       -
       { config, pkgs, ... }:

     

       432
       -
       

     

       433
       -
       { services.xserver.enable = true;

     

       434
       -
         services.xserver.displayManager.kdm.enable = true;

     

       435
       -
         services.xserver.desktopManager.kde4.enable = true;

     

       436
       -
         environment.systemPackages = [ pkgs.kde4.kscreensaver ];

     

       437
       -
       }

     

       438
       -
       </programlisting>

     

       439
       -
       

     

       440
       -
       Note that both <filename>configuration.nix</filename> and

     

       441
       -
       <filename>kde.nix</filename> define the option

     

       442
       -
       <option>environment.systemPackages</option>.  When multiple modules

     

       443
       -
       define an option, NixOS will try to <emphasis>merge</emphasis> the

     

       444
       -
       definitions.  In the case of

     

       445
       -
       <option>environment.systemPackages</option>, that’s easy: the lists of

     

       446
       -
       packages can simply be concatenated.  The value in

     

       447
       -
       <filename>configuration.nix</filename> is merged last, so for

     

       448
       -
       list-type options, it will appear at the end of the merged list. If

     

       449
       -
       you want it to appear first, you can use <varname>mkBefore</varname>:

     

       450
       -
       

     

       451
       -
       <programlisting>

     

       452
       -
       boot.kernelModules = mkBefore [ "kvm-intel" ];

     

       453
       -
       </programlisting>

     

       454
       -
       

     

       455
       -
       This causes the <literal>kvm-intel</literal> kernel module to be

     

       456
       -
       loaded before any other kernel modules.</para>

     

       457
       -
       

     

       458
       -
       <para>For other types of options, a merge may not be possible. For

     

       459
       -
       instance, if two modules define

     

       460
       -
       <option>services.httpd.adminAddr</option>,

     

       461
       -
       <command>nixos-rebuild</command> will give an error:

     

       462
       -
       

     

       463
       -
       <screen>

     

       464
       -
       The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.

     

       465
       -
       </screen>

     

       466
       -
       

     

       467
       -
       When that happens, it’s possible to force one definition take

     

       468
       -
       precedence over the others:

     

       469
       -
       

     

       470
       -
       <programlisting>

     

       471
       -
       services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";

     

       472
       -
       </programlisting>

     

       473
       -
       

     

       474
       -
       </para>

     

       475
       -
       

     

       476
       -
       <para>When using multiple modules, you may need to access

     

       477
       -
       configuration values defined in other modules.  This is what the

     

       478
       -
       <varname>config</varname> function argument is for: it contains the

     

       479
       -
       complete, merged system configuration.  That is,

     

       480
       -
       <varname>config</varname> is the result of combining the

     

       481
       -
       configurations returned by every module<footnote><para>If you’re

     

       482
       -
       wondering how it’s possible that the (indirect)

     

       483
       -
       <emphasis>result</emphasis> of a function is passed as an

     

       484
       -
       <emphasis>input</emphasis> to that same function: that’s because Nix

     

       485
       -
       is a “lazy” language — it only computes values when they are needed.

     

       486
       -
       This works as long as no individual configuration value depends on

     

       487
       -
       itself.</para></footnote>.  For example, here is a module that adds

     

       488
       -
       some packages to <option>environment.systemPackages</option> only if

     

       489
       -
       <option>services.xserver.enable</option> is set to

     

       490
       -
       <literal>true</literal> somewhere else:

     

       491
       -
       

     

       492
       -
       <programlisting>

     

       493
       -
       { config, pkgs, ... }:

     

       494
       -
       

     

       495
       -
       { environment.systemPackages =

     

       496
       -
           if config.services.xserver.enable then

     

       497
       -
             [ pkgs.firefox

     

       498
       -
               pkgs.thunderbird

     

       499
       -
             ]

     

       500
       -
           else

     

       501
       -
             [ ];

     

       502
       -
       }

     

       503
       -
       </programlisting>

     

       504
       -
       

     

       505
       -
       </para>

     

       506
       -
       

     

       507
       -
       <para>With multiple modules, it may not be obvious what the final

     

       508
       -
       value of a configuration option is.  The command

     

       509
       -
       <option>nixos-option</option> allows you to find out:

     

       510
       -
       

     

       511
       -
       <screen>

     

       512
       -
       $ nixos-option services.xserver.enable

     

       513
       -
       true

     

       514
       -
       

     

       515
       -
       $ nixos-option boot.kernelModules

     

       516
       -
       [ "tun" "ipv6" "loop" <replaceable>...</replaceable> ]

     

       517
       -
       </screen>

     

       518
       -
       

     

       519
       -
       Interactive exploration of the configuration is possible using

     

       520
       -
       <command

     

       521
       -
       xlink:href="https://github.com/edolstra/nix-repl">nix-repl</command>,

     

       522
       -
       a read-eval-print loop for Nix expressions.  It’s not installed by

     

       523
       -
       default; run <literal>nix-env -i nix-repl</literal> to get it.  A

     

       524
       -
       typical use:

     

       525
       -
       

     

       526
       -
       <screen>

     

       527
       -
       $ nix-repl '&lt;nixos>'

     

       528
       -
       

     

       529
       -
       nix-repl> config.networking.hostName

     

       530
       -
       "mandark"

     

       531
       -
       

     

       532
       -
       nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts

     

       533
       -
       [ "example.org" "example.gov" ]

     

       534
       -
       </screen>

     

       535
       -
       

     

       536
       -
       </para>

     

       537
       -
       

     

       538
       -
       </section>

     

       539
       -
       

     

       540
       -
       

     

       541
       -
       <section xml:id="sec-nix-syntax-summary"><title>Syntax summary</title>

     

       542
       -
       

     

       543
       -
       <para>Below is a summary of the most important syntactic constructs in

     

       544
       -
       the Nix expression language.  It’s not complete.  In particular, there

     

       545
       -
       are many other built-in functions.  See the <link

     

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

     

       547
       -
       manual</link> for the rest.</para>

     

       548
       -
       

     

       549
       -
       <informaltable frame='none'>

     

       550
       -
         <tgroup cols='2'>

     

       551
       -
           <colspec colname='c1' rowsep='1' colsep='1' />

     

       552
       -
           <colspec colname='c2' rowsep='1' />

     

       553
       -
           <thead>

     

       554
       -
             <row>

     

       555
       -
               <entry>Example</entry>

     

       556
       -
               <entry>Description</entry>

     

       557
       -
             </row>

     

       558
       -
           </thead>

     

       559
       -
           <tbody>

     

       560
       -
       

     

       561
       -
             <row>

     

       562
       -
               <entry namest="c1" nameend="c2"><emphasis>Basic values</emphasis></entry>

     

       563
       -
             </row>

     

       564
       -
             <row>

     

       565
       -
               <entry><literal>"Hello world"</literal></entry>

     

       566
       -
               <entry>A string</entry>

     

       567
       -
             </row>

     

       568
       -
             <row>

     

       569
       -
               <entry><literal>"${pkgs.bash}/bin/sh"</literal></entry>

     

       570
       -
               <entry>A string containing an expression (expands to <literal>"/nix/store/<replaceable>hash</replaceable>-bash-<replaceable>version</replaceable>/bin/sh"</literal>)</entry>

     

       571
       -
             </row>

     

       572
       -
             <row>

     

       573
       -
               <entry><literal>true</literal>, <literal>false</literal></entry>

     

       574
       -
               <entry>Booleans</entry>

     

       575
       -
             </row>

     

       576
       -
             <row>

     

       577
       -
               <entry><literal>123</literal></entry>

     

       578
       -
               <entry>An integer</entry>

     

       579
       -
             </row>

     

       580
       -
             <row>

     

       581
       -
               <entry><literal>./foo.png</literal></entry>

     

       582
       -
               <entry>A path (relative to the containing Nix expression)</entry>

     

       583
       -
             </row>

     

       584
       -
       

     

       585
       -
             <row>

     

       586
       -
               <entry namest="c1" nameend="c2"><emphasis>Compound values</emphasis></entry>

     

       587
       -
             </row>

     

       588
       -
             <row>

     

       589
       -
               <entry><literal>{ x = 1; y = 2; }</literal></entry>

     

       590
       -
               <entry>An set with attributes names <literal>x</literal> and <literal>y</literal></entry>

     

       591
       -
             </row>

     

       592
       -
             <row>

     

       593
       -
               <entry><literal>{ foo.bar = 1; }</literal></entry>

     

       594
       -
               <entry>A nested set, equivalent to <literal>{ foo = { bar = 1; }; }</literal></entry>

     

       595
       -
             </row>

     

       596
       -
             <row>

     

       597
       -
               <entry><literal>rec { x = "bla"; y = x + "bar"; }</literal></entry>

     

       598
       -
               <entry>A recursive set, equivalent to <literal>{ x = "foo"; y = "foobar"; }</literal></entry>

     

       599
       -
             </row>

     

       600
       -
             <row>

     

       601
       -
               <entry><literal>[ "foo" "bar" ]</literal></entry>

     

       602
       -
               <entry>A list with two elements</entry>

     

       603
       -
             </row>

     

       604
       -
       

     

       605
       -
             <row>

     

       606
       -
               <entry namest="c1" nameend="c2"><emphasis>Operators</emphasis></entry>

     

       607
       -
             </row>

     

       608
       -
             <row>

     

       609
       -
               <entry><literal>"foo" + "bar"</literal></entry>

     

       610
       -
               <entry>String concatenation</entry>

     

       611
       -
             </row>

     

       612
       -
             <row>

     

       613
       -
               <entry><literal>1 + 2</literal></entry>

     

       614
       -
               <entry>Integer addition</entry>

     

       615
       -
             </row>

     

       616
       -
             <row>

     

       617
       -
               <entry><literal>"foo" == "f" + "oo"</literal></entry>

     

       618
       -
               <entry>Equality test (evaluates to <literal>true</literal>)</entry>

     

       619
       -
             </row>

     

       620
       -
             <row>

     

       621
       -
               <entry><literal>"foo" != "bar"</literal></entry>

     

       622
       -
               <entry>Inequality test (evaluates to <literal>true</literal>)</entry>

     

       623
       -
             </row>

     

       624
       -
             <row>

     

       625
       -
               <entry><literal>!true</literal></entry>

     

       626
       -
               <entry>Boolean negation</entry>

     

       627
       -
             </row>

     

       628
       -
             <row>

     

       629
       -
               <entry><literal>{ x = 1; y = 2; }.x</literal></entry>

     

       630
       -
               <entry>Attribute selection (evaluates to <literal>1</literal>)</entry>

     

       631
       -
             </row>

     

       632
       -
             <row>

     

       633
       -
               <entry><literal>{ x = 1; y = 2; }.z or 3</literal></entry>

     

       634
       -
               <entry>Attribute selection with default (evaluates to <literal>3</literal>)</entry>

     

       635
       -
             </row>

     

       636
       -
             <row>

     

       637
       -
               <entry><literal>{ x = 1; y = 2; } // { z = 3; }</literal></entry>

     

       638
       -
               <entry>Merge two sets (attributes in the right-hand set taking precedence)</entry>

     

       639
       -
             </row>

     

       640
       -
       

     

       641
       -
             <row>

     

       642
       -
               <entry namest="c1" nameend="c2"><emphasis>Control structures</emphasis></entry>

     

       643
       -
             </row>

     

       644
       -
             <row>

     

       645
       -
               <entry><literal>if 1 + 1 == 2 then "yes!" else "no!"</literal></entry>

     

       646
       -
               <entry>Conditional expression</entry>

     

       647
       -
             </row>

     

       648
       -
             <row>

     

       649
       -
               <entry><literal>assert 1 + 1 == 2; "yes!"</literal></entry>

     

       650
       -
               <entry>Assertion check (evaluates to <literal>"yes!"</literal>)</entry>

     

       651
       -
             </row>

     

       652
       -
             <row>

     

       653
       -
               <entry><literal>let x = "foo"; y = "bar"; in x + y</literal></entry>

     

       654
       -
               <entry>Variable definition</entry>

     

       655
       -
             </row>

     

       656
       -
             <row>

     

       657
       -
               <entry><literal>with pkgs.lib; head [ 1 2 3 ]</literal></entry>

     

       658
       -
               <entry>Add all attributes from the given set to the scope

     

       659
       -
               (evaluates to <literal>1</literal>)</entry>

     

       660
       -
             </row>

     

       661
       -
       

     

       662
       -
             <row>

     

       663
       -
               <entry namest="c1" nameend="c2"><emphasis>Functions (lambdas)</emphasis></entry>

     

       664
       -
             </row>

     

       665
       -
             <row>

     

       666
       -
               <entry><literal>x: x + 1</literal></entry>

     

       667
       -
               <entry>A function that expects an integer and returns it increased by 1</entry>

     

       668
       -
             </row>

     

       669
       -
             <row>

     

       670
       -
               <entry><literal>(x: x + 1) 100</literal></entry>

     

       671
       -
               <entry>A function call (evaluates to 101)</entry>

     

       672
       -
             </row>

     

       673
       -
             <row>

     

       674
       -
               <entry><literal>let inc = x: x + 1; in inc (inc (inc 100))</literal></entry>

     

       675
       -
               <entry>A function bound to a variable and subsequently called by name (evaluates to 103)</entry>

     

       676
       -
             </row>

     

       677
       -
             <row>

     

       678
       -
               <entry><literal>{ x, y }: x + y</literal></entry>

     

       679
       -
               <entry>A function that expects a set with required attributes

     

       680
       -
               <literal>x</literal> and <literal>y</literal> and concatenates

     

       681
       -
               them</entry>

     

       682
       -
             </row>

     

       683
       -
             <row>

     

       684
       -
               <entry><literal>{ x, y ? "bar" }: x + y</literal></entry>

     

       685
       -
               <entry>A function that expects a set with required attribute

     

       686
       -
               <literal>x</literal> and optional <literal>y</literal>, using

     

       687
       -
               <literal>"bar"</literal> as default value for

     

       688
       -
               <literal>y</literal></entry>

     

       689
       -
             </row>

     

       690
       -
             <row>

     

       691
       -
               <entry><literal>{ x, y, ... }: x + y</literal></entry>

     

       692
       -
               <entry>A function that expects a set with required attributes

     

       693
       -
               <literal>x</literal> and <literal>y</literal> and ignores any

     

       694
       -
               other attributes</entry>

     

       695
       -
             </row>

     

       696
       -
             <row>

     

       697
       -
               <entry><literal>{ x, y } @ args: x + y</literal></entry>

     

       698
       -
               <entry>A function that expects a set with required attributes

     

       699
       -
               <literal>x</literal> and <literal>y</literal>, and binds the

     

       700
       -
               whole set to <literal>args</literal></entry>

     

       701
       -
             </row>

     

       702
       -
       

     

       703
       -
             <row>

     

       704
       -
               <entry namest="c1" nameend="c2"><emphasis>Built-in functions</emphasis></entry>

     

       705
       -
             </row>

     

       706
       -
             <row>

     

       707
       -
               <entry><literal>import ./foo.nix</literal></entry>

     

       708
       -
               <entry>Load and return Nix expression in given file</entry>

     

       709
       -
             </row>

     

       710
       -
             <row>

     

       711
       -
               <entry><literal>map (x: x + x) [ 1 2 3 ]</literal></entry>

     

       712
       -
               <entry>Apply a function to every element of a list (evaluates to <literal>[ 2 4 6 ]</literal>)</entry>

     

       713
       -
             </row>

     

       714
       -
             <!--

     

       715
       -
             <row>

     

       716
       -
               <entry><literal>throw "Urgh"</literal></entry>

     

       717
       -
               <entry>Raise an error condition</entry>

     

       718
       -
             </row>

     

       719
       -
             -->

     

       720
       -
       

     

       721
       -
           </tbody>

     

       722
       -
         </tgroup>

     

       723
       -
       </informaltable>

     

       724
       -
       

     

       725
       -
       </section>

     

       726
       -
       

     

       727
       -
       

     

       728
       -
       </section>

     

       729
       -
       

     

       730
       -
       

     

       731
       -
       <!--===============================================================-->

     

       732
       -
       

     

       733
       -
       <section xml:id="sec-package-management"><title>Package management</title>

     

       734
       -
       

     

       735
       -
       <para>This section describes how to add additional packages to your

     

       736
       -
       system.  NixOS has two distinct styles of package management:

     

       737
       -
       

     

       738
       -
       <itemizedlist>

     

       739
       -
       

     

       740
       -
         <listitem><para><emphasis>Declarative</emphasis>, where you declare

     

       741
       -
         what packages you want in your

     

       742
       -
         <filename>configuration.nix</filename>.  Every time you run

     

       743
       -
         <command>nixos-rebuild</command>, NixOS will ensure that you get a

     

       744
       -
         consistent set of binaries corresponding to your

     

       745
       -
         specification.</para></listitem>

     

       746
       -
       

     

       747
       -
         <listitem><para><emphasis>Ad hoc</emphasis>, where you install,

     

       748
       -
         upgrade and uninstall packages via the <command>nix-env</command>

     

       749
       -
         command.  This style allows mixing packages from different Nixpkgs

     

       750
       -
         versions.  It’s the only choice for non-root

     

       751
       -
         users.</para></listitem>

     

       752
       -
       

     

       753
       -
       </itemizedlist>

     

       754
       -
       

     

       755
       -
       </para>

     

       756
       -
       

     

       757
       -
       <para>The next two sections describe these two styles.</para>

     

       758
       -
       

     

       759
       -
       

     

       760
       -
       <section><title>Declarative package management</title>

     

       761
       -
       

     

       762
       -
       <para>With declarative package management, you specify which packages

     

       763
       -
       you want on your system by setting the option

     

       764
       -
       <option>environment.systemPackages</option>.  For instance, adding the

     

       765
       -
       following line to <filename>configuration.nix</filename> enables the

     

       766
       -
       Mozilla Thunderbird email application:

     

       767
       -
       

     

       768
       -
       <programlisting>

     

       769
       -
       environment.systemPackages = [ pkgs.thunderbird ];

     

       770
       -
       </programlisting>

     

       771
       -
       

     

       772
       -
       The effect of this specification is that the Thunderbird package from

     

       773
       -
       Nixpkgs will be built or downloaded as part of the system when you run

     

       774
       -
       <command>nixos-rebuild switch</command>.</para>

     

       775
       -
       

     

       776
       -
       <para>You can get a list of the available packages as follows:

     

       777
       -
       <screen>

     

       778
       -
       $ nix-env -qaP '*' --description

     

       779
       -
       nixos.pkgs.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded

     

       780
       -
       <replaceable>...</replaceable>

     

       781
       -
       </screen>

     

       782
       -
       

     

       783
       -
       The first column in the output is the <emphasis>attribute

     

       784
       -
       name</emphasis>, such as

     

       785
       -
       <literal>nixos.pkgs.thunderbird</literal>. (The

     

       786
       -
       <literal>nixos</literal> prefix allows distinguishing between

     

       787
       -
       different channels that you might have.)</para>

     

       788
       -
       

     

       789
       -
       <para>To “uninstall” a package, simply remove it from

     

       790
       -
       <option>environment.systemPackages</option> and run

     

       791
       -
       <command>nixos-rebuild switch</command>.</para>

     

       792
       -
       

     

       793
       -
       

     

       794
       -
       <section xml:id="sec-customising-packages"><title>Customising packages</title>

     

       795
       -
       

     

       796
       -
       <para>Some packages in Nixpkgs have options to enable or disable

     

       797
       -
       optional functionality or change other aspects of the package.  For

     

       798
       -
       instance, the Firefox wrapper package (which provides Firefox with a

     

       799
       -
       set of plugins such as the Adobe Flash player) has an option to enable

     

       800
       -
       the Google Talk plugin.  It can be set in

     

       801
       -
       <filename>configuration.nix</filename> as follows:

     

       802
       -
       

     

       803
       -
       <filename>

     

       804
       -
       nixpkgs.config.firefox.enableGoogleTalkPlugin = true;

     

       805
       -
       </filename>

     

       806
       -
       </para>

     

       807
       -
       

     

       808
       -
       <warning><para>Unfortunately, Nixpkgs currently lacks a way to query

     

       809
       -
       available configuration options.</para></warning>

     

       810
       -
       

     

       811
       -
       <para>Apart from high-level options, it’s possible to tweak a package

     

       812
       -
       in almost arbitrary ways, such as changing or disabling dependencies

     

       813
       -
       of a package.  For instance, the Emacs package in Nixpkgs by default

     

       814
       -
       has a dependency on GTK+ 2.  If you want to build it against GTK+ 3,

     

       815
       -
       you can specify that as follows:

     

       816
       -
       

     

       817
       -
       <programlisting>

     

       818
       -
       environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];

     

       819
       -
       </programlisting>

     

       820
       -
       

     

       821
       -
       The function <varname>override</varname> performs the call to the Nix

     

       822
       -
       function that produces Emacs, with the original arguments amended by

     

       823
       -
       the set of arguments specified by you.  So here the function argument

     

       824
       -
       <varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>,

     

       825
       -
       causing Emacs to depend on GTK+ 3.  (The parentheses are necessary

     

       826
       -
       because in Nix, function application binds more weakly than list

     

       827
       -
       construction, so without them,

     

       828
       -
       <literal>environment.systemPackages</literal> would be a list with two

     

       829
       -
       elements.)</para>

     

       830
       -
       

     

       831
       -
       <para>Even greater customisation is possible using the function

     

       832
       -
       <varname>overrideDerivation</varname>.  While the

     

       833
       -
       <varname>override</varname> mechanism above overrides the arguments of

     

       834
       -
       a package function, <varname>overrideDerivation</varname> allows

     

       835
       -
       changing the <emphasis>result</emphasis> of the function.  This

     

       836
       -
       permits changing any aspect of the package, such as the source code.

     

       837
       -
       For instance, if you want to override the source code of Emacs, you

     

       838
       -
       can say:

     

       839
       -
       

     

       840
       -
       <programlisting>

     

       841
       -
       environment.systemPackages =

     

       842
       -
         [ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: {

     

       843
       -
             name = "emacs-25.0-pre";

     

       844
       -
             src = /path/to/my/emacs/tree;

     

       845
       -
           }))

     

       846
       -
         ];

     

       847
       -
       </programlisting>

     

       848
       -
       

     

       849
       -
       Here, <varname>overrideDerivation</varname> takes the Nix derivation

     

       850
       -
       specified by <varname>pkgs.emacs</varname> and produces a new

     

       851
       -
       derivation in which the original’s <literal>name</literal> and

     

       852
       -
       <literal>src</literal> attribute have been replaced by the given

     

       853
       -
       values.  The original attributes are accessible via

     

       854
       -
       <varname>attrs</varname>.</para>

     

       855
       -
       

     

       856
       -
       <para>The overrides shown above are not global.  They do not affect

     

       857
       -
       the original package; other packages in Nixpkgs continue to depend on

     

       858
       -
       the original rather than the customised package.  This means that if

     

       859
       -
       another package in your system depends on the original package, you

     

       860
       -
       end up with two instances of the package.  If you want to have

     

       861
       -
       everything depend on your customised instance, you can apply a

     

       862
       -
       <emphasis>global</emphasis> override as follows:

     

       863
       -
       

     

       864
       -
       <screen>

     

       865
       -
       nixpkgs.config.packageOverrides = pkgs:

     

       866
       -
         { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };

     

       867
       -
         };

     

       868
       -
       </screen>

     

       869
       -
       

     

       870
       -
       The effect of this definition is essentially equivalent to modifying

     

       871
       -
       the <literal>emacs</literal> attribute in the Nixpkgs source tree.

     

       872
       -
       Any package in Nixpkgs that depends on <literal>emacs</literal> will

     

       873
       -
       be passed your customised instance.  (However, the value

     

       874
       -
       <literal>pkgs.emacs</literal> in

     

       875
       -
       <varname>nixpkgs.config.packageOverrides</varname> refers to the

     

       876
       -
       original rather than overridden instance, to prevent an infinite

     

       877
       -
       recursion.)</para>

     

       878
       -
       

     

       879
       -
       </section>

     

       880
       -
       

     

       881
       -
       <section xml:id="sec-custom-packages"><title>Adding custom packages</title>

     

       882
       -
       

     

       883
       -
       <para>It’s possible that a package you need is not available in NixOS.

     

       884
       -
       In that case, you can do two things.  First, you can clone the Nixpkgs

     

       885
       -
       repository, add the package to your clone, and (optionally) submit a

     

       886
       -
       patch or pull request to have it accepted into the main Nixpkgs

     

       887
       -
       repository.  This is described in detail in the <link

     

       888
       -
       xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs manual</link>.

     

       889
       -
       In short, you clone Nixpkgs:

     

       890
       -
       

     

       891
       -
       <screen>

     

       892
       -
       $ git clone git://github.com/NixOS/nixpkgs.git

     

       893
       -
       $ cd nixpkgs

     

       894
       -
       </screen>

     

       895
       -
       

     

       896
       -
       Then you write and test the package as described in the Nixpkgs

     

       897
       -
       manual.  Finally, you add it to

     

       898
       -
       <literal>environment.systemPackages</literal>, e.g.

     

       899
       -
       

     

       900
       -
       <programlisting>

     

       901
       -
       environment.systemPackages = [ pkgs.my-package ];

     

       902
       -
       </programlisting>

     

       903
       -
       

     

       904
       -
       and you run <command>nixos-rebuild</command>, specifying your own

     

       905
       -
       Nixpkgs tree:

     

       906
       -
       

     

       907
       -
       <screen>

     

       908
       -
       $ nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>

     

       909
       -
       

     

       910
       -
       </para>

     

       911
       -
       

     

       912
       -
       <para>The second possibility is to add the package outside of the

     

       913
       -
       Nixpkgs tree.  For instance, here is how you specify a build of the

     

       914
       -
       <link xlink:href="http://www.gnu.org/software/hello/">GNU Hello</link>

     

       915
       -
       package directly in <filename>configuration.nix</filename>:

     

       916
       -
       

     

       917
       -
       <programlisting>

     

       918
       -
       environment.systemPackages =

     

       919
       -
         let

     

       920
       -
           my-hello = with pkgs; stdenv.mkDerivation rec {

     

       921
       -
             name = "hello-2.8";

     

       922
       -
             src = fetchurl {

     

       923
       -
               url = "mirror://gnu/hello/${name}.tar.gz";

     

       924
       -
               sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";

     

       925
       -
             };

     

       926
       -
           };

     

       927
       -
         in

     

       928
       -
         [ my-hello ];

     

       929
       -
       </programlisting>

     

       930
       -
       

     

       931
       -
       Of course, you can also move the definition of

     

       932
       -
       <literal>my-hello</literal> into a separate Nix expression, e.g.

     

       933
       -
       <programlisting>

     

       934
       -
       environment.systemPackages = [ (import ./my-hello.nix) ];

     

       935
       -
       </programlisting>

     

       936
       -
       where <filename>my-hello.nix</filename> contains:

     

       937
       -
       <programlisting>

     

       938
       -
       with import &lt;nixpkgs> {}; # bring all of Nixpkgs into scope

     

       939
       -
       

     

       940
       -
       stdenv.mkDerivation rec {

     

       941
       -
         name = "hello-2.8";

     

       942
       -
         src = fetchurl {

     

       943
       -
           url = "mirror://gnu/hello/${name}.tar.gz";

     

       944
       -
           sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";

     

       945
       -
         };

     

       946
       -
       }

     

       947
       -
       </programlisting>

     

       948
       -
       

     

       949
       -
       This allows testing the package easily:

     

       950
       -
       <screen>

     

       951
       -
       $ nix-build my-hello.nix

     

       952
       -
       $ ./result/bin/hello

     

       953
       -
       Hello, world!

     

       954
       -
       </screen>

     

       955
       -
       

     

       956
       -
       </para>

     

       957
       -
       

     

       958
       -
       </section>

     

       959
       -
       

     

       960
       -
       </section>

     

       961
       -
       

     

       962
       -
       

     

       963
       -
       <section><title>Ad hoc package management</title>

     

       964
       -
       

     

       965
       -
       <para>With the command <command>nix-env</command>, you can install and

     

       966
       -
       uninstall packages from the command line.  For instance, to install

     

       967
       -
       Mozilla Thunderbird:

     

       968
       -
       

     

       969
       -
       <screen>

     

       970
       -
       $ nix-env -iA nixos.pkgs.thunderbird</screen>

     

       971
       -
       

     

       972
       -
       If you invoke this as root, the package is installed in the Nix

     

       973
       -
       profile <filename>/nix/var/nix/profiles/default</filename> and visible

     

       974
       -
       to all users of the system; otherwise, the package ends up in

     

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

     

       976
       -
       and is not visible to other users.  The <option>-A</option> flag

     

       977
       -
       specifies the package by its attribute name; without it, the package

     

       978
       -
       is installed by matching against its package name

     

       979
       -
       (e.g. <literal>thunderbird</literal>).  The latter is slower because

     

       980
       -
       it requires matching against all available Nix packages, and is

     

       981
       -
       ambiguous if there are multiple matching packages.</para>

     

       982
       -
       

     

       983
       -
       <para>Packages come from the NixOS channel.  You typically upgrade a

     

       984
       -
       package by updating to the latest version of the NixOS channel:

     

       985
       -
       <screen>

     

       986
       -
       $ nix-channel --update nixos

     

       987
       -
       </screen>

     

       988
       -
       and then running <literal>nix-env -i</literal> again.  Other packages

     

       989
       -
       in the profile are <emphasis>not</emphasis> affected; this is the

     

       990
       -
       crucial difference with the declarative style of package management,

     

       991
       -
       where running <command>nixos-rebuild switch</command> causes all

     

       992
       -
       packages to be updated to their current versions in the NixOS channel.

     

       993
       -
       You can however upgrade all packages for which there is a newer

     

       994
       -
       version by doing:

     

       995
       -
       <screen>

     

       996
       -
       $ nix-env -u '*'

     

       997
       -
       </screen>

     

       998
       -
       </para>

     

       999
       -
       

     

       1000
       -
       <para>A package can be uninstalled using the <option>-e</option>

     

       1001
       -
       flag:

     

       1002
       -
       <screen>

     

       1003
       -
       $ nix-env -e thunderbird

     

       1004
       -
       </screen>

     

       1005
       -
       </para>

     

       1006
       -
       

     

       1007
       -
       <para>Finally, you can roll back an undesirable

     

       1008
       -
       <command>nix-env</command> action:

     

       1009
       -
       <screen>

     

       1010
       -
       $ nix-env --rollback

     

       1011
       -
       </screen>

     

       1012
       -
       </para>

     

       1013
       -
       

     

       1014
       -
       <para><command>nix-env</command> has many more flags.  For details,

     

       1015
       -
       see the

     

       1016
       -
       <citerefentry><refentrytitle>nix-env</refentrytitle><manvolnum>1</manvolnum></citerefentry>

     

       1017
       -
       manpage or the Nix manual.</para>

     

       1018
       -
       

     

       1019
       -
       </section>

     

       1020
       -
       

     

       1021
       -
       

     

       1022
       -
       </section>

     

       1023
       -
       

     

       1024
       -
       

     

       1025
       -
       <!--===============================================================-->

     

       1026
       -
       

     

       1027
       -
       <section xml:id="sec-user-management"><title>User management</title>

     

       1028
       -
       

     

       1029
       -
       <para>NixOS supports both declarative and imperative styles of user

     

       1030
       -
       management.  In the declarative style, users are specified in

     

       1031
       -
       <filename>configuration.nix</filename>.  For instance, the following

     

       1032
       -
       states that a user account named <literal>alice</literal> shall exist:

     

       1033
       -
       

     

       1034
       -
       <programlisting>

     

       1035
       -
       users.extraUsers.alice =

     

       1036
       -
         { createHome = true;

     

       1037
       -
           home = "/home/alice";

     

       1038
       -
           description = "Alice Foobar";

     

       1039
       -
           extraGroups = [ "wheel" "networkmanager" ];

     

       1040
       -
           useDefaultShell = true;

     

       1041
       -
           openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];

     

       1042
       -
         };

     

       1043
       -
       </programlisting>

     

       1044
       -
       

     

       1045
       -
       Note that <literal>alice</literal> is a member of the

     

       1046
       -
       <literal>wheel</literal> and <literal>networkmanager</literal> groups,

     

       1047
       -
       which allows her to use <command>sudo</command> to execute commands as

     

       1048
       -
       <literal>root</literal> and to configure the network, respectively.

     

       1049
       -
       Also note the SSH public key that allows remote logins with the

     

       1050
       -
       corresponding private key. Users created in this way do not have a

     

       1051
       -
       password by default, so they cannot log in via mechanisms that require

     

       1052
       -
       a password. However, you can use the <command>passwd</command> program

     

       1053
       -
       to set a password, which is retained across invocations of

     

       1054
       -
       <command>nixos-rebuild</command>.</para>

     

       1055
       -
       

     

       1056
       -
       <para>If you set users.mutableUsers to false, then the contents of /etc/passwd

     

       1057
       -
       and /etc/group will be congruent to your NixOS configuration. For instance,

     

       1058
       -
       if you remove a user from users.extraUsers and run nixos-rebuild, the user

     

       1059
       -
       account will cease to exist. Also, imperative commands for managing users

     

       1060
       -
       and groups, such as useradd, are no longer available.</para>

     

       1061
       -
       

     

       1062
       -
       <para>A user ID (uid) is assigned automatically.  You can also specify

     

       1063
       -
       a uid manually by adding

     

       1064
       -
       

     

       1065
       -
       <programlisting>

     

       1066
       -
           uid = 1000;

     

       1067
       -
       </programlisting>

     

       1068
       -
       

     

       1069
       -
       to the user specification.</para>

     

       1070
       -
       

     

       1071
       -
       <para>Groups can be specified similarly.  The following states that a

     

       1072
       -
       group named <literal>students</literal> shall exist:

     

       1073
       -
       

     

       1074
       -
       <programlisting>

     

       1075
       -
       users.extraGroups.students.gid = 1000;

     

       1076
       -
       </programlisting>

     

       1077
       -
       

     

       1078
       -
       As with users, the group ID (gid) is optional and will be assigned

     

       1079
       -
       automatically if it’s missing.</para>

     

       1080
       -
       

     

       1081
       -
       <warning><para>Currently declarative user management is not perfect:

     

       1082
       -
       <command>nixos-rebuild</command> does not know how to realise certain

     

       1083
       -
       configuration changes.  This includes removing a user or group, and

     

       1084
       -
       removing group membership from a user.</para></warning>

     

       1085
       -
       

     

       1086
       -
       <para>In the imperative style, users and groups are managed by

     

       1087
       -
       commands such as <command>useradd</command>,

     

       1088
       -
       <command>groupmod</command> and so on.  For instance, to create a user

     

       1089
       -
       account named <literal>alice</literal>:

     

       1090
       -
       

     

       1091
       -
       <screen>

     

       1092
       -
       $ useradd -m alice</screen>

     

       1093
       -
       

     

       1094
       -
       The flag <option>-m</option> causes the creation of a home directory

     

       1095
       -
       for the new user, which is generally what you want.  The user does not

     

       1096
       -
       have an initial password and therefore cannot log in.  A password can

     

       1097
       -
       be set using the <command>passwd</command> utility:

     

       1098
       -
       

     

       1099
       -
       <screen>

     

       1100
       -
       $ passwd alice

     

       1101
       -
       Enter new UNIX password: ***

     

       1102
       -
       Retype new UNIX password: ***

     

       1103
       -
       </screen>

     

       1104
       -
       

     

       1105
       -
       A user can be deleted using <command>userdel</command>:

     

       1106
       -
       

     

       1107
       -
       <screen>

     

       1108
       -
       $ userdel -r alice</screen>

     

       1109
       -
       

     

       1110
       -
       The flag <option>-r</option> deletes the user’s home directory.

     

       1111
       -
       Accounts can be modified using <command>usermod</command>.  Unix

     

       1112
       -
       groups can be managed using <command>groupadd</command>,

     

       1113
       -
       <command>groupmod</command> and <command>groupdel</command>.</para>

     

       1114
       -
       

     

       1115
       -
       </section>

     

       1116
       -
       

     

       1117
       -
       

     

       1118
       -
       <!--===============================================================-->

     

       1119
       -
       

     

       1120
       -
       <section><title>File systems</title>

     

       1121
       -
       

     

       1122
       -
       <para>You can define file systems using the

     

       1123
       -
       <option>fileSystems</option> configuration option.  For instance, the

     

       1124
       -
       following definition causes NixOS to mount the Ext4 file system on

     

       1125
       -
       device <filename>/dev/disk/by-label/data</filename> onto the mount

     

       1126
       -
       point <filename>/data</filename>:

     

       1127
       -
       

     

       1128
       -
       <programlisting>

     

       1129
       -
       fileSystems."/data" =

     

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

     

       1131
       -
           fsType = "ext4";

     

       1132
       -
         };

     

       1133
       -
       </programlisting>

     

       1134
       -
       

     

       1135
       -
       Mount points are created automatically if they don’t already exist.

     

       1136
       -
       For <option>device</option>, it’s best to use the topology-independent

     

       1137
       -
       device aliases in <filename>/dev/disk/by-label</filename> and

     

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

     

       1139
       -
       topology changes (e.g. if a disk is moved to another IDE

     

       1140
       -
       controller).</para>

     

       1141
       -
       

     

       1142
       -
       <para>You can usually omit the file system type

     

       1143
       -
       (<option>fsType</option>), since <command>mount</command> can usually

     

       1144
       -
       detect the type and load the necessary kernel module automatically.

     

       1145
       -
       However, if the file system is needed at early boot (in the initial

     

       1146
       -
       ramdisk) and is not <literal>ext2</literal>, <literal>ext3</literal>

     

       1147
       -
       or <literal>ext4</literal>, then it’s best to specify

     

       1148
       -
       <option>fsType</option> to ensure that the kernel module is

     

       1149
       -
       available.</para>

     

       1150
       -
       

     

       1151
       -
       <section><title>LUKS-encrypted file systems</title>

     

       1152
       -
       

     

       1153
       -
       <para>NixOS supports file systems that are encrypted using

     

       1154
       -
       <emphasis>LUKS</emphasis> (Linux Unified Key Setup).  For example,

     

       1155
       -
       here is how you create an encrypted Ext4 file system on the device

     

       1156
       -
       <filename>/dev/sda2</filename>:

     

       1157
       -
       

     

       1158
       -
       <screen>

     

       1159
       -
       $ cryptsetup luksFormat /dev/sda2

     

       1160
       -
       

     

       1161
       -
       WARNING!

     

       1162
       -
       ========

     

       1163
       -
       This will overwrite data on /dev/sda2 irrevocably.

     

       1164
       -
       

     

       1165
       -
       Are you sure? (Type uppercase yes): YES

     

       1166
       -
       Enter LUKS passphrase: ***

     

       1167
       -
       Verify passphrase: ***

     

       1168
       -
       

     

       1169
       -
       $ cryptsetup luksOpen /dev/sda2 crypted

     

       1170
       -
       Enter passphrase for /dev/sda2: ***

     

       1171
       -
       

     

       1172
       -
       $ mkfs.ext4 /dev/mapper/crypted

     

       1173
       -
       </screen>

     

       1174
       -
       

     

       1175
       -
       To ensure that this file system is automatically mounted at boot time

     

       1176
       -
       as <filename>/</filename>, add the following to

     

       1177
       -
       <filename>configuration.nix</filename>:

     

       1178
       -
       

     

       1179
       -
       <programlisting>

     

       1180
       -
       boot.initrd.luks.devices = [ { device = "/dev/sda2"; name = "crypted"; } ];

     

       1181
       -
       fileSystems."/".device = "/dev/mapper/crypted";

     

       1182
       -
       </programlisting>

     

       1183
       -
       

     

       1184
       -
       </para>

     

       1185
       -
       

     

       1186
       -
       </section>

     

       1187
       -
       

     

       1188
       -
       </section>

     

       1189
       -
       

     

       1190
       -
       

     

       1191
       -
       <!--===============================================================-->

     

       1192
       -
       

     

       1193
       -
       <section xml:id="sec-x11"><title>X Window System</title>

     

       1194
       -
       

     

       1195
       -
       <para>The X Window System (X11) provides the basis of NixOS’ graphical

     

       1196
       -
       user interface.  It can be enabled as follows:

     

       1197
       -
       <programlisting>

     

       1198
       -
       services.xserver.enable = true;

     

       1199
       -
       </programlisting>

     

       1200
       -
       The X server will automatically detect and use the appropriate video

     

       1201
       -
       driver from a set of X.org drivers (such as <literal>vesa</literal>

     

       1202
       -
       and <literal>intel</literal>).  You can also specify a driver

     

       1203
       -
       manually, e.g.

     

       1204
       -
       <programlisting>

     

       1205
       -
       services.xserver.videoDrivers = [ "r128" ];

     

       1206
       -
       </programlisting>

     

       1207
       -
       to enable X.org’s <literal>xf86-video-r128</literal> driver.</para>

     

       1208
       -
       

     

       1209
       -
       <para>You also need to enable at least one desktop or window manager.

     

       1210
       -
       Otherwise, you can only log into a plain undecorated

     

       1211
       -
       <command>xterm</command> window.  Thus you should pick one or more of

     

       1212
       -
       the following lines:

     

       1213
       -
       <programlisting>

     

       1214
       -
       services.xserver.desktopManager.kde4.enable = true;

     

       1215
       -
       services.xserver.desktopManager.xfce.enable = true;

     

       1216
       -
       services.xserver.windowManager.xmonad.enable = true;

     

       1217
       -
       services.xserver.windowManager.twm.enable = true;

     

       1218
       -
       services.xserver.windowManager.icewm.enable = true;

     

       1219
       -
       </programlisting>

     

       1220
       -
       </para>

     

       1221
       -
       

     

       1222
       -
       <para>NixOS’s default <emphasis>display manager</emphasis> (the

     

       1223
       -
       program that provides a graphical login prompt and manages the X

     

       1224
       -
       server) is SLiM.  You can select KDE’s <command>kdm</command> instead:

     

       1225
       -
       <programlisting>

     

       1226
       -
       services.xserver.displayManager.kdm.enable = true;

     

       1227
       -
       </programlisting>

     

       1228
       -
       </para>

     

       1229
       -
       

     

       1230
       -
       <para>The X server is started automatically at boot time.  If you

     

       1231
       -
       don’t want this to happen, you can set:

     

       1232
       -
       <programlisting>

     

       1233
       -
       services.xserver.autorun = false;

     

       1234
       -
       </programlisting>

     

       1235
       -
       The X server can then be started manually:

     

       1236
       -
       <screen>

     

       1237
       -
       $ systemctl start display-manager.service

     

       1238
       -
       </screen>

     

       1239
       -
       </para>

     

       1240
       -
       

     

       1241
       -
       

     

       1242
       -
       <section><title>NVIDIA graphics cards</title>

     

       1243
       -
       

     

       1244
       -
       <para>NVIDIA provides a proprietary driver for its graphics cards that

     

       1245
       -
       has better 3D performance than the X.org drivers.  It is not enabled

     

       1246
       -
       by default because it’s not free software.  You can enable it as follows:

     

       1247
       -
       <programlisting>

     

       1248
       -
       services.xserver.videoDrivers = [ "nvidia" ];

     

       1249
       -
       </programlisting>

     

       1250
       -
       You may need to reboot after enabling this driver to prevent a clash

     

       1251
       -
       with other kernel modules.</para>

     

       1252
       -
       

     

       1253
       -
       <para>On 64-bit systems, if you want full acceleration for 32-bit

     

       1254
       -
       programs such as Wine, you should also set the following:

     

       1255
       -
       <programlisting>

     

       1256
       -
       services.xserver.driSupport32Bit = true;

     

       1257
       -
       </programlisting>

     

       1258
       -
       </para>

     

       1259
       -
       

     

       1260
       -
       </section>

     

       1261
       -
       

     

       1262
       -
       

     

       1263
       -
       <section><title>Touchpads</title>

     

       1264
       -
       

     

       1265
       -
       <para>Support for Synaptics touchpads (found in many laptops such as

     

       1266
       -
       the Dell Latitude series) can be enabled as follows:

     

       1267
       -
       <programlisting>

     

       1268
       -
       services.xserver.synaptics.enable = true;

     

       1269
       -
       </programlisting>

     

       1270
       -
       The driver has many options (see <xref linkend="ch-options"/>).  For

     

       1271
       -
       instance, the following enables two-finger scrolling:

     

       1272
       -
       <programlisting>

     

       1273
       -
       services.xserver.synaptics.twoFingerScroll = true;

     

       1274
       -
       </programlisting>

     

       1275
       -
       </para>

     

       1276
       -
       

     

       1277
       -
       </section>

     

       1278
       -
       

     

       1279
       -
       

     

       1280
       -
       </section>

     

       1281
       -
       

     

       1282
       -
       

     

       1283
       -
       <!--===============================================================-->

     

       1284
       -
       

     

       1285
       -
       <section xml:id="sec-networking"><title>Networking</title>

     

       1286
       -
       

     

       1287
       -
       <section xml:id="sec-networkmanager"><title>NetworkManager</title>

     

       1288
       -
       

     

       1289
       -
       <para>To facilitate network configuration, some desktop environments

     

       1290
       -
       use NetworkManager. You can enable NetworkManager by setting:

     

       1291
       -
       

     

       1292
       -
       <programlisting>

     

       1293
       -
       services.networkmanager.enable = true;

     

       1294
       -
       </programlisting>

     

       1295
       -
       

     

       1296
       -
       Some desktop managers (e.g., GNOME) enable NetworkManager

     

       1297
       -
       automatically for you.</para>

     

       1298
       -
       

     

       1299
       -
       <para>All users that should have permission to change network settings

     

       1300
       -
       must belong to the <code>networkmanager</code> group.</para>

     

       1301
       -
       

     

       1302
       -
       <note><para><code>services.networkmanager</code> and

     

       1303
       -
       <code>services.wireless</code> can not be enabled at the same time:

     

       1304
       -
       you can still connect to the wireless networks using

     

       1305
       -
       NetworkManager.</para></note>

     

       1306
       -
       

     

       1307
       -
       </section>

     

       1308
       -
       

     

       1309
       -
       <section xml:id="sec-ssh"><title>Secure shell access</title>

     

       1310
       -
       

     

       1311
       -
       <para>Secure shell (SSH) access to your machine can be enabled by

     

       1312
       -
       setting:

     

       1313
       -
       

     

       1314
       -
       <programlisting>

     

       1315
       -
       services.openssh.enable = true;

     

       1316
       -
       </programlisting>

     

       1317
       -
       

     

       1318
       -
       By default, root logins using a password are disallowed.  They can be

     

       1319
       -
       disabled entirely by setting

     

       1320
       -
       <literal>services.openssh.permitRootLogin</literal> to

     

       1321
       -
       <literal>"no"</literal>.</para>

     

       1322
       -
       

     

       1323
       -
       <para>You can declaratively specify authorised RSA/DSA public keys for

     

       1324
       -
       a user as follows:

     

       1325
       -
       

     

       1326
       -
       <!-- FIXME: this might not work if the user is unmanaged. -->

     

       1327
       -
       <programlisting>

     

       1328
       -
       users.extraUsers.alice.openssh.authorizedKeys.keys =

     

       1329
       -
         [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];

     

       1330
       -
       </programlisting>

     

       1331
       -
       

     

       1332
       -
       </para>

     

       1333
       -
       

     

       1334
       -
       </section>

     

       1335
       -
       

     

       1336
       -
       

     

       1337
       -
       <section xml:id="sec-ipv4"><title>IPv4 configuration</title>

     

       1338
       -
       

     

       1339
       -
       <para>By default, NixOS uses DHCP (specifically,

     

       1340
       -
       <command>dhcpcd</command>) to automatically configure network

     

       1341
       -
       interfaces.  However, you can configure an interface manually as

     

       1342
       -
       follows:

     

       1343
       -
       

     

       1344
       -
       <programlisting>

     

       1345
       -
       networking.interfaces.eth0 = { ipAddress = "192.168.1.2"; prefixLength = 24; };

     

       1346
       -
       </programlisting>

     

       1347
       -
       

     

       1348
       -
       (The network prefix can also be specified using the option

     

       1349
       -
       <literal>subnetMask</literal>,

     

       1350
       -
       e.g. <literal>"255.255.255.0"</literal>, but this is deprecated.)

     

       1351
       -
       Typically you’ll also want to set a default gateway and set of name

     

       1352
       -
       servers:

     

       1353
       -
       

     

       1354
       -
       <programlisting>

     

       1355
       -
       networking.defaultGateway = "192.168.1.1";

     

       1356
       -
       networking.nameservers = [ "8.8.8.8" ];

     

       1357
       -
       </programlisting>

     

       1358
       -
       

     

       1359
       -
       </para>

     

       1360
       -
       

     

       1361
       -
       <note><para>Statically configured interfaces are set up by the systemd

     

       1362
       -
       service

     

       1363
       -
       <replaceable>interface-name</replaceable><literal>-cfg.service</literal>.

     

       1364
       -
       The default gateway and name server configuration is performed by

     

       1365
       -
       <literal>network-setup.service</literal>.</para></note>

     

       1366
       -
       

     

       1367
       -
       <para>The host name is set using <option>networking.hostName</option>:

     

       1368
       -
       

     

       1369
       -
       <programlisting>

     

       1370
       -
       networking.hostName = "cartman";

     

       1371
       -
       </programlisting>

     

       1372
       -
       

     

       1373
       -
       The default host name is <literal>nixos</literal>.  Set it to the

     

       1374
       -
       empty string (<literal>""</literal>) to allow the DHCP server to

     

       1375
       -
       provide the host name.</para>

     

       1376
       -
       

     

       1377
       -
       </section>

     

       1378
       -
       

     

       1379
       -
       

     

       1380
       -
       <section xml:id="sec-ipv6"><title>IPv6 configuration</title>

     

       1381
       -
       

     

       1382
       -
       <para>IPv6 is enabled by default.  Stateless address autoconfiguration

     

       1383
       -
       is used to automatically assign IPv6 addresses to all interfaces.  You

     

       1384
       -
       can disable IPv6 support globally by setting:

     

       1385
       -
       

     

       1386
       -
       <programlisting>

     

       1387
       -
       networking.enableIPv6 = false;

     

       1388
       -
       </programlisting>

     

       1389
       -
       

     

       1390
       -
       </para>

     

       1391
       -
       

     

       1392
       -
       </section>

     

       1393
       -
       

     

       1394
       -
       

     

       1395
       -
       <section xml:id="sec-firewall"><title>Firewall</title>

     

       1396
       -
       

     

       1397
       -
       <para>NixOS has a simple stateful firewall that blocks incoming

     

       1398
       -
       connections and other unexpected packets.  The firewall applies to

     

       1399
       -
       both IPv4 and IPv6 traffic. It is enabled by default. It can be

     

       1400
       -
       disabled as follows:

     

       1401
       -
       

     

       1402
       -
       <programlisting>

     

       1403
       -
       networking.firewall.enable = false;

     

       1404
       -
       </programlisting>

     

       1405
       -
       

     

       1406
       -
       If the firewall is enabled, you can open specific TCP ports to the

     

       1407
       -
       outside world:

     

       1408
       -
       

     

       1409
       -
       <programlisting>

     

       1410
       -
       networking.firewall.allowedTCPPorts = [ 80 443 ];

     

       1411
       -
       </programlisting>

     

       1412
       -
       

     

       1413
       -
       Note that TCP port 22 (ssh) is opened automatically if the SSH daemon

     

       1414
       -
       is enabled (<option>services.openssh.enable = true</option>).  UDP

     

       1415
       -
       ports can be opened through

     

       1416
       -
       <option>networking.firewall.allowedUDPPorts</option>.  Also of

     

       1417
       -
       interest is

     

       1418
       -
       

     

       1419
       -
       <programlisting>

     

       1420
       -
       networking.firewall.allowPing = true;

     

       1421
       -
       </programlisting>

     

       1422
       -
       

     

       1423
       -
       to allow the machine to respond to ping requests.  (ICMPv6 pings are

     

       1424
       -
       always allowed.)</para>

     

       1425
       -
       

     

       1426
       -
       </section>

     

       1427
       -
       

     

       1428
       -
       

     

       1429
       -
       <section xml:id="sec-wireless"><title>Wireless networks</title>

     

       1430
       -
       

     

       1431
       -
       <para>For a desktop installation using NetworkManager (e.g., GNOME),

     

       1432
       -
       you just have to make sure the user is in the

     

       1433
       -
       <code>networkmanager</code> group and you can skip the rest of this

     

       1434
       -
       section on wireless networks.</para>

     

       1435
       -
       

     

       1436
       -
       <para>

     

       1437
       -
       NixOS will start wpa_supplicant for you if you enable this setting:

     

       1438
       -
       

     

       1439
       -
       <programlisting>

     

       1440
       -
       networking.wireless.enable = true;

     

       1441
       -
       </programlisting>

     

       1442
       -
       

     

       1443
       -
       NixOS currently does not generate wpa_supplicant's

     

       1444
       -
       configuration file, <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file

     

       1445
       -
       yourself to define wireless networks, WPA keys and so on (see

     

       1446
       -
       wpa_supplicant.conf(5)).

     

       1447
       -
       </para>

     

       1448
       -
       

     

       1449
       -
       <para>

     

       1450
       -
       If you are using WPA2 the <command>wpa_passphrase</command> tool might be useful

     

       1451
       -
       to generate the <literal>wpa_supplicant.conf</literal>.

     

       1452
       -
       

     

       1453
       -
       <screen>

     

       1454
       -
       $ wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen>

     

       1455
       -
       

     

       1456
       -
       After you have edited the <literal>wpa_supplicant.conf</literal>,

     

       1457
       -
       you need to restart the wpa_supplicant service.

     

       1458
       -
       

     

       1459
       -
       <screen>

     

       1460
       -
       $ systemctl restart wpa_supplicant.service</screen>

     

       1461
       -
       </para>

     

       1462
       -
       

     

       1463
       -
       

     

       1464
       -
       </section>

     

       1465
       -
       

     

       1466
       -
       

     

       1467
       -
       <section><title>Ad-hoc configuration</title>

     

       1468
       -
       

     

       1469
       -
       <para>You can use <option>networking.localCommands</option> to specify

     

       1470
       -
       shell commands to be run at the end of

     

       1471
       -
       <literal>network-setup.service</literal>.  This is useful for doing

     

       1472
       -
       network configuration not covered by the existing NixOS modules.  For

     

       1473
       -
       instance, to statically configure an IPv6 address:

     

       1474
       -
       

     

       1475
       -
       <programlisting>

     

       1476
       -
       networking.localCommands =

     

       1477
       -
         ''

     

       1478
       -
           ip -6 addr add 2001:610:685:1::1/64 dev eth0

     

       1479
       -
         '';

     

       1480
       -
       </programlisting>

     

       1481
       -
       

     

       1482
       -
       </para>

     

       1483
       -
       

     

       1484
       -
       </section>

     

       1485
       -
       

     

       1486
       -
       

     

       1487
       -
       <!-- TODO: OpenVPN, NAT -->

     

       1488
       -
       

     

       1489
       -
       

     

       1490
       -
       </section>

     

       1491
       -
       

     

       1492
       -
       

     

       1493
       -
       <!--===============================================================-->

     

       1494
       -
       

     

       1495
       -
       <section xml:id="sec-kernel-config"><title>Linux kernel</title>

     

       1496
       -
       

     

       1497
       -
       <para>You can override the Linux kernel and associated packages using

     

       1498
       -
       the option <option>boot.kernelPackages</option>.  For instance, this

     

       1499
       -
       selects the Linux 3.10 kernel:

     

       1500
       -
       <programlisting>

     

       1501
       -
       boot.kernelPackages = pkgs.linuxPackages_3_10;

     

       1502
       -
       </programlisting>

     

       1503
       -
       Note that this not only replaces the kernel, but also packages that

     

       1504
       -
       are specific to the kernel version, such as the NVIDIA video drivers.

     

       1505
       -
       This ensures that driver packages are consistent with the

     

       1506
       -
       kernel.</para>

     

       1507
       -
       

     

       1508
       -
       <para>The default Linux kernel configuration should be fine for most users. You can see the configuration of your current kernel with the following command:

     

       1509
       -
       <programlisting>

     

       1510
       -
       cat /proc/config.gz | gunzip

     

       1511
       -
       </programlisting>

     

       1512
       -
       If you want to change the kernel configuration, you can use the

     

       1513
       -
       <option>packageOverrides</option> feature (see <xref

     

       1514
       -
       linkend="sec-customising-packages" />).  For instance, to enable

     

       1515
       -
       support for the kernel debugger KGDB:

     

       1516
       -
       

     

       1517
       -
       <programlisting>

     

       1518
       -
       nixpkgs.config.packageOverrides = pkgs:

     

       1519
       -
         { linux_3_4 = pkgs.linux_3_4.override {

     

       1520
       -
             extraConfig =

     

       1521
       -
               ''

     

       1522
       -
                 KGDB y

     

       1523
       -
               '';

     

       1524
       -
           };

     

       1525
       -
         };

     

       1526
       -
       </programlisting>

     

       1527
       -
       

     

       1528
       -
       <varname>extraConfig</varname> takes a list of Linux kernel

     

       1529
       -
       configuration options, one per line.  The name of the option should

     

       1530
       -
       not include the prefix <literal>CONFIG_</literal>.  The option value

     

       1531
       -
       is typically <literal>y</literal>, <literal>n</literal> or

     

       1532
       -
       <literal>m</literal> (to build something as a kernel module).</para>

     

       1533
       -
       

     

       1534
       -
       <para>Kernel modules for hardware devices are generally loaded

     

       1535
       -
       automatically by <command>udev</command>.  You can force a module to

     

       1536
       -
       be loaded via <option>boot.kernelModules</option>, e.g.

     

       1537
       -
       <programlisting>

     

       1538
       -
       boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];

     

       1539
       -
       </programlisting>

     

       1540
       -
       If the module is required early during the boot (e.g. to mount the

     

       1541
       -
       root file system), you can use

     

       1542
       -
       <option>boot.initrd.extraKernelModules</option>:

     

       1543
       -
       <programlisting>

     

       1544
       -
       boot.initrd.extraKernelModules = [ "cifs" ];

     

       1545
       -
       </programlisting>

     

       1546
       -
       This causes the specified modules and their dependencies to be added

     

       1547
       -
       to the initial ramdark.</para>

     

       1548
       -
       

     

       1549
       -
       <para>Kernel runtime parameters can be set through

     

       1550
       -
       <option>boot.kernel.sysctl</option>, e.g.

     

       1551
       -
       <programlisting>

     

       1552
       -
       boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;

     

       1553
       -
       </programlisting>

     

       1554
       -
       sets the kernel’s TCP keepalive time to 120 seconds.  To see the

     

       1555
       -
       available parameters, run <command>sysctl -a</command>.</para>

     

       1556
       -
       

     

       1557
       -
       </section>

     

       1558
       -
       

     

       1559
       -
       

     

       1560
       -
       <!-- Apache; libvirtd virtualisation -->

     

       1561
       -
       

     

       1562
       -
       

     

       1563
       -
       </chapter>

+42

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-luks-file-systems">

     

       6
       +
       

     

       7
       +
       <title>LUKS-Encrypted File Systems</title>

     

       8
       +
       

     

       9
       +
       <para>NixOS supports file systems that are encrypted using

     

       10
       +
       <emphasis>LUKS</emphasis> (Linux Unified Key Setup).  For example,

     

       11
       +
       here is how you create an encrypted Ext4 file system on the device

     

       12
       +
       <filename>/dev/sda2</filename>:

     

       13
       +
       

     

       14
       +
       <screen>

     

       15
       +
       $ cryptsetup luksFormat /dev/sda2

     

       16
       +
       

     

       17
       +
       WARNING!

     

       18
       +
       ========

     

       19
       +
       This will overwrite data on /dev/sda2 irrevocably.

     

       20
       +
       

     

       21
       +
       Are you sure? (Type uppercase yes): YES

     

       22
       +
       Enter LUKS passphrase: ***

     

       23
       +
       Verify passphrase: ***

     

       24
       +
       

     

       25
       +
       $ cryptsetup luksOpen /dev/sda2 crypted

     

       26
       +
       Enter passphrase for /dev/sda2: ***

     

       27
       +
       

     

       28
       +
       $ mkfs.ext4 /dev/mapper/crypted

     

       29
       +
       </screen>

     

       30
       +
       

     

       31
       +
       To ensure that this file system is automatically mounted at boot time

     

       32
       +
       as <filename>/</filename>, add the following to

     

       33
       +
       <filename>configuration.nix</filename>:

     

       34
       +
       

     

       35
       +
       <programlisting>

     

       36
       +
       boot.initrd.luks.devices = [ { device = "/dev/sda2"; name = "crypted"; } ];

     

       37
       +
       fileSystems."/".device = "/dev/mapper/crypted";

     

       38
       +
       </programlisting>

     

       39
       +
       

     

       40
       +
       </para>

     

       41
       +
       

     

       42
       +
       </section>

+166

nixos/doc/manual/configuration/abstractions.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-module-abstractions">

     

       6
       +
       

     

       7
       +
       <title>Abstractions</title>

     

       8
       +
       

     

       9
       +
       <para>If you find yourself repeating yourself over and over, it’s time

     

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

     

       11
       +
       

     

       12
       +
       <programlisting>

     

       13
       +
       {

     

       14
       +
         services.httpd.virtualHosts =

     

       15
       +
           [ { hostName = "example.org";

     

       16
       +
               documentRoot = "/webroot";

     

       17
       +
               adminAddr = "alice@example.org";

     

       18
       +
               enableUserDir = true;

     

       19
       +
             }

     

       20
       +
             { hostName = "example.org";

     

       21
       +
               documentRoot = "/webroot";

     

       22
       +
               adminAddr = "alice@example.org";

     

       23
       +
               enableUserDir = true;

     

       24
       +
               enableSSL = true;

     

       25
       +
               sslServerCert = "/root/ssl-example-org.crt";

     

       26
       +
               sslServerKey = "/root/ssl-example-org.key";

     

       27
       +
             }

     

       28
       +
           ];

     

       29
       +
       }

     

       30
       +
       </programlisting>

     

       31
       +
       

     

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

     

       33
       +
       only difference is that the second one has SSL enabled.  To prevent

     

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

     

       35
       +
       

     

       36
       +
       <programlisting>

     

       37
       +
       let

     

       38
       +
         exampleOrgCommon =

     

       39
       +
           { hostName = "example.org";

     

       40
       +
             documentRoot = "/webroot";

     

       41
       +
             adminAddr = "alice@example.org";

     

       42
       +
             enableUserDir = true;

     

       43
       +
           };

     

       44
       +
       in

     

       45
       +
       {

     

       46
       +
         services.httpd.virtualHosts =

     

       47
       +
           [ exampleOrgCommon

     

       48
       +
             (exampleOrgCommon // {

     

       49
       +
               enableSSL = true;

     

       50
       +
               sslServerCert = "/root/ssl-example-org.crt";

     

       51
       +
               sslServerKey = "/root/ssl-example-org.key";

     

       52
       +
             })

     

       53
       +
           ];

     

       54
       +
       }

     

       55
       +
       </programlisting>

     

       56
       +
       

     

       57
       +
       The <literal>let exampleOrgCommon =

     

       58
       +
       <replaceable>...</replaceable></literal> defines a variable named

     

       59
       +
       <literal>exampleOrgCommon</literal>.  The <literal>//</literal>

     

       60
       +
       operator merges two attribute sets, so the configuration of the second

     

       61
       +
       virtual host is the set <literal>exampleOrgCommon</literal> extended

     

       62
       +
       with the SSL options.</para>

     

       63
       +
       

     

       64
       +
       <para>You can write a <literal>let</literal> wherever an expression is

     

       65
       +
       allowed.  Thus, you also could have written:

     

       66
       +
       

     

       67
       +
       <programlisting>

     

       68
       +
       {

     

       69
       +
         services.httpd.virtualHosts =

     

       70
       +
           let exampleOrgCommon = <replaceable>...</replaceable>; in

     

       71
       +
           [ exampleOrgCommon

     

       72
       +
             (exampleOrgCommon // { <replaceable>...</replaceable> })

     

       73
       +
           ];

     

       74
       +
       }

     

       75
       +
       </programlisting>

     

       76
       +
       

     

       77
       +
       but not <literal>{ let exampleOrgCommon =

     

       78
       +
       <replaceable>...</replaceable>; in <replaceable>...</replaceable>;

     

       79
       +
       }</literal> since attributes (as opposed to attribute values) are not

     

       80
       +
       expressions.</para>

     

       81
       +
       

     

       82
       +
       <para><emphasis>Functions</emphasis> provide another method of

     

       83
       +
       abstraction.  For instance, suppose that we want to generate lots of

     

       84
       +
       different virtual hosts, all with identical configuration except for

     

       85
       +
       the host name.  This can be done as follows:

     

       86
       +
       

     

       87
       +
       <programlisting>

     

       88
       +
       {

     

       89
       +
         services.httpd.virtualHosts =

     

       90
       +
           let

     

       91
       +
             makeVirtualHost = name:

     

       92
       +
               { hostName = name;

     

       93
       +
                 documentRoot = "/webroot";

     

       94
       +
                 adminAddr = "alice@example.org";

     

       95
       +
               };

     

       96
       +
           in

     

       97
       +
             [ (makeVirtualHost "example.org")

     

       98
       +
               (makeVirtualHost "example.com")

     

       99
       +
               (makeVirtualHost "example.gov")

     

       100
       +
               (makeVirtualHost "example.nl")

     

       101
       +
             ];

     

       102
       +
       }

     

       103
       +
       </programlisting>

     

       104
       +
       

     

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

     

       106
       +
       single argument <literal>name</literal> and returns the configuration

     

       107
       +
       for a virtual host.  That function is then called for several names to

     

       108
       +
       produce the list of virtual host configurations.</para>

     

       109
       +
       

     

       110
       +
       <para>We can further improve on this by using the function

     

       111
       +
       <varname>map</varname>, which applies another function to every

     

       112
       +
       element in a list:

     

       113
       +
       

     

       114
       +
       <programlisting>

     

       115
       +
       {

     

       116
       +
         services.httpd.virtualHosts =

     

       117
       +
           let

     

       118
       +
             makeVirtualHost = <replaceable>...</replaceable>;

     

       119
       +
           in map makeVirtualHost

     

       120
       +
             [ "example.org" "example.com" "example.gov" "example.nl" ];

     

       121
       +
       }

     

       122
       +
       </programlisting>

     

       123
       +
       

     

       124
       +
       (The function <literal>map</literal> is called a

     

       125
       +
       <emphasis>higher-order function</emphasis> because it takes another

     

       126
       +
       function as an argument.)</para>

     

       127
       +
       

     

       128
       +
       <para>What if you need more than one argument, for instance, if we

     

       129
       +
       want to use a different <literal>documentRoot</literal> for each

     

       130
       +
       virtual host?  Then we can make <varname>makeVirtualHost</varname> a

     

       131
       +
       function that takes a <emphasis>set</emphasis> as its argument, like this:

     

       132
       +
       

     

       133
       +
       <programlisting>

     

       134
       +
       {

     

       135
       +
         services.httpd.virtualHosts =

     

       136
       +
           let

     

       137
       +
             makeVirtualHost = { name, root }:

     

       138
       +
               { hostName = name;

     

       139
       +
                 documentRoot = root;

     

       140
       +
                 adminAddr = "alice@example.org";

     

       141
       +
               };

     

       142
       +
           in map makeVirtualHost

     

       143
       +
             [ { name = "example.org"; root = "/sites/example.org"; }

     

       144
       +
               { name = "example.com"; root = "/sites/example.com"; }

     

       145
       +
               { name = "example.gov"; root = "/sites/example.gov"; }

     

       146
       +
               { name = "example.nl"; root = "/sites/example.nl"; }

     

       147
       +
             ];

     

       148
       +
       }

     

       149
       +
       </programlisting>

     

       150
       +
       

     

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

     

       152
       +
       <filename>/sites</filename> named after the virtual host), it would

     

       153
       +
       have been shorter to define <varname>makeVirtualHost</varname> as

     

       154
       +
       <programlisting>

     

       155
       +
       makeVirtualHost = name:

     

       156
       +
         { hostName = name;

     

       157
       +
           documentRoot = "/sites/${name}";

     

       158
       +
           adminAddr = "alice@example.org";

     

       159
       +
         };

     

       160
       +
       </programlisting>

     

       161
       +
       

     

       162
       +
       Here, the construct

     

       163
       +
       <literal>${<replaceable>...</replaceable>}</literal> allows the result

     

       164
       +
       of an expression to be spliced into a string.</para>

     

       165
       +
       

     

       166
       +
       </section>

+24

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="ad-hoc-network-config">

     

       6
       +
       

     

       7
       +
       <title>Ad-Hoc Configuration</title>

     

       8
       +
       

     

       9
       +
       <para>You can use <option>networking.localCommands</option> to specify

     

       10
       +
       shell commands to be run at the end of

     

       11
       +
       <literal>network-setup.service</literal>.  This is useful for doing

     

       12
       +
       network configuration not covered by the existing NixOS modules.  For

     

       13
       +
       instance, to statically configure an IPv6 address:

     

       14
       +
       

     

       15
       +
       <programlisting>

     

       16
       +
       networking.localCommands =

     

       17
       +
         ''

     

       18
       +
           ip -6 addr add 2001:610:685:1::1/64 dev eth0

     

       19
       +
         '';

     

       20
       +
       </programlisting>

     

       21
       +
       

     

       22
       +
       </para>

     

       23
       +
       

     

       24
       +
       </section>

+63

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-ad-hoc-packages">

     

       6
       +
       

     

       7
       +
       <title>Ad-Hoc Package Management</title>

     

       8
       +
       

     

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

     

       10
       +
       uninstall packages from the command line.  For instance, to install

     

       11
       +
       Mozilla Thunderbird:

     

       12
       +
       

     

       13
       +
       <screen>

     

       14
       +
       $ nix-env -iA nixos.pkgs.thunderbird</screen>

     

       15
       +
       

     

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

     

       17
       +
       profile <filename>/nix/var/nix/profiles/default</filename> and visible

     

       18
       +
       to all users of the system; otherwise, the package ends up in

     

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

     

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

     

       21
       +
       specifies the package by its attribute name; without it, the package

     

       22
       +
       is installed by matching against its package name

     

       23
       +
       (e.g. <literal>thunderbird</literal>).  The latter is slower because

     

       24
       +
       it requires matching against all available Nix packages, and is

     

       25
       +
       ambiguous if there are multiple matching packages.</para>

     

       26
       +
       

     

       27
       +
       <para>Packages come from the NixOS channel.  You typically upgrade a

     

       28
       +
       package by updating to the latest version of the NixOS channel:

     

       29
       +
       <screen>

     

       30
       +
       $ nix-channel --update nixos

     

       31
       +
       </screen>

     

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

     

       33
       +
       in the profile are <emphasis>not</emphasis> affected; this is the

     

       34
       +
       crucial difference with the declarative style of package management,

     

       35
       +
       where running <command>nixos-rebuild switch</command> causes all

     

       36
       +
       packages to be updated to their current versions in the NixOS channel.

     

       37
       +
       You can however upgrade all packages for which there is a newer

     

       38
       +
       version by doing:

     

       39
       +
       <screen>

     

       40
       +
       $ nix-env -u '*'

     

       41
       +
       </screen>

     

       42
       +
       </para>

     

       43
       +
       

     

       44
       +
       <para>A package can be uninstalled using the <option>-e</option>

     

       45
       +
       flag:

     

       46
       +
       <screen>

     

       47
       +
       $ nix-env -e thunderbird

     

       48
       +
       </screen>

     

       49
       +
       </para>

     

       50
       +
       

     

       51
       +
       <para>Finally, you can roll back an undesirable

     

       52
       +
       <command>nix-env</command> action:

     

       53
       +
       <screen>

     

       54
       +
       $ nix-env --rollback

     

       55
       +
       </screen>

     

       56
       +
       </para>

     

       57
       +
       

     

       58
       +
       <para><command>nix-env</command> has many more flags.  For details,

     

       59
       +
       see the

     

       60
       +
       <citerefentry><refentrytitle>nix-env</refentrytitle><manvolnum>1</manvolnum></citerefentry>

     

       61
       +
       manpage or the Nix manual.</para>

     

       62
       +
       

     

       63
       +
       </section>

+84

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-custom-packages">

     

       6
       +
       

     

       7
       +
       <title>Adding Custom Packages</title>

     

       8
       +
       

     

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

     

       10
       +
       In that case, you can do two things.  First, you can clone the Nixpkgs

     

       11
       +
       repository, add the package to your clone, and (optionally) submit a

     

       12
       +
       patch or pull request to have it accepted into the main Nixpkgs

     

       13
       +
       repository.  This is described in detail in the <link

     

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

     

       15
       +
       In short, you clone Nixpkgs:

     

       16
       +
       

     

       17
       +
       <screen>

     

       18
       +
       $ git clone git://github.com/NixOS/nixpkgs.git

     

       19
       +
       $ cd nixpkgs

     

       20
       +
       </screen>

     

       21
       +
       

     

       22
       +
       Then you write and test the package as described in the Nixpkgs

     

       23
       +
       manual.  Finally, you add it to

     

       24
       +
       <literal>environment.systemPackages</literal>, e.g.

     

       25
       +
       

     

       26
       +
       <programlisting>

     

       27
       +
       environment.systemPackages = [ pkgs.my-package ];

     

       28
       +
       </programlisting>

     

       29
       +
       

     

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

     

       31
       +
       Nixpkgs tree:

     

       32
       +
       

     

       33
       +
       <screen>

     

       34
       +
       $ nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>

     

       35
       +
       

     

       36
       +
       </para>

     

       37
       +
       

     

       38
       +
       <para>The second possibility is to add the package outside of the

     

       39
       +
       Nixpkgs tree.  For instance, here is how you specify a build of the

     

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

     

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

     

       42
       +
       

     

       43
       +
       <programlisting>

     

       44
       +
       environment.systemPackages =

     

       45
       +
         let

     

       46
       +
           my-hello = with pkgs; stdenv.mkDerivation rec {

     

       47
       +
             name = "hello-2.8";

     

       48
       +
             src = fetchurl {

     

       49
       +
               url = "mirror://gnu/hello/${name}.tar.gz";

     

       50
       +
               sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";

     

       51
       +
             };

     

       52
       +
           };

     

       53
       +
         in

     

       54
       +
         [ my-hello ];

     

       55
       +
       </programlisting>

     

       56
       +
       

     

       57
       +
       Of course, you can also move the definition of

     

       58
       +
       <literal>my-hello</literal> into a separate Nix expression, e.g.

     

       59
       +
       <programlisting>

     

       60
       +
       environment.systemPackages = [ (import ./my-hello.nix) ];

     

       61
       +
       </programlisting>

     

       62
       +
       where <filename>my-hello.nix</filename> contains:

     

       63
       +
       <programlisting>

     

       64
       +
       with import &lt;nixpkgs> {}; # bring all of Nixpkgs into scope

     

       65
       +
       

     

       66
       +
       stdenv.mkDerivation rec {

     

       67
       +
         name = "hello-2.8";

     

       68
       +
         src = fetchurl {

     

       69
       +
           url = "mirror://gnu/hello/${name}.tar.gz";

     

       70
       +
           sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";

     

       71
       +
         };

     

       72
       +
       }

     

       73
       +
       </programlisting>

     

       74
       +
       

     

       75
       +
       This allows testing the package easily:

     

       76
       +
       <screen>

     

       77
       +
       $ nix-build my-hello.nix

     

       78
       +
       $ ./result/bin/hello

     

       79
       +
       Hello, world!

     

       80
       +
       </screen>

     

       81
       +
       

     

       82
       +
       </para>

     

       83
       +
       

     

       84
       +
       </section>

+213

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
           version="5.0"

     

       5
       +
           xml:id="sec-configuration-file">

     

       6
       +
       

     

       7
       +
       <title>NixOS Configuration File</title>

     

       8
       +
       

     

       9
       +
       <para>The NixOS configuration file generally looks like this:

     

       10
       +
       

     

       11
       +
       <programlisting>

     

       12
       +
       { config, pkgs, ... }:

     

       13
       +
       

     

       14
       +
       { <replaceable>option definitions</replaceable>

     

       15
       +
       }

     

       16
       +
       </programlisting>

     

       17
       +
       

     

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

     

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

     

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

     

       21
       +
       explained later.)  The function returns a <emphasis>set</emphasis> of

     

       22
       +
       option definitions (<literal>{ <replaceable>...</replaceable> }</literal>).  These definitions have the

     

       23
       +
       form <literal><replaceable>name</replaceable> =

     

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

     

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

     

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

     

       27
       +
       

     

       28
       +
       <programlisting>

     

       29
       +
       { config, pkgs, ... }:

     

       30
       +
       

     

       31
       +
       { services.httpd.enable = true;

     

       32
       +
         services.httpd.adminAddr = "alice@example.org";

     

       33
       +
         services.httpd.documentRoot = "/webroot";

     

       34
       +
       }

     

       35
       +
       </programlisting>

     

       36
       +
       

     

       37
       +
       defines a configuration with three option definitions that together

     

       38
       +
       enable the Apache HTTP Server with <filename>/webroot</filename> as

     

       39
       +
       the document root.</para>

     

       40
       +
       

     

       41
       +
       <para>Sets can be nested, and in fact dots in option names are

     

       42
       +
       shorthand for defining a set containing another set.  For instance,

     

       43
       +
       <option>services.httpd.enable</option> defines a set named

     

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

     

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

     

       46
       +
       named <varname>enable</varname> with value <literal>true</literal>.

     

       47
       +
       This means that the example above can also be written as:

     

       48
       +
       

     

       49
       +
       <programlisting>

     

       50
       +
       { config, pkgs, ... }:

     

       51
       +
       

     

       52
       +
       { services = {

     

       53
       +
           httpd = {

     

       54
       +
             enable = true;

     

       55
       +
             adminAddr = "alice@example.org";

     

       56
       +
             documentRoot = "/webroot";

     

       57
       +
           };

     

       58
       +
         };

     

       59
       +
       }

     

       60
       +
       </programlisting>

     

       61
       +
       

     

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

     

       63
       +
       that share the same prefix (such as

     

       64
       +
       <literal>services.httpd</literal>).</para>

     

       65
       +
       

     

       66
       +
       <para>NixOS checks your option definitions for correctness.  For

     

       67
       +
       instance, if you try to define an option that doesn’t exist (that is,

     

       68
       +
       doesn’t have a corresponding <emphasis>option declaration</emphasis>),

     

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

     

       70
       +
       <screen>

     

       71
       +
       The option `services.httpd.enabl' defined in `/etc/nixos/configuration.nix' does not exist.

     

       72
       +
       </screen>

     

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

     

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

     

       75
       +
       (<literal>true</literal> or <literal>false</literal>).  Trying to give

     

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

     

       77
       +
       <screen>

     

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

     

       79
       +
       </screen>

     

       80
       +
       

     

       81
       +
       </para>

     

       82
       +
       

     

       83
       +
       <para>Options have various types of values.  The most important are:

     

       84
       +
       

     

       85
       +
       <variablelist>

     

       86
       +
         <varlistentry>

     

       87
       +
           <term>Strings</term>

     

       88
       +
           <listitem>

     

       89
       +
             <para>Strings are enclosed in double quotes, e.g.

     

       90
       +
       

     

       91
       +
       <programlisting>

     

       92
       +
       networking.hostName = "dexter";

     

       93
       +
       </programlisting>

     

       94
       +
       

     

       95
       +
             Special characters can be escaped by prefixing them with a

     

       96
       +
             backslash (e.g. <literal>\"</literal>).</para>

     

       97
       +
       

     

       98
       +
             <para>Multi-line strings can be enclosed in <emphasis>double

     

       99
       +
             single quotes</emphasis>, e.g.

     

       100
       +
       

     

       101
       +
       <programlisting>

     

       102
       +
       networking.extraHosts =

     

       103
       +
         ''

     

       104
       +
           127.0.0.2 other-localhost

     

       105
       +
           10.0.0.1 server

     

       106
       +
         '';

     

       107
       +
       </programlisting>

     

       108
       +
       

     

       109
       +
             The main difference is that preceding whitespace is

     

       110
       +
             automatically stripped from each line, and that characters like

     

       111
       +
             <literal>"</literal> and <literal>\</literal> are not special

     

       112
       +
             (making it more convenient for including things like shell

     

       113
       +
             code).</para>

     

       114
       +
           </listitem>

     

       115
       +
         </varlistentry>

     

       116
       +
       

     

       117
       +
         <varlistentry>

     

       118
       +
           <term>Booleans</term>

     

       119
       +
           <listitem>

     

       120
       +
             <para>These can be <literal>true</literal> or

     

       121
       +
             <literal>false</literal>, e.g.

     

       122
       +
       

     

       123
       +
       <programlisting>

     

       124
       +
       networking.firewall.enable = true;

     

       125
       +
       networking.firewall.allowPing = false;

     

       126
       +
       </programlisting>

     

       127
       +
             </para>

     

       128
       +
           </listitem>

     

       129
       +
         </varlistentry>

     

       130
       +
       

     

       131
       +
         <varlistentry>

     

       132
       +
           <term>Integers</term>

     

       133
       +
           <listitem>

     

       134
       +
             <para>For example,

     

       135
       +
       

     

       136
       +
       <programlisting>

     

       137
       +
       boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;

     

       138
       +
       </programlisting>

     

       139
       +
       

     

       140
       +
             (Note that here the attribute name

     

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

     

       142
       +
             quotes to prevent it from being interpreted as a set named

     

       143
       +
             <literal>net</literal> containing a set named

     

       144
       +
             <literal>ipv4</literal>, and so on.  This is because it’s not a

     

       145
       +
             NixOS option but the literal name of a Linux kernel

     

       146
       +
             setting.)</para>

     

       147
       +
           </listitem>

     

       148
       +
         </varlistentry>

     

       149
       +
       

     

       150
       +
         <varlistentry>

     

       151
       +
           <term>Sets</term>

     

       152
       +
           <listitem>

     

       153
       +
             <para>Sets were introduced above.  They are name/value pairs

     

       154
       +
             enclosed in braces, as in the option definition

     

       155
       +
       

     

       156
       +
       <programlisting>

     

       157
       +
       fileSystems."/boot" =

     

       158
       +
         { device = "/dev/sda1";

     

       159
       +
           fsType = "ext4";

     

       160
       +
           options = "rw,data=ordered,relatime";

     

       161
       +
         };

     

       162
       +
       </programlisting>

     

       163
       +
             </para>

     

       164
       +
           </listitem>

     

       165
       +
         </varlistentry>

     

       166
       +
       

     

       167
       +
         <varlistentry>

     

       168
       +
           <term>Lists</term>

     

       169
       +
           <listitem>

     

       170
       +
             <para>The important thing to note about lists is that list

     

       171
       +
             elements are separated by whitespace, like this:

     

       172
       +
       

     

       173
       +
       <programlisting>

     

       174
       +
       boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];

     

       175
       +
       </programlisting>

     

       176
       +
       

     

       177
       +
             List elements can be any other type, e.g. sets:

     

       178
       +
       

     

       179
       +
       <programlisting>

     

       180
       +
       swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];

     

       181
       +
       </programlisting>

     

       182
       +
             </para>

     

       183
       +
           </listitem>

     

       184
       +
         </varlistentry>

     

       185
       +
       

     

       186
       +
         <varlistentry>

     

       187
       +
           <term>Packages</term>

     

       188
       +
           <listitem>

     

       189
       +
             <para>Usually, the packages you need are already part of the Nix

     

       190
       +
             Packages collection, which is a set that can be accessed through

     

       191
       +
             the function argument <varname>pkgs</varname>.  Typical uses:

     

       192
       +
       

     

       193
       +
       <programlisting>

     

       194
       +
       environment.systemPackages =

     

       195
       +
         [ pkgs.thunderbird

     

       196
       +
           pkgs.emacs

     

       197
       +
         ];

     

       198
       +
       

     

       199
       +
       postgresql.package = pkgs.postgresql90;

     

       200
       +
       </programlisting>

     

       201
       +
       

     

       202
       +
             The latter option definition changes the default PostgreSQL

     

       203
       +
             package used by NixOS’s PostgreSQL service to 9.0.  For more

     

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

     

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

     

       206
       +
           </listitem>

     

       207
       +
         </varlistentry>

     

       208
       +
       

     

       209
       +
       </variablelist>

     

       210
       +
       

     

       211
       +
       </para>

     

       212
       +
       

     

       213
       +
       </section>

+27

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

···

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

     

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

     

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

     

       4
       +
                version="5.0"

     

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

     

       6
       +
       

     

       7
       +
       <title>Configuration Syntax</title>

     

       8
       +
       

     

       9
       +
       <para>The NixOS configuration file

     

       10
       +
       <filename>/etc/nixos/configuration.nix</filename> is actually a

     

       11
       +
       <emphasis>Nix expression</emphasis>, which is the Nix package

     

       12
       +
       manager’s purely functional language for describing how to build

     

       13
       +
       packages and configurations.  This means you have all the expressive

     

       14
       +
       power of that language at your disposal, including the ability to

     

       15
       +
       abstract over common patterns, which is very useful when managing

     

       16
       +
       complex systems.  The syntax and semantics of the Nix language are

     

       17
       +
       fully described in the <link

     

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

     

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

     

       20
       +
       constructs useful in NixOS configuration files.</para>

     

       21
       +
       

     

       22
       +
       <xi:include href="config-file.xml" />

     

       23
       +
       <xi:include href="abstractions.xml" />

     

       24
       +
       <xi:include href="modularity.xml" />

     

       25
       +
       <xi:include href="summary.xml" />

     

       26
       +
       

     

       27
       +
       </chapter>

+29

nixos/doc/manual/configuration/configuration.xml

···

       1
       +
       <part xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
             version="5.0"

     

       5
       +
             xml:id="ch-configuration">

     

       6
       +
       

     

       7
       +
       <title>Configuration</title>

     

       8
       +
       

     

       9
       +
       <partintro>

     

       10
       +
       

     

       11
       +
       <para>This chapter describes how to configure various aspects of a

     

       12
       +
       NixOS machine through the configuration file

     

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

     

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

     

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

     

       16
       +
       

     

       17
       +
       </partintro>

     

       18
       +
       

     

       19
       +
       <xi:include href="config-syntax.xml" />

     

       20
       +
       <xi:include href="package-mgmt.xml" />

     

       21
       +
       <xi:include href="user-mgmt.xml" />

     

       22
       +
       <xi:include href="file-systems.xml" />

     

       23
       +
       <xi:include href="x-windows.xml" />

     

       24
       +
       <xi:include href="networking.xml" />

     

       25
       +
       <xi:include href="linux-kernel.xml" />

     

       26
       +
       

     

       27
       +
       <!-- Apache; libvirtd virtualisation -->

     

       28
       +
       

     

       29
       +
       </part>

+92

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-customising-packages">

     

       6
       +
       

     

       7
       +
       <title>Customising Packages</title>

     

       8
       +
       

     

       9
       +
       <para>Some packages in Nixpkgs have options to enable or disable

     

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

     

       11
       +
       instance, the Firefox wrapper package (which provides Firefox with a

     

       12
       +
       set of plugins such as the Adobe Flash player) has an option to enable

     

       13
       +
       the Google Talk plugin.  It can be set in

     

       14
       +
       <filename>configuration.nix</filename> as follows:

     

       15
       +
       

     

       16
       +
       <filename>

     

       17
       +
       nixpkgs.config.firefox.enableGoogleTalkPlugin = true;

     

       18
       +
       </filename>

     

       19
       +
       </para>

     

       20
       +
       

     

       21
       +
       <warning><para>Unfortunately, Nixpkgs currently lacks a way to query

     

       22
       +
       available configuration options.</para></warning>

     

       23
       +
       

     

       24
       +
       <para>Apart from high-level options, it’s possible to tweak a package

     

       25
       +
       in almost arbitrary ways, such as changing or disabling dependencies

     

       26
       +
       of a package.  For instance, the Emacs package in Nixpkgs by default

     

       27
       +
       has a dependency on GTK+ 2.  If you want to build it against GTK+ 3,

     

       28
       +
       you can specify that as follows:

     

       29
       +
       

     

       30
       +
       <programlisting>

     

       31
       +
       environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];

     

       32
       +
       </programlisting>

     

       33
       +
       

     

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

     

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

     

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

     

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

     

       38
       +
       causing Emacs to depend on GTK+ 3.  (The parentheses are necessary

     

       39
       +
       because in Nix, function application binds more weakly than list

     

       40
       +
       construction, so without them,

     

       41
       +
       <literal>environment.systemPackages</literal> would be a list with two

     

       42
       +
       elements.)</para>

     

       43
       +
       

     

       44
       +
       <para>Even greater customisation is possible using the function

     

       45
       +
       <varname>overrideDerivation</varname>.  While the

     

       46
       +
       <varname>override</varname> mechanism above overrides the arguments of

     

       47
       +
       a package function, <varname>overrideDerivation</varname> allows

     

       48
       +
       changing the <emphasis>result</emphasis> of the function.  This

     

       49
       +
       permits changing any aspect of the package, such as the source code.

     

       50
       +
       For instance, if you want to override the source code of Emacs, you

     

       51
       +
       can say:

     

       52
       +
       

     

       53
       +
       <programlisting>

     

       54
       +
       environment.systemPackages =

     

       55
       +
         [ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: {

     

       56
       +
             name = "emacs-25.0-pre";

     

       57
       +
             src = /path/to/my/emacs/tree;

     

       58
       +
           }))

     

       59
       +
         ];

     

       60
       +
       </programlisting>

     

       61
       +
       

     

       62
       +
       Here, <varname>overrideDerivation</varname> takes the Nix derivation

     

       63
       +
       specified by <varname>pkgs.emacs</varname> and produces a new

     

       64
       +
       derivation in which the original’s <literal>name</literal> and

     

       65
       +
       <literal>src</literal> attribute have been replaced by the given

     

       66
       +
       values.  The original attributes are accessible via

     

       67
       +
       <varname>attrs</varname>.</para>

     

       68
       +
       

     

       69
       +
       <para>The overrides shown above are not global.  They do not affect

     

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

     

       71
       +
       the original rather than the customised package.  This means that if

     

       72
       +
       another package in your system depends on the original package, you

     

       73
       +
       end up with two instances of the package.  If you want to have

     

       74
       +
       everything depend on your customised instance, you can apply a

     

       75
       +
       <emphasis>global</emphasis> override as follows:

     

       76
       +
       

     

       77
       +
       <screen>

     

       78
       +
       nixpkgs.config.packageOverrides = pkgs:

     

       79
       +
         { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };

     

       80
       +
         };

     

       81
       +
       </screen>

     

       82
       +
       

     

       83
       +
       The effect of this definition is essentially equivalent to modifying

     

       84
       +
       the <literal>emacs</literal> attribute in the Nixpkgs source tree.

     

       85
       +
       Any package in Nixpkgs that depends on <literal>emacs</literal> will

     

       86
       +
       be passed your customised instance.  (However, the value

     

       87
       +
       <literal>pkgs.emacs</literal> in

     

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

     

       89
       +
       original rather than overridden instance, to prevent an infinite

     

       90
       +
       recursion.)</para>

     

       91
       +
       

     

       92
       +
       </section>

+43

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-declarative-package-mgmt">

     

       6
       +
       

     

       7
       +
       <title>Declarative Package Management</title>

     

       8
       +
       

     

       9
       +
       <para>With declarative package management, you specify which packages

     

       10
       +
       you want on your system by setting the option

     

       11
       +
       <option>environment.systemPackages</option>.  For instance, adding the

     

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

     

       13
       +
       Mozilla Thunderbird email application:

     

       14
       +
       

     

       15
       +
       <programlisting>

     

       16
       +
       environment.systemPackages = [ pkgs.thunderbird ];

     

       17
       +
       </programlisting>

     

       18
       +
       

     

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

     

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

     

       21
       +
       <command>nixos-rebuild switch</command>.</para>

     

       22
       +
       

     

       23
       +
       <para>You can get a list of the available packages as follows:

     

       24
       +
       <screen>

     

       25
       +
       $ nix-env -qaP '*' --description

     

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

     

       27
       +
       <replaceable>...</replaceable>

     

       28
       +
       </screen>

     

       29
       +
       

     

       30
       +
       The first column in the output is the <emphasis>attribute

     

       31
       +
       name</emphasis>, such as

     

       32
       +
       <literal>nixos.pkgs.thunderbird</literal>. (The

     

       33
       +
       <literal>nixos</literal> prefix allows distinguishing between

     

       34
       +
       different channels that you might have.)</para>

     

       35
       +
       

     

       36
       +
       <para>To “uninstall” a package, simply remove it from

     

       37
       +
       <option>environment.systemPackages</option> and run

     

       38
       +
       <command>nixos-rebuild switch</command>.</para>

     

       39
       +
       

     

       40
       +
       <xi:include href="customizing-packages.xml" />

     

       41
       +
       <xi:include href="adding-custom-packages.xml" />

     

       42
       +
       

     

       43
       +
       </section>

+40

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

···

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

     

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

     

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

     

       4
       +
                version="5.0"

     

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

     

       6
       +
       

     

       7
       +
       <title>File Systems</title>

     

       8
       +
       

     

       9
       +
       <para>You can define file systems using the

     

       10
       +
       <option>fileSystems</option> configuration option.  For instance, the

     

       11
       +
       following definition causes NixOS to mount the Ext4 file system on

     

       12
       +
       device <filename>/dev/disk/by-label/data</filename> onto the mount

     

       13
       +
       point <filename>/data</filename>:

     

       14
       +
       

     

       15
       +
       <programlisting>

     

       16
       +
       fileSystems."/data" =

     

       17
       +
         { device = "/dev/disk/by-label/data";

     

       18
       +
           fsType = "ext4";

     

       19
       +
         };

     

       20
       +
       </programlisting>

     

       21
       +
       

     

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

     

       23
       +
       For <option>device</option>, it’s best to use the topology-independent

     

       24
       +
       device aliases in <filename>/dev/disk/by-label</filename> and

     

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

     

       26
       +
       topology changes (e.g. if a disk is moved to another IDE

     

       27
       +
       controller).</para>

     

       28
       +
       

     

       29
       +
       <para>You can usually omit the file system type

     

       30
       +
       (<option>fsType</option>), since <command>mount</command> can usually

     

       31
       +
       detect the type and load the necessary kernel module automatically.

     

       32
       +
       However, if the file system is needed at early boot (in the initial

     

       33
       +
       ramdisk) and is not <literal>ext2</literal>, <literal>ext3</literal>

     

       34
       +
       or <literal>ext4</literal>, then it’s best to specify

     

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

     

       36
       +
       available.</para>

     

       37
       +
       

     

       38
       +
       <xi:include href="LUKS-file-systems.xml" />

     

       39
       +
       

     

       40
       +
       </chapter>

+38

nixos/doc/manual/configuration/firewall.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-firewall">

     

       6
       +
       

     

       7
       +
       <title>Firewall</title>

     

       8
       +
       

     

       9
       +
       <para>NixOS has a simple stateful firewall that blocks incoming

     

       10
       +
       connections and other unexpected packets.  The firewall applies to

     

       11
       +
       both IPv4 and IPv6 traffic. It is enabled by default. It can be

     

       12
       +
       disabled as follows:

     

       13
       +
       

     

       14
       +
       <programlisting>

     

       15
       +
       networking.firewall.enable = false;

     

       16
       +
       </programlisting>

     

       17
       +
       

     

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

     

       19
       +
       outside world:

     

       20
       +
       

     

       21
       +
       <programlisting>

     

       22
       +
       networking.firewall.allowedTCPPorts = [ 80 443 ];

     

       23
       +
       </programlisting>

     

       24
       +
       

     

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

     

       26
       +
       is enabled (<option>services.openssh.enable = true</option>).  UDP

     

       27
       +
       ports can be opened through

     

       28
       +
       <option>networking.firewall.allowedUDPPorts</option>.  Also of

     

       29
       +
       interest is

     

       30
       +
       

     

       31
       +
       <programlisting>

     

       32
       +
       networking.firewall.allowPing = true;

     

       33
       +
       </programlisting>

     

       34
       +
       

     

       35
       +
       to allow the machine to respond to ping requests.  (ICMPv6 pings are

     

       36
       +
       always allowed.)</para>

     

       37
       +
       

     

       38
       +
       </section>

+47

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-ipv4">

     

       6
       +
       

     

       7
       +
       <title>IPv4 Configuration</title>

     

       8
       +
       

     

       9
       +
       <para>By default, NixOS uses DHCP (specifically,

     

       10
       +
       <command>dhcpcd</command>) to automatically configure network

     

       11
       +
       interfaces.  However, you can configure an interface manually as

     

       12
       +
       follows:

     

       13
       +
       

     

       14
       +
       <programlisting>

     

       15
       +
       networking.interfaces.eth0 = { ipAddress = "192.168.1.2"; prefixLength = 24; };

     

       16
       +
       </programlisting>

     

       17
       +
       

     

       18
       +
       (The network prefix can also be specified using the option

     

       19
       +
       <literal>subnetMask</literal>,

     

       20
       +
       e.g. <literal>"255.255.255.0"</literal>, but this is deprecated.)

     

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

     

       22
       +
       servers:

     

       23
       +
       

     

       24
       +
       <programlisting>

     

       25
       +
       networking.defaultGateway = "192.168.1.1";

     

       26
       +
       networking.nameservers = [ "8.8.8.8" ];

     

       27
       +
       </programlisting>

     

       28
       +
       

     

       29
       +
       </para>

     

       30
       +
       

     

       31
       +
       <note><para>Statically configured interfaces are set up by the systemd

     

       32
       +
       service

     

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

     

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

     

       35
       +
       <literal>network-setup.service</literal>.</para></note>

     

       36
       +
       

     

       37
       +
       <para>The host name is set using <option>networking.hostName</option>:

     

       38
       +
       

     

       39
       +
       <programlisting>

     

       40
       +
       networking.hostName = "cartman";

     

       41
       +
       </programlisting>

     

       42
       +
       

     

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

     

       44
       +
       empty string (<literal>""</literal>) to allow the DHCP server to

     

       45
       +
       provide the host name.</para>

     

       46
       +
       

     

       47
       +
       </section>

+19

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

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-ipv6">

     

       6
       +
       

     

       7
       +
       <title>IPv6 Configuration</title>

     

       8
       +
       

     

       9
       +
       <para>IPv6 is enabled by default.  Stateless address autoconfiguration

     

       10
       +
       is used to automatically assign IPv6 addresses to all interfaces.  You

     

       11
       +
       can disable IPv6 support globally by setting:

     

       12
       +
       

     

       13
       +
       <programlisting>

     

       14
       +
       networking.enableIPv6 = false;

     

       15
       +
       </programlisting>

     

       16
       +
       

     

       17
       +
       </para>

     

       18
       +
       

     

       19
       +
       </section>

+69

nixos/doc/manual/configuration/linux-kernel.xml

···

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

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-kernel-config">

     

       6
       +
       

     

       7
       +
       <title>Linux Kernel</title>

     

       8
       +
       

     

       9
       +
       <para>You can override the Linux kernel and associated packages using

     

       10
       +
       the option <option>boot.kernelPackages</option>.  For instance, this

     

       11
       +
       selects the Linux 3.10 kernel:

     

       12
       +
       <programlisting>

     

       13
       +
       boot.kernelPackages = pkgs.linuxPackages_3_10;

     

       14
       +
       </programlisting>

     

       15
       +
       Note that this not only replaces the kernel, but also packages that

     

       16
       +
       are specific to the kernel version, such as the NVIDIA video drivers.

     

       17
       +
       This ensures that driver packages are consistent with the

     

       18
       +
       kernel.</para>

     

       19
       +
       

     

       20
       +
       <para>The default Linux kernel configuration should be fine for most users. You can see the configuration of your current kernel with the following command:

     

       21
       +
       <programlisting>

     

       22
       +
       cat /proc/config.gz | gunzip

     

       23
       +
       </programlisting>

     

       24
       +
       If you want to change the kernel configuration, you can use the

     

       25
       +
       <option>packageOverrides</option> feature (see <xref

     

       26
       +
       linkend="sec-customising-packages" />).  For instance, to enable

     

       27
       +
       support for the kernel debugger KGDB:

     

       28
       +
       

     

       29
       +
       <programlisting>

     

       30
       +
       nixpkgs.config.packageOverrides = pkgs:

     

       31
       +
         { linux_3_4 = pkgs.linux_3_4.override {

     

       32
       +
             extraConfig =

     

       33
       +
               ''

     

       34
       +
                 KGDB y

     

       35
       +
               '';

     

       36
       +
           };

     

       37
       +
         };

     

       38
       +
       </programlisting>

     

       39
       +
       

     

       40
       +
       <varname>extraConfig</varname> takes a list of Linux kernel

     

       41
       +
       configuration options, one per line.  The name of the option should

     

       42
       +
       not include the prefix <literal>CONFIG_</literal>.  The option value

     

       43
       +
       is typically <literal>y</literal>, <literal>n</literal> or

     

       44
       +
       <literal>m</literal> (to build something as a kernel module).</para>

     

       45
       +
       

     

       46
       +
       <para>Kernel modules for hardware devices are generally loaded

     

       47
       +
       automatically by <command>udev</command>.  You can force a module to

     

       48
       +
       be loaded via <option>boot.kernelModules</option>, e.g.

     

       49
       +
       <programlisting>

     

       50
       +
       boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];

     

       51
       +
       </programlisting>

     

       52
       +
       If the module is required early during the boot (e.g. to mount the

     

       53
       +
       root file system), you can use

     

       54
       +
       <option>boot.initrd.extraKernelModules</option>:

     

       55
       +
       <programlisting>

     

       56
       +
       boot.initrd.extraKernelModules = [ "cifs" ];

     

       57
       +
       </programlisting>

     

       58
       +
       This causes the specified modules and their dependencies to be added

     

       59
       +
       to the initial ramdark.</para>

     

       60
       +
       

     

       61
       +
       <para>Kernel runtime parameters can be set through

     

       62
       +
       <option>boot.kernel.sysctl</option>, e.g.

     

       63
       +
       <programlisting>

     

       64
       +
       boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;

     

       65
       +
       </programlisting>

     

       66
       +
       sets the kernel’s TCP keepalive time to 120 seconds.  To see the

     

       67
       +
       available parameters, run <command>sysctl -a</command>.</para>

     

       68
       +
       

     

       69
       +
       </chapter>

+143

nixos/doc/manual/configuration/modularity.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-modularity">

     

       6
       +
       

     

       7
       +
       <title>Modularity</title>

     

       8
       +
       

     

       9
       +
       <para>The NixOS configuration mechanism is modular.  If your

     

       10
       +
       <filename>configuration.nix</filename> becomes too big, you can split

     

       11
       +
       it into multiple files.  Likewise, if you have multiple NixOS

     

       12
       +
       configurations (e.g. for different computers) with some commonality,

     

       13
       +
       you can move the common configuration into a shared file.</para>

     

       14
       +
       

     

       15
       +
       <para>Modules have exactly the same syntax as

     

       16
       +
       <filename>configuration.nix</filename>.  In fact,

     

       17
       +
       <filename>configuration.nix</filename> is itself a module.  You can

     

       18
       +
       use other modules by including them from

     

       19
       +
       <filename>configuration.nix</filename>, e.g.:

     

       20
       +
       

     

       21
       +
       <programlisting>

     

       22
       +
       { config, pkgs, ... }:

     

       23
       +
       

     

       24
       +
       { imports = [ ./vpn.nix ./kde.nix ];

     

       25
       +
         services.httpd.enable = true;

     

       26
       +
         environment.systemPackages = [ pkgs.emacs ];

     

       27
       +
         <replaceable>...</replaceable>

     

       28
       +
       }

     

       29
       +
       </programlisting>

     

       30
       +
       

     

       31
       +
       Here, we include two modules from the same directory,

     

       32
       +
       <filename>vpn.nix</filename> and <filename>kde.nix</filename>.  The

     

       33
       +
       latter might look like this:

     

       34
       +
       

     

       35
       +
       <programlisting>

     

       36
       +
       { config, pkgs, ... }:

     

       37
       +
       

     

       38
       +
       { services.xserver.enable = true;

     

       39
       +
         services.xserver.displayManager.kdm.enable = true;

     

       40
       +
         services.xserver.desktopManager.kde4.enable = true;

     

       41
       +
         environment.systemPackages = [ pkgs.kde4.kscreensaver ];

     

       42
       +
       }

     

       43
       +
       </programlisting>

     

       44
       +
       

     

       45
       +
       Note that both <filename>configuration.nix</filename> and

     

       46
       +
       <filename>kde.nix</filename> define the option

     

       47
       +
       <option>environment.systemPackages</option>.  When multiple modules

     

       48
       +
       define an option, NixOS will try to <emphasis>merge</emphasis> the

     

       49
       +
       definitions.  In the case of

     

       50
       +
       <option>environment.systemPackages</option>, that’s easy: the lists of

     

       51
       +
       packages can simply be concatenated.  The value in

     

       52
       +
       <filename>configuration.nix</filename> is merged last, so for

     

       53
       +
       list-type options, it will appear at the end of the merged list. If

     

       54
       +
       you want it to appear first, you can use <varname>mkBefore</varname>:

     

       55
       +
       

     

       56
       +
       <programlisting>

     

       57
       +
       boot.kernelModules = mkBefore [ "kvm-intel" ];

     

       58
       +
       </programlisting>

     

       59
       +
       

     

       60
       +
       This causes the <literal>kvm-intel</literal> kernel module to be

     

       61
       +
       loaded before any other kernel modules.</para>

     

       62
       +
       

     

       63
       +
       <para>For other types of options, a merge may not be possible. For

     

       64
       +
       instance, if two modules define

     

       65
       +
       <option>services.httpd.adminAddr</option>,

     

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

     

       67
       +
       

     

       68
       +
       <screen>

     

       69
       +
       The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.

     

       70
       +
       </screen>

     

       71
       +
       

     

       72
       +
       When that happens, it’s possible to force one definition take

     

       73
       +
       precedence over the others:

     

       74
       +
       

     

       75
       +
       <programlisting>

     

       76
       +
       services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";

     

       77
       +
       </programlisting>

     

       78
       +
       

     

       79
       +
       </para>

     

       80
       +
       

     

       81
       +
       <para>When using multiple modules, you may need to access

     

       82
       +
       configuration values defined in other modules.  This is what the

     

       83
       +
       <varname>config</varname> function argument is for: it contains the

     

       84
       +
       complete, merged system configuration.  That is,

     

       85
       +
       <varname>config</varname> is the result of combining the

     

       86
       +
       configurations returned by every module<footnote><para>If you’re

     

       87
       +
       wondering how it’s possible that the (indirect)

     

       88
       +
       <emphasis>result</emphasis> of a function is passed as an

     

       89
       +
       <emphasis>input</emphasis> to that same function: that’s because Nix

     

       90
       +
       is a “lazy” language — it only computes values when they are needed.

     

       91
       +
       This works as long as no individual configuration value depends on

     

       92
       +
       itself.</para></footnote>.  For example, here is a module that adds

     

       93
       +
       some packages to <option>environment.systemPackages</option> only if

     

       94
       +
       <option>services.xserver.enable</option> is set to

     

       95
       +
       <literal>true</literal> somewhere else:

     

       96
       +
       

     

       97
       +
       <programlisting>

     

       98
       +
       { config, pkgs, ... }:

     

       99
       +
       

     

       100
       +
       { environment.systemPackages =

     

       101
       +
           if config.services.xserver.enable then

     

       102
       +
             [ pkgs.firefox

     

       103
       +
               pkgs.thunderbird

     

       104
       +
             ]

     

       105
       +
           else

     

       106
       +
             [ ];

     

       107
       +
       }

     

       108
       +
       </programlisting>

     

       109
       +
       

     

       110
       +
       </para>

     

       111
       +
       

     

       112
       +
       <para>With multiple modules, it may not be obvious what the final

     

       113
       +
       value of a configuration option is.  The command

     

       114
       +
       <option>nixos-option</option> allows you to find out:

     

       115
       +
       

     

       116
       +
       <screen>

     

       117
       +
       $ nixos-option services.xserver.enable

     

       118
       +
       true

     

       119
       +
       

     

       120
       +
       $ nixos-option boot.kernelModules

     

       121
       +
       [ "tun" "ipv6" "loop" <replaceable>...</replaceable> ]

     

       122
       +
       </screen>

     

       123
       +
       

     

       124
       +
       Interactive exploration of the configuration is possible using

     

       125
       +
       <command

     

       126
       +
       xlink:href="https://github.com/edolstra/nix-repl">nix-repl</command>,

     

       127
       +
       a read-eval-print loop for Nix expressions.  It’s not installed by

     

       128
       +
       default; run <literal>nix-env -i nix-repl</literal> to get it.  A

     

       129
       +
       typical use:

     

       130
       +
       

     

       131
       +
       <screen>

     

       132
       +
       $ nix-repl '&lt;nixos>'

     

       133
       +
       

     

       134
       +
       nix-repl> config.networking.hostName

     

       135
       +
       "mandark"

     

       136
       +
       

     

       137
       +
       nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts

     

       138
       +
       [ "example.org" "example.gov" ]

     

       139
       +
       </screen>

     

       140
       +
       

     

       141
       +
       </para>

     

       142
       +
       

     

       143
       +
       </section>

+27

nixos/doc/manual/configuration/network-manager.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-networkmanager">

     

       6
       +
       

     

       7
       +
       <title>NetworkManager</title>

     

       8
       +
       

     

       9
       +
       <para>To facilitate network configuration, some desktop environments

     

       10
       +
       use NetworkManager. You can enable NetworkManager by setting:

     

       11
       +
       

     

       12
       +
       <programlisting>

     

       13
       +
       services.networkmanager.enable = true;

     

       14
       +
       </programlisting>

     

       15
       +
       

     

       16
       +
       Some desktop managers (e.g., GNOME) enable NetworkManager

     

       17
       +
       automatically for you.</para>

     

       18
       +
       

     

       19
       +
       <para>All users that should have permission to change network settings

     

       20
       +
       must belong to the <code>networkmanager</code> group.</para>

     

       21
       +
       

     

       22
       +
       <note><para><code>services.networkmanager</code> and

     

       23
       +
       <code>services.wireless</code> can not be enabled at the same time:

     

       24
       +
       you can still connect to the wireless networks using

     

       25
       +
       NetworkManager.</para></note>

     

       26
       +
       

     

       27
       +
       </section>

+22

nixos/doc/manual/configuration/networking.xml

···

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

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-networking">

     

       6
       +
       

     

       7
       +
       <title>Networking</title>

     

       8
       +
       

     

       9
       +
       <para>This section describes how to configure networking components on

     

       10
       +
       your NixOS machine.</para>

     

       11
       +
       

     

       12
       +
       <xi:include href="network-manager.xml" />

     

       13
       +
       <xi:include href="ssh.xml" />

     

       14
       +
       <xi:include href="ipv4-config.xml" />

     

       15
       +
       <xi:include href="ipv6-config.xml" />

     

       16
       +
       <xi:include href="firewall.xml" />

     

       17
       +
       <xi:include href="wireless.xml" />

     

       18
       +
       <xi:include href="ad-hoc-network-config.xml" />

     

       19
       +
       

     

       20
       +
       <!-- TODO: OpenVPN, NAT -->

     

       21
       +
       

     

       22
       +
       </chapter>

+34

nixos/doc/manual/configuration/package-mgmt.xml

···

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

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-package-management">

     

       6
       +
       

     

       7
       +
       <title>Package Management</title>

     

       8
       +
       

     

       9
       +
       <para>This section describes how to add additional packages to your

     

       10
       +
       system.  NixOS has two distinct styles of package management:

     

       11
       +
       

     

       12
       +
       <itemizedlist>

     

       13
       +
       

     

       14
       +
         <listitem><para><emphasis>Declarative</emphasis>, where you declare

     

       15
       +
         what packages you want in your

     

       16
       +
         <filename>configuration.nix</filename>.  Every time you run

     

       17
       +
         <command>nixos-rebuild</command>, NixOS will ensure that you get a

     

       18
       +
         consistent set of binaries corresponding to your

     

       19
       +
         specification.</para></listitem>

     

       20
       +
       

     

       21
       +
         <listitem><para><emphasis>Ad hoc</emphasis>, where you install,

     

       22
       +
         upgrade and uninstall packages via the <command>nix-env</command>

     

       23
       +
         command.  This style allows mixing packages from different Nixpkgs

     

       24
       +
         versions.  It’s the only choice for non-root

     

       25
       +
         users.</para></listitem>

     

       26
       +
       

     

       27
       +
       </itemizedlist>

     

       28
       +
       

     

       29
       +
       </para>

     

       30
       +
       

     

       31
       +
       <xi:include href="declarative-packages.xml" />

     

       32
       +
       <xi:include href="ad-hoc-packages.xml" />

     

       33
       +
       

     

       34
       +
       </chapter>

+32

nixos/doc/manual/configuration/ssh.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-ssh">

     

       6
       +
       

     

       7
       +
       <title>Secure Shell Access</title>

     

       8
       +
       

     

       9
       +
       <para>Secure shell (SSH) access to your machine can be enabled by

     

       10
       +
       setting:

     

       11
       +
       

     

       12
       +
       <programlisting>

     

       13
       +
       services.openssh.enable = true;

     

       14
       +
       </programlisting>

     

       15
       +
       

     

       16
       +
       By default, root logins using a password are disallowed.  They can be

     

       17
       +
       disabled entirely by setting

     

       18
       +
       <literal>services.openssh.permitRootLogin</literal> to

     

       19
       +
       <literal>"no"</literal>.</para>

     

       20
       +
       

     

       21
       +
       <para>You can declaratively specify authorised RSA/DSA public keys for

     

       22
       +
       a user as follows:

     

       23
       +
       

     

       24
       +
       <!-- FIXME: this might not work if the user is unmanaged. -->

     

       25
       +
       <programlisting>

     

       26
       +
       users.extraUsers.alice.openssh.authorizedKeys.keys =

     

       27
       +
         [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];

     

       28
       +
       </programlisting>

     

       29
       +
       

     

       30
       +
       </para>

     

       31
       +
       

     

       32
       +
       </section>

+191

nixos/doc/manual/configuration/summary.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
           version="5.0"

     

       5
       +
           xml:id="sec-nix-syntax-summary">

     

       6
       +
       

     

       7
       +
       <title>Syntax Summary</title>

     

       8
       +
       

     

       9
       +
       <para>Below is a summary of the most important syntactic constructs in

     

       10
       +
       the Nix expression language.  It’s not complete.  In particular, there

     

       11
       +
       are many other built-in functions.  See the <link

     

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

     

       13
       +
       manual</link> for the rest.</para>

     

       14
       +
       

     

       15
       +
       <informaltable frame='none'>

     

       16
       +
         <tgroup cols='2'>

     

       17
       +
           <colspec colname='c1' rowsep='1' colsep='1' />

     

       18
       +
           <colspec colname='c2' rowsep='1' />

     

       19
       +
           <thead>

     

       20
       +
             <row>

     

       21
       +
               <entry>Example</entry>

     

       22
       +
               <entry>Description</entry>

     

       23
       +
             </row>

     

       24
       +
           </thead>

     

       25
       +
           <tbody>

     

       26
       +
       

     

       27
       +
             <row>

     

       28
       +
               <entry namest="c1" nameend="c2"><emphasis>Basic values</emphasis></entry>

     

       29
       +
             </row>

     

       30
       +
             <row>

     

       31
       +
               <entry><literal>"Hello world"</literal></entry>

     

       32
       +
               <entry>A string</entry>

     

       33
       +
             </row>

     

       34
       +
             <row>

     

       35
       +
               <entry><literal>"${pkgs.bash}/bin/sh"</literal></entry>

     

       36
       +
               <entry>A string containing an expression (expands to <literal>"/nix/store/<replaceable>hash</replaceable>-bash-<replaceable>version</replaceable>/bin/sh"</literal>)</entry>

     

       37
       +
             </row>

     

       38
       +
             <row>

     

       39
       +
               <entry><literal>true</literal>, <literal>false</literal></entry>

     

       40
       +
               <entry>Booleans</entry>

     

       41
       +
             </row>

     

       42
       +
             <row>

     

       43
       +
               <entry><literal>123</literal></entry>

     

       44
       +
               <entry>An integer</entry>

     

       45
       +
             </row>

     

       46
       +
             <row>

     

       47
       +
               <entry><literal>./foo.png</literal></entry>

     

       48
       +
               <entry>A path (relative to the containing Nix expression)</entry>

     

       49
       +
             </row>

     

       50
       +
       

     

       51
       +
             <row>

     

       52
       +
               <entry namest="c1" nameend="c2"><emphasis>Compound values</emphasis></entry>

     

       53
       +
             </row>

     

       54
       +
             <row>

     

       55
       +
               <entry><literal>{ x = 1; y = 2; }</literal></entry>

     

       56
       +
               <entry>An set with attributes names <literal>x</literal> and <literal>y</literal></entry>

     

       57
       +
             </row>

     

       58
       +
             <row>

     

       59
       +
               <entry><literal>{ foo.bar = 1; }</literal></entry>

     

       60
       +
               <entry>A nested set, equivalent to <literal>{ foo = { bar = 1; }; }</literal></entry>

     

       61
       +
             </row>

     

       62
       +
             <row>

     

       63
       +
               <entry><literal>rec { x = "bla"; y = x + "bar"; }</literal></entry>

     

       64
       +
               <entry>A recursive set, equivalent to <literal>{ x = "foo"; y = "foobar"; }</literal></entry>

     

       65
       +
             </row>

     

       66
       +
             <row>

     

       67
       +
               <entry><literal>[ "foo" "bar" ]</literal></entry>

     

       68
       +
               <entry>A list with two elements</entry>

     

       69
       +
             </row>

     

       70
       +
       

     

       71
       +
             <row>

     

       72
       +
               <entry namest="c1" nameend="c2"><emphasis>Operators</emphasis></entry>

     

       73
       +
             </row>

     

       74
       +
             <row>

     

       75
       +
               <entry><literal>"foo" + "bar"</literal></entry>

     

       76
       +
               <entry>String concatenation</entry>

     

       77
       +
             </row>

     

       78
       +
             <row>

     

       79
       +
               <entry><literal>1 + 2</literal></entry>

     

       80
       +
               <entry>Integer addition</entry>

     

       81
       +
             </row>

     

       82
       +
             <row>

     

       83
       +
               <entry><literal>"foo" == "f" + "oo"</literal></entry>

     

       84
       +
               <entry>Equality test (evaluates to <literal>true</literal>)</entry>

     

       85
       +
             </row>

     

       86
       +
             <row>

     

       87
       +
               <entry><literal>"foo" != "bar"</literal></entry>

     

       88
       +
               <entry>Inequality test (evaluates to <literal>true</literal>)</entry>

     

       89
       +
             </row>

     

       90
       +
             <row>

     

       91
       +
               <entry><literal>!true</literal></entry>

     

       92
       +
               <entry>Boolean negation</entry>

     

       93
       +
             </row>

     

       94
       +
             <row>

     

       95
       +
               <entry><literal>{ x = 1; y = 2; }.x</literal></entry>

     

       96
       +
               <entry>Attribute selection (evaluates to <literal>1</literal>)</entry>

     

       97
       +
             </row>

     

       98
       +
             <row>

     

       99
       +
               <entry><literal>{ x = 1; y = 2; }.z or 3</literal></entry>

     

       100
       +
               <entry>Attribute selection with default (evaluates to <literal>3</literal>)</entry>

     

       101
       +
             </row>

     

       102
       +
             <row>

     

       103
       +
               <entry><literal>{ x = 1; y = 2; } // { z = 3; }</literal></entry>

     

       104
       +
               <entry>Merge two sets (attributes in the right-hand set taking precedence)</entry>

     

       105
       +
             </row>

     

       106
       +
       

     

       107
       +
             <row>

     

       108
       +
               <entry namest="c1" nameend="c2"><emphasis>Control structures</emphasis></entry>

     

       109
       +
             </row>

     

       110
       +
             <row>

     

       111
       +
               <entry><literal>if 1 + 1 == 2 then "yes!" else "no!"</literal></entry>

     

       112
       +
               <entry>Conditional expression</entry>

     

       113
       +
             </row>

     

       114
       +
             <row>

     

       115
       +
               <entry><literal>assert 1 + 1 == 2; "yes!"</literal></entry>

     

       116
       +
               <entry>Assertion check (evaluates to <literal>"yes!"</literal>)</entry>

     

       117
       +
             </row>

     

       118
       +
             <row>

     

       119
       +
               <entry><literal>let x = "foo"; y = "bar"; in x + y</literal></entry>

     

       120
       +
               <entry>Variable definition</entry>

     

       121
       +
             </row>

     

       122
       +
             <row>

     

       123
       +
               <entry><literal>with pkgs.lib; head [ 1 2 3 ]</literal></entry>

     

       124
       +
               <entry>Add all attributes from the given set to the scope

     

       125
       +
               (evaluates to <literal>1</literal>)</entry>

     

       126
       +
             </row>

     

       127
       +
       

     

       128
       +
             <row>

     

       129
       +
               <entry namest="c1" nameend="c2"><emphasis>Functions (lambdas)</emphasis></entry>

     

       130
       +
             </row>

     

       131
       +
             <row>

     

       132
       +
               <entry><literal>x: x + 1</literal></entry>

     

       133
       +
               <entry>A function that expects an integer and returns it increased by 1</entry>

     

       134
       +
             </row>

     

       135
       +
             <row>

     

       136
       +
               <entry><literal>(x: x + 1) 100</literal></entry>

     

       137
       +
               <entry>A function call (evaluates to 101)</entry>

     

       138
       +
             </row>

     

       139
       +
             <row>

     

       140
       +
               <entry><literal>let inc = x: x + 1; in inc (inc (inc 100))</literal></entry>

     

       141
       +
               <entry>A function bound to a variable and subsequently called by name (evaluates to 103)</entry>

     

       142
       +
             </row>

     

       143
       +
             <row>

     

       144
       +
               <entry><literal>{ x, y }: x + y</literal></entry>

     

       145
       +
               <entry>A function that expects a set with required attributes

     

       146
       +
               <literal>x</literal> and <literal>y</literal> and concatenates

     

       147
       +
               them</entry>

     

       148
       +
             </row>

     

       149
       +
             <row>

     

       150
       +
               <entry><literal>{ x, y ? "bar" }: x + y</literal></entry>

     

       151
       +
               <entry>A function that expects a set with required attribute

     

       152
       +
               <literal>x</literal> and optional <literal>y</literal>, using

     

       153
       +
               <literal>"bar"</literal> as default value for

     

       154
       +
               <literal>y</literal></entry>

     

       155
       +
             </row>

     

       156
       +
             <row>

     

       157
       +
               <entry><literal>{ x, y, ... }: x + y</literal></entry>

     

       158
       +
               <entry>A function that expects a set with required attributes

     

       159
       +
               <literal>x</literal> and <literal>y</literal> and ignores any

     

       160
       +
               other attributes</entry>

     

       161
       +
             </row>

     

       162
       +
             <row>

     

       163
       +
               <entry><literal>{ x, y } @ args: x + y</literal></entry>

     

       164
       +
               <entry>A function that expects a set with required attributes

     

       165
       +
               <literal>x</literal> and <literal>y</literal>, and binds the

     

       166
       +
               whole set to <literal>args</literal></entry>

     

       167
       +
             </row>

     

       168
       +
       

     

       169
       +
             <row>

     

       170
       +
               <entry namest="c1" nameend="c2"><emphasis>Built-in functions</emphasis></entry>

     

       171
       +
             </row>

     

       172
       +
             <row>

     

       173
       +
               <entry><literal>import ./foo.nix</literal></entry>

     

       174
       +
               <entry>Load and return Nix expression in given file</entry>

     

       175
       +
             </row>

     

       176
       +
             <row>

     

       177
       +
               <entry><literal>map (x: x + x) [ 1 2 3 ]</literal></entry>

     

       178
       +
               <entry>Apply a function to every element of a list (evaluates to <literal>[ 2 4 6 ]</literal>)</entry>

     

       179
       +
             </row>

     

       180
       +
             <!--

     

       181
       +
             <row>

     

       182
       +
               <entry><literal>throw "Urgh"</literal></entry>

     

       183
       +
               <entry>Raise an error condition</entry>

     

       184
       +
             </row>

     

       185
       +
             -->

     

       186
       +
       

     

       187
       +
           </tbody>

     

       188
       +
         </tgroup>

     

       189
       +
       </informaltable>

     

       190
       +
       

     

       191
       +
       </section>

+95

nixos/doc/manual/configuration/user-mgmt.xml

···

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

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-user-management">

     

       6
       +
       

     

       7
       +
       <title>User Management</title>

     

       8
       +
       

     

       9
       +
       <para>NixOS supports both declarative and imperative styles of user

     

       10
       +
       management.  In the declarative style, users are specified in

     

       11
       +
       <filename>configuration.nix</filename>.  For instance, the following

     

       12
       +
       states that a user account named <literal>alice</literal> shall exist:

     

       13
       +
       

     

       14
       +
       <programlisting>

     

       15
       +
       users.extraUsers.alice =

     

       16
       +
         { createHome = true;

     

       17
       +
           home = "/home/alice";

     

       18
       +
           description = "Alice Foobar";

     

       19
       +
           extraGroups = [ "wheel" "networkmanager" ];

     

       20
       +
           useDefaultShell = true;

     

       21
       +
           openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];

     

       22
       +
         };

     

       23
       +
       </programlisting>

     

       24
       +
       

     

       25
       +
       Note that <literal>alice</literal> is a member of the

     

       26
       +
       <literal>wheel</literal> and <literal>networkmanager</literal> groups,

     

       27
       +
       which allows her to use <command>sudo</command> to execute commands as

     

       28
       +
       <literal>root</literal> and to configure the network, respectively.

     

       29
       +
       Also note the SSH public key that allows remote logins with the

     

       30
       +
       corresponding private key. Users created in this way do not have a

     

       31
       +
       password by default, so they cannot log in via mechanisms that require

     

       32
       +
       a password. However, you can use the <command>passwd</command> program

     

       33
       +
       to set a password, which is retained across invocations of

     

       34
       +
       <command>nixos-rebuild</command>.</para>

     

       35
       +
       

     

       36
       +
       <para>If you set users.mutableUsers to false, then the contents of /etc/passwd

     

       37
       +
       and /etc/group will be congruent to your NixOS configuration. For instance,

     

       38
       +
       if you remove a user from users.extraUsers and run nixos-rebuild, the user

     

       39
       +
       account will cease to exist. Also, imperative commands for managing users

     

       40
       +
       and groups, such as useradd, are no longer available.</para>

     

       41
       +
       

     

       42
       +
       <para>A user ID (uid) is assigned automatically.  You can also specify

     

       43
       +
       a uid manually by adding

     

       44
       +
       

     

       45
       +
       <programlisting>

     

       46
       +
           uid = 1000;

     

       47
       +
       </programlisting>

     

       48
       +
       

     

       49
       +
       to the user specification.</para>

     

       50
       +
       

     

       51
       +
       <para>Groups can be specified similarly.  The following states that a

     

       52
       +
       group named <literal>students</literal> shall exist:

     

       53
       +
       

     

       54
       +
       <programlisting>

     

       55
       +
       users.extraGroups.students.gid = 1000;

     

       56
       +
       </programlisting>

     

       57
       +
       

     

       58
       +
       As with users, the group ID (gid) is optional and will be assigned

     

       59
       +
       automatically if it’s missing.</para>

     

       60
       +
       

     

       61
       +
       <warning><para>Currently declarative user management is not perfect:

     

       62
       +
       <command>nixos-rebuild</command> does not know how to realise certain

     

       63
       +
       configuration changes.  This includes removing a user or group, and

     

       64
       +
       removing group membership from a user.</para></warning>

     

       65
       +
       

     

       66
       +
       <para>In the imperative style, users and groups are managed by

     

       67
       +
       commands such as <command>useradd</command>,

     

       68
       +
       <command>groupmod</command> and so on.  For instance, to create a user

     

       69
       +
       account named <literal>alice</literal>:

     

       70
       +
       

     

       71
       +
       <screen>

     

       72
       +
       $ useradd -m alice</screen>

     

       73
       +
       

     

       74
       +
       The flag <option>-m</option> causes the creation of a home directory

     

       75
       +
       for the new user, which is generally what you want.  The user does not

     

       76
       +
       have an initial password and therefore cannot log in.  A password can

     

       77
       +
       be set using the <command>passwd</command> utility:

     

       78
       +
       

     

       79
       +
       <screen>

     

       80
       +
       $ passwd alice

     

       81
       +
       Enter new UNIX password: ***

     

       82
       +
       Retype new UNIX password: ***

     

       83
       +
       </screen>

     

       84
       +
       

     

       85
       +
       A user can be deleted using <command>userdel</command>:

     

       86
       +
       

     

       87
       +
       <screen>

     

       88
       +
       $ userdel -r alice</screen>

     

       89
       +
       

     

       90
       +
       The flag <option>-r</option> deletes the user’s home directory.

     

       91
       +
       Accounts can be modified using <command>usermod</command>.  Unix

     

       92
       +
       groups can be managed using <command>groupadd</command>,

     

       93
       +
       <command>groupmod</command> and <command>groupdel</command>.</para>

     

       94
       +
       

     

       95
       +
       </chapter>

+41

nixos/doc/manual/configuration/wireless.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-wireless">

     

       6
       +
       

     

       7
       +
       <title>Wireless Networks</title>

     

       8
       +
       

     

       9
       +
       <para>For a desktop installation using NetworkManager (e.g., GNOME),

     

       10
       +
       you just have to make sure the user is in the

     

       11
       +
       <code>networkmanager</code> group and you can skip the rest of this

     

       12
       +
       section on wireless networks.</para>

     

       13
       +
       

     

       14
       +
       <para>

     

       15
       +
       NixOS will start wpa_supplicant for you if you enable this setting:

     

       16
       +
       

     

       17
       +
       <programlisting>

     

       18
       +
       networking.wireless.enable = true;

     

       19
       +
       </programlisting>

     

       20
       +
       

     

       21
       +
       NixOS currently does not generate wpa_supplicant's

     

       22
       +
       configuration file, <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file

     

       23
       +
       yourself to define wireless networks, WPA keys and so on (see

     

       24
       +
       wpa_supplicant.conf(5)).

     

       25
       +
       </para>

     

       26
       +
       

     

       27
       +
       <para>

     

       28
       +
       If you are using WPA2 the <command>wpa_passphrase</command> tool might be useful

     

       29
       +
       to generate the <literal>wpa_supplicant.conf</literal>.

     

       30
       +
       

     

       31
       +
       <screen>

     

       32
       +
       $ wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen>

     

       33
       +
       

     

       34
       +
       After you have edited the <literal>wpa_supplicant.conf</literal>,

     

       35
       +
       you need to restart the wpa_supplicant service.

     

       36
       +
       

     

       37
       +
       <screen>

     

       38
       +
       $ systemctl restart wpa_supplicant.service</screen>

     

       39
       +
       </para>

     

       40
       +
       

     

       41
       +
       </section>

+94

nixos/doc/manual/configuration/x-windows.xml

···

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

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-x11">

     

       6
       +
       

     

       7
       +
       <title>X Window System</title>

     

       8
       +
           

     

       9
       +
       <para>The X Window System (X11) provides the basis of NixOS’ graphical

     

       10
       +
       user interface.  It can be enabled as follows:

     

       11
       +
       <programlisting>

     

       12
       +
       services.xserver.enable = true;

     

       13
       +
       </programlisting>

     

       14
       +
       The X server will automatically detect and use the appropriate video

     

       15
       +
       driver from a set of X.org drivers (such as <literal>vesa</literal>

     

       16
       +
       and <literal>intel</literal>).  You can also specify a driver

     

       17
       +
       manually, e.g.

     

       18
       +
       <programlisting>

     

       19
       +
       services.xserver.videoDrivers = [ "r128" ];

     

       20
       +
       </programlisting>

     

       21
       +
       to enable X.org’s <literal>xf86-video-r128</literal> driver.</para>

     

       22
       +
       

     

       23
       +
       <para>You also need to enable at least one desktop or window manager.

     

       24
       +
       Otherwise, you can only log into a plain undecorated

     

       25
       +
       <command>xterm</command> window.  Thus you should pick one or more of

     

       26
       +
       the following lines:

     

       27
       +
       <programlisting>

     

       28
       +
       services.xserver.desktopManager.kde4.enable = true;

     

       29
       +
       services.xserver.desktopManager.xfce.enable = true;

     

       30
       +
       services.xserver.windowManager.xmonad.enable = true;

     

       31
       +
       services.xserver.windowManager.twm.enable = true;

     

       32
       +
       services.xserver.windowManager.icewm.enable = true;

     

       33
       +
       </programlisting>

     

       34
       +
       </para>

     

       35
       +
       

     

       36
       +
       <para>NixOS’s default <emphasis>display manager</emphasis> (the

     

       37
       +
       program that provides a graphical login prompt and manages the X

     

       38
       +
       server) is SLiM.  You can select KDE’s <command>kdm</command> instead:

     

       39
       +
       <programlisting>

     

       40
       +
       services.xserver.displayManager.kdm.enable = true;

     

       41
       +
       </programlisting>

     

       42
       +
       </para>

     

       43
       +
       

     

       44
       +
       <para>The X server is started automatically at boot time.  If you

     

       45
       +
       don’t want this to happen, you can set:

     

       46
       +
       <programlisting>

     

       47
       +
       services.xserver.autorun = false;

     

       48
       +
       </programlisting>

     

       49
       +
       The X server can then be started manually:

     

       50
       +
       <screen>

     

       51
       +
       $ systemctl start display-manager.service

     

       52
       +
       </screen>

     

       53
       +
       </para>

     

       54
       +
       

     

       55
       +
       

     

       56
       +
       <simplesect><title>NVIDIA Graphics Cards</title>

     

       57
       +
       

     

       58
       +
       <para>NVIDIA provides a proprietary driver for its graphics cards that

     

       59
       +
       has better 3D performance than the X.org drivers.  It is not enabled

     

       60
       +
       by default because it’s not free software.  You can enable it as follows:

     

       61
       +
       <programlisting>

     

       62
       +
       services.xserver.videoDrivers = [ "nvidia" ];

     

       63
       +
       </programlisting>

     

       64
       +
       You may need to reboot after enabling this driver to prevent a clash

     

       65
       +
       with other kernel modules.</para>

     

       66
       +
       

     

       67
       +
       <para>On 64-bit systems, if you want full acceleration for 32-bit

     

       68
       +
       programs such as Wine, you should also set the following:

     

       69
       +
       <programlisting>

     

       70
       +
       services.xserver.driSupport32Bit = true;

     

       71
       +
       </programlisting>

     

       72
       +
       </para>

     

       73
       +
       

     

       74
       +
       </simplesect>

     

       75
       +
       

     

       76
       +
       

     

       77
       +
       <simplesect><title>Touchpads</title>

     

       78
       +
       

     

       79
       +
       <para>Support for Synaptics touchpads (found in many laptops such as

     

       80
       +
       the Dell Latitude series) can be enabled as follows:

     

       81
       +
       <programlisting>

     

       82
       +
       services.xserver.synaptics.enable = true;

     

       83
       +
       </programlisting>

     

       84
       +
       The driver has many options (see <xref linkend="ch-options"/>).  For

     

       85
       +
       instance, the following enables two-finger scrolling:

     

       86
       +
       <programlisting>

     

       87
       +
       services.xserver.synaptics.twoFingerScroll = true;

     

       88
       +
       </programlisting>

     

       89
       +
       </para>

     

       90
       +
       

     

       91
       +
       </simplesect>

     

       92
       +
       

     

       93
       +
       

     

       94
       +
       </chapter>

-242

nixos/doc/manual/containers.xml

···

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

     

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

     

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

     

       4
       -
       

     

       5
       -
       <title>Containers</title>

     

       6
       -
       

     

       7
       -
       <para>NixOS allows you to easily run other NixOS instances as

     

       8
       -
       <emphasis>containers</emphasis>. Containers are a light-weight

     

       9
       -
       approach to virtualisation that runs software in the container at the

     

       10
       -
       same speed as in the host system. NixOS containers share the Nix store

     

       11
       -
       of the host, making container creation very efficient.</para>

     

       12
       -
       

     

       13
       -
       <warning><para>Currently, NixOS containers are not perfectly isolated

     

       14
       -
       from the host system. This means that a user with root access to the

     

       15
       -
       container can do things that affect the host. So you should not give

     

       16
       -
       container root access to untrusted users.</para></warning>

     

       17
       -
       

     

       18
       -
       <para>NixOS containers can be created in two ways: imperatively, using

     

       19
       -
       the command <command>nixos-container</command>, and declaratively, by

     

       20
       -
       specifying them in your <filename>configuration.nix</filename>. The

     

       21
       -
       declarative approach implies that containers get upgraded along with

     

       22
       -
       your host system when you run <command>nixos-rebuild</command>, which

     

       23
       -
       is often not what you want. By contrast, in the imperative approach,

     

       24
       -
       containers are configured and updated independently from the host

     

       25
       -
       system.</para>

     

       26
       -
       

     

       27
       -
       

     

       28
       -
       <section><title>Imperative container management</title>

     

       29
       -
       

     

       30
       -
       <para>We’ll cover imperative container management using

     

       31
       -
       <command>nixos-container</command> first. You create a container with

     

       32
       -
       identifier <literal>foo</literal> as follows:

     

       33
       -
       

     

       34
       -
       <screen>

     

       35
       -
       $ nixos-container create foo

     

       36
       -
       </screen>

     

       37
       -
       

     

       38
       -
       This creates the container’s root directory in

     

       39
       -
       <filename>/var/lib/containers/foo</filename> and a small configuration

     

       40
       -
       file in <filename>/etc/containers/foo.conf</filename>. It also builds

     

       41
       -
       the container’s initial system configuration and stores it in

     

       42
       -
       <filename>/nix/var/nix/profiles/per-container/foo/system</filename>. You

     

       43
       -
       can modify the initial configuration of the container on the command

     

       44
       -
       line. For instance, to create a container that has

     

       45
       -
       <command>sshd</command> running, with the given public key for

     

       46
       -
       <literal>root</literal>:

     

       47
       -
       

     

       48
       -
       <screen>

     

       49
       -
       $ nixos-container create foo --config 'services.openssh.enable = true; \

     

       50
       -
         users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];'

     

       51
       -
       </screen>

     

       52
       -
       

     

       53
       -
       </para>

     

       54
       -
       

     

       55
       -
       <para>Creating a container does not start it. To start the container,

     

       56
       -
       run:

     

       57
       -
       

     

       58
       -
       <screen>

     

       59
       -
       $ nixos-container start foo

     

       60
       -
       </screen>

     

       61
       -
       

     

       62
       -
       This command will return as soon as the container has booted and has

     

       63
       -
       reached <literal>multi-user.target</literal>. On the host, the

     

       64
       -
       container runs within a systemd unit called

     

       65
       -
       <literal>container@<replaceable>container-name</replaceable>.service</literal>.

     

       66
       -
       Thus, if something went wrong, you can get status info using

     

       67
       -
       <command>systemctl</command>:

     

       68
       -
       

     

       69
       -
       <screen>

     

       70
       -
       $ systemctl status container@foo

     

       71
       -
       </screen>

     

       72
       -
       

     

       73
       -
       </para>

     

       74
       -
       

     

       75
       -
       <para>If the container has started succesfully, you can log in as

     

       76
       -
       root using the <command>root-login</command> operation:

     

       77
       -
       

     

       78
       -
       <screen>

     

       79
       -
       $ nixos-container root-login foo

     

       80
       -
       [root@foo:~]#

     

       81
       -
       </screen>

     

       82
       -
       

     

       83
       -
       Note that only root on the host can do this (since there is no

     

       84
       -
       authentication).  You can also get a regular login prompt using the

     

       85
       -
       <command>login</command> operation, which is available to all users on

     

       86
       -
       the host:

     

       87
       -
       

     

       88
       -
       <screen>

     

       89
       -
       $ nixos-container login foo

     

       90
       -
       foo login: alice

     

       91
       -
       Password: ***

     

       92
       -
       </screen>

     

       93
       -
       

     

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

     

       95
       -
       commands in the container:

     

       96
       -
       

     

       97
       -
       <screen>

     

       98
       -
       $ nixos-container run foo -- uname -a

     

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

     

       100
       -
       </screen>

     

       101
       -
       

     

       102
       -
       </para>

     

       103
       -
       

     

       104
       -
       <para>There are several ways to change the configuration of the

     

       105
       -
       container. First, on the host, you can edit

     

       106
       -
       <literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>,

     

       107
       -
       and run

     

       108
       -
       

     

       109
       -
       <screen>

     

       110
       -
       $ nixos-container update foo

     

       111
       -
       </screen>

     

       112
       -
       

     

       113
       -
       This will build and activate the new configuration. You can also

     

       114
       -
       specify a new configuration on the command line:

     

       115
       -
       

     

       116
       -
       <screen>

     

       117
       -
       $ nixos-container update foo --config 'services.httpd.enable = true; \

     

       118
       -
         services.httpd.adminAddr = "foo@example.org";'

     

       119
       -
       

     

       120
       -
       $ curl http://$(nixos-container show-ip foo)/

     

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

     

       122
       -
       </screen>

     

       123
       -
       

     

       124
       -
       However, note that this will overwrite the container’s

     

       125
       -
       <filename>/etc/nixos/configuration.nix</filename>.</para>

     

       126
       -
       

     

       127
       -
       <para>Alternatively, you can change the configuration from within the

     

       128
       -
       container itself by running <command>nixos-rebuild switch</command>

     

       129
       -
       inside the container. Note that the container by default does not have

     

       130
       -
       a copy of the NixOS channel, so you should run <command>nix-channel

     

       131
       -
       --update</command> first.</para>

     

       132
       -
       

     

       133
       -
       <para>Containers can be stopped and started using

     

       134
       -
       <literal>nixos-container stop</literal> and <literal>nixos-container

     

       135
       -
       start</literal>, respectively, or by using

     

       136
       -
       <command>systemctl</command> on the container’s service unit. To

     

       137
       -
       destroy a container, including its file system, do

     

       138
       -
       

     

       139
       -
       <screen>

     

       140
       -
       $ nixos-container destroy foo

     

       141
       -
       </screen>

     

       142
       -
       

     

       143
       -
       </para>

     

       144
       -
       

     

       145
       -
       </section>

     

       146
       -
       

     

       147
       -
       

     

       148
       -
       <section><title>Declarative container specification</title>

     

       149
       -
       

     

       150
       -
       <para>You can also specify containers and their configuration in the

     

       151
       -
       host’s <filename>configuration.nix</filename>.  For example, the

     

       152
       -
       following specifies that there shall be a container named

     

       153
       -
       <literal>database</literal> running PostgreSQL:

     

       154
       -
       

     

       155
       -
       <programlisting>

     

       156
       -
       containers.database =

     

       157
       -
         { config =

     

       158
       -
             { config, pkgs, ... }:

     

       159
       -
             { services.postgresql.enable = true;

     

       160
       -
               services.postgresql.package = pkgs.postgresql92;

     

       161
       -
             };

     

       162
       -
         };

     

       163
       -
       </programlisting>

     

       164
       -
       

     

       165
       -
       If you run <literal>nixos-rebuild switch</literal>, the container will

     

       166
       -
       be built and started. If the container was already running, it will be

     

       167
       -
       updated in place, without rebooting.</para>

     

       168
       -
       

     

       169
       -
       <para>By default, declarative containers share the network namespace

     

       170
       -
       of the host, meaning that they can listen on (privileged)

     

       171
       -
       ports. However, they cannot change the network configuration. You can

     

       172
       -
       give a container its own network as follows:

     

       173
       -
       

     

       174
       -
       <programlisting>

     

       175
       -
       containers.database =

     

       176
       -
         { privateNetwork = true;

     

       177
       -
           hostAddress = "192.168.100.10";

     

       178
       -
           localAddress = "192.168.100.11";

     

       179
       -
         };

     

       180
       -
       </programlisting>

     

       181
       -
       

     

       182
       -
       This gives the container a private virtual Ethernet interface with IP

     

       183
       -
       address <literal>192.168.100.11</literal>, which is hooked up to a

     

       184
       -
       virtual Ethernet interface on the host with IP address

     

       185
       -
       <literal>192.168.100.10</literal>.  (See the next section for details

     

       186
       -
       on container networking.)</para>

     

       187
       -
       

     

       188
       -
       <para>To disable the container, just remove it from

     

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

     

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

     

       191
       -
       the container in <literal>/var/lib/containers</literal>.</para>

     

       192
       -
       

     

       193
       -
       </section>

     

       194
       -
       

     

       195
       -
       

     

       196
       -
       <section><title>Networking</title>

     

       197
       -
       

     

       198
       -
       <para>When you create a container using <literal>nixos-container

     

       199
       -
       create</literal>, it gets it own private IPv4 address in the range

     

       200
       -
       <literal>10.233.0.0/16</literal>. You can get the container’s IPv4

     

       201
       -
       address as follows:

     

       202
       -
       

     

       203
       -
       <screen>

     

       204
       -
       $ nixos-container show-ip foo

     

       205
       -
       10.233.4.2

     

       206
       -
       

     

       207
       -
       $ ping -c1 10.233.4.2

     

       208
       -
       64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms

     

       209
       -
       </screen>

     

       210
       -
       

     

       211
       -
       </para>

     

       212
       -
       

     

       213
       -
       <para>Networking is implemented using a pair of virtual Ethernet

     

       214
       -
       devices. The network interface in the container is called

     

       215
       -
       <literal>eth0</literal>, while the matching interface in the host is

     

       216
       -
       called <literal>ve-<replaceable>container-name</replaceable></literal>

     

       217
       -
       (e.g., <literal>ve-foo</literal>).  The container has its own network

     

       218
       -
       namespace and the <literal>CAP_NET_ADMIN</literal> capability, so it

     

       219
       -
       can perform arbitrary network configuration such as setting up

     

       220
       -
       firewall rules, without affecting or having access to the host’s

     

       221
       -
       network.</para>

     

       222
       -
       

     

       223
       -
       <para>By default, containers cannot talk to the outside network. If

     

       224
       -
       you want that, you should set up Network Address Translation (NAT)

     

       225
       -
       rules on the host to rewrite container traffic to use your external

     

       226
       -
       IP address. This can be accomplished using the following configuration

     

       227
       -
       on the host:

     

       228
       -
       

     

       229
       -
       <programlisting>

     

       230
       -
       networking.nat.enable = true;

     

       231
       -
       networking.nat.internalInterfaces = ["ve-+"];

     

       232
       -
       networking.nat.externalInterface = "eth0";

     

       233
       -
       </programlisting>

     

       234
       -
       where <literal>eth0</literal> should be replaced with the desired

     

       235
       -
       external interface. Note that <literal>ve-+</literal> is a wildcard

     

       236
       -
       that matches all container interfaces.</para>

     

       237
       -
       

     

       238
       -
       </section>

     

       239
       -
       

     

       240
       -
       

     

       241
       -
       </chapter>

     

       242
       -

-1119

nixos/doc/manual/development.xml

···

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

     

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

     

       3
       -
                xml:id="ch-development">

     

       4
       -
       

     

       5
       -
       <title>Development</title>

     

       6
       -
       

     

       7
       -
       <para>This chapter describes how you can modify and extend

     

       8
       -
       NixOS.</para>

     

       9
       -
       

     

       10
       -
       

     

       11
       -
       <!--===============================================================-->

     

       12
       -
       

     

       13
       -
       <section xml:id="sec-getting-sources">

     

       14
       -
       

     

       15
       -
       <title>Getting the sources</title>

     

       16
       -
       

     

       17
       -
       <para>By default, NixOS’s <command>nixos-rebuild</command> command

     

       18
       -
       uses the NixOS and Nixpkgs sources provided by the

     

       19
       -
       <literal>nixos-unstable</literal> channel (kept in

     

       20
       -
       <filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>).

     

       21
       -
       To modify NixOS, however, you should check out the latest sources from

     

       22
       -
       Git.  This is done using the following command:

     

       23
       -
       

     

       24
       -
       <screen>

     

       25
       -
       $ nixos-checkout <replaceable>/my/sources</replaceable>

     

       26
       -
       </screen>

     

       27
       -
       

     

       28
       -
       or

     

       29
       -
       

     

       30
       -
       <screen>

     

       31
       -
       $ mkdir -p <replaceable>/my/sources</replaceable>

     

       32
       -
       $ cd <replaceable>/my/sources</replaceable>

     

       33
       -
       $ nix-env -i git

     

       34
       -
       $ git clone git://github.com/NixOS/nixpkgs.git

     

       35
       -
       </screen>

     

       36
       -
       

     

       37
       -
       This will check out the latest NixOS sources to

     

       38
       -
       <filename><replaceable>/my/sources</replaceable>/nixpkgs/nixos</filename>

     

       39
       -
       and the Nixpkgs sources to

     

       40
       -
       <filename><replaceable>/my/sources</replaceable>/nixpkgs</filename>.

     

       41
       -
       (The NixOS source tree lives in a subdirectory of the Nixpkgs

     

       42
       -
       repository.)</para>

     

       43
       -
       

     

       44
       -
       <para>It’s often inconvenient to develop directly on the master

     

       45
       -
       branch, since if somebody has just committed (say) a change to GCC,

     

       46
       -
       then the binary cache may not have caught up yet and you’ll have to

     

       47
       -
       rebuild everything from source. So you may want to create a local

     

       48
       -
       branch based on your current NixOS version:

     

       49
       -
       

     

       50
       -
       <screen>

     

       51
       -
       $ nixos-version

     

       52
       -
       14.04.273.ea1952b (Baboon)

     

       53
       -
       

     

       54
       -
       $ git checkout -b local ea1952b

     

       55
       -
       </screen>

     

       56
       -
       

     

       57
       -
       Or, to base your local branch on the latest version available in the

     

       58
       -
       NixOS channel:

     

       59
       -
       

     

       60
       -
       <screen>

     

       61
       -
       $ curl -sI http://nixos.org/channels/nixos-unstable/ | grep Location

     

       62
       -
       Location: http://releases.nixos.org/nixos/unstable/nixos-14.10pre43986.acaf4a6/

     

       63
       -
       

     

       64
       -
       $ git checkout -b local acaf4a6

     

       65
       -
       </screen>

     

       66
       -
       

     

       67
       -
       You can then use <command>git rebase</command> to sync your local

     

       68
       -
       branch with the upstream branch, and use <command>git

     

       69
       -
       cherry-pick</command> to copy commits from your local branch to the

     

       70
       -
       upstream branch.</para>

     

       71
       -
       

     

       72
       -
       <para>If you want to rebuild your system using your (modified)

     

       73
       -
       sources, you need to tell <command>nixos-rebuild</command> about them

     

       74
       -
       using the <option>-I</option> flag:

     

       75
       -
       

     

       76
       -
       <screen>

     

       77
       -
       $ nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs

     

       78
       -
       </screen>

     

       79
       -
       

     

       80
       -
       </para>

     

       81
       -
       

     

       82
       -
       <para>If you want <command>nix-env</command> to use the expressions in

     

       83
       -
       <replaceable>/my/sources</replaceable>, use <command>nix-env -f

     

       84
       -
       <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change

     

       85
       -
       the default by adding a symlink in

     

       86
       -
       <filename>~/.nix-defexpr</filename>:

     

       87
       -
       

     

       88
       -
       <screen>

     

       89
       -
       $ ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs

     

       90
       -
       </screen>

     

       91
       -
       

     

       92
       -
       You may want to delete the symlink

     

       93
       -
       <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s

     

       94
       -
       NixOS channel from clashing with your own tree.</para>

     

       95
       -
       

     

       96
       -
       <!-- FIXME: not sure what this means.

     

       97
       -
       <para>You should not pass the base directory

     

       98
       -
       <filename><replaceable>/my/sources</replaceable></filename>

     

       99
       -
       to <command>nix-env</command>, as it will break after interpreting expressions

     

       100
       -
       in <filename>nixos/</filename> as packages.</para>

     

       101
       -
       -->

     

       102
       -
       

     

       103
       -
       </section>

     

       104
       -
       

     

       105
       -
       

     

       106
       -
       <!--===============================================================-->

     

       107
       -
       

     

       108
       -
       <section xml:id="sec-writing-modules">

     

       109
       -
       

     

       110
       -
       <title>Writing NixOS modules</title>

     

       111
       -
       

     

       112
       -
       <para>NixOS has a modular system for declarative configuration.  This

     

       113
       -
       system combines multiple <emphasis>modules</emphasis> to produce the

     

       114
       -
       full system configuration.  One of the modules that constitute the

     

       115
       -
       configuration is <filename>/etc/nixos/configuration.nix</filename>.

     

       116
       -
       Most of the others live in the <link

     

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

     

       118
       -
       subdirectory of the Nixpkgs tree.</para>

     

       119
       -
       

     

       120
       -
       <para>Each NixOS module is a file that handles one logical aspect of

     

       121
       -
       the configuration, such as a specific kind of hardware, a service, or

     

       122
       -
       network settings.  A module configuration does not have to handle

     

       123
       -
       everything from scratch; it can use the functionality provided by

     

       124
       -
       other modules for its implementation.  Thus a module can

     

       125
       -
       <emphasis>declare</emphasis> options that can be used by other

     

       126
       -
       modules, and conversely can <emphasis>define</emphasis> options

     

       127
       -
       provided by other modules in its own implementation.  For example, the

     

       128
       -
       module <link

     

       129
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link>

     

       130
       -
       declares the option <option>security.pam.services</option> that allows

     

       131
       -
       other modules (e.g. <link

     

       132
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>)

     

       133
       -
       to define PAM services; and it defines the option

     

       134
       -
       <option>environment.etc</option> (declared by <link

     

       135
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>)

     

       136
       -
       to cause files to be created in

     

       137
       -
       <filename>/etc/pam.d</filename>.</para>

     

       138
       -
       

     

       139
       -
       <para xml:id="para-module-syn">In <xref

     

       140
       -
       linkend="sec-configuration-syntax"/>, we saw the following structure

     

       141
       -
       of NixOS modules:

     

       142
       -
       

     

       143
       -
       <programlisting>

     

       144
       -
       { config, pkgs, ... }:

     

       145
       -
       

     

       146
       -
       { <replaceable>option definitions</replaceable>

     

       147
       -
       }

     

       148
       -
       </programlisting>

     

       149
       -
       

     

       150
       -
       This is actually an <emphasis>abbreviated</emphasis> form of module

     

       151
       -
       that only defines options, but does not declare any.  The structure of

     

       152
       -
       full NixOS modules is shown in <xref linkend='ex-module-syntax' />.</para>

     

       153
       -
       

     

       154
       -
       <example xml:id='ex-module-syntax'><title>Structure of NixOS modules</title>

     

       155
       -
       <programlisting>

     

       156
       -
       { config, pkgs, ... }: <co xml:id='module-syntax-1' />

     

       157
       -
       

     

       158
       -
       {

     

       159
       -
         imports =

     

       160
       -
           [ <replaceable>paths of other modules</replaceable> <co xml:id='module-syntax-2' />

     

       161
       -
           ];

     

       162
       -
       

     

       163
       -
         options = {

     

       164
       -
           <replaceable>option declarations</replaceable> <co xml:id='module-syntax-3' />

     

       165
       -
         };

     

       166
       -
       

     

       167
       -
         config = {

     

       168
       -
           <replaceable>option definitions</replaceable> <co xml:id='module-syntax-4' />

     

       169
       -
         };

     

       170
       -
       }</programlisting>

     

       171
       -
       </example>

     

       172
       -
       

     

       173
       -
       <para>The meaning of each part is as follows.

     

       174
       -
       

     

       175
       -
       <calloutlist>

     

       176
       -
         <callout arearefs='module-syntax-1'>

     

       177
       -
           <para>This line makes the current Nix expression a function.  The

     

       178
       -
           variable <varname>pkgs</varname> contains Nixpkgs, while

     

       179
       -
           <varname>config</varname> contains the full system configuration.

     

       180
       -
           This line can be omitted if there is no reference to

     

       181
       -
           <varname>pkgs</varname> and <varname>config</varname> inside the

     

       182
       -
           module.</para>

     

       183
       -
         </callout>

     

       184
       -
       

     

       185
       -
         <callout arearefs='module-syntax-2'>

     

       186
       -
           <para>This list enumerates the paths to other NixOS modules that

     

       187
       -
           should be included in the evaluation of the system configuration.

     

       188
       -
           A default set of modules is defined in the file

     

       189
       -
           <filename>modules/module-list.nix</filename>.  These don't need to

     

       190
       -
           be added in the import list.</para>

     

       191
       -
         </callout>

     

       192
       -
       

     

       193
       -
         <callout arearefs='module-syntax-3'>

     

       194
       -
           <para>The attribute <varname>options</varname> is a nested set of

     

       195
       -
           <emphasis>option declarations</emphasis> (described below).</para>

     

       196
       -
         </callout>

     

       197
       -
       

     

       198
       -
         <callout arearefs='module-syntax-4'>

     

       199
       -
           <para>The attribute <varname>config</varname> is a nested set of

     

       200
       -
           <emphasis>option definitions</emphasis> (also described

     

       201
       -
           below).</para>

     

       202
       -
         </callout>

     

       203
       -
       </calloutlist>

     

       204
       -
       

     

       205
       -
       </para>

     

       206
       -
       

     

       207
       -
       <para><xref linkend='locate-example' /> shows a module that handles

     

       208
       -
       the regular update of the “locate” database, an index of all files in

     

       209
       -
       the file system.  This module declares two options that can be defined

     

       210
       -
       by other modules (typically the user’s

     

       211
       -
       <filename>configuration.nix</filename>):

     

       212
       -
       <option>services.locate.enable</option> (whether the database should

     

       213
       -
       be updated) and <option>services.locate.period</option> (when the

     

       214
       -
       update should be done).  It implements its functionality by defining

     

       215
       -
       two options declared by other modules:

     

       216
       -
       <option>systemd.services</option> (the set of all systemd services)

     

       217
       -
       and <option>services.cron.systemCronJobs</option> (the list of

     

       218
       -
       commands to be executed periodically by <command>cron</command>).</para>

     

       219
       -
       

     

       220
       -
       <example xml:id='locate-example'><title>NixOS module for the “locate” service</title>

     

       221
       -
       <programlisting>

     

       222
       -
       { config, lib, pkgs, ... }:

     

       223
       -
       

     

       224
       -
       with lib;

     

       225
       -
       

     

       226
       -
       let locatedb = "/var/cache/locatedb"; in

     

       227
       -
       

     

       228
       -
       {

     

       229
       -
         options = {

     

       230
       -
       

     

       231
       -
           services.locate = {

     

       232
       -
       

     

       233
       -
             enable = mkOption {

     

       234
       -
               type = types.bool;

     

       235
       -
               default = false;

     

       236
       -
               description = ''

     

       237
       -
                 If enabled, NixOS will periodically update the database of

     

       238
       -
                 files used by the <command>locate</command> command.

     

       239
       -
               '';

     

       240
       -
             };

     

       241
       -
       

     

       242
       -
             period = mkOption {

     

       243
       -
               type = types.str;

     

       244
       -
               default = "15 02 * * *";

     

       245
       -
               description = ''

     

       246
       -
                 This option defines (in the format used by cron) when the

     

       247
       -
                 locate database is updated.  The default is to update at

     

       248
       -
                 02:15 at night every day.

     

       249
       -
               '';

     

       250
       -
             };

     

       251
       -
       

     

       252
       -
           };

     

       253
       -
       

     

       254
       -
         };

     

       255
       -
       

     

       256
       -
         config = {

     

       257
       -
       

     

       258
       -
           systemd.services.update-locatedb =

     

       259
       -
             { description = "Update Locate Database";

     

       260
       -
               path  = [ pkgs.su ];

     

       261
       -
               script =

     

       262
       -
                 ''

     

       263
       -
                   mkdir -m 0755 -p $(dirname ${locatedb})

     

       264
       -
                   exec updatedb --localuser=nobody --output=${locatedb} --prunepaths='/tmp /var/tmp /media /run'

     

       265
       -
                 '';

     

       266
       -
             };

     

       267
       -
       

     

       268
       -
           services.cron.systemCronJobs = optional config.services.locate.enable

     

       269
       -
             "${config.services.locate.period} root ${config.systemd.package}/bin/systemctl start update-locatedb.service";

     

       270
       -
       

     

       271
       -
         };

     

       272
       -
       }</programlisting>

     

       273
       -
       </example>

     

       274
       -
       

     

       275
       -
       <section><title>Option declarations</title>

     

       276
       -
       

     

       277
       -
       <para>An option declaration specifies the name, type and description

     

       278
       -
       of a NixOS configuration option.  It is illegal to define an option

     

       279
       -
       that hasn’t been declared in any module.  A option declaration

     

       280
       -
       generally looks like this:

     

       281
       -
       

     

       282
       -
       <programlisting>

     

       283
       -
       options = {

     

       284
       -
         <replaceable>name</replaceable> = mkOption {

     

       285
       -
           type = <replaceable>type specification</replaceable>;

     

       286
       -
           default = <replaceable>default value</replaceable>;

     

       287
       -
           example = <replaceable>example value</replaceable>;

     

       288
       -
           description = "<replaceable>Description for use in the NixOS manual.</replaceable>";

     

       289
       -
         };

     

       290
       -
       };

     

       291
       -
       </programlisting>

     

       292
       -
       

     

       293
       -
       </para>

     

       294
       -
       

     

       295
       -
       <para>The function <varname>mkOption</varname> accepts the following arguments.

     

       296
       -
       

     

       297
       -
       <variablelist>

     

       298
       -
       

     

       299
       -
         <varlistentry>

     

       300
       -
           <term><varname>type</varname></term>

     

       301
       -
           <listitem>

     

       302
       -
             <para>The type of the option (see below).  It may be omitted,

     

       303
       -
             but that’s not advisable since it may lead to errors that are

     

       304
       -
             hard to diagnose.</para>

     

       305
       -
           </listitem>

     

       306
       -
         </varlistentry>

     

       307
       -
       

     

       308
       -
         <varlistentry>

     

       309
       -
           <term><varname>default</varname></term>

     

       310
       -
           <listitem>

     

       311
       -
             <para>The default value used if no value is defined by any

     

       312
       -
             module.  A default is not required; in that case, if the option

     

       313
       -
             value is ever used, an error will be thrown.</para>

     

       314
       -
           </listitem>

     

       315
       -
         </varlistentry>

     

       316
       -
       

     

       317
       -
         <varlistentry>

     

       318
       -
           <term><varname>example</varname></term>

     

       319
       -
           <listitem>

     

       320
       -
             <para>An example value that will be shown in the NixOS manual.</para>

     

       321
       -
           </listitem>

     

       322
       -
         </varlistentry>

     

       323
       -
       

     

       324
       -
         <varlistentry>

     

       325
       -
           <term><varname>description</varname></term>

     

       326
       -
           <listitem>

     

       327
       -
             <para>A textual description of the option, in DocBook format,

     

       328
       -
             that will be included in the NixOS manual.</para>

     

       329
       -
           </listitem>

     

       330
       -
         </varlistentry>

     

       331
       -
       

     

       332
       -
       </variablelist>

     

       333
       -
       

     

       334
       -
       </para>

     

       335
       -
       

     

       336
       -
       <para>Here is a non-exhaustive list of option types:

     

       337
       -
       

     

       338
       -
       <variablelist>

     

       339
       -
       

     

       340
       -
         <varlistentry>

     

       341
       -
           <term><varname>types.bool</varname></term>

     

       342
       -
           <listitem>

     

       343
       -
             <para>A Boolean.</para>

     

       344
       -
           </listitem>

     

       345
       -
         </varlistentry>

     

       346
       -
       

     

       347
       -
         <varlistentry>

     

       348
       -
           <term><varname>types.int</varname></term>

     

       349
       -
           <listitem>

     

       350
       -
             <para>An integer.</para>

     

       351
       -
           </listitem>

     

       352
       -
         </varlistentry>

     

       353
       -
       

     

       354
       -
         <varlistentry>

     

       355
       -
           <term><varname>types.str</varname></term>

     

       356
       -
           <listitem>

     

       357
       -
             <para>A string.</para>

     

       358
       -
           </listitem>

     

       359
       -
         </varlistentry>

     

       360
       -
       

     

       361
       -
         <varlistentry>

     

       362
       -
           <term><varname>types.lines</varname></term>

     

       363
       -
           <listitem>

     

       364
       -
             <para>A string.  If there are multiple definitions, they are

     

       365
       -
             concatenated, with newline characters in between.</para>

     

       366
       -
           </listitem>

     

       367
       -
         </varlistentry>

     

       368
       -
       

     

       369
       -
         <varlistentry>

     

       370
       -
           <term><varname>types.path</varname></term>

     

       371
       -
           <listitem>

     

       372
       -
             <para>A path, defined as anything that, when coerced to a

     

       373
       -
             string, starts with a slash.  This includes derivations.</para>

     

       374
       -
           </listitem>

     

       375
       -
         </varlistentry>

     

       376
       -
       

     

       377
       -
         <varlistentry>

     

       378
       -
           <term><varname>types.listOf</varname> <replaceable>t</replaceable></term>

     

       379
       -
           <listitem>

     

       380
       -
             <para>A list of elements of type <replaceable>t</replaceable>

     

       381
       -
             (e.g., <literal>types.listOf types.str</literal> is a list of

     

       382
       -
             strings).  Multiple definitions are concatenated together.</para>

     

       383
       -
           </listitem>

     

       384
       -
         </varlistentry>

     

       385
       -
       

     

       386
       -
         <varlistentry>

     

       387
       -
           <term><varname>types.attrsOf</varname> <replaceable>t</replaceable></term>

     

       388
       -
           <listitem>

     

       389
       -
             <para>A set of elements of type <replaceable>t</replaceable>

     

       390
       -
             (e.g., <literal>types.attrsOf types.int</literal> is a set of

     

       391
       -
             name/value pairs, the values being integers).</para>

     

       392
       -
           </listitem>

     

       393
       -
         </varlistentry>

     

       394
       -
       

     

       395
       -
         <varlistentry>

     

       396
       -
           <term><varname>types.nullOr</varname> <replaceable>t</replaceable></term>

     

       397
       -
           <listitem>

     

       398
       -
             <para>Either the value <literal>null</literal> or something of

     

       399
       -
             type <replaceable>t</replaceable>.</para>

     

       400
       -
           </listitem>

     

       401
       -
         </varlistentry>

     

       402
       -
       

     

       403
       -
       </variablelist>

     

       404
       -
       

     

       405
       -
       You can also create new types using the function

     

       406
       -
       <varname>mkOptionType</varname>.  See

     

       407
       -
       <filename>lib/types.nix</filename> in Nixpkgs for details.</para>

     

       408
       -
       

     

       409
       -
       </section>

     

       410
       -
       

     

       411
       -
       

     

       412
       -
       <section><title>Option definitions</title>

     

       413
       -
       

     

       414
       -
       <para>Option definitions are generally straight-forward bindings of values to option names, like

     

       415
       -
       

     

       416
       -
       <programlisting>

     

       417
       -
       config = {

     

       418
       -
         services.httpd.enable = true;

     

       419
       -
       };

     

       420
       -
       </programlisting>

     

       421
       -
       

     

       422
       -
       However, sometimes you need to wrap an option definition or set of

     

       423
       -
       option definitions in a <emphasis>property</emphasis> to achieve

     

       424
       -
       certain effects:</para>

     

       425
       -
       

     

       426
       -
       <simplesect><title>Delaying conditionals</title>

     

       427
       -
       

     

       428
       -
       <para>If a set of option definitions is conditional on the value of

     

       429
       -
       another option, you may need to use <varname>mkIf</varname>.

     

       430
       -
       Consider, for instance:

     

       431
       -
       

     

       432
       -
       <programlisting>

     

       433
       -
       config = if config.services.httpd.enable then {

     

       434
       -
         environment.systemPackages = [ <replaceable>...</replaceable> ];

     

       435
       -
         <replaceable>...</replaceable>

     

       436
       -
       } else {};

     

       437
       -
       </programlisting>

     

       438
       -
       

     

       439
       -
       This definition will cause Nix to fail with an “infinite recursion”

     

       440
       -
       error.  Why?  Because the value of

     

       441
       -
       <option>config.services.httpd.enable</option> depends on the value

     

       442
       -
       being constructed here.  After all, you could also write the clearly

     

       443
       -
       circular and contradictory:

     

       444
       -
       <programlisting>

     

       445
       -
       config = if config.services.httpd.enable then {

     

       446
       -
         services.httpd.enable = false;

     

       447
       -
       } else {

     

       448
       -
         services.httpd.enable = true;

     

       449
       -
       };

     

       450
       -
       </programlisting>

     

       451
       -
       

     

       452
       -
       The solution is to write:

     

       453
       -
       

     

       454
       -
       <programlisting>

     

       455
       -
       config = mkIf config.services.httpd.enable {

     

       456
       -
         environment.systemPackages = [ <replaceable>...</replaceable> ];

     

       457
       -
         <replaceable>...</replaceable>

     

       458
       -
       };

     

       459
       -
       </programlisting>

     

       460
       -
       

     

       461
       -
       The special function <varname>mkIf</varname> causes the evaluation of

     

       462
       -
       the conditional to be “pushed down” into the individual definitions,

     

       463
       -
       as if you had written:

     

       464
       -
       

     

       465
       -
       <programlisting>

     

       466
       -
       config = {

     

       467
       -
         environment.systemPackages = if config.services.httpd.enable then [ <replaceable>...</replaceable> ] else [];

     

       468
       -
         <replaceable>...</replaceable>

     

       469
       -
       };

     

       470
       -
       </programlisting>

     

       471
       -
       

     

       472
       -
       </para>

     

       473
       -
       

     

       474
       -
       </simplesect>

     

       475
       -
       

     

       476
       -
       <simplesect><title>Setting priorities</title>

     

       477
       -
       

     

       478
       -
       <para>A module can override the definitions of an option in other

     

       479
       -
       modules by setting a <emphasis>priority</emphasis>.  All option

     

       480
       -
       definitions that do not have the lowest priority value are discarded.

     

       481
       -
       By default, option definitions have priority 1000.  You can specify an

     

       482
       -
       explicit priority by using <varname>mkOverride</varname>, e.g.

     

       483
       -
       

     

       484
       -
       <programlisting>

     

       485
       -
       services.openssh.enable = mkOverride 10 false;

     

       486
       -
       </programlisting>

     

       487
       -
       

     

       488
       -
       This definition causes all other definitions with priorities above 10

     

       489
       -
       to be discarded.  The function <varname>mkForce</varname> is

     

       490
       -
       equal to <varname>mkOverride 50</varname>.</para>

     

       491
       -
       

     

       492
       -
       </simplesect>

     

       493
       -
       

     

       494
       -
       <simplesect><title>Merging configurations</title>

     

       495
       -
       

     

       496
       -
       <para>In conjunction with <literal>mkIf</literal>, it is sometimes

     

       497
       -
       useful for a module to return multiple sets of option definitions, to

     

       498
       -
       be merged together as if they were declared in separate modules.  This

     

       499
       -
       can be done using <varname>mkMerge</varname>:

     

       500
       -
       

     

       501
       -
       <programlisting>

     

       502
       -
       config = mkMerge

     

       503
       -
         [ # Unconditional stuff.

     

       504
       -
           { environment.systemPackages = [ <replaceable>...</replaceable> ];

     

       505
       -
           }

     

       506
       -
           # Conditional stuff.

     

       507
       -
           (mkIf config.services.bla.enable {

     

       508
       -
             environment.systemPackages = [ <replaceable>...</replaceable> ];

     

       509
       -
           })

     

       510
       -
         ];

     

       511
       -
       </programlisting>

     

       512
       -
       

     

       513
       -
       </para>

     

       514
       -
       

     

       515
       -
       </simplesect>

     

       516
       -
       

     

       517
       -
       </section>

     

       518
       -
       

     

       519
       -
       

     

       520
       -
       <section><title>Important options</title>

     

       521
       -
       

     

       522
       -
       <para>NixOS has many options, but some are of particular importance to

     

       523
       -
       module writers.</para>

     

       524
       -
       

     

       525
       -
       <variablelist>

     

       526
       -
       

     

       527
       -
         <varlistentry>

     

       528
       -
           <term><option>environment.etc</option></term>

     

       529
       -
           <listitem>

     

       530
       -
             <para>This set defines files in <filename>/etc</filename>.  A

     

       531
       -
             typical use is:

     

       532
       -
       <programlisting>

     

       533
       -
       environment.etc."os-release".text =

     

       534
       -
         ''

     

       535
       -
           NAME=NixOS

     

       536
       -
           <replaceable>...</replaceable>

     

       537
       -
         '';

     

       538
       -
       </programlisting>

     

       539
       -
             which causes a file named <filename>/etc/os-release</filename>

     

       540
       -
             to be created with the given contents.</para>

     

       541
       -
           </listitem>

     

       542
       -
         </varlistentry>

     

       543
       -
       

     

       544
       -
         <varlistentry>

     

       545
       -
           <term><option>system.activationScripts</option></term>

     

       546
       -
           <listitem>

     

       547
       -
             <para>A set of shell script fragments that must be executed

     

       548
       -
             whenever the configuration is activated (i.e., at boot time, or

     

       549
       -
             after running <command>nixos-rebuild switch</command>).  For instance,

     

       550
       -
       <programlisting>

     

       551
       -
       system.activationScripts.media =

     

       552
       -
         ''

     

       553
       -
           mkdir -m 0755 -p /media

     

       554
       -
         '';

     

       555
       -
       </programlisting>

     

       556
       -
             causes the directory <filename>/media</filename> to be created.

     

       557
       -
             Activation scripts must be idempotent.  They should not start

     

       558
       -
             background processes such as daemons; use

     

       559
       -
             <option>systemd.services</option> for that.</para>

     

       560
       -
           </listitem>

     

       561
       -
         </varlistentry>

     

       562
       -
       

     

       563
       -
         <varlistentry>

     

       564
       -
           <term><option>systemd.services</option></term>

     

       565
       -
           <listitem>

     

       566
       -
             <para>This is the set of systemd services.  Example:

     

       567
       -
       <programlisting>

     

       568
       -
       systemd.services.dhcpcd =

     

       569
       -
         { description = "DHCP Client";

     

       570
       -
           wantedBy = [ "multi-user.target" ];

     

       571
       -
           after = [ "systemd-udev-settle.service" ];

     

       572
       -
           path = [ dhcpcd pkgs.nettools pkgs.openresolv ];

     

       573
       -
           serviceConfig =

     

       574
       -
             { Type = "forking";

     

       575
       -
               PIDFile = "/run/dhcpcd.pid";

     

       576
       -
               ExecStart = "${dhcpcd}/sbin/dhcpcd --config ${dhcpcdConf}";

     

       577
       -
               Restart = "always";

     

       578
       -
             };

     

       579
       -
         };

     

       580
       -
       </programlisting>

     

       581
       -
             which creates the systemd unit

     

       582
       -
             <literal>dhcpcd.service</literal>.  The option

     

       583
       -
             <option>wantedBy</option> determined which other units pull this

     

       584
       -
             one in; <literal>multi-user.target</literal> is the default

     

       585
       -
             target of the system, so <literal>dhcpcd.service</literal> will

     

       586
       -
             always be started.  The option

     

       587
       -
             <option>serviceConfig.ExecStart</option> provides the main

     

       588
       -
             command for the service; it’s also possible to provide pre-start

     

       589
       -
             actions, stop scripts, and so on.</para>

     

       590
       -
           </listitem>

     

       591
       -
         </varlistentry>

     

       592
       -
       

     

       593
       -
         <varlistentry>

     

       594
       -
           <term><option>users.extraUsers</option></term>

     

       595
       -
           <term><option>users.extraGroups</option></term>

     

       596
       -
           <listitem>

     

       597
       -
             <para>If your service requires special UIDs or GIDs, you can

     

       598
       -
             define them with these options.  See <xref

     

       599
       -
             linkend="sec-user-management"/> for details.</para>

     

       600
       -
           </listitem>

     

       601
       -
         </varlistentry>

     

       602
       -
       

     

       603
       -
       </variablelist>

     

       604
       -
       

     

       605
       -
       </section>

     

       606
       -
       

     

       607
       -
       

     

       608
       -
       </section>

     

       609
       -
       

     

       610
       -
       

     

       611
       -
       <!--===============================================================-->

     

       612
       -
       

     

       613
       -
       <section xml:id="sec-building-parts">

     

       614
       -
       

     

       615
       -
       <title>Building specific parts of NixOS</title>

     

       616
       -
       

     

       617
       -
       <para>With the command <command>nix-build</command>, you can build

     

       618
       -
       specific parts of your NixOS configuration.  This is done as follows:

     

       619
       -
       

     

       620
       -
       <screen>

     

       621
       -
       $ cd <replaceable>/path/to/nixpkgs/nixos</replaceable>

     

       622
       -
       $ nix-build -A config.<replaceable>option</replaceable></screen>

     

       623
       -
       

     

       624
       -
       where <replaceable>option</replaceable> is a NixOS option with type

     

       625
       -
       “derivation” (i.e. something that can be built).  Attributes of

     

       626
       -
       interest include:

     

       627
       -
       

     

       628
       -
       <variablelist>

     

       629
       -
       

     

       630
       -
         <varlistentry>

     

       631
       -
           <term><varname>system.build.toplevel</varname></term>

     

       632
       -
           <listitem>

     

       633
       -
             <para>The top-level option that builds the entire NixOS system.

     

       634
       -
             Everything else in your configuration is indirectly pulled in by

     

       635
       -
             this option.  This is what <command>nixos-rebuild</command>

     

       636
       -
             builds and what <filename>/run/current-system</filename> points

     

       637
       -
             to afterwards.</para>

     

       638
       -
       

     

       639
       -
             <para>A shortcut to build this is:

     

       640
       -
       

     

       641
       -
       <screen>

     

       642
       -
       $ nix-build -A system</screen>

     

       643
       -
             </para>

     

       644
       -
           </listitem>

     

       645
       -
         </varlistentry>

     

       646
       -
       

     

       647
       -
         <varlistentry>

     

       648
       -
           <term><varname>system.build.manual.manual</varname></term>

     

       649
       -
           <listitem><para>The NixOS manual.</para></listitem>

     

       650
       -
         </varlistentry>

     

       651
       -
       

     

       652
       -
         <varlistentry>

     

       653
       -
           <term><varname>system.build.etc</varname></term>

     

       654
       -
           <listitem><para>A tree of symlinks that form the static parts of

     

       655
       -
           <filename>/etc</filename>.</para></listitem>

     

       656
       -
         </varlistentry>

     

       657
       -
       

     

       658
       -
         <varlistentry>

     

       659
       -
           <term><varname>system.build.initialRamdisk</varname></term>

     

       660
       -
           <term><varname>system.build.kernel</varname></term>

     

       661
       -
           <listitem>

     

       662
       -
             <para>The initial ramdisk and kernel of the system.  This allows

     

       663
       -
             a quick way to test whether the kernel and the initial ramdisk

     

       664
       -
             boot correctly, by using QEMU’s <option>-kernel</option> and

     

       665
       -
             <option>-initrd</option> options:

     

       666
       -
       

     

       667
       -
       <screen>

     

       668
       -
       $ nix-build -A config.system.build.initialRamdisk -o initrd

     

       669
       -
       $ nix-build -A config.system.build.kernel -o kernel

     

       670
       -
       $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null

     

       671
       -
       </screen>

     

       672
       -
       

     

       673
       -
             </para>

     

       674
       -
           </listitem>

     

       675
       -
         </varlistentry>

     

       676
       -
       

     

       677
       -
         <varlistentry>

     

       678
       -
           <term><varname>system.build.nixos-rebuild</varname></term>

     

       679
       -
           <term><varname>system.build.nixos-install</varname></term>

     

       680
       -
           <term><varname>system.build.nixos-generate-config</varname></term>

     

       681
       -
           <listitem>

     

       682
       -
             <para>These build the corresponding NixOS commands.</para>

     

       683
       -
           </listitem>

     

       684
       -
         </varlistentry>

     

       685
       -
       

     

       686
       -
         <varlistentry>

     

       687
       -
           <term><varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname></term>

     

       688
       -
           <listitem>

     

       689
       -
             <para>This builds the unit with the specified name.  Note that

     

       690
       -
             since unit names contain dots

     

       691
       -
             (e.g. <literal>httpd.service</literal>), you need to put them

     

       692
       -
             between quotes, like this:

     

       693
       -
       

     

       694
       -
       <screen>

     

       695
       -
       $ nix-build -A 'config.systemd.units."httpd.service".unit'

     

       696
       -
       </screen>

     

       697
       -
       

     

       698
       -
             You can also test individual units, without rebuilding the whole

     

       699
       -
             system, by putting them in

     

       700
       -
             <filename>/run/systemd/system</filename>:

     

       701
       -
       

     

       702
       -
       <screen>

     

       703
       -
       $ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \

     

       704
       -
           /run/systemd/system/tmp-httpd.service

     

       705
       -
       $ systemctl daemon-reload

     

       706
       -
       $ systemctl start tmp-httpd.service

     

       707
       -
       </screen>

     

       708
       -
       

     

       709
       -
             Note that the unit must not have the same name as any unit in

     

       710
       -
             <filename>/etc/systemd/system</filename> since those take

     

       711
       -
             precedence over <filename>/run/systemd/system</filename>.

     

       712
       -
             That’s why the unit is installed as

     

       713
       -
             <filename>tmp-httpd.service</filename> here.</para>

     

       714
       -
           </listitem>

     

       715
       -
         </varlistentry>

     

       716
       -
       

     

       717
       -
       </variablelist>

     

       718
       -
       

     

       719
       -
       </para>

     

       720
       -
       

     

       721
       -
       </section>

     

       722
       -
       

     

       723
       -
       

     

       724
       -
       <!--===============================================================-->

     

       725
       -
       

     

       726
       -
       <section xml:id="sec-building-cd">

     

       727
       -
       

     

       728
       -
       <title>Building your own NixOS CD</title>

     

       729
       -
       

     

       730
       -
       <para>Building a NixOS CD is as easy as configuring your own computer. The

     

       731
       -
       idea is to use another module which will replace

     

       732
       -
       your <filename>configuration.nix</filename> to configure the system that

     

       733
       -
       would be installed on the CD.</para>

     

       734
       -
       

     

       735
       -
       <para>Default CD/DVD configurations are available

     

       736
       -
       inside <filename>nixos/modules/installer/cd-dvd</filename>.  To build them

     

       737
       -
       you have to set <envar>NIXOS_CONFIG</envar> before

     

       738
       -
       running <command>nix-build</command> to build the ISO.

     

       739
       -
       

     

       740
       -
       <screen>

     

       741
       -
       $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix</screen>

     

       742
       -
       

     

       743
       -
       </para>

     

       744
       -
       

     

       745
       -
       <para>Before burning your CD/DVD, you can check the content of the image by mounting anywhere like

     

       746
       -
       suggested by the following command:

     

       747
       -
       

     

       748
       -
       <screen>

     

       749
       -
       $ mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>

     

       750
       -
       

     

       751
       -
       </para>

     

       752
       -
       

     

       753
       -
       </section>

     

       754
       -
       

     

       755
       -
       

     

       756
       -
       <!--===============================================================-->

     

       757
       -
       

     

       758
       -
       <section>

     

       759
       -
       

     

       760
       -
       <title>Testing the installer</title>

     

       761
       -
       

     

       762
       -
       <para>Building, burning, and booting from an installation CD is rather

     

       763
       -
       tedious, so here is a quick way to see if the installer works

     

       764
       -
       properly:

     

       765
       -
       

     

       766
       -
       <screen>

     

       767
       -
       $ nix-build -A config.system.build.nixos-install

     

       768
       -
       $ mount -t tmpfs none /mnt

     

       769
       -
       $ ./result/bin/nixos-install</screen>

     

       770
       -
       

     

       771
       -
       To start a login shell in the new NixOS installation in

     

       772
       -
       <filename>/mnt</filename>:

     

       773
       -
       

     

       774
       -
       <screen>

     

       775
       -
       $ ./result/bin/nixos-install --chroot

     

       776
       -
       </screen>

     

       777
       -
       

     

       778
       -
       </para>

     

       779
       -
       

     

       780
       -
       </section>

     

       781
       -
       

     

       782
       -
       

     

       783
       -
       

     

       784
       -
       <!--===============================================================-->

     

       785
       -
       

     

       786
       -
       <section xml:id="sec-nixos-tests">

     

       787
       -
       

     

       788
       -
       <title>NixOS tests</title>

     

       789
       -
       

     

       790
       -
       <para>When you add some feature to NixOS, you should write a test for

     

       791
       -
       it. NixOS tests are kept in the directory <filename

     

       792
       -
       xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/tests</filename>,

     

       793
       -
       and are executed (using Nix) by a testing framework that automatically

     

       794
       -
       starts one or more virtual machines containing the NixOS system(s)

     

       795
       -
       required for the test.</para>

     

       796
       -
       

     

       797
       -
       <simplesect><title>Writing tests</title>

     

       798
       -
       

     

       799
       -
       <para>A NixOS test is a Nix expression that has the following structure:

     

       800
       -
       

     

       801
       -
       <programlisting>

     

       802
       -
       import ./make-test.nix {

     

       803
       -
       

     

       804
       -
         # Either the configuration of a single machine:

     

       805
       -
         machine =

     

       806
       -
           { config, pkgs, ... }:

     

       807
       -
           { <replaceable>configuration…</replaceable>

     

       808
       -
           };

     

       809
       -
       

     

       810
       -
         # Or a set of machines:

     

       811
       -
         nodes =

     

       812
       -
           { <replaceable>machine1</replaceable> =

     

       813
       -
               { config, pkgs, ... }: { <replaceable>…</replaceable> };

     

       814
       -
             <replaceable>machine2</replaceable> =

     

       815
       -
               { config, pkgs, ... }: { <replaceable>…</replaceable> };

     

       816
       -
             …

     

       817
       -
           };

     

       818
       -
       

     

       819
       -
         testScript =

     

       820
       -
           ''

     

       821
       -
             <replaceable>Perl code…</replaceable>

     

       822
       -
           '';

     

       823
       -
       }

     

       824
       -
       </programlisting>

     

       825
       -
       

     

       826
       -
       The attribute <literal>testScript</literal> is a bit of Perl code that

     

       827
       -
       executes the test (described below). During the test, it will start

     

       828
       -
       one or more virtual machines, the configuration of which is described

     

       829
       -
       by the attribute <literal>machine</literal> (if you need only one

     

       830
       -
       machine in your test) or by the attribute <literal>nodes</literal> (if

     

       831
       -
       you need multiple machines). For instance, <filename

     

       832
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>

     

       833
       -
       only needs a single machine to test whether users can log in on the

     

       834
       -
       virtual console, whether device ownership is correctly maintained when

     

       835
       -
       switching between consoles, and so on. On the other hand, <filename

     

       836
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs.nix">nfs.nix</filename>,

     

       837
       -
       which tests NFS client and server functionality in the Linux kernel

     

       838
       -
       (including whether locks are maintained across server crashes),

     

       839
       -
       requires three machines: a server and two clients.</para>

     

       840
       -
       

     

       841
       -
       <para>There are a few special NixOS configuration options for test

     

       842
       -
       VMs:

     

       843
       -
       

     

       844
       -
       <!-- FIXME: would be nice to generate this automatically. -->

     

       845
       -
       

     

       846
       -
       <variablelist>

     

       847
       -
       

     

       848
       -
         <varlistentry>

     

       849
       -
           <term><option>virtualisation.memorySize</option></term>

     

       850
       -
           <listitem><para>The memory of the VM in

     

       851
       -
           megabytes.</para></listitem>

     

       852
       -
         </varlistentry>

     

       853
       -
       

     

       854
       -
         <varlistentry>

     

       855
       -
           <term><option>virtualisation.vlans</option></term>

     

       856
       -
           <listitem><para>The virtual networks to which the VM is

     

       857
       -
           connected. See <filename

     

       858
       -
           xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nat.nix">nat.nix</filename>

     

       859
       -
           for an example.</para></listitem>

     

       860
       -
         </varlistentry>

     

       861
       -
       

     

       862
       -
         <varlistentry>

     

       863
       -
           <term><option>virtualisation.writableStore</option></term>

     

       864
       -
           <listitem><para>By default, the Nix store in the VM is not

     

       865
       -
           writable. If you enable this option, a writable union file system

     

       866
       -
           is mounted on top of the Nix store to make it appear

     

       867
       -
           writable. This is necessary for tests that run Nix operations that

     

       868
       -
           modify the store.</para></listitem>

     

       869
       -
         </varlistentry>

     

       870
       -
       

     

       871
       -
       </variablelist>

     

       872
       -
       

     

       873
       -
       For more options, see the module <filename

     

       874
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix">qemu-vm.nix</filename>.</para>

     

       875
       -
       

     

       876
       -
       <para>The test script is a sequence of Perl statements that perform

     

       877
       -
       various actions, such as starting VMs, executing commands in the VMs,

     

       878
       -
       and so on. Each virtual machine is represented as an object stored in

     

       879
       -
       the variable <literal>$<replaceable>name</replaceable></literal>,

     

       880
       -
       where <replaceable>name</replaceable> is the identifier of the machine

     

       881
       -
       (which is just <literal>machine</literal> if you didn’t specify

     

       882
       -
       multiple machines using the <literal>nodes</literal> attribute). For

     

       883
       -
       instance, the following starts the machine, waits until it has

     

       884
       -
       finished booting, then executes a command and checks that the output

     

       885
       -
       is more-or-less correct:

     

       886
       -
       

     

       887
       -
       <programlisting>

     

       888
       -
       $machine->start;

     

       889
       -
       $machine->waitForUnit("default.target");

     

       890
       -
       $machine->succeed("uname") =~ /Linux/;

     

       891
       -
       </programlisting>

     

       892
       -
       

     

       893
       -
       The first line is actually unnecessary; machines are implicitly

     

       894
       -
       started when you first execute an action on them (such as

     

       895
       -
       <literal>waitForUnit</literal> or <literal>succeed</literal>). If you

     

       896
       -
       have multiple machines, you can speed up the test by starting them in

     

       897
       -
       parallel:

     

       898
       -
       

     

       899
       -
       <programlisting>

     

       900
       -
       startAll;

     

       901
       -
       </programlisting>

     

       902
       -
       

     

       903
       -
       </para>

     

       904
       -
       

     

       905
       -
       <para>The following methods are available on machine objects:

     

       906
       -
       

     

       907
       -
       <variablelist>

     

       908
       -
       

     

       909
       -
         <varlistentry>

     

       910
       -
           <term><methodname>start</methodname></term>

     

       911
       -
           <listitem><para>Start the virtual machine. This method is

     

       912
       -
           asynchronous — it does not wait for the machine to finish

     

       913
       -
           booting.</para></listitem>

     

       914
       -
         </varlistentry>

     

       915
       -
       

     

       916
       -
         <varlistentry>

     

       917
       -
           <term><methodname>shutdown</methodname></term>

     

       918
       -
           <listitem><para>Shut down the machine, waiting for the VM to

     

       919
       -
           exit.</para></listitem>

     

       920
       -
         </varlistentry>

     

       921
       -
       

     

       922
       -
         <varlistentry>

     

       923
       -
           <term><methodname>crash</methodname></term>

     

       924
       -
           <listitem><para>Simulate a sudden power failure, by telling the VM

     

       925
       -
           to exit immediately.</para></listitem>

     

       926
       -
         </varlistentry>

     

       927
       -
       

     

       928
       -
         <varlistentry>

     

       929
       -
           <term><methodname>block</methodname></term>

     

       930
       -
           <listitem><para>Simulate unplugging the Ethernet cable that

     

       931
       -
           connects the machine to the other machines.</para></listitem>

     

       932
       -
         </varlistentry>

     

       933
       -
       

     

       934
       -
         <varlistentry>

     

       935
       -
           <term><methodname>unblock</methodname></term>

     

       936
       -
           <listitem><para>Undo the effect of

     

       937
       -
           <methodname>block</methodname>.</para></listitem>

     

       938
       -
         </varlistentry>

     

       939
       -
       

     

       940
       -
         <varlistentry>

     

       941
       -
           <term><methodname>screenshot</methodname></term>

     

       942
       -
           <listitem><para>Take a picture of the display of the virtual

     

       943
       -
           machine, in PNG format. The screenshot is linked from the HTML

     

       944
       -
           log.</para></listitem>

     

       945
       -
         </varlistentry>

     

       946
       -
       

     

       947
       -
         <varlistentry>

     

       948
       -
           <term><methodname>sendMonitorCommand</methodname></term>

     

       949
       -
           <listitem><para>Send a command to the QEMU monitor. This is rarely

     

       950
       -
           used, but allows doing stuff such as attaching virtual USB disks

     

       951
       -
           to a running machine.</para></listitem>

     

       952
       -
         </varlistentry>

     

       953
       -
       

     

       954
       -
         <varlistentry>

     

       955
       -
           <term><methodname>sendKeys</methodname></term>

     

       956
       -
           <listitem><para>Simulate pressing keys on the virtual keyboard,

     

       957
       -
           e.g., <literal>sendKeys("ctrl-alt-delete")</literal>.</para></listitem>

     

       958
       -
         </varlistentry>

     

       959
       -
       

     

       960
       -
         <varlistentry>

     

       961
       -
           <term><methodname>sendChars</methodname></term>

     

       962
       -
           <listitem><para>Simulate typing a sequence of characters on the

     

       963
       -
           virtual keyboard, e.g., <literal>sendKeys("foobar\n")</literal>

     

       964
       -
           will type the string <literal>foobar</literal> followed by the

     

       965
       -
           Enter key.</para></listitem>

     

       966
       -
         </varlistentry>

     

       967
       -
       

     

       968
       -
         <varlistentry>

     

       969
       -
           <term><methodname>execute</methodname></term>

     

       970
       -
           <listitem><para>Execute a shell command, returning a list

     

       971
       -
           <literal>(<replaceable>status</replaceable>,

     

       972
       -
           <replaceable>stdout</replaceable>)</literal>.</para></listitem>

     

       973
       -
         </varlistentry>

     

       974
       -
       

     

       975
       -
         <varlistentry>

     

       976
       -
           <term><methodname>succeed</methodname></term>

     

       977
       -
           <listitem><para>Execute a shell command, raising an exception if

     

       978
       -
           the exit status is not zero, otherwise returning the standard

     

       979
       -
           output.</para></listitem>

     

       980
       -
         </varlistentry>

     

       981
       -
       

     

       982
       -
         <varlistentry>

     

       983
       -
           <term><methodname>fail</methodname></term>

     

       984
       -
           <listitem><para>Like <methodname>succeed</methodname>, but raising

     

       985
       -
           an exception if the command returns a zero status.</para></listitem>

     

       986
       -
         </varlistentry>

     

       987
       -
       

     

       988
       -
         <varlistentry>

     

       989
       -
           <term><methodname>waitUntilSucceeds</methodname></term>

     

       990
       -
           <listitem><para>Repeat a shell command with 1-second intervals

     

       991
       -
           until it succeeds.</para></listitem>

     

       992
       -
         </varlistentry>

     

       993
       -
       

     

       994
       -
         <varlistentry>

     

       995
       -
           <term><methodname>waitUntilFails</methodname></term>

     

       996
       -
           <listitem><para>Repeat a shell command with 1-second intervals

     

       997
       -
           until it fails.</para></listitem>

     

       998
       -
         </varlistentry>

     

       999
       -
       

     

       1000
       -
         <varlistentry>

     

       1001
       -
           <term><methodname>waitForUnit</methodname></term>

     

       1002
       -
           <listitem><para>Wait until the specified systemd unit has reached

     

       1003
       -
           the “active” state.</para></listitem>

     

       1004
       -
         </varlistentry>

     

       1005
       -
       

     

       1006
       -
         <varlistentry>

     

       1007
       -
           <term><methodname>waitForFile</methodname></term>

     

       1008
       -
           <listitem><para>Wait until the specified file

     

       1009
       -
           exists.</para></listitem>

     

       1010
       -
         </varlistentry>

     

       1011
       -
       

     

       1012
       -
         <varlistentry>

     

       1013
       -
           <term><methodname>waitForOpenPort</methodname></term>

     

       1014
       -
           <listitem><para>Wait until a process is listening on the given TCP

     

       1015
       -
           port (on <literal>localhost</literal>, at least).</para></listitem>

     

       1016
       -
         </varlistentry>

     

       1017
       -
       

     

       1018
       -
         <varlistentry>

     

       1019
       -
           <term><methodname>waitForClosedPort</methodname></term>

     

       1020
       -
           <listitem><para>Wait until nobody is listening on the given TCP

     

       1021
       -
           port.</para></listitem>

     

       1022
       -
         </varlistentry>

     

       1023
       -
       

     

       1024
       -
         <varlistentry>

     

       1025
       -
           <term><methodname>waitForX</methodname></term>

     

       1026
       -
           <listitem><para>Wait until the X11 server is accepting

     

       1027
       -
           connections.</para></listitem>

     

       1028
       -
         </varlistentry>

     

       1029
       -
       

     

       1030
       -
         <varlistentry>

     

       1031
       -
           <term><methodname>waitForWindow</methodname></term>

     

       1032
       -
           <listitem><para>Wait until an X11 window has appeared whose name

     

       1033
       -
           matches the given regular expression, e.g.,

     

       1034
       -
           <literal>waitForWindow(qr/Terminal/)</literal>.</para></listitem>

     

       1035
       -
         </varlistentry>

     

       1036
       -
       

     

       1037
       -
       </variablelist>

     

       1038
       -
       

     

       1039
       -
       </para>

     

       1040
       -
       

     

       1041
       -
       </simplesect>

     

       1042
       -
       

     

       1043
       -
       

     

       1044
       -
       <simplesect><title>Running tests</title>

     

       1045
       -
       

     

       1046
       -
       <para>You can run tests using <command>nix-build</command>. For

     

       1047
       -
       example, to run the test <filename

     

       1048
       -
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>,

     

       1049
       -
       you just do:

     

       1050
       -
       

     

       1051
       -
       <screen>

     

       1052
       -
       $ nix-build '&lt;nixpkgs/nixos/tests/login.nix>'

     

       1053
       -
       </screen>

     

       1054
       -
       

     

       1055
       -
       or, if you don’t want to rely on <envar>NIX_PATH</envar>:

     

       1056
       -
       

     

       1057
       -
       <screen>

     

       1058
       -
       $ cd /my/nixpkgs/nixos/tests

     

       1059
       -
       $ nix-build login.nix

     

       1060
       -
       …

     

       1061
       -
       running the VM test script

     

       1062
       -
       machine: QEMU running (pid 8841)

     

       1063
       -
       …

     

       1064
       -
       6 out of 6 tests succeeded

     

       1065
       -
       </screen>

     

       1066
       -
       

     

       1067
       -
       After building/downloading all required dependencies, this will

     

       1068
       -
       perform a build that starts a QEMU/KVM virtual machine containing a

     

       1069
       -
       NixOS system. The virtual machine mounts the Nix store of the host;

     

       1070
       -
       this makes VM creation very fast, as no disk image needs to be

     

       1071
       -
       created. Afterwards, you can view a pretty-printed log of the test:

     

       1072
       -
       

     

       1073
       -
       <screen>

     

       1074
       -
       $ firefox result/log.html

     

       1075
       -
       </screen>

     

       1076
       -
       

     

       1077
       -
       </para>

     

       1078
       -
       

     

       1079
       -
       <para>It is also possible to run the test environment interactively,

     

       1080
       -
       allowing you to experiment with the VMs.  For example:

     

       1081
       -
       

     

       1082
       -
       <screen>

     

       1083
       -
       $ nix-build login.nix -A driver

     

       1084
       -
       $ ./result/bin/nixos-run-vms

     

       1085
       -
       </screen>

     

       1086
       -
       

     

       1087
       -
       The script <command>nixos-run-vms</command> starts the virtual

     

       1088
       -
       machines defined by test.  The root file system of the VMs is created

     

       1089
       -
       on the fly and kept across VM restarts in

     

       1090
       -
       <filename>./</filename><varname>hostname</varname><filename>.qcow2</filename>.</para>

     

       1091
       -
       

     

       1092
       -
       <para>Finally, the test itself can be run interactively.  This is

     

       1093
       -
       particularly useful when developing or debugging a test:

     

       1094
       -
       

     

       1095
       -
       <screen>

     

       1096
       -
       $ nix-build tests/ -A nfs.driver

     

       1097
       -
       $ ./result/bin/nixos-test-driver

     

       1098
       -
       starting VDE switch for network 1

     

       1099
       -
       &gt;

     

       1100
       -
       </screen>

     

       1101
       -
       

     

       1102
       -
       You can then take any Perl statement, e.g.

     

       1103
       -
       

     

       1104
       -
       <screen>

     

       1105
       -
       &gt; startAll

     

       1106
       -
       &gt; $machine->succeed("touch /tmp/foo")

     

       1107
       -
       </screen>

     

       1108
       -
       

     

       1109
       -
       The function <command>testScript</command> executes the entire test

     

       1110
       -
       script and drops you back into the test driver command line upon its

     

       1111
       -
       completion.  This allows you to inspect the state of the VMs after the

     

       1112
       -
       test (e.g. to debug the test script).</para>

     

       1113
       -
       

     

       1114
       -
       </simplesect>

     

       1115
       -
       

     

       1116
       -
       </section>

     

       1117
       -
       

     

       1118
       -
       

     

       1119
       -
       </chapter>

+32

nixos/doc/manual/development/building-nixos.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-building-cd">

     

       6
       +
       

     

       7
       +
       <title>Building Your Own NixOS CD</title>

     

       8
       +
       

     

       9
       +
       <para>Building a NixOS CD is as easy as configuring your own computer. The

     

       10
       +
       idea is to use another module which will replace

     

       11
       +
       your <filename>configuration.nix</filename> to configure the system that

     

       12
       +
       would be installed on the CD.</para>

     

       13
       +
       

     

       14
       +
       <para>Default CD/DVD configurations are available

     

       15
       +
       inside <filename>nixos/modules/installer/cd-dvd</filename>.  To build them

     

       16
       +
       you have to set <envar>NIXOS_CONFIG</envar> before

     

       17
       +
       running <command>nix-build</command> to build the ISO.

     

       18
       +
       

     

       19
       +
       <screen>

     

       20
       +
       $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix</screen>

     

       21
       +
       

     

       22
       +
       </para>

     

       23
       +
       

     

       24
       +
       <para>Before burning your CD/DVD, you can check the content of the image by mounting anywhere like

     

       25
       +
       suggested by the following command:

     

       26
       +
       

     

       27
       +
       <screen>

     

       28
       +
       $ mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>

     

       29
       +
       

     

       30
       +
       </para>

     

       31
       +
       

     

       32
       +
       </chapter>

+113

nixos/doc/manual/development/building-parts.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-building-parts">

     

       6
       +
       

     

       7
       +
       <title>Building Specific Parts of NixOS</title>

     

       8
       +
       

     

       9
       +
       <para>With the command <command>nix-build</command>, you can build

     

       10
       +
       specific parts of your NixOS configuration.  This is done as follows:

     

       11
       +
       

     

       12
       +
       <screen>

     

       13
       +
       $ cd <replaceable>/path/to/nixpkgs/nixos</replaceable>

     

       14
       +
       $ nix-build -A config.<replaceable>option</replaceable></screen>

     

       15
       +
       

     

       16
       +
       where <replaceable>option</replaceable> is a NixOS option with type

     

       17
       +
       “derivation” (i.e. something that can be built).  Attributes of

     

       18
       +
       interest include:

     

       19
       +
       

     

       20
       +
       <variablelist>

     

       21
       +
       

     

       22
       +
         <varlistentry>

     

       23
       +
           <term><varname>system.build.toplevel</varname></term>

     

       24
       +
           <listitem>

     

       25
       +
             <para>The top-level option that builds the entire NixOS system.

     

       26
       +
             Everything else in your configuration is indirectly pulled in by

     

       27
       +
             this option.  This is what <command>nixos-rebuild</command>

     

       28
       +
             builds and what <filename>/run/current-system</filename> points

     

       29
       +
             to afterwards.</para>

     

       30
       +
       

     

       31
       +
             <para>A shortcut to build this is:

     

       32
       +
       

     

       33
       +
       <screen>

     

       34
       +
       $ nix-build -A system</screen>

     

       35
       +
             </para>

     

       36
       +
           </listitem>

     

       37
       +
         </varlistentry>

     

       38
       +
       

     

       39
       +
         <varlistentry>

     

       40
       +
           <term><varname>system.build.manual.manual</varname></term>

     

       41
       +
           <listitem><para>The NixOS manual.</para></listitem>

     

       42
       +
         </varlistentry>

     

       43
       +
       

     

       44
       +
         <varlistentry>

     

       45
       +
           <term><varname>system.build.etc</varname></term>

     

       46
       +
           <listitem><para>A tree of symlinks that form the static parts of

     

       47
       +
           <filename>/etc</filename>.</para></listitem>

     

       48
       +
         </varlistentry>

     

       49
       +
       

     

       50
       +
         <varlistentry>

     

       51
       +
           <term><varname>system.build.initialRamdisk</varname></term>

     

       52
       +
           <term><varname>system.build.kernel</varname></term>

     

       53
       +
           <listitem>

     

       54
       +
             <para>The initial ramdisk and kernel of the system.  This allows

     

       55
       +
             a quick way to test whether the kernel and the initial ramdisk

     

       56
       +
             boot correctly, by using QEMU’s <option>-kernel</option> and

     

       57
       +
             <option>-initrd</option> options:

     

       58
       +
       

     

       59
       +
       <screen>

     

       60
       +
       $ nix-build -A config.system.build.initialRamdisk -o initrd

     

       61
       +
       $ nix-build -A config.system.build.kernel -o kernel

     

       62
       +
       $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null

     

       63
       +
       </screen>

     

       64
       +
       

     

       65
       +
             </para>

     

       66
       +
           </listitem>

     

       67
       +
         </varlistentry>

     

       68
       +
       

     

       69
       +
         <varlistentry>

     

       70
       +
           <term><varname>system.build.nixos-rebuild</varname></term>

     

       71
       +
           <term><varname>system.build.nixos-install</varname></term>

     

       72
       +
           <term><varname>system.build.nixos-generate-config</varname></term>

     

       73
       +
           <listitem>

     

       74
       +
             <para>These build the corresponding NixOS commands.</para>

     

       75
       +
           </listitem>

     

       76
       +
         </varlistentry>

     

       77
       +
       

     

       78
       +
         <varlistentry>

     

       79
       +
           <term><varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname></term>

     

       80
       +
           <listitem>

     

       81
       +
             <para>This builds the unit with the specified name.  Note that

     

       82
       +
             since unit names contain dots

     

       83
       +
             (e.g. <literal>httpd.service</literal>), you need to put them

     

       84
       +
             between quotes, like this:

     

       85
       +
       

     

       86
       +
       <screen>

     

       87
       +
       $ nix-build -A 'config.systemd.units."httpd.service".unit'

     

       88
       +
       </screen>

     

       89
       +
       

     

       90
       +
             You can also test individual units, without rebuilding the whole

     

       91
       +
             system, by putting them in

     

       92
       +
             <filename>/run/systemd/system</filename>:

     

       93
       +
       

     

       94
       +
       <screen>

     

       95
       +
       $ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \

     

       96
       +
           /run/systemd/system/tmp-httpd.service

     

       97
       +
       $ systemctl daemon-reload

     

       98
       +
       $ systemctl start tmp-httpd.service

     

       99
       +
       </screen>

     

       100
       +
       

     

       101
       +
             Note that the unit must not have the same name as any unit in

     

       102
       +
             <filename>/etc/systemd/system</filename> since those take

     

       103
       +
             precedence over <filename>/run/systemd/system</filename>.

     

       104
       +
             That’s why the unit is installed as

     

       105
       +
             <filename>tmp-httpd.service</filename> here.</para>

     

       106
       +
           </listitem>

     

       107
       +
         </varlistentry>

     

       108
       +
       

     

       109
       +
       </variablelist>

     

       110
       +
       

     

       111
       +
       </para>

     

       112
       +
       

     

       113
       +
       </chapter>

+20

nixos/doc/manual/development/development.xml

···

       1
       +
       <part   xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="ch-development">

     

       6
       +
       

     

       7
       +
       <title>Development</title>

     

       8
       +
       

     

       9
       +
       <partintro>

     

       10
       +
       <para>This chapter describes how you can modify and extend

     

       11
       +
       NixOS.</para>

     

       12
       +
       </partintro>

     

       13
       +
       

     

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

     

       15
       +
       <xi:include href="writing-modules.xml" />

     

       16
       +
       <xi:include href="building-parts.xml" />

     

       17
       +
       <xi:include href="building-nixos.xml" />

     

       18
       +
       <xi:include href="testing-installer.xml" />

     

       19
       +
       

     

       20
       +
       </part>

+19

nixos/doc/manual/development/nixos-tests.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-nixos-tests">

     

       6
       +
       

     

       7
       +
       <title>NixOS Tests</title>

     

       8
       +
       

     

       9
       +
       <para>When you add some feature to NixOS, you should write a test for

     

       10
       +
       it. NixOS tests are kept in the directory <filename

     

       11
       +
       xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/tests</filename>,

     

       12
       +
       and are executed (using Nix) by a testing framework that automatically

     

       13
       +
       starts one or more virtual machines containing the NixOS system(s)

     

       14
       +
       required for the test.</para>

     

       15
       +
       

     

       16
       +
       <xi:include href="writing-nixos-tests.xml" />

     

       17
       +
       <xi:include href="running-nixos-tests.xml" />

     

       18
       +
       

     

       19
       +
       </chapter>

+141

nixos/doc/manual/development/option-declarations.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-option-declarations">

     

       6
       +
       

     

       7
       +
       <title>Option Declarations</title>

     

       8
       +
       

     

       9
       +
       <para>An option declaration specifies the name, type and description

     

       10
       +
       of a NixOS configuration option.  It is illegal to define an option

     

       11
       +
       that hasn’t been declared in any module.  A option declaration

     

       12
       +
       generally looks like this:

     

       13
       +
       

     

       14
       +
       <programlisting>

     

       15
       +
       options = {

     

       16
       +
         <replaceable>name</replaceable> = mkOption {

     

       17
       +
           type = <replaceable>type specification</replaceable>;

     

       18
       +
           default = <replaceable>default value</replaceable>;

     

       19
       +
           example = <replaceable>example value</replaceable>;

     

       20
       +
           description = "<replaceable>Description for use in the NixOS manual.</replaceable>";

     

       21
       +
         };

     

       22
       +
       };

     

       23
       +
       </programlisting>

     

       24
       +
       

     

       25
       +
       </para>

     

       26
       +
       

     

       27
       +
       <para>The function <varname>mkOption</varname> accepts the following arguments.

     

       28
       +
       

     

       29
       +
       <variablelist>

     

       30
       +
       

     

       31
       +
         <varlistentry>

     

       32
       +
           <term><varname>type</varname></term>

     

       33
       +
           <listitem>

     

       34
       +
             <para>The type of the option (see below).  It may be omitted,

     

       35
       +
             but that’s not advisable since it may lead to errors that are

     

       36
       +
             hard to diagnose.</para>

     

       37
       +
           </listitem>

     

       38
       +
         </varlistentry>

     

       39
       +
       

     

       40
       +
         <varlistentry>

     

       41
       +
           <term><varname>default</varname></term>

     

       42
       +
           <listitem>

     

       43
       +
             <para>The default value used if no value is defined by any

     

       44
       +
             module.  A default is not required; in that case, if the option

     

       45
       +
             value is ever used, an error will be thrown.</para>

     

       46
       +
           </listitem>

     

       47
       +
         </varlistentry>

     

       48
       +
       

     

       49
       +
         <varlistentry>

     

       50
       +
           <term><varname>example</varname></term>

     

       51
       +
           <listitem>

     

       52
       +
             <para>An example value that will be shown in the NixOS manual.</para>

     

       53
       +
           </listitem>

     

       54
       +
         </varlistentry>

     

       55
       +
       

     

       56
       +
         <varlistentry>

     

       57
       +
           <term><varname>description</varname></term>

     

       58
       +
           <listitem>

     

       59
       +
             <para>A textual description of the option, in DocBook format,

     

       60
       +
             that will be included in the NixOS manual.</para>

     

       61
       +
           </listitem>

     

       62
       +
         </varlistentry>

     

       63
       +
       

     

       64
       +
       </variablelist>

     

       65
       +
       

     

       66
       +
       </para>

     

       67
       +
       

     

       68
       +
       <para>Here is a non-exhaustive list of option types:

     

       69
       +
       

     

       70
       +
       <variablelist>

     

       71
       +
       

     

       72
       +
         <varlistentry>

     

       73
       +
           <term><varname>types.bool</varname></term>

     

       74
       +
           <listitem>

     

       75
       +
             <para>A Boolean.</para>

     

       76
       +
           </listitem>

     

       77
       +
         </varlistentry>

     

       78
       +
       

     

       79
       +
         <varlistentry>

     

       80
       +
           <term><varname>types.int</varname></term>

     

       81
       +
           <listitem>

     

       82
       +
             <para>An integer.</para>

     

       83
       +
           </listitem>

     

       84
       +
         </varlistentry>

     

       85
       +
       

     

       86
       +
         <varlistentry>

     

       87
       +
           <term><varname>types.str</varname></term>

     

       88
       +
           <listitem>

     

       89
       +
             <para>A string.</para>

     

       90
       +
           </listitem>

     

       91
       +
         </varlistentry>

     

       92
       +
       

     

       93
       +
         <varlistentry>

     

       94
       +
           <term><varname>types.lines</varname></term>

     

       95
       +
           <listitem>

     

       96
       +
             <para>A string.  If there are multiple definitions, they are

     

       97
       +
             concatenated, with newline characters in between.</para>

     

       98
       +
           </listitem>

     

       99
       +
         </varlistentry>

     

       100
       +
       

     

       101
       +
         <varlistentry>

     

       102
       +
           <term><varname>types.path</varname></term>

     

       103
       +
           <listitem>

     

       104
       +
             <para>A path, defined as anything that, when coerced to a

     

       105
       +
             string, starts with a slash.  This includes derivations.</para>

     

       106
       +
           </listitem>

     

       107
       +
         </varlistentry>

     

       108
       +
       

     

       109
       +
         <varlistentry>

     

       110
       +
           <term><varname>types.listOf</varname> <replaceable>t</replaceable></term>

     

       111
       +
           <listitem>

     

       112
       +
             <para>A list of elements of type <replaceable>t</replaceable>

     

       113
       +
             (e.g., <literal>types.listOf types.str</literal> is a list of

     

       114
       +
             strings).  Multiple definitions are concatenated together.</para>

     

       115
       +
           </listitem>

     

       116
       +
         </varlistentry>

     

       117
       +
       

     

       118
       +
         <varlistentry>

     

       119
       +
           <term><varname>types.attrsOf</varname> <replaceable>t</replaceable></term>

     

       120
       +
           <listitem>

     

       121
       +
             <para>A set of elements of type <replaceable>t</replaceable>

     

       122
       +
             (e.g., <literal>types.attrsOf types.int</literal> is a set of

     

       123
       +
             name/value pairs, the values being integers).</para>

     

       124
       +
           </listitem>

     

       125
       +
         </varlistentry>

     

       126
       +
       

     

       127
       +
         <varlistentry>

     

       128
       +
           <term><varname>types.nullOr</varname> <replaceable>t</replaceable></term>

     

       129
       +
           <listitem>

     

       130
       +
             <para>Either the value <literal>null</literal> or something of

     

       131
       +
             type <replaceable>t</replaceable>.</para>

     

       132
       +
           </listitem>

     

       133
       +
         </varlistentry>

     

       134
       +
       

     

       135
       +
       </variablelist>

     

       136
       +
       

     

       137
       +
       You can also create new types using the function

     

       138
       +
       <varname>mkOptionType</varname>.  See

     

       139
       +
       <filename>lib/types.nix</filename> in Nixpkgs for details.</para>

     

       140
       +
       

     

       141
       +
       </section>

+112

nixos/doc/manual/development/option-def.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-option-definitions">

     

       6
       +
       

     

       7
       +
       <title>Option Definitions</title>

     

       8
       +
       

     

       9
       +
       <para>Option definitions are generally straight-forward bindings of values to option names, like

     

       10
       +
       

     

       11
       +
       <programlisting>

     

       12
       +
       config = {

     

       13
       +
         services.httpd.enable = true;

     

       14
       +
       };

     

       15
       +
       </programlisting>

     

       16
       +
       

     

       17
       +
       However, sometimes you need to wrap an option definition or set of

     

       18
       +
       option definitions in a <emphasis>property</emphasis> to achieve

     

       19
       +
       certain effects:</para>

     

       20
       +
       

     

       21
       +
       <simplesect><title>Delaying Conditionals</title>

     

       22
       +
       

     

       23
       +
       <para>If a set of option definitions is conditional on the value of

     

       24
       +
       another option, you may need to use <varname>mkIf</varname>.

     

       25
       +
       Consider, for instance:

     

       26
       +
       

     

       27
       +
       <programlisting>

     

       28
       +
       config = if config.services.httpd.enable then {

     

       29
       +
         environment.systemPackages = [ <replaceable>...</replaceable> ];

     

       30
       +
         <replaceable>...</replaceable>

     

       31
       +
       } else {};

     

       32
       +
       </programlisting>

     

       33
       +
       

     

       34
       +
       This definition will cause Nix to fail with an “infinite recursion”

     

       35
       +
       error.  Why?  Because the value of

     

       36
       +
       <option>config.services.httpd.enable</option> depends on the value

     

       37
       +
       being constructed here.  After all, you could also write the clearly

     

       38
       +
       circular and contradictory:

     

       39
       +
       <programlisting>

     

       40
       +
       config = if config.services.httpd.enable then {

     

       41
       +
         services.httpd.enable = false;

     

       42
       +
       } else {

     

       43
       +
         services.httpd.enable = true;

     

       44
       +
       };

     

       45
       +
       </programlisting>

     

       46
       +
       

     

       47
       +
       The solution is to write:

     

       48
       +
       

     

       49
       +
       <programlisting>

     

       50
       +
       config = mkIf config.services.httpd.enable {

     

       51
       +
         environment.systemPackages = [ <replaceable>...</replaceable> ];

     

       52
       +
         <replaceable>...</replaceable>

     

       53
       +
       };

     

       54
       +
       </programlisting>

     

       55
       +
       

     

       56
       +
       The special function <varname>mkIf</varname> causes the evaluation of

     

       57
       +
       the conditional to be “pushed down” into the individual definitions,

     

       58
       +
       as if you had written:

     

       59
       +
       

     

       60
       +
       <programlisting>

     

       61
       +
       config = {

     

       62
       +
         environment.systemPackages = if config.services.httpd.enable then [ <replaceable>...</replaceable> ] else [];

     

       63
       +
         <replaceable>...</replaceable>

     

       64
       +
       };

     

       65
       +
       </programlisting>

     

       66
       +
       

     

       67
       +
       </para>

     

       68
       +
       

     

       69
       +
       </simplesect>

     

       70
       +
       

     

       71
       +
       <simplesect><title>Setting Priorities</title>

     

       72
       +
       

     

       73
       +
       <para>A module can override the definitions of an option in other

     

       74
       +
       modules by setting a <emphasis>priority</emphasis>.  All option

     

       75
       +
       definitions that do not have the lowest priority value are discarded.

     

       76
       +
       By default, option definitions have priority 1000.  You can specify an

     

       77
       +
       explicit priority by using <varname>mkOverride</varname>, e.g.

     

       78
       +
       

     

       79
       +
       <programlisting>

     

       80
       +
       services.openssh.enable = mkOverride 10 false;

     

       81
       +
       </programlisting>

     

       82
       +
       

     

       83
       +
       This definition causes all other definitions with priorities above 10

     

       84
       +
       to be discarded.  The function <varname>mkForce</varname> is

     

       85
       +
       equal to <varname>mkOverride 50</varname>.</para>

     

       86
       +
       

     

       87
       +
       </simplesect>

     

       88
       +
       

     

       89
       +
       <simplesect><title>Merging Configurations</title>

     

       90
       +
       

     

       91
       +
       <para>In conjunction with <literal>mkIf</literal>, it is sometimes

     

       92
       +
       useful for a module to return multiple sets of option definitions, to

     

       93
       +
       be merged together as if they were declared in separate modules.  This

     

       94
       +
       can be done using <varname>mkMerge</varname>:

     

       95
       +
       

     

       96
       +
       <programlisting>

     

       97
       +
       config = mkMerge

     

       98
       +
         [ # Unconditional stuff.

     

       99
       +
           { environment.systemPackages = [ <replaceable>...</replaceable> ];

     

       100
       +
           }

     

       101
       +
           # Conditional stuff.

     

       102
       +
           (mkIf config.services.bla.enable {

     

       103
       +
             environment.systemPackages = [ <replaceable>...</replaceable> ];

     

       104
       +
           })

     

       105
       +
         ];

     

       106
       +
       </programlisting>

     

       107
       +
       

     

       108
       +
       </para>

     

       109
       +
       

     

       110
       +
       </simplesect>

     

       111
       +
       

     

       112
       +
       </section>

+77

nixos/doc/manual/development/running-nixos-tests.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-running-nixos-tests">

     

       6
       +
       

     

       7
       +
       <title>Running Tests</title>

     

       8
       +
       

     

       9
       +
       <para>You can run tests using <command>nix-build</command>. For

     

       10
       +
       example, to run the test <filename

     

       11
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>,

     

       12
       +
       you just do:

     

       13
       +
       

     

       14
       +
       <screen>

     

       15
       +
       $ nix-build '&lt;nixpkgs/nixos/tests/login.nix>'

     

       16
       +
       </screen>

     

       17
       +
       

     

       18
       +
       or, if you don’t want to rely on <envar>NIX_PATH</envar>:

     

       19
       +
       

     

       20
       +
       <screen>

     

       21
       +
       $ cd /my/nixpkgs/nixos/tests

     

       22
       +
       $ nix-build login.nix

     

       23
       +
       …

     

       24
       +
       running the VM test script

     

       25
       +
       machine: QEMU running (pid 8841)

     

       26
       +
       …

     

       27
       +
       6 out of 6 tests succeeded

     

       28
       +
       </screen>

     

       29
       +
       

     

       30
       +
       After building/downloading all required dependencies, this will

     

       31
       +
       perform a build that starts a QEMU/KVM virtual machine containing a

     

       32
       +
       NixOS system. The virtual machine mounts the Nix store of the host;

     

       33
       +
       this makes VM creation very fast, as no disk image needs to be

     

       34
       +
       created. Afterwards, you can view a pretty-printed log of the test:

     

       35
       +
       

     

       36
       +
       <screen>

     

       37
       +
       $ firefox result/log.html

     

       38
       +
       </screen>

     

       39
       +
       

     

       40
       +
       </para>

     

       41
       +
       

     

       42
       +
       <para>It is also possible to run the test environment interactively,

     

       43
       +
       allowing you to experiment with the VMs.  For example:

     

       44
       +
       

     

       45
       +
       <screen>

     

       46
       +
       $ nix-build login.nix -A driver

     

       47
       +
       $ ./result/bin/nixos-run-vms

     

       48
       +
       </screen>

     

       49
       +
       

     

       50
       +
       The script <command>nixos-run-vms</command> starts the virtual

     

       51
       +
       machines defined by test.  The root file system of the VMs is created

     

       52
       +
       on the fly and kept across VM restarts in

     

       53
       +
       <filename>./</filename><varname>hostname</varname><filename>.qcow2</filename>.</para>

     

       54
       +
       

     

       55
       +
       <para>Finally, the test itself can be run interactively.  This is

     

       56
       +
       particularly useful when developing or debugging a test:

     

       57
       +
       

     

       58
       +
       <screen>

     

       59
       +
       $ nix-build tests/ -A nfs.driver

     

       60
       +
       $ ./result/bin/nixos-test-driver

     

       61
       +
       starting VDE switch for network 1

     

       62
       +
       &gt;

     

       63
       +
       </screen>

     

       64
       +
       

     

       65
       +
       You can then take any Perl statement, e.g.

     

       66
       +
       

     

       67
       +
       <screen>

     

       68
       +
       &gt; startAll

     

       69
       +
       &gt; $machine->succeed("touch /tmp/foo")

     

       70
       +
       </screen>

     

       71
       +
       

     

       72
       +
       The function <command>testScript</command> executes the entire test

     

       73
       +
       script and drops you back into the test driver command line upon its

     

       74
       +
       completion.  This allows you to inspect the state of the VMs after the

     

       75
       +
       test (e.g. to debug the test script).</para>

     

       76
       +
       

     

       77
       +
       </section>

+95

nixos/doc/manual/development/sources.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-getting-sources">

     

       6
       +
       

     

       7
       +
       <title>Getting the Sources</title>

     

       8
       +
       

     

       9
       +
       <para>By default, NixOS’s <command>nixos-rebuild</command> command

     

       10
       +
       uses the NixOS and Nixpkgs sources provided by the

     

       11
       +
       <literal>nixos-unstable</literal> channel (kept in

     

       12
       +
       <filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>).

     

       13
       +
       To modify NixOS, however, you should check out the latest sources from

     

       14
       +
       Git.  This is done using the following command:

     

       15
       +
       

     

       16
       +
       <screen>

     

       17
       +
       $ nixos-checkout <replaceable>/my/sources</replaceable>

     

       18
       +
       </screen>

     

       19
       +
       

     

       20
       +
       or

     

       21
       +
       

     

       22
       +
       <screen>

     

       23
       +
       $ mkdir -p <replaceable>/my/sources</replaceable>

     

       24
       +
       $ cd <replaceable>/my/sources</replaceable>

     

       25
       +
       $ nix-env -i git

     

       26
       +
       $ git clone git://github.com/NixOS/nixpkgs.git

     

       27
       +
       </screen>

     

       28
       +
       

     

       29
       +
       This will check out the latest NixOS sources to

     

       30
       +
       <filename><replaceable>/my/sources</replaceable>/nixpkgs/nixos</filename>

     

       31
       +
       and the Nixpkgs sources to

     

       32
       +
       <filename><replaceable>/my/sources</replaceable>/nixpkgs</filename>.

     

       33
       +
       (The NixOS source tree lives in a subdirectory of the Nixpkgs

     

       34
       +
       repository.)</para>

     

       35
       +
       

     

       36
       +
       <para>It’s often inconvenient to develop directly on the master

     

       37
       +
       branch, since if somebody has just committed (say) a change to GCC,

     

       38
       +
       then the binary cache may not have caught up yet and you’ll have to

     

       39
       +
       rebuild everything from source. So you may want to create a local

     

       40
       +
       branch based on your current NixOS version:

     

       41
       +
       

     

       42
       +
       <screen>

     

       43
       +
       $ nixos-version

     

       44
       +
       14.04.273.ea1952b (Baboon)

     

       45
       +
       

     

       46
       +
       $ git checkout -b local ea1952b

     

       47
       +
       </screen>

     

       48
       +
       

     

       49
       +
       Or, to base your local branch on the latest version available in the

     

       50
       +
       NixOS channel:

     

       51
       +
       

     

       52
       +
       <screen>

     

       53
       +
       $ curl -sI http://nixos.org/channels/nixos-unstable/ | grep Location

     

       54
       +
       Location: http://releases.nixos.org/nixos/unstable/nixos-14.10pre43986.acaf4a6/

     

       55
       +
       

     

       56
       +
       $ git checkout -b local acaf4a6

     

       57
       +
       </screen>

     

       58
       +
       

     

       59
       +
       You can then use <command>git rebase</command> to sync your local

     

       60
       +
       branch with the upstream branch, and use <command>git

     

       61
       +
       cherry-pick</command> to copy commits from your local branch to the

     

       62
       +
       upstream branch.</para>

     

       63
       +
       

     

       64
       +
       <para>If you want to rebuild your system using your (modified)

     

       65
       +
       sources, you need to tell <command>nixos-rebuild</command> about them

     

       66
       +
       using the <option>-I</option> flag:

     

       67
       +
       

     

       68
       +
       <screen>

     

       69
       +
       $ nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs

     

       70
       +
       </screen>

     

       71
       +
       

     

       72
       +
       </para>

     

       73
       +
       

     

       74
       +
       <para>If you want <command>nix-env</command> to use the expressions in

     

       75
       +
       <replaceable>/my/sources</replaceable>, use <command>nix-env -f

     

       76
       +
       <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change

     

       77
       +
       the default by adding a symlink in

     

       78
       +
       <filename>~/.nix-defexpr</filename>:

     

       79
       +
       

     

       80
       +
       <screen>

     

       81
       +
       $ ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs

     

       82
       +
       </screen>

     

       83
       +
       

     

       84
       +
       You may want to delete the symlink

     

       85
       +
       <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s

     

       86
       +
       NixOS channel from clashing with your own tree.</para>

     

       87
       +
       

     

       88
       +
       <!-- FIXME: not sure what this means.

     

       89
       +
       <para>You should not pass the base directory

     

       90
       +
       <filename><replaceable>/my/sources</replaceable></filename>

     

       91
       +
       to <command>nix-env</command>, as it will break after interpreting expressions

     

       92
       +
       in <filename>nixos/</filename> as packages.</para>

     

       93
       +
       -->

     

       94
       +
       

     

       95
       +
       </chapter>

+27

nixos/doc/manual/development/testing-installer.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="ch-testing-installer">

     

       6
       +
       

     

       7
       +
       <title>Testing the Installer</title>

     

       8
       +
       

     

       9
       +
       <para>Building, burning, and booting from an installation CD is rather

     

       10
       +
       tedious, so here is a quick way to see if the installer works

     

       11
       +
       properly:

     

       12
       +
       

     

       13
       +
       <screen>

     

       14
       +
       $ nix-build -A config.system.build.nixos-install

     

       15
       +
       $ mount -t tmpfs none /mnt

     

       16
       +
       $ ./result/bin/nixos-install</screen>

     

       17
       +
       

     

       18
       +
       To start a login shell in the new NixOS installation in

     

       19
       +
       <filename>/mnt</filename>:

     

       20
       +
       

     

       21
       +
       <screen>

     

       22
       +
       $ ./result/bin/nixos-install --chroot

     

       23
       +
       </screen>

     

       24
       +
       

     

       25
       +
       </para>

     

       26
       +
       

     

       27
       +
       </chapter>

+175

nixos/doc/manual/development/writing-modules.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-writing-modules">

     

       6
       +
       

     

       7
       +
       <title>Writing NixOS Modules</title>

     

       8
       +
       

     

       9
       +
       <para>NixOS has a modular system for declarative configuration.  This

     

       10
       +
       system combines multiple <emphasis>modules</emphasis> to produce the

     

       11
       +
       full system configuration.  One of the modules that constitute the

     

       12
       +
       configuration is <filename>/etc/nixos/configuration.nix</filename>.

     

       13
       +
       Most of the others live in the <link

     

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

     

       15
       +
       subdirectory of the Nixpkgs tree.</para>

     

       16
       +
       

     

       17
       +
       <para>Each NixOS module is a file that handles one logical aspect of

     

       18
       +
       the configuration, such as a specific kind of hardware, a service, or

     

       19
       +
       network settings.  A module configuration does not have to handle

     

       20
       +
       everything from scratch; it can use the functionality provided by

     

       21
       +
       other modules for its implementation.  Thus a module can

     

       22
       +
       <emphasis>declare</emphasis> options that can be used by other

     

       23
       +
       modules, and conversely can <emphasis>define</emphasis> options

     

       24
       +
       provided by other modules in its own implementation.  For example, the

     

       25
       +
       module <link

     

       26
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix"><filename>pam.nix</filename></link>

     

       27
       +
       declares the option <option>security.pam.services</option> that allows

     

       28
       +
       other modules (e.g. <link

     

       29
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix"><filename>sshd.nix</filename></link>)

     

       30
       +
       to define PAM services; and it defines the option

     

       31
       +
       <option>environment.etc</option> (declared by <link

     

       32
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix"><filename>etc.nix</filename></link>)

     

       33
       +
       to cause files to be created in

     

       34
       +
       <filename>/etc/pam.d</filename>.</para>

     

       35
       +
       

     

       36
       +
       <para xml:id="para-module-syn">In <xref

     

       37
       +
       linkend="sec-configuration-syntax"/>, we saw the following structure

     

       38
       +
       of NixOS modules:

     

       39
       +
       

     

       40
       +
       <programlisting>

     

       41
       +
       { config, pkgs, ... }:

     

       42
       +
       

     

       43
       +
       { <replaceable>option definitions</replaceable>

     

       44
       +
       }

     

       45
       +
       </programlisting>

     

       46
       +
       

     

       47
       +
       This is actually an <emphasis>abbreviated</emphasis> form of module

     

       48
       +
       that only defines options, but does not declare any.  The structure of

     

       49
       +
       full NixOS modules is shown in <xref linkend='ex-module-syntax' />.</para>

     

       50
       +
       

     

       51
       +
       <example xml:id='ex-module-syntax'><title>Structure of NixOS Modules</title>

     

       52
       +
       <programlisting>

     

       53
       +
       { config, pkgs, ... }: <co xml:id='module-syntax-1' />

     

       54
       +
       

     

       55
       +
       {

     

       56
       +
         imports =

     

       57
       +
           [ <replaceable>paths of other modules</replaceable> <co xml:id='module-syntax-2' />

     

       58
       +
           ];

     

       59
       +
       

     

       60
       +
         options = {

     

       61
       +
           <replaceable>option declarations</replaceable> <co xml:id='module-syntax-3' />

     

       62
       +
         };

     

       63
       +
       

     

       64
       +
         config = {

     

       65
       +
           <replaceable>option definitions</replaceable> <co xml:id='module-syntax-4' />

     

       66
       +
         };

     

       67
       +
       }</programlisting>

     

       68
       +
       </example>

     

       69
       +
       

     

       70
       +
       <para>The meaning of each part is as follows.

     

       71
       +
       

     

       72
       +
       <calloutlist>

     

       73
       +
         <callout arearefs='module-syntax-1'>

     

       74
       +
           <para>This line makes the current Nix expression a function.  The

     

       75
       +
           variable <varname>pkgs</varname> contains Nixpkgs, while

     

       76
       +
           <varname>config</varname> contains the full system configuration.

     

       77
       +
           This line can be omitted if there is no reference to

     

       78
       +
           <varname>pkgs</varname> and <varname>config</varname> inside the

     

       79
       +
           module.</para>

     

       80
       +
         </callout>

     

       81
       +
       

     

       82
       +
         <callout arearefs='module-syntax-2'>

     

       83
       +
           <para>This list enumerates the paths to other NixOS modules that

     

       84
       +
           should be included in the evaluation of the system configuration.

     

       85
       +
           A default set of modules is defined in the file

     

       86
       +
           <filename>modules/module-list.nix</filename>.  These don't need to

     

       87
       +
           be added in the import list.</para>

     

       88
       +
         </callout>

     

       89
       +
       

     

       90
       +
         <callout arearefs='module-syntax-3'>

     

       91
       +
           <para>The attribute <varname>options</varname> is a nested set of

     

       92
       +
           <emphasis>option declarations</emphasis> (described below).</para>

     

       93
       +
         </callout>

     

       94
       +
       

     

       95
       +
         <callout arearefs='module-syntax-4'>

     

       96
       +
           <para>The attribute <varname>config</varname> is a nested set of

     

       97
       +
           <emphasis>option definitions</emphasis> (also described

     

       98
       +
           below).</para>

     

       99
       +
         </callout>

     

       100
       +
       </calloutlist>

     

       101
       +
       

     

       102
       +
       </para>

     

       103
       +
       

     

       104
       +
       <para><xref linkend='locate-example' /> shows a module that handles

     

       105
       +
       the regular update of the “locate” database, an index of all files in

     

       106
       +
       the file system.  This module declares two options that can be defined

     

       107
       +
       by other modules (typically the user’s

     

       108
       +
       <filename>configuration.nix</filename>):

     

       109
       +
       <option>services.locate.enable</option> (whether the database should

     

       110
       +
       be updated) and <option>services.locate.period</option> (when the

     

       111
       +
       update should be done).  It implements its functionality by defining

     

       112
       +
       two options declared by other modules:

     

       113
       +
       <option>systemd.services</option> (the set of all systemd services)

     

       114
       +
       and <option>services.cron.systemCronJobs</option> (the list of

     

       115
       +
       commands to be executed periodically by <command>cron</command>).</para>

     

       116
       +
       

     

       117
       +
       <example xml:id='locate-example'><title>NixOS Module for the “locate” Service</title>

     

       118
       +
       <programlisting>

     

       119
       +
       { config, lib, pkgs, ... }:

     

       120
       +
       

     

       121
       +
       with lib;

     

       122
       +
       

     

       123
       +
       let locatedb = "/var/cache/locatedb"; in

     

       124
       +
       

     

       125
       +
       {

     

       126
       +
         options = {

     

       127
       +
       

     

       128
       +
           services.locate = {

     

       129
       +
       

     

       130
       +
             enable = mkOption {

     

       131
       +
               type = types.bool;

     

       132
       +
               default = false;

     

       133
       +
               description = ''

     

       134
       +
                 If enabled, NixOS will periodically update the database of

     

       135
       +
                 files used by the <command>locate</command> command.

     

       136
       +
               '';

     

       137
       +
             };

     

       138
       +
       

     

       139
       +
             period = mkOption {

     

       140
       +
               type = types.str;

     

       141
       +
               default = "15 02 * * *";

     

       142
       +
               description = ''

     

       143
       +
                 This option defines (in the format used by cron) when the

     

       144
       +
                 locate database is updated.  The default is to update at

     

       145
       +
                 02:15 at night every day.

     

       146
       +
               '';

     

       147
       +
             };

     

       148
       +
       

     

       149
       +
           };

     

       150
       +
       

     

       151
       +
         };

     

       152
       +
       

     

       153
       +
         config = {

     

       154
       +
       

     

       155
       +
           systemd.services.update-locatedb =

     

       156
       +
             { description = "Update Locate Database";

     

       157
       +
               path  = [ pkgs.su ];

     

       158
       +
               script =

     

       159
       +
                 ''

     

       160
       +
                   mkdir -m 0755 -p $(dirname ${locatedb})

     

       161
       +
                   exec updatedb --localuser=nobody --output=${locatedb} --prunepaths='/tmp /var/tmp /media /run'

     

       162
       +
                 '';

     

       163
       +
             };

     

       164
       +
       

     

       165
       +
           services.cron.systemCronJobs = optional config.services.locate.enable

     

       166
       +
             "${config.services.locate.period} root ${config.systemd.package}/bin/systemctl start update-locatedb.service";

     

       167
       +
       

     

       168
       +
         };

     

       169
       +
       }</programlisting>

     

       170
       +
       </example>

     

       171
       +
       

     

       172
       +
       <xi:include href="option-declarations.xml" />

     

       173
       +
       <xi:include href="option-def.xml" />

     

       174
       +
       

     

       175
       +
       </chapter>

+251

nixos/doc/manual/development/writing-nixos-tests.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-writing-nixos-tests">

     

       6
       +
       

     

       7
       +
       <title>Writing Tests</title>

     

       8
       +
       

     

       9
       +
       <para>A NixOS test is a Nix expression that has the following structure:

     

       10
       +
       

     

       11
       +
       <programlisting>

     

       12
       +
       import ./make-test.nix {

     

       13
       +
       

     

       14
       +
         # Either the configuration of a single machine:

     

       15
       +
         machine =

     

       16
       +
           { config, pkgs, ... }:

     

       17
       +
           { <replaceable>configuration…</replaceable>

     

       18
       +
           };

     

       19
       +
       

     

       20
       +
         # Or a set of machines:

     

       21
       +
         nodes =

     

       22
       +
           { <replaceable>machine1</replaceable> =

     

       23
       +
               { config, pkgs, ... }: { <replaceable>…</replaceable> };

     

       24
       +
             <replaceable>machine2</replaceable> =

     

       25
       +
               { config, pkgs, ... }: { <replaceable>…</replaceable> };

     

       26
       +
             …

     

       27
       +
           };

     

       28
       +
       

     

       29
       +
         testScript =

     

       30
       +
           ''

     

       31
       +
             <replaceable>Perl code…</replaceable>

     

       32
       +
           '';

     

       33
       +
       }

     

       34
       +
       </programlisting>

     

       35
       +
       

     

       36
       +
       The attribute <literal>testScript</literal> is a bit of Perl code that

     

       37
       +
       executes the test (described below). During the test, it will start

     

       38
       +
       one or more virtual machines, the configuration of which is described

     

       39
       +
       by the attribute <literal>machine</literal> (if you need only one

     

       40
       +
       machine in your test) or by the attribute <literal>nodes</literal> (if

     

       41
       +
       you need multiple machines). For instance, <filename

     

       42
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>

     

       43
       +
       only needs a single machine to test whether users can log in on the

     

       44
       +
       virtual console, whether device ownership is correctly maintained when

     

       45
       +
       switching between consoles, and so on. On the other hand, <filename

     

       46
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs.nix">nfs.nix</filename>,

     

       47
       +
       which tests NFS client and server functionality in the Linux kernel

     

       48
       +
       (including whether locks are maintained across server crashes),

     

       49
       +
       requires three machines: a server and two clients.</para>

     

       50
       +
       

     

       51
       +
       <para>There are a few special NixOS configuration options for test

     

       52
       +
       VMs:

     

       53
       +
       

     

       54
       +
       <!-- FIXME: would be nice to generate this automatically. -->

     

       55
       +
       

     

       56
       +
       <variablelist>

     

       57
       +
       

     

       58
       +
         <varlistentry>

     

       59
       +
           <term><option>virtualisation.memorySize</option></term>

     

       60
       +
           <listitem><para>The memory of the VM in

     

       61
       +
           megabytes.</para></listitem>

     

       62
       +
         </varlistentry>

     

       63
       +
       

     

       64
       +
         <varlistentry>

     

       65
       +
           <term><option>virtualisation.vlans</option></term>

     

       66
       +
           <listitem><para>The virtual networks to which the VM is

     

       67
       +
           connected. See <filename

     

       68
       +
           xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nat.nix">nat.nix</filename>

     

       69
       +
           for an example.</para></listitem>

     

       70
       +
         </varlistentry>

     

       71
       +
       

     

       72
       +
         <varlistentry>

     

       73
       +
           <term><option>virtualisation.writableStore</option></term>

     

       74
       +
           <listitem><para>By default, the Nix store in the VM is not

     

       75
       +
           writable. If you enable this option, a writable union file system

     

       76
       +
           is mounted on top of the Nix store to make it appear

     

       77
       +
           writable. This is necessary for tests that run Nix operations that

     

       78
       +
           modify the store.</para></listitem>

     

       79
       +
         </varlistentry>

     

       80
       +
       

     

       81
       +
       </variablelist>

     

       82
       +
       

     

       83
       +
       For more options, see the module <filename

     

       84
       +
       xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix">qemu-vm.nix</filename>.</para>

     

       85
       +
       

     

       86
       +
       <para>The test script is a sequence of Perl statements that perform

     

       87
       +
       various actions, such as starting VMs, executing commands in the VMs,

     

       88
       +
       and so on. Each virtual machine is represented as an object stored in

     

       89
       +
       the variable <literal>$<replaceable>name</replaceable></literal>,

     

       90
       +
       where <replaceable>name</replaceable> is the identifier of the machine

     

       91
       +
       (which is just <literal>machine</literal> if you didn’t specify

     

       92
       +
       multiple machines using the <literal>nodes</literal> attribute). For

     

       93
       +
       instance, the following starts the machine, waits until it has

     

       94
       +
       finished booting, then executes a command and checks that the output

     

       95
       +
       is more-or-less correct:

     

       96
       +
       

     

       97
       +
       <programlisting>

     

       98
       +
       $machine->start;

     

       99
       +
       $machine->waitForUnit("default.target");

     

       100
       +
       $machine->succeed("uname") =~ /Linux/;

     

       101
       +
       </programlisting>

     

       102
       +
       

     

       103
       +
       The first line is actually unnecessary; machines are implicitly

     

       104
       +
       started when you first execute an action on them (such as

     

       105
       +
       <literal>waitForUnit</literal> or <literal>succeed</literal>). If you

     

       106
       +
       have multiple machines, you can speed up the test by starting them in

     

       107
       +
       parallel:

     

       108
       +
       

     

       109
       +
       <programlisting>

     

       110
       +
       startAll;

     

       111
       +
       </programlisting>

     

       112
       +
       

     

       113
       +
       </para>

     

       114
       +
       

     

       115
       +
       <para>The following methods are available on machine objects:

     

       116
       +
       

     

       117
       +
       <variablelist>

     

       118
       +
       

     

       119
       +
         <varlistentry>

     

       120
       +
           <term><methodname>start</methodname></term>

     

       121
       +
           <listitem><para>Start the virtual machine. This method is

     

       122
       +
           asynchronous — it does not wait for the machine to finish

     

       123
       +
           booting.</para></listitem>

     

       124
       +
         </varlistentry>

     

       125
       +
       

     

       126
       +
         <varlistentry>

     

       127
       +
           <term><methodname>shutdown</methodname></term>

     

       128
       +
           <listitem><para>Shut down the machine, waiting for the VM to

     

       129
       +
           exit.</para></listitem>

     

       130
       +
         </varlistentry>

     

       131
       +
       

     

       132
       +
         <varlistentry>

     

       133
       +
           <term><methodname>crash</methodname></term>

     

       134
       +
           <listitem><para>Simulate a sudden power failure, by telling the VM

     

       135
       +
           to exit immediately.</para></listitem>

     

       136
       +
         </varlistentry>

     

       137
       +
       

     

       138
       +
         <varlistentry>

     

       139
       +
           <term><methodname>block</methodname></term>

     

       140
       +
           <listitem><para>Simulate unplugging the Ethernet cable that

     

       141
       +
           connects the machine to the other machines.</para></listitem>

     

       142
       +
         </varlistentry>

     

       143
       +
       

     

       144
       +
         <varlistentry>

     

       145
       +
           <term><methodname>unblock</methodname></term>

     

       146
       +
           <listitem><para>Undo the effect of

     

       147
       +
           <methodname>block</methodname>.</para></listitem>

     

       148
       +
         </varlistentry>

     

       149
       +
       

     

       150
       +
         <varlistentry>

     

       151
       +
           <term><methodname>screenshot</methodname></term>

     

       152
       +
           <listitem><para>Take a picture of the display of the virtual

     

       153
       +
           machine, in PNG format. The screenshot is linked from the HTML

     

       154
       +
           log.</para></listitem>

     

       155
       +
         </varlistentry>

     

       156
       +
       

     

       157
       +
         <varlistentry>

     

       158
       +
           <term><methodname>sendMonitorCommand</methodname></term>

     

       159
       +
           <listitem><para>Send a command to the QEMU monitor. This is rarely

     

       160
       +
           used, but allows doing stuff such as attaching virtual USB disks

     

       161
       +
           to a running machine.</para></listitem>

     

       162
       +
         </varlistentry>

     

       163
       +
       

     

       164
       +
         <varlistentry>

     

       165
       +
           <term><methodname>sendKeys</methodname></term>

     

       166
       +
           <listitem><para>Simulate pressing keys on the virtual keyboard,

     

       167
       +
           e.g., <literal>sendKeys("ctrl-alt-delete")</literal>.</para></listitem>

     

       168
       +
         </varlistentry>

     

       169
       +
       

     

       170
       +
         <varlistentry>

     

       171
       +
           <term><methodname>sendChars</methodname></term>

     

       172
       +
           <listitem><para>Simulate typing a sequence of characters on the

     

       173
       +
           virtual keyboard, e.g., <literal>sendKeys("foobar\n")</literal>

     

       174
       +
           will type the string <literal>foobar</literal> followed by the

     

       175
       +
           Enter key.</para></listitem>

     

       176
       +
         </varlistentry>

     

       177
       +
       

     

       178
       +
         <varlistentry>

     

       179
       +
           <term><methodname>execute</methodname></term>

     

       180
       +
           <listitem><para>Execute a shell command, returning a list

     

       181
       +
           <literal>(<replaceable>status</replaceable>,

     

       182
       +
           <replaceable>stdout</replaceable>)</literal>.</para></listitem>

     

       183
       +
         </varlistentry>

     

       184
       +
       

     

       185
       +
         <varlistentry>

     

       186
       +
           <term><methodname>succeed</methodname></term>

     

       187
       +
           <listitem><para>Execute a shell command, raising an exception if

     

       188
       +
           the exit status is not zero, otherwise returning the standard

     

       189
       +
           output.</para></listitem>

     

       190
       +
         </varlistentry>

     

       191
       +
       

     

       192
       +
         <varlistentry>

     

       193
       +
           <term><methodname>fail</methodname></term>

     

       194
       +
           <listitem><para>Like <methodname>succeed</methodname>, but raising

     

       195
       +
           an exception if the command returns a zero status.</para></listitem>

     

       196
       +
         </varlistentry>

     

       197
       +
       

     

       198
       +
         <varlistentry>

     

       199
       +
           <term><methodname>waitUntilSucceeds</methodname></term>

     

       200
       +
           <listitem><para>Repeat a shell command with 1-second intervals

     

       201
       +
           until it succeeds.</para></listitem>

     

       202
       +
         </varlistentry>

     

       203
       +
       

     

       204
       +
         <varlistentry>

     

       205
       +
           <term><methodname>waitUntilFails</methodname></term>

     

       206
       +
           <listitem><para>Repeat a shell command with 1-second intervals

     

       207
       +
           until it fails.</para></listitem>

     

       208
       +
         </varlistentry>

     

       209
       +
       

     

       210
       +
         <varlistentry>

     

       211
       +
           <term><methodname>waitForUnit</methodname></term>

     

       212
       +
           <listitem><para>Wait until the specified systemd unit has reached

     

       213
       +
           the “active” state.</para></listitem>

     

       214
       +
         </varlistentry>

     

       215
       +
       

     

       216
       +
         <varlistentry>

     

       217
       +
           <term><methodname>waitForFile</methodname></term>

     

       218
       +
           <listitem><para>Wait until the specified file

     

       219
       +
           exists.</para></listitem>

     

       220
       +
         </varlistentry>

     

       221
       +
       

     

       222
       +
         <varlistentry>

     

       223
       +
           <term><methodname>waitForOpenPort</methodname></term>

     

       224
       +
           <listitem><para>Wait until a process is listening on the given TCP

     

       225
       +
           port (on <literal>localhost</literal>, at least).</para></listitem>

     

       226
       +
         </varlistentry>

     

       227
       +
       

     

       228
       +
         <varlistentry>

     

       229
       +
           <term><methodname>waitForClosedPort</methodname></term>

     

       230
       +
           <listitem><para>Wait until nobody is listening on the given TCP

     

       231
       +
           port.</para></listitem>

     

       232
       +
         </varlistentry>

     

       233
       +
       

     

       234
       +
         <varlistentry>

     

       235
       +
           <term><methodname>waitForX</methodname></term>

     

       236
       +
           <listitem><para>Wait until the X11 server is accepting

     

       237
       +
           connections.</para></listitem>

     

       238
       +
         </varlistentry>

     

       239
       +
       

     

       240
       +
         <varlistentry>

     

       241
       +
           <term><methodname>waitForWindow</methodname></term>

     

       242
       +
           <listitem><para>Wait until an X11 window has appeared whose name

     

       243
       +
           matches the given regular expression, e.g.,

     

       244
       +
           <literal>waitForWindow(qr/Terminal/)</literal>.</para></listitem>

     

       245
       +
         </varlistentry>

     

       246
       +
       

     

       247
       +
       </variablelist>

     

       248
       +
       

     

       249
       +
       </para>

     

       250
       +
       

     

       251
       +
       </section>

-570

nixos/doc/manual/installation.xml

···

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

     

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

     

       3
       -
                xml:id="ch-installation">

     

       4
       -
       

     

       5
       -
       <title>Installing NixOS</title>

     

       6
       -
       

     

       7
       -
       

     

       8
       -
       <!--===============================================================-->

     

       9
       -
       

     

       10
       -
       <section xml:id="sec-obtaining">

     

       11
       -
       

     

       12
       -
       <title>Obtaining NixOS</title>

     

       13
       -
       

     

       14
       -
       <para>NixOS ISO images can be downloaded from the <link

     

       15
       -
       xlink:href="http://nixos.org/nixos/download.html">NixOS

     

       16
       -
       homepage</link>.  These can be burned onto a CD.  It is also possible

     

       17
       -
       to copy them onto a USB stick and install NixOS from there.  For

     

       18
       -
       details, see the <link

     

       19
       -
       xlink:href="https://nixos.org/wiki/Installing_NixOS_from_a_USB_stick">NixOS

     

       20
       -
       Wiki</link>.</para>

     

       21
       -
       

     

       22
       -
       <para>As an alternative to installing NixOS yourself, you can get a

     

       23
       -
       running NixOS system through several other means:

     

       24
       -
       

     

       25
       -
       <itemizedlist>

     

       26
       -
         <listitem>

     

       27
       -
           <para>Using virtual appliances in Open Virtualization Format (OVF)

     

       28
       -
           that can be imported into VirtualBox.  These are available from

     

       29
       -
           the <link xlink:href="http://nixos.org/nixos/download.html">NixOS

     

       30
       -
           homepage</link>.</para>

     

       31
       -
         </listitem>

     

       32
       -
         <listitem>

     

       33
       -
           <para>Using AMIs for Amazon’s EC2.  To find one for your region

     

       34
       -
           and instance type, please refer to the <link

     

       35
       -
           xlink:href="https://github.com/NixOS/nixops/blob/master/nix/ec2-amis.nix">list

     

       36
       -
           of most recent AMIs</link>.</para>

     

       37
       -
         </listitem>

     

       38
       -
         <listitem>

     

       39
       -
           <para>Using NixOps, the NixOS-based cloud deployment tool, which

     

       40
       -
           allows you to provision VirtualBox and EC2 NixOS instances from

     

       41
       -
           declarative specifications.  Check out the <link

     

       42
       -
           xlink:href="https://github.com/NixOS/nixops">NixOps

     

       43
       -
           homepage</link> for details.</para>

     

       44
       -
         </listitem>

     

       45
       -
       </itemizedlist>

     

       46
       -
       

     

       47
       -
       </para>

     

       48
       -
       

     

       49
       -
       </section>

     

       50
       -
       

     

       51
       -
       

     

       52
       -
       <!--===============================================================-->

     

       53
       -
       

     

       54
       -
       <section xml:id="sec-installation">

     

       55
       -
       

     

       56
       -
       <title>Installation</title>

     

       57
       -
       

     

       58
       -
       <orderedlist>

     

       59
       -
       

     

       60
       -
         <listitem><para>Boot from the CD.</para></listitem>

     

       61
       -
       

     

       62
       -
         <listitem><para>The CD contains a basic NixOS installation.  (It

     

       63
       -
         also contains Memtest86+, useful if you want to test new hardware.)

     

       64
       -
         When it’s finished booting, it should have detected most of your

     

       65
       -
         hardware and brought up networking (check

     

       66
       -
         <command>ifconfig</command>).  Networking is necessary for the

     

       67
       -
         installer, since it will download lots of stuff (such as source

     

       68
       -
         tarballs or Nixpkgs channel binaries).  It’s best if you have a DHCP

     

       69
       -
         server on your network.  Otherwise configure networking manually

     

       70
       -
         using <command>ifconfig</command>.</para></listitem>

     

       71
       -
       

     

       72
       -
         <listitem><para>The NixOS manual is available on virtual console 8

     

       73
       -
         (press Alt+F8 to access).</para></listitem>

     

       74
       -
       

     

       75
       -
         <listitem><para>Login as <literal>root</literal> and the empty

     

       76
       -
         password.</para></listitem>

     

       77
       -
       

     

       78
       -
         <listitem><para>If you downloaded the graphical ISO image, you can

     

       79
       -
         run <command>start display-manager</command> to start KDE.</para></listitem>

     

       80
       -
       

     

       81
       -
         <listitem><para>The NixOS installer doesn’t do any partitioning or

     

       82
       -
         formatting yet, so you need to that yourself.  Use the following

     

       83
       -
         commands:

     

       84
       -
       

     

       85
       -
         <itemizedlist>

     

       86
       -
       

     

       87
       -
           <listitem><para>For partitioning:

     

       88
       -
           <command>fdisk</command>.</para></listitem>

     

       89
       -
       

     

       90
       -
           <listitem><para>For initialising Ext4 partitions:

     

       91
       -
           <command>mkfs.ext4</command>.  It is recommended that you assign a

     

       92
       -
           unique symbolic label to the file system using the option

     

       93
       -
           <option>-L <replaceable>label</replaceable></option>, since this

     

       94
       -
           makes the file system configuration independent from device

     

       95
       -
           changes.  For example:

     

       96
       -
       

     

       97
       -
       <screen>

     

       98
       -
       $ mkfs.ext4 -L nixos /dev/sda1</screen>

     

       99
       -
       

     

       100
       -
           </para></listitem>

     

       101
       -
       

     

       102
       -
           <listitem><para>For creating swap partitions:

     

       103
       -
           <command>mkswap</command>.  Again it’s recommended to assign a

     

       104
       -
           label to the swap partition: <option>-L

     

       105
       -
           <replaceable>label</replaceable></option>.</para></listitem>

     

       106
       -
       

     

       107
       -
           <listitem><para>For creating LVM volumes, the LVM commands, e.g.,

     

       108
       -
       

     

       109
       -
       <screen>

     

       110
       -
       $ pvcreate /dev/sda1 /dev/sdb1

     

       111
       -
       $ vgcreate MyVolGroup /dev/sda1 /dev/sdb1

     

       112
       -
       $ lvcreate --size 2G --name bigdisk MyVolGroup

     

       113
       -
       $ lvcreate --size 1G --name smalldisk MyVolGroup</screen>

     

       114
       -
       

     

       115
       -
           </para></listitem>

     

       116
       -
       

     

       117
       -
           <listitem><para>For creating software RAID devices, use

     

       118
       -
           <command>mdadm</command>.</para></listitem>

     

       119
       -
       

     

       120
       -
         </itemizedlist>

     

       121
       -
       

     

       122
       -
         </para></listitem>

     

       123
       -
       

     

       124
       -
         <listitem><para>Mount the target file system on which NixOS should

     

       125
       -
         be installed on <filename>/mnt</filename>, e.g.

     

       126
       -
       

     

       127
       -
       <screen>

     

       128
       -
       $ mount /dev/disk/by-label/nixos /mnt

     

       129
       -
       </screen>

     

       130
       -
       

     

       131
       -
         </para></listitem>

     

       132
       -
       

     

       133
       -
         <listitem><para>If your machine has a limited amount of memory, you

     

       134
       -
         may want to activate swap devices now (<command>swapon

     

       135
       -
         <replaceable>device</replaceable></command>).  The installer (or

     

       136
       -
         rather, the build actions that it may spawn) may need quite a bit of

     

       137
       -
         RAM, depending on your configuration.</para></listitem>

     

       138
       -
       

     

       139
       -
         <listitem>

     

       140
       -
       

     

       141
       -
           <para>You now need to create a file

     

       142
       -
           <filename>/mnt/etc/nixos/configuration.nix</filename> that

     

       143
       -
           specifies the intended configuration of the system.  This is

     

       144
       -
           because NixOS has a <emphasis>declarative</emphasis> configuration

     

       145
       -
           model: you create or edit a description of the desired

     

       146
       -
           configuration of your system, and then NixOS takes care of making

     

       147
       -
           it happen.  The syntax of the NixOS configuration file is

     

       148
       -
           described in <xref linkend="sec-configuration-syntax"/>, while a

     

       149
       -
           list of available configuration options appears in <xref

     

       150
       -
           linkend="ch-options"/>.  A minimal example is shown in <xref

     

       151
       -
           linkend="ex-config"/>.</para>

     

       152
       -
       

     

       153
       -
           <para>The command <command>nixos-generate-config</command> can

     

       154
       -
           generate an initial configuration file for you:

     

       155
       -
       

     

       156
       -
       <screen>

     

       157
       -
       $ nixos-generate-config --root /mnt</screen>

     

       158
       -
       

     

       159
       -
           You should then edit

     

       160
       -
           <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your

     

       161
       -
           needs:

     

       162
       -
       

     

       163
       -
       <screen>

     

       164
       -
       $ nano /mnt/etc/nixos/configuration.nix

     

       165
       -
       </screen>

     

       166
       -
       

     

       167
       -
           The <command>vim</command> text editor is also available.</para>

     

       168
       -
       

     

       169
       -
           <para>You <emphasis>must</emphasis> set the option

     

       170
       -
           <option>boot.loader.grub.device</option> to specify on which disk

     

       171
       -
           the GRUB boot loader is to be installed.  Without it, NixOS cannot

     

       172
       -
           boot.</para>

     

       173
       -
       

     

       174
       -
           <para>Another critical option is <option>fileSystems</option>,

     

       175
       -
           specifying the file systems that need to be mounted by NixOS.

     

       176
       -
           However, you typically don’t need to set it yourself, because

     

       177
       -
           <command>nixos-generate-config</command> sets it automatically in

     

       178
       -
           <filename>/mnt/etc/nixos/hardware-configuration.nix</filename>

     

       179
       -
           from your currently mounted file systems.  (The configuration file

     

       180
       -
           <filename>hardware-configuration.nix</filename> is included from

     

       181
       -
           <filename>configuration.nix</filename> and will be overwritten by

     

       182
       -
           future invocations of <command>nixos-generate-config</command>;

     

       183
       -
           thus, you generally should not modify it.)</para>

     

       184
       -
       

     

       185
       -
           <note><para>Depending on your hardware configuration or type of

     

       186
       -
           file system, you may need to set the option

     

       187
       -
           <option>boot.initrd.kernelModules</option> to include the kernel

     

       188
       -
           modules that are necessary for mounting the root file system,

     

       189
       -
           otherwise the installed system will not be able to boot.  (If this

     

       190
       -
           happens, boot from the CD again, mount the target file system on

     

       191
       -
           <filename>/mnt</filename>, fix

     

       192
       -
           <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun

     

       193
       -
           <filename>nixos-install</filename>.)  In most cases,

     

       194
       -
           <command>nixos-generate-config</command> will figure out the

     

       195
       -
           required modules.</para></note>

     

       196
       -
       

     

       197
       -
           <para>Examples of real-world NixOS configuration files can be

     

       198
       -
           found at <link

     

       199
       -
           xlink:href="https://nixos.org/repos/nix/configurations/trunk/"/>.</para>

     

       200
       -
       

     

       201
       -
         </listitem>

     

       202
       -
       

     

       203
       -
         <listitem><para>Do the installation:

     

       204
       -
       

     

       205
       -
       <screen>

     

       206
       -
       $ nixos-install</screen>

     

       207
       -
       

     

       208
       -
           Cross fingers.  If this fails due to a temporary problem (such as

     

       209
       -
           a network issue while downloading binaries from the NixOS binary

     

       210
       -
           cache), you can just re-run <command>nixos-install</command>.

     

       211
       -
           Otherwise, fix your <filename>configuration.nix</filename> and

     

       212
       -
           then re-run <command>nixos-install</command>.</para>

     

       213
       -
       

     

       214
       -
           <para>As the last step, <command>nixos-install</command> will ask

     

       215
       -
           you to set the password for the <literal>root</literal> user, e.g.

     

       216
       -
       

     

       217
       -
       <screen>

     

       218
       -
       setting root password...

     

       219
       -
       Enter new UNIX password: ***

     

       220
       -
       Retype new UNIX password: ***

     

       221
       -
       </screen>

     

       222
       -
       

     

       223
       -
           </para>

     

       224
       -
       

     

       225
       -
         </listitem>

     

       226
       -
       

     

       227
       -
         <listitem><para>If everything went well:

     

       228
       -
       

     

       229
       -
       <screen>

     

       230
       -
       $ reboot</screen>

     

       231
       -
       

     

       232
       -
         </para></listitem>

     

       233
       -
       

     

       234
       -
         <listitem>

     

       235
       -
       

     

       236
       -
           <para>You should now be able to boot into the installed NixOS.

     

       237
       -
           The GRUB boot menu shows a list of <emphasis>available

     

       238
       -
           configurations</emphasis> (initially just one).  Every time you

     

       239
       -
           change the NixOS configuration (see <xref

     

       240
       -
           linkend="sec-changing-config" />), a new item appears in the menu.

     

       241
       -
           This allows you to easily roll back to another configuration if

     

       242
       -
           something goes wrong.</para>

     

       243
       -
       

     

       244
       -
           <para>You should log in and change the <literal>root</literal>

     

       245
       -
           password with <command>passwd</command>.</para>

     

       246
       -
       

     

       247
       -
           <para>You’ll probably want to create some user accounts as well,

     

       248
       -
           which can be done with <command>useradd</command>:

     

       249
       -
       

     

       250
       -
       <screen>

     

       251
       -
       $ useradd -c 'Eelco Dolstra' -m eelco

     

       252
       -
       $ passwd eelco</screen>

     

       253
       -
       

     

       254
       -
           </para>

     

       255
       -
       

     

       256
       -
           <para>You may also want to install some software.  For instance,

     

       257
       -
       

     

       258
       -
       <screen>

     

       259
       -
       $ nix-env -qa \*</screen>

     

       260
       -
       

     

       261
       -
           shows what packages are available, and

     

       262
       -
       

     

       263
       -
       <screen>

     

       264
       -
       $ nix-env -i w3m</screen>

     

       265
       -
       

     

       266
       -
           install the <literal>w3m</literal> browser.</para>

     

       267
       -
       

     

       268
       -
         </listitem>

     

       269
       -
       

     

       270
       -
       </orderedlist>

     

       271
       -
       

     

       272
       -
       <para>To summarise, <xref linkend="ex-install-sequence" /> shows a

     

       273
       -
       typical sequence of commands for installing NixOS on an empty hard

     

       274
       -
       drive (here <filename>/dev/sda</filename>).  <xref linkend="ex-config"

     

       275
       -
       /> shows a corresponding configuration Nix expression.</para>

     

       276
       -
       

     

       277
       -
       <example xml:id='ex-install-sequence'><title>Commands for installing NixOS on <filename>/dev/sda</filename></title>

     

       278
       -
       <screen>

     

       279
       -
       $ fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>

     

       280
       -
       $ mkfs.ext4 -L nixos /dev/sda1

     

       281
       -
       $ mkswap -L swap /dev/sda2

     

       282
       -
       $ swapon /dev/sda2

     

       283
       -
       $ mount /dev/disk/by-label/nixos /mnt

     

       284
       -
       $ nixos-generate-config --root /mnt

     

       285
       -
       $ nano /mnt/etc/nixos/configuration.nix

     

       286
       -
       $ nixos-install

     

       287
       -
       $ reboot</screen>

     

       288
       -
       </example>

     

       289
       -
       

     

       290
       -
       <example xml:id='ex-config'><title>NixOS configuration</title>

     

       291
       -
       <screen>

     

       292
       -
       { config, pkgs, ... }:

     

       293
       -
       

     

       294
       -
       {

     

       295
       -
         imports =

     

       296
       -
           [ # Include the results of the hardware scan.

     

       297
       -
             ./hardware-configuration.nix

     

       298
       -
           ];

     

       299
       -
       

     

       300
       -
         boot.loader.grub.device = "/dev/sda";

     

       301
       -
       

     

       302
       -
         # Note: setting fileSystems is generally not

     

       303
       -
         # necessary, since nixos-generate-config figures them out

     

       304
       -
         # automatically in hardware-configuration.nix.

     

       305
       -
         #fileSystems."/".device = "/dev/disk/by-label/nixos";

     

       306
       -
       

     

       307
       -
         # Enable the OpenSSH server.

     

       308
       -
         services.sshd.enable = true;

     

       309
       -
       }</screen>

     

       310
       -
       </example>

     

       311
       -
       

     

       312
       -
       <section xml:id="sec-uefi-installation">

     

       313
       -
       

     

       314
       -
       <title>UEFI Installation</title>

     

       315
       -
       

     

       316
       -
       <para>NixOS can also be installed on UEFI systems.  The procedure

     

       317
       -
       is by and large the same as a BIOS installation, with the following

     

       318
       -
       changes:

     

       319
       -
       

     

       320
       -
       <itemizedlist>

     

       321
       -
         <listitem>

     

       322
       -
           <para>You should boot the live CD in UEFI mode (consult your

     

       323
       -
           specific hardware's documentation for instructions). You may find

     

       324
       -
           the <link

     

       325
       -
           xlink:href="http://www.rodsbooks.com/refind">rEFInd

     

       326
       -
           boot manager</link> useful.</para>

     

       327
       -
         </listitem>

     

       328
       -
         <listitem>

     

       329
       -
           <para>Instead of <command>fdisk</command>, you should use

     

       330
       -
           <command>gdisk</command> to partition your disks. You will need to

     

       331
       -
           have a separate partition for <filename>/boot</filename> with

     

       332
       -
           partition code EF00, and it should be formatted as a

     

       333
       -
           <literal>vfat</literal> filesystem.</para>

     

       334
       -
         </listitem>

     

       335
       -
         <listitem>

     

       336
       -
           <para>You must set <option>boot.loader.gummiboot.enable</option> to

     

       337
       -
           <literal>true</literal>. <command>nixos-generate-config</command>

     

       338
       -
           should do this automatically for new configurations when booted in

     

       339
       -
           UEFI mode.</para>

     

       340
       -
         </listitem>

     

       341
       -
         <listitem>

     

       342
       -
           <para>After having mounted your installation partition to

     

       343
       -
           <code>/mnt</code>, you must mount the <code>boot</code> partition

     

       344
       -
           to <code>/mnt/boot</code>.</para>

     

       345
       -
         </listitem>

     

       346
       -
         <listitem>

     

       347
       -
           <para>You may want to look at the options starting with

     

       348
       -
           <option>boot.loader.efi</option> and <option>boot.loader.gummiboot</option>

     

       349
       -
           as well.</para>

     

       350
       -
         </listitem>

     

       351
       -
         <listitem>

     

       352
       -
           <para>To see console messages during early boot, add <literal>"fbcon"</literal>

     

       353
       -
           to your <option>boot.initrd.kernelModules</option>.</para>

     

       354
       -
         </listitem>

     

       355
       -
       </itemizedlist>

     

       356
       -
       </para>

     

       357
       -
       

     

       358
       -
       </section>

     

       359
       -
       

     

       360
       -
       <section>

     

       361
       -
       

     

       362
       -
       <title xml:id="sec-booting-from-usb">Booting from a USB stick</title>

     

       363
       -
       

     

       364
       -
       <para>For systems without CD drive, the NixOS livecd can be booted from

     

       365
       -
       a usb stick. For non-UEFI installations,

     

       366
       -
       <link xlink:href="http://unetbootin.sourceforge.net/">unetbootin</link>

     

       367
       -
       will work. For UEFI installations, you should mount the ISO, copy its contents

     

       368
       -
       verbatim to your drive, then either:

     

       369
       -
       

     

       370
       -
       <itemizedlist>

     

       371
       -
         <listitem>

     

       372
       -
           <para>Change the label of the disk partition to the label of the ISO

     

       373
       -
           (visible with the blkid command), or</para>

     

       374
       -
         </listitem>

     

       375
       -
         <listitem>

     

       376
       -
           <para>Edit <filename>loader/entries/nixos-livecd.conf</filename> on the drive

     

       377
       -
           and change the <literal>root=</literal> field in the <literal>options</literal>

     

       378
       -
           line to point to your drive (see the documentation on <literal>root=</literal>

     

       379
       -
           in <link xlink:href="https://www.kernel.org/doc/Documentation/kernel-parameters.txt">

     

       380
       -
           the kernel documentation</link> for more details).</para>

     

       381
       -
         </listitem>

     

       382
       -
       </itemizedlist>

     

       383
       -
       </para>

     

       384
       -
       </section>

     

       385
       -
       

     

       386
       -
       </section>

     

       387
       -
       

     

       388
       -
       

     

       389
       -
       <!--===============================================================-->

     

       390
       -
       

     

       391
       -
       <section xml:id="sec-changing-config">

     

       392
       -
       

     

       393
       -
       <title>Changing the configuration</title>

     

       394
       -
       

     

       395
       -
       <para>The file <filename>/etc/nixos/configuration.nix</filename>

     

       396
       -
       contains the current configuration of your machine.  Whenever you’ve

     

       397
       -
       changed something to that file, you should do

     

       398
       -
       

     

       399
       -
       <screen>

     

       400
       -
       $ nixos-rebuild switch</screen>

     

       401
       -
       

     

       402
       -
       to build the new configuration, make it the default configuration for

     

       403
       -
       booting, and try to realise the configuration in the running system

     

       404
       -
       (e.g., by restarting system services).</para>

     

       405
       -
       

     

       406
       -
       <warning><para>These commands must be executed as root, so you should

     

       407
       -
       either run them from a root shell or by prefixing them with

     

       408
       -
       <literal>sudo -i</literal>.</para></warning>

     

       409
       -
       

     

       410
       -
       <para>You can also do

     

       411
       -
       

     

       412
       -
       <screen>

     

       413
       -
       $ nixos-rebuild test</screen>

     

       414
       -
       

     

       415
       -
       to build the configuration and switch the running system to it, but

     

       416
       -
       without making it the boot default.  So if (say) the configuration

     

       417
       -
       locks up your machine, you can just reboot to get back to a working

     

       418
       -
       configuration.</para>

     

       419
       -
       

     

       420
       -
       <para>There is also

     

       421
       -
       

     

       422
       -
       <screen>

     

       423
       -
       $ nixos-rebuild boot</screen>

     

       424
       -
       

     

       425
       -
       to build the configuration and make it the boot default, but not

     

       426
       -
       switch to it now (so it will only take effect after the next

     

       427
       -
       reboot).</para>

     

       428
       -
       

     

       429
       -
       <para>You can make your configuration show up in a different submenu

     

       430
       -
       of the GRUB 2 boot screen by giving it a different <emphasis>profile

     

       431
       -
       name</emphasis>, e.g.

     

       432
       -
       

     

       433
       -
       <screen>

     

       434
       -
       $ nixos-rebuild switch -p test </screen>

     

       435
       -
       

     

       436
       -
       which causes the new configuration (and previous ones created using

     

       437
       -
       <literal>-p test</literal>) to show up in the GRUB submenu “NixOS -

     

       438
       -
       Profile 'test'”.  This can be useful to separate test configurations

     

       439
       -
       from “stable” configurations.</para>

     

       440
       -
       

     

       441
       -
       <para>Finally, you can do

     

       442
       -
       

     

       443
       -
       <screen>

     

       444
       -
       $ nixos-rebuild build</screen>

     

       445
       -
       

     

       446
       -
       to build the configuration but nothing more.  This is useful to see

     

       447
       -
       whether everything compiles cleanly.</para>

     

       448
       -
       

     

       449
       -
       <para>If you have a machine that supports hardware virtualisation, you

     

       450
       -
       can also test the new configuration in a sandbox by building and

     

       451
       -
       running a QEMU <emphasis>virtual machine</emphasis> that contains the

     

       452
       -
       desired configuration.  Just do

     

       453
       -
       

     

       454
       -
       <screen>

     

       455
       -
       $ nixos-rebuild build-vm

     

       456
       -
       $ ./result/bin/run-*-vm

     

       457
       -
       </screen>

     

       458
       -
       

     

       459
       -
       The VM does not have any data from your host system, so your existing

     

       460
       -
       user accounts and home directories will not be available.  You can

     

       461
       -
       forward ports on the host to the guest.  For instance, the following

     

       462
       -
       will forward host port 2222 to guest port 22 (SSH):

     

       463
       -
       

     

       464
       -
       <screen>

     

       465
       -
       $ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm

     

       466
       -
       </screen>

     

       467
       -
       

     

       468
       -
       allowing you to log in via SSH (assuming you have set the appropriate

     

       469
       -
       passwords or SSH authorized keys):

     

       470
       -
       

     

       471
       -
       <screen>

     

       472
       -
       $ ssh -p 2222 localhost

     

       473
       -
       </screen>

     

       474
       -
       

     

       475
       -
       </para>

     

       476
       -
       

     

       477
       -
       </section>

     

       478
       -
       

     

       479
       -
       

     

       480
       -
       <!--===============================================================-->

     

       481
       -
       

     

       482
       -
       <section xml:id="sec-upgrading">

     

       483
       -
       

     

       484
       -
       <title>Upgrading NixOS</title>

     

       485
       -
       

     

       486
       -
       <para>The best way to keep your NixOS installation up to date is to

     

       487
       -
       use one of the NixOS <emphasis>channels</emphasis>.  A channel is a

     

       488
       -
       Nix mechanism for distributing Nix expressions and associated

     

       489
       -
       binaries.  The NixOS channels are updated automatically from NixOS’s

     

       490
       -
       Git repository after certain tests have passed and all packages have

     

       491
       -
       been built.  These channels are:

     

       492
       -
       

     

       493
       -
       <itemizedlist>

     

       494
       -
         <listitem>

     

       495
       -
           <para>Stable channels, such as <literal

     

       496
       -
           xlink:href="http://nixos.org/channels/nixos-14.04">nixos-14.04</literal>.

     

       497
       -
           These only get conservative bug fixes and package upgrades.  For

     

       498
       -
           instance, a channel update may cause the Linux kernel on your

     

       499
       -
           system to be upgraded from 3.4.66 to 3.4.67 (a minor bug fix), but

     

       500
       -
           not from 3.4.<replaceable>x</replaceable> to

     

       501
       -
           3.11.<replaceable>x</replaceable> (a major change that has the

     

       502
       -
           potential to break things).  Stable channels are generally

     

       503
       -
           maintained until the next stable branch is created.</para>

     

       504
       -
         </listitem>

     

       505
       -
         <listitem>

     

       506
       -
           <para>The unstable channel, <literal

     

       507
       -
           xlink:href="http://nixos.org/channels/nixos-unstable">nixos-unstable</literal>.

     

       508
       -
           This corresponds to NixOS’s main development branch, and may thus

     

       509
       -
           see radical changes between channel updates.  It’s not recommended

     

       510
       -
           for production systems.</para>

     

       511
       -
         </listitem>

     

       512
       -
       </itemizedlist>

     

       513
       -
       

     

       514
       -
       To see what channels are available, go to <link

     

       515
       -
       xlink:href="http://nixos.org/channels"/>.  (Note that the URIs of the

     

       516
       -
       various channels redirect to a directory that contains the channel’s

     

       517
       -
       latest version and includes ISO images and VirtualBox

     

       518
       -
       appliances.)</para>

     

       519
       -
       

     

       520
       -
       <para>When you first install NixOS, you’re automatically subscribed to

     

       521
       -
       the NixOS channel that corresponds to your installation source.   For

     

       522
       -
       instance, if you installed from a 14.04 ISO, you will be subscribed to

     

       523
       -
       the <literal>nixos-14.04</literal> channel.  To see which NixOS

     

       524
       -
       channel you’re subscribed to, run the following as root:

     

       525
       -
       

     

       526
       -
       <screen>

     

       527
       -
       $ nix-channel --list | grep nixos

     

       528
       -
       nixos https://nixos.org/channels/nixos-unstable

     

       529
       -
       </screen>

     

       530
       -
       

     

       531
       -
       To switch to a different NixOS channel, do

     

       532
       -
       

     

       533
       -
       <screen>

     

       534
       -
       $ nix-channel --add http://nixos.org/channels/<replaceable>channel-name</replaceable> nixos

     

       535
       -
       </screen>

     

       536
       -
       

     

       537
       -
       (Be sure to include the <literal>nixos</literal> parameter at the

     

       538
       -
       end.)  For instance, to use the NixOS 14.04 stable channel:

     

       539
       -
       

     

       540
       -
       <screen>

     

       541
       -
       $ nix-channel --add http://nixos.org/channels/nixos-14.04 nixos

     

       542
       -
       </screen>

     

       543
       -
       

     

       544
       -
       But it you want to live on the bleeding edge:

     

       545
       -
       

     

       546
       -
       <screen>

     

       547
       -
       $ nix-channel --add http://nixos.org/channels/nixos-unstable nixos

     

       548
       -
       </screen>

     

       549
       -
       

     

       550
       -
       </para>

     

       551
       -
       

     

       552
       -
       <para>You can then upgrade NixOS to the latest version in your chosen

     

       553
       -
       channel by running

     

       554
       -
       

     

       555
       -
       <screen>

     

       556
       -
       $ nixos-rebuild switch --upgrade

     

       557
       -
       </screen>

     

       558
       -
       

     

       559
       -
       which is equivalent to the more verbose <literal>nix-channel --update

     

       560
       -
       nixos; nixos-rebuild switch</literal>.</para>

     

       561
       -
       

     

       562
       -
       <warning><para>It is generally safe to switch back and forth between

     

       563
       -
       channels.  The only exception is that a newer NixOS may also have a

     

       564
       -
       newer Nix version, which may involve an upgrade of Nix’s database

     

       565
       -
       schema.  This cannot be undone easily, so in that case you will not be

     

       566
       -
       able to go back to your original channel.</para></warning>

     

       567
       -
       

     

       568
       -
       </section>

     

       569
       -
       

     

       570
       -
       </chapter>

+90

nixos/doc/manual/installation/changing-config.xml

···

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

     

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

     

       3
       +
                version="5.0"

     

       4
       +
                xml:id="sec-changing-config">

     

       5
       +
       

     

       6
       +
       <title>Changing the Configuration</title>

     

       7
       +
       

     

       8
       +
       <para>The file <filename>/etc/nixos/configuration.nix</filename>

     

       9
       +
       contains the current configuration of your machine.  Whenever you’ve

     

       10
       +
       changed something to that file, you should do

     

       11
       +
       

     

       12
       +
       <screen>

     

       13
       +
       $ nixos-rebuild switch</screen>

     

       14
       +
       

     

       15
       +
       to build the new configuration, make it the default configuration for

     

       16
       +
       booting, and try to realise the configuration in the running system

     

       17
       +
       (e.g., by restarting system services).</para>

     

       18
       +
       

     

       19
       +
       <warning><para>These commands must be executed as root, so you should

     

       20
       +
       either run them from a root shell or by prefixing them with

     

       21
       +
       <literal>sudo -i</literal>.</para></warning>

     

       22
       +
       

     

       23
       +
       <para>You can also do

     

       24
       +
       

     

       25
       +
       <screen>

     

       26
       +
       $ nixos-rebuild test</screen>

     

       27
       +
       

     

       28
       +
       to build the configuration and switch the running system to it, but

     

       29
       +
       without making it the boot default.  So if (say) the configuration

     

       30
       +
       locks up your machine, you can just reboot to get back to a working

     

       31
       +
       configuration.</para>

     

       32
       +
       

     

       33
       +
       <para>There is also

     

       34
       +
       

     

       35
       +
       <screen>

     

       36
       +
       $ nixos-rebuild boot</screen>

     

       37
       +
       

     

       38
       +
       to build the configuration and make it the boot default, but not

     

       39
       +
       switch to it now (so it will only take effect after the next

     

       40
       +
       reboot).</para>

     

       41
       +
       

     

       42
       +
       <para>You can make your configuration show up in a different submenu

     

       43
       +
       of the GRUB 2 boot screen by giving it a different <emphasis>profile

     

       44
       +
       name</emphasis>, e.g.

     

       45
       +
       

     

       46
       +
       <screen>

     

       47
       +
       $ nixos-rebuild switch -p test </screen>

     

       48
       +
       

     

       49
       +
       which causes the new configuration (and previous ones created using

     

       50
       +
       <literal>-p test</literal>) to show up in the GRUB submenu “NixOS -

     

       51
       +
       Profile 'test'”.  This can be useful to separate test configurations

     

       52
       +
       from “stable” configurations.</para>

     

       53
       +
       

     

       54
       +
       <para>Finally, you can do

     

       55
       +
       

     

       56
       +
       <screen>

     

       57
       +
       $ nixos-rebuild build</screen>

     

       58
       +
       

     

       59
       +
       to build the configuration but nothing more.  This is useful to see

     

       60
       +
       whether everything compiles cleanly.</para>

     

       61
       +
       

     

       62
       +
       <para>If you have a machine that supports hardware virtualisation, you

     

       63
       +
       can also test the new configuration in a sandbox by building and

     

       64
       +
       running a QEMU <emphasis>virtual machine</emphasis> that contains the

     

       65
       +
       desired configuration.  Just do

     

       66
       +
       

     

       67
       +
       <screen>

     

       68
       +
       $ nixos-rebuild build-vm

     

       69
       +
       $ ./result/bin/run-*-vm

     

       70
       +
       </screen>

     

       71
       +
       

     

       72
       +
       The VM does not have any data from your host system, so your existing

     

       73
       +
       user accounts and home directories will not be available.  You can

     

       74
       +
       forward ports on the host to the guest.  For instance, the following

     

       75
       +
       will forward host port 2222 to guest port 22 (SSH):

     

       76
       +
       

     

       77
       +
       <screen>

     

       78
       +
       $ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm

     

       79
       +
       </screen>

     

       80
       +
       

     

       81
       +
       allowing you to log in via SSH (assuming you have set the appropriate

     

       82
       +
       passwords or SSH authorized keys):

     

       83
       +
       

     

       84
       +
       <screen>

     

       85
       +
       $ ssh -p 2222 localhost

     

       86
       +
       </screen>

     

       87
       +
       

     

       88
       +
       </para>

     

       89
       +
       

     

       90
       +
       </chapter>

+21

nixos/doc/manual/installation/installation.xml

···

       1
       +
       <part xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
             version="5.0"

     

       5
       +
             xml:id="ch-installation">

     

       6
       +
       

     

       7
       +
       <title>Installation</title>

     

       8
       +
       

     

       9
       +
       <partintro>

     

       10
       +
       

     

       11
       +
       <para>This section describes how to obtain, install, and configure

     

       12
       +
       NixOS for first-time use.</para>

     

       13
       +
       

     

       14
       +
       </partintro>

     

       15
       +
       

     

       16
       +
       <xi:include href="obtaining.xml" />

     

       17
       +
       <xi:include href="installing.xml" />

     

       18
       +
       <xi:include href="changing-config.xml" />

     

       19
       +
       <xi:include href="upgrading.xml" />

     

       20
       +
       

     

       21
       +
       </part>

+51

nixos/doc/manual/installation/installing-UEFI.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-uefi-installation">

     

       6
       +
       

     

       7
       +
       <title>UEFI Installation</title>

     

       8
       +
           

     

       9
       +
       <para>NixOS can also be installed on UEFI systems.  The procedure

     

       10
       +
       is by and large the same as a BIOS installation, with the following

     

       11
       +
       changes:

     

       12
       +
       

     

       13
       +
       <itemizedlist>

     

       14
       +
         <listitem>

     

       15
       +
           <para>You should boot the live CD in UEFI mode (consult your

     

       16
       +
           specific hardware's documentation for instructions). You may find

     

       17
       +
           the <link

     

       18
       +
           xlink:href="http://www.rodsbooks.com/refind">rEFInd

     

       19
       +
           boot manager</link> useful.</para>

     

       20
       +
         </listitem>

     

       21
       +
         <listitem>

     

       22
       +
           <para>Instead of <command>fdisk</command>, you should use

     

       23
       +
           <command>gdisk</command> to partition your disks. You will need to

     

       24
       +
           have a separate partition for <filename>/boot</filename> with

     

       25
       +
           partition code EF00, and it should be formatted as a

     

       26
       +
           <literal>vfat</literal> filesystem.</para>

     

       27
       +
         </listitem>

     

       28
       +
         <listitem>

     

       29
       +
           <para>You must set <option>boot.loader.gummiboot.enable</option> to

     

       30
       +
           <literal>true</literal>. <command>nixos-generate-config</command>

     

       31
       +
           should do this automatically for new configurations when booted in

     

       32
       +
           UEFI mode.</para>

     

       33
       +
         </listitem>

     

       34
       +
         <listitem>

     

       35
       +
           <para>After having mounted your installation partition to

     

       36
       +
           <code>/mnt</code>, you must mount the <code>boot</code> partition

     

       37
       +
           to <code>/mnt/boot</code>.</para>

     

       38
       +
         </listitem>

     

       39
       +
         <listitem>

     

       40
       +
           <para>You may want to look at the options starting with

     

       41
       +
           <option>boot.loader.efi</option> and <option>boot.loader.gummiboot</option>

     

       42
       +
           as well.</para>

     

       43
       +
         </listitem>

     

       44
       +
         <listitem>

     

       45
       +
           <para>To see console messages during early boot, add <literal>"fbcon"</literal>

     

       46
       +
           to your <option>boot.initrd.kernelModules</option>.</para>

     

       47
       +
         </listitem>

     

       48
       +
       </itemizedlist>

     

       49
       +
       </para>

     

       50
       +
       

     

       51
       +
       </section>

+30

nixos/doc/manual/installation/installing-USB.xml

···

       1
       +
       <section xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-booting-from-usb">

     

       6
       +
       

     

       7
       +
       <title>Booting from a USB Drive</title>

     

       8
       +
       

     

       9
       +
       <para>For systems without CD drive, the NixOS livecd can be booted from

     

       10
       +
       a usb stick. For non-UEFI installations,

     

       11
       +
       <link xlink:href="http://unetbootin.sourceforge.net/">unetbootin</link>

     

       12
       +
       will work. For UEFI installations, you should mount the ISO, copy its contents

     

       13
       +
       verbatim to your drive, then either:

     

       14
       +
       

     

       15
       +
       <itemizedlist>

     

       16
       +
         <listitem>

     

       17
       +
           <para>Change the label of the disk partition to the label of the ISO

     

       18
       +
           (visible with the blkid command), or</para>

     

       19
       +
         </listitem>

     

       20
       +
         <listitem>

     

       21
       +
           <para>Edit <filename>loader/entries/nixos-livecd.conf</filename> on the drive

     

       22
       +
           and change the <literal>root=</literal> field in the <literal>options</literal>

     

       23
       +
           line to point to your drive (see the documentation on <literal>root=</literal>

     

       24
       +
           in <link xlink:href="https://www.kernel.org/doc/Documentation/kernel-parameters.txt">

     

       25
       +
           the kernel documentation</link> for more details).</para>

     

       26
       +
         </listitem>

     

       27
       +
       </itemizedlist>

     

       28
       +
       </para>

     

       29
       +
       

     

       30
       +
       </section>

+264

nixos/doc/manual/installation/installing.xml

···

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

     

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

     

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

     

       4
       +
                   version="5.0"

     

       5
       +
                   xml:id="sec-installation">

     

       6
       +
       

     

       7
       +
       <title>Installing NixOS</title>

     

       8
       +
       

     

       9
       +
       <orderedlist>

     

       10
       +
       

     

       11
       +
         <listitem><para>Boot from the CD.</para></listitem>

     

       12
       +
       

     

       13
       +
         <listitem><para>The CD contains a basic NixOS installation.  (It

     

       14
       +
         also contains Memtest86+, useful if you want to test new hardware.)

     

       15
       +
         When it’s finished booting, it should have detected most of your

     

       16
       +
         hardware and brought up networking (check

     

       17
       +
         <command>ifconfig</command>).  Networking is necessary for the

     

       18
       +
         installer, since it will download lots of stuff (such as source

     

       19
       +
         tarballs or Nixpkgs channel binaries).  It’s best if you have a DHCP

     

       20
       +
         server on your network.  Otherwise configure networking manually

     

       21
       +
         using <command>ifconfig</command>.</para></listitem>

     

       22
       +
       

     

       23
       +
         <listitem><para>The NixOS manual is available on virtual console 8

     

       24
       +
         (press Alt+F8 to access).</para></listitem>

     

       25
       +
       

     

       26
       +
         <listitem><para>Login as <literal>root</literal> and the empty

     

       27
       +
         password.</para></listitem>

     

       28
       +
       

     

       29
       +
         <listitem><para>If you downloaded the graphical ISO image, you can

     

       30
       +
         run <command>start display-manager</command> to start KDE.</para></listitem>

     

       31
       +
       

     

       32
       +
         <listitem><para>The NixOS installer doesn’t do any partitioning or

     

       33
       +
         formatting yet, so you need to that yourself.  Use the following

     

       34
       +
         commands:

     

       35
       +
       

     

       36
       +
         <itemizedlist>

     

       37
       +
       

     

       38
       +
           <listitem><para>For partitioning:

     

       39
       +
           <command>fdisk</command>.</para></listitem>

     

       40
       +
       

     

       41
       +
           <listitem><para>For initialising Ext4 partitions:

     

       42
       +
           <command>mkfs.ext4</command>.  It is recommended that you assign a

     

       43
       +
           unique symbolic label to the file system using the option

     

       44
       +
           <option>-L <replaceable>label</replaceable></option>, since this

     

       45
       +
           makes the file system configuration independent from device

     

       46
       +
           changes.  For example:

     

       47
       +
       

     

       48
       +
       <screen>

     

       49
       +
       $ mkfs.ext4 -L nixos /dev/sda1</screen>

     

       50
       +
       

     

       51
       +
           </para></listitem>

     

       52
       +
       

     

       53
       +
           <listitem><para>For creating swap partitions:

     

       54
       +
           <command>mkswap</command>.  Again it’s recommended to assign a

     

       55
       +
           label to the swap partition: <option>-L

     

       56
       +
           <replaceable>label</replaceable></option>.</para></listitem>

     

       57
       +
       

     

       58
       +
           <listitem><para>For creating LVM volumes, the LVM commands, e.g.,

     

       59
       +
       

     

       60
       +
       <screen>

     

       61
       +
       $ pvcreate /dev/sda1 /dev/sdb1

     

       62
       +
       $ vgcreate MyVolGroup /dev/sda1 /dev/sdb1

     

       63
       +
       $ lvcreate --size 2G --name bigdisk MyVolGroup

     

       64
       +
       $ lvcreate --size 1G --name smalldisk MyVolGroup</screen>

     

       65
       +
       

     

       66
       +
           </para></listitem>

     

       67
       +
       

     

       68
       +
           <listitem><para>For creating software RAID devices, use

     

       69
       +
           <command>mdadm</command>.</para></listitem>

     

       70
       +
       

     

       71
       +
         </itemizedlist>

     

       72
       +
       

     

       73
       +
         </para></listitem>

     

       74
       +
       

     

       75
       +
         <listitem><para>Mount the target file system on which NixOS should

     

       76
       +
         be installed on <filename>/mnt</filename>, e.g.

     

       77
       +
       

     

       78
       +
       <screen>

     

       79
       +
       $ mount /dev/disk/by-label/nixos /mnt

     

       80
       +
       </screen>

     

       81
       +
       

     

       82
       +
         </para></listitem>

     

       83
       +
       

     

       84
       +
         <listitem><para>If your machine has a limited amount of memory, you

     

       85
       +
         may want to activate swap devices now (<command>swapon

     

       86
       +
         <replaceable>device</replaceable></command>).  The installer (or

     

       87
       +
         rather, the build actions that it may spawn) may need quite a bit of

     

       88
       +
         RAM, depending on your configuration.</para></listitem>

     

       89
       +
       

     

       90
       +
         <listitem>

     

       91
       +
       

     

       92
       +
           <para>You now need to create a file

     

       93
       +
           <filename>/mnt/etc/nixos/configuration.nix</filename> that

     

       94
       +
           specifies the intended configuration of the system.  This is

     

       95
       +
           because NixOS has a <emphasis>declarative</emphasis> configuration

     

       96
       +
           model: you create or edit a description of the desired

     

       97
       +
           configuration of your system, and then NixOS takes care of making

     

       98
       +
           it happen.  The syntax of the NixOS configuration file is

     

       99
       +
           described in <xref linkend="sec-configuration-syntax"/>, while a

     

       100
       +
           list of available configuration options appears in <xref

     

       101
       +
           linkend="ch-options"/>.  A minimal example is shown in <xref

     

       102
       +
           linkend="ex-config"/>.</para>

     

       103
       +
       

     

       104
       +
           <para>The command <command>nixos-generate-config</command> can

     

       105
       +
           generate an initial configuration file for you:

     

       106
       +
       

     

       107
       +
       <screen>

     

       108
       +
       $ nixos-generate-config --root /mnt</screen>

     

       109
       +
       

     

       110
       +
           You should then edit

     

       111
       +
           <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your

     

       112
       +
           needs:

     

       113
       +
       

     

       114
       +
       <screen>

     

       115
       +
       $ nano /mnt/etc/nixos/configuration.nix

     

       116
       +
       </screen>

     

       117
       +
       

     

       118
       +
           The <command>vim</command> text editor is also available.</para>

     

       119
       +
       

     

       120
       +
           <para>You <emphasis>must</emphasis> set the option

     

       121
       +
           <option>boot.loader.grub.device</option> to specify on which disk

     

       122
       +
           the GRUB boot loader is to be installed.  Without it, NixOS cannot

     

       123
       +
           boot.</para>

     

       124
       +
       

     

       125
       +
           <para>Another critical option is <option>fileSystems</option>,

     

       126
       +
           specifying the file systems that need to be mounted by NixOS.

     

       127
       +
           However, you typically don’t need to set it yourself, because

     

       128
       +
           <command>nixos-generate-config</command> sets it automatically in

     

       129
       +
           <filename>/mnt/etc/nixos/hardware-configuration.nix</filename>

     

       130
       +
           from your currently mounted file systems.  (The configuration file

     

       131
       +
           <filename>hardware-configuration.nix</filename> is included from

     

       132
       +
           <filename>configuration.nix</filename> and will be overwritten by

     

       133
       +
           future invocations of <command>nixos-generate-config</command>;

     

       134
       +
           thus, you generally should not modify it.)</para>

     

       135
       +
       

     

       136
       +
           <note><para>Depending on your hardware configuration or type of

     

       137
       +
           file system, you may need to set the option

     

       138
       +
           <option>boot.initrd.kernelModules</option> to include the kernel

     

       139
       +
           modules that are necessary for mounting the root file system,

     

       140
       +
           otherwise the installed system will not be able to boot.  (If this

     

       141
       +
           happens, boot from the CD again, mount the target file system on

     

       142
       +
           <filename>/mnt</filename>, fix

     

       143
       +
           <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun

     

       144
       +
           <filename>nixos-install</filename>.)  In most cases,

     

       145
       +
           <command>nixos-generate-config</command> will figure out the

     

       146
       +
           required modules.</para></note>

     

       147
       +
       

     

       148
       +
           <para>Examples of real-world NixOS configuration files can be

     

       149
       +
           found at <link

     

       150
       +
           xlink:href="https://nixos.org/repos/nix/configurations/trunk/"/>.</para>

     

       151
       +
       

     

       152
       +
         </listitem>

     

       153
       +
       

     

       154
       +
         <listitem><para>Do the installation:

     

       155
       +
       

     

       156
       +
       <screen>

     

       157
       +
       $ nixos-install</screen>

     

       158
       +
       

     

       159
       +
           Cross fingers.  If this fails due to a temporary problem (such as

     

       160
       +
           a network issue while downloading binaries from the NixOS binary

     

       161
       +
           cache), you can just re-run <command>nixos-install</command>.

     

       162
       +
           Otherwise, fix your <filename>configuration.nix</filename> and

     

       163
       +
           then re-run <command>nixos-install</command>.</para>

     

       164
       +
       

     

       165
       +
           <para>As the last step, <command>nixos-install</command> will ask

     

       166
       +
           you to set the password for the <literal>root</literal> user, e.g.

     

       167
       +
       

     

       168
       +
       <screen>

     

       169
       +
       setting root password...

     

       170
       +
       Enter new UNIX password: ***

     

       171
       +
       Retype new UNIX password: ***

     

       172
       +
       </screen>

     

       173
       +
       

     

       174
       +
           </para>

     

       175
       +
       

     

       176
       +
         </listitem>

     

       177
       +
       

     

       178
       +
         <listitem><para>If everything went well:

     

       179
       +
       

     

       180
       +
       <screen>

     

       181
       +
       $ reboot</screen>

     

       182
       +
       

     

       183
       +
         </para></listitem>

     

       184
       +
       

     

       185
       +
         <listitem>

     

       186
       +
       

     

       187
       +
           <para>You should now be able to boot into the installed NixOS. The GRUB boot menu shows a list

     

       188
       +
                       of <emphasis>available configurations</emphasis> (initially just one). Every time

     

       189
       +
                       you change the NixOS configuration (see<link linkend="sec-changing-config">Changing

     

       190
       +
                           Configuration</link> ), a new item appears in the menu. This allows you to

     

       191
       +
                       easily roll back to another configuration if something goes wrong.</para>

     

       192
       +
       

     

       193
       +
           <para>You should log in and change the <literal>root</literal>

     

       194
       +
           password with <command>passwd</command>.</para>

     

       195
       +
       

     

       196
       +
           <para>You’ll probably want to create some user accounts as well,

     

       197
       +
           which can be done with <command>useradd</command>:

     

       198
       +
       

     

       199
       +
       <screen>

     

       200
       +
       $ useradd -c 'Eelco Dolstra' -m eelco

     

       201
       +
       $ passwd eelco</screen>

     

       202
       +
       

     

       203
       +
           </para>

     

       204
       +
       

     

       205
       +
           <para>You may also want to install some software.  For instance,

     

       206
       +
       

     

       207
       +
       <screen>

     

       208
       +
       $ nix-env -qa \*</screen>

     

       209
       +
       

     

       210
       +
           shows what packages are available, and

     

       211
       +
       

     

       212
       +
       <screen>

     

       213
       +
       $ nix-env -i w3m</screen>

     

       214
       +
       

     

       215
       +
           install the <literal>w3m</literal> browser.</para>

     

       216
       +
       

     

       217
       +
         </listitem>

     

       218
       +
       

     

       219
       +
       </orderedlist>

     

       220
       +
       

     

       221
       +
       <para>To summarise, <xref linkend="ex-install-sequence" /> shows a

     

       222
       +
       typical sequence of commands for installing NixOS on an empty hard

     

       223
       +
       drive (here <filename>/dev/sda</filename>).  <xref linkend="ex-config"

     

       224
       +
       /> shows a corresponding configuration Nix expression.</para>

     

       225
       +
       

     

       226
       +
       <example xml:id='ex-install-sequence'><title>Commands for Installing NixOS on <filename>/dev/sda</filename></title>

     

       227
       +
       <screen>

     

       228
       +
       $ fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>

     

       229
       +
       $ mkfs.ext4 -L nixos /dev/sda1

     

       230
       +
       $ mkswap -L swap /dev/sda2

     

       231
       +
       $ swapon /dev/sda2

     

       232
       +
       $ mount /dev/disk/by-label/nixos /mnt

     

       233
       +
       $ nixos-generate-config --root /mnt

     

       234
       +
       $ nano /mnt/etc/nixos/configuration.nix

     

       235
       +
       $ nixos-install

     

       236
       +
       $ reboot</screen>

     

       237
       +
       </example>

     

       238
       +
       

     

       239
       +
       <example xml:id='ex-config'><title>NixOS Configuration</title>

     

       240
       +
       <screen>

     

       241
       +
       { config, pkgs, ... }:

     

       242
       +
       

     

       243
       +
       {

     

       244
       +
         imports =

     

       245
       +
           [ # Include the results of the hardware scan.

     

       246
       +
             ./hardware-configuration.nix

     

       247
       +
           ];

     

       248
       +
       

     

       249
       +
         boot.loader.grub.device = "/dev/sda";

     

       250
       +
       

     

       251
       +
         # Note: setting fileSystems is generally not

     

       252
       +
         # necessary, since nixos-generate-config figures them out

     

       253
       +
         # automatically in hardware-configuration.nix.

     

       254
       +
         #fileSystems."/".device = "/dev/disk/by-label/nixos";

     

       255
       +
       

     

       256
       +
         # Enable the OpenSSH server.

     

       257
       +
         services.sshd.enable = true;

     

       258
       +
       }</screen>

     

       259
       +
       </example>

     

       260
       +
       

     

       261
       +
       <xi:include href="installing-UEFI.xml" />

     

       262
       +
       <xi:include href="installing-USB.xml" />

     

       263
       +
       

     

       264
       +
       </chapter>

+44

nixos/doc/manual/installation/obtaining.xml

···

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

     

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

     

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

     

       4
       +
                version="5.0"

     

       5
       +
                xml:id="sec-obtaining">

     

       6
       +
       

     

       7
       +
       <title>Obtaining NixOS</title>

     

       8
       +
       

     

       9
       +
       <para>NixOS ISO images can be downloaded from the <link

     

       10
       +
       xlink:href="http://nixos.org/nixos/download.html">NixOS

     

       11
       +
       homepage</link>.  These can be burned onto a CD.  It is also possible

     

       12
       +
       to copy them onto a USB stick and install NixOS from there.  For

     

       13
       +
       details, see the <link

     

       14
       +
       xlink:href="https://nixos.org/wiki/Installing_NixOS_from_a_USB_stick">NixOS

     

       15
       +
       Wiki</link>.</para>

     

       16
       +
       

     

       17
       +
       <para>As an alternative to installing NixOS yourself, you can get a

     

       18
       +
       running NixOS system through several other means:

     

       19
       +
       

     

       20
       +
       <itemizedlist>

     

       21
       +
         <listitem>

     

       22
       +
           <para>Using virtual appliances in Open Virtualization Format (OVF)

     

       23
       +
           that can be imported into VirtualBox.  These are available from

     

       24
       +
           the <link xlink:href="http://nixos.org/nixos/download.html">NixOS

     

       25
       +
           homepage</link>.</para>

     

       26
       +
         </listitem>

     

       27
       +
         <listitem>

     

       28
       +
           <para>Using AMIs for Amazon’s EC2.  To find one for your region

     

       29
       +
           and instance type, please refer to the <link

     

       30
       +
           xlink:href="https://github.com/NixOS/nixops/blob/master/nix/ec2-amis.nix">list

     

       31
       +
           of most recent AMIs</link>.</para>

     

       32
       +
         </listitem>

     

       33
       +
         <listitem>

     

       34
       +
           <para>Using NixOps, the NixOS-based cloud deployment tool, which

     

       35
       +
           allows you to provision VirtualBox and EC2 NixOS instances from

     

       36
       +
           declarative specifications.  Check out the <link

     

       37
       +
           xlink:href="https://github.com/NixOS/nixops">NixOps

     

       38
       +
           homepage</link> for details.</para>

     

       39
       +
         </listitem>

     

       40
       +
       </itemizedlist>

     

       41
       +
       

     

       42
       +
       </para>

     

       43
       +
       

     

       44
       +
       </chapter>

+90

nixos/doc/manual/installation/upgrading.xml

···

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

     

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

     

       3
       +
                version="5.0"

     

       4
       +
                xml:id="sec-upgrading">

     

       5
       +
       

     

       6
       +
       <title>Upgrading NixOS</title>

     

       7
       +
       

     

       8
       +
       <para>The best way to keep your NixOS installation up to date is to

     

       9
       +
       use one of the NixOS <emphasis>channels</emphasis>.  A channel is a

     

       10
       +
       Nix mechanism for distributing Nix expressions and associated

     

       11
       +
       binaries.  The NixOS channels are updated automatically from NixOS’s

     

       12
       +
       Git repository after certain tests have passed and all packages have

     

       13
       +
       been built.  These channels are:

     

       14
       +
       

     

       15
       +
       <itemizedlist>

     

       16
       +
         <listitem>

     

       17
       +
           <para>Stable channels, such as <literal

     

       18
       +
           xlink:href="http://nixos.org/channels/nixos-14.04">nixos-14.04</literal>.

     

       19
       +
           These only get conservative bug fixes and package upgrades.  For

     

       20
       +
           instance, a channel update may cause the Linux kernel on your

     

       21
       +
           system to be upgraded from 3.4.66 to 3.4.67 (a minor bug fix), but

     

       22
       +
           not from 3.4.<replaceable>x</replaceable> to

     

       23
       +
           3.11.<replaceable>x</replaceable> (a major change that has the

     

       24
       +
           potential to break things).  Stable channels are generally

     

       25
       +
           maintained until the next stable branch is created.</para>

     

       26
       +
         </listitem>

     

       27
       +
         <listitem>

     

       28
       +
           <para>The unstable channel, <literal

     

       29
       +
           xlink:href="http://nixos.org/channels/nixos-unstable">nixos-unstable</literal>.

     

       30
       +
           This corresponds to NixOS’s main development branch, and may thus

     

       31
       +
           see radical changes between channel updates.  It’s not recommended

     

       32
       +
           for production systems.</para>

     

       33
       +
         </listitem>

     

       34
       +
       </itemizedlist>

     

       35
       +
       

     

       36
       +
       To see what channels are available, go to <link

     

       37
       +
       xlink:href="http://nixos.org/channels"/>.  (Note that the URIs of the

     

       38
       +
       various channels redirect to a directory that contains the channel’s

     

       39
       +
       latest version and includes ISO images and VirtualBox

     

       40
       +
       appliances.)</para>

     

       41
       +
       

     

       42
       +
       <para>When you first install NixOS, you’re automatically subscribed to

     

       43
       +
       the NixOS channel that corresponds to your installation source.   For

     

       44
       +
       instance, if you installed from a 14.04 ISO, you will be subscribed to

     

       45
       +
       the <literal>nixos-14.04</literal> channel.  To see which NixOS

     

       46
       +
       channel you’re subscribed to, run the following as root:

     

       47
       +
       

     

       48
       +
       <screen>

     

       49
       +
       $ nix-channel --list | grep nixos

     

       50
       +
       nixos https://nixos.org/channels/nixos-unstable

     

       51
       +
       </screen>

     

       52
       +
       

     

       53
       +
       To switch to a different NixOS channel, do

     

       54
       +
       

     

       55
       +
       <screen>

     

       56
       +
       $ nix-channel --add http://nixos.org/channels/<replaceable>channel-name</replaceable> nixos

     

       57
       +
       </screen>

     

       58
       +
       

     

       59
       +
       (Be sure to include the <literal>nixos</literal> parameter at the

     

       60
       +
       end.)  For instance, to use the NixOS 14.04 stable channel:

     

       61
       +
       

     

       62
       +
       <screen>

     

       63
       +
       $ nix-channel --add http://nixos.org/channels/nixos-14.04 nixos

     

       64
       +
       </screen>

     

       65
       +
       

     

       66
       +
       But it you want to live on the bleeding edge:

     

       67
       +
       

     

       68
       +
       <screen>

     

       69
       +
       $ nix-channel --add http://nixos.org/channels/nixos-unstable nixos

     

       70
       +
       </screen>

     

       71
       +
       

     

       72
       +
       </para>

     

       73
       +
       

     

       74
       +
       <para>You can then upgrade NixOS to the latest version in your chosen

     

       75
       +
       channel by running

     

       76
       +
       

     

       77
       +
       <screen>

     

       78
       +
       $ nixos-rebuild switch --upgrade

     

       79
       +
       </screen>

     

       80
       +
       

     

       81
       +
       which is equivalent to the more verbose <literal>nix-channel --update

     

       82
       +
       nixos; nixos-rebuild switch</literal>.</para>

     

       83
       +
       

     

       84
       +
       <warning><para>It is generally safe to switch back and forth between

     

       85
       +
       channels.  The only exception is that a newer NixOS may also have a

     

       86
       +
       newer Nix version, which may involve an upgrade of Nix’s database

     

       87
       +
       schema.  This cannot be undone easily, so in that case you will not be

     

       88
       +
       able to go back to your original channel.</para></warning>

     

       89
       +
       

     

       90
       +
       </chapter>

+9 -15

nixos/doc/manual/manual.xml

···

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

     

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

     

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

     

       4
       -
       

     

       0
        
       
     

       0
        
       
     

       5
        
         <info>

     

       6
       -
       

     

       7
        
           <title>NixOS Manual</title>

     

       8
        
           <subtitle>Version <xi:include href="version" parse="text" /></subtitle>

     

       9
       -
       

     

       10
        
         </info>

     

       11
       -
       

     

       12
        
       

     

       13
        
         <preface>

     

       14
        
           <title>Preface</title>

     
···

       29
        
       

     

       30
        
         </preface>

     

       31
        
       

     

       32
       -
       

     

       33
       -
         <xi:include href="installation.xml" />

     

       34
       -
         <xi:include href="configuration.xml" />

     

       35
       -
         <xi:include href="running.xml" />

     

       36
        
         <!-- <xi:include href="userconfiguration.xml" /> -->

     

       37
       -
         <xi:include href="troubleshooting.xml" />

     

       38
       -
         <xi:include href="containers.xml" />

     

       39
       -
         <xi:include href="development.xml" />

     

       40
       -
       

     

       41
       -
         <xi:include href="release-notes.xml" />

     

       42
        
       

     

       43
        
         <appendix xml:id="ch-options">

     

       44
       -
           <title>Configuration options</title>

     

       45
        
           <xi:include href="options-db.xml" />

     

       46
        
         </appendix>

     

       47

···

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

     

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

     

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

     

       4
       +
             version="5.0"

     

       5
       +
             xml:id="NixOSManual">

     

       6
       +
         

     

       7
        
         <info>

     

       0
        
       
     

       8
        
           <title>NixOS Manual</title>

     

       9
        
           <subtitle>Version <xi:include href="version" parse="text" /></subtitle>

     

       0
        
       
     

       10
        
         </info>

     

       0
        
       
     

       11
        
       

     

       12
        
         <preface>

     

       13
        
           <title>Preface</title>

     
···

       28
        
       

     

       29
        
         </preface>

     

       30
        
       

     

       31
       +
         <xi:include href="installation/installation.xml" />

     

       32
       +
         <xi:include href="configuration/configuration.xml" />

     

       33
       +
         <xi:include href="administration/running.xml" />

     

       0
        
       
     

       34
        
         <!-- <xi:include href="userconfiguration.xml" /> -->

     

       35
       +
         <xi:include href="release-notes/release-notes.xml" />

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       36
        
       

     

       37
        
         <appendix xml:id="ch-options">

     

       38
       +
           <title>Configuration Options</title>

     

       39
        
           <xi:include href="options-db.xml" />

     

       40
        
         </appendix>

     

       41

+6 -44

nixos/doc/manual/release-notes.xml nixos/doc/manual/release-notes/rl-1404.xml

···

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

     

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

     

       3
       -
                 xml:id="ch-release-notes">

     

       4
       -
       

     

       5
       -
       <title>Release notes</title>

     

       6
       -
       

     

       7
       -
       <!--==================================================================-->

     

       8
       -
       

     

       9
       -
       <section xml:id="sec-release-14.10">

     

       10
       -
       

     

       11
       -
       <title>Release 14.10 (“Caterpillar”, 2014/10/??)</title>

     

       12
       -
       

     

       13
       -
       <para>When upgrading from a previous release, please be aware of the

     

       14
       -
       following incompatible changes:

     

       15
       -
       

     

       16
       -
       <itemizedlist>

     

       17
       -
       

     

       18
       -
         <listitem><para>The host side of a container virtual Ethernet pair

     

       19
       -
         is now called <literal>ve-<replaceable>container-name</replaceable></literal>

     

       20
       -
         rather than <literal>c-<replaceable>container-name</replaceable></literal>.</para></listitem>

     

       21
       -
       

     

       22
       -
       </itemizedlist>

     

       23
       -
       

     

       24
       -
       </para>

     

       25
       -
       

     

       26
       -
       </section>

     

       27
       -
       

     

       28
       -
       

     

       29
       -
       <!--==================================================================-->

     

       30
       -
       

     

       31
       -
       <section xml:id="sec-release-14.04">

     

       32
        
       

     

       33
        
       <title>Release 14.04 (“Baboon”, 2014/04/30)</title>

     

       34
        
       

     
···

       183
        
       

     

       184
        
       </para>

     

       185
        
       

     

       186
       -
       </section>

     

       187
       -
       

     

       188
       -
       <!--==================================================================-->

     

       189
       -
       

     

       190
       -
       <section xml:id="sec-release-13.10">

     

       191
       -
       

     

       192
       -
       <title>Release 13.10 (“Aardvark”, 2013/10/31)</title>

     

       193
       -
       

     

       194
       -
       <para>This is the first stable release branch of NixOS.</para>

     

       195
       -
       

     

       196
       -
       </section>

     

       197
       -
       

     

       198
       -
       </appendix>

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-release-14.04">

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       6
        
       

     

       7
        
       <title>Release 14.04 (“Baboon”, 2014/04/30)</title>

     

       8
        
       

     
···

       157
        
       

     

       158
        
       </para>

     

       159
        
       

     

       160
       +
       </chapter>
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0

+17

nixos/doc/manual/release-notes/release-notes.xml

···

       1
       +
       <part   xmlns="http://docbook.org/ns/docbook"

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="ch-release-notes">

     

       6
       +
       

     

       7
       +
       <title>Release Notes</title>

     

       8
       +
       

     

       9
       +
       <partintro>

     

       10
       +
       <para>This section lists the release notes for each stable version of NixOS.</para>

     

       11
       +
       </partintro>

     

       12
       +
       

     

       13
       +
       <xi:include href="rl-1410.xml" />

     

       14
       +
       <xi:include href="rl-1404.xml" />

     

       15
       +
       <xi:include href="rl-1310.xml" />

     

       16
       +
       

     

       17
       +
       </part>

+11

nixos/doc/manual/release-notes/rl-1310.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-release-13.10">

     

       6
       +
       

     

       7
       +
       <title>Release 13.10 (“Aardvark”, 2013/10/31)</title>

     

       8
       +
       

     

       9
       +
       <para>This is the first stable release branch of NixOS.</para>

     

       10
       +
       

     

       11
       +
       </chapter>

+22

nixos/doc/manual/release-notes/rl-1410.xml

···

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

     

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

     

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

     

       4
       +
               version="5.0"

     

       5
       +
               xml:id="sec-release-14.10">

     

       6
       +
       

     

       7
       +
       <title>Release 14.10 (“Caterpillar”, 2014/10/??)</title>

     

       8
       +
       

     

       9
       +
       <para>When upgrading from a previous release, please be aware of the

     

       10
       +
       following incompatible changes:

     

       11
       +
       

     

       12
       +
       <itemizedlist>

     

       13
       +
       

     

       14
       +
         <listitem><para>The host side of a container virtual Ethernet pair

     

       15
       +
         is now called <literal>ve-<replaceable>container-name</replaceable></literal>

     

       16
       +
         rather than <literal>c-<replaceable>container-name</replaceable></literal>.</para></listitem>

     

       17
       +
       

     

       18
       +
       </itemizedlist>

     

       19
       +
       

     

       20
       +
       </para>

     

       21
       +
       

     

       22
       +
       </chapter>

-369

nixos/doc/manual/running.xml

···

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

     

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

     

       3
       -
                xml:id="ch-running">

     

       4
       -
       

     

       5
       -
       <title>Running NixOS</title>

     

       6
       -
       

     

       7
       -
       <para>This chapter describes various aspects of managing a running

     

       8
       -
       NixOS system, such as how to use the <command>systemd</command>

     

       9
       -
       service manager.</para>

     

       10
       -
       

     

       11
       -
       

     

       12
       -
       <!--===============================================================-->

     

       13
       -
       

     

       14
       -
       <section xml:id="sec-systemctl"><title>Service management</title>

     

       15
       -
       

     

       16
       -
       <para>In NixOS, all system services are started and monitored using

     

       17
       -
       the systemd program.  Systemd is the “init” process of the system

     

       18
       -
       (i.e. PID 1), the parent of all other processes.  It manages a set of

     

       19
       -
       so-called “units”, which can be things like system services

     

       20
       -
       (programs), but also mount points, swap files, devices, targets

     

       21
       -
       (groups of units) and more.  Units can have complex dependencies; for

     

       22
       -
       instance, one unit can require that another unit must be successfully

     

       23
       -
       started before the first unit can be started.  When the system boots,

     

       24
       -
       it starts a unit named <literal>default.target</literal>; the

     

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

     

       26
       -
       file systems to be mounted, swap files to be activated, and so

     

       27
       -
       on.</para>

     

       28
       -
       

     

       29
       -
       <para>The command <command>systemctl</command> is the main way to

     

       30
       -
       interact with <command>systemd</command>.  Without any arguments, it

     

       31
       -
       shows the status of active units:

     

       32
       -
       

     

       33
       -
       <screen>

     

       34
       -
       $ systemctl

     

       35
       -
       -.mount          loaded active mounted   /

     

       36
       -
       swapfile.swap    loaded active active    /swapfile

     

       37
       -
       sshd.service     loaded active running   SSH Daemon

     

       38
       -
       graphical.target loaded active active    Graphical Interface

     

       39
       -
       <replaceable>...</replaceable>

     

       40
       -
       </screen>

     

       41
       -
       

     

       42
       -
       </para>

     

       43
       -
       

     

       44
       -
       <para>You can ask for detailed status information about a unit, for

     

       45
       -
       instance, the PostgreSQL database service:

     

       46
       -
       

     

       47
       -
       <screen>

     

       48
       -
       $ systemctl status postgresql.service

     

       49
       -
       postgresql.service - PostgreSQL Server

     

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

     

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

     

       52
       -
               Main PID: 2390 (postgres)

     

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

     

       54
       -
                         ├─2390 postgres

     

       55
       -
                         ├─2418 postgres: writer process

     

       56
       -
                         ├─2419 postgres: wal writer process

     

       57
       -
                         ├─2420 postgres: autovacuum launcher process

     

       58
       -
                         ├─2421 postgres: stats collector process

     

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

     

       60
       -
       

     

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

     

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

     

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

     

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

     

       65
       -
       </screen>

     

       66
       -
       

     

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

     

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

     

       69
       -
       messages from the service.

     

       70
       -
       

     

       71
       -
       </para>

     

       72
       -
       

     

       73
       -
       <para>Units can be stopped, started or restarted:

     

       74
       -
       

     

       75
       -
       <screen>

     

       76
       -
       $ systemctl stop postgresql.service

     

       77
       -
       $ systemctl start postgresql.service

     

       78
       -
       $ systemctl restart postgresql.service

     

       79
       -
       </screen>

     

       80
       -
       

     

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

     

       82
       -
       finished starting or stopping (or has failed).  Starting a unit will

     

       83
       -
       cause the dependencies of that unit to be started as well (if

     

       84
       -
       necessary).</para>

     

       85
       -
       

     

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

     

       87
       -
       

     

       88
       -
       - cgroup resource management -->

     

       89
       -
       

     

       90
       -
       </section>

     

       91
       -
       

     

       92
       -
       

     

       93
       -
       <!--===============================================================-->

     

       94
       -
       

     

       95
       -
       <section xml:id="sec-rebooting"><title>Rebooting and shutting down</title>

     

       96
       -
       

     

       97
       -
       <para>The system can be shut down (and automatically powered off) by

     

       98
       -
       doing:

     

       99
       -
       

     

       100
       -
       <screen>

     

       101
       -
       $ shutdown

     

       102
       -
       </screen>

     

       103
       -
       

     

       104
       -
       This is equivalent to running <command>systemctl

     

       105
       -
       poweroff</command>.</para>

     

       106
       -
       

     

       107
       -
       <para>To reboot the system, run

     

       108
       -
       

     

       109
       -
       <screen>

     

       110
       -
       $ reboot

     

       111
       -
       </screen>

     

       112
       -
       

     

       113
       -
       which is equivalent to <command>systemctl reboot</command>.

     

       114
       -
       Alternatively, you can quickly reboot the system using

     

       115
       -
       <literal>kexec</literal>, which bypasses the BIOS by directly loading

     

       116
       -
       the new kernel into memory:

     

       117
       -
       

     

       118
       -
       <screen>

     

       119
       -
       $ systemctl kexec

     

       120
       -
       </screen>

     

       121
       -
       

     

       122
       -
       </para>

     

       123
       -
       

     

       124
       -
       <para>The machine can be suspended to RAM (if supported) using

     

       125
       -
       <command>systemctl suspend</command>, and suspended to disk using

     

       126
       -
       <command>systemctl hibernate</command>.</para>

     

       127
       -
       

     

       128
       -
       <para>These commands can be run by any user who is logged in locally,

     

       129
       -
       i.e. on a virtual console or in X11; otherwise, the user is asked for

     

       130
       -
       authentication.</para>

     

       131
       -
       

     

       132
       -
       </section>

     

       133
       -
       

     

       134
       -
       

     

       135
       -
       <!--===============================================================-->

     

       136
       -
       

     

       137
       -
       <section xml:id="sec-user-sessions"><title>User sessions</title>

     

       138
       -
       

     

       139
       -
       <para>Systemd keeps track of all users who are logged into the system

     

       140
       -
       (e.g. on a virtual console or remotely via SSH).  The command

     

       141
       -
       <command>loginctl</command> allows querying and manipulating user

     

       142
       -
       sessions.  For instance, to list all user sessions:

     

       143
       -
       

     

       144
       -
       <screen>

     

       145
       -
       $ loginctl

     

       146
       -
          SESSION        UID USER             SEAT

     

       147
       -
               c1        500 eelco            seat0

     

       148
       -
               c3          0 root             seat0

     

       149
       -
               c4        500 alice

     

       150
       -
       </screen>

     

       151
       -
       

     

       152
       -
       This shows that two users are logged in locally, while another is

     

       153
       -
       logged in remotely.  (“Seats” are essentially the combinations of

     

       154
       -
       displays and input devices attached to the system; usually, there is

     

       155
       -
       only one seat.)  To get information about a session:

     

       156
       -
       

     

       157
       -
       <screen>

     

       158
       -
       $ loginctl session-status c3

     

       159
       -
       c3 - root (0)

     

       160
       -
                  Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago

     

       161
       -
                 Leader: 2536 (login)

     

       162
       -
                   Seat: seat0; vc3

     

       163
       -
                    TTY: /dev/tty3

     

       164
       -
                Service: login; type tty; class user

     

       165
       -
                  State: online

     

       166
       -
                 CGroup: name=systemd:/user/root/c3

     

       167
       -
                         ├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login --

     

       168
       -
                         ├─10339 -bash

     

       169
       -
                         └─10355 w3m nixos.org

     

       170
       -
       </screen>

     

       171
       -
       

     

       172
       -
       This shows that the user is logged in on virtual console 3.  It also

     

       173
       -
       lists the processes belonging to this session.  Since systemd keeps

     

       174
       -
       track of this, you can terminate a session in a way that ensures that

     

       175
       -
       all the session’s processes are gone:

     

       176
       -
       

     

       177
       -
       <screen>

     

       178
       -
       $ loginctl terminate-session c3

     

       179
       -
       </screen>

     

       180
       -
       

     

       181
       -
       </para>

     

       182
       -
       

     

       183
       -
       </section>

     

       184
       -
       

     

       185
       -
       

     

       186
       -
       <!--===============================================================-->

     

       187
       -
       

     

       188
       -
       <section xml:id="sec-cgroups"><title>Control groups</title>

     

       189
       -
       

     

       190
       -
       <para>To keep track of the processes in a running system, systemd uses

     

       191
       -
       <emphasis>control groups</emphasis> (cgroups).  A control group is a

     

       192
       -
       set of processes used to allocate resources such as CPU, memory or I/O

     

       193
       -
       bandwidth.  There can be multiple control group hierarchies, allowing

     

       194
       -
       each kind of resource to be managed independently.</para>

     

       195
       -
       

     

       196
       -
       <para>The command <command>systemd-cgls</command> lists all control

     

       197
       -
       groups in the <literal>systemd</literal> hierarchy, which is what

     

       198
       -
       systemd uses to keep track of the processes belonging to each service

     

       199
       -
       or user session:

     

       200
       -
       

     

       201
       -
       <screen>

     

       202
       -
       $ systemd-cgls

     

       203
       -
       ├─user

     

       204
       -
       │ └─eelco

     

       205
       -
       │   └─c1

     

       206
       -
       │     ├─ 2567 -:0

     

       207
       -
       │     ├─ 2682 kdeinit4: kdeinit4 Running...

     

       208
       -
       │     ├─ <replaceable>...</replaceable>

     

       209
       -
       │     └─10851 sh -c less -R

     

       210
       -
       └─system

     

       211
       -
         ├─httpd.service

     

       212
       -
         │ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH

     

       213
       -
         │ └─<replaceable>...</replaceable>

     

       214
       -
         ├─dhcpcd.service

     

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

     

       216
       -
         └─ <replaceable>...</replaceable>

     

       217
       -
       </screen>

     

       218
       -
       

     

       219
       -
       Similarly, <command>systemd-cgls cpu</command> shows the cgroups in

     

       220
       -
       the CPU hierarchy, which allows per-cgroup CPU scheduling priorities.

     

       221
       -
       By default, every systemd service gets its own CPU cgroup, while all

     

       222
       -
       user sessions are in the top-level CPU cgroup.  This ensures, for

     

       223
       -
       instance, that a thousand run-away processes in the

     

       224
       -
       <literal>httpd.service</literal> cgroup cannot starve the CPU for one

     

       225
       -
       process in the <literal>postgresql.service</literal> cgroup.  (By

     

       226
       -
       contrast, it they were in the same cgroup, then the PostgreSQL process

     

       227
       -
       would get 1/1001 of the cgroup’s CPU time.)  You can limit a service’s

     

       228
       -
       CPU share in <filename>configuration.nix</filename>:

     

       229
       -
       

     

       230
       -
       <programlisting>

     

       231
       -
       systemd.services.httpd.serviceConfig.CPUShares = 512;

     

       232
       -
       </programlisting>

     

       233
       -
       

     

       234
       -
       By default, every cgroup has 1024 CPU shares, so this will halve the

     

       235
       -
       CPU allocation of the <literal>httpd.service</literal> cgroup.</para>

     

       236
       -
       

     

       237
       -
       <para>There also is a <literal>memory</literal> hierarchy that

     

       238
       -
       controls memory allocation limits; by default, all processes are in

     

       239
       -
       the top-level cgroup, so any service or session can exhaust all

     

       240
       -
       available memory.  Per-cgroup memory limits can be specified in

     

       241
       -
       <filename>configuration.nix</filename>; for instance, to limit

     

       242
       -
       <literal>httpd.service</literal> to 512 MiB of RAM (excluding swap)

     

       243
       -
       and 640 MiB of RAM (including swap):

     

       244
       -
       

     

       245
       -
       <programlisting>

     

       246
       -
       systemd.services.httpd.serviceConfig.MemoryLimit = "512M";

     

       247
       -
       systemd.services.httpd.serviceConfig.ControlGroupAttribute = [ "memory.memsw.limit_in_bytes 640M" ];

     

       248
       -
       </programlisting>

     

       249
       -
       

     

       250
       -
       </para>

     

       251
       -
       

     

       252
       -
       <para>The command <command>systemd-cgtop</command> shows a

     

       253
       -
       continuously updated list of all cgroups with their CPU and memory

     

       254
       -
       usage.</para>

     

       255
       -
       

     

       256
       -
       </section>

     

       257
       -
       

     

       258
       -
       

     

       259
       -
       <!--===============================================================-->

     

       260
       -
       

     

       261
       -
       <section xml:id="sec-logging"><title>Logging</title>

     

       262
       -
       

     

       263
       -
       <para>System-wide logging is provided by systemd’s

     

       264
       -
       <emphasis>journal</emphasis>, which subsumes traditional logging

     

       265
       -
       daemons such as syslogd and klogd.  Log entries are kept in binary

     

       266
       -
       files in <filename>/var/log/journal/</filename>.  The command

     

       267
       -
       <literal>journalctl</literal> allows you to see the contents of the

     

       268
       -
       journal.  For example,

     

       269
       -
       

     

       270
       -
       <screen>

     

       271
       -
       $ journalctl -b

     

       272
       -
       </screen>

     

       273
       -
       

     

       274
       -
       shows all journal entries since the last reboot.  (The output of

     

       275
       -
       <command>journalctl</command> is piped into <command>less</command> by

     

       276
       -
       default.)  You can use various options and match operators to restrict

     

       277
       -
       output to messages of interest.  For instance, to get all messages

     

       278
       -
       from PostgreSQL:

     

       279
       -
       

     

       280
       -
       <screen>

     

       281
       -
       $ journalctl -u postgresql.service

     

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

     

       283
       -
       ...

     

       284
       -
       Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG:  database system is shut down

     

       285
       -
       -- Reboot --

     

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

     

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

     

       288
       -
       </screen>

     

       289
       -
       

     

       290
       -
       Or to get all messages since the last reboot that have at least a

     

       291
       -
       “critical” severity level:

     

       292
       -
       

     

       293
       -
       <screen>

     

       294
       -
       $ journalctl -b -p crit

     

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

     

       296
       -
       Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1)

     

       297
       -
       </screen>

     

       298
       -
       

     

       299
       -
       </para>

     

       300
       -
       

     

       301
       -
       <para>The system journal is readable by root and by users in the

     

       302
       -
       <literal>wheel</literal> and <literal>systemd-journal</literal>

     

       303
       -
       groups.  All users have a private journal that can be read using

     

       304
       -
       <command>journalctl</command>.</para>

     

       305
       -
       

     

       306
       -
       </section>

     

       307
       -
       

     

       308
       -
       

     

       309
       -
       <!--===============================================================-->

     

       310
       -
       

     

       311
       -
       <section xml:id="sec-nix-gc"><title>Cleaning up the Nix store</title>

     

       312
       -
       

     

       313
       -
       <para>Nix has a purely functional model, meaning that packages are

     

       314
       -
       never upgraded in place.  Instead new versions of packages end up in a

     

       315
       -
       different location in the Nix store (<filename>/nix/store</filename>).

     

       316
       -
       You should periodically run Nix’s <emphasis>garbage

     

       317
       -
       collector</emphasis> to remove old, unreferenced packages.  This is

     

       318
       -
       easy:

     

       319
       -
       

     

       320
       -
       <screen>

     

       321
       -
       $ nix-collect-garbage

     

       322
       -
       </screen>

     

       323
       -
       

     

       324
       -
       Alternatively, you can use a systemd unit that does the same in the

     

       325
       -
       background:

     

       326
       -
       

     

       327
       -
       <screen>

     

       328
       -
       $ systemctl start nix-gc.service

     

       329
       -
       </screen>

     

       330
       -
       

     

       331
       -
       You can tell NixOS in <filename>configuration.nix</filename> to run

     

       332
       -
       this unit automatically at certain points in time, for instance, every

     

       333
       -
       night at 03:15:

     

       334
       -
       

     

       335
       -
       <programlisting>

     

       336
       -
       nix.gc.automatic = true;

     

       337
       -
       nix.gc.dates = "03:15";

     

       338
       -
       </programlisting>

     

       339
       -
       

     

       340
       -
       </para>

     

       341
       -
       

     

       342
       -
       <para>The commands above do not remove garbage collector roots, such

     

       343
       -
       as old system configurations.  Thus they do not remove the ability to

     

       344
       -
       roll back to previous configurations.  The following command deletes

     

       345
       -
       old roots, removing the ability to roll back to them:

     

       346
       -
       <screen>

     

       347
       -
       $ nix-collect-garbage -d

     

       348
       -
       </screen>

     

       349
       -
       You can also do this for specific profiles, e.g.

     

       350
       -
       <screen>

     

       351
       -
       $ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old

     

       352
       -
       </screen>

     

       353
       -
       Note that NixOS system configurations are stored in the profile

     

       354
       -
       <filename>/nix/var/nix/profiles/system</filename>.</para>

     

       355
       -
       

     

       356
       -
       <para>Another way to reclaim disk space (often as much as 40% of the

     

       357
       -
       size of the Nix store) is to run Nix’s store optimiser, which seeks

     

       358
       -
       out identical files in the store and replaces them with hard links to

     

       359
       -
       a single copy.

     

       360
       -
       <screen>

     

       361
       -
       $ nix-store --optimise

     

       362
       -
       </screen>

     

       363
       -
       Since this command needs to read the entire Nix store, it can take

     

       364
       -
       quite a while to finish.</para>

     

       365
       -
       

     

       366
       -
       </section>

     

       367
       -
       

     

       368
       -
       

     

       369
       -
       </chapter>

-199

nixos/doc/manual/troubleshooting.xml

···

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

     

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

     

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

     

       4
       -
       

     

       5
       -
       <title>Troubleshooting</title>

     

       6
       -
       

     

       7
       -
       

     

       8
       -
       <!--===============================================================-->

     

       9
       -
       

     

       10
       -
       <section xml:id="sec-boot-problems"><title>Boot problems</title>

     

       11
       -
       

     

       12
       -
       <para>If NixOS fails to boot, there are a number of kernel command

     

       13
       -
       line parameters that may help you to identify or fix the issue.  You

     

       14
       -
       can add these parameters in the GRUB boot menu by pressing “e” to

     

       15
       -
       modify the selected boot entry and editing the line starting with

     

       16
       -
       <literal>linux</literal>.  The following are some useful kernel command

     

       17
       -
       line parameters that are recognised by the NixOS boot scripts or by

     

       18
       -
       systemd:

     

       19
       -
       

     

       20
       -
       <variablelist>

     

       21
       -
       

     

       22
       -
         <varlistentry><term><literal>boot.shell_on_fail</literal></term>

     

       23
       -
           <listitem><para>Start a root shell if something goes wrong in

     

       24
       -
           stage 1 of the boot process (the initial ramdisk).  This is

     

       25
       -
           disabled by default because there is no authentication for the

     

       26
       -
           root shell.</para></listitem>

     

       27
       -
         </varlistentry>

     

       28
       -
       

     

       29
       -
         <varlistentry><term><literal>boot.debug1</literal></term>

     

       30
       -
           <listitem><para>Start an interactive shell in stage 1 before

     

       31
       -
           anything useful has been done.  That is, no modules have been

     

       32
       -
           loaded and no file systems have been mounted, except for

     

       33
       -
           <filename>/proc</filename> and

     

       34
       -
           <filename>/sys</filename>.</para></listitem>

     

       35
       -
         </varlistentry>

     

       36
       -
       

     

       37
       -
         <varlistentry><term><literal>boot.trace</literal></term>

     

       38
       -
           <listitem><para>Print every shell command executed by the stage 1

     

       39
       -
           and 2 boot scripts.</para></listitem>

     

       40
       -
         </varlistentry>

     

       41
       -
       

     

       42
       -
         <varlistentry><term><literal>single</literal></term>

     

       43
       -
           <listitem><para>Boot into rescue mode (a.k.a. single user mode).

     

       44
       -
           This will cause systemd to start nothing but the unit

     

       45
       -
           <literal>rescue.target</literal>, which runs

     

       46
       -
           <command>sulogin</command> to prompt for the root password and

     

       47
       -
           start a root login shell.  Exiting the shell causes the system to

     

       48
       -
           continue with the normal boot process.</para></listitem>

     

       49
       -
         </varlistentry>

     

       50
       -
       

     

       51
       -
         <varlistentry><term><literal>systemd.log_level=debug systemd.log_target=console</literal></term>

     

       52
       -
           <listitem><para>Make systemd very verbose and send log messages to

     

       53
       -
           the console instead of the journal.</para></listitem>

     

       54
       -
         </varlistentry>

     

       55
       -
       

     

       56
       -
       </variablelist>

     

       57
       -
       

     

       58
       -
       For more parameters recognised by systemd, see

     

       59
       -
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>

     

       60
       -
       

     

       61
       -
       <para>If no login prompts or X11 login screens appear (e.g. due to

     

       62
       -
       hanging dependencies), you can press Alt+ArrowUp.  If you’re lucky,

     

       63
       -
       this will start rescue mode (described above).  (Also note that since

     

       64
       -
       most units have a 90-second timeout before systemd gives up on them,

     

       65
       -
       the <command>agetty</command> login prompts should appear eventually

     

       66
       -
       unless something is very wrong.)</para>

     

       67
       -
       

     

       68
       -
       </section>

     

       69
       -
       

     

       70
       -
       

     

       71
       -
       <!--===============================================================-->

     

       72
       -
       

     

       73
       -
       <section xml:id="sec-maintenance-mode"><title>Maintenance mode</title>

     

       74
       -
       

     

       75
       -
       <para>You can enter rescue mode by running:

     

       76
       -
       

     

       77
       -
       <screen>

     

       78
       -
       $ systemctl rescue</screen>

     

       79
       -
       

     

       80
       -
       This will eventually give you a single-user root shell.  Systemd will

     

       81
       -
       stop (almost) all system services.  To get out of maintenance mode,

     

       82
       -
       just exit from the rescue shell.</para>

     

       83
       -
       

     

       84
       -
       </section>

     

       85
       -
       

     

       86
       -
       

     

       87
       -
       <!--===============================================================-->

     

       88
       -
       

     

       89
       -
       <section xml:id="sec-rollback"><title>Rolling back configuration changes</title>

     

       90
       -
       

     

       91
       -
       <para>After running <command>nixos-rebuild</command> to switch to a

     

       92
       -
       new configuration, you may find that the new configuration doesn’t

     

       93
       -
       work very well.  In that case, there are several ways to return to a

     

       94
       -
       previous configuration.</para>

     

       95
       -
       

     

       96
       -
       <para>First, the GRUB boot manager allows you to boot into any

     

       97
       -
       previous configuration that hasn’t been garbage-collected.  These

     

       98
       -
       configurations can be found under the GRUB submenu “NixOS - All

     

       99
       -
       configurations”.  This is especially useful if the new configuration

     

       100
       -
       fails to boot.  After the system has booted, you can make the selected

     

       101
       -
       configuration the default for subsequent boots:

     

       102
       -
       

     

       103
       -
       <screen>

     

       104
       -
       $ /run/current-system/bin/switch-to-configuration boot</screen>

     

       105
       -
       

     

       106
       -
       </para>

     

       107
       -
       

     

       108
       -
       <para>Second, you can switch to the previous configuration in a running

     

       109
       -
       system:

     

       110
       -
       

     

       111
       -
       <screen>

     

       112
       -
       $ nixos-rebuild switch --rollback</screen>

     

       113
       -
       

     

       114
       -
       This is equivalent to running:

     

       115
       -
       

     

       116
       -
       <screen>

     

       117
       -
       $ /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>

     

       118
       -
       

     

       119
       -
       where <replaceable>N</replaceable> is the number of the NixOS system

     

       120
       -
       configuration.  To get a list of the available configurations, do:

     

       121
       -
       

     

       122
       -
       <screen>

     

       123
       -
       $ ls -l /nix/var/nix/profiles/system-*-link

     

       124
       -
       <replaceable>...</replaceable>

     

       125
       -
       lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055

     

       126
       -
       </screen>

     

       127
       -
       

     

       128
       -
       </para>

     

       129
       -
       

     

       130
       -
       </section>

     

       131
       -
       

     

       132
       -
       

     

       133
       -
       <!--===============================================================-->

     

       134
       -
       

     

       135
       -
       <section xml:id="sec-nix-store-corruption"><title>Nix store corruption</title>

     

       136
       -
       

     

       137
       -
       <para>After a system crash, it’s possible for files in the Nix store

     

       138
       -
       to become corrupted.  (For instance, the Ext4 file system has the

     

       139
       -
       tendency to replace un-synced files with zero bytes.)  NixOS tries

     

       140
       -
       hard to prevent this from happening: it performs a

     

       141
       -
       <command>sync</command> before switching to a new configuration, and

     

       142
       -
       Nix’s database is fully transactional.  If corruption still occurs,

     

       143
       -
       you may be able to fix it automatically.</para>

     

       144
       -
       

     

       145
       -
       <para>If the corruption is in a path in the closure of the NixOS

     

       146
       -
       system configuration, you can fix it by doing

     

       147
       -
       

     

       148
       -
       <screen>

     

       149
       -
       $ nixos-rebuild switch --repair

     

       150
       -
       </screen>

     

       151
       -
       

     

       152
       -
       This will cause Nix to check every path in the closure, and if its

     

       153
       -
       cryptographic hash differs from the hash recorded in Nix’s database,

     

       154
       -
       the path is rebuilt or redownloaded.</para>

     

       155
       -
       

     

       156
       -
       <para>You can also scan the entire Nix store for corrupt paths:

     

       157
       -
       

     

       158
       -
       <screen>

     

       159
       -
       $ nix-store --verify --check-contents --repair

     

       160
       -
       </screen>

     

       161
       -
       

     

       162
       -
       Any corrupt paths will be redownloaded if they’re available in a

     

       163
       -
       binary cache; otherwise, they cannot be repaired.</para>

     

       164
       -
       

     

       165
       -
       </section>

     

       166
       -
       

     

       167
       -
       

     

       168
       -
       <!--===============================================================-->

     

       169
       -
       

     

       170
       -
       <section xml:id="sec-nix-network-issues"><title>Nix network issues</title>

     

       171
       -
       

     

       172
       -
       <para>Nix uses a so-called <emphasis>binary cache</emphasis> to

     

       173
       -
       optimise building a package from source into downloading it as a

     

       174
       -
       pre-built binary.  That is, whenever a command like

     

       175
       -
       <command>nixos-rebuild</command> needs a path in the Nix store, Nix

     

       176
       -
       will try to download that path from the Internet rather than build it

     

       177
       -
       from source.  The default binary cache is

     

       178
       -
       <uri>http://cache.nixos.org/</uri>.  If this cache is unreachable, Nix

     

       179
       -
       operations may take a long time due to HTTP connection timeouts.  You

     

       180
       -
       can disable the use of the binary cache by adding <option>--option

     

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

     

       182
       -
       

     

       183
       -
       <screen>

     

       184
       -
       $ nixos-rebuild switch --option use-binary-caches false

     

       185
       -
       </screen>

     

       186
       -
       

     

       187
       -
       If you have an alternative binary cache at your disposal, you can use

     

       188
       -
       it instead:

     

       189
       -
       

     

       190
       -
       <screen>

     

       191
       -
       $ nixos-rebuild switch --option binary-caches http://my-cache.example.org/

     

       192
       -
       </screen>

     

       193
       -
       

     

       194
       -
       </para>

     

       195
       -
       

     

       196
       -
       </section>

     

       197
       -
       

     

       198
       -
       

     

       199
       -
       </chapter>