diff options
Diffstat (limited to 'nixos/doc/manual/configuration/config-file.xml')
| -rw-r--r-- | nixos/doc/manual/configuration/config-file.xml | 216 |
1 files changed, 0 insertions, 216 deletions
diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml deleted file mode 100644 index 19cfb57920d..00000000000 --- a/nixos/doc/manual/configuration/config-file.xml +++ /dev/null @@ -1,216 +0,0 @@ -<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, in chapter <xref linkend="sec-writing-modules" />) 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> |