<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"; <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.localhost.documentRoot</link> = "/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"; virtualHosts = { localhost = { 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 doesn’t exist (that is, doesn’t 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 it’s 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.postgresql_10; </programlisting> The latter option definition changes the default PostgreSQL package used by NixOS’s PostgreSQL service to 10.x. For more information on packages, including how to add new ones, see <xref linkend="sec-custom-packages"/>. </para> </listitem> </varlistentry> </variablelist> </para> </section>