nixos/doc/manual/configuration/config-file.section.md

   1 # NixOS Configuration File {#sec-configuration-file}
   2
   3 The NixOS configuration file generally looks like this:
   4
   5 ```nix
   6 { config, pkgs, ... }:
   7
   8 { /* option definitions */
   9 }
  10 ```
  11
  12 The first line (`{ config, pkgs, ... }:`) denotes that this is actually
  13 a function that takes at least the two arguments `config` and `pkgs`.
  14 (These are explained later, in chapter [](#sec-writing-modules)) The
  15 function returns a *set* of option definitions (`{ ... }`).
  16 These definitions have the form `name = value`, where `name` is the
  17 name of an option and `value` is its value. For example,
  18
  19 ```nix
  20 { config, pkgs, ... }:
  21
  22 { services.httpd.enable = true;
  23   services.httpd.adminAddr = "alice@example.org";
  24   services.httpd.virtualHosts.localhost.documentRoot = "/webroot";
  25 }
  26 ```
  27
  28 defines a configuration with three option definitions that together
  29 enable the Apache HTTP Server with `/webroot` as the document root.
  30
  31 Sets can be nested, and in fact dots in option names are shorthand for
  32 defining a set containing another set. For instance,
  33 [](#opt-services.httpd.enable) defines a set named
  34 `services` that contains a set named `httpd`, which in turn contains an
  35 option definition named `enable` with value `true`. This means that the
  36 example above can also be written as:
  37
  38 ```nix
  39 { config, pkgs, ... }:
  40
  41 { services = {
  42     httpd = {
  43       enable = true;
  44       adminAddr = "alice@example.org";
  45       virtualHosts = {
  46         localhost = {
  47           documentRoot = "/webroot";
  48         };
  49       };
  50     };
  51   };
  52 }
  53 ```
  54
  55 which may be more convenient if you have lots of option definitions that
  56 share the same prefix (such as `services.httpd`).
  57
  58 NixOS checks your option definitions for correctness. For instance, if
  59 you try to define an option that doesn't exist (that is, doesn't have a
  60 corresponding *option declaration*), `nixos-rebuild` will give an error
  61 like:
  62
  63 ```plain
  64 The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
  65 ```
  66
  67 Likewise, values in option definitions must have a correct type. For
  68 instance, `services.httpd.enable` must be a Boolean (`true` or `false`).
  69 Trying to give it a value of another type, such as a string, will cause
  70 an error:
  71
  72 ```plain
  73 The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
  74 ```
  75
  76 Options have various types of values. The most important are:
  77
  78 Strings
  79
  80 :   Strings are enclosed in double quotes, e.g.
  81
  82     ```nix
  83     {
  84       networking.hostName = "dexter";
  85     }
  86     ```
  87
  88     Special characters can be escaped by prefixing them with a backslash
  89     (e.g. `\"`).
  90
  91     Multi-line strings can be enclosed in *double single quotes*, e.g.
  92
  93     ```nix
  94     {
  95       networking.extraHosts =
  96         ''
  97           127.0.0.2 other-localhost
  98           10.0.0.1 server
  99         '';
 100     }
 101     ```
 102
 103     The main difference is that it strips from each line a number of
 104     spaces equal to the minimal indentation of the string as a whole
 105     (disregarding the indentation of empty lines), and that characters
 106     like `"` and `\` are not special (making it more convenient for
 107     including things like shell code). See more info about this in the
 108     Nix manual [here](https://nixos.org/nix/manual/#ssec-values).
 109
 110 Booleans
 111
 112 :   These can be `true` or `false`, e.g.
 113
 114     ```nix
 115     {
 116       networking.firewall.enable = true;
 117       networking.firewall.allowPing = false;
 118     }
 119     ```
 120
 121 Integers
 122
 123 :   For example,
 124
 125     ```nix
 126     {
 127       boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
 128     }
 129     ```
 130
 131     (Note that here the attribute name `net.ipv4.tcp_keepalive_time` is
 132     enclosed in quotes to prevent it from being interpreted as a set
 133     named `net` containing a set named `ipv4`, and so on. This is
 134     because it's not a NixOS option but the literal name of a Linux
 135     kernel setting.)
 136
 137 Sets
 138
 139 :   Sets were introduced above. They are name/value pairs enclosed in
 140     braces, as in the option definition
 141
 142     ```nix
 143     {
 144       fileSystems."/boot" =
 145         { device = "/dev/sda1";
 146           fsType = "ext4";
 147           options = [ "rw" "data=ordered" "relatime" ];
 148         };
 149     }
 150     ```
 151
 152 Lists
 153
 154 :   The important thing to note about lists is that list elements are
 155     separated by whitespace, like this:
 156
 157     ```nix
 158     {
 159       boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
 160     }
 161     ```
 162
 163     List elements can be any other type, e.g. sets:
 164
 165     ```nix
 166     {
 167       swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
 168     }
 169     ```
 170
 171 Packages
 172
 173 :   Usually, the packages you need are already part of the Nix Packages
 174     collection, which is a set that can be accessed through the function
 175     argument `pkgs`. Typical uses:
 176
 177     ```nix
 178     {
 179       environment.systemPackages =
 180         [ pkgs.thunderbird
 181           pkgs.emacs
 182         ];
 183
 184       services.postgresql.package = pkgs.postgresql_14;
 185     }
 186     ```
 187
 188     The latter option definition changes the default PostgreSQL package
 189     used by NixOS's PostgreSQL service to 14.x. For more information on
 190     packages, including how to add new ones, see
 191     [](#sec-custom-packages).