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, 0 insertions, 231 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 deleted file mode 100644 index 952c6e60030..00000000000 --- a/nixos/doc/manual/from_md/configuration/config-file.section.xml +++ /dev/null @@ -1,231 +0,0 @@ -<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> |