To begin the installation, you have to boot your computer from the install drive.

The graphical installer is recommended for desktop users and will guide you through the installation.

NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI installation is broadly the same as for a BIOS installation. The differences are mentioned in the following steps.

The NixOS manual is available by running nixos-help in the command line or from the application menu in the desktop environment.

To have access to the command line on the graphical images, open Terminal (GNOME) or Konsole (Plasma) from the application menu.

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

$ sudo -i

You can use loadkeys to switch to your preferred keyboard layout. (We even provide neo2 via loadkeys de neo!)

If the text is too small to be legible, try setfont ter-v32n to increase the font size.

To install over a serial port connect with 115200n8 (e.g. picocom -b 115200 /dev/ttyUSB0). When the bootloader lists boot entries, select the serial console boot entry.

> add_network
0
> set_network 0 ssid "myhomenetwork"
OK
> set_network 0 psk "mypassword"
OK
> set_network 0 key_mgmt WPA-PSK
OK
> enable_network 0
OK

> add_network
0
> set_network 0 ssid "eduroam"
OK
> set_network 0 identity "myname@example.com"
OK
> set_network 0 password "mypassword"
OK
> set_network 0 key_mgmt WPA-EAP
OK
> enable_network 0
OK

<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=]

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

# parted /dev/sda -- mklabel gpt
# parted /dev/sda -- mkpart root ext4 512MB -8GB
# parted /dev/sda -- mkpart swap linux-swap -8GB 100%
# parted /dev/sda -- mkpart ESP fat32 1MB 512MB
# parted /dev/sda -- set 3 esp 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://channels.nixos.org/nixos-23.11";

To build an ISO image for the channel nixos-unstable:

$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ git switch nixos-unstable
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix

To check the content of an ISO image, mount it like so:

# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso

If you need additional (non-distributable) drivers or firmware in the installer, you might want to extend these configurations.

For example, to build the GNOME graphical installer ISO, but with support for certain WiFi adapters present in some MacBooks, you can create the following file at modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix:

{ config, ... }:

{
  imports = [ ./installation-cd-graphical-gnome.nix ];

  boot.initrd.kernelModules = [ "wl" ];

  boot.kernelModules = [ "kvm-intel" "wl" ];
  boot.extraModulePackages = [ config.boot.kernelPackages.broadcom_sta ];
}

Then build it like in the example above:

$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ export NIXPKGS_ALLOW_UNFREE=1
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix default.nix

The config value enforcement is implemented via mkImageMediaOverride = mkOverride 60; and therefore primes over simple value assignments, but also yields to mkForce.

This property allows image designers to implement in semantically correct ways those configuration values upon which the correct functioning of the image depends.

For example, the iso base image overrides those file systems which it needs at a minimum for correct functioning, while the installer base image overrides the entire file system layout because there can’t be any other guarantees on a live medium than those given by the live medium itself. The latter is especially true before formatting the target block device(s). On the other hand, the netboot iso only overrides its minimum dependencies since netboot images are always made-to-target.

You can define a partition that only contains the Nix store and then mount it under /nix/store. Because the /nix/store part of the paths is already determined by the mount point, you have to set stripNixStorePrefix = true; so that the prefix is stripped from the paths before copying them into the image.

fileSystems."/nix/store".device = "/dev/disk/by-partlabel/nix-store"

image.repart.partitions = {
  "store" = {
    storePaths = [ config.system.build.toplevel ];
    stripNixStorePrefix = true;
    repartConfig = {
      Type = "linux-generic";
      Label = "nix-store";
      ...
    };
  };
};

The image/repart.nix module can also be used to build self-contained software appliances.

The generation based update mechanism of NixOS is not suited for appliances. Updates of appliances are usually either performed by replacing the entire image with a new one or by updating partitions via an A/B scheme. See the Chrome OS update process for an example of how to achieve this. The appliance image built in the following example does not contain a configuration.nix and thus you will not be able to call nixos-rebuild from this system. Furthermore, it uses a Unified Kernel Image.

let
  pkgs = import <nixpkgs> { };
  efiArch = pkgs.stdenv.hostPlatform.efiArch;
in
(pkgs.nixos [
  ({ config, lib, pkgs, modulesPath, ... }: {

    imports = [ "${modulesPath}/image/repart.nix" ];

    boot.loader.grub.enable = false;

    fileSystems."/".device = "/dev/disk/by-label/nixos";

    image.repart = {
      name = "image";
      partitions = {
        "esp" = {
          contents = {
            "/EFI/BOOT/BOOT${lib.toUpper efiArch}.EFI".source =
              "${pkgs.systemd}/lib/systemd/boot/efi/systemd-boot${efiArch}.efi";

            "/EFI/Linux/${config.system.boot.loader.ukiFile}".source =
              "${config.system.build.uki}/${config.system.boot.loader.ukiFile}";
          };
          repartConfig = {
            Type = "esp";
            Format = "vfat";
            SizeMinBytes = "96M";
          };
        };
        "root" = {
          storePaths = [ config.system.build.toplevel ];
          repartConfig = {
            Type = "root";
            Format = "ext4";
            Label = "nixos";
            Minimize = "guess";
          };
        };
      };
    };

  })
]).image

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, in chapter Writing NixOS Modules) 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;
  environment.systemPackages = [ pkgs.vim ];
}

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 the lists of packages will 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. (If you’re wondering how it’s possible that the (indirect) result of a function is passed as an input to that same function: that’s because Nix is a “lazy” language — it only computes values when they are needed. This works as long as no individual configuration value depends on itself.)

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

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, 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";
        hash = "sha256-5rd/gffPfa761Kn1tl3myunD8TuM+66oy1O7XqVGDXM=";
      };
    };
  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";
    hash = "sha256-5rd/gffPfa761Kn1tl3myunD8TuM+66oy1O7XqVGDXM=";
  };
}

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

environment.systemPackages = [ pkgs.appimage-run ];

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.

Instead of using a custom perl script to create users and groups, you can use systemd-sysusers:

systemd.sysusers.enable = true;

The primary benefit of this is to remove a dependency on perl.

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

The LUKS volume should be automatically picked up by nixos-generate-config, but you might want to verify that your hardware-configuration.nix looks correct. To manually ensure that the 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;

boot.initrd = {
  luks.devices.root = {
    crypttabExtraOpts = [ "fido2-device=auto" ];
    device = "/dev/sda2";
  };
  systemd.enable = true;
};

# systemd-cryptenroll --fido2-device=auto /dev/sda2

# systemd-cryptenroll --recovery-key /dev/sda2

SSHFS is a FUSE filesystem that allows easy access to directories on a remote machine using the SSH File Transfer Protocol (SFTP). It means that if you have SSH access to a machine, no additional setup is needed to mount a directory.

$ sshfs my-user@example.com:/my-dir /mnt/my-dir

$ fusermount -u /mnt/my-dir

$ ssh-keygen -t ed25519 -P '' -f example-key
Generating public/private ed25519 key pair.
Your identification has been saved in test-key
Your public key has been saved in test-key.pub
The key fingerprint is:
SHA256:yjxl3UbTn31fLWeyLYTAKYJPRmzknjQZoyG8gSNEoIE my-user@workstation

{
  fileSystems."/mnt/my-dir" = {
    device = "my-user@example.com:/my-dir/";
    fsType = "sshfs";
    options =
      [ # Filesystem options
        "allow_other"          # for non-root access
        "_netdev"              # this is a network fs
        "x-systemd.automount"  # mount on demand

        # SSH options
        "reconnect"              # handle connection drops
        "ServerAliveInterval=15" # keep connections alive
        "IdentityFile=/var/secrets/example-key"
      ];
  };
}

{
  options =
    [ "ProxyJump=bastion@example.com"
      "Port=22"
    ];
}

{
  options =
    [ (builtins.replaceStrings [" "] ["\\040"]
        "ssh_command=${pkgs.openssh}/bin/ssh -v -L 8080:localhost:80")
    ];

}

$ journalctl -u $(systemd-escape -p /mnt/my-dir/).mount
Jun 22 11:41:18 workstation mount[87790]: SSHFS version 3.7.1
Jun 22 11:41:18 workstation mount[87793]: executing <ssh> <-x> <-a> <-oClearAllForwardings=yes> <-oServerAliveInterval=15> <-oIdentityFile=/var/secrets/wrong-key> <-2> <my-user@example.com> <-s> <sftp>
Jun 22 11:41:19 workstation mount[87793]: my-user@example.com: Permission denied (publickey).
Jun 22 11:41:19 workstation mount[87790]: read: Connection reset by peer
Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Mount process exited, code=exited, status=1/FAILURE
Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Failed with result 'exit-code'.
Jun 22 11:41:19 workstation systemd[1]: Failed to mount /mnt/my-dir.
Jun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Consumed 54ms CPU time, received 2.3K IP traffic, sent 2.7K IP traffic.

NixOS offers a convenient abstraction to create both read-only as well writable overlays.

fileSystems = {
  "/writable-overlay" = {
    overlay = {
      lowerdir = [ writableOverlayLowerdir ];
      upperdir = "/.rw-writable-overlay/upper";
      workdir = "/.rw-writable-overlay/work";
    };
    # Mount the writable overlay in the initrd.
    neededForBoot = true;
  };
  "/readonly-overlay".overlay.lowerdir = [
    writableOverlayLowerdir
    writableOverlayLowerdir2
  ];
};

If upperdir and workdir are not null, they will be created before the overlay is mounted.

To mount an overlay as read-only, you need to provide at least two lowerdirs.

The x11 login screen can be skipped entirely, automatically logging you into your window manager and desktop environment when you boot your computer.

This is especially helpful if you have disk encryption enabled. Since you already have to provide a password to decrypt your disk, entering a second password to login can be redundant.

To enable auto-login, you need to define your default window manager and desktop environment. If you wanted no desktop environment and i3 as your your window manager, you’d define:

services.xserver.displayManager.defaultSession = "none+i3";

Every display manager in NixOS supports auto-login, here is an example using lightdm for a user alice:

services.xserver.displayManager.lightdm.enable = true;
services.xserver.displayManager.autoLogin.enable = true;
services.xserver.displayManager.autoLogin.user = "alice";

There are two choices for Intel Graphics drivers in X.org: modesetting (included in the xorg-server itself) and intel (provided by the package xf86-video-intel).

The default and recommended is modesetting. It is a generic driver which uses the kernel mode setting (KMS) mechanism. It supports Glamor (2D graphics acceleration via OpenGL) and is actively maintained but may perform worse in some cases (like in old chipsets).

The second driver, intel, is specific to Intel GPUs, but not recommended by most distributions: it lacks several modern features (for example, it doesn’t support Glamor) and the package hasn’t been officially updated since 2015.

The results vary depending on the hardware, so you may have to try both drivers. Use the option services.xserver.videoDrivers to set one. The recommended configuration for modern systems is:

services.xserver.videoDrivers = [ "modesetting" ];

If you experience screen tearing no matter what, this configuration was reported to resolve the issue:

services.xserver.videoDrivers = [ "intel" ];
services.xserver.deviceSection = ''
  Option "DRI" "2"
  Option "TearFree" "true"
'';

Note that this will likely downgrade the performance compared to modesetting or intel with DRI 3 (default).

NVIDIA provides a proprietary driver for its graphics cards that has better 3D performance than the X.org drivers. It is not enabled by default because it’s not free software. You can enable it as follows:

services.xserver.videoDrivers = [ "nvidia" ];

Or if you have an older card, you may have to use one of the legacy drivers:

services.xserver.videoDrivers = [ "nvidiaLegacy390" ];
services.xserver.videoDrivers = [ "nvidiaLegacy340" ];
services.xserver.videoDrivers = [ "nvidiaLegacy304" ];

You may need to reboot after enabling this driver to prevent a clash with other kernel modules.

AMD provides a proprietary driver for its graphics cards that is not enabled by default because it’s not Free Software, is often broken in nixpkgs and as of this writing doesn’t offer more features or performance. If you still want to use it anyway, you need to explicitly set:

services.xserver.videoDrivers = [ "amdgpu-pro" ];

You will need to reboot after enabling this driver to prevent a clash with other kernel modules.

Support for Synaptics touchpads (found in many laptops such as the Dell Latitude series) can be enabled as follows:

services.xserver.libinput.enable = true;

The driver has many options (see Appendix A). For instance, the following disables tap-to-click behavior:

services.xserver.libinput.touchpad.tapping = false;

Note: the use of services.xserver.synaptics is deprecated since NixOS 17.09.

GTK themes can be installed either to user profile or system-wide (via environment.systemPackages). To make Qt 5 applications look similar to GTK ones, you can use the following configuration:

qt.enable = true;
qt.platformTheme = "gtk2";
qt.style = "gtk2";

It is possible to install custom XKB keyboard layouts using the option services.xserver.xkb.extraLayouts.

As a first example, we are going to create a layout based on the basic US layout, with an additional layer to type some greek symbols by pressing the right-alt key.

Create a file called us-greek with the following content (under a directory called symbols; it’s an XKB peculiarity that will help with testing):

xkb_symbols "us-greek"
{
  include "us(basic)"            // includes the base US keys
  include "level3(ralt_switch)"  // configures right alt as a third level switch

  key <LatA> { [ a, A, Greek_alpha ] };
  key <LatB> { [ b, B, Greek_beta  ] };
  key <LatG> { [ g, G, Greek_gamma ] };
  key <LatD> { [ d, D, Greek_delta ] };
  key <LatZ> { [ z, Z, Greek_zeta  ] };
};

A minimal layout specification must include the following:

services.xserver.xkb.extraLayouts.us-greek = {
  description = "US layout with alt-gr greek";
  languages   = [ "eng" ];
  symbolsFile = /yourpath/symbols/us-greek;
};

Applying this customization requires rebuilding several packages, and a broken XKB file can lead to the X session crashing at login. Therefore, you’re strongly advised to test your layout before applying it:

$ nix-shell -p xorg.xkbcomp
$ setxkbmap -I/yourpath us-greek -print | xkbcomp -I/yourpath - $DISPLAY

You can inspect the predefined XKB files for examples:

$ echo "$(nix-build --no-out-link '<nixpkgs>' -A xorg.xkeyboardconfig)/etc/X11/xkb/"

Once the configuration is applied, and you did a logout/login cycle, the layout should be ready to use. You can try it by e.g. running setxkbmap us-greek and then type <alt>+a (it may not get applied in your terminal straight away). To change the default, the usual services.xserver.xkb.layout option can still be used.

A layout can have several other components besides xkb_symbols, for example we will define new keycodes for some multimedia key and bind these to some symbol.

Use the xev utility from pkgs.xorg.xev to find the codes of the keys of interest, then create a media-key file to hold the keycodes definitions

xkb_keycodes "media"
{
 <volUp>   = 123;
 <volDown> = 456;
}

Now use the newly define keycodes in media-sym:

xkb_symbols "media"
{
 key.type = "ONE_LEVEL";
 key <volUp>   { [ XF86AudioLowerVolume ] };
 key <volDown> { [ XF86AudioRaiseVolume ] };
}

As before, to install the layout do

services.xserver.xkb.extraLayouts.media = {
  description  = "Multimedia keys remapping";
  languages    = [ "eng" ];
  symbolsFile  = /path/to/media-key;
  keycodesFile = /path/to/media-sym;
};

Unfortunately, the Xorg server does not (currently) support setting a keymap directly but relies instead on XKB rules to select the matching components (keycodes, types, …) of a layout. This means that components other than symbols won’t be loaded by default. As a workaround, you can set the keymap using setxkbmap at the start of the session with:

services.xserver.displayManager.sessionCommands = "setxkbmap -keycodes media";

If you are manually starting the X server, you should set the argument -xkbdir /etc/X11/xkb, otherwise X won’t find your layout files. For example with xinit run

$ xinit -- -xkbdir /etc/X11/xkb

To learn how to write layouts take a look at the XKB documentation . More example layouts can also be found here .

OpenCL is a general compute API. It is used by various applications such as Blender and Darktable to accelerate certain operations.

OpenCL applications load drivers through the Installable Client Driver (ICD) mechanism. In this mechanism, an ICD file specifies the path to the OpenCL driver for a particular GPU family. In NixOS, there are two ways to make ICD files visible to the ICD loader. The first is through the OCL_ICD_VENDORS environment variable. This variable can contain a directory which is scanned by the ICL loader for ICD files. For example:

$ export \
  OCL_ICD_VENDORS=`nix-build '<nixpkgs>' --no-out-link -A rocmPackages.clr.icd`/etc/OpenCL/vendors/

The second mechanism is to add the OpenCL driver package to hardware.opengl.extraPackages. This links the ICD file under /run/opengl-driver, where it will be visible to the ICD loader.

The proper installation of OpenCL drivers can be verified through the clinfo command of the clinfo package. This command will report the number of hardware devices that is found and give detailed information for each device:

$ clinfo | head -n3
Number of platforms  1
Platform Name        AMD Accelerated Parallel Processing
Platform Vendor      Advanced Micro Devices, Inc.

hardware.opengl.extraPackages = [
  rocmPackages.clr.icd
];

hardware.opengl.extraPackages = [
  intel-compute-runtime
];

Vulkan is a graphics and compute API for GPUs. It is used directly by games or indirectly though compatibility layers like DXVK.

By default, if hardware.opengl.driSupport is enabled, mesa is installed and provides Vulkan for supported hardware.

Similar to OpenCL, Vulkan drivers are loaded through the Installable Client Driver (ICD) mechanism. ICD files for Vulkan are JSON files that specify the path to the driver library and the supported Vulkan version. All successfully loaded drivers are exposed to the application as different GPUs. In NixOS, there are two ways to make ICD files visible to Vulkan applications: an environment variable and a module option.

The first option is through the VK_ICD_FILENAMES environment variable. This variable can contain multiple JSON files, separated by :. For example:

$ export \
  VK_ICD_FILENAMES=`nix-build '<nixpkgs>' --no-out-link -A amdvlk`/share/vulkan/icd.d/amd_icd64.json

The second mechanism is to add the Vulkan driver package to hardware.opengl.extraPackages. This links the ICD file under /run/opengl-driver, where it will be visible to the ICD loader.

The proper installation of Vulkan drivers can be verified through the vulkaninfo command of the vulkan-tools package. This command will report the hardware devices and drivers found, in this example output amdvlk and radv:

$ vulkaninfo | grep GPU
                GPU id  : 0 (Unknown AMD GPU)
                GPU id  : 1 (AMD RADV NAVI10 (LLVM 9.0.1))
     ...
GPU0:
        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU
        deviceName     = Unknown AMD GPU
GPU1:
        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU

A simple graphical application that uses Vulkan is vkcube from the vulkan-tools package.

hardware.opengl.extraPackages = [
  pkgs.amdvlk
];

# To enable Vulkan support for 32-bit applications, also add:
hardware.opengl.extraPackages32 = [
  pkgs.driversi686Linux.amdvlk
];

# Force radv
environment.variables.AMD_VULKAN_ICD = "RADV";
# Or
environment.variables.VK_ICD_FILENAMES =
  "/run/opengl-driver/share/vulkan/icd.d/radeon_icd.x86_64.json";

VA-API (Video Acceleration API) is an open-source library and API specification, which provides access to graphics hardware acceleration capabilities for video processing.

VA-API drivers are loaded by libva. The version in nixpkgs is built to search the opengl driver path, so drivers can be installed in hardware.opengl.extraPackages.

VA-API can be tested using:

$ nix-shell -p libva-utils --run vainfo

hardware.opengl.extraPackages = [
  intel-media-driver
];

hardware.opengl.extraPackages = [
  intel-vaapi-driver
];

Thunar (the Xfce file manager) is automatically enabled when Xfce is enabled. To enable Thunar without enabling Xfce, use the configuration option programs.thunar.enable instead of adding pkgs.xfce.thunar to environment.systemPackages.

If you’d like to add extra plugins to Thunar, add them to programs.thunar.plugins. You shouldn’t just add them to environment.systemPackages.

Even after enabling udisks2, volume management might not work. Thunar and/or the desktop takes time to show up. Thunar will spit out this kind of message on start (look at journalctl --user -b).

Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported

This is caused by some needed GNOME services not running. This is all fixed by enabling “Launch GNOME services on startup” in the Advanced tab of the Session and Startup settings panel. Alternatively, you can run this command to do the same thing.

$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true

It is necessary to log out and log in again for this to take effect.

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.

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.settings.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, and Privacy Extensions (RFC 4946) are enabled by default. You can adjust the default for this by setting networking.tempAddresses. This option may be overridden on a per-interface basis by networking.interfaces.<name>.tempAddress. 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 the section called “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
  '';

NixOS uses the udev predictable naming scheme to assign names to network interfaces. This means that by default cards are not given the traditional names like eth0 or eth1, whose order can change unpredictably across reboots. Instead, relying on physical locations and firmware information, the scheme produces names like ens1, enp2s0, etc.

These names are predictable but less memorable and not necessarily stable: for example installing new hardware or changing firmware settings can result in a name change. If this is undesirable, for example if you have a single ethernet card, you can revert to the traditional scheme by setting networking.usePredictableInterfaceNames to false.

systemd.network.links."10-wan" = {
  matchConfig.PermanentMACAddress = "52:54:00:12:01:01";
  linkConfig.Name = "wan";
};

boot.initrd.services.udev.rules = ''
  SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
  ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
'';

Please refer to the Nixpkgs manual for the various ways of building a custom kernel.

To use your custom kernel package in your NixOS configuration, set

boot.kernelPackages = pkgs.linuxPackagesFor yourCustomKernel;

The Linux kernel does not have Rust language support enabled by default. For kernel versions 6.7 or newer, experimental Rust support can be enabled. In a NixOS configuration, set:

boot.kernelPatches = [
  {
    name = "Rust Support";
    patch = null;
    features = {
      rust = true;
    };
  }
];

This section was moved to the Nixpkgs manual.

It’s a common issue that the latest stable version of ZFS doesn’t support the latest available Linux kernel. It is recommended to use the latest available LTS that’s compatible with ZFS. Usually this is the default kernel provided by nixpkgs (i.e. pkgs.linuxPackages).

Alternatively, it’s possible to pin the system to the latest available kernel version that is supported by ZFS like this:

{
  boot.kernelPackages = pkgs.zfs.latestCompatibleLinuxPackages;
}

Please note that the version this attribute points to isn’t monotonic because the latest kernel version only refers to kernel versions supported by the Linux developers. In other words, the latest kernel version that ZFS is compatible with may decrease over time.

An example: the latest version ZFS is compatible with is 5.19 which is a non-longterm version. When 5.19 is out of maintenance, the latest supported kernel version is 5.15 because it’s longterm and the versions 5.16, 5.17 and 5.18 are already out of maintenance because they’re non-longterm.

This section focuses on configuring a web-based server on top of the Apache HTTP server, which uses WebDAV/DeltaV for communication.

For more information on the general setup, please refer to the the appropriate section of the Subversion book.

To configure, include in /etc/nixos/configuration.nix code to activate Apache HTTP, setting services.httpd.adminAddr appropriately:

services.httpd.enable = true;
services.httpd.adminAddr = ...;
networking.firewall.allowedTCPPorts = [ 80 443 ];

For a simple Subversion server with basic authentication, configure the Subversion module for Apache as follows, setting hostName and documentRoot appropriately, and SVNParentPath to the parent directory of the repositories, AuthzSVNAccessFile to the location of the .authz file describing access permission, and AuthUserFile to the password file.

services.httpd.extraModules = [
    # note that order is *super* important here
    { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }
    { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }
  ];
  services.httpd.virtualHosts = {
    "svn" = {
       hostName = HOSTNAME;
       documentRoot = DOCUMENTROOT;
       locations."/svn".extraConfig = ''
           DAV svn
           SVNParentPath REPO_PARENT
           AuthzSVNAccessFile ACCESS_FILE
           AuthName "SVN Repositories"
           AuthType Basic
           AuthUserFile PASSWORD_FILE
           Require valid-user
      '';
    }

The key "svn" is just a symbolic name identifying the virtual host. The "/svn" in locations."/svn".extraConfig is the path underneath which the repositories will be served.

This page explains how to set up the Subversion configuration itself. This boils down to the following:

Underneath REPO_PARENT repositories can be set up as follows:

$ svn create REPO_NAME

Repository files need to be accessible by wwwrun:

$ chown -R wwwrun:wwwrun REPO_PARENT

The password file PASSWORD_FILE can be created as follows:

$ htpasswd -cs PASSWORD_FILE USER_NAME

Additional users can be set up similarly, omitting the c flag:

$ htpasswd -s PASSWORD_FILE USER_NAME

The file describing access permissions ACCESS_FILE will look something like the following:

[/]
* = r

[REPO_NAME:/]
USER_NAME = rw

The Subversion repositories will be accessible as http://HOSTNAME/svn/REPO_NAME.

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 elementary-mail).

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.

All of the core apps, optional apps, games, and core developer tools from GNOME are available.

To enable the GNOME desktop use:

services.xserver.desktopManager.gnome.enable = true;
services.xserver.displayManager.gdm.enable = true;

The default applications used in NixOS are very minimal, inspired by the defaults used in gnome-build-meta.

services.gnome.core-utilities.enable = false;

services.gnome.tracker-miners.enable = false;
services.gnome.tracker.enable = false;

services.gnome.games.enable = true;

services.gnome.core-developer-tools.enable = true;

GNOME Flashback provides a desktop environment based on the classic GNOME 2 architecture. You can enable the default GNOME Flashback session, which uses the Metacity window manager, with:

services.xserver.desktopManager.gnome.flashback.enableMetacity = true;

It is also possible to create custom sessions that replace Metacity with a different window manager using services.xserver.desktopManager.gnome.flashback.customSessions.

The following example uses xmonad window manager:

services.xserver.desktopManager.gnome.flashback.customSessions = [
  {
    wmName = "xmonad";
    wmLabel = "XMonad";
    wmCommand = "${pkgs.haskellPackages.xmonad}/bin/xmonad";
    enableGnomePanel = false;
  }
];

Icon themes and GTK themes don’t require any special option to install in NixOS.

You can add them to environment.systemPackages and switch to them with GNOME Tweaks. If you’d like to do this manually in dconf, change the values of the following keys:

/org/gnome/desktop/interface/gtk-theme
/org/gnome/desktop/interface/icon-theme

in dconf-editor

Most Shell extensions are packaged under the gnomeExtensions attribute. Some packages that include Shell extensions, like gnome.gpaste, don’t have their extension decoupled under this attribute.

You can install them like any other package:

environment.systemPackages = [
  gnomeExtensions.dash-to-dock
  gnomeExtensions.gsconnect
  gnomeExtensions.mpris-indicator-button
];

Unfortunately, we lack a way for these to be managed in a completely declarative way. So you have to enable them manually with an Extensions application. It is possible to use a GSettings override for this on org.gnome.shell.enabled-extensions, but that will only influence the default value.

Majority of software building on the GNOME platform use GLib’s GSettings system to manage runtime configuration. For our purposes, the system consists of XML schemas describing the individual configuration options, stored in the package, and a settings backend, where the values of the settings are stored. On NixOS, like on most Linux distributions, dconf database is used as the backend.

GSettings vendor overrides can be used to adjust the default values for settings of the GNOME desktop and apps by replacing the default values specified in the XML schemas. Using overrides will allow you to pre-seed user settings before you even start the session.

You can override the default GSettings values using the services.xserver.desktopManager.gnome.extraGSettingsOverrides option.

Take note that whatever packages you want to override GSettings for, you need to add them to services.xserver.desktopManager.gnome.extraGSettingsOverridePackages.

You can use dconf-editor tool to explore which GSettings you can set.

services.xserver.desktopManager.gnome = {
  extraGSettingsOverrides = ''
    # Change default background
    [org.gnome.desktop.background]
    picture-uri='file://${pkgs.nixos-artwork.wallpapers.mosaic-blue.gnomeFilePath}'

    # Favorite apps in gnome-shell
    [org.gnome.shell]
    favorite-apps=['org.gnome.Console.desktop', 'org.gnome.Nautilus.desktop']
  '';

  extraGSettingsOverridePackages = [
    pkgs.gsettings-desktop-schemas # for org.gnome.desktop
    pkgs.gnome.gnome-shell # for org.gnome.shell
  ];
};

Bootloaders should use RFC-0125’s Bootspec format and synthesis tools to identify the key properties for bootable system generations.

The first step is to embed your secret in a JWE file. JWE files have to be created through the clevis command line. 3 types of policies are supported:

Secrets are pinned against the presence of a TPM2 device, for example:

echo -n hi | clevis encrypt tpm2 '{}' > hi.jwe

Secrets are pinned against the presence of a Tang server, for example:

echo -n hi | clevis encrypt tang '{"url": "http://tang.local"}' > hi.jwe

Using Shamir’s Secret Sharing (sss), secrets are pinned using a combination of the two preceding policies. For example:

echo -n hi | clevis encrypt sss \
'{"t": 2, "pins": {"tpm2": {"pcr_ids": "0"}, "tang": {"url": "http://tang.local"}}}' \
> hi.jwe

For more complete documentation on how to generate a secret with clevis, see the clevis documentation.

In order to activate unattended decryption of a resource at boot, enable the clevis module:

boot.initrd.clevis.enable = true;

Then, specify the device you want to decrypt using a given clevis secret. Clevis will automatically try to decrypt the device at boot and will fallback to interactive unlocking if the decryption policy is not fulfilled.

boot.initrd.clevis.devices."/dev/nvme0n1p1".secretFile = ./nvme0n1p1.jwe;

Only bcachefs, zfs and luks encrypted devices are supported at this time.

Garage provides a cookbook documentation on how to upgrade: https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/

Here are some baseline instructions to handle advanced upgrades in Garage, when in doubt, please refer to upstream instructions.

Your upgraded cluster should be in a working state, re-enable API and web access.

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

While 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. Garage v0.8.0 should be available in nixpkgs as pkgs.garage_0_8_0). 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 garage-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 should keep those packages, but mark them as insecure in an expression like this (in <nixpkgs/pkgs/tools/filesystem/garage/default.nix>):

/* ... */
{
  garage_0_7_3 = generic {
    version = "0.7.3";
    sha256 = "0000000000000000000000000000000000000000000000000000";
    eol = true;
  };
}

Ideally we should make sure that it’s possible to jump two NixOS versions forward: i.e. the warnings and the logic in the module should guard a user to upgrade from a Garage on e.g. 22.11 to a Garage on 23.11.

YouTrack exposes a web GUI installer on first login. You need a token to access it. You can find this token in the log of the youtrack service. The log line looks like

* JetBrains YouTrack 2023.3 Configuration Wizard will be available on [http://127.0.0.1:8090/?wizard_token=somelongtoken] after start

Starting with YouTrack 2023.1, JetBrains no longer distributes it as as JAR. The new distribution with the JetBrains Launcher as a ZIP changed the basic data structure and also some configuration parameters. Check out https://www.jetbrains.com/help/youtrack/server/YouTrack-Java-Start-Parameters.html for more information on the new configuration options. When upgrading to YouTrack 2023.1 or higher, a migration script will move the old state directory to /var/lib/youtrack/2022_3 as a backup. A one-time manual update is required:

If you migrate a larger YouTrack instance, it might be useful to set -Dexodus.entityStore.refactoring.forceAll=true in services.youtrack.generalParameters for the first startup of YouTrack 2023.x.

By default, the module will execute Suwayomi-Server backend and web UI:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;
  };
}

It runs in the systemd service named suwayomi-server in the data directory /var/lib/suwayomi-server.

You can change the default parameters with some other parameters:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;

    dataDir = "/var/lib/suwayomi"; # Default is "/var/lib/suwayomi-server"
    openFirewall = true;

    settings = {
      server.port = 4567;
    };
  };
}

If you want to create a desktop icon, you can activate the system tray option:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;

    dataDir = "/var/lib/suwayomi"; # Default is "/var/lib/suwayomi-server"
    openFirewall = true;

    settings = {
      server.port = 4567;
      server.enableSystemTray = true;
    };
  };
}

You can configure a basic authentication to the web interface with:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;

    openFirewall = true;

    settings = {
      server.port = 4567;
      server = {
        basicAuthEnabled = true;
        basicAuthUsername = "username";

        # NOTE: this is not a real upstream option
        basicAuthPasswordFile = ./path/to/the/password/file;
      };
    };
  };
}

Not all the configuration options are available directly in this module, but you can add the other options of suwayomi-server with:

{ ... }:

{
  services.suwayomi-server = {
    enable = true;

    openFirewall = true;

    settings = {
      server = {
        port = 4567;
        autoDownloadNewChapters = false;
        maxSourcesInParallel" = 6;
      };
    };
  };
}

At first, a secret key is needed to be generated. This can be done with e.g.

$ openssl rand -base64 64

After that, plausible can be deployed like this:

{
  services.plausible = {
    enable = true;
    adminUser = {
      # activate is used to skip the email verification of the admin-user that's
      # automatically created by plausible. This is only supported if
      # postgresql is configured by the module. This is done by default, but
      # can be turned off with services.plausible.database.postgres.setup.
      activate = true;
      email = "admin@localhost";
      passwordFile = "/run/secrets/plausible-admin-pwd";
    };
    server = {
      baseUrl = "http://analytics.example.org";
      # secretKeybaseFile is a path to the file which contains the secret generated
      # with openssl as described above.
      secretKeybaseFile = "/run/secrets/plausible-secret-key-base";
    };
  };
}

the minimum to start pict-rs is

services.pict-rs.enable = true;

this will start the http server on port 8080 by default.

pict-rs offers the following endpoints:

Nextcloud is a PHP-based application which requires an HTTP server (services.nextcloud and optionally supports services.nginx).

For the database, you can set services.nextcloud.config.dbtype to either sqlite (the default), mysql, or pgsql. The simplest is sqlite, which will be automatically created and managed by the application. For the last two, you can easily create a local database by setting services.nextcloud.database.createLocally to true, Nextcloud will automatically be configured to connect to it through socket.

A very basic configuration may look like this:

{ pkgs, ... }:
{
  services.nextcloud = {
    enable = true;
    hostName = "nextcloud.tld";
    database.createLocally = true;
    config = {
      dbtype = "pgsql";
      adminpassFile = "/path/to/admin-pass-file";
    };
  };

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

The hostName option is 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.settings.trusted_domains.

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

By default, nginx is used as reverse-proxy for nextcloud. However, it’s possible to use e.g. httpd by explicitly disabling nginx using services.nginx.enable and fixing the settings listen.owner & listen.group in the corresponding phpfpm pool.

An exemplary configuration may look like this:

{ config, lib, pkgs, ... }: {
  services.nginx.enable = false;
  services.nextcloud = {
    enable = true;
    hostName = "localhost";

    /* further, required options */
  };
  services.phpfpm.pools.nextcloud.settings = {
    "listen.owner" = config.services.httpd.user;
    "listen.group" = config.services.httpd.group;
  };
  services.httpd = {
    enable = true;
    adminAddr = "webmaster@localhost";
    extraModules = [ "proxy_fcgi" ];
    virtualHosts."localhost" = {
      documentRoot = config.services.nextcloud.package;
      extraConfig = ''
        <Directory "${config.services.nextcloud.package}">
          <FilesMatch "\.php$">
            <If "-f %{REQUEST_FILENAME}">
              SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/"
            </If>
          </FilesMatch>
          <IfModule mod_rewrite.c>
            RewriteEngine On
            RewriteBase /
            RewriteRule ^index\.php$ - [L]
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteRule . /index.php [L]
          </IfModule>
          DirectoryIndex index.php
          Require all granted
          Options +FollowSymLinks
        </Directory>
      '';
    };
  };
}

Nextcloud apps are installed statefully through the web interface. Some apps may require extra PHP extensions to be installed. This can be configured with the services.nextcloud.phpExtraExtensions setting.

Alternatively, extra apps can also be declared with the services.nextcloud.extraApps setting. When using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating apps that are managed by Nix. If you want automatic updates it is recommended that you use web interface to install apps.

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 should 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";
    eol = true;
  };
}

Ideally we should make sure that it’s possible to jump two NixOS versions forward: i.e. the warnings and the logic in the module should guard a user to upgrade from a Nextcloud on e.g. 19.09 to a Nextcloud on 20.09.

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.

the minimum to start lemmy is

services.lemmy = {
  enable = true;
  settings = {
    hostname = "lemmy.union.rocks";
    database.createLocally = true;
  };
  caddy.enable = true;
}

this will start the backend on port 8536 and the frontend on port 1234. It will expose your instance with a caddy reverse proxy to the hostname you’ve provided. Postgres will be initialized on that same instance automatically.

On first connection you will be asked to define an admin user.

An administrative user with the username admin is automatically created in the master realm. Its initial password can be configured by setting services.keycloak.initialAdminPassword and defaults to changeme. The password is not stored safely and should be changed immediately in the admin panel.

Refer to the Keycloak Server Administration Guide for information on how to administer your Keycloak instance.

Keycloak can be used with either PostgreSQL, MariaDB or MySQL. Which one is used can be configured in services.keycloak.database.type. The selected database will automatically be enabled and a database and role created unless services.keycloak.database.host is changed from its default of localhost or services.keycloak.database.createLocally is set to false.

External database access can also be configured by setting services.keycloak.database.host, services.keycloak.database.name, services.keycloak.database.username, services.keycloak.database.useSSL and services.keycloak.database.caCert as appropriate. Note that you need to manually create the database and allow the configured database user full access to it.

services.keycloak.database.passwordFile must be set to the path to a file containing the password used to log in to the database. If services.keycloak.database.host and services.keycloak.database.createLocally are kept at their defaults, the database role keycloak with that password is provisioned on the local database instance.

The hostname is used to build the public URL used as base for all frontend requests and must be configured through services.keycloak.settings.hostname.

services.keycloak.settings.hostname-strict-backchannel determines whether Keycloak should force all requests to go through the frontend URL. By default, Keycloak allows backend requests to instead use its local hostname or IP address and may also advertise it to clients through its OpenID Connect Discovery endpoint.

For more information on hostname configuration, see the Hostname section of the Keycloak Server Installation and Configuration Guide.

By default, Keycloak won’t accept unsecured HTTP connections originating from outside its local network.

HTTPS support requires a TLS/SSL certificate and a private key, both PEM formatted. Their paths should be set through services.keycloak.sslCertificate and services.keycloak.sslCertificateKey.

You can package custom themes and make them visible to Keycloak through services.keycloak.themes. See the Themes section of the Keycloak Server Development Guide and the description of the aforementioned NixOS option for more information.

Keycloak server configuration parameters can be set in services.keycloak.settings. These correspond directly to options in conf/keycloak.conf. Some of the most important parameters are documented as suboptions, the rest can be found in the All configuration section of the Keycloak Server Installation and Configuration Guide.

Options containing secret data should be set to an attribute set containing the attribute _secret - a string pointing to a file containing the value the option should be set to. See the description of services.keycloak.settings for an example.

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

services.keycloak = {
  enable = true;
  settings = {
    hostname = "keycloak.example.com";
    hostname-strict-backchannel = true;
  };
  initialAdminPassword = "e6Wcm0RrtegMEHl";  # change on first login
  sslCertificate = "/run/keys/ssl_cert";
  sslCertificateKey = "/run/keys/ssl_key";
  database.passwordFile = "/run/keys/db_password";
};

A minimal configuration using Let’s Encrypt for TLS certificates looks like this:

{
  services.jitsi-meet = {
    enable = true;
    hostName = "jitsi.example.com";
  };
  services.jitsi-videobridge.openFirewall = true;
  networking.firewall.allowedTCPPorts = [ 80 443 ];
  security.acme.email = "me@example.com";
  security.acme.acceptTerms = true;
}

Here is the minimal configuration with additional configurations:

{
  services.jitsi-meet = {
    enable = true;
    hostName = "jitsi.example.com";
    config = {
      enableWelcomePage = false;
      prejoinPageEnabled = true;
      defaultLang = "fi";
    };
    interfaceConfig = {
      SHOW_JITSI_WATERMARK = false;
      SHOW_WATERMARK_FOR_GUESTS = false;
    };
  };
  services.jitsi-videobridge.openFirewall = true;
  networking.firewall.allowedTCPPorts = [ 80 443 ];
  security.acme.email = "me@example.com";
  security.acme.acceptTerms = true;
}

A minimal configuration looks like this:

{
  services.honk = {
    enable = true;
    host = "0.0.0.0";
    port = 8080;
    username = "username";
    passwordFile = "/etc/honk/password.txt";
    servername = "honk.example.com";
  };

  networking.firewall.allowedTCPPorts = [ 8080 ];
}

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
  '';
}

The following configuration sets up the PostgreSQL as database backend and binds GoToSocial to 127.0.0.1:8080, expecting to be run behind a HTTP proxy on gotosocial.example.com.

services.gotosocial = {
  enable = true;
  setupPostgresqlDB = true;
  settings = {
    application-name = "My GoToSocial";
    host = "gotosocial.example.com";
    protocol = "https";
    bind-address = "127.0.0.1";
    port = 8080;
  };
};

Please refer to the GoToSocial Documentation for additional configuration options.

Although it is possible to expose GoToSocial directly, it is common practice to operate it behind an HTTP reverse proxy such as nginx.

networking.firewall.allowedTCPPorts = [ 80 443 ];
services.nginx = {
  enable = true;
  clientMaxBodySize = "40M";
  virtualHosts = with config.services.gotosocial.settings; {
    "${host}" = {
      enableACME = true;
      forceSSL = true;
      locations = {
        "/" = {
          recommendedProxySettings = true;
          proxyWebsockets = true;
          proxyPass = "http://${bind-address}:${toString port}";
        };
      };
    };
  };
};

Please refer to SSL/TLS Certificates with ACME for details on how to provision an SSL/TLS certificate.

After the GoToSocial service is running, the gotosocial-admin utility can be used to manage users. In particular an administrative user can be created with

$ sudo gotosocial-admin account create --username <nickname> --email <email> --password <password>
$ sudo gotosocial-admin account confirm --username <nickname>
$ sudo gotosocial-admin account promote --username <nickname>

A minimal configuration using Let’s Encrypt for TLS certificates looks like this:

services.discourse = {
  enable = true;
  hostname = "discourse.example.com";
  admin = {
    email = "admin@example.com";
    username = "admin";
    fullName = "Administrator";
    passwordFile = "/path/to/password_file";
  };
  secretKeyBaseFile = "/path/to/secret_key_base_file";
};
security.acme.email = "me@example.com";
security.acme.acceptTerms = true;

Provided a proper DNS setup, you’ll be able to connect to the instance at discourse.example.com and log in using the credentials provided in services.discourse.admin.

To set up TLS using a regular certificate and key on file, use the services.discourse.sslCertificate and services.discourse.sslCertificateKey options:

services.discourse = {
  enable = true;
  hostname = "discourse.example.com";
  sslCertificate = "/path/to/ssl_certificate";
  sslCertificateKey = "/path/to/ssl_certificate_key";
  admin = {
    email = "admin@example.com";
    username = "admin";
    fullName = "Administrator";
    passwordFile = "/path/to/password_file";
  };
  secretKeyBaseFile = "/path/to/secret_key_base_file";
};

Discourse uses PostgreSQL to store most of its data. A database will automatically be enabled and a database and role created unless services.discourse.database.host is changed from its default of null or services.discourse.database.createLocally is set to false.

External database access can also be configured by setting services.discourse.database.host, services.discourse.database.username and services.discourse.database.passwordFile as appropriate. Note that you need to manually create a database called discourse (or the name you chose in services.discourse.database.name) and allow the configured database user full access to it.

In addition to the basic setup, you’ll want to configure an SMTP server Discourse can use to send user registration and password reset emails, among others. You can also optionally let Discourse receive email, which enables people to reply to threads and conversations via email.

A basic setup which assumes you want to use your configured hostname as email domain can be done like this:

services.discourse = {
  enable = true;
  hostname = "discourse.example.com";
  sslCertificate = "/path/to/ssl_certificate";
  sslCertificateKey = "/path/to/ssl_certificate_key";
  admin = {
    email = "admin@example.com";
    username = "admin";
    fullName = "Administrator";
    passwordFile = "/path/to/password_file";
  };
  mail.outgoing = {
    serverAddress = "smtp.emailprovider.com";
    port = 587;
    username = "user@emailprovider.com";
    passwordFile = "/path/to/smtp_password_file";
  };
  mail.incoming.enable = true;
  secretKeyBaseFile = "/path/to/secret_key_base_file";
};

This assumes you have set up an MX record for the address you’ve set in hostname and requires proper SPF, DKIM and DMARC configuration to be done for the domain you’re sending from, in order for email to be reliably delivered.

If you want to use a different domain for your outgoing email (for example example.com instead of discourse.example.com) you should set services.discourse.mail.notificationEmailAddress and services.discourse.mail.contactEmailAddress manually.

Additional site settings and backend settings, for which no explicit NixOS options are provided, can be set in services.discourse.siteSettings and services.discourse.backendSettings respectively.

services.discourse = {
  enable = true;
  hostname = "discourse.example.com";
  sslCertificate = "/path/to/ssl_certificate";
  sslCertificateKey = "/path/to/ssl_certificate_key";
  admin = {
    email = "admin@example.com";
    username = "admin";
    fullName = "Administrator";
    passwordFile = "/path/to/password_file";
  };
  mail.outgoing = {
    serverAddress = "smtp.emailprovider.com";
    port = 587;
    username = "user@emailprovider.com";
    passwordFile = "/path/to/smtp_password_file";
  };
  mail.incoming.enable = true;
  siteSettings = {
    required = {
      title = "My Cats";
      site_description = "Discuss My Cats (and be nice plz)";
    };
    login = {
      enable_github_logins = true;
      github_client_id = "a2f6dfe838cb3206ce20";
      github_client_secret._secret = /run/keys/discourse_github_client_secret;
    };
  };
  backendSettings = {
    max_reqs_per_ip_per_minute = 300;
    max_reqs_per_ip_per_10_seconds = 60;
    max_asset_reqs_per_ip_per_10_seconds = 250;
    max_reqs_per_ip_mode = "warn+block";
  };
  secretKeyBaseFile = "/path/to/secret_key_base_file";
};

You can install Discourse plugins using the services.discourse.plugins option. Pre-packaged plugins are provided in <your_discourse_package_here>.plugins. If you want the full suite of plugins provided through nixpkgs, you can also set the services.discourse.package option to pkgs.discourseAllPlugins.

Plugins can be built with the <your_discourse_package_here>.mkDiscoursePlugin function. Normally, it should suffice to provide a name and src attribute. If the plugin has Ruby dependencies, however, they need to be packaged in accordance with the Developing with Ruby section of the Nixpkgs manual and the appropriate gem options set in bundlerEnvArgs (normally gemdir is sufficient). A plugin’s Ruby dependencies are listed in its plugin.rb file as function calls to gem. To construct the corresponding Gemfile manually, run bundle init, then add the gem lines to it verbatim.

Much of the packaging can be done automatically by the nixpkgs/pkgs/servers/web-apps/discourse/update.py script - just add the plugin to the plugins list in the update_plugins function and run the script:

./update.py update-plugins

Some plugins provide site settings. Their defaults can be configured using services.discourse.siteSettings, just like regular site settings. To find the names of these settings, look in the config/settings.yml file of the plugin repo.

For example, to add the discourse-spoiler-alert and discourse-solved plugins, and disable discourse-spoiler-alert by default:

services.discourse = {
  enable = true;
  hostname = "discourse.example.com";
  sslCertificate = "/path/to/ssl_certificate";
  sslCertificateKey = "/path/to/ssl_certificate_key";
  admin = {
    email = "admin@example.com";
    username = "admin";
    fullName = "Administrator";
    passwordFile = "/path/to/password_file";
  };
  mail.outgoing = {
    serverAddress = "smtp.emailprovider.com";
    port = 587;
    username = "user@emailprovider.com";
    passwordFile = "/path/to/smtp_password_file";
  };
  mail.incoming.enable = true;
  plugins = with config.services.discourse.package.plugins; [
    discourse-spoiler-alert
    discourse-solved
  ];
  siteSettings = {
    plugins = {
      spoiler_enabled = false;
    };
  };
  secretKeyBaseFile = "/path/to/secret_key_base_file";
};

The Elixir configuration file required by Akkoma is generated automatically from services.akkoma.config. Secrets must be included from external files outside of the Nix store by setting the configuration option to an attribute set containing the attribute _secret – a string pointing to the file containing the actual value of the option.

For the mandatory configuration settings these secrets will be generated automatically if the referenced file does not exist during startup, unless disabled through services.akkoma.initSecrets.

The following configuration binds Akkoma to the Unix socket /run/akkoma/socket, expecting to be run behind a HTTP proxy on fediverse.example.com.

services.akkoma.enable = true;
services.akkoma.config = {
  ":pleroma" = {
    ":instance" = {
      name = "My Akkoma instance";
      description = "More detailed description";
      email = "admin@example.com";
      registration_open = false;
    };

    "Pleroma.Web.Endpoint" = {
      url.host = "fediverse.example.com";
    };
  };
};

Please refer to the configuration cheat sheet for additional configuration options.

After the Akkoma service is running, the administration utility can be used to manage users. In particular an administrative user can be created with

$ pleroma_ctl user new <nickname> <email> --admin --moderator --password <password>

Although it is possible to expose Akkoma directly, it is common practice to operate it behind an HTTP reverse proxy such as nginx.

services.akkoma.nginx = {
  enableACME = true;
  forceSSL = true;
};

services.nginx = {
  enable = true;

  clientMaxBodySize = "16m";
  recommendedTlsSettings = true;
  recommendedOptimisation = true;
  recommendedGzipSettings = true;
};

Please refer to SSL/TLS Certificates with ACME for details on how to provision an SSL/TLS certificate.

# Enable nginx slice module distributed with Tengine
services.nginx.package = pkgs.tengine;

# Enable media proxy
services.akkoma.config.":pleroma".":media_proxy" = {
  enabled = true;
  proxy_opts.redirect_on_failure = true;
};

# Adjust the persistent cache size as needed:
#  Assuming an average object size of 128 KiB, around 1 MiB
#  of memory is required for the key zone per GiB of cache.
# Ensure that the cache directory exists and is writable by nginx.
services.nginx.commonHttpConfig = ''
  proxy_cache_path /var/cache/nginx/cache/akkoma-media-cache
    levels= keys_zone=akkoma_media_cache:16m max_size=16g
    inactive=1y use_temp_path=off;
'';

services.akkoma.nginx = {
  locations."/proxy" = {
    proxyPass = "http://unix:/run/akkoma/socket";

    extraConfig = ''
      proxy_cache akkoma_media_cache;

      # Cache objects in slices of 1 MiB
      slice 1m;
      proxy_cache_key $host$uri$is_args$args$slice_range;
      proxy_set_header Range $slice_range;

      # Decouple proxy and upstream responses
      proxy_buffering on;
      proxy_cache_lock on;
      proxy_ignore_client_abort on;

      # Default cache times for various responses
      proxy_cache_valid 200 1y;
      proxy_cache_valid 206 301 304 1h;

      # Allow serving of stale items
      proxy_cache_use_stale error timeout invalid_header updating;
    '';
  };
};

services.akkoma.config.":pleroma".":mrf".policies =
  map (pkgs.formats.elixirConf { }).lib.mkRaw [
    "Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy"
];

services.akkoma.config.":pleroma".":media_preview_proxy" = {
  enabled = true;
  thumbnail_max_width = 1920;
  thumbnail_max_height = 1080;
};

Akkoma will be deployed with the akkoma-fe and admin-fe frontends by default. These can be modified by setting services.akkoma.frontends.

The following example overrides the primary frontend’s default configuration using a custom derivation.

services.akkoma.frontends.primary.package = pkgs.runCommand "akkoma-fe" {
  config = builtins.toJSON {
    expertLevel = 1;
    collapseMessageWithSubject = false;
    stopGifs = false;
    replyVisibility = "following";
    webPushHideIfCW = true;
    hideScopeNotice = true;
    renderMisskeyMarkdown = false;
    hideSiteFavicon = true;
    postContentType = "text/markdown";
    showNavShortcuts = false;
  };
  nativeBuildInputs = with pkgs; [ jq xorg.lndir ];
  passAsFile = [ "config" ];
} ''
  mkdir $out
  lndir ${pkgs.akkoma-frontends.akkoma-fe} $out

  rm $out/static/config.json
  jq -s add ${pkgs.akkoma-frontends.akkoma-fe}/static/config.json ${config} \
    >$out/static/config.json
'';

Akkoma comes with a number of modules to police federation with other ActivityPub instances. The most valuable for typical users is the :mrf_simple module which allows limiting federation based on instance hostnames.

This configuration snippet provides an example on how these can be used. Choosing an adequate federation policy is not trivial and entails finding a balance between connectivity to the rest of the fediverse and providing a pleasant experience to the users of an instance.

services.akkoma.config.":pleroma" = with (pkgs.formats.elixirConf { }).lib; {
  ":mrf".policies = map mkRaw [
    "Pleroma.Web.ActivityPub.MRF.SimplePolicy"
  ];

  ":mrf_simple" = {
    # Tag all media as sensitive
    media_nsfw = mkMap {
      "nsfw.weird.kinky" = "Untagged NSFW content";
    };

    # Reject all activities except deletes
    reject = mkMap {
      "kiwifarms.cc" = "Persistent harassment of users, no moderation";
    };

    # Force posts to be visible by followers only
    followers_only = mkMap {
      "beta.birdsite.live" = "Avoid polluting timelines with Twitter posts";
    };
  };
};

This example strips GPS and location metadata from uploads, deduplicates them and anonymises the the file name.

services.akkoma.config.":pleroma"."Pleroma.Upload".filters =
  map (pkgs.formats.elixirConf { }).lib.mkRaw [
    "Pleroma.Upload.Filter.Exiftool"
    "Pleroma.Upload.Filter.Dedupe"
    "Pleroma.Upload.Filter.AnonymizeFilename"
  ];

Pleroma instances can be migrated to Akkoma either by copying the database and upload data or by pointing Akkoma to the existing data. The necessary database migrations are run automatically during startup of the service.

The configuration has to be copy‐edited manually.

Depending on the size of the database, the initial migration may take a long time and exceed the startup timeout of the system manager. To work around this issue one may adjust the startup timeout systemd.services.akkoma.serviceConfig.TimeoutStartSec or simply run the migrations manually:

pleroma_ctl migrate

# Create a copy of the database
nix-shell -p postgresql --run 'createdb -T pleroma akkoma'

# Copy upload data
mkdir /var/lib/akkoma
cp -R --reflink=auto /var/lib/pleroma/uploads /var/lib/akkoma/

# Delete original database
nix-shell -p postgresql --run 'dropdb pleroma'

# Delete original Pleroma state
rm -r /var/lib/pleroma

# Adjust these settings according to the database name and upload directory path used by Pleroma
services.akkoma.config.":pleroma"."Pleroma.Repo".database = "pleroma";
services.akkoma.config.":pleroma".":instance".upload_dir = "/var/lib/pleroma/uploads";

the minimum to start meilisearch is

services.meilisearch.enable = true;

this will start the http server included with meilisearch on port 7700.

test with curl -X GET 'http://localhost:7700/health'

you first need to add documents to an index before you can search for documents.

A common struggle for most XMPP newcomers is to find the right set of XMPP Extensions (XEPs) to setup. Forget to activate a few of those and your XMPP experience might turn into a nightmare!

The XMPP community tackles this problem by creating a meta-XEP listing a decent set of XEPs you should implement. This meta-XEP is issued every year, the 2020 edition being XEP-0423.

The NixOS Prosody module will implement most of these recommendend XEPs out of the box. That being said, two components still require some manual configuration: the Multi User Chat (MUC) and the HTTP File Upload ones. You’ll need to create a DNS subdomain for each of those. The current convention is to name your MUC endpoint conference.example.org and your HTTP upload domain upload.example.org.

A good configuration to start with, including a Multi User Chat (MUC) endpoint as well as a HTTP File Upload endpoint will look like this:

services.prosody = {
  enable = true;
  admins = [ "root@example.org" ];
  ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
  ssl.key = "/var/lib/acme/example.org/key.pem";
  virtualHosts."example.org" = {
      enabled = true;
      domain = "example.org";
      ssl.cert = "/var/lib/acme/example.org/fullchain.pem";
      ssl.key = "/var/lib/acme/example.org/key.pem";
  };
  muc = [ {
      domain = "conference.example.org";
  } ];
  uploadHttp = {
      domain = "upload.example.org";
  };
};

As you can see in the code snippet from the previous section, you’ll need a single TLS certificate covering your main endpoint, the MUC one as well as the HTTP Upload one. We can generate such a certificate by leveraging the ACME extraDomainNames module option.

Provided the setup detailed in the previous section, you’ll need the following acme configuration to generate a TLS certificate for the three endponits:

security.acme = {
  email = "root@example.org";
  acceptTerms = true;
  certs = {
    "example.org" = {
      webroot = "/var/www/example.org";
      email = "root@example.org";
      extraDomainNames = [ "conference.example.org" "upload.example.org" ];
    };
  };
};

The pleroma_ctl CLI utility will prompt you some questions and it will generate an initial config file. This is an example of usage

$ mkdir tmp-pleroma
$ cd tmp-pleroma
$ nix-shell -p pleroma-otp
$ pleroma_ctl instance gen --output config.exs --output-psql setup.psql

The config.exs file can be further customized following the instructions on the upstream documentation. Many refinements can be applied also after the service is running.

First, the Postgresql service must be enabled in the NixOS configuration

services.postgresql = {
  enable = true;
  package = pkgs.postgresql_13;
};

and activated with the usual

$ nixos-rebuild switch

Then you can create and seed the database, using the setup.psql file that you generated in the previous section, by running

$ sudo -u postgres psql -f setup.psql

In this section we will enable the Pleroma service only locally, so its configurations can be improved incrementally.

This is an example of configuration, where services.pleroma.configs option contains the content of the file config.exs, generated in the first section, but with the secrets (database password, endpoint secret key, salts, etc.) removed. Removing secrets is important, because otherwise they will be stored publicly in the Nix store.

services.pleroma = {
  enable = true;
  secretConfigFile = "/var/lib/pleroma/secrets.exs";
  configs = [
    ''
    import Config

    config :pleroma, Pleroma.Web.Endpoint,
      url: [host: "pleroma.example.net", scheme: "https", port: 443],
      http: [ip: {127, 0, 0, 1}, port: 4000]

    config :pleroma, :instance,
      name: "Test",
      email: "admin@example.net",
      notify_email: "admin@example.net",
      limit: 5000,
      registrations_open: true

    config :pleroma, :media_proxy,
      enabled: false,
      redirect_on_failure: true

    config :pleroma, Pleroma.Repo,
      adapter: Ecto.Adapters.Postgres,
      username: "pleroma",
      database: "pleroma",
      hostname: "localhost"

    # Configure web push notifications
    config :web_push_encryption, :vapid_details,
      subject: "mailto:admin@example.net"

    # ... TO CONTINUE ...
    ''
  ];
};

Secrets must be moved into a file pointed by services.pleroma.secretConfigFile, in our case /var/lib/pleroma/secrets.exs. This file can be created copying the previously generated config.exs file and then removing all the settings, except the secrets. This is an example

# Pleroma instance passwords

import Config

config :pleroma, Pleroma.Web.Endpoint,
   secret_key_base: "<the secret generated by pleroma_ctl>",
   signing_salt: "<the secret generated by pleroma_ctl>"

config :pleroma, Pleroma.Repo,
  password: "<the secret generated by pleroma_ctl>"

# Configure web push notifications
config :web_push_encryption, :vapid_details,
  public_key: "<the secret generated by pleroma_ctl>",
  private_key: "<the secret generated by pleroma_ctl>"

# ... TO CONTINUE ...

Note that the lines of the same configuration group are comma separated (i.e. all the lines end with a comma, except the last one), so when the lines with passwords are added or removed, commas must be adjusted accordingly.

The service can be enabled with the usual

$ nixos-rebuild switch

The service is accessible only from the local 127.0.0.1:4000 port. It can be tested using a port forwarding like this

$ ssh -L 4000:localhost:4000 myuser@example.net

and then accessing http://localhost:4000 from a web browser.

After Pleroma service is running, all Pleroma administration utilities can be used. In particular an admin user can be created with

$ pleroma_ctl user new <nickname> <email>  --admin --moderator --password <password>

In this configuration, Pleroma is listening only on the local port 4000. Nginx can be configured as a Reverse Proxy, for forwarding requests from public ports to the Pleroma service. This is an example of configuration, using Let’s Encrypt for the TLS certificates

security.acme = {
  email = "root@example.net";
  acceptTerms = true;
};

services.nginx = {
  enable = true;
  addSSL = true;

  recommendedTlsSettings = true;
  recommendedOptimisation = true;
  recommendedGzipSettings = true;

  recommendedProxySettings = false;
  # NOTE: if enabled, the NixOS proxy optimizations will override the Pleroma
  # specific settings, and they will enter in conflict.

  virtualHosts = {
    "pleroma.example.net" = {
      http2 = true;
      enableACME = true;
      forceSSL = true;

      locations."/" = {
        proxyPass = "http://127.0.0.1:4000";

        extraConfig = ''
          etag on;
          gzip on;

          add_header 'Access-Control-Allow-Origin' '*' always;
          add_header 'Access-Control-Allow-Methods' 'POST, PUT, DELETE, GET, PATCH, OPTIONS' always;
          add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Idempotency-Key' always;
          add_header 'Access-Control-Expose-Headers' 'Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id' always;
          if ($request_method = OPTIONS) {
            return 204;
          }
          add_header X-XSS-Protection "1; mode=block";
          add_header X-Permitted-Cross-Domain-Policies none;
          add_header X-Frame-Options DENY;
          add_header X-Content-Type-Options nosniff;
          add_header Referrer-Policy same-origin;
          add_header X-Download-Options noopen;
          proxy_http_version 1.1;
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection "upgrade";
          proxy_set_header Host $host;

          client_max_body_size 16m;
          # NOTE: increase if users need to upload very big files
        '';
      };
    };
  };
};

The absolute minimal configuration for the netbird daemon looks like this:

services.netbird.enable = true;

This will set up a netbird service listening on the port 51820 associated to the wt0 interface.

It is strictly equivalent to setting:

services.netbird.tunnels.wt0.stateDir = "netbird";

The enable option is mainly kept for backward compatibility, as defining netbird tunnels through the tunnels option is more expressive.

Using the services.netbird.tunnels option, it is also possible to define more than one netbird service running at the same time.

The following configuration will start a netbird daemon using the interface wt1 and the port 51830. Its configuration file will then be located at /var/lib/netbird-wt1/config.json.

services.netbird.tunnels = {
  wt1 = {
    port = 51830;
  };
};

To interact with it, you will need to specify the correct daemon address:

netbird --daemon-addr unix:///var/run/netbird-wt1/sock ...

The address will by default be unix:///var/run/netbird-<name>.

It is also possible to overwrite default options passed to the service, for example:

services.netbird.tunnels.wt1.environment = {
  NB_DAEMON_ADDR = "unix:///var/run/toto.sock"
};

This will set the socket to interact with the netbird service to /var/run/toto.sock.

A minimal configuration for Mosquitto is

services.mosquitto = {
  enable = true;
  listeners = [ {
    acl = [ "pattern readwrite #" ];
    omitPasswordAuth = true;
    settings.allow_anonymous = true;
  } ];
};

This will start a broker on port 1883, listening on all interfaces of the machine, allowing read/write access to all topics to any user without password requirements.

User authentication can be configured with the users key of listeners. A config that gives full read access to a user monitor and restricted write access to a user service could look like

services.mosquitto = {
  enable = true;
  listeners = [ {
    users = {
      monitor = {
        acl = [ "read #" ];
        password = "monitor";
      };
      service = {
        acl = [ "write service/#" ];
        password = "service";
      };
    };
  } ];
};

TLS authentication is configured by setting TLS-related options of the listener:

services.mosquitto = {
  enable = true;
  listeners = [ {
    port = 8883; # port change is not required, but helpful to avoid mistakes
    # ...
    settings = {
      cafile = "/path/to/mqtt.ca.pem";
      certfile = "/path/to/mqtt.pem";
      keyfile = "/path/to/mqtt.key";
    };
  } ];

The Mosquitto configuration has four distinct types of settings: the global settings of the daemon, listeners, plugins, and bridges. Bridges and listeners are part of the global configuration, plugins are part of listeners. Users of the broker are configured as parts of listeners rather than globally, allowing configurations in which a given user is only allowed to log in to the broker using specific listeners (eg to configure an admin user with full access to all topics, but restricted to localhost).

Almost all options of Mosquitto are available for configuration at their appropriate levels, some as NixOS options written in camel case, the remainders under settings with their exact names in the Mosquitto config file. The exceptions are acl_file (which is always set according to the acl attributes of a listener and its users) and per_listener_settings (which is always set to true).

A minimal configuration looks like this:

{
  services.gns3-server = {
    enable = true;

    auth = {
      enable = true;
      user = "gns3";
      passwordFile = "/var/lib/secrets/gns3_password";
    };

    ssl = {
      enable = true;
      certFile = "/var/lib/gns3/ssl/cert.pem";
      keyFile = "/var/lib/gns3/ssl/key.pem";
    };

    dynamips.enable = true;
    ubridge.enable = true;
    vpcs.enable = true;
  };
}

The absolute minimal configuration for the sync server looks like this:

services.mysql.package = pkgs.mariadb;

services.firefox-syncserver = {
  enable = true;
  secrets = builtins.toFile "sync-secrets" ''
    SYNC_MASTER_SECRET=this-secret-is-actually-leaked-to-/nix/store
  '';
  singleNode = {
    enable = true;
    hostname = "localhost";
    url = "http://localhost:5000";
  };
};

This will start a sync server that is only accessible locally. Once the services is running you can navigate to about:config in your Firefox profile and set identity.sync.tokenserver.uri to http://localhost:5000/1.0/sync/1.5. Your browser will now use your local sync server for data storage.

The firefox-syncserver service provides a number of options to make setting up small deployment easier. These are grouped under the singleNode element of the option tree and allow simple configuration of the most important parameters.

Single node setup is split into two kinds of options: those that affect the sync server itself, and those that affect its surroundings. Options that affect the sync server are capacity, which configures how many accounts may be active on this instance, and url, which holds the URL under which the sync server can be accessed. The url can be configured automatically when using nginx.

Options that affect the surroundings of the sync server are enableNginx, enableTLS and hostname. If enableNginx is set the sync server module will automatically add an nginx virtual host to the system using hostname as the domain and set url accordingly. If enableTLS is set the module will also enable ACME certificates on the new virtual host and force all connections to be made via TLS.

For actual deployment it is also recommended to store the secrets file in a secure location.

Litestream service is managed by a dedicated user named litestream which needs permission to the database file. Here’s an example config which gives required permissions to access grafana database:

{ pkgs, ... }:
{
  users.users.litestream.extraGroups = [ "grafana" ];

  systemd.services.grafana.serviceConfig.ExecStartPost = "+" + pkgs.writeShellScript "grant-grafana-permissions" ''
    timeout=10

    while [ ! -f /var/lib/grafana/data/grafana.db ];
    do
      if [ "$timeout" == 0 ]; then
        echo "ERROR: Timeout while waiting for /var/lib/grafana/data/grafana.db."
        exit 1
      fi

      sleep 1

      ((timeout--))
    done

    find /var/lib/grafana -type d -exec chmod -v 775 {} \;
    find /var/lib/grafana -type f -exec chmod -v 660 {} \;
  '';

  services.litestream = {
    enable = true;

    environmentFile = "/run/secrets/litestream";

    settings = {
      dbs = [
        {
          path = "/var/lib/grafana/data/grafana.db";
          replicas = [{
            url = "s3://mybkt.litestream.io/grafana";
          }];
        }
      ];
    };
  };
}

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;
    port = 9100;
    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 separately of course). For more information about configuration see man configuration.nix or search through the available options.

Prometheus can now be configured to consume the metrics produced by the exporter:

    services.prometheus = {
      # ...

      scrapeConfigs = [
        {
          job_name = "node";
          static_configs = [{
            targets = [ "localhost:${toString config.services.prometheus.exporters.node.port}" ];
          }];
        }
      ];

      # ...
    }

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

A very minimal setup which reads incoming reports from an external email address and saves them to a local Elasticsearch instance looks like this:

services.parsedmarc = {
  enable = true;
  settings.imap = {
    host = "imap.example.com";
    user = "alice@example.com";
    password = "/path/to/imap_password_file";
  };
  provision.geoIp = false; # Not recommended!
};

Note that GeoIP provisioning is disabled in the example for simplicity, but should be turned on for fully functional reports.

Instead of watching an external inbox, a local inbox can be automatically provisioned. The recipient’s name is by default set to dmarc, but can be configured in services.parsedmarc.provision.localMail.recipientName. You need to add an MX record pointing to the host. More concretely: for the example to work, an MX record needs to be set up for monitoring.example.com and the complete email address that should be configured in the domain’s dmarc policy is dmarc@monitoring.example.com.

services.parsedmarc = {
  enable = true;
  provision = {
    localMail = {
      enable = true;
      hostname = monitoring.example.com;
    };
    geoIp = false; # Not recommended!
  };
};

The reports can be visualized and summarized with parsedmarc’s official Grafana dashboard. For all views to work, and for the data to be complete, GeoIP databases are also required. The following example shows a basic deployment where the provisioned Elasticsearch instance is automatically added as a Grafana datasource, and the dashboard is added to Grafana as well.

services.parsedmarc = {
  enable = true;
  provision = {
    localMail = {
      enable = true;
      hostname = url;
    };
    grafana = {
      datasource = true;
      dashboard = true;
    };
  };
};

# Not required, but recommended for full functionality
services.geoipupdate = {
  settings = {
    AccountID = 000000;
    LicenseKey = "/path/to/license_key_file";
  };
};

services.grafana = {
  enable = true;
  addr = "0.0.0.0";
  domain = url;
  rootUrl = "https://" + url;
  protocol = "socket";
  security = {
    adminUser = "admin";
    adminPasswordFile = "/path/to/admin_password_file";
    secretKeyFile = "/path/to/secret_key_file";
  };
};

services.nginx = {
  enable = true;
  recommendedTlsSettings = true;
  recommendedOptimisation = true;
  recommendedGzipSettings = true;
  recommendedProxySettings = true;
  upstreams.grafana.servers."unix:/${config.services.grafana.socket}" = {};
  virtualHosts.${url} = {
    root = config.services.grafana.staticRootPath;
    enableACME = true;
    forceSSL = true;
    locations."/".tryFiles = "$uri @grafana";
    locations."@grafana".proxyPass = "http://grafana";
  };
};
users.users.nginx.extraGroups = [ "grafana" ];

A minimal configuration looks like this:

{
  services.ocsinventory-agent = {
    enable = true;
    settings = {
      server = "https://ocsinventory.localhost:8080/ocsinventory";
      tag = "01234567890123";
    };
  };
}

This configuration will periodically run the ocsinventory-agent SystemD service.

The OCS Inventory Agent will inventory the computer and then sends the results to the specified OCS Inventory Server.

A minimal configuration looks like this:

{
  services.goss = {
    enable = true;

    environment = {
      GOSS_FMT = "json";
      GOSS_LOGLEVEL = "TRACE";
    };

    settings = {
      addr."tcp://localhost:8080" = {
        reachable = true;
        local-address = "127.0.0.1";
      };
      command."check-goss-version" = {
        exec = "${lib.getExe pkgs.goss} --version";
        exit-status = 0;
      };
      dns.localhost.resolvable = true;
      file."/nix" = {
        filetype = "directory";
        exists = true;
      };
      group.root.exists = true;
      kernel-param."kernel.ostype".value = "Linux";
      service.goss = {
        enabled = true;
        running = true;
      };
      user.root.exists = true;
    };
  };
}

A basic config that notifies you of all certificate changes for your domain would look as follows:

services.certspotter = {
  enable = true;
  # replace example.org with your domain name
  watchlist = [ ".example.org" ];
  emailRecipients = [ "webmaster@example.org" ];
};

# Configure an SMTP client
programs.msmtp.enable = true;
# Or you can use any other module that provides sendmail, like
# services.nullmailer, services.opensmtpd, services.postfix

In this case, the leading dot in ".example.org" means that Cert Spotter should monitor not only example.org, but also all of its subdomains.

By default, NixOS configures Cert Spotter to skip all certificates issued before its first launch, because checking the entire Certificate Transparency logs requires downloading tens of terabytes of data. If you want to check the entire logs for previously issued certificates, you have to set services.certspotter.startAtEnd to false and remove all previously saved log state in /var/lib/certspotter/logs. The downloaded logs aren’t saved, so if you add a new domain to the watchlist and want Cert Spotter to go through the logs again, you will have to remove /var/lib/certspotter/logs again.

After catching up with the logs, Cert Spotter will start monitoring live logs. As of October 2023, it uses around 20 Mbps of traffic on average.

Cert Spotter supports running custom hooks instead of (or in addition to) sending emails. Hooks are shell scripts that will be passed certain environment variables.

To see hook documentation, see Cert Spotter’s man pages:

nix-shell -p certspotter --run 'man 8 certspotter-script'

For example, you can remove emailRecipients and send email notifications manually using the following hook:

services.certspotter.hooks = [
  (pkgs.writeShellScript "certspotter-hook" ''
    function print_email() {
      echo "Subject: [certspotter] $SUMMARY"
      echo "Mime-Version: 1.0"
      echo "Content-Type: text/plain; charset=US-ASCII"
      echo
      cat "$TEXT_FILENAME"
    }
    print_email | ${config.services.certspotter.sendmailPath} -i webmaster@example.org
  '')
];

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.

Sourcehut is a Python and Go based set of applications. This NixOS module also provides basic configuration integrating Sourcehut into locally running services.nginx, services.redis.servers.sourcehut, services.postfix and services.postgresql services.

A very basic configuration may look like this:

{ pkgs, ... }:
let
  fqdn =
    let
      join = hostName: domain: hostName + optionalString (domain != null) ".${domain}";
    in join config.networking.hostName config.networking.domain;
in {

  networking = {
    hostName = "srht";
    domain = "tld";
    firewall.allowedTCPPorts = [ 22 80 443 ];
  };

  services.sourcehut = {
    enable = true;
    git.enable = true;
    man.enable = true;
    meta.enable = true;
    nginx.enable = true;
    postfix.enable = true;
    postgresql.enable = true;
    redis.enable = true;
    settings = {
        "sr.ht" = {
          environment = "production";
          global-domain = fqdn;
          origin = "https://${fqdn}";
          # Produce keys with srht-keygen from sourcehut.coresrht.
          network-key = "/run/keys/path/to/network-key";
          service-key = "/run/keys/path/to/service-key";
        };
        webhooks.private-key= "/run/keys/path/to/webhook-key";
    };
  };

  security.acme.certs."${fqdn}".extraDomainNames = [
    "meta.${fqdn}"
    "man.${fqdn}"
    "git.${fqdn}"
  ];

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

    # Settings to setup what certificates are used for which endpoint.
    virtualHosts = {
      "${fqdn}".enableACME = true;
      "meta.${fqdn}".useACMEHost = fqdn:
      "man.${fqdn}".useACMEHost = fqdn:
      "git.${fqdn}".useACMEHost = fqdn:
    };
  };
}

The hostName option is used internally to configure the nginx reverse-proxy. The settings attribute set is used by the configuration generator and the result is placed in /etc/sr.ht/config.ini.

All configuration parameters are also stored in /etc/sr.ht/config.ini which is generated by the module and linked from the store to ensure that all values from config.ini can be modified by the module.

By default, nginx is used as reverse-proxy for sourcehut. However, it’s possible to use e.g. httpd by explicitly disabling nginx using services.nginx.enable and fixing the settings.

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.

When incoming_mail.enabled is set to true in extraConfig an additional service called gitlab-mailroom is enabled for fetching incoming mail.

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

The Apache Kafka service is configured almost exclusively through its settings option, with each attribute corresponding to the upstream configuration manual broker settings.

Unlike in Zookeeper mode, Kafka in KRaft mode requires each log dir to be “formatted” (which means a cluster-specific a metadata file must exist in each log dir)

The upstream intention is for users to execute the storage tool to achieve this, but this module contains a few extra options to automate this:

Migrating a cluster to the new settings-based changes requires adapting removed options to the corresponding upstream settings.

This means that the upstream Broker Configs documentation should be followed closely.

Note that dotted options in the upstream docs do not correspond to nested Nix attrsets, but instead as quoted top level settings attributes, as in services.apache-kafka.settings."broker.id", NOT services.apache-kafka.settings.broker.id.

Care should be taken, especially when migrating clusters from the old module, to ensure that the same intended configuration is reproduced faithfully via settings.

To assist in the comparison, the final config can be inspected by building the config file itself, ie. with: nix-build <nixpkgs/nixos> -A config.services.apache-kafka.configFiles.serverProperties.

Notable changes to be aware of include:

By default, the module creates a systemd unit which runs the sync server with an isolated user using the systemd DynamicUser option.

This can be done by enabling the anki-sync-server service:

{ ... }:

{
  services.anki-sync-server.enable = true;
}

It is necessary to set at least one username-password pair under services.anki-sync-server.users. For example

{
  services.anki-sync-server.users = [
    {
      username = "user";
      passwordFile = /etc/anki-sync-server/user;
    }
  ];
}

Here, passwordFile is the path to a file containing just the password in plaintext. Make sure to set permissions to make this file unreadable to any user besides root.

By default, the server listen address services.anki-sync-server.host is set to localhost, listening on port services.anki-sync-server.port, and does not open the firewall. This is suitable for purely local testing, or to be used behind a reverse proxy. If you want to expose the sync server directly to other computers (not recommended in most circumstances, because the sync server doesn’t use HTTPS), then set the following options:

{
  services.anki-sync-server.host = "0.0.0.0";
  services.anki-sync-server.openFirewall = true;
}

The ankisyncd NixOS module provides similar functionality, but using a third-party implementation, anki-sync-server-rs. According to that project’s README, it is “no longer maintained”, and not recommended for Anki 2.1.64+.

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, lib, config, ... }:
let
  fqdn = "${config.networking.hostName}.${config.networking.domain}";
  baseUrl = "https://${fqdn}";
  clientConfig."m.homeserver".base_url = baseUrl;
  serverConfig."m.server" = "${fqdn}:443";
  mkWellKnown = data: ''
    default_type application/json;
    add_header Access-Control-Allow-Origin *;
    return 200 '${builtins.toJSON data}';
  '';
in {
  networking.hostName = "myhostname";
  networking.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;
    recommendedTlsSettings = true;
    recommendedOptimisation = true;
    recommendedGzipSettings = true;
    recommendedProxySettings = true;
    virtualHosts = {
      # 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.
      "${config.networking.domain}" = {
        enableACME = true;
        forceSSL = true;
        # This section is not needed if the server_name of matrix-synapse is equal to
        # the domain (i.e. example.org from @foo:example.org) and the federation port
        # is 8448.
        # Further reference can be found in the docs about delegation under
        # https://element-hq.github.io/synapse/latest/delegate.html
        locations."= /.well-known/matrix/server".extraConfig = mkWellKnown serverConfig;
        # This is usually needed for homeserver discovery (from e.g. other Matrix clients).
        # Further reference can be found in the upstream docs at
        # https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient
        locations."= /.well-known/matrix/client".extraConfig = mkWellKnown clientConfig;
      };
      "${fqdn}" = {
        enableACME = true;
        forceSSL = true;
        # It's also possible to do a redirect here or something else, this vhost is not
        # needed for Matrix. It's recommended though to *not put* element
        # here, see also the section about Element.
        locations."/".extraConfig = ''
          return 404;
        '';
        # Forward all Matrix API calls to the synapse Matrix homeserver. A trailing slash
        # *must not* be used here.
        locations."/_matrix".proxyPass = "http://[::1]:8008";
        # Forward requests for e.g. SSO and password-resets.
        locations."/_synapse/client".proxyPass = "http://[::1]:8008";
      };
    };
  };

  services.matrix-synapse = {
    enable = true;
    settings.server_name = config.networking.domain;
    # The public base URL value must match the `base_url` value set in `clientConfig` above.
    # The default value here is based on `server_name`, so if your `server_name` is different
    # from the value of `fqdn` above, you will likely run into some mismatched domain names
    # in client applications.
    settings.public_baseurl = baseUrl;
    settings.listeners = [
      { port = 8008;
        bind_addresses = [ "::1" ];
        type = "http";
        tls = false;
        x_forwarded = true;
        resources = [ {
          names = [ "client" "federation" ];
          compress = true;
        } ];
      }
    ];
  };
}

If you want to run a server with public registration by anybody, you can then enable services.matrix-synapse.settings.enable_registration = true;. Otherwise, or you can generate a registration secret with pwgen -s 64 1 and set it with services.matrix-synapse.settings.registration_shared_secret. To create a new user or admin from the terminal your client listener must be configured to use TCP sockets. Then you can run the following after you have set the secret and have rebuilt NixOS:

$ nix-shell -p 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.

Element Web is the reference web client for Matrix and developed by the core team at matrix.org. Element was formerly known as Riot.im, see the Element introductory blog post for more information. The following snippet can be optionally added to the code before to complete the synapse installation with a web client served at https://element.myhostname.example.org and https://element.example.org. Alternatively, you can use the hosted copy at https://app.element.io/, 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."element.${fqdn}" = {
    enableACME = true;
    forceSSL = true;
    serverAliases = [
      "element.${config.networking.domain}"
    ];

    root = pkgs.element-web.override {
      conf = {
        default_server_config = clientConfig; # see `clientConfig` from the snippet above.
      };
    };
  };
}

First create a new Room which will be used as a management room for Mjolnir. In this room, Mjolnir will log possible errors and debugging information. You’ll need to set this Room-ID in services.mjolnir.managementRoom.

Next, create a new user for Mjolnir on your homeserver, if not present already.

The Mjolnir Matrix user expects to be free of any rate limiting. See Synapse #6286 for an example on how to achieve this.

If you want Mjolnir to be able to deactivate users, move room aliases, shutdown rooms, etc. you’ll need to make the Mjolnir user a Matrix server admin.

Now invite the Mjolnir user to the management room.

It is recommended to use Pantalaimon, so your management room can be encrypted. This also applies if you are looking to moderate an encrypted room.

To enable the Pantalaimon E2E Proxy for mjolnir, enable services.mjolnir.pantalaimon. This will autoconfigure a new Pantalaimon instance, which will connect to the homeserver set in services.mjolnir.homeserverUrl and Mjolnir itself will be configured to connect to the new Pantalaimon instance.

{
  services.mjolnir = {
    enable = true;
    homeserverUrl = "https://matrix.domain.tld";
    pantalaimon = {
       enable = true;
       username = "mjolnir";
       passwordFile = "/run/secrets/mjolnir-password";
    };
    protectedRooms = [
      "https://matrix.to/#/!xxx:domain.tld"
    ];
    managementRoom = "!yyy:domain.tld";
  };
}

A Synapse module is also available to apply the same rulesets the bot uses across an entire homeserver.

To use the Antispam Module, add matrix-synapse-plugins.matrix-synapse-mjolnir-antispam to the Synapse plugin list and enable the mjolnir.Module module.

{
  services.matrix-synapse = {
    plugins = with pkgs; [
      matrix-synapse-plugins.matrix-synapse-mjolnir-antispam
    ];
    extraConfig = ''
      modules:
        - module: mjolnir.Module
          config:
            # Prevent servers/users in the ban lists from inviting users on this
            # server to rooms. Default true.
            block_invites: true
            # Flag messages sent by servers/users in the ban lists as spam. Currently
            # this means that spammy messages will appear as empty to users. Default
            # false.
            block_messages: false
            # Remove users from the user directory search by filtering matrix IDs and
            # display names by the entries in the user ban list. Default false.
            block_usernames: false
            # The room IDs of the ban lists to honour. Unlike other parts of Mjolnir,
            # this list cannot be room aliases or permalinks. This server is expected
            # to already be joined to the room - Mjolnir will not automatically join
            # these rooms.
            ban_lists:
              - "!roomid:example.org"
    '';
  };
}

For a basic configuration with Postfix as the MTA, the following settings are suggested:

{ config, ... }: {
  services.postfix = {
    enable = true;
    relayDomains = ["hash:/var/lib/mailman/data/postfix_domains"];
    sslCert = config.security.acme.certs."lists.example.org".directory + "/full.pem";
    sslKey = config.security.acme.certs."lists.example.org".directory + "/key.pem";
    config = {
      transport_maps = ["hash:/var/lib/mailman/data/postfix_lmtp"];
      local_recipient_maps = ["hash:/var/lib/mailman/data/postfix_lmtp"];
    };
  };
  services.mailman = {
    enable = true;
    serve.enable = true;
    hyperkitty.enable = true;
    webHosts = ["lists.example.org"];
    siteOwner = "mailman@example.org";
  };
  services.nginx.virtualHosts."lists.example.org".enableACME = true;
  networking.firewall.allowedTCPPorts = [ 25 80 443 ];
}

DNS records will also be required:

After this has been done and appropriate DNS records have been set up, the Postorius mailing list manager and the Hyperkitty archive browser will be available at https://lists.example.org/. Note that this setup is not sufficient to deliver emails to most email providers nor to avoid spam – a number of additional measures for authenticating incoming and outgoing mails, such as SPF, DMARC and DKIM are necessary, but outside the scope of the Mailman module.

Mailman also supports other MTA, though with a little bit more configuration. For example, to use Mailman with Exim, you can use the following settings:

{ config, ... }: {
  services = {
    mailman = {
      enable = true;
      siteOwner = "mailman@example.org";
      enablePostfix = false;
      settings.mta = {
        incoming = "mailman.mta.exim4.LMTP";
        outgoing = "mailman.mta.deliver.deliver";
        lmtp_host = "localhost";
        lmtp_port = "8024";
        smtp_host = "localhost";
        smtp_port = "25";
        configuration = "python:mailman.config.exim4";
      };
    };
    exim = {
      enable = true;
      # You can configure Exim in a separate file to reduce configuration.nix clutter
      config = builtins.readFile ./exim.conf;
    };
  };
}

The exim config needs some special additions to work with Mailman. Currently NixOS can’t manage Exim config with such granularity. Please refer to Mailman documentation for more info on configuring Mailman for working with Exim.

Emacs can be installed in the normal way for Nix (see 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
*/

# The first non-comment line in this file indicates that
# the whole file represents a function.
{ pkgs ? import <nixpkgs> {} }:

let
  # The let expression below defines a myEmacs binding pointing to the
  # current stable version of Emacs. This binding is here to separate
  # the choice of the Emacs binary from the specification of the
  # required packages.
  myEmacs = pkgs.emacs;
  # This generates an emacsWithPackages function. It takes a single
  # argument: a function from a package set to a list of packages
  # (the packages that will be available in Emacs).
  emacsWithPackages = (pkgs.emacsPackagesFor myEmacs).emacsWithPackages;
in
  # The rest of the file specifies the list of packages to install. In the
  # example, two packages (magit and zerodark-theme) are taken from
  # MELPA stable.
  emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
    magit          # ; Integrate git <C-x g>
    zerodark-theme # ; Nicolas' theme
  ])
  # Two packages (undo-tree and zoom-frm) are taken from MELPA.
  ++ (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-+>
  ])
  # Three packages are taken from GNU ELPA.
  ++ (with epkgs.elpaPackages; [
    auctex         # ; LaTeX mode
    beacon         # ; highlight my cursor when scrolling
    nameless       # ; hide current package name everywhere in elisp code
  ])
  # notmuch is taken from a nixpkgs derivation which contains an Emacs mode.
  ++ [
    pkgs.notmuch   # From main packages set
  ])

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

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

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

{
  packageOverrides = super: let self = super.pkgs; in {
    myemacs = import ./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;

$ 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

If you want to only use extension packages from Nixpkgs, you can add (setq package-archives nil) to your init file.

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>

Enabling the livebook service creates a user systemd unit which runs the server.

{ ... }:

{
  services.livebook = {
    enableUserService = true;
    environment = {
      LIVEBOOK_PORT = 20123;
      LIVEBOOK_PASSWORD = "mypassword";
    };
    # See note below about security
    environmentFile = "/var/lib/livebook.env";
  };
}

The Livebook documentation lists all the applicable environment variables. It is recommended to at least set LIVEBOOK_PASSWORD or LIVEBOOK_TOKEN_ENABLED=false.

services.livebook.extraPackages = with pkgs; [ gcc gnumake ];

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

A very basic configuration for Athens that acts as a caching and forwarding HTTP proxy is:

{
    services.athens = {
      enable = true;
    };
}

If you want to prevent Athens from writing to disk, you can instead configure it to cache modules only in memory:

{
    services.athens = {
      enable = true;
      storageType = "memory";
    };
}

To use the local proxy in Go builds, you can set the proxy as environment variable:

{
  environment.variables = {
    GOPROXY = "http://localhost:3000"
  };
}

It is currently not possible to use the local proxy for builds done by the Nix daemon. This might be enabled by experimental features, specifically configurable-impure-env, in upcoming Nix versions.

By default, TigerBeetle will only listen on a local interface. To configure it to listen on a different interface (and to configure it to connect to other replicas, if you’re creating more than one), you’ll have to set the addresses option. Note that the TigerBeetle module won’t open any firewall ports automatically, so if you configure it to listen on an external interface, you’ll need to ensure that connections can reach it:

  services.tigerbeetle = {
    enable = true;
    addresses = [ "0.0.0.0:3001" ];
  };

  networking.firewall.allowedTCPPorts = [ 3001 ];

A complete list of options for TigerBeetle can be found here.

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

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

Note that you are required to specify the desired version of PostgreSQL (e.g. pkgs.postgresql_15). 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";

As of NixOS 23.11, services.postgresql.ensureUsers.*.ensurePermissions has been deprecated, after a change to default permissions in PostgreSQL 15 invalidated most of its previous use cases:

    systemd.services.postgresql.postStart = lib.mkAfter ''
      $PSQL service1 -c 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO "extraUser1"'
      $PSQL service1 -c 'GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO "extraUser1"'
      # ....
    '';

    systemd.services."migrate-service1-db1" = {
      serviceConfig.Type = "oneshot";
      requiredBy = "service1.service";
      before = "service1.service";
      after = "postgresql.service";
      serviceConfig.User = "postgres";
      environment.PSQL = "psql --port=${toString services.postgresql.port}";
      path = [ postgresql ];
      script = ''
        $PSQL service1 -c 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO "extraUser1"'
        $PSQL service1 -c 'GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO "extraUser1"'
        # ....
      '';
    };

    environment.PSQL = "psql --port=${toString services.postgresql.port}";
    path = [ postgresql ];
    systemd.services."service1".preStart = ''
      $PSQL -c 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO "extraUser1"'
      $PSQL -c 'GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO "extraUser1"'
      # ....
    '';

    systemd.services."migrate-service1-db1" = {
      serviceConfig.Type = "oneshot";
      requiredBy = "service1.service";
      before = "service1.service";
      after = "postgresql.service";
      serviceConfig.User = "service1";
      environment.PSQL = "psql --port=${toString services.postgresql.port}";
      path = [ postgresql ];
      script = ''
        $PSQL -c 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO "extraUser1"'
        $PSQL -c 'GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO "extraUser1"'
        # ....
      '';
    };

Major PostgreSQL upgrades require a downtime and a few imperative steps to be called. This is the case because each major version has some internal changes in the databases’ state during major releases. Because of that, NixOS places the state into /var/lib/postgresql/<version> where each version can be obtained like this:

$ nix-instantiate --eval -A postgresql_13.psqlSchema
"13"

For an upgrade, a script like this can be used to simplify the process:

{ config, pkgs, ... }:
{
  environment.systemPackages = [
    (let
      # XXX specify the postgresql package you'd like to upgrade to.
      # Do not forget to list the extensions you need.
      newPostgres = pkgs.postgresql_13.withPackages (pp: [
        # pp.plv8
      ]);
    in pkgs.writeScriptBin "upgrade-pg-cluster" ''
      set -eux
      # XXX it's perhaps advisable to stop all services that depend on postgresql
      systemctl stop postgresql

      export NEWDATA="/var/lib/postgresql/${newPostgres.psqlSchema}"

      export NEWBIN="${newPostgres}/bin"

      export OLDDATA="${config.services.postgresql.dataDir}"
      export OLDBIN="${config.services.postgresql.package}/bin"

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

      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_15 package, its plugin collection is accessed by pkgs.postgresql_15.pkgs:

$ nix repl '<nixpkgs>'

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

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

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

services.postgresql.package = pkgs.postgresql_12;
services.postgresql.extraPlugins = ps: with ps; [
  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_12.withPackages (ps: [
    ps.pg_repack
    ps.postgis
  ]);
}

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

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

JIT-support in the PostgreSQL package is disabled by default because of the ~300MiB closure-size increase from the LLVM dependency. It can be optionally enabled in PostgreSQL with the following config option:

{
  services.postgresql.enableJIT = true;
}

This makes sure that the jit-setting is set to on and a PostgreSQL package with JIT enabled is used. Further tweaking of the JIT compiler, e.g. setting a different query cost threshold via jit_above_cost can be done manually via services.postgresql.settings.

The attribute-names of JIT-enabled PostgreSQL packages are suffixed with _jit, i.e. for each pkgs.postgresql (and pkgs.postgresql_<major>) in nixpkgs there’s also a pkgs.postgresql_jit (and pkgs.postgresql_<major>_jit). Alternatively, a JIT-enabled variant can be derived from a given postgresql package via postgresql.withJIT. This is also useful if it’s not clear which attribute from nixpkgs was originally used (e.g. when working with config.services.postgresql.package or if the package was modified via an overlay) since all modifications are propagated to withJIT. I.e.

with import <nixpkgs> {
  overlays = [
    (self: super: {
      postgresql = super.postgresql.overrideAttrs (_: { pname = "foobar"; });
    })
  ];
};
postgresql.withJIT.pname

evaluates to "foobar".

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

services.foundationdb.enable = true;
services.foundationdb.package = pkgs.foundationdb71; # FoundationDB 7.1.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.foundationdb71

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/.

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

A very basic configuration for backing up to a locally accessible directory is:

{
    opt.services.borgbackup.jobs = {
      { rootBackup = {
          paths = "/";
          exclude = [ "/nix" "/path/to/local/repo" ];
          repo = "/path/to/local/repo";
          doInit = true;
          encryption = {
            mode = "repokey";
            passphrase = "secret";
          };
          compression = "auto,lzma";
          startAt = "weekly";
        };
      }
    };
}

You should use a different SSH key for each repository you write to, because the specified keys are restricted to running borg serve and can only access this single repository. You need the output of the generate pub file.

# sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo
# cat /run/keys/id_ed25519_my_borg_repo
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos

Add the following snippet to your NixOS configuration:

{
  services.borgbackup.repos = {
    my_borg_repo = {
      authorizedKeys = [
        "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos"
      ] ;
      path = "/var/lib/my_borg_repo" ;
    };
  };
}

The following NixOS snippet creates an hourly backup to the service (on the host nixos) as created in the section above. We assume that you have stored a secret passphrasse in the file /run/keys/borgbackup_passphrase, which should be only accessible by root

{
  services.borgbackup.jobs = {
    backupToLocalServer = {
      paths = [ "/etc/nixos" ];
      doInit = true;
      repo =  "borg@nixos:." ;
      encryption = {
        mode = "repokey-blake2";
        passCommand = "cat /run/keys/borgbackup_passphrase";
      };
      environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_my_borg_repo"; };
      compression = "auto,lzma";
      startAt = "hourly";
    };
  };
};

The following few commands (run as root) let you test your backup.

> nixos-rebuild switch
...restarting the following units: polkit.service
> systemctl restart borgbackup-job-backupToLocalServer
> sleep 10
> systemctl restart borgbackup-job-backupToLocalServer
> export BORG_PASSPHRASE=topSecrect
> borg list --rsh='ssh -i /run/keys/id_ed25519_my_borg_repo' borg@nixos:.
nixos-backupToLocalServer-2020-03-30T21:46:17 Mon, 2020-03-30 21:46:19 [84feb97710954931ca384182f5f3cb90665f35cef214760abd7350fb064786ac]
nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e77321694ecd160ca2228611747c6ad1be177d6e0d894538898de7a2621b6e68]

Several companies offer (paid) hosting services for Borg repositories.

To backup your home directory to borgbase you have to:

Vorta is a backup client for macOS and Linux desktops. It integrates the mighty BorgBackup with your desktop environment to protect your data from disk failure, ransomware and theft.

It can be installed in NixOS e.g. by adding pkgs.vorta to environment.systemPackages.

Details about using Vorta can be found under https://vorta.borgbase.com .

Use the following configuration to start a public instance of Castopod on castopod.example.com domain:

networking.firewall.allowedTCPPorts = [ 80 443 ];
services.castopod = {
  enable = true;
  database.createLocally = true;
  nginx.virtualHost = {
    serverName = "castopod.example.com";
    enableACME = true;
    forceSSL = true;
  };
};

Go to https://castopod.example.com/cp-install to create superadmin account after applying the above configuration.

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.defaults.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.defaults.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 this:

security.acme.acceptTerms = true;
security.acme.defaults.email = "admin+acme@example.com";
services.nginx = {
  enable = true;
  virtualHosts = {
    "foo.example.com" = {
      forceSSL = true;
      enableACME = true;
      # All serverAliases will be added as extra domain names 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 extraDomainNames manually beforehand:
    # security.acme.certs."foo.example.com".extraDomainNames = [ "baz.example.com" ];
    "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.defaults.email = "admin+acme@example.com";

# /var/lib/acme/.challenges must be writable by the ACME user
# and readable by the Nginx user. The easiest way to achieve
# this is to add the Nginx user to the ACME group.
users.users.nginx.extraGroups = [ "acme" ];

services.nginx = {
  enable = true;
  virtualHosts = {
    "acmechallenge.example.com" = {
      # Catchall vhost, will redirect users to HTTPS for all vhosts
      serverAliases = [ "*.example.com" ];
      locations."/.well-known/acme-challenge" = {
        root = "/var/lib/acme/.challenges";
      };
      locations."/" = {
        return = "301 https://$host$request_uri";
      };
    };
  };
};
# Alternative config for Apache
users.users.wwwrun.extraGroups = [ "acme" ];
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";
  # Ensure that the web server you use can read the generated certs
  # Take a look at the group option for the web server you choose.
  group = "nginx";
  # Since we have a wildcard vhost to handle port 80,
  # we can generate certs for anything!
  # Just make sure your DNS resolves them.
  extraDomainNames = [ "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 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 are 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.defaults.email = "admin+acme@example.com";
security.acme.certs."example.com" = {
  domain = "*.example.com";
  dnsProvider = "rfc2136";
  environmentFile = "/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 a systemd service:

systemd.services.dns-rfc2136-conf = {
  requiredBy = ["acme-example.com.service" "bind.service"];
  before = ["acme-example.com.service" "bind.service"];
  unitConfig = {
    ConditionPathExists = "!/var/lib/secrets/dnskeys.conf";
  };
  serviceConfig = {
    Type = "oneshot";
    UMask = 0077;
  };
  path = [ pkgs.bind ];
  script = ''
    mkdir -p /var/lib/secrets
    chmod 755 /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

    # extract secret value from the dnskeys.conf
    while read x y; do if [ "$x" = "secret" ]; then secret="''${y:1:''${#y}-3}"; fi; done < /var/lib/secrets/dnskeys.conf

    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='$secret'
    EOF
    chmod 400 /var/lib/secrets/certs.secret
  '';
};

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

It is possible to use DNS-01 validation with all certificates, including those automatically configured via the Nginx/Apache enableACME option. This configuration pattern is fully supported and part of the module’s test suite for Nginx + Apache.

You must follow the guide above on configuring DNS-01 validation first, however instead of setting the options for one certificate (e.g. security.acme.certs.<name>.dnsProvider) you will set them as defaults (e.g. security.acme.defaults.dnsProvider).

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

# For each virtual host you would like to use DNS-01 validation with,
# set acmeRoot = null
services.nginx = {
  enable = true;
  virtualHosts = {
    "foo.example.com" = {
      enableACME = true;
      acmeRoot = null;
    };
  };
};

And that’s it! Next time your configuration is rebuilt, or when you add a new virtualHost, it will be DNS-01 validated.

Some services refuse to start if the configured certificate files are not owned by root. PostgreSQL and OpenSMTPD are examples of these. There is no way to change the user the ACME module uses (it will always be acme), however you can use systemd’s LoadCredential feature to resolve this elegantly. Below is an example configuration for OpenSMTPD, but this pattern can be applied to any service.

# Configure ACME however you like (DNS or HTTP validation), adding
# the following configuration for the relevant certificate.
# Note: You cannot use `systemctl reload` here as that would mean
# the LoadCredential configuration below would be skipped and
# the service would continue to use old certificates.
security.acme.certs."mail.example.com".postRun = ''
  systemctl restart opensmtpd
'';

# Now you must augment OpenSMTPD's systemd service to load
# the certificate files.
systemd.services.opensmtpd.requires = ["acme-finished-mail.example.com.target"];
systemd.services.opensmtpd.serviceConfig.LoadCredential = let
  certDir = config.security.acme.certs."mail.example.com".directory;
in [
  "cert.pem:${certDir}/cert.pem"
  "key.pem:${certDir}/key.pem"
];

# Finally, configure OpenSMTPD to use these certs.
services.opensmtpd = let
  credsDir = "/run/credentials/opensmtpd.service";
in {
  enable = true;
  setSendmail = false;
  serverConfiguration = ''
    pki mail.example.com cert "${credsDir}/cert.pem"
    pki mail.example.com key "${credsDir}/key.pem"
    listen on localhost tls pki mail.example.com
    action act1 relay host smtp://127.0.0.1:10027
    match for local action act1
  '';
};

Should you need to regenerate a particular certificate in a hurry, such as when a vulnerability is found in Let’s Encrypt, there is now a convenient mechanism for doing so. Running systemctl clean --what=state acme-example.com.service will remove all certificate files and the account data for the given domain, allowing you to then systemctl start acme-example.com.service to generate fresh ones.

It is possible that your account credentials file may become corrupt and need to be regenerated. In this scenario lego will produce the error JWS verification error. The solution is to simply delete the associated accounts file and re-run the affected service(s).

# Find the accounts folder for the certificate
systemctl cat acme-example.com.service | grep -Po 'accounts/[^:]*'
export accountdir="$(!!)"
# Move this folder to some place else
mv /var/lib/acme/.lego/$accountdir{,.bak}
# Recreate the folder using systemd-tmpfiles
systemd-tmpfiles --create
# Get a new account and reissue certificates
# Note: Do this for all certs that share the same account email address
systemctl start acme-example.com.service

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 = [
    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
  '';
}