nixpkgs/nixos/doc/manual/configuration/config-file.xml
2018-04-17 09:19:55 +10:00

218 lines
6.7 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-configuration-file">
<title>NixOS Configuration File</title>
<para>The NixOS configuration file generally looks like this:
<programlisting>
{ config, pkgs, ... }:
{ <replaceable>option definitions</replaceable>
}
</programlisting>
The first line (<literal>{ config, pkgs, ... }:</literal>) denotes
that this is actually a function that takes at least the two arguments
<varname>config</varname> and <varname>pkgs</varname>. (These are
explained later.) The function returns a <emphasis>set</emphasis> of
option definitions (<literal>{ <replaceable>...</replaceable> }</literal>). These definitions have the
form <literal><replaceable>name</replaceable> =
<replaceable>value</replaceable></literal>, where
<replaceable>name</replaceable> is the name of an option and
<replaceable>value</replaceable> is its value. For example,
<programlisting>
{ config, pkgs, ... }:
{ <xref linkend="opt-services.httpd.enable"/> = true;
<xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org";
<xref linkend="opt-services.httpd.documentRoot"/> = "/webroot";
}
</programlisting>
defines a configuration with three option definitions that together
enable the Apache HTTP Server with <filename>/webroot</filename> as
the document root.</para>
<para>Sets can be nested, and in fact dots in option names are
shorthand for defining a set containing another set. For instance,
<xref linkend="opt-services.httpd.enable"/> defines a set named
<varname>services</varname> that contains a set named
<varname>httpd</varname>, which in turn contains an option definition
named <varname>enable</varname> with value <literal>true</literal>.
This means that the example above can also be written as:
<programlisting>
{ config, pkgs, ... }:
{ services = {
httpd = {
enable = true;
adminAddr = "alice@example.org";
documentRoot = "/webroot";
};
};
}
</programlisting>
which may be more convenient if you have lots of option definitions
that share the same prefix (such as
<literal>services.httpd</literal>).</para>
<para>NixOS checks your option definitions for correctness. For
instance, if you try to define an option that doesnt exist (that is,
doesnt have a corresponding <emphasis>option declaration</emphasis>),
<command>nixos-rebuild</command> will give an error like:
<screen>
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
</screen>
Likewise, values in option definitions must have a correct type. For
instance, <option>services.httpd.enable</option> must be a Boolean
(<literal>true</literal> or <literal>false</literal>). Trying to give
it a value of another type, such as a string, will cause an error:
<screen>
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
</screen>
</para>
<para>Options have various types of values. The most important are:
<variablelist>
<varlistentry>
<term>Strings</term>
<listitem>
<para>Strings are enclosed in double quotes, e.g.
<programlisting>
<xref linkend="opt-networking.hostName"/> = "dexter";
</programlisting>
Special characters can be escaped by prefixing them with a
backslash (e.g. <literal>\"</literal>).</para>
<para>Multi-line strings can be enclosed in <emphasis>double
single quotes</emphasis>, e.g.
<programlisting>
<xref linkend="opt-networking.extraHosts"/> =
''
127.0.0.2 other-localhost
10.0.0.1 server
'';
</programlisting>
The main difference is that it strips from each line
a number of spaces equal to the minimal indentation of
the string as a whole (disregarding the indentation of
empty lines), and that characters like
<literal>"</literal> and <literal>\</literal> are not special
(making it more convenient for including things like shell
code).
See more info about this in the Nix manual <link
xlink:href="https://nixos.org/nix/manual/#ssec-values">here</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Booleans</term>
<listitem>
<para>These can be <literal>true</literal> or
<literal>false</literal>, e.g.
<programlisting>
<xref linkend="opt-networking.firewall.enable"/> = true;
<xref linkend="opt-networking.firewall.allowPing"/> = false;
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Integers</term>
<listitem>
<para>For example,
<programlisting>
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;
</programlisting>
(Note that here the attribute name
<literal>net.ipv4.tcp_keepalive_time</literal> is enclosed in
quotes to prevent it from being interpreted as a set named
<literal>net</literal> containing a set named
<literal>ipv4</literal>, and so on. This is because its not a
NixOS option but the literal name of a Linux kernel
setting.)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Sets</term>
<listitem>
<para>Sets were introduced above. They are name/value pairs
enclosed in braces, as in the option definition
<programlisting>
<xref linkend="opt-fileSystems"/>."/boot" =
{ device = "/dev/sda1";
fsType = "ext4";
options = [ "rw" "data=ordered" "relatime" ];
};
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Lists</term>
<listitem>
<para>The important thing to note about lists is that list
elements are separated by whitespace, like this:
<programlisting>
<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
</programlisting>
List elements can be any other type, e.g. sets:
<programlisting>
swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Packages</term>
<listitem>
<para>Usually, the packages you need are already part of the Nix
Packages collection, which is a set that can be accessed through
the function argument <varname>pkgs</varname>. Typical uses:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> =
[ pkgs.thunderbird
pkgs.emacs
];
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql90;
</programlisting>
The latter option definition changes the default PostgreSQL
package used by NixOSs PostgreSQL service to 9.0. For more
information on packages, including how to add new ones, see
<xref linkend="sec-custom-packages"/>.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>