Chunk NixOS manual

[Squashed commits to make git blame etc. more likely to work. -ED]

1 files changed, 213 insertions, 0 deletions

diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml
new file mode 100644
index 000000000000..2a58ff25941c
--- /dev/null
+++ b/nixos/doc/manual/configuration/config-file.xml
@@ -0,0 +1,213 @@
+<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, ... }:
+
+{ services.httpd.enable = true;
+  services.httpd.adminAddr = "alice@example.org";
+  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,
+<option>services.httpd.enable</option> 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.enabl' 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>
+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>
+networking.extraHosts =
+  ''
+    127.0.0.2 other-localhost
+    10.0.0.1 server
+  '';
+</programlisting>
+
+      The main difference is that preceding whitespace is
+      automatically stripped from each line, and that characters like
+      <literal>"</literal> and <literal>\</literal> are not special
+      (making it more convenient for including things like shell
+      code).</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>Booleans</term>
+    <listitem>
+      <para>These can be <literal>true</literal> or
+      <literal>false</literal>, e.g.
+
+<programlisting>
+networking.firewall.enable = true;
+networking.firewall.allowPing = false;
+</programlisting>
+      </para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term>Integers</term>
+    <listitem>
+      <para>For example,
+
+<programlisting>
+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>
+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>
+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>
+environment.systemPackages =
+  [ pkgs.thunderbird
+    pkgs.emacs
+  ];
+
+postgresql.package = pkgs.postgresql90;
+</programlisting>
+
+      The latter option definition changes the default PostgreSQL
+      package used by NixOS’s PostgreSQL service to 9.0.  For more
+      information on packages, including how to add new ones, see
+      <xref linkend="sec-custom-packages"/>.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+</section>