diff options
Diffstat (limited to 'nixos/doc/manual/from_md/configuration/config-file.section.xml')
| -rw-r--r-- | nixos/doc/manual/from_md/configuration/config-file.section.xml | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/configuration/config-file.section.xml b/nixos/doc/manual/from_md/configuration/config-file.section.xml new file mode 100644 index 00000000000..952c6e60030 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/config-file.section.xml @@ -0,0 +1,231 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-configuration-file"> + <title>NixOS Configuration File</title> + <para> + The NixOS configuration file generally looks like this: + </para> + <programlisting language="bash"> +{ config, pkgs, ... }: + +{ option definitions +} +</programlisting> + <para> + The first line (<literal>{ config, pkgs, ... }:</literal>) denotes + that this is actually a function that takes at least the two + arguments <literal>config</literal> and <literal>pkgs</literal>. + (These are explained later, in chapter + <xref linkend="sec-writing-modules" />) The function returns a + <emphasis>set</emphasis> of option definitions + (<literal>{ ... }</literal>). These definitions have the form + <literal>name = value</literal>, where <literal>name</literal> is + the name of an option and <literal>value</literal> is its value. For + example, + </para> + <programlisting language="bash"> +{ config, pkgs, ... }: + +{ services.httpd.enable = true; + services.httpd.adminAddr = "alice@example.org"; + services.httpd.virtualHosts.localhost.documentRoot = "/webroot"; +} +</programlisting> + <para> + defines a configuration with three option definitions that together + enable the Apache HTTP Server with <literal>/webroot</literal> 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 + <literal>services</literal> that contains a set named + <literal>httpd</literal>, which in turn contains an option + definition named <literal>enable</literal> with value + <literal>true</literal>. This means that the example above can also + be written as: + </para> + <programlisting language="bash"> +{ config, pkgs, ... }: + +{ services = { + httpd = { + enable = true; + adminAddr = "alice@example.org"; + virtualHosts = { + localhost = { + documentRoot = "/webroot"; + }; + }; + }; + }; +} +</programlisting> + <para> + 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>), + <literal>nixos-rebuild</literal> will give an error like: + </para> + <programlisting> +The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist. +</programlisting> + <para> + Likewise, values in option definitions must have a correct type. For + instance, <literal>services.httpd.enable</literal> 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: + </para> + <programlisting> +The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean. +</programlisting> + <para> + Options have various types of values. The most important are: + </para> + <variablelist> + <varlistentry> + <term> + Strings + </term> + <listitem> + <para> + Strings are enclosed in double quotes, e.g. + </para> + <programlisting language="bash"> +networking.hostName = "dexter"; +</programlisting> + <para> + 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. + </para> + <programlisting language="bash"> +networking.extraHosts = + '' + 127.0.0.2 other-localhost + 10.0.0.1 server + ''; +</programlisting> + <para> + 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. + </para> + <programlisting language="bash"> +networking.firewall.enable = true; +networking.firewall.allowPing = false; +</programlisting> + </listitem> + </varlistentry> + <varlistentry> + <term> + Integers + </term> + <listitem> + <para> + For example, + </para> + <programlisting language="bash"> +boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60; +</programlisting> + <para> + (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 + </para> + <programlisting language="bash"> +fileSystems."/boot" = + { device = "/dev/sda1"; + fsType = "ext4"; + options = [ "rw" "data=ordered" "relatime" ]; + }; +</programlisting> + </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: + </para> + <programlisting language="bash"> +boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ]; +</programlisting> + <para> + List elements can be any other type, e.g. sets: + </para> + <programlisting language="bash"> +swapDevices = [ { device = "/dev/disk/by-label/swap"; } ]; +</programlisting> + </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 <literal>pkgs</literal>. Typical + uses: + </para> + <programlisting language="bash"> +environment.systemPackages = + [ pkgs.thunderbird + pkgs.emacs + ]; + +services.postgresql.package = pkgs.postgresql_10; +</programlisting> + <para> + 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> +</section> |