NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI installation is by and large the same as a BIOS installation. The differences are mentioned in the steps that follow.

The installation media can be burned to a CD, or now more commonly, "burned" to a USB drive (see Section 2.5.1, “Booting from a USB Drive”).

The installation media contains a basic NixOS installation. When it’s finished booting, it should have detected most of your hardware.

The NixOS manual is available on virtual console 8 (press Alt+F8 to access) or by running nixos-help.

You are logged-in automatically as nixos. The nixos user account has an empty password so you can use sudo without a password.

If you downloaded the graphical ISO image, you can run systemctl start display-manager to start the desktop environment. If you want to continue on the terminal, you can use loadkeys to switch to your preferred keyboard layout. (We even provide neo2 via loadkeys de neo!)

The NixOS installer doesn’t do any partitioning or formatting, so you need to do that yourself.

The NixOS installer ships with multiple partitioning tools. The examples below use parted, but also provides fdisk, gdisk, cfdisk, and cgdisk.

The recommended partition scheme differs depending if the computer uses Legacy Boot or UEFI.

To summarise, Example 2.3, “Commands for Installing NixOS on /dev/sda” shows a typical sequence of commands for installing NixOS on an empty hard drive (here /dev/sda). Example 2.4, “NixOS Configuration” shows a corresponding configuration Nix expression.

# parted /dev/sda -- mklabel msdos
# parted /dev/sda -- mkpart primary 1MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%

# parted /dev/sda -- mklabel gpt
# parted /dev/sda -- mkpart primary 512MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
# parted /dev/sda -- set 3 boot on

# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
# mkfs.fat -F 32 -n boot /dev/sda3        # (for UEFI systems only)
# mount /dev/disk/by-label/nixos /mnt
# mkdir -p /mnt/boot                      # (for UEFI systems only)
# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
# nixos-install
# reboot

{ config, pkgs, ... }: {
  imports = [
    # Include the results of the hardware scan.
    ./hardware-configuration.nix
  ];

  boot.loader.grub.device = "/dev/sda";   # (for BIOS systems only)
  boot.loader.systemd-boot.enable = true; # (for UEFI systems only)

  # Note: setting fileSystems is generally not
  # necessary, since nixos-generate-config figures them out
  # automatically in hardware-configuration.nix.
  #fileSystems."/".device = "/dev/disk/by-label/nixos";

  # Enable the OpenSSH server.
  services.sshd.enable = true;
}

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

system.autoUpgrade.enable = true;
system.autoUpgrade.allowReboot = true;

This enables a periodically executed systemd service named nixos-upgrade.service. If the allowReboot option is false, 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.) If allowReboot is true, then the system will automatically reboot if the new generation contains a different kernel, initrd or kernel modules. You can also specify a channel explicitly, e.g.

system.autoUpgrade.channel = https://nixos.org/channels/nixos-20.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.virtualHosts.localhost.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";
      virtualHosts = {
        localhost = {
          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 =
    { "blog.example.org" = {
        documentRoot = "/webroot/blog.example.org";
        adminAddr = "alice@example.org";
        forceSSL = true;
        enableACME = true;
        enablePHP = true;
      };
      "wiki.example.org" = {
        documentRoot = "/webroot/wiki.example.org";
        adminAddr = "alice@example.org";
        forceSSL = true;
        enableACME = true;
        enablePHP = true;
      };
    };
}

It defines two virtual hosts with nearly identical configuration; the only difference is the document root directories. To prevent this duplication, we can use a let:

let
  commonConfig =
    { adminAddr = "alice@example.org";
      forceSSL = true;
      enableACME = true;
    };
in
{
  services.httpd.virtualHosts =
    { "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; });
      "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.com"; });
    };
}

The let commonConfig = ... defines a variable named commonConfig. The // operator merges two attribute sets, so the configuration of the second virtual host is the set commonConfig extended with the document root option.

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

{
  services.httpd.virtualHosts =
    let commonConfig = ...; in
    { "blog.example.org" = (commonConfig // { ... })
      "wiki.example.org" = (commonConfig // { ... })
    };
}

but not { let commonConfig = ...; 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 document root. This can be done as follows:

{
  services.httpd.virtualHosts =
    let
      makeVirtualHost = webroot:
        { documentRoot = webroot;
          adminAddr = "alice@example.org";
          forceSSL = true;
          enableACME = true;
        };
    in
      { "example.org" = (makeVirtualHost "/webroot/example.org");
        "example.com" = (makeVirtualHost "/webroot/example.com");
        "example.gov" = (makeVirtualHost "/webroot/example.gov");
        "example.nl" = (makeVirtualHost "/webroot/example.nl");
      };
}

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

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. 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" ]

While abstracting your configuration, you may find it useful to generate modules using code, instead of writing files. The example below would have the same effect as importing a file which sets those options.

{ config, pkgs, ... }:

let netConfig = { hostName }: {
  networking.hostName = hostName;
  networking.useDHCP = false;
};

in

{ imports = [ (netConfig "nixos.localdomain") ]; }

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.

Note: the nixos prefix tells us that we want to get the package from the nixos channel and works only in CLI tools. In declarative configuration use pkgs prefix (variable).

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 https://github.com/NixOS/nixpkgs
$ 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;

# export FIDO2_LABEL="/dev/sda2 @ $HOSTNAME"
# fido2luks credential "$FIDO2_LABEL"
f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7

# fido2luks -i add-key /dev/sda2 f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7
Password:
Password (again):
Old password:
Old password (again):
Added to key to device /dev/sda2, slot: 2

boot.initrd.luks.fido2Support = true;
boot.initrd.luks.devices."/dev/sda2".fido2.credential = "f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7";

boot.initrd.luks.devices."/dev/sda2".fido2.passwordLess = 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.users.alice.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 enabling programs.nm-applet.enable, the graphical applet will be installed and will launch automatically when the graphical session is started.

networking.networkmanager.unmanaged = [
   "*" "except:type:wwan" "except:type:gsm"
];

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.users.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.ipv4.addresses = [ {
  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.ipv6.addresses = [ {
  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.

To open ranges of TCP ports:

networking.firewall.allowedTCPPortRanges = [
  { from = 4000; to = 4007; }
  { from = 8000; to = 8010; }
];

Similarly, UDP port ranges can be opened through networking.firewall.allowedUDPPortRanges.

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 = {                # SSID with no spaces or special characters
    psk = "abcdefgh";
  };
  "echelon's AP" = {         # SSID with spaces and/or special characters
    psk = "ijklmnop";
  };
  echelon = {                # Hidden SSID
    hidden = true;
    psk = "qrstuvwx";
  };
  free.wifi = {};            # Public wireless network
};

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 you can generate pskRaw key using wpa_passphrase:

$ wpa_passphrase ESSID PSK
network={
        ssid="echelon"
        #psk="abcdefgh"
        psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435
}

networking.wireless.networks = {
  echelon = {
    pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";
  };
}

or you can use it to directly 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
  '';

The first step before compiling the kernel is to generate an appropriate .config configuration. Either you pass your own config via the configfile setting of linuxManualConfig:

  custom-kernel = super.linuxManualConfig {
    inherit (super) stdenv hostPlatform;
    inherit (linux_4_9) src;
    version = "${linux_4_9.version}-custom";

    configfile = /home/me/my_kernel_config;
    allowImportFromDerivation = true;
  };
  

You can edit the config with this snippet (by default make menuconfig won't work out of the box on nixos):

      nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkgconfig ncurses ];})'
  

or you can let nixpkgs generate the configuration. Nixpkgs generates it via answering the interactive kernel utility make config. The answers depend on parameters passed to pkgs/os-specific/linux/kernel/generic.nix (which you can influence by overriding extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig).

  mptcp93.override ({
      name="mptcp-local";

      ignoreConfigErrors = true;
      autoModules = false;
      kernelPreferBuiltin = true;

      enableParallelBuilding = true;

      extraConfig = ''
        DEBUG_KERNEL y
        FRAME_POINTER y
        KGDB y
        KGDB_SERIAL_CONSOLE y
        DEBUG_INFO y
      '';
    });
  

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

All of Pantheon is working in NixOS and the applications should be available, aside from a few exceptions. To enable Pantheon, set

services.xserver.desktopManager.pantheon.enable = true;

This automatically enables LightDM and Pantheon's LightDM greeter. If you'd like to disable this, set

services.xserver.displayManager.lightdm.greeters.pantheon.enable = false;
services.xserver.displayManager.lightdm.enable = false;

but please be aware using Pantheon without LightDM as a display manager will break screenlocking from the UI. The NixOS module for Pantheon installs all of Pantheon's default applications. If you'd like to not install Pantheon's apps, set

services.pantheon.apps.enable = false;

You can also use environment.pantheon.excludePackages to remove any other app (like geary).

Wingpanel and Switchboard work differently than they do in other distributions, as far as using plugins. You cannot install a plugin globally (like with environment.systemPackages) to start using it. You should instead be using the following options:

to configure the programs with plugs or indicators.

The difference in NixOS is both these programs are patched to load plugins from a directory that is the value of an environment variable. All of which is controlled in Nix. If you need to configure the particular packages manually you can override the packages like:

wingpanel-with-indicators.override {
  indicators = [
    pkgs.some-special-indicator
  ];
};

switchboard-with-plugs.override {
  plugs = [
    pkgs.some-special-plug
  ];
};

please note that, like how the NixOS options describe these as extra plugins, this would only add to the default plugins included with the programs. If for some reason you'd like to configure which plugins to use exactly, both packages have an argument for this:

wingpanel-with-indicators.override {
  useDefaultIndicators = false;
  indicators = specialListOfIndicators;
};

switchboard-with-plugs.override {
  useDefaultPlugs = false;
  plugs = specialListOfPlugs;
};

this could be most useful for testing a particular plug-in in isolation.

You also need to configure a MariaDB or MySQL database and -user for Matomo 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 matomo;
CREATE USER 'matomo'@'localhost' IDENTIFIED WITH unix_socket;
GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';

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

Then fill in matomo as database user and database name, and leave the password field blank. This authentication works by allowing only the matomo unix user to authenticate as the matomo 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.

This module comes with the systemd service matomo-archive-processing.service and a timer that automatically triggers archive processing every hour. This means that you can safely disable browser triggers for Matomo archiving at Administration > System > General Settings.

With automatic archive processing, you can now also enable to delete old visitor logs at Administration > System > Privacy, but make sure that you run systemctl start matomo-archive-processing.service at least once without errors if you have already collected data before, so that the reports get archived before the source data gets deleted.

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

You can use other web servers by forwarding calls for index.php and piwik.php to the services.phpfpm.pools.<name>.socket fastcgi unix socket. You can use the nginx configuration in the module code as a reference to what else should be configured.

Nextcloud is a PHP-based application which requires an HTTP server (services.nextcloud optionally supports services.nginx) and a database (it's recommended to use services.postgresql).

A very basic configuration may look like this:

{ pkgs, ... }:
{
  services.nextcloud = {
    enable = true;
    hostName = "nextcloud.tld";
    nginx.enable = true;
    config = {
      dbtype = "pgsql";
      dbuser = "nextcloud";
      dbhost = "/run/postgresql"; # nextcloud will add /.s.PGSQL.5432 by itself
      dbname = "nextcloud";
      adminpassFile = "/path/to/admin-pass-file";
      adminuser = "root";
    };
  };

  services.postgresql = {
    enable = true;
    ensureDatabases = [ "nextcloud" ];
    ensureUsers = [
     { name = "nextcloud";
       ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES";
     }
    ];
  };

  # ensure that postgres is running *before* running the setup
  systemd.services."nextcloud-setup" = {
    requires = ["postgresql.service"];
    after = ["postgresql.service"];
  };

  networking.firewall.allowedTCPPorts = [ 80 443 ];
}

The options hostName and nginx.enable are used internally to configure an HTTP server using PHP-FPM and nginx. The config attribute set is used by the imperative installer and all values are written to an additional file to ensure that changes can be applied by changing the module's options.

In case the application serves multiple domains (those are checked with $_SERVER['HTTP_HOST']) it's needed to add them to services.nextcloud.config.extraTrustedDomains.

Auto updates for Nextcloud apps can be enabled using services.nextcloud.autoUpdateApps.

Unfortunately Nextcloud appears to be very stateful when it comes to managing its own configuration. The config file lives in the home directory of the nextcloud user (by default /var/lib/nextcloud/config/config.php) and is also used to track several states of the application (e.g. whether installed or not).

All configuration parameters are also stored in /var/lib/nextcloud/config/override.config.php which is generated by the module and linked from the store to ensure that all values from config.php can be modified by the module. However config.php manages the application's state and shouldn't be touched manually because of that.

Nextcloud doesn't allow to move more than one major-version forward. If you're e.g. on v16, you cannot upgrade to v18, you need to upgrade to v17 first. This is ensured automatically as long as the stateVersion is declared properly. In that case the oldest version available (one major behind the one from the previous NixOS release) will be selected by default and the module will generate a warning that reminds the user to upgrade to latest Nextcloud after that deploy.

As stated in the previous paragraph, we must provide a clean upgrade-path for Nextcloud since it cannot move more than one major version forward on a single upgrade. This chapter adds some notes how Nextcloud updates should be rolled out in the future.

While minor and patch-level updates are no problem and can be done directly in the package-expression (and should be backported to supported stable branches after that), major-releases should be added in a new attribute (e.g. Nextcloud v19.0.0 should be available in nixpkgs as pkgs.nextcloud19). To provide simple upgrade paths it's generally useful to backport those as well to stable branches. As long as the package-default isn't altered, this won't break existing setups. After that, the versioning-warning in the nextcloud-module should be updated to make sure that the package-option selects the latest version on fresh setups.

If major-releases will be abandoned by upstream, we should check first if those are needed in NixOS for a safe upgrade-path before removing those. In that case we shold keep those packages, but mark them as insecure in an expression like this (in <nixpkgs/pkgs/servers/nextcloud/default.nix>):

/* ... */
{
  nextcloud17 = generic {
    version = "17.0.x";
    sha256 = "0000000000000000000000000000000000000000000000000000";
    insecure = true;
  };
}

A very basic configuration may look like this:

{ pkgs, ... }:
{
  services.grocy = {
    enable = true;
    hostName = "grocy.tld";
  };
}

This configures a simple vhost using nginx which listens to grocy.tld with fully configured ACME/LE (this can be disabled by setting services.grocy.nginx.enableSSL to false). After the initial setup the credentials admin:admin can be used to login.

The application's state is persisted at /var/lib/grocy/grocy.db in a sqlite3 database. The migration is applied when requesting the /-route of the application.

The configuration for grocy is located at /etc/grocy/config.php. By default, the following settings can be defined in the NixOS-configuration:

{ pkgs, ... }:
{
  services.grocy.settings = {
    # The default currency in the system for invoices etc.
    # Please note that exchange rates aren't taken into account, this
    # is just the setting for what's shown in the frontend.
    currency = "EUR";

    # The display language (and locale configuration) for grocy.
    culture = "de";

    calendar = {
      # Whether or not to show the week-numbers
      # in the calendar.
      showWeekNumber = true;

      # Index of the first day to be shown in the calendar (0=Sunday, 1=Monday,
      # 2=Tuesday and so on).
      firstDayOfWeek = 2;
    };
  };
}

If you want to alter the configuration file on your own, you can do this manually with an expression like this:

{ lib, ... }:
{
  environment.etc."grocy/config.php".text = lib.mkAfter ''
    // Arbitrary PHP code in grocy's configuration file
  '';
}

One of the most common exporters is the node exporter, it provides hardware and OS metrics from the host it's running on. The exporter could be configured as follows:

  services.prometheus.exporters.node = {
    enable = true;
    enabledCollectors = [
      "logind"
      "systemd"
    ];
    disabledCollectors = [
      "textfile"
    ];
    openFirewall = true;
    firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";
  };

It should now serve all metrics from the collectors that are explicitly enabled and the ones that are enabled by default, via http under /metrics. In this example the firewall should just allow incoming connections to the exporter's port on the bridge interface br0 (this would have to be configured seperately of course). For more information about configuration see man configuration.nix or search through the available options.

To add a new exporter, it has to be packaged first (see nixpkgs/pkgs/servers/monitoring/prometheus/ for examples), then a module can be added. The postfix exporter is used in this example:

Should an exporter option change at some point, it is possible to add information about the change to the exporter definition similar to nixpkgs/nixos/modules/rename.nix:

{ config, lib, pkgs, options }:

with lib;

let
  cfg = config.services.prometheus.exporters.nginx;
in
{
  port = 9113;
  extraOpts = {
    # additional module options
    # ...
  };
  serviceOpts = {
    # service configuration
    # ...
  };
  imports = [
    # 'services.prometheus.exporters.nginx.telemetryEndpoint' -> 'services.prometheus.exporters.nginx.telemetryPath'
    (mkRenamedOptionModule [ "telemetryEndpoint" ] [ "telemetryPath" ])

    # removed option 'services.prometheus.exporters.nginx.insecure'
    (mkRemovedOptionModule [ "insecure" ] ''
      This option was replaced by 'prometheus.exporters.nginx.sslVerify' which defaults to true.
    '')
    ({ options.warnings = options.warnings; })
  ];
}

By default, the module creates a systemd unit which runs the chat client in a detached screen session.

This can be done by enabling the weechat service:

{ ... }:

{
  services.weechat.enable = true;
}

The service is managed by a dedicated user named weechat in the state directory /var/lib/weechat.

WeeChat runs in a screen session owned by a dedicated user. To explicitly allow your another user to attach to this session, the screenrc needs to be tweaked by adding multiuser support:

{
  programs.screen.screenrc = ''
    multiuser on
    acladd normal_user
  '';
}

Now, the session can be re-attached like this:

screen -x weechat/weechat-screen

The session name can be changed using services.weechat.sessionName.

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.

Synapse is the reference homeserver implementation of Matrix from the core development team at matrix.org. The following configuration example will set up a synapse server for the example.org domain, served from the host myhostname.example.org. For more information, please refer to the installation instructions of Synapse .

{ pkgs, ... }:
let
  fqdn =
    let
      join = hostName: domain: hostName + optionalString (domain != null) ".${domain}";
    in join config.networking.hostName config.networking.domain;
in {
  networking = {
    hostName = "myhostname";
    domain = "example.org";
  };
  networking.firewall.allowedTCPPorts = [ 80 443 ];

  services.postgresql.enable = true;
  services.postgresql.initialScript = pkgs.writeText "synapse-init.sql" ''
    CREATE ROLE "matrix-synapse" WITH LOGIN PASSWORD 'synapse';
    CREATE DATABASE "matrix-synapse" WITH OWNER "matrix-synapse"
      TEMPLATE template0
      LC_COLLATE = "C"
      LC_CTYPE = "C";
  '';

  services.nginx = {
    enable = true;
    # only recommendedProxySettings and recommendedGzipSettings are strictly required,
    # but the rest make sense as well
    recommendedTlsSettings = true;
    recommendedOptimisation = true;
    recommendedGzipSettings = true;
    recommendedProxySettings = true;

    virtualHosts = {
      # This host section can be placed on a different host than the rest,
      # i.e. to delegate from the host being accessible as ${config.networking.domain}
      # to another host actually running the Matrix homeserver.
      "${config.networking.domain}" = {
        locations."= /.well-known/matrix/server".extraConfig =
          let
            # use 443 instead of the default 8448 port to unite
            # the client-server and server-server port for simplicity
            server = { "m.server" = "${fqdn}:443"; };
          in ''
            add_header Content-Type application/json;
            return 200 '${builtins.toJSON server}';
          '';
        locations."= /.well-known/matrix/client".extraConfig =
          let
            client = {
              "m.homeserver" =  { "base_url" = "https://${fqdn}"; };
              "m.identity_server" =  { "base_url" = "https://vector.im"; };
            };
          # ACAO required to allow riot-web on any URL to request this json file
          in ''
            add_header Content-Type application/json;
            add_header Access-Control-Allow-Origin *;
            return 200 '${builtins.toJSON client}';
          '';
      };

      # Reverse proxy for Matrix client-server and server-server communication
      ${fqdn} = {
        enableACME = true;
        forceSSL = true;

        # Or do a redirect instead of the 404, or whatever is appropriate for you.
        # But do not put a Matrix Web client here! See the Riot Web section below.
        locations."/".extraConfig = ''
          return 404;
        '';

        # forward all Matrix API calls to the synapse Matrix homeserver
        locations."/_matrix" = {
          proxyPass = "http://[::1]:8008"; # without a trailing /
        };
      };
    };
  };
  services.matrix-synapse = {
    enable = true;
    server_name = config.networking.domain;
    listeners = [
      {
        port = 8008;
        bind_address = "::1";
        type = "http";
        tls = false;
        x_forwarded = true;
        resources = [
          {
            names = [ "client" "federation" ];
            compress = false;
          }
        ];
      }
    ];
  };
};

If the A and AAAA DNS records on example.org do not point on the same host as the records for myhostname.example.org, you can easily move the /.well-known virtualHost section of the code to the host that is serving example.org, while the rest stays on myhostname.example.org with no other changes required. This pattern also allows to seamlessly move the homeserver from myhostname.example.org to myotherhost.example.org by only changing the /.well-known redirection target.

If you want to run a server with public registration by anybody, you can then enable services.matrix-synapse.enable_registration = true;. Otherwise, or you can generate a registration secret with pwgen -s 64 1 and set it with services.matrix-synapse.registration_shared_secret. To create a new user or admin, run the following after you have set the secret and have rebuilt NixOS:

$ nix run nixpkgs.matrix-synapse
$ register_new_matrix_user -k your-registration-shared-secret http://localhost:8008
New user localpart: your-username
Password:
Confirm password:
Make admin [no]:
Success!

In the example, this would create a user with the Matrix Identifier @your-username:example.org. Note that the registration secret ends up in the nix store and therefore is world-readable by any user on your machine, so it makes sense to only temporarily activate the registration_shared_secret option until a better solution for NixOS is in place.

Riot Web is the reference web client for Matrix and developed by the core team at matrix.org. The following snippet can be optionally added to the code before to complete the synapse installation with a web client served at https://riot.myhostname.example.org and https://riot.example.org. Alternatively, you can use the hosted copy at https://riot.im/app, or use other web clients or native client applications. Due to the /.well-known urls set up done above, many clients should fill in the required connection details automatically when you enter your Matrix Identifier. See Try Matrix Now! for a list of existing clients and their supported featureset.

{
  services.nginx.virtualHosts."riot.${fqdn}" = {
    enableACME = true;
    forceSSL = true;
    serverAliases = [
      "riot.${config.networking.domain}"
    ];

    root = pkgs.riot-web.override {
      conf = {
        default_server_config."m.homeserver" = {
          "base_url" = "${config.networking.domain}";
          "server_name" = "${fqdn}";
        };
      };
    };
  };
}

Note that the Riot developers do not recommend running Riot and your Matrix homeserver on the same fully-qualified domain name for security reasons. In the example, this means that you should not reuse the myhostname.example.org virtualHost to also serve Riot, but instead serve it on a different subdomain, like riot.example.org in the example. See the Riot Important Security Notes for more information on this subject.

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;
  databasePasswordFile = "/var/keys/gitlab/db_password";
  initialRootPasswordFile = "/var/keys/gitlab/root_password";
  https = true;
  host = "git.example.com";
  port = 443;
  user = "git";
  group = "git";
  smtp = {
    enable = true;
    address = "localhost";
    port = 25;
  };
  secrets = {
    dbFile = "/var/keys/gitlab/db";
    secretFile = "/var/keys/gitlab/secret";
    otpFile = "/var/keys/gitlab/otp";
    jwsFile = "/var/keys/gitlab/jws";
  };
  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 > /var/keys/gitlab/db to generate a new db secret. Make sure the files can be read by, and only by, the user specified by services.gitlab.user. 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.emacsPackagesGen 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 emacsPackages.elpaPackages
nix-env -f "<nixpkgs>" -qaP -A emacsPackages.melpaPackages
nix-env -f "<nixpkgs>" -qaP -A emacsPackages.melpaStablePackages
nix-env -f "<nixpkgs>" -qaP -A emacsPackages.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.postgresql_11;

Note that you are required to specify the desired version of PostgreSQL (e.g. pkgs.postgresql_11). 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/lib/postgresql/$psqlSchema. You can override this using services.postgresql.dataDir, e.g.

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

Major PostgreSQL upgrade requires PostgreSQL downtime and a few imperative steps to be called. To simplify this process, use the following NixOS module:

  containers.temp-pg.config.services.postgresql = {
    enable = true;
    package = pkgs.postgresql_12;
    ## set a custom new dataDir
    # dataDir = "/some/data/dir";
  };
  environment.systemPackages =
    let newpg = config.containers.temp-pg.config.services.postgresql;
    in [
      (pkgs.writeScriptBin "upgrade-pg-cluster" ''
        set -x
        export OLDDATA="${config.services.postgresql.dataDir}"
        export NEWDATA="${newpg.dataDir}"
        export OLDBIN="${config.services.postgresql.package}/bin"
        export NEWBIN="${newpg.package}/bin"

        install -d -m 0700 -o postgres -g postgres "$NEWDATA"
        cd "$NEWDATA"
        sudo -u postgres $NEWBIN/initdb -D "$NEWDATA"

        systemctl stop postgresql    # old one

        sudo -u postgres $NEWBIN/pg_upgrade \
          --old-datadir "$OLDDATA" --new-datadir "$NEWDATA" \
          --old-bindir $OLDBIN --new-bindir $NEWBIN \
          "$@"
      '')
    ];

The upgrade process is:

A complete list of options for the PostgreSQL module may be found here.

Plugins collection for each PostgreSQL version can be accessed with .pkgs. For example, for pkgs.postgresql_11 package, its plugin collection is accessed by pkgs.postgresql_11.pkgs:

$ nix repl '<nixpkgs>'

Loading '<nixpkgs>'...
Added 10574 variables.

nix-repl> postgresql_11.pkgs.<TAB><TAB>
postgresql_11.pkgs.cstore_fdw        postgresql_11.pkgs.pg_repack
postgresql_11.pkgs.pg_auto_failover  postgresql_11.pkgs.pg_safeupdate
postgresql_11.pkgs.pg_bigm           postgresql_11.pkgs.pg_similarity
postgresql_11.pkgs.pg_cron           postgresql_11.pkgs.pg_topn
postgresql_11.pkgs.pg_hll            postgresql_11.pkgs.pgjwt
postgresql_11.pkgs.pg_partman        postgresql_11.pkgs.pgroonga
...

To add plugins via NixOS configuration, set services.postgresql.extraPlugins:

services.postgresql.package = pkgs.postgresql_11;
services.postgresql.extraPlugins = with pkgs.postgresql_11.pkgs; [
  pg_repack
  postgis
];

You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using function .withPackages. For example, creating a custom PostgreSQL package in an overlay can look like:

self: super: {
  postgresql_custom = self.postgresql_11.withPackages (ps: [
    ps.pg_repack
    ps.postgis
  ]);
}

Here's a recipe on how to override a particular plugin through an overlay:

self: super: {
  postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {
    pkgs = super.postgresql_11.pkgs // {
      pg_repack = super.postgresql_11.pkgs.pg_repack.overrideAttrs (_: {
        name = "pg_repack-v20181024";
        src = self.fetchzip {
          url = "https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz";
          sha256 = "17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5";
        };
      });
    };
  };
}

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

services.foundationdb.enable = true;
services.foundationdb.package = pkgs.foundationdb52; # FoundationDB 5.2.x

The services.foundationdb.package option is required, and must always be specified. Due to the fact FoundationDB network protocols and on-disk storage formats may change between (major) versions, and upgrades must be explicitly handled by the user, you must always manually specify this yourself so that the NixOS module will use the proper version. Note that minor, bugfix releases are always compatible.

After running nixos-rebuild, you can verify whether FoundationDB is running by executing fdbcli (which is added to environment.systemPackages):

$ sudo -u foundationdb fdbcli
Using cluster file `/etc/foundationdb/fdb.cluster'.

The database is available.

Welcome to the fdbcli. For help, type `help'.
fdb> status

Using cluster file `/etc/foundationdb/fdb.cluster'.

Configuration:
  Redundancy mode        - single
  Storage engine         - memory
  Coordinators           - 1

Cluster:
  FoundationDB processes - 1
  Machines               - 1
  Memory availability    - 5.4 GB per process on machine with least available
  Fault Tolerance        - 0 machines
  Server time            - 04/20/18 15:21:14

...

fdb>

You can also write programs using the available client libraries. For example, the following Python program can be run in order to grab the cluster status, as a quick example. (This example uses nix-shell shebang support to automatically supply the necessary Python modules).

a@link> cat fdb-status.py
#! /usr/bin/env nix-shell
#! nix-shell -i python -p python pythonPackages.foundationdb52

import fdb
import json

def main():
    fdb.api_version(520)
    db = fdb.open()

    @fdb.transactional
    def get_status(tr):
        return str(tr['\xff\xff/status/json'])

    obj = json.loads(get_status(db))
    print('FoundationDB available: %s' % obj['client']['database_status']['available'])

if __name__ == "__main__":
    main()
a@link> chmod +x fdb-status.py
a@link> ./fdb-status.py
FoundationDB available: True
a@link>

FoundationDB is run under the foundationdb user and group by default, but this may be changed in the NixOS configuration. The systemd unit foundationdb.service controls the fdbmonitor process.

By default, the NixOS module for FoundationDB creates a single SSD-storage based database for development and basic usage. This storage engine is designed for SSDs and will perform poorly on HDDs; however it can handle far more data than the alternative "memory" engine and is a better default choice for most deployments. (Note that you can change the storage backend on-the-fly for a given FoundationDB cluster using fdbcli.)

Furthermore, only 1 server process and 1 backup agent are started in the default configuration. See below for more on scaling to increase this.

FoundationDB stores all data for all server processes under /var/lib/foundationdb. You can override this using services.foundationdb.dataDir, e.g.

services.foundationdb.dataDir = "/data/fdb";

Similarly, logs are stored under /var/log/foundationdb by default, and there is a corresponding services.foundationdb.logDir as well.

Scaling the number of server processes is quite easy; simply specify services.foundationdb.serverProcesses to be the number of FoundationDB worker processes that should be started on the machine.

FoundationDB worker processes typically require 4GB of RAM per-process at minimum for good performance, so this option is set to 1 by default since the maximum amount of RAM is unknown. You're advised to abide by this restriction, so pick a number of processes so that each has 4GB or more.

A similar option exists in order to scale backup agent processes, services.foundationdb.backupProcesses. Backup agents are not as performance/RAM sensitive, so feel free to experiment with the number of available backup processes.

FoundationDB on NixOS works similarly to other Linux systems, so this section will be brief. Please refer to the full FoundationDB documentation for more on clustering.

FoundationDB organizes clusters using a set of coordinators, which are just specially-designated worker processes. By default, every installation of FoundationDB on NixOS will start as its own individual cluster, with a single coordinator: the first worker process on localhost.

Coordinators are specified globally using the /etc/foundationdb/fdb.cluster file, which all servers and client applications will use to find and join coordinators. Note that this file can not be managed by NixOS so easily: FoundationDB is designed so that it will rewrite the file at runtime for all clients and nodes when cluster coordinators change, with clients transparently handling this without intervention. It is fundamentally a mutable file, and you should not try to manage it in any way in NixOS.

When dealing with a cluster, there are two main things you want to do:

A node must already be a member of the cluster in order to properly be promoted to a coordinator, so you must always add it first if you wish to promote it.

To add a machine to a FoundationDB cluster:

At this point, you can add as many nodes as you want by just repeating the above steps. By default there will still be a single coordinator: you can use fdbcli to change this and add new coordinators.

As a convenience, FoundationDB can automatically assign coordinators based on the redundancy mode you wish to achieve for the cluster. Once all the nodes have been joined, simply set the replication policy, and then issue the coordinators auto command

For example, assuming we have 3 nodes available, we can enable double redundancy mode, then auto-select coordinators. For double redundancy, 3 coordinators is ideal: therefore FoundationDB will make every node a coordinator automatically:

fdbcli> configure double ssd
fdbcli> coordinators auto

This will transparently update all the servers within seconds, and appropriately rewrite the fdb.cluster file, as well as informing all client processes to do the same.

By default, all clients must use the current fdb.cluster file to access a given FoundationDB cluster. This file is located by default in /etc/foundationdb/fdb.cluster on all machines with the FoundationDB service enabled, so you may copy the active one from your cluster to a new node in order to connect, if it is not part of the cluster.

By default, any user who can connect to a FoundationDB process with the correct cluster configuration can access anything. FoundationDB uses a pluggable design to transport security, and out of the box it supports a LibreSSL-based plugin for TLS support. This plugin not only does in-flight encryption, but also performs client authorization based on the given endpoint's certificate chain. For example, a FoundationDB server may be configured to only accept client connections over TLS, where the client TLS certificate is from organization Acme Co in the Research and Development unit.

Configuring TLS with FoundationDB is done using the services.foundationdb.tls options in order to control the peer verification string, as well as the certificate and its private key.

Note that the certificate and its private key must be accessible to the FoundationDB user account that the server runs under. These files are also NOT managed by NixOS, as putting them into the store may reveal private information.

After you have a key and certificate file in place, it is not enough to simply set the NixOS module options -- you must also configure the fdb.cluster file to specify that a given set of coordinators use TLS. This is as simple as adding the suffix :tls to your cluster coordinator configuration, after the port number. For example, assuming you have a coordinator on localhost with the default configuration, simply specifying:

XXXXXX:XXXXXX@127.0.0.1:4500:tls

will configure all clients and server processes to use TLS from now on.

The usual rules for doing FoundationDB backups apply on NixOS as written in the FoundationDB manual. However, one important difference is the security profile for NixOS: by default, the foundationdb systemd unit uses Linux namespaces to restrict write access to the system, except for the log directory, data directory, and the /etc/foundationdb/ directory. This is enforced by default and cannot be disabled.

However, a side effect of this is that the fdbbackup command doesn't work properly for local filesystem backups: FoundationDB uses a server process alongside the database processes to perform backups and copy the backups to the filesystem. As a result, this process is put under the restricted namespaces above: the backup process can only write to a limited number of paths.

In order to allow flexible backup locations on local disks, the FoundationDB NixOS module supports a services.foundationdb.extraReadWritePaths option. This option takes a list of paths, and adds them to the systemd unit, allowing the processes inside the service to write (and read) the specified directories.

For example, to create backups in /opt/fdb-backups, first set up the paths in the module options:

services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ];

Restart the FoundationDB service, and it will now be able to write to this directory (even if it does not yet exist.) Note: this path must exist before restarting the unit. Otherwise, systemd will not include it in the private FoundationDB namespace (and it will not add it dynamically at runtime).

You can now perform a backup:

$ sudo -u foundationdb fdbbackup start  -t default -d file:///opt/fdb-backups
$ sudo -u foundationdb fdbbackup status -t default

The FoundationDB setup for NixOS should currently be considered beta. FoundationDB is not new software, but the NixOS compilation and integration has only undergone fairly basic testing of all the available functionality.

NixOS's FoundationDB module allows you to configure all of the most relevant configuration options for fdbmonitor, matching it quite closely. A complete list of options for the FoundationDB module may be found here. You should also read the FoundationDB documentation as well.

FoundationDB is a complex piece of software, and requires careful administration to properly use. Full documentation for administration can be found here: https://apple.github.io/foundationdb/.

To use the ACME module, you must accept the provider's terms of service by setting security.acme.acceptTerms to true. The Let's Encrypt ToS can be found here.

You must also set an email address to be used when creating accounts with Let's Encrypt. You can set this for all certs with security.acme.email and/or on a per-cert basis with security.acme.certs.<name>.email. This address is only used for registration and renewal reminders, and cannot be used to administer the certificates in any way.

Alternatively, you can use a different ACME server by changing the security.acme.server option to a provider of your choosing, or just change the server for one cert with security.acme.certs.<name>.server.

You will need an HTTP server or DNS server for verification. For HTTP, 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 DNS, you must set up credentials with your provider/server for use with lego.

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.

security.acme.acceptTerms = true;
security.acme.email = "admin+acme@example.com";
services.nginx = {
  enable = true;
  virtualHosts = {
    "foo.example.com" = {
      forceSSL = true;
      enableACME = true;
      # All serverAliases will be added as extra domains on the certificate.
      serverAliases = [ "bar.example.com" ];
      locations."/" = {
        root = "/var/www";
      };
    };

    # We can also add a different vhost and reuse the same certificate
    # but we have to append extraDomains manually.
    security.acme.certs."foo.example.com".extraDomains."baz.example.com" = null;
    "baz.example.com" = {
      forceSSL = true;
      useACMEHost = "foo.example.com";
      locations."/" = {
        root = "/var/www";
      };
    };
  };
}

Using ACME certificates with Apache virtual hosts is identical to using them with Nginx. The attribute names are all the same, just replace "nginx" with "httpd" where appropriate.

First off you will need to set up a virtual host to serve the challenges. This example uses a vhost called certs.example.com, with the intent that you will generate certs for all your vhosts and redirect everyone to HTTPS.

security.acme.acceptTerms = true;
security.acme.email = "admin+acme@example.com";
services.nginx = {
  enable = true;
  virtualHosts = {
    "acmechallenge.example.com" = {
      # Catchall vhost, will redirect users to HTTPS for all vhosts
      serverAliases = [ "*.example.com" ];
      # /var/lib/acme/.challenges must be writable by the ACME user
      # and readable by the Nginx user.
      # By default, this is the case.
      locations."/.well-known/acme-challenge" = {
        root = "/var/lib/acme/.challenges";
      };
      locations."/" = {
        return = "301 https://$host$request_uri";
      };
    };
  };
}
# Alternative config for Apache
services.httpd = {
  enable = true;
  virtualHosts = {
    "acmechallenge.example.com" = {
      # Catchall vhost, will redirect users to HTTPS for all vhosts
      serverAliases = [ "*.example.com" ];
      # /var/lib/acme/.challenges must be writable by the ACME user and readable by the Apache user.
      # By default, this is the case.
      documentRoot = "/var/lib/acme/.challenges";
      extraConfig = ''
        RewriteEngine On
        RewriteCond %{HTTPS} off
        RewriteCond %{REQUEST_URI} !^/\.well-known/acme-challenge [NC]
        RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} [R=301]
      '';
    };
  };
}

Now you need to configure ACME to generate a certificate.

security.acme.certs."foo.example.com" = {
  webroot = "/var/lib/acme/.challenges";
  email = "foo@example.com";
  # Since we have a wildcard vhost to handle port 80,
  # we can generate certs for anything!
  # Just make sure your DNS resolves them.
  extraDomains = [ "mail.example.com" ];
};

The private key key.pem and certificate fullchain.pem will be put into /var/lib/acme/foo.example.com.

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

This is useful if you want to generate a wildcard certificate, since ACME servers will only hand out wildcard certs over DNS validation. There a number of supported DNS providers and servers you can utilise, see the lego docs for provider/server specific configuration values. For the sake of these docs, we will provide a fully self-hosted example using bind.

services.bind = {
  enable = true;
  extraConfig = ''
    include "/var/lib/secrets/dnskeys.conf";
  '';
  zones = [
    rec {
      name = "example.com";
      file = "/var/db/bind/${name}";
      master = true;
      extraConfig = "allow-update { key rfc2136key.example.com.; };";
    }
  ];
}

# Now we can configure ACME
security.acme.acceptTerms = true;
security.acme.email = "admin+acme@example.com";
security.acme.certs."example.com" = {
  domain = "*.example.com";
  dnsProvider = "rfc2136";
  credentialsFile = "/var/lib/secrets/certs.secret";
  # We don't need to wait for propagation since this is a local DNS server
  dnsPropagationCheck = false;
};

The dnskeys.conf and certs.secret must be kept secure and thus you should not keep their contents in your Nix config. Instead, generate them one time with these commands:

mkdir -p /var/lib/secrets
tsig-keygen rfc2136key.example.com > /var/lib/secrets/dnskeys.conf
chown named:root /var/lib/secrets/dnskeys.conf
chmod 400 /var/lib/secrets/dnskeys.conf

# Copy the secret value from the dnskeys.conf, and put it in
# RFC2136_TSIG_SECRET below

cat > /var/lib/secrets/certs.secret << EOF
RFC2136_NAMESERVER='127.0.0.1:53'
RFC2136_TSIG_ALGORITHM='hmac-sha256.'
RFC2136_TSIG_KEY='rfc2136key.example.com'
RFC2136_TSIG_SECRET='your secret key'
EOF
chmod 400 /var/lib/secrets/certs.secret

Now you're all set to generate certs! You should monitor the first invokation by running systemctl start acme-example.com.service & journalctl -fu acme-example.com.service and watching its log output.

The module uses the oh-my-zsh package with all available features. The initial setup using Nix expressions is fairly similar to the configuration format of oh-my-zsh.

{
  programs.zsh.ohMyZsh = {
    enable = true;
    plugins = [ "git" "python" "man" ];
    theme = "agnoster";
  };
}

For a detailed explanation of these arguments please refer to the oh-my-zsh docs.

The expression generates the needed configuration and writes it into your /etc/zshrc.

Sometimes third-party or custom scripts such as a modified theme may be needed. oh-my-zsh provides the ZSH_CUSTOM environment variable for this which points to a directory with additional scripts.

The module can do this as well:

{
  programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts";
}

There are several extensions for oh-my-zsh packaged in nixpkgs. One of them is nix-zsh-completions which bundles completion scripts and a plugin for oh-my-zsh.

Rather than using a single mutable path for ZSH_CUSTOM, it's also possible to generate this path from a list of Nix packages:

{ pkgs, ... }:
{
  programs.zsh.ohMyZsh.customPkgs = with pkgs; [
    pkgs.nix-zsh-completions
    # and even more...
  ];
}

Internally a single store path will be created using buildEnv. Please refer to the docs of buildEnv for further reference.

Please keep in mind that this is not compatible with programs.zsh.ohMyZsh.custom as it requires an immutable store path while custom shall remain mutable! An evaluation failure will be thrown if both custom and customPkgs are set.

If third-party customizations (e.g. new themes) are supposed to be added to oh-my-zsh there are several pitfalls to keep in mind:

A derivation for oh-my-zsh may look like this:

{ stdenv, fetchFromGitHub }:

stdenv.mkDerivation rec {
  name = "exemplary-zsh-customization-${version}";
  version = "1.0.0";
  src = fetchFromGitHub {
    # path to the upstream repository
  };

  dontBuild = true;
  installPhase = ''
    mkdir -p $out/share/zsh/site-functions
    cp {themes,plugins} $out/share/zsh
    cp completions $out/share/zsh/site-functions
  '';
}

The binaries, dbb-app (a GUI tool) and dbb-cli (a CLI tool), are available through the digitalbitbox package which could be installed as follows:

environment.systemPackages = [
  pkgs.digitalbitbox
];

The digitalbitbox hardware package enables the udev rules for Digital Bitbox devices and may be installed as follows:

hardware.digitalbitbox.enable = true;

In order to alter the udev rules, one may provide different values for the udevRule51 and udevRule52 attributes by means of overriding as follows:

programs.digitalbitbox = {
  enable = true;
  package = pkgs.digitalbitbox.override {
    udevRule51 = "something else";
  };
};

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.

Enables all hardware supported by NixOS: i.e., all firmware is included, and all devices from which one may boot are enabled in the initrd. Its primary use is in the NixOS installation CDs.

The enabled kernel modules include support for SATA and PATA, SCSI (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and Hyper-V. Additionally, hardware.enableAllFirmware is enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically installed.

Defines the software packages included in the "minimal" installation CD. It installs several utilities useful in a simple recovery or install media, such as a text-mode web browser, and tools for manipulating block devices, networking, hardware diagnostics, and filesystems (with their respective kernel modules).

This profile is used in installer images. It provides an editable configuration.nix that imports all the modules that were also used when creating the image in the first place. As a result it allows users to edit and rebuild the live-system.

On images where the installation media also becomes an installation target, copying over configuration.nix should be disabled by setting installer.cloneConfig to false. For example, this is done in sd-image-aarch64.nix.

This profile just enables a demo user, with password demo, uid 1000, wheel group and autologin in the SDDM display manager.

This is the profile from which the Docker images are generated. It prepares a working system by importing the Minimal and Clone Config profiles, and setting appropriate configuration options that are useful inside a container context, like boot.isContainer.

Defines a NixOS configuration with the Plasma 5 desktop. It's used by the graphical installation CD.

It sets services.xserver.enable, services.xserver.displayManager.sddm.enable, services.xserver.desktopManager.plasma5.enable, and services.xserver.libinput.enable to true. It also includes glxinfo and firefox in the system packages list.

A profile with most (vanilla) hardening options enabled by default, potentially at the cost of features and performance.

This includes a hardened kernel, and limiting the system information available to processes through the /sys and /proc filesystems. It also disables the User Namespaces feature of the kernel, which stops Nix from being able to build anything (this particular setting can be overriden via security.allowUserNamespaces). See the profile source for further detail on which settings are altered.

Common configuration for headless machines (e.g., Amazon EC2 instances).

Disables sound, vesa, serial consoles, emergency mode, grub splash images and configures the kernel to reboot automatically on panic.

Provides a basic configuration for installation devices like CDs. This enables redistributable firmware, includes the Clone Config profile and a copy of the Nixpkgs channel, so nixos-install works out of the box.

Documentation for Nixpkgs and NixOS are forcefully enabled (to override the Minimal profile preference); the NixOS manual is shown automatically on TTY 8, udisks is disabled. Autologin is enabled as nixos user, while passwordless login as both root and nixos is possible. Passwordless sudo is enabled too. wpa_supplicant is enabled, but configured to not autostart.

It is explained how to login, start the ssh server, and if available, how to start the display manager.

Several settings are tweaked so that the installer has a better chance of succeeding under low-memory environments.

This profile defines a small NixOS configuration. It does not contain any graphical stuff. It's a very short file that enables noXlibs, sets i18n.supportedLocales to only support the user-selected locale, disables packages' documentation , and disables sound.

This profile contains common configuration for virtual machines running under QEMU (using virtio).

It makes virtio modules available on the initrd, sets the system time from the hardware clock to work around a bug in qemu-kvm, and enables rngd.

If your /boot partition runs out of space, after clearing old profiles you must rebuild your system with nixos-rebuild to update the /boot partition and clear space.

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.users.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];
'

By default the next free address in the 10.233.0.0/16 subnet will be chosen as container IP. This behavior can be altered by setting --host-address and --local-address:

# nixos-container create test --config-file test-container.nix \
    --local-address 10.235.1.2 --host-address 10.235.1.1

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.postgresql_9_6;
      };
  };

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-*" ];

You may need to restart your system for the changes to take effect.

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 attribute names within the name attribute path must be camel cased in general but should, as an exception, match the package attribute name when referencing a Nixpkgs package. For example, the option services.nix-serve.bindAddress references the nix-serve Nixpkgs package.

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 [ "gdm" ]);
};

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

Sometimes NixOS modules need to be used in configuration but exist outside of Nixpkgs. These modules can be imported:

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

{
  imports =
    [ # Use a locally-available module definition in
      # ./example-module/default.nix
        ./example-module
    ];

  services.exampleModule.enable = true;
}

The environment variable NIXOS_EXTRA_MODULE_PATH is an absolute path to a NixOS module that is included alongside the Nixpkgs NixOS modules. Like any NixOS module, this module can import additional modules:

# ./module-list/default.nix
[
  ./example-module1
  ./example-module2
]

# ./extra-module/default.nix
{ imports = import ./module-list.nix; }

# NIXOS_EXTRA_MODULE_PATH=/absolute/path/to/extra-module
{ config, lib, pkgs, ... }:

{
  # No `imports` needed

  services.exampleModule1.enable = true;
}

Modules that are imported can also be disabled. The option declarations, config implementation and the imports 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.

You can quickly validate your edits with make:

  $ cd /path/to/nixpkgs/nixos/doc/manual
  $ make

Once you are done making 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 23.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 44.5, “Meta Attributes” for an explanation.

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

import ./make-test-python.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 =
    ''
      Python code…
    '';
}

The attribute testScript is a bit of Python 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 Python 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 if this is also the identifier of the machine in the declarative config. If you didn't specify multiple machines using the nodes attribute, it is just machine. The following example 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.wait_for_unit("default.target")
if not "Linux" in machine.succeed("uname"):
  raise Exception("Wrong OS")

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

start_all()

The following methods are available on machine objects:

To test user units declared by systemd.user.services the optional user argument can be used:

machine.start()
machine.wait_for_x()
machine.wait_for_unit("xautolock.service", "x-session-user")

This applies to systemctl, get_unit_info, wait_for_unit, start_job and stop_job.

For faster dev cycles it's also possible to disable the code-linters (this shouldn't be commited though):

import ./make-test-python.nix {
  skipLint = true;
  machine =
    { config, pkgs, ... }:
    { configuration…
    };

  testScript =
    ''
      Python code…
    '';
}

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 Python statement, e.g.

> start_all()
> test_script()
> machine.succeed("touch /tmp/foo")
> print(machine.succeed("pwd")) # Show stdout of command

The function test_script 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 machine state is kept across VM restarts in /tmp/vm-state-machinename.

Going through an example of releasing NixOS 17.09:

For each release there are two release managers. After each release the release manager having managed two releases steps down and the release management team of the last release appoints a new release manager.

This makes sure a release management team always consists of one release manager who already has managed one release and one release manager being introduced to their role, making it easier to pass on knowledge and experience.

Release managers for the current NixOS release are tracked by GitHub team @NixOS/nixos-release-managers.

A release manager's role and responsibilities are: