pyrox.dev
Chunk NixOS manual
[Squashed commits to make git blame etc. more likely to work. -ED]
authored by
Mikey Ariel
and committed by
Eelco Dolstra
a099ca45
8707a070
+65
nixos/doc/manual/administration/boot-problems.xml
+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
+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
+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
+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
+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
+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
+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
+
<!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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
-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 '<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 <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
+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
+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
+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
+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
+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 <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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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 '<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
+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
+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
+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
+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
+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
+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
+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
+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
-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
-
<!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
-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 '<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
-
>
1100
-
</screen>
1101
-
1102
-
You can then take any Perl statement, e.g.
1103
-
1104
-
<screen>
1105
-
> startAll
1106
-
> $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
+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
+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
+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
+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
+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
+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
+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 '<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
+
>
63
+
</screen>
64
+
65
+
You can then take any Perl statement, e.g.
66
+
67
+
<screen>
68
+
> startAll
69
+
> $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
+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
+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
+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
+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
-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
+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
+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
+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
+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
+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
+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
+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
+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
-
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>
8
<title>NixOS Manual</title>
9
<subtitle>Version <xi:include href="version" parse="text" /></subtitle>
10
</info>
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" />
34
<!-- <xi:include href="userconfiguration.xml" /> -->
35
+
<xi:include href="release-notes/release-notes.xml" />
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
+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>
+17
nixos/doc/manual/release-notes/release-notes.xml
+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
+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
+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
-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
-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>
···