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 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>
124networking.firewall.enable = true;
125networking.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>
137boot.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>
157fileSystems."/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>
174boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
175</programlisting>
176
177 List elements can be any other type, e.g. sets:
178
179<programlisting>
180swapDevices = [ { 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>
194environment.systemPackages =
195 [ pkgs.thunderbird
196 pkgs.emacs
197 ];
198
199postgresql.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>