pyrox.dev
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
18The first line (<literal>{ config, pkgs, ... }:</literal>) denotes
19that this is actually a function that takes at least the two arguments
20 <varname>config</varname> and <varname>pkgs</varname>. (These are
21explained later.) The function returns a <emphasis>set</emphasis> of
22option definitions (<literal>{ <replaceable>...</replaceable> }</literal>). These definitions have the
23form <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
37defines a configuration with three option definitions that together
38enable the Apache HTTP Server with <filename>/webroot</filename> as
39the document root.</para>
40
41<para>Sets can be nested, and in fact dots in option names are
42shorthand 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
46named <varname>enable</varname> with value <literal>true</literal>.
47This 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
62which may be more convenient if you have lots of option definitions
63that share the same prefix (such as
64<literal>services.httpd</literal>).</para>
65
66<para>NixOS checks your option definitions for correctness. For
67instance, if you try to define an option that doesn’t exist (that is,
68doesn’t have a corresponding <emphasis>option declaration</emphasis>),
69<command>nixos-rebuild</command> will give an error like:
70<screen>
71The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
72</screen>
73Likewise, values in option definitions must have a correct type. For
74instance, <option>services.httpd.enable</option> must be a Boolean
75(<literal>true</literal> or <literal>false</literal>). Trying to give
76it a value of another type, such as a string, will cause an error:
77<screen>
78The 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>
92networking.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>
102networking.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 it strips from each line
110 a number of spaces equal to the minimal indentation of
111 the string as a whole (disregarding the indentation of
112 empty lines), and that characters like
113 <literal>"</literal> and <literal>\</literal> are not special
114 (making it more convenient for including things like shell
115 code).
116 See more info about this in the Nix manual <link
117 xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.</para>
118 </listitem>
119 </varlistentry>
120
121 <varlistentry>
122 <term>Booleans</term>
123 <listitem>
124 <para>These can be <literal>true</literal> or
125 <literal>false</literal>, e.g.
126
127<programlisting>
128networking.firewall.enable = true;
129networking.firewall.allowPing = false;
130</programlisting>
131 </para>
132 </listitem>
133 </varlistentry>
134
135 <varlistentry>
136 <term>Integers</term>
137 <listitem>
138 <para>For example,
139
140<programlisting>
141boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
142</programlisting>
143
144 (Note that here the attribute name
145 <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in
146 quotes to prevent it from being interpreted as a set named
147 <literal>net</literal> containing a set named
148 <literal>ipv4</literal>, and so on. This is because it’s not a
149 NixOS option but the literal name of a Linux kernel
150 setting.)</para>
151 </listitem>
152 </varlistentry>
153
154 <varlistentry>
155 <term>Sets</term>
156 <listitem>
157 <para>Sets were introduced above. They are name/value pairs
158 enclosed in braces, as in the option definition
159
160<programlisting>
161fileSystems."/boot" =
162 { device = "/dev/sda1";
163 fsType = "ext4";
164 options = [ "rw" "data=ordered" "relatime" ];
165 };
166</programlisting>
167 </para>
168 </listitem>
169 </varlistentry>
170
171 <varlistentry>
172 <term>Lists</term>
173 <listitem>
174 <para>The important thing to note about lists is that list
175 elements are separated by whitespace, like this:
176
177<programlisting>
178boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
179</programlisting>
180
181 List elements can be any other type, e.g. sets:
182
183<programlisting>
184swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
185</programlisting>
186 </para>
187 </listitem>
188 </varlistentry>
189
190 <varlistentry>
191 <term>Packages</term>
192 <listitem>
193 <para>Usually, the packages you need are already part of the Nix
194 Packages collection, which is a set that can be accessed through
195 the function argument <varname>pkgs</varname>. Typical uses:
196
197<programlisting>
198environment.systemPackages =
199 [ pkgs.thunderbird
200 pkgs.emacs
201 ];
202
203postgresql.package = pkgs.postgresql90;
204</programlisting>
205
206 The latter option definition changes the default PostgreSQL
207 package used by NixOS’s PostgreSQL service to 9.0. For more
208 information on packages, including how to add new ones, see
209 <xref linkend="sec-custom-packages"/>.</para>
210 </listitem>
211 </varlistentry>
212
213</variablelist>
214
215</para>
216
217</section>