diff options
Diffstat (limited to 'nixpkgs/nixos/doc/manual/configuration/config-file.xml')
| -rw-r--r-- | nixpkgs/nixos/doc/manual/configuration/config-file.xml | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/configuration/config-file.xml b/nixpkgs/nixos/doc/manual/configuration/config-file.xml new file mode 100644 index 000000000000..eadafb94b8f6 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/configuration/config-file.xml @@ -0,0 +1,211 @@ +<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 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> |