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 <title>NixOS Configuration File</title>
7
8 <para>
9 The NixOS configuration file generally looks like this:
10<programlisting>
11{ config, pkgs, ... }:
12
13{ <replaceable>option definitions</replaceable>
14}
15</programlisting>
16 The first line (<literal>{ config, pkgs, ... }:</literal>) denotes that this
17 is actually a function that takes at least the two arguments
18 <varname>config</varname> and <varname>pkgs</varname>. (These are explained
19 later.) The function returns a <emphasis>set</emphasis> of option definitions
20 (<literal>{ <replaceable>...</replaceable> }</literal>). These definitions
21 have the form <literal><replaceable>name</replaceable> =
22 <replaceable>value</replaceable></literal>, where
23 <replaceable>name</replaceable> is the name of an option and
24 <replaceable>value</replaceable> is its value. For example,
25<programlisting>
26{ config, pkgs, ... }:
27
28{ <xref linkend="opt-services.httpd.enable"/> = true;
29 <xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org";
30 <xref linkend="opt-services.httpd.documentRoot"/> = "/webroot";
31}
32</programlisting>
33 defines a configuration with three option definitions that together enable
34 the Apache HTTP Server with <filename>/webroot</filename> as the document
35 root.
36 </para>
37
38 <para>
39 Sets can be nested, and in fact dots in option names are shorthand for
40 defining a set containing another set. For instance,
41 <xref linkend="opt-services.httpd.enable"/> defines a set named
42 <varname>services</varname> that contains a set named
43 <varname>httpd</varname>, which in turn contains an option definition named
44 <varname>enable</varname> with value <literal>true</literal>. This means that
45 the example above can also be written as:
46<programlisting>
47{ config, pkgs, ... }:
48
49{ services = {
50 httpd = {
51 enable = true;
52 adminAddr = "alice@example.org";
53 documentRoot = "/webroot";
54 };
55 };
56}
57</programlisting>
58 which may be more convenient if you have lots of option definitions that
59 share the same prefix (such as <literal>services.httpd</literal>).
60 </para>
61
62 <para>
63 NixOS checks your option definitions for correctness. For instance, if you
64 try to define an option that doesn’t exist (that is, doesn’t have a
65 corresponding <emphasis>option declaration</emphasis>),
66 <command>nixos-rebuild</command> will give an error like:
67<screen>
68The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
69</screen>
70 Likewise, values in option definitions must have a correct type. For
71 instance, <option>services.httpd.enable</option> must be a Boolean
72 (<literal>true</literal> or <literal>false</literal>). Trying to give it a
73 value of another type, such as a string, will cause an error:
74<screen>
75The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
76</screen>
77 </para>
78
79 <para>
80 Options have various types of values. The most important are:
81 <variablelist>
82 <varlistentry>
83 <term>
84 Strings
85 </term>
86 <listitem>
87 <para>
88 Strings are enclosed in double quotes, e.g.
89<programlisting>
90<xref linkend="opt-networking.hostName"/> = "dexter";
91</programlisting>
92 Special characters can be escaped by prefixing them with a backslash
93 (e.g. <literal>\"</literal>).
94 </para>
95 <para>
96 Multi-line strings can be enclosed in <emphasis>double single
97 quotes</emphasis>, e.g.
98<programlisting>
99<xref linkend="opt-networking.extraHosts"/> =
100 ''
101 127.0.0.2 other-localhost
102 10.0.0.1 server
103 '';
104</programlisting>
105 The main difference is that it strips from each line a number of spaces
106 equal to the minimal indentation of the string as a whole (disregarding
107 the indentation of empty lines), and that characters like
108 <literal>"</literal> and <literal>\</literal> are not special (making it
109 more convenient for including things like shell code). See more info
110 about this in the Nix manual
111 <link
112 xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.
113 </para>
114 </listitem>
115 </varlistentry>
116 <varlistentry>
117 <term>
118 Booleans
119 </term>
120 <listitem>
121 <para>
122 These can be <literal>true</literal> or <literal>false</literal>, e.g.
123<programlisting>
124<xref linkend="opt-networking.firewall.enable"/> = true;
125<xref linkend="opt-networking.firewall.allowPing"/> = false;
126</programlisting>
127 </para>
128 </listitem>
129 </varlistentry>
130 <varlistentry>
131 <term>
132 Integers
133 </term>
134 <listitem>
135 <para>
136 For example,
137<programlisting>
138<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;
139</programlisting>
140 (Note that here the attribute name
141 <literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in quotes to
142 prevent it from being interpreted as a set named <literal>net</literal>
143 containing a set named <literal>ipv4</literal>, and so on. This is
144 because it’s not a NixOS option but the literal name of a Linux kernel
145 setting.)
146 </para>
147 </listitem>
148 </varlistentry>
149 <varlistentry>
150 <term>
151 Sets
152 </term>
153 <listitem>
154 <para>
155 Sets were introduced above. They are name/value pairs enclosed in braces,
156 as in the option definition
157<programlisting>
158<xref linkend="opt-fileSystems"/>."/boot" =
159 { device = "/dev/sda1";
160 fsType = "ext4";
161 options = [ "rw" "data=ordered" "relatime" ];
162 };
163</programlisting>
164 </para>
165 </listitem>
166 </varlistentry>
167 <varlistentry>
168 <term>
169 Lists
170 </term>
171 <listitem>
172 <para>
173 The important thing to note about lists is that list elements are
174 separated by whitespace, like this:
175<programlisting>
176<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
177</programlisting>
178 List elements can be any other type, e.g. sets:
179<programlisting>
180swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
181</programlisting>
182 </para>
183 </listitem>
184 </varlistentry>
185 <varlistentry>
186 <term>
187 Packages
188 </term>
189 <listitem>
190 <para>
191 Usually, the packages you need are already part of the Nix Packages
192 collection, which is a set that can be accessed through the function
193 argument <varname>pkgs</varname>. Typical uses:
194<programlisting>
195<xref linkend="opt-environment.systemPackages"/> =
196 [ pkgs.thunderbird
197 pkgs.emacs
198 ];
199
200<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql90;
201</programlisting>
202 The latter option definition changes the default PostgreSQL package used
203 by NixOS’s PostgreSQL service to 9.0. For more information on packages,
204 including how to add new ones, see <xref linkend="sec-custom-packages"/>.
205 </para>
206 </listitem>
207 </varlistentry>
208 </variablelist>
209 </para>
210</section>