path: root/nixos/doc/manual/from_md/configuration/config-file.section.xml

<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 = &quot;alice@example.org&quot;;
  services.httpd.virtualHosts.localhost.documentRoot = &quot;/webroot&quot;;
}
</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 = &quot;alice@example.org&quot;;
      virtualHosts = {
        localhost = {
          documentRoot = &quot;/webroot&quot;;
        };
      };
    };
  };
}
</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 = &quot;dexter&quot;;
</programlisting>
        <para>
          Special characters can be escaped by prefixing them with a
          backslash (e.g. <literal>\&quot;</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>&quot;</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.&quot;net.ipv4.tcp_keepalive_time&quot; = 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.&quot;/boot&quot; =
  { device = &quot;/dev/sda1&quot;;
    fsType = &quot;ext4&quot;;
    options = [ &quot;rw&quot; &quot;data=ordered&quot; &quot;relatime&quot; ];
  };
</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 = [ &quot;fuse&quot; &quot;kvm-intel&quot; &quot;coretemp&quot; ];
</programlisting>
        <para>
          List elements can be any other type, e.g. sets:
        </para>
        <programlisting language="bash">
swapDevices = [ { device = &quot;/dev/disk/by-label/swap&quot;; } ];
</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>