NixOS can also be installed on UEFI systems. The procedure is by and large the same as a BIOS installation, with the following changes:

For systems without CD drive, the NixOS live CD can be booted from a USB stick. You can use the dd utility to write the image: dd if=path-to-image of=/dev/sdb. Be careful about specifying the correct drive; you can use the lsblk command to get a list of block devices. If you're on macOS you can run diskutil list to see the list of devices; the device you'll use for the USB must be ejected before writing the image.

The dd utility will write the image verbatim to the drive, making it the recommended option for both UEFI and non-UEFI installations. For non-UEFI installations, you can alternatively use unetbootin. If you cannot use dd for a UEFI installation, you can also mount the ISO, copy its contents verbatim to your drive, then either:

Advanced users may wish to install NixOS using an existing PXE or iPXE setup.

These instructions assume that you have an existing PXE or iPXE infrastructure and simply want to add the NixOS installer as another option. To build the necessary files from a recent version of nixpkgs, you can run:

nix-build -A netboot nixos/release.nix

This will create a result directory containing: * bzImage – the Linux kernel * initrd – the initrd file * netboot.ipxe – an example ipxe script demonstrating the appropriate kernel command line arguments for this image

If you’re using plain PXE, configure your boot loader to use the bzImage and initrd files and have it provide the same kernel command line arguments found in netboot.ipxe.

If you’re using iPXE, depending on how your HTTP/FTP/etc. server is configured you may be able to use netboot.ipxe unmodified, or you may need to update the paths to the files to match your server’s directory layout

In the future we may begin making these files available as build products from hydra at which point we will update this documentation with instructions on how to obtain them either for placing on a dedicated TFTP server or to boot them directly over the internet.

Installing NixOS into a Virtualbox guest is convenient for users who want to try NixOS without installing it on bare metal. If you want to use a pre-made Virtualbox appliance, it is available at the downloads page. If you want to set up a Virtualbox guest manually, follow these instructions:

There are a few modifications you should make in configuration.nix. Enable booting:

boot.loader.grub.device = "/dev/sda";

Also remove the fsck that runs at startup. It will always fail to run, stopping your boot until you press *.

boot.initrd.checkJournalingFS = false;

Shared folders can be given a name and a path in the host system in the VirtualBox settings (Machine / Settings / Shared Folders, then click on the "Add" icon). Add the following to the /etc/nixos/configuration.nix to auto-mount them:

{ config, pkgs, ...} :
{
  ...

  fileSystems."/virtualboxshare" = {
    fsType = "vboxsf";
    device = "nameofthesharedfolder";
    options = [ "rw" ];
  };
}

The folder will be available directly under the root directory.

You can keep a NixOS system up-to-date automatically by adding the following to configuration.nix:

system.autoUpgrade.enable = true;

This enables a periodically executed systemd service named nixos-upgrade.service. It runs nixos-rebuild switch --upgrade to upgrade NixOS to the latest version in the current channel. (To see when the service runs, see systemctl list-timers.) You can also specify a channel explicitly, e.g.

system.autoUpgrade.channel = https://nixos.org/channels/nixos-17.03;

The NixOS configuration file generally looks like this:

{ config, pkgs, ... }:

{ option definitions
}

The first line ({ config, pkgs, ... }:) denotes that this is actually a function that takes at least the two arguments config and pkgs. (These are explained later.) The function returns a set of option definitions ({ ... }). These definitions have the form name = value, where name is the name of an option and value is its value. For example,

{ config, pkgs, ... }:

{ services.httpd.enable = true;
  services.httpd.adminAddr = "alice@example.org";
  services.httpd.documentRoot = "/webroot";
}

defines a configuration with three option definitions that together enable the Apache HTTP Server with /webroot as the document root.

Sets can be nested, and in fact dots in option names are shorthand for defining a set containing another set. For instance, services.httpd.enable defines a set named services that contains a set named httpd, which in turn contains an option definition named enable with value true. This means that the example above can also be written as:

{ config, pkgs, ... }:

{ services = {
    httpd = {
      enable = true;
      adminAddr = "alice@example.org";
      documentRoot = "/webroot";
    };
  };
}

which may be more convenient if you have lots of option definitions that share the same prefix (such as services.httpd).

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 option declaration), nixos-rebuild will give an error like:

The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.

Likewise, values in option definitions must have a correct type. For instance, services.httpd.enable must be a Boolean (true or false). Trying to give it a value of another type, such as a string, will cause an error:

The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.

Options have various types of values. The most important are:

If you find yourself repeating yourself over and over, it’s time to abstract. Take, for instance, this Apache HTTP Server configuration:

{
  services.httpd.virtualHosts =
    [ { hostName = "example.org";
        documentRoot = "/webroot";
        adminAddr = "alice@example.org";
        enableUserDir = true;
      }
      { hostName = "example.org";
        documentRoot = "/webroot";
        adminAddr = "alice@example.org";
        enableUserDir = true;
        enableSSL = true;
        sslServerCert = "/root/ssl-example-org.crt";
        sslServerKey = "/root/ssl-example-org.key";
      }
    ];
}

It defines two virtual hosts with nearly identical configuration; the only difference is that the second one has SSL enabled. To prevent this duplication, we can use a let:

let
  exampleOrgCommon =
    { hostName = "example.org";
      documentRoot = "/webroot";
      adminAddr = "alice@example.org";
      enableUserDir = true;
    };
in
{
  services.httpd.virtualHosts =
    [ exampleOrgCommon
      (exampleOrgCommon // {
        enableSSL = true;
        sslServerCert = "/root/ssl-example-org.crt";
        sslServerKey = "/root/ssl-example-org.key";
      })
    ];
}

The let exampleOrgCommon = ... defines a variable named exampleOrgCommon. The // operator merges two attribute sets, so the configuration of the second virtual host is the set exampleOrgCommon extended with the SSL options.

You can write a let wherever an expression is allowed. Thus, you also could have written:

{
  services.httpd.virtualHosts =
    let exampleOrgCommon = ...; in
    [ exampleOrgCommon
      (exampleOrgCommon // { ... })
    ];
}

but not { let exampleOrgCommon = ...; in ...; } since attributes (as opposed to attribute values) are not expressions.

Functions provide another method of abstraction. For instance, suppose that we want to generate lots of different virtual hosts, all with identical configuration except for the host name. This can be done as follows:

{
  services.httpd.virtualHosts =
    let
      makeVirtualHost = name:
        { hostName = name;
          documentRoot = "/webroot";
          adminAddr = "alice@example.org";
        };
    in
      [ (makeVirtualHost "example.org")
        (makeVirtualHost "example.com")
        (makeVirtualHost "example.gov")
        (makeVirtualHost "example.nl")
      ];
}

Here, makeVirtualHost is a function that takes a single argument name and returns the configuration for a virtual host. That function is then called for several names to produce the list of virtual host configurations.

We can further improve on this by using the function map, which applies another function to every element in a list:

{
  services.httpd.virtualHosts =
    let
      makeVirtualHost = ...;
    in map makeVirtualHost
      [ "example.org" "example.com" "example.gov" "example.nl" ];
}

(The function map is called a higher-order function because it takes another function as an argument.)

What if you need more than one argument, for instance, if we want to use a different documentRoot for each virtual host? Then we can make makeVirtualHost a function that takes a set as its argument, like this:

{
  services.httpd.virtualHosts =
    let
      makeVirtualHost = { name, root }:
        { hostName = name;
          documentRoot = root;
          adminAddr = "alice@example.org";
        };
    in map makeVirtualHost
      [ { name = "example.org"; root = "/sites/example.org"; }
        { name = "example.com"; root = "/sites/example.com"; }
        { name = "example.gov"; root = "/sites/example.gov"; }
        { name = "example.nl"; root = "/sites/example.nl"; }
      ];
}

But in this case (where every root is a subdirectory of /sites named after the virtual host), it would have been shorter to define makeVirtualHost as

makeVirtualHost = name:
  { hostName = name;
    documentRoot = "/sites/${name}";
    adminAddr = "alice@example.org";
  };

Here, the construct ${...} allows the result of an expression to be spliced into a string.

The NixOS configuration mechanism is modular. If your configuration.nix becomes too big, you can split it into multiple files. Likewise, if you have multiple NixOS configurations (e.g. for different computers) with some commonality, you can move the common configuration into a shared file.

Modules have exactly the same syntax as configuration.nix. In fact, configuration.nix is itself a module. You can use other modules by including them from configuration.nix, e.g.:

{ config, pkgs, ... }:

{ imports = [ ./vpn.nix ./kde.nix ];
  services.httpd.enable = true;
  environment.systemPackages = [ pkgs.emacs ];
  ...
}

Here, we include two modules from the same directory, vpn.nix and kde.nix. The latter might look like this:

{ config, pkgs, ... }:

{ services.xserver.enable = true;
  services.xserver.displayManager.sddm.enable = true;
  services.xserver.desktopManager.plasma5.enable = true;
}

Note that both configuration.nix and kde.nix define the option environment.systemPackages. When multiple modules define an option, NixOS will try to merge the definitions. In the case of environment.systemPackages, that’s easy: the lists of packages can simply be concatenated. The value in configuration.nix is merged last, so for list-type options, it will appear at the end of the merged list. If you want it to appear first, you can use mkBefore:

boot.kernelModules = mkBefore [ "kvm-intel" ];

This causes the kvm-intel kernel module to be loaded before any other kernel modules.

For other types of options, a merge may not be possible. For instance, if two modules define services.httpd.adminAddr, nixos-rebuild will give an error:

The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.

When that happens, it’s possible to force one definition take precedence over the others:

services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";

When using multiple modules, you may need to access configuration values defined in other modules. This is what the config function argument is for: it contains the complete, merged system configuration. That is, config is the result of combining the configurations returned by every module^[1]. For example, here is a module that adds some packages to environment.systemPackages only if services.xserver.enable is set to true somewhere else:

{ config, pkgs, ... }:

{ environment.systemPackages =
    if config.services.xserver.enable then
      [ pkgs.firefox
        pkgs.thunderbird
      ]
    else
      [ ];
}

With multiple modules, it may not be obvious what the final value of a configuration option is. The command nixos-option allows you to find out:

$ nixos-option services.xserver.enable
true

$ nixos-option boot.kernelModules
[ "tun" "ipv6" "loop" ... ]

Interactive exploration of the configuration is possible using nix-repl, a read-eval-print loop for Nix expressions. It’s not installed by default; run nix-env -i nix-repl to get it. A typical use:

$ nix-repl '<nixpkgs/nixos>'

nix-repl> config.networking.hostName
"mandark"

nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts
[ "example.org" "example.gov" ]

Below is a summary of the most important syntactic constructs in the Nix expression language. It’s not complete. In particular, there are many other built-in functions. See the Nix manual for the rest.

With declarative package management, you specify which packages you want on your system by setting the option environment.systemPackages. For instance, adding the following line to configuration.nix enables the Mozilla Thunderbird email application:

environment.systemPackages = [ pkgs.thunderbird ];

The effect of this specification is that the Thunderbird package from Nixpkgs will be built or downloaded as part of the system when you run nixos-rebuild switch.

You can get a list of the available packages as follows:

$ nix-env -qaP '*' --description
nixos.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
...

The first column in the output is the attribute name, such as nixos.thunderbird. (The nixos prefix allows distinguishing between different channels that you might have.)

To “uninstall” a package, simply remove it from environment.systemPackages and run nixos-rebuild switch.

environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];

environment.systemPackages = [
  (pkgs.emacs.overrideAttrs (oldAttrs: {
    name = "emacs-25.0-pre";
    src = /path/to/my/emacs/tree;
  }))
];

nixpkgs.config.packageOverrides = pkgs:
  { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
  };

$ git clone git://github.com/NixOS/nixpkgs.git
$ cd nixpkgs

environment.systemPackages = [ pkgs.my-package ];

# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs

environment.systemPackages =
  let
    my-hello = with pkgs; stdenv.mkDerivation rec {
      name = "hello-2.8";
      src = fetchurl {
        url = "mirror://gnu/hello/${name}.tar.gz";
        sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
      };
    };
  in
  [ my-hello ];

environment.systemPackages = [ (import ./my-hello.nix) ];

with import <nixpkgs> {}; # bring all of Nixpkgs into scope

stdenv.mkDerivation rec {
  name = "hello-2.8";
  src = fetchurl {
    url = "mirror://gnu/hello/${name}.tar.gz";
    sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
  };
}

$ nix-build my-hello.nix
$ ./result/bin/hello
Hello, world!

With the command nix-env, you can install and uninstall packages from the command line. For instance, to install Mozilla Thunderbird:

$ nix-env -iA nixos.thunderbird

If you invoke this as root, the package is installed in the Nix profile /nix/var/nix/profiles/default and visible to all users of the system; otherwise, the package ends up in /nix/var/nix/profiles/per-user/username/profile and is not visible to other users. The -A flag specifies the package by its attribute name; without it, the package is installed by matching against its package name (e.g. thunderbird). The latter is slower because it requires matching against all available Nix packages, and is ambiguous if there are multiple matching packages.

Packages come from the NixOS channel. You typically upgrade a package by updating to the latest version of the NixOS channel:

$ nix-channel --update nixos

and then running nix-env -i again. Other packages in the profile are not affected; this is the crucial difference with the declarative style of package management, where running nixos-rebuild switch causes all packages to be updated to their current versions in the NixOS channel. You can however upgrade all packages for which there is a newer version by doing:

$ nix-env -u '*'

A package can be uninstalled using the -e flag:

$ nix-env -e thunderbird

Finally, you can roll back an undesirable nix-env action:

$ nix-env --rollback

nix-env has many more flags. For details, see the nix-env(1) manpage or the Nix manual.

NixOS supports file systems that are encrypted using LUKS (Linux Unified Key Setup). For example, here is how you create an encrypted Ext4 file system on the device /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d:

# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d

WARNING!
========
This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably.

Are you sure? (Type uppercase yes): YES
Enter LUKS passphrase: ***
Verify passphrase: ***

# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted
Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***

# mkfs.ext4 /dev/mapper/crypted

To ensure that this file system is automatically mounted at boot time as /, add the following to configuration.nix:

boot.initrd.luks.devices.crypted.device = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";
fileSystems."/".device = "/dev/mapper/crypted";

Should grub be used as bootloader, and /boot is located on an encrypted partition, it is necessary to add the following grub option:

boot.loader.grub.enableCryptodisk = true;

To facilitate network configuration, some desktop environments use NetworkManager. You can enable NetworkManager by setting:

networking.networkmanager.enable = true;

some desktop managers (e.g., GNOME) enable NetworkManager automatically for you.

All users that should have permission to change network settings must belong to the networkmanager group:

users.extraUsers.youruser.extraGroups = [ "networkmanager" ];

NetworkManager is controlled using either nmcli or nmtui (curses-based terminal user interface). See their manual pages for details on their usage. Some desktop environments (GNOME, KDE) have their own configuration tools for NetworkManager. On XFCE, there is no configuration tool for NetworkManager by default: by adding networkmanagerapplet to the list of system packages, the graphical applet will be installed and will launch automatically when XFCE is starting (and will show in the status tray).

Secure shell (SSH) access to your machine can be enabled by setting:

services.openssh.enable = true;

By default, root logins using a password are disallowed. They can be disabled entirely by setting services.openssh.permitRootLogin to "no".

You can declaratively specify authorised RSA/DSA public keys for a user as follows:

users.extraUsers.alice.openssh.authorizedKeys.keys =
  [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];

By default, NixOS uses DHCP (specifically, dhcpcd) to automatically configure network interfaces. However, you can configure an interface manually as follows:

networking.interfaces.eth0.ip4 = [ { address = "192.168.1.2"; prefixLength = 24; } ];

Typically you’ll also want to set a default gateway and set of name servers:

networking.defaultGateway = "192.168.1.1";
networking.nameservers = [ "8.8.8.8" ];

The host name is set using networking.hostName:

networking.hostName = "cartman";

The default host name is nixos. Set it to the empty string ("") to allow the DHCP server to provide the host name.

IPv6 is enabled by default. Stateless address autoconfiguration is used to automatically assign IPv6 addresses to all interfaces. You can disable IPv6 support globally by setting:

networking.enableIPv6 = false;

You can disable IPv6 on a single interface using a normal sysctl (in this example, we use interface eth0):

boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true;

As with IPv4 networking interfaces are automatically configured via DHCPv6. You can configure an interface manually:

networking.interfaces.eth0.ip6 = [ { address = "fe00:aa:bb:cc::2"; prefixLength = 64; } ];

For configuring a gateway, optionally with explicitly specified interface:

networking.defaultGateway6 = {
  address = "fe00::1";
  interface = "enp0s3";
}

See Section 11.3, “IPv4 Configuration” for similar examples and additional information.

NixOS has a simple stateful firewall that blocks incoming connections and other unexpected packets. The firewall applies to both IPv4 and IPv6 traffic. It is enabled by default. It can be disabled as follows:

networking.firewall.enable = false;

If the firewall is enabled, you can open specific TCP ports to the outside world:

networking.firewall.allowedTCPPorts = [ 80 443 ];

Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is enabled (services.openssh.enable = true). UDP ports can be opened through networking.firewall.allowedUDPPorts. Also of interest is

networking.firewall.allowPing = true;

to allow the machine to respond to ping requests. (ICMPv6 pings are always allowed.)

For a desktop installation using NetworkManager (e.g., GNOME), you just have to make sure the user is in the networkmanager group and you can skip the rest of this section on wireless networks.

NixOS will start wpa_supplicant for you if you enable this setting:

networking.wireless.enable = true;

NixOS lets you specify networks for wpa_supplicant declaratively:

networking.wireless.networks = {
  echelon = {
    psk = "abcdefgh";
  };
  "free.wifi" = {};
}

Be aware that keys will be written to the nix store in plaintext! When no networks are set, it will default to using a configuration file at /etc/wpa_supplicant.conf. You should edit this file yourself to define wireless networks, WPA keys and so on (see wpa_supplicant.conf(5)).

If you are using WPA2 the wpa_passphrase tool might be useful to generate the wpa_supplicant.conf.

# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf

After you have edited the wpa_supplicant.conf, you need to restart the wpa_supplicant service.

# systemctl restart wpa_supplicant.service

You can use networking.localCommands to specify shell commands to be run at the end of network-setup.service. This is useful for doing network configuration not covered by the existing NixOS modules. For instance, to statically configure an IPv6 address:

networking.localCommands =
  ''
    ip -6 addr add 2001:610:685:1::1/64 dev eth0
  '';

When developing kernel modules it's often convenient to run edit-compile-run loop as quickly as possible. See below snippet as an example of developing mellanox drivers.

$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev
$ nix-shell '<nixpkgs>' -A linuxPackages.kernel
$ unpackPhase
$ cd linux-*
$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko

You also need to configure a MariaDB or MySQL database and -user for piwik yourself, and enter those credentials in your browser. You can use passwordless database authentication via the UNIX_SOCKET authentication plugin with the following SQL commands:

        # For MariaDB
        INSTALL PLUGIN unix_socket SONAME 'auth_socket';
        CREATE DATABASE piwik;
        CREATE USER 'piwik'@'localhost' IDENTIFIED WITH unix_socket;
        GRANT ALL PRIVILEGES ON piwik.* TO 'piwik'@'localhost';

        # For MySQL
        INSTALL PLUGIN auth_socket SONAME 'auth_socket.so';
        CREATE DATABASE piwik;
        CREATE USER 'piwik'@'localhost' IDENTIFIED WITH auth_socket;
        GRANT ALL PRIVILEGES ON piwik.* TO 'piwik'@'localhost';
      

Then fill in piwik as database user and database name, and leave the password field blank. This authentication works by allowing only the piwik unix user to authenticate as the piwik database user (without needing a password), but no other users. For more information on passwordless login, see https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/.

Of course, you can use password based authentication as well, e.g. when the database is not on the same host.

You only need to take backups of your MySQL database and the /var/lib/piwik/config/config.ini.php file. Use a user in the piwik group or root to access the file. For more information, see https://piwik.org/faq/how-to-install/faq_138/.

You can use other web servers by forwarding calls for index.php and piwik.php to the /run/phpfpm-piwik.sock fastcgi unix socket. You can use the nginx configuration in the module code as a reference to what else should be configured.

Taskserver does all of its authentication via TLS using client certificates, so you either need to roll your own CA or purchase a certificate from a known CA, which allows creation of client certificates. These certificates are usually advertised as “server certificates”.

So in order to make it easier to handle your own CA, there is a helper tool called nixos-taskserver which manages the custom CA along with Taskserver organisations, users and groups.

While the client certificates in Taskserver only authenticate whether a user is allowed to connect, every user has its own UUID which identifies it as an entity.

With nixos-taskserver the client certificate is created along with the UUID of the user, so it handles all of the credentials needed in order to setup the Taskwarrior client to work with a Taskserver.

Because Taskserver by default only provides scripts to setup users imperatively, the nixos-taskserver tool is used for addition and deletion of organisations along with users and groups defined by services.taskserver.organisations and as well for imperative set up.

The tool is designed to not interfere if the command is used to manually set up some organisations, users or groups.

For example if you add a new organisation using nixos-taskserver org add foo, the organisation is not modified and deleted no matter what you define in services.taskserver.organisations, even if you're adding the same organisation in that option.

The tool is modelled to imitate the official taskd command, documentation for each subcommand can be shown by using the --help switch.

Everything is done according to what you specify in the module options, however in order to set up a Taskwarrior client for synchronisation with a Taskserver instance, you have to transfer the keys and certificates to the client machine.

This is done using nixos-taskserver user export $orgname $username which is printing a shell script fragment to stdout which can either be used verbatim or adjusted to import the user on the client machine.

For example, let's say you have the following configuration:

{
  services.taskserver.enable = true;
  services.taskserver.fqdn = "server";
  services.taskserver.listenHost = "::";
  services.taskserver.organisations.my-company.users = [ "alice" ];
}

This creates an organisation called my-company with the user alice.

Now in order to import the alice user to another machine alicebox, all we need to do is something like this:

$ ssh server nixos-taskserver user export my-company alice | sh

Of course, if no SSH daemon is available on the server you can also copy & paste it directly into a shell.

After this step the user should be set up and you can start synchronising your tasks for the first time with task sync init on alicebox.

Subsequent synchronisation requests merely require the command task sync after that stage.

If you set any options within service.taskserver.pki.manual.*, nixos-taskserver won't issue certificates, but you can still use it for adding or removing user accounts.

The gitlab service exposes only an Unix socket at /run/gitlab/gitlab-workhorse.socket. You need to configure a webserver to proxy HTTP requests to the socket.

For instance, the following configuration could be used to use nginx as frontend proxy:

    services.nginx = {
      enable = true;
      recommendedGzipSettings = true;
      recommendedOptimisation = true;
      recommendedProxySettings = true;
      recommendedTlsSettings = true;
      virtualHosts."git.example.com" = {
        enableACME = true;
        forceSSL = true;
        locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";
      };
    };
'';

Gitlab depends on both PostgreSQL and Redis and will automatically enable both services. In the case of PostgreSQL, a database and a role will be created.

The default state dir is /var/gitlab/state. This is where all data like the repositories and uploads will be stored.

A basic configuration with some custom settings could look like this:

services.gitlab = {
  enable = true;
  databasePassword = "eXaMpl3";
  initialRootPassword = "UseNixOS!";
  https = true;
  host = "git.example.com";
  port = 443;
  user = "git";
  group = "git";
  smtp = {
    enable = true;
    address = "localhost";
    port = 25;
  };
  secrets = {
    db = "uPgq1gtwwHiatiuE0YHqbGa5lEIXH7fMsvuTNgdzJi8P0Dg12gibTzBQbq5LT7PNzcc3BP9P1snHVnduqtGF43PgrQtU7XL93ts6gqe9CBNhjtaqUwutQUDkygP5NrV6";
    secret = "devzJ0Tz0POiDBlrpWmcsjjrLaltyiAdS8TtgT9YNBOoUcDsfppiY3IXZjMVtKgXrFImIennFGOpPN8IkP8ATXpRgDD5rxVnKuTTwYQaci2NtaV1XxOQGjdIE50VGsR3";
    otp = "e1GATJVuS2sUh7jxiPzZPre4qtzGGaS22FR50Xs1TerRVdgI3CBVUi5XYtQ38W4xFeS4mDqi5cQjExE838iViSzCdcG19XSL6qNsfokQP9JugwiftmhmCadtsnHErBMI";
    jws = ''
      -----BEGIN RSA PRIVATE KEY-----
      MIIEpAIBAAKCAQEArrtx4oHKwXoqUbMNqnHgAklnnuDon3XG5LJB35yPsXKv/8GK
      ke92wkI+s1Xkvsp8tg9BIY/7c6YK4SR07EWL+dB5qwctsWR2Q8z+/BKmTx9D99pm
      hnsjuNIXTF7BXrx3RX6BxZpH5Vzzh9nCwWKT/JCFqtwH7afNGGL7aMf+hdaiUg/Q
      SD05yRObioiO4iXDolsJOhrnbZvlzVHl1ZYxFJv0H6/Snc0BBA9Fl/3uj6ANpbjP
      eXF1SnJCqT87bj46r5NdVauzaRxAsIfqHroHK4UZ98X5LjGQFGvSqTvyjPBS4I1i
      s7VJU28ObuutHxIxSlH0ibn4HZqWmKWlTS652wIDAQABAoIBAGtPcUTTw2sJlR3x
      4k2wfAvLexkHNbZhBdKEa5JiO5mWPuLKwUiZEY2CU7Gd6csG3oqNWcm7/IjtC7dz
      xV8p4yp8T4yq7vQIJ93B80NqTLtBD2QTvG2RCMJEPMzJUObWxkVmyVpLQyZo7KOd
      KE/OM+aj94OUeEYLjRkSCScz1Gvq/qFG/nAy7KPCmN9JDHuhX26WHo2Rr1OnPNT/
      7diph0bB9F3b8gjjNTqXDrpdAqVOgR/PsjEBz6DMY+bdyMIn87q2yfmMexxRofN6
      LulpzSaa6Yup8N8H6PzVO6KAkQuf1aQRj0sMwGk1IZEnj6I0KbuHIZkw21Nc6sf2
      ESFySDECgYEA1PnCNn5tmLnwe62Ttmrzl20zIS3Me1gUVJ1NTfr6+ai0I9iMYU21
      5czuAjJPm9JKQF2vY8UAaCj2ZoObtHa/anb3xsCd8NXoM3iJq5JDoXI1ldz3Y+ad
      U/bZUg1DLRvAniTuXmw9iOTwTwPxlDIGq5k+wG2Xmi1lk7zH8ezr9BMCgYEA0gfk
      EhgcmPH8Z5cU3YYwOdt6HSJOM0OyN4k/5gnkv+HYVoJTj02gkrJmLr+mi1ugKj46
      7huYO9TVnrKP21tmbaSv1dp5hS3letVRIxSloEtVGXmmdvJvBRzDWos+G+KcvADi
      fFCz6w8v9NmO40CB7y/3SxTmSiSxDQeoi9LhDBkCgYEAsPgMWm25sfOnkY2NNUIv
      wT8bAlHlHQT2d8zx5H9NttBpR3P0ShJhuF8N0sNthSQ7ULrIN5YGHYcUH+DyLAWU
      TuomP3/kfa+xL7vUYb269tdJEYs4AkoppxBySoz8qenqpz422D0G8M6TpIS5Y5Qi
      GMrQ6uLl21YnlpiCaFOfSQMCgYEAmZxj1kgEQmhZrnn1LL/D7czz1vMMNrpAUhXz
      wg9iWmSXkU3oR1sDIceQrIhHCo2M6thwyU0tXjUft93pEQocM/zLDaGoVxtmRxxV
      J08mg8IVD3jFoyFUyWxsBIDqgAKRl38eJsXvkO+ep3mm49Z+Ma3nM+apN3j2dQ0w
      3HLzXaECgYBFLMEAboVFwi5+MZjGvqtpg2PVTisfuJy2eYnPwHs+AXUgi/xRNFjI
      YHEa7UBPb5TEPSzWImQpETi2P5ywcUYL1EbN/nqPWmjFnat8wVmJtV4sUpJhubF4
      Vqm9LxIWc1uQ1q1HDCejRIxIN3aSH+wgRS3Kcj8kCTIoXd1aERb04g==
      -----END RSA PRIVATE KEY-----
    '';
  };
  extraConfig = {
    gitlab = {
      email_from = "gitlab-no-reply@example.com";
      email_display_name = "Example GitLab";
      email_reply_to = "gitlab-no-reply@example.com";
      default_projects_features = { builds = false; };
    };
  };
};

If you're setting up a new Gitlab instance, generate new secrets. You for instance use tr -dc A-Za-z0-9 < /dev/urandom | head -c 128 to generate a new secret. Gitlab encrypts sensitive data stored in the database. If you're restoring an existing Gitlab instance, you must specify the secrets secret from config/secrets.yml located in your Gitlab state folder.

Refer to Appendix A, Configuration Options for all available configuration options for the services.gitlab module.

You can run Gitlab's rake tasks with gitlab-rake which will be available on the system when gitlab is enabled. You will have to run the command as the user that you configured to run gitlab with.

For example, to backup a Gitlab instance:

$ sudo -u git -H gitlab-rake gitlab:backup:create

A list of all availabe rake tasks can be obtained by running:

$ sudo -u git -H gitlab-rake -T

Emacs can be installed in the normal way for Nix (see Chapter 6, Package Management). In addition, a NixOS service can be enabled.

/*
This is a nix expression to build Emacs and some Emacs packages I like
from source on any distribution where Nix is installed. This will install
all the dependencies from the nixpkgs repository and build the binary files
without interfering with the host distribution.

To build the project, type the following from the current directory:

$ nix-build emacs.nix

To run the newly compiled executable:

$ ./result/bin/emacs
*/
{ pkgs ? import <nixpkgs> {} }: 

let
  myEmacs = pkgs.emacs; 
  emacsWithPackages = (pkgs.emacsPackagesNgGen myEmacs).emacsWithPackages; 
in
  emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ 
    magit          # ; Integrate git <C-x g>
    zerodark-theme # ; Nicolas' theme
  ]) ++ (with epkgs.melpaPackages; [ 
    undo-tree      # ; <C-x u> to show the undo tree
    zoom-frm       # ; increase/decrease font size for all buffers %lt;C-x C-+>
  ]) ++ (with epkgs.elpaPackages; [ 
    auctex         # ; LaTeX mode
    beacon         # ; highlight my cursor when scrolling
    nameless       # ; hide current package name everywhere in elisp code
  ]) ++ [
    pkgs.notmuch   # From main packages set 
  ])

$ nix-build emacs.nix
$ ./result/bin/emacs -q

nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.elpaPackages
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaPackages
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaStablePackages
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.orgPackages

{
 environment.systemPackages = [
   # [...]
   (import /path/to/emacs.nix { inherit pkgs; })
  ];
}

{
  packageOverrides = super: let self = super.pkgs; in {
    myemacs = import /path/to/emacs.nix { pkgs = self; };
  };
}

{ pkgs ? import <nixpkgs> {} }:
let
  myEmacs = (pkgs.emacs.override {
    # Use gtk3 instead of the default gtk2
    withGTK3 = true;
    withGTK2 = false;
  }).overrideAttrs (attrs: {
    # I don't want emacs.desktop file because I only use
    # emacsclient.
    postInstall = (attrs.postInstall or "") + ''
      rm $out/share/applications/emacs.desktop
    '';
  });
in [...]

NixOS provides an optional systemd service which launches Emacs daemon with the user's login session.

Source: modules/services/editors/emacs.nix

services.emacs.enable = true;
services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; };

$ nixos-rebuild switch  # to activate the new configuration.nix
$ systemctl --user daemon-reload        # to force systemd reload
$ systemctl --user start emacs.service  # to start the Emacs daemon

emacsclient FILENAME
emacsclient --create-frame  # opens a new frame (window)
emacsclient --create-frame --tty  # opens a new frame on the current terminal

alias vi=$EDITOR

services.emacs.enable = false;
services.emacs.install = true;

systemctl --user enable emacs

The Emacs init file should be changed to load the extension packages at startup:

(require 'package)

;; optional. makes unpure packages archives unavailable
(setq package-archives nil)

(setq package-enable-at-startup nil)
(package-initialize)

After the declarative emacs package configuration has been tested, previously downloaded packages can be cleaned up by removing ~/.emacs.d/elpa (do make a backup first, in case you forgot a package).

<?xml version="1.0"?>
<!--
  To let emacs find this file, evaluate:
  (add-to-list 'rng-schema-locating-files "~/.emacs.d/schemas.xml")
-->
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
  <!--
    Use this variation if pkgs.docbook5 is added to environment.systemPackages
  -->
  <namespace ns="http://docbook.org/ns/docbook"
             uri="/run/current-system/sw/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
  <!--
    Use this variation if installing schema with "nix-env -iA pkgs.docbook5".
  <namespace ns="http://docbook.org/ns/docbook"
             uri="../.nix-profile/share/xml/docbook-5.0/rng/docbookxi.rnc"/>
  -->
</locatingRules>

To enable PostgreSQL, add the following to your configuration.nix:

services.postgresql.enable = true;
services.postgresql.package = pkgs.postgresql94;

Note that you are required to specify the desired version of PostgreSQL (e.g. pkgs.postgresql94). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for services.postgresql.package such as the most recent release of PostgreSQL.

By default, PostgreSQL stores its databases in /var/db/postgresql. You can override this using services.postgresql.dataDir, e.g.

services.postgresql.dataDir = "/data/postgresql";

FIXME: document dump/upgrade/load cycle.

FIXME: auto-generated list of module options.

You need to have a running HTTP server for verification. The server must have a webroot defined that can serve .well-known/acme-challenge. This directory must be writeable by the user that will run the ACME client.

For instance, this generic snippet could be used for Nginx:

http {
  server {
    server_name _;
    listen 80;
    listen [::]:80;

    location /.well-known/acme-challenge {
      root /var/www/challenges;
    }

    location / {
      return 301 https://$host$request_uri;
    }
  }
}

To enable ACME certificate retrieval & renewal for a certificate for foo.example.com, add the following in your configuration.nix:

security.acme.certs."foo.example.com" = {
  webroot = "/var/www/challenges";
  email = "foo@example.com";
};

The private key key.pem and certificate fullchain.pem will be put into /var/lib/acme/foo.example.com. The target directory can be configured with the option security.acme.directory.

Refer to Appendix A, Configuration Options for all available configuration options for the security.acme module.

NixOS supports fetching ACME certificates for you by setting enableACME = true; in a virtualHost config. We first create self-signed placeholder certificates in place of the real ACME certs. The placeholder certs are overwritten when the ACME certs arrive. For foo.example.com the config would look like.

services.nginx = {
  enable = true;
  virtualHosts = {
    "foo.example.com" = {
      forceSSL = true;
      enableACME = true;
      locations."/" = {
        root = "/var/www";
      };
    };
  };
}

IBus is an Intelligent Input Bus. It provides full featured and user friendly input method user interface.

The following snippet can be used to configure IBus:

i18n.inputMethod = {
  enabled = "ibus";
  ibus.engines = with pkgs.ibus-engines; [ anthy hangul mozc ];
};

i18n.inputMethod.ibus.engines is optional and can be used to add extra IBus engines.

Available extra IBus engines are:

To use any input method, the package must be added in the configuration, as shown above, and also (after running nixos-rebuild) the input method must be added from IBus' preference dialog.

Fcitx is an input method framework with extension support. It has three built-in Input Method Engine, Pinyin, QuWei and Table-based input methods.

The following snippet can be used to configure Fcitx:

i18n.inputMethod = {
  enabled = "fcitx";
  fcitx.engines = with pkgs.fcitx-engines; [ mozc hangul m17n ];
};

i18n.inputMethod.fcitx.engines is optional and can be used to add extra Fcitx engines.

Available extra Fcitx engines are:

Nabi is an easy to use Korean X input method. It allows you to enter phonetic Korean characters (hangul) and pictographic Korean characters (hanja).

The following snippet can be used to configure Nabi:

i18n.inputMethod = {
  enabled = "nabi";
};

Uim (short for "universal input method") is a multilingual input method framework. Applications can use it through so-called bridges.

The following snippet can be used to configure uim:

i18n.inputMethod = {
  enabled = "uim";
};

Note: The i18n.inputMethod.uim.toolbar option can be used to choose uim toolbar.

We’ll cover imperative container management using nixos-container first. Be aware that container management is currently only possible as root.

You create a container with identifier foo as follows:

# nixos-container create foo

This creates the container’s root directory in /var/lib/containers/foo and a small configuration file in /etc/containers/foo.conf. It also builds the container’s initial system configuration and stores it in /nix/var/nix/profiles/per-container/foo/system. You can modify the initial configuration of the container on the command line. For instance, to create a container that has sshd running, with the given public key for root:

# nixos-container create foo --config '
  services.openssh.enable = true;
  users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];
'

Creating a container does not start it. To start the container, run:

# nixos-container start foo

This command will return as soon as the container has booted and has reached multi-user.target. On the host, the container runs within a systemd unit called container@container-name.service. Thus, if something went wrong, you can get status info using systemctl:

# systemctl status container@foo

If the container has started successfully, you can log in as root using the root-login operation:

# nixos-container root-login foo
[root@foo:~]#

Note that only root on the host can do this (since there is no authentication). You can also get a regular login prompt using the login operation, which is available to all users on the host:

# nixos-container login foo
foo login: alice
Password: ***

With nixos-container run, you can execute arbitrary commands in the container:

# nixos-container run foo -- uname -a
Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux

There are several ways to change the configuration of the container. First, on the host, you can edit /var/lib/container/name/etc/nixos/configuration.nix, and run

# nixos-container update foo

This will build and activate the new configuration. You can also specify a new configuration on the command line:

# nixos-container update foo --config '
  services.httpd.enable = true;
  services.httpd.adminAddr = "foo@example.org";
  networking.firewall.allowedTCPPorts = [ 80 ];
'

# curl http://$(nixos-container show-ip foo)/
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…

However, note that this will overwrite the container’s /etc/nixos/configuration.nix.

Alternatively, you can change the configuration from within the container itself by running nixos-rebuild switch inside the container. Note that the container by default does not have a copy of the NixOS channel, so you should run nix-channel --update first.

Containers can be stopped and started using nixos-container stop and nixos-container start, respectively, or by using systemctl on the container’s service unit. To destroy a container, including its file system, do

# nixos-container destroy foo

You can also specify containers and their configuration in the host’s configuration.nix. For example, the following specifies that there shall be a container named database running PostgreSQL:

containers.database =
  { config =
      { config, pkgs, ... }:
      { services.postgresql.enable = true;
        services.postgresql.package = pkgs.postgresql96;
      };
  };

If you run nixos-rebuild switch, the container will be built. If the container was already running, it will be updated in place, without rebooting. The container can be configured to start automatically by setting containers.database.autoStart = true in its configuration.

By default, declarative containers share the network namespace of the host, meaning that they can listen on (privileged) ports. However, they cannot change the network configuration. You can give a container its own network as follows:

containers.database =
  { privateNetwork = true;
    hostAddress = "192.168.100.10";
    localAddress = "192.168.100.11";
  };

This gives the container a private virtual Ethernet interface with IP address 192.168.100.11, which is hooked up to a virtual Ethernet interface on the host with IP address 192.168.100.10. (See the next section for details on container networking.)

To disable the container, just remove it from configuration.nix and run nixos-rebuild switch. Note that this will not delete the root directory of the container in /var/lib/containers. Containers can be destroyed using the imperative method: nixos-container destroy foo.

Declarative containers can be started and stopped using the corresponding systemd service, e.g. systemctl start container@database.

When you create a container using nixos-container create, it gets it own private IPv4 address in the range 10.233.0.0/16. You can get the container’s IPv4 address as follows:

# nixos-container show-ip foo
10.233.4.2

$ ping -c1 10.233.4.2
64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms

Networking is implemented using a pair of virtual Ethernet devices. The network interface in the container is called eth0, while the matching interface in the host is called ve-container-name (e.g., ve-foo). The container has its own network namespace and the CAP_NET_ADMIN capability, so it can perform arbitrary network configuration such as setting up firewall rules, without affecting or having access to the host’s network.

By default, containers cannot talk to the outside network. If you want that, you should set up Network Address Translation (NAT) rules on the host to rewrite container traffic to use your external IP address. This can be accomplished using the following configuration on the host:

networking.nat.enable = true;
networking.nat.internalInterfaces = ["ve-+"];
networking.nat.externalInterface = "eth0";

where eth0 should be replaced with the desired external interface. Note that ve-+ is a wildcard that matches all container interfaces.

If you are using Network Manager, you need to explicitly prevent it from managing container interfaces:

networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];

If NixOS fails to boot, there are a number of kernel command line parameters that may help you to identify or fix the issue. You can add these parameters in the GRUB boot menu by pressing “e” to modify the selected boot entry and editing the line starting with linux. The following are some useful kernel command line parameters that are recognised by the NixOS boot scripts or by systemd:

For more parameters recognised by systemd, see systemd(1).

If no login prompts or X11 login screens appear (e.g. due to hanging dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start rescue mode (described above). (Also note that since most units have a 90-second timeout before systemd gives up on them, the agetty login prompts should appear eventually unless something is very wrong.)

You can enter rescue mode by running:

# systemctl rescue

This will eventually give you a single-user root shell. Systemd will stop (almost) all system services. To get out of maintenance mode, just exit from the rescue shell.

After running nixos-rebuild to switch to a new configuration, you may find that the new configuration doesn’t work very well. In that case, there are several ways to return to a previous configuration.

First, the GRUB boot manager allows you to boot into any previous configuration that hasn’t been garbage-collected. These configurations can be found under the GRUB submenu “NixOS - All configurations”. This is especially useful if the new configuration fails to boot. After the system has booted, you can make the selected configuration the default for subsequent boots:

# /run/current-system/bin/switch-to-configuration boot

Second, you can switch to the previous configuration in a running system:

# nixos-rebuild switch --rollback

This is equivalent to running:

# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch

where N is the number of the NixOS system configuration. To get a list of the available configurations, do:

$ ls -l /nix/var/nix/profiles/system-*-link
...
lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055

After a system crash, it’s possible for files in the Nix store to become corrupted. (For instance, the Ext4 file system has the tendency to replace un-synced files with zero bytes.) NixOS tries hard to prevent this from happening: it performs a sync before switching to a new configuration, and Nix’s database is fully transactional. If corruption still occurs, you may be able to fix it automatically.

If the corruption is in a path in the closure of the NixOS system configuration, you can fix it by doing

# nixos-rebuild switch --repair

This will cause Nix to check every path in the closure, and if its cryptographic hash differs from the hash recorded in Nix’s database, the path is rebuilt or redownloaded.

You can also scan the entire Nix store for corrupt paths:

# nix-store --verify --check-contents --repair

Any corrupt paths will be redownloaded if they’re available in a binary cache; otherwise, they cannot be repaired.

Nix uses a so-called binary cache to optimise building a package from source into downloading it as a pre-built binary. That is, whenever a command like nixos-rebuild needs a path in the Nix store, Nix will try to download that path from the Internet rather than build it from source. The default binary cache is https://cache.nixos.org/. If this cache is unreachable, Nix operations may take a long time due to HTTP connection timeouts. You can disable the use of the binary cache by adding --option use-binary-caches false, e.g.

# nixos-rebuild switch --option use-binary-caches false

If you have an alternative binary cache at your disposal, you can use it instead:

# nixos-rebuild switch --option binary-caches http://my-cache.example.org/

An option declaration specifies the name, type and description of a NixOS configuration option. It is invalid to define an option that hasn’t been declared in any module. An option declaration generally looks like this:

options = {
  name = mkOption {
    type = type specification;
    default = default value;
    example = example value;
    description = "Description for use in the NixOS manual.";
  };
};

The function mkOption accepts the following arguments.

services.xserver.displayManager.enable = mkOption {
  description = "Display manager to use";
  type = with types; nullOr (enum [ ]);
};

services.xserver.displayManager.enable = mkOption {
  type = with types; nullOr (enum [ "slim" ]);
};

services.xserver.displayManager.enable = mkOption {
  type = with types; nullOr (enum [ "sddm" ]);
};

Option types are a way to put constraints on the values a module option can take. Types are also responsible of how values are merged in case of multiple value definitions.

options.mod = mkOption {
  description = "submodule example";
  type = with types; submodule {
    options = {
      foo = mkOption {
        type = int;
      };
      bar = mkOption {
        type = str;
      };
    };
  };
};

let
  modOptions = {
    options = {
      foo = mkOption {
        type = int;
      };
      bar = mkOption {
        type = int;
      };
    };
  };
in
options.mod = mkOption {
  description = "submodule example";
  type = with types; submodule modOptions;
};

options.mod = mkOption {
  description = "submodule example";
  type = with types; listOf (submodule {
    options = {
      foo = mkOption {
        type = int;
      };
      bar = mkOption {
        type = str;
      };
    };
  });
};

config.mod = [
  { foo = 1; bar = "one"; }
  { foo = 2; bar = "two"; }
];

options.mod = mkOption {
  description = "submodule example";
  type = with types; attrsOf (submodule {
    options = {
      foo = mkOption {
        type = int;
      };
      bar = mkOption {
        type = str;
      };
    };
  });
};

config.mod.one = { foo = 1; bar = "one"; };
config.mod.two = { foo = 2; bar = "two"; };

Option definitions are generally straight-forward bindings of values to option names, like

config = {
  services.httpd.enable = true;
};

However, sometimes you need to wrap an option definition or set of option definitions in a property to achieve certain effects:

config = if config.services.httpd.enable then {
  environment.systemPackages = [ ... ];
  ...
} else {};

config = if config.services.httpd.enable then {
  services.httpd.enable = false;
} else {
  services.httpd.enable = true;
};

config = mkIf config.services.httpd.enable {
  environment.systemPackages = [ ... ];
  ...
};

config = {
  environment.systemPackages = if config.services.httpd.enable then [ ... ] else [];
  ...
};

services.openssh.enable = mkOverride 10 false;

config = mkMerge
  [ # Unconditional stuff.
    { environment.systemPackages = [ ... ];
    }
    # Conditional stuff.
    (mkIf config.services.bla.enable {
      environment.systemPackages = [ ... ];
    })
  ];

When configuration problems are detectable in a module, it is a good idea to write an assertion or warning. Doing so provides clear feedback to the user and prevents errors after the build.

Although Nix has the abort and builtins.trace functions to perform such tasks, they are not ideally suited for NixOS modules. Instead of these functions, you can declare your warnings and assertions using the NixOS module system.

{ config, lib, ... }:
{
  config = lib.mkIf config.services.foo.enable {
    warnings =
      if config.services.foo.bar
      then [ ''You have enabled the bar feature of the foo service.
               This is known to cause some specific problems in certain situations.
               '' ]
      else [];
  }
}

{ config, lib, ... }:
{
  config = lib.mkIf config.services.syslogd.enable {
    assertions =
      [ { assertion = !config.services.rsyslogd.enable;
          message = "rsyslogd conflicts with syslogd";
        }
      ];
  }
}

Like Nix packages, NixOS modules can declare meta-attributes to provide extra information. Module meta attributes are defined in the meta.nix special module.

meta is a top level attribute like options and config. Available meta-attributes are maintainers and doc.

Each of the meta-attributes must be defined at most once per module file.

{ config, lib, pkgs, ... }:
{
  options = {
    ...
  };

  config = {
    ...
  };

  meta = {
    maintainers = with lib.maintainers; [ ericsagnes ]; 
    doc = ./default.xml; 
  };
}

$ nix-build nixos/release.nix -A manual

Modules that are imported can also be disabled. The option declarations and config implementation of a disabled module will be ignored, allowing another to take it's place. This can be used to import a set of modules from another channel while keeping the rest of the system on a stable release.

disabledModules is a top level attribute like imports, options and config. It contains a list of modules that will be disabled. This can either be the full path to the module or a string with the filename relative to the modules path (eg. <nixpkgs/nixos/modules> for nixos).

This example will replace the existing postgresql module with the version defined in the nixos-unstable channel while keeping the rest of the modules and packages from the original nixos channel. This only overrides the module definition, this won't use postgresql from nixos-unstable unless explicitly configured to do so.

{ config, lib, pkgs, ... }:

{
  disabledModules = [ "services/databases/postgresql.nix" ];

  imports =
    [ # Use postgresql service from nixos-unstable channel.
      # sudo nix-channel --add http://nixos.org/channels/nixos-unstable nixos-unstable
      <nixos-unstable/nixos/modules/services/databases/postgresql.nix>
    ];

  services.postgresql.enable = true;
}

This example shows how to define a custom module as a replacement for an existing module. Importing this module will disable the original module without having to know it's implementation details.

{ config, lib, pkgs, ... }:

with lib;

let
  cfg = config.programs.man;
in

{
  disabledModules = [ "services/programs/man.nix" ];

  options = {
    programs.man.enable = mkOption {
      type = types.bool;
      default = true;
      description = "Whether to enable manual pages.";
    };
  };

  config = mkIf cfg.enabled {
    warnings = [ "disabled manpages for production deployments." ];
  };
}

The DocBook sources of the NixOS Manual are in the nixos/doc/manual subdirectory of the Nixpkgs repository. If you make modifications to the manual, it's important to build it before committing. You can do that as follows:

nix-build nixos/release.nix -A manual.x86_64-linux

When this command successfully finishes, it will tell you where the manual got generated. The HTML will be accessible through the result symlink at ./result/share/doc/nixos/index.html.

For general information on how to write in DocBook, see DocBook 5: The Definitive Guide.

Emacs nXML Mode is very helpful for editing DocBook XML because it validates the document as you write, and precisely locates errors. To use it, see Section 17.3.3, “Editing DocBook 5 XML Documents”.

Pandoc can generate DocBook XML from a multitude of formats, which makes a good starting point.

pandoc -f markdown_github -t docbook5 docs.md -o my-section.md

Pandoc can also quickly convert a single section.xml to HTML, which is helpful when drafting.

Sometimes writing valid DocBook is simply too difficult. In this case, submit your documentation updates in a GitHub Issue and someone will handle the conversion to XML for you.

You can use an existing topic as a basis for the new topic or create a topic from scratch.

Keep the following guidelines in mind when you create and add a topic:

Open the parent XML file and add an xi:include element to the list of chapters with the file name of the topic that you created. If you created a section, you add the file to the chapter file. If you created a chapter, you add the file to the part file.

If the topic is about configuring a NixOS module, it can be automatically included in the manual by using the meta.doc attribute. See Section 31.5, “Meta Attributes” for an explanation.

A NixOS test is a Nix expression that has the following structure:

import ./make-test.nix {

  # Either the configuration of a single machine:
  machine =
    { config, pkgs, ... }:
    { configuration…
    };

  # Or a set of machines:
  nodes =
    { machine1 =
        { config, pkgs, ... }: { … };
      machine2 =
        { config, pkgs, ... }: { … };
      …
    };

  testScript =
    ''
      Perl code…
    '';
}

The attribute testScript is a bit of Perl code that executes the test (described below). During the test, it will start one or more virtual machines, the configuration of which is described by the attribute machine (if you need only one machine in your test) or by the attribute nodes (if you need multiple machines). For instance, login.nix only needs a single machine to test whether users can log in on the virtual console, whether device ownership is correctly maintained when switching between consoles, and so on. On the other hand, nfs.nix, which tests NFS client and server functionality in the Linux kernel (including whether locks are maintained across server crashes), requires three machines: a server and two clients.

There are a few special NixOS configuration options for test VMs:

For more options, see the module qemu-vm.nix.

The test script is a sequence of Perl statements that perform various actions, such as starting VMs, executing commands in the VMs, and so on. Each virtual machine is represented as an object stored in the variable $name, where name is the identifier of the machine (which is just machine if you didn’t specify multiple machines using the nodes attribute). For instance, the following starts the machine, waits until it has finished booting, then executes a command and checks that the output is more-or-less correct:

$machine->start;
$machine->waitForUnit("default.target");
$machine->succeed("uname") =~ /Linux/;

The first line is actually unnecessary; machines are implicitly started when you first execute an action on them (such as waitForUnit or succeed). If you have multiple machines, you can speed up the test by starting them in parallel:

startAll;

The following methods are available on machine objects:

You can run tests using nix-build. For example, to run the test login.nix, you just do:

$ nix-build '<nixpkgs/nixos/tests/login.nix>'

or, if you don’t want to rely on NIX_PATH:

$ cd /my/nixpkgs/nixos/tests
$ nix-build login.nix
…
running the VM test script
machine: QEMU running (pid 8841)
…
6 out of 6 tests succeeded

After building/downloading all required dependencies, this will perform a build that starts a QEMU/KVM virtual machine containing a NixOS system. The virtual machine mounts the Nix store of the host; this makes VM creation very fast, as no disk image needs to be created. Afterwards, you can view a pretty-printed log of the test:

$ firefox result/log.html

The test itself can be run interactively. This is particularly useful when developing or debugging a test:

$ nix-build nixos/tests/login.nix -A driver
$ ./result/bin/nixos-test-driver
starting VDE switch for network 1
>

You can then take any Perl statement, e.g.

> startAll
> testScript
> $machine->succeed("touch /tmp/foo")

The function testScript executes the entire test script and drops you back into the test driver command line upon its completion. This allows you to inspect the state of the VMs after the test (e.g. to debug the test script).

To just start and experiment with the VMs, run:

$ nix-build nixos/tests/login.nix -A driver
$ ./result/bin/nixos-run-vms

The script nixos-run-vms starts the virtual machines defined by test. The root file system of the VMs is created on the fly and kept across VM restarts in ./hostname.qcow2.

Going through an example of releasing NixOS 17.09: