NixOS Manual

Version 25.05

Table of Contents

Obtaining NixOS

Installing NixOS

Changing the Configuration

Upgrading NixOS

Building a NixOS (Live) ISO

Building Images withnixos-rebuild build-image

Building Images viasystemd-repart

• Using virtual appliances in Open Virtualization Format (OVF) thatcan be imported into VirtualBox. These are available from theNixOSdownload page.

• Using AMIs for Amazon’s EC2. To find one for your region, please referto thedownload page.

• Using NixOps, the NixOS-based cloud deployment tool, which allowsyou to provision VirtualBox and EC2 NixOS instances from declarativespecifications. Check out theNixOpshomepage for details.

Table of Contents

Booting from the install medium

Graphical Installation

Manual Installation

Additional installation notes

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 youthrough the installation.

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

The NixOS manual is available by runningnixos-help in the command lineor from the application menu in the desktop environment.

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

You are logged-in automatically asnixos. Thenixos user account hasan empty password so you can usesudo without a password:

$ sudo -i

You can useloadkeys to switch to your preferred keyboard layout.(We even provide neo2 vialoadkeys de neo!)

If the text is too small to be legible, trysetfont ter-v32n toincrease the font size.

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

> add_network0> set_network 0 ssid "myhomenetwork"OK> set_network 0 psk "mypassword"OK> enable_network 0OK

> add_network0> set_network 0 ssid "eduroam"OK> set_network 0 identity "myname@example.com"OK> set_network 0 password "mypassword"OK> enable_network 0OK

<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 -o umask=077 /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;}

Warning

This command doesn’t start/stopuser servicesautomatically.nixos-rebuild only runs adaemon-reload for each user with runninguser services.

Warning

These commands must be executed as root, so you should either run themfrom a root shell or by prefixing them withsudo -i.

Table of Contents

Automatic Upgrades

• Stable channels, such asnixos-25.05.These only get conservative bug fixes and package upgrades. Forinstance, a channel update may cause the Linux kernel on your systemto be upgraded from 4.19.34 to 4.19.38 (a minor bug fix), but notfrom 4.19.x to 4.20.x (a major change that has the potential to break things).Stable channels are generally maintained until the next stablebranch is created.

• Theunstable channel,nixos-unstable.This corresponds to NixOS’s main development branch, and may thus seeradical changes between channel updates. It’s not recommended forproduction systems.

• Small channels, such asnixos-25.05-smallornixos-unstable-small.These are identical to the stable and unstable channels described above,except that they contain fewer binary packages. This means they get updatedfaster than the regular channels (for instance, when a critical security patchis committed to NixOS’s source tree), but may require more packages to bebuilt from source than usual. They’re mostly intended for server environmentsand as such contain few GUI applications.

Note

Channels are set per user. This means that runningnix-channel --addas a non root user (or without sudo) will not affectconfiguration in/etc/nixos/configuration.nix

Warning

It is generally safe to switch back and forth between channels. The onlyexception is that a newer NixOS may also have a newer Nix version, whichmay involve an upgrade of Nix’s database schema. This cannot be undoneeasily, so in that case you will not be able to go back to your originalchannel.

You can keep a NixOS system up-to-date automatically by adding thefollowing toconfiguration.nix:

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

This enables a periodically executed systemd service namednixos-upgrade.service. If theallowReboot option isfalse, it runsnixos-rebuild switch --upgrade to upgrade NixOS to the latest versionin the current channel. (To see when the service runs, seesystemctl list-timers.)IfallowReboot istrue, then the system will automatically reboot ifthe new generation contains a different kernel, initrd or kernelmodules. You can also specify a channel explicitly, e.g.

{ system.autoUpgrade.channel = "https://channels.nixos.org/nixos-25.05"; }

Table of Contents

Practical Instructions

Additional drivers or firmware

Technical Notes

• Use any of those default configurations as is

• Combine them with (any of) your host config(s)

To build an ISO image for the channelnixos-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/nixos-image-25.05pre-git-x86_64-linux.iso /mnt/iso

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

For example, to build the GNOME graphical installer ISO, but with support forcertain WiFi adapters present in some MacBooks, you can create the followingfile atmodules/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 viamkImageMediaOverride = mkOverride 60;and therefore primes over simple value assignments, but also yields tomkForce.

This property allows image designers to implement in semantically correct ways thoseconfiguration 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 minimumfor correct functioning, while the installer base image overrides the entire file systemlayout because there can’t be any other guarantees on a live medium than those givenby the live medium itself. The latter is especially true before formatting the targetblock device(s). On the other hand, the netboot iso only overrides its minimum dependenciessince netboot images are always made-to-target.

Table of Contents

Nix Store Partition

Appliance Image

You can define a partition that only contains the Nix store and then mount itunder/nix/store. Because the/nix/store part of the paths is alreadydetermined by the mount point, you have to setstripNixStorePrefix = true; sothat 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";        # ...      };    };  };}

Theimage/repart.nix module can also be used to build self-containedsoftwareappliances.

The generation based update mechanism of NixOS is not suited for appliances.Updates of appliances are usually either performed by replacing the entireimage with a new one or by updating partitions via an A/B scheme. See theChrome OS update process for an example of how to achievethis. The appliance image built in the following example does not contain aconfiguration.nix and thus you will not be able to callnixos-rebuild fromthis system. Furthermore, it uses aUnified 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

Table of Contents

Configuration Syntax

Package Management

User Management

File Systems

X Window System

Wayland

GPU acceleration

Xfce Desktop Environment

Networking

Linux Kernel

Subversion

Pantheon Desktop

GNOME Desktop

External Bootloader Backends

Clevis

Garage

YouTrack

Suwayomi-Server

strfry

Plausible

Pingvin Share

Pict-rs

Nextcloud

Matomo

Lemmy

Keycloak

Jitsi Meet

Immich

Honk

Hatsu

Grocy

GoToSocial

Glance

FileSender

Discourse

Davis

Castopod

c2FmZQ

Akkoma

systemd-lock-handler

kerberos_server

Meilisearch

Yggdrasil

uMurmur

Prosody

Pleroma

Netbird server

Netbird

Mosquitto

Jottacloud Command-line Tool

GNS3 Server

Firefox Sync server

DNS-over-HTTPS Server

Dnsmasq

🦀 crab-hole

Anubis

Samba

Litestream

Prometheus exporters

parsedmarc

OCS Inventory Agent

Goss

Cert Spotter

WeeChat

Taskserver

Sourcehut

GitLab

Forgejo

Dump1090-fa

Apache Kafka

Anki Sync Server

Matrix

Mjolnir (Matrix Moderation Tool)

Mautrix-Whatsapp

Mautrix-Signal

Maubot

Draupnir (Matrix Moderation Bot)

Mailman

Trezor

Customizing display configuration

Emacs

Livebook

Blackfire profiler

Athens

Flatpak

TigerBeetle

PostgreSQL

FoundationDB

BorgBackup

SSL/TLS Certificates with ACME

Oh my ZSH

Plotinus

Digital Bitbox

Input Methods

Profiles

Mattermost

Kubernetes

Table of Contents

NixOS Configuration File

Abstractions

Modularity

The NixOS configuration file generally looks like this:

{ config, pkgs, ... }:{  # option definitions}

The first line ({ config, pkgs, ... }:) denotes that this is actuallya function that takes at least the two argumentsconfig andpkgs.(These are explained later, in chapterWriting NixOS Modules) Thefunction returns aset of option definitions ({ ... }).These definitions have the formname = value, wherename is thename of an option andvalue 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 togetherenable the Apache HTTP Server with/webroot as the document root.

Sets can be nested, and in fact dots in option names are shorthand fordefining a set containing another set. For instance,services.httpd.enable defines a set namedservices that contains a set namedhttpd, which in turn contains anoption definition namedenable with valuetrue. This means that theexample 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 thatshare the same prefix (such asservices.httpd).

NixOS checks your option definitions for correctness. For instance, ifyou try to define an option that doesn’t exist (that is, doesn’t have acorrespondingoption declaration),nixos-rebuild will give an errorlike:

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

Likewise, values in option definitions must have a correct type. Forinstance,services.httpd.enable must be a Boolean (true orfalse).Trying to give it a value of another type, such as a string, will causean 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;    };    "wiki.example.org" = {      documentRoot = "/webroot/wiki.example.org";      adminAddr = "alice@example.org";      forceSSL = true;      enableACME = 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 alet:

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

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

You can write alet 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 argumentwebroot 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 yourconfiguration.nix becomes too big, you can split it into multiplefiles. Likewise, if you have multiple NixOS configurations (e.g. fordifferent computers) with some commonality, you can move the commonconfiguration into a shared file.

Modules have exactly the same syntax asconfiguration.nix. In fact,configuration.nix is itself a module. You can use other modules byincluding them fromconfiguration.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 andkde.nix. The latter might look like this:

{ config, pkgs, ... }:{  services.xserver.enable = true;  services.displayManager.sddm.enable = true;  services.xserver.desktopManager.plasma5.enable = true;  environment.systemPackages = [ pkgs.vim ];}

Note that bothconfiguration.nix andkde.nix define the optionenvironment.systemPackages. When multiple modules define anoption, NixOS will try tomerge the definitions. In the case ofenvironment.systemPackages the lists of packages will beconcatenated. The value inconfiguration.nix ismerged last, so for list-type options, it will appear at the end of themerged list. If you want it to appear first, you can usemkBefore:

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

This causes thekvm-intel kernel module to be loaded before any otherkernel modules.

For other types of options, a merge may not be possible. For instance,if two modules defineservices.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 precedenceover the others:

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

When using multiple modules, you may need to access configuration valuesdefined in other modules. This is what theconfig function argument isfor: it contains the complete, merged system configuration. That is,config is the result of combining the configurations returned by everymodule. (If you’re wondering how it’s possible that the (indirect)resultof a function is passed as aninput to that same function: that’sbecause Nix is a “lazy” language — it only computes values whenthey are needed. This works as long as no individual configurationvalue depends on itself.)

For example, here is a module that adds some packages toenvironment.systemPackages only ifservices.xserver.enable is set totrue 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 aconfiguration option is. The commandnixos-option allows you to findout:

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

Interactive exploration of the configuration is possible usingnix 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 generatemodules using code, instead of writing files. The example below wouldhave 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") ];}

Table of Contents

Declarative Package Management

Ad-Hoc Package Management

• Declarative, where you declare what packages you want in yourconfiguration.nix. Every time you runnixos-rebuild, NixOS willensure that you get a consistent set of binaries corresponding toyour specification.

• Ad hoc, where you install, upgrade and uninstall packages via thenix-env command. This style allows mixing packages from differentNixpkgs versions. It’s the only choice for non-root users.

With declarative package management, you specify which packages you wanton your system by setting the optionenvironment.systemPackages. For instance, adding thefollowing line toconfiguration.nix enables the Mozilla Thunderbirdemail application:

{ environment.systemPackages = [ pkgs.thunderbird ]; }

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

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

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

The first column in the output is theattribute name, such asnixos.thunderbird.

Note: thenixos prefix tells us that we want to get the package fromthenixos channel and works only in CLI tools. In declarativeconfiguration usepkgs prefix (variable).

To “uninstall” a package, remove it fromenvironment.systemPackages and runnixos-rebuild switch.

{  nixpkgs.config = {    allowUnfree = true;  };}

{  environment.systemPackages = with pkgs; [    sl    (pass.withExtensions (      subpkgs: with subpkgs; [        pass-audit        pass-otp        pass-genphrase      ]    ))    (python3.withPackages (subpkgs: with subpkgs; [ requests ]))    cowsay  ];}

{ 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 scopestdenv.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/helloHello, world!

{  programs.appimage.enable = true;  programs.appimage.binfmt = true;}

{  programs.appimage.package = pkgs.appimage-run.override {    extraPkgs = pkgs: [      # missing libraries here, e.g.: `pkgs.libepoxy`    ];  };}

With the commandnix-env, you can install and uninstall packages fromthe 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 toother users. The-A flag specifies the package by its attribute name;without it, the package is installed by matching against its packagename (e.g.thunderbird). The latter is slower because it requiresmatching against all available Nix packages, and is ambiguous if thereare multiple matching packages.

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

$ nix-channel --update nixos

and then runningnix-env -i again. Other packages in the profile arenot affected; this is the crucial difference with the declarativestyle of package management, where runningnixos-rebuild switch causesall packages to be updated to their current versions in the NixOSchannel. You can however upgrade all packages for which there is a newerversion by doing:

$ nix-env -u '*'

A package can be uninstalled using the-e flag:

$ nix-env -e thunderbird

Finally, you can roll back an undesirablenix-env action:

$ nix-env --rollback

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

Table of Contents

Create users and groups withsystemd-sysusers

Manage users and groups withuserborn

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

{ systemd.sysusers.enable = true; }

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

Like systemd-sysusers, Userborn doesn’t depend on Perl but offers some moreadvantages over systemd-sysusers:

Userborn is the recommended way to manage users if you don’t want to rely onthe Perl script. It aims to eventually replace the Perl script by default.

You can enable Userborn via:

{ services.userborn.enable = true; }

You can configure Userborn to store the password files(/etc/{group,passwd,shadow}) outside of/etc and symlink them from thislocation to/etc:

{ services.userborn.passwordFilesLocation = "/persistent/etc"; }

This is useful when you store/etc on atmpfs or if/etc is immutable(e.g. when usingsystem.etc.overlay.mutable = false;). In the latter case theoriginal files are by default stored in/var/lib/nixos.

Userborn implements immutable users by re-mounting the password filesread-only. This means that unlike when using the Perl script, trying to add anew user (e.g. viauseradd) will fail right away.

Table of Contents

LUKS-Encrypted File Systems

SSHFS File Systems

Overlayfs

Note

System startup will fail if any of the filesystems fails to mount,dropping you to the emergency shell. You can make a mount asynchronousand non-critical by addingoptions = [ "nofail" ];.

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

# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5dWARNING!========This will overwrite data on /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d irrevocably.Are you sure? (Type uppercase yes): YESEnter LUKS passphrase: ***Verify passphrase: ***# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d cryptedEnter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***# mkfs.ext4 /dev/mapper/crypted

The LUKS volume should be automatically picked up bynixos-generate-config, but you might want to verify that yourhardware-configuration.nix looks correct. To manually ensure that thesystem is automatically mounted at boot time as/, add the followingtoconfiguration.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 anencrypted 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 f1d00200108b9d6e849a8b388da457688e3dd653b4e53770012d8f28e5d3b269865038c346802f36f3da7278b13ad6a3bb6a1452e24ebeeaa24ba40eef559b1b287d2a2f80b7Password: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 aFUSE 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-keyGenerating public/private ed25519 key pair.Your identification has been saved in example-keyYour public key has been saved in example-key.pubThe 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/).mountJun 22 11:41:18 workstation mount[87790]: SSHFS version 3.7.1Jun 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 peerJun 22 11:41:19 workstation systemd[1]: mnt-my\x2ddir.mount: Mount process exited, code=exited, status=1/FAILUREJun 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 writableoverlays.

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

Ifupperdir andworkdir are not null, they will be created before theoverlay is mounted.

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

Table of Contents

Auto-login

Running X without a display manager

Intel Graphics drivers

Proprietary NVIDIA drivers

Touchpads

GTK/Qt themes

Custom XKB layouts

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

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

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

{ services.displayManager.defaultSession = "none+i3"; }

Every display manager in NixOS supports auto-login, here is an exampleusing lightdm for a useralice:

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

It is possible to avoid a display manager entirely and starting the X servermanually from a virtual terminal. Add to your configuration:

{  services.xserver.displayManager.startx = {    enable = true;    generateScript = true;  };}

then you can start the X server with thestartx command.

The second option will generate a basexinitrc script that will run yourwindow manager and set up the systemd user session.You can extend the script using theextraCommandsoption, for example:

{  services.xserver.displayManager.startx = {    generateScript = true;    extraCommands = ''      xrdb -load .Xresources      xsetroot -solid '#666661'      xsetroot -cursor_name left_ptr    '';  };}

or, alternatively, you can write your own from scratch in~/.xinitrc.

In this case, remember you’re responsible for starting the window manager, forexample:

sxhkd &bspwm &

and if you have enabled some systemd user service, you will probably want toalso add these lines too:

# import required env variables from the current shellsystemctl --user import-environment DISPLAY XDG_SESSION_ID# start all graphical user servicessystemctl --user start nixos-fake-graphical-session.target# start the user dbus daemondbus-daemon --session --address="unix:path=/run/user/$(id -u)/bus" &

The default and recommended driver for Intel Graphics in X.org ismodesetting(included in the xorg-server package itself).This is a generic driver which uses the kernelmodesetting (KMS) mechanism, itsupports Glamor (2D graphics acceleration via OpenGL) and is activelymaintained, it may perform worse in some cases (like in old chipsets).

There is a second driver,intel (provided by the xf86-video-intel package),specific to older Intel iGPUs from generation 2 to 9. It is not recommended bymost distributions: it lacks several modern features (for example, it doesn’tsupport Glamor) and the package hasn’t been officially updated since 2015.

Third generation and older iGPUs (15-20+ years old) are not supported by themodesetting driver (X will crash upon startup). Thus, theintel driver isrequired for these chipsets.Otherwise, the results vary depending on the hardware, so you may have to tryboth drivers. Use the optionservices.xserver.videoDriversto set one. The recommended configuration for modern systems is:

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

If you experience screen tearing no matter what, this configuration wasreported 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 tomodesetting orintel with DRI 3 (default).

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

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

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

{  hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_470;  hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_390;  hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.legacy_340;}

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

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

{ services.libinput.enable = true; }

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

{ services.libinput.touchpad.tapping = false; }

Note: the use ofservices.xserver.synaptics is deprecated since NixOS17.09.

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

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

It is possible to install custom XKB keyboard layoutsusing the optionservices.xserver.xkb.extraLayouts.

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

Create a file calledus-greek with the following content (under adirectory calledsymbols; it’s an XKB peculiarity that will help withtesting):

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 abroken XKB file can lead to the X session crashing at login. Therefore,you’re strongly advised totest 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, thelayout should be ready to use. You can try it by e.g. runningsetxkbmap us-greek and then type<alt>+a (it may not get applied inyour terminal straight away). To change the default, the usualservices.xserver.xkb.layout option can still be used.

A layout can have several other components besidesxkb_symbols, forexample we will define new keycodes for some multimedia key and bindthese to some symbol.

Use thexev utility frompkgs.xorg.xev to find the codes of the keysof interest, then create amedia-key file to hold the keycodesdefinitions

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

Now use the newly define keycodes inmedia-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 akeymap directly but relies instead on XKB rules to select the matchingcomponents (keycodes, types, …) of a layout. This means thatcomponents other than symbols won’t be loaded by default. As aworkaround, you can set the keymap usingsetxkbmap at the start of thesession 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. Forexample withxinit run

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

To learn how to write layouts take a look at the XKBdocumentation.More example layouts can also be foundhere.

Table of Contents

OpenCL

Vulkan

VA-API

Common issues

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

OpenCL applications load drivers through theInstallable Client Driver(ICD) mechanism. In this mechanism, an ICD file specifies the path tothe OpenCL driver for a particular GPU family. In NixOS, there are twoways to make ICD files visible to the ICD loader. The first is throughtheOCL_ICD_VENDORS environment variable. This variable can contain adirectory 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 tohardware.graphics.extraPackages.This links the ICD file under/run/opengl-driver, where it will be visibleto the ICD loader.

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

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

{ hardware.graphics.extraPackages = [ rocmPackages.clr.icd ]; }

{ hardware.graphics.extraPackages = [ intel-compute-runtime ]; }

Vulkan is a graphics andcompute API for GPUs. It is used directly by games or indirectly thoughcompatibility layers likeDXVK.

By default, ifhardware.graphics.enableis enabled, Mesa is installed and provides Vulkan for supported hardware.

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

The first option is through theVK_ICD_FILENAMES environment variable.This variable can contain multiple JSON files, separated by:. Forexample:

$ 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 tohardware.graphics.extraPackages.This links the ICD file under/run/opengl-driver, where it will bevisible to the ICD loader.

The proper installation of Vulkan drivers can be verified through thevulkaninfo command of the vulkan-tools package. This command willreport the hardware devices and drivers found, in this example outputamdvlk 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 GPUGPU1:        deviceType     = PHYSICAL_DEVICE_TYPE_DISCRETE_GPU

A simple graphical application that uses Vulkan isvkcube from thevulkan-tools package.

{  hardware.graphics.extraPackages = [ pkgs.amdvlk ];  # To enable Vulkan support for 32-bit applications, also add:  hardware.graphics.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 tographics hardware acceleration capabilities for video processing.

VA-API drivers are loaded bylibva. The version in nixpkgs is built to searchthe opengl driver path, so drivers can be installed inhardware.graphics.extraPackages.

VA-API can be tested using:

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

{ hardware.graphics.extraPackages = [ intel-media-driver ]; }

{ hardware.graphics.extraPackages = [ intel-vaapi-driver ]; }

Table of Contents

Thunar

Troubleshooting

Thunar (the Xfce file manager) is automatically enabled when Xfce isenabled. To enable Thunar without enabling Xfce, use the configurationoptionprograms.thunar.enable instead of addingpkgs.xfce.thunar toenvironment.systemPackages.

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

Even after enabling udisks2, volume management might not work. Thunarand/or the desktop takes time to show up. Thunar will spit out this kindof message on start (look atjournalctl --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 allfixed by enabling “Launch GNOME services on startup” in the Advancedtab of the Session and Startup settings panel. Alternatively, you canrun 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.

Table of Contents

NetworkManager

Secure Shell Access

IPv4 Configuration

IPv6 Configuration

Firewall

Wireless Networks

Ad-Hoc Configuration

Renaming network interfaces

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

{ networking.networkmanager.enable = true; }

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

All users that should have permission to change network settings mustbelong to thenetworkmanager group:

{ users.users.alice.extraGroups = [ "networkmanager" ]; }

NetworkManager is controlled using eithernmcli ornmtui(curses-based terminal user interface). See their manual pages fordetails on their usage. Some desktop environments (GNOME, KDE) havetheir own configuration tools for NetworkManager. On XFCE, there is noconfiguration tool for NetworkManager by default: by enablingprograms.nm-applet.enable, the graphical applet will beinstalled and will launch automatically when the graphical session isstarted.

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

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

{ services.openssh.enable = true; }

By default, root logins using a password are disallowed. They can bedisabled entirely by settingservices.openssh.settings.PermitRootLogin to"no".

You can declaratively specify authorised public keys for a useras follows:

{  users.users.alice.openssh.authorizedKeys.keys = [ "ssh-ed25519 AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];}

By default, NixOS uses DHCP (specifically,dhcpcd) to automaticallyconfigure network interfaces. However, you can configure an interfacemanually 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 nameservers:

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

The host name is set usingnetworking.hostName:

{ networking.hostName = "cartman"; }

The default host name isnixos. Set it to the empty string ("") toallow the DHCP server to provide the host name.

IPv6 is enabled by default. Stateless address autoconfiguration is usedto automatically assign IPv6 addresses to all interfaces, and PrivacyExtensions (RFC 4946) are enabled by default. You can adjust the defaultfor this by settingnetworking.tempAddresses. This optionmay be overridden on a per-interface basis bynetworking.interfaces.<name>.tempAddress. You can disableIPv6 support globally by setting:

{ networking.enableIPv6 = false; }

You can disable IPv6 on a single interface using a normal sysctl (inthis example, we use interfaceeth0):

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

As with IPv4 networking interfaces are automatically configured viaDHCPv6. 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 specifiedinterface:

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

Seethe section called “IPv4 Configuration” for similar examples and additional information.

NixOS has a simple stateful firewall that blocks incoming connectionsand other unexpected packets. The firewall applies to both IPv4 and IPv6traffic. 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 theoutside world:

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

Note that TCP port 22 (ssh) is opened automatically if the SSH daemon isenabled (services.openssh.enable = true). UDP ports can be opened throughnetworking.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 throughnetworking.firewall.allowedUDPPortRanges.

For a desktop installation using NetworkManager (e.g., GNOME), you justhave to make sure the user is in thenetworkmanager group and you canskip 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 = {    # SSID with no spaces or special characters    echelon = {      psk = "abcdefgh";    };    # SSID with spaces and/or special characters    "echelon's AP" = {      psk = "ijklmnop";    };    # Hidden SSID    echelon = {      hidden = true;      psk = "qrstuvwx";    };    free.wifi = { }; # Public wireless network  };}

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

If you are using WPA2 you can generate pskRaw key usingwpa_passphrase:

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

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

or you can use it to directly generate thewpa_supplicant.conf:

# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf

After you have edited thewpa_supplicant.conf, you need to restart thewpa_supplicant service.

# systemctl restart wpa_supplicant.service

You can usenetworking.localCommands tospecify shell commands to be run at the end ofnetwork-setup.service. Thisis useful for doing network configuration not covered by the existing NixOSmodules. 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 udevpredictable namingscheme to assign namesto network interfaces. This means that by default cards are not giventhe traditional names likeeth0 oreth1, whose order can changeunpredictably across reboots. Instead, relying on physical locations andfirmware information, the scheme produces names likeens1,enp2s0,etc.

These names are predictable but less memorable and not necessarilystable: for example installing new hardware or changing firmwaresettings can result in anamechange.If this is undesirable, for example if you have a single ethernet card,you can revert to the traditional scheme by settingnetworking.usePredictableInterfaceNamestofalse.

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

Table of Contents

Building a custom kernel

Rust

Developing kernel modules

ZFS

Please refer to the Nixpkgs manual for the various ways ofbuilding 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 bydefault. For kernel versions 6.7 or newer, experimental Rust supportcan be enabled. In a NixOS configuration, set:

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

This section was moved to theNixpkgs manual.

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

Table of Contents

Subversion inside Apache HTTP

This section focuses on configuring a web-based server on top of theApache HTTP server, which usesWebDAV/DeltaVfor communication.

For more information on the general setup, please refer to thetheappropriate section of the Subversionbook.

To configure, include in/etc/nixos/configuration.nix code to activateApache HTTP, settingservices.httpd.adminAddrappropriately:

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

For a simple Subversion server with basic authentication, configure theSubversion module for Apache as follows, settinghostName anddocumentRoot appropriately, andSVNParentPath to the parentdirectory of the repositories,AuthzSVNAccessFile to the location ofthe.authz file describing access permission, andAuthUserFile tothe 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" inlocations."/svn".extraConfig is the path underneathwhich the repositories will be served.

This page explainshow to set up the Subversion configuration itself. This boils down tothe following:

UnderneathREPO_PARENT repositories can be set up as follows:

$ svn create REPO_NAME

Repository files need to be accessible bywwwrun:

$ chown -R wwwrun:wwwrun REPO_PARENT

The password filePASSWORD_FILE can be created as follows:

$ htpasswd -cs PASSWORD_FILE USER_NAME

Additional users can be set up similarly, omitting thec flag:

$ htpasswd -s PASSWORD_FILE USER_NAME

The file describing access permissionsACCESS_FILE will look somethinglike the following:

[/]* = r[REPO_NAME:/]USER_NAME = rw

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

Table of Contents

Enabling Pantheon

Wingpanel and Switchboard plugins

FAQ

All of Pantheon is working in NixOS and the applications should be available, aside from a fewexceptions. 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 useenvironment.pantheon.excludePackages to remove any other app (likeelementary-mail).

Wingpanel and Switchboard work differently than they do in other distributions, as far as using plugins. You cannot install a plugin globally (like withenvironment.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.

Table of Contents

Enabling GNOME

Enabling GNOME Flashback

Icons and GTK Themes

Shell Extensions

GSettings Overrides

Frequently Asked Questions

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 ingnome-build-meta.

{ services.gnome.core-apps.enable = false; }

{  services.gnome.localsearch.enable = false;  services.gnome.tinysparql.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 usingservices.xserver.desktopManager.gnome.flashback.customSessions.

The following example usesxmonad 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 toenvironment.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

indconf-editor

Most Shell extensions are packaged under thegnomeExtensions attribute.Some packages that include Shell extensions, likegpaste, 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 aGSettings override for this onorg.gnome.shell.enabled-extensions, but that will only influence the default value.

Majority of software building on the GNOME platform use GLib’sGSettings 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 theservices.xserver.desktopManager.gnome.extraGSettingsOverrides option.

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

You can usedconf-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-shell # for org.gnome.shell    ];  };}

Table of Contents

Developing Custom Bootloader Backends

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

Table of Contents

Create a JWE file containing your secret

Activate unattended decryption of a resource at boot

The first step is to embed your secret in aJWE 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 theclevis documentation.

In order to activate unattended decryption of a resource at boot, enable theclevis 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; }

Onlybcachefs,zfs andluks encrypted devices are supported at this time.

Table of Contents

General considerations on upgrades

Advanced upgrades (minor/major version upgrades)

Maintainer information

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 Garagesince it cannot move more than one major version forward on a single upgrade. This chapteradds 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 thepackage-expression (and should be backported to supported stable branches after that),major-releases should be added in a new attribute (e.g. Garagev0.8.0should be available innixpkgs aspkgs.garage_0_8_0).To provide simple upgrade paths it’s generally useful to backport those as well to stablebranches. As long as the package-default isn’t altered, this won’t break existing setups.After that, the versioning-warning in thegarage-module should beupdated to make sure that thepackage-option selects the latest versionon fresh setups.

If major-releases will be abandoned by upstream, we should check first if those are neededin NixOS for a safe upgrade-path before removing those. In that case we should keep thosepackages, 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 aGarage on e.g. 22.11 to a Garage on 23.11.

Table of Contents

Installation

Upgrade from 2022.3 to 2023.x

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 theyoutrack 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 inservices.youtrack.generalParameters for the first startup of YouTrack 2023.x.

Table of Contents

Basic usage

Basic authentication

Extra configuration

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

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

It runs in the systemd service namedsuwayomi-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;        extensionRepos = [          "https://raw.githubusercontent.com/MY_ACCOUNT/MY_REPO/repo/index.min.json"        ];      };    };  };}

Table of Contents

Basic usage

Reverse Proxy

By default, the module will execute strfry:

{ ... }:{  services.strfry.enable = true;}

It runs in the systemd service namedstrfry.

You can configure nginx as a reverse proxy with:

{ ... }:{  security.acme = {    acceptTerms = true;    defaults.email = "foo@bar.com";  };  services.nginx.enable = true;  services.nginx.virtualHosts."strfry.example.com" = {    addSSL = true;    enableACME = true;    locations."/" = {      proxyPass = "http://127.0.0.1:${toString config.services.strfry.settings.relay.port}";      proxyWebsockets = true; # nostr uses websockets    };  };  services.strfry.enable = true;}

Table of Contents

Basic Usage

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

Table of Contents

Configuration

Reverse proxy configuration

By default, the module will execute Pingvin Share backend and frontend on the ports 8080 and 3000.

I will run two systemd services namedpingvin-share-backend andpingvin-share-frontend in the specified data directory.

Here is a basic configuration:

{  services-pingvin-share = {    enable = true;    openFirewall = true;    backend.port = 9010;    frontend.port = 9011;  };}

The preferred method to run this service is behind a reverse proxy not to expose an open port. This, you can configure Nginx such like this:

{  services-pingvin-share = {    enable = true;    hostname = "pingvin-share.domain.tld";    https = true;    nginx.enable = true;  };}

Furthermore, you can increase the maximal size of an uploaded file with the optionservices.nginx.clientMaxBodySize.

Table of Contents

Quickstart

Usage

Missing

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:

Table of Contents

Basic usage

nextcloud-occ

Common problems

Using an alternative webserver as reverse-proxy (e.g.httpd)

Installing Apps and PHP extensions

Known warnings

Maintainer information

Nextcloud is a PHP-based application which requires an HTTP server(services.nextcloudand optionally supportsservices.nginx).

For the database, you can setservices.nextcloud.config.dbtype toeithersqlite (the default),mysql, orpgsql. The simplest issqlite,which will be automatically created and managed by the application. For thelast two, you can easily create a local database by settingservices.nextcloud.database.createLocallytotrue, Nextcloud will automatically be configured to connect to it throughsocket.

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

ThehostName option is used internally to configure an HTTPserver usingPHP-FPMandnginx. Theconfig attribute set isused by the imperative installer and all values are written to an additional fileto 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 toservices.nextcloud.settings.trusted_domains.

Auto updates for Nextcloud apps can be enabled usingservices.nextcloud.autoUpdateApps.

The management commandocc can beinvoked by using thenextcloud-occ wrapper that’s globally available on a system with Nextcloud enabled.

It requires elevated permissions to become thenextcloud user. Given the way the privilegeescalation is implemented, parameters passed via the environment to Nextcloud arecurrently ignored, except forOC_PASS andNC_PASS.

Custom service units that need to runnextcloud-occ either need elevated privilegesor the systemd configuration fromnextcloud-setup.service (recommended):

{ config, ... }:{  systemd.services.my-custom-service = {    script = ''      nextcloud-occ …    '';    serviceConfig = {      inherit (config.systemd.services.nextcloud-cron.serviceConfig)        User        LoadCredential        KillMode        ;    };  };}

Please note that the options required are subject to change. Please make sure to read therelease notes when upgrading.

By default,nginx is used as reverse-proxy fornextcloud.However, it’s possible to use e.g.httpd by explicitly disablingnginx usingservices.nginx.enable and fixing thesettingslisten.owner &listen.group in thecorrespondingphpfpm 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 theservices.nextcloud.phpExtraExtensions setting.

Alternatively, extra apps can also be declared with theservices.nextcloud.extraApps setting.When using this setting, apps can no longer be managed statefully because this can lead to Nextcloud updating appsthat are managed by Nix:

{ config, pkgs, ... }:{  services.nextcloud.extraApps = with config.services.nextcloud.package.packages.apps; {    inherit user_oidc calendar contacts;  };}

Keep in mind that this is essentially a mirror of the apps from the appstore, but managed innixpkgs. This is by no means a curated list of apps that receive special testing on each update.

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 Nextcloudsince it cannot move more than one major version forward on a single upgrade. This chapteradds 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 thepackage-expression (and should be backported to supported stable branches after that),major-releases should be added in a new attribute (e.g. Nextcloudv19.0.0should be available innixpkgs aspkgs.nextcloud19).To provide simple upgrade paths it’s generally useful to backport those as well to stablebranches. As long as the package-default isn’t altered, this won’t break existing setups.After that, the versioning-warning in thenextcloud-module should beupdated to make sure that thepackage-option selects the latest versionon fresh setups.

If major-releases will be abandoned by upstream, we should check first if those are neededin NixOS for a safe upgrade-path before removing those. In that case we should keep thosepackages, 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 aNextcloud on e.g. 19.09 to a Nextcloud on 20.09.

Table of Contents

Database Setup

Archive Processing

Backup

Issues

Using other Web Servers than nginx

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

# For MariaDBINSTALL 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 MySQLINSTALL 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 inmatomo as database user and database name,and leave the password field blank. This authentication works by allowingonly thematomo unix user to authenticate as thematomo database user (without needing a password), but noother users. For more information on passwordless login, seehttps://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/.

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

This module comes with the systemd servicematomo-archive-processing.service and a timer thatautomatically triggers archive processing every hour. This means that youcan safelydisable browser triggers for Matomo archiving atAdministration > System > General Settings.

With automatic archive processing, you can now also enable todelete old visitor logsatAdministration > System > Privacy, but make sure that you runsystemctl start matomo-archive-processing.service at least once without errors ifyou have already collected data before, so that the reports get archivedbefore 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 userin thematomo group or root to access the file. For moreinformation, seehttps://matomo.org/faq/how-to-install/faq_138/.

You can use other web servers by forwarding calls forindex.php andpiwik.php to theservices.phpfpm.pools.<name>.socketfastcgi unix socket. You can usethe nginx configuration in the module code as a reference to what elseshould be configured.

Table of Contents

Quickstart

Usage

Missing

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.

Table of Contents

Administration

Database access

Hostname

Setting up TLS/SSL

Themes

Configuration file settings

Example configuration

An administrative user with the usernameadmin is automatically created in themaster realm. Its initial password can beconfigured by settingservices.keycloak.initialAdminPasswordand defaults tochangeme. The password isnot stored safely and should be changed immediately in theadmin panel.

Refer to theKeycloak Server Administration Guide for information onhow to administer your Keycloakinstance.

Keycloak can be used with either PostgreSQL, MariaDB orMySQL. Which one is used can beconfigured inservices.keycloak.database.type. The selecteddatabase will automatically be enabled and a database and rolecreated unlessservices.keycloak.database.host is changedfrom its default oflocalhost orservices.keycloak.database.createLocally is set tofalse.

External database access can also be configured by settingservices.keycloak.database.host,services.keycloak.database.name,services.keycloak.database.username,services.keycloak.database.useSSL andservices.keycloak.database.caCert asappropriate. Note that you need to manually create the databaseand allow the configured database user full access to it.

services.keycloak.database.passwordFilemust be set to the path to a file containing the password usedto log in to the database. Ifservices.keycloak.database.hostandservices.keycloak.database.createLocallyare kept at their defaults, the database rolekeycloak with that password is provisionedon the local database instance.

The hostname is used to build the public URL used as base forall frontend requests and must be configured throughservices.keycloak.settings.hostname.

services.keycloak.settings.hostname-backchannel-dynamicKeycloak has the capability to offer a separate URL for backchannel requests,enabling internal communication while maintaining the use of a public URLfor frontchannel requests. Moreover, the backchannel is dynamicallyresolved based on incoming headers endpoint.

For more information on hostname configuration, see theHostnamesection of the Keycloak Server Installation and ConfigurationGuide.

By default, Keycloak won’t acceptunsecured HTTP connections originating from outside its localnetwork.

HTTPS support requires a TLS/SSL certificate and a private key,bothPEM formatted.Their paths should be set throughservices.keycloak.sslCertificate andservices.keycloak.sslCertificateKey.

You can package custom themes and make them visible toKeycloak throughservices.keycloak.themes. See theThemes section of the Keycloak Server Development Guide and the description of the aforementioned NixOS option formore information.

Keycloak server configuration parameters can be set inservices.keycloak.settings. These corresponddirectly to options inconf/keycloak.conf. Some of the mostimportant parameters are documented as suboptions, the rest canbe found in theAllconfiguration section of the Keycloak Server Installation andConfiguration Guide.

Options containing secret data should be set to an attributeset containing the attribute_secret - astring pointing to a file containing the value the optionshould be set to. See the description ofservices.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";  };}

Table of Contents

Basic usage

Configuration

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

Jitsi Meet depends on the Prosody XMPP server only for message passing fromthe web browser while the default Prosody configuration is intended for usewith standalone XMPP clients and XMPP federation. If you only use Prosody asa backend for Jitsi Meet it is therefore recommended to also enableservices.jitsi-meet.prosody.lockdown option to disable unnecessaryProsody features such as federation or the file proxy.

Here is the minimal configuration with additional configurations:

{  services.jitsi-meet = {    enable = true;    hostName = "jitsi.example.com";    prosody.lockdown = true;    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;}

Table of Contents

Migrating frompgvecto-rs to VectorChord (pre-25.11 installations)

Immich instances that were setup before 25.11 (as insystem.stateVersion = 25.11;) will be automatically migrated to VectorChord.Note that this migration is not reversible, so database dumps should be createdif desired.

SeeImmich documentation for more details aboutthe automatic migration.

After a successful migration,pgvecto-rs should be removed from the databaseinstallation, unless other applications depend on it.

Table of Contents

Basic usage

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

Table of Contents

Quickstart

the minimum configuration to start hatsu server would look like this:

{  services.hatsu = {    enable = true;    settings = {      HATSU_DOMAIN = "hatsu.local";      HATSU_PRIMARY_ACCOUNT = "example.com";    };  };}

this will start the hatsu server on port 3939 and save the database in/var/lib/hatsu/hatsu.sqlite3.

Please refer to theHatsu Documentation for additional configuration options.

Table of Contents

Basic usage

Settings

A very basic configuration may look like this:

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

This configures a simple vhost usingnginxwhich listens togrocy.tld with fully configured ACME/LE (this can bedisabled by settingservices.grocy.nginx.enableSSLtofalse). After the initial setup the credentialsadmin:admincan be used to login.

The application’s state is persisted at/var/lib/grocy/grocy.db in asqlite3 database. The migration is applied when requesting the/-routeof the application.

The configuration forgrocy 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 withan expression like this:

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

Table of Contents

Service configuration

Proxy configuration

User management

The following configuration sets up the PostgreSQL as database backend and bindsGoToSocial to127.0.0.1:8080, expecting to be run behind a HTTP proxy ongotosocial.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 theGoToSocial Documentationfor additional configuration options.

Although it is possible to expose GoToSocial directly, it is common practice to operate it behind anHTTP 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 toSSL/TLS Certificates with ACME for details on how to provision an SSL/TLS certificate.

After the GoToSocial service is running, thegotosocial-admin utility can be used to manage users. In particular anadministrative 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>

Table of Contents

Quickstart

Checkout theconfiguration docs to learn more.Use the following configuration to start a public instance of Glance locally:

{  services.glance = {    enable = true;    settings = {      pages = [        {          name = "Home";          columns = [            {              size = "full";              widgets = [                { type = "calendar"; }                {                  type = "weather";                  location = "Nivelles, Belgium";                }              ];            }          ];        }      ];    };    openFirewall = true;  };}

Table of Contents

Quickstart

FileSender usesSimpleSAMLphp for authentication, which needs to be configured separately.

Minimal working instance of FileSender that uses password-authentication would look like this:

let  format = pkgs.formats.php { };in{  networking.firewall.allowedTCPPorts = [    80    443  ];  services.filesender = {    enable = true;    localDomain = "filesender.example.com";    configureNginx = true;    database.createLocally = true;    settings = {      auth_sp_saml_authentication_source = "default";      auth_sp_saml_uid_attribute = "uid";      storage_filesystem_path = "<STORAGE PATH FOR UPLOADED FILES>";      admin = "admin";      admin_email = "admin@example.com";      email_reply_to = "noreply@example.com";    };  };  services.simplesamlphp.filesender = {    settings = {      "module.enable".exampleauth = true;    };    authSources = {      admin = [ "core:AdminPassword" ];      default = format.lib.mkMixedArray [ "exampleauth:UserPass" ] {        "admin:admin123" = {          uid = [ "admin" ];          cn = [ "admin" ];          mail = [ "admin@example.com" ];        };      };    };  };}

Table of Contents

Basic usage

Using a regular TLS certificate

Database access

Email

Additional settings

Plugins

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 theinstance atdiscourse.example.com and log inusing the credentials provided inservices.discourse.admin.

To set up TLS using a regular certificate and key on file, usetheservices.discourse.sslCertificateandservices.discourse.sslCertificateKeyoptions:

{  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 itsdata. A database will automatically be enabled and a databaseand role created unlessservices.discourse.database.host is changed fromits default ofnull orservices.discourse.database.createLocally is settofalse.

External database access can also be configured by settingservices.discourse.database.host,services.discourse.database.username andservices.discourse.database.passwordFile asappropriate. Note that you need to manually create a databasecalleddiscourse (or the name you chose inservices.discourse.database.name) andallow the configured database user full access to it.

In addition to the basic setup, you’ll want to configure an SMTPserver Discourse can use to send userregistration and password reset emails, among others. You canalso optionally let Discourse receiveemail, which enables people to reply to threads and conversationsvia email.

A basic setup which assumes you want to use your configuredhostname asemail 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’veset inhostname andrequires proper SPF, DKIM and DMARC configuration to be done forthe 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 exampleexample.com instead ofdiscourse.example.com) you should setservices.discourse.mail.notificationEmailAddress andservices.discourse.mail.contactEmailAddress manually.

Additional site settings and backend settings, for which noexplicit NixOS options are provided,can be set inservices.discourse.siteSettings andservices.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 pluginsusing theservices.discourse.pluginsoption. Pre-packaged plugins are provided in<your_discourse_package_here>.plugins. Ifyou want the full suite of plugins provided throughnixpkgs, you can also set theservices.discourse.package option topkgs.discourseAllPlugins.

Plugins can be built with the<your_discourse_package_here>.mkDiscoursePluginfunction. Normally, it should suffice to provide aname andsrc attribute. Ifthe plugin has Ruby dependencies, however, they need to bepackaged in accordance with theDeveloping with Rubysection of the Nixpkgs manual and theappropriate gem options set inbundlerEnvArgs(normallygemdir is sufficient). A plugin’sRuby dependencies are listed in itsplugin.rb file as function calls togem. To construct the correspondingGemfile manually, runbundle init, then add thegem lines to itverbatim.

Much of the packaging can be done automatically by thenixpkgs/pkgs/servers/web-apps/discourse/update.pyscript - just add the plugin to thepluginslist in theupdate_plugins function and runthe script:

./update.py update-plugins

Some plugins providesite settings.Their defaults can be configured usingservices.discourse.siteSettings, just likeregular site settings. To find the names of these settings, lookin theconfig/settings.yml file of the pluginrepo.

For example, to add thediscourse-spoiler-alertanddiscourse-solvedplugins, and disablediscourse-spoiler-alertby 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";  };}

Table of Contents

Basic Usage

At first, an application secret is needed, this can be generated with:

$ cat /dev/urandom | tr -dc a-zA-Z0-9 | fold -w 48 | head -n 1

After that,davis can be deployed like this:

{  services.davis = {    enable = true;    hostname = "davis.example.com";    mail = {      dsn = "smtp://username@example.com:25";      inviteFromAddress = "davis@example.com";    };    adminLogin = "admin";    adminPasswordFile = "/run/secrets/davis-admin-password";    appSecretFile = "/run/secrets/davis-app-secret";    nginx = {};  };}

This deploys Davis using a sqlite database running out of/var/lib/davis.

Table of Contents

Quickstart

Configure ACME (https://nixos.org/manual/nixos/unstable/#module-security-acme).Use the following configuration to start a public instance of Castopod oncastopod.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 tohttps://castopod.example.com/cp-install to create superadmin account after applying the above configuration.

Table of Contents

Service configuration

User management

Proxy configuration

Frontend management

Federation policies

Upload filters

Migration from Pleroma

Advanced deployment options

The Elixir configuration file required by Akkoma is generated automatically fromservices.akkoma.config. Secrets must beincluded from external files outside of the Nix store by setting the configuration option toan attribute set containing the attribute_secret – a string pointing to the filecontaining the actual value of the option.

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

The following configuration binds Akkoma to the Unix socket/run/akkoma/socket, expecting tobe run behind a HTTP proxy onfediverse.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 theconfiguration cheat sheetfor additional configuration options.

After the Akkoma service is running, the administration utility can be used tomanage users. In particular anadministrative 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 anHTTP 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 toSSL/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 theakkoma-fe andadmin-fe frontends by default. These can bemodified by settingservices.akkoma.frontends.

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

{  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 modulewhich allows limiting federation based on instance hostnames.

This configuration snippet provides an example on how these can be used. Choosing an adequatefederation policy is not trivial and entails finding a balance between connectivity to the restof 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 thethe 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 bypointing Akkoma to the existing data. The necessary database migrations are run automaticallyduring 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 thestartup timeout of the system manager. To work around this issue one may adjust the startup timeoutsystemd.services.akkoma.serviceConfig.TimeoutStartSec or simply run the migrationsmanually:

pleroma_ctl migrate

# Create a copy of the databasenix-shell -p postgresql --run 'createdb -T pleroma akkoma'# Copy upload datamkdir /var/lib/akkomacp -R --reflink=auto /var/lib/pleroma/uploads /var/lib/akkoma/

# Delete original databasenix-shell -p postgresql --run 'dropdb pleroma'# Delete original Pleroma staterm -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";}

• lock.target started byloginctl lock-session,

• unlock.target started byloginctl unlock-session and

• sleep.target started bysystemctl suspend.

Table of Contents

Usage

Notes

Upstream Documentation

To enable a Kerberos server:

{  security.krb5 = {    # Here you can choose between the MIT and Heimdal implementations.    package = pkgs.krb5;    # package = pkgs.heimdal;    # Optionally set up a client on the same machine as the server    enable = true;    settings = {      libdefaults.default_realm = "EXAMPLE.COM";      realms."EXAMPLE.COM" = {        kdc = "kerberos.example.com";        admin_server = "kerberos.example.com";      };    };  };  services.kerberos-server = {    enable = true;    settings = {      realms."EXAMPLE.COM" = {        acl = [          {            principal = "adminuser";            access = [              "add"              "cpw"            ];          }        ];      };    };  };}

Note the version number in the URLs, it may be different for the latest version.

Table of Contents

Quickstart

Usage

Defaults

Missing

the minimum to start meilisearch is

{ services.meilisearch.enable = true; }

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

test withcurl -X GET 'http://localhost:7700/health'

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

Table of Contents

Configuration

Table of Contents

Quick Start

{  services.umurmur = {    enable = true;    openFirewall = true;    settings = {      port = 7365;      channels = [        {          name = "root";          parent = "";          description = "Root channel. No entry.";          noenter = true;        }        {          name = "lobby";          parent = "root";          description = "Lobby channel";        }      ];      default_channel = "lobby";    };  };}

See a full configuration inumurmur.conf.example

Table of Contents

Basic usage

Let’s Encrypt Configuration

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

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

The NixOS Prosody module will implement most of these recommendend XEPs out ofthe box. That being said, two components still require somemanual configuration: theMulti User Chat (MUC)and theHTTP File Upload ones.You’ll need to create a DNS subdomain for each of those. The current convention is to name yourMUC endpointconference.example.org and your HTTP upload domainupload.example.org.

A good configuration to start with, including aMulti User Chat (MUC)endpoint as well as aHTTP File Uploadendpoint 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 theprevious 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 acertificate by leveraging the ACMEextraDomainNames module option.

Provided the setup detailed in the previous section, you’ll need the following acme configuration to generatea 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"        ];      };    };  };}

Table of Contents

Generating the Pleroma config

Initializing the database

Enabling the Pleroma service locally

Creating the admin user

Configuring Nginx

Thepleroma_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

Theconfig.exs file can be further customized following the instructions on theupstream 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 thesetup.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, whereservices.pleroma.configs option contains the content of the fileconfig.exs, generatedin 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 byservices.pleroma.secretConfigFile, in our case/var/lib/pleroma/secrets.exs. This file can be created copying the previously generatedconfig.exs file and then removing all the settings, except the secrets. This is an example

# Pleroma instance passwordsimport Configconfig :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 notificationsconfig :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 local127.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 accessinghttp://localhost:4000 from a web browser.

After Pleroma service is running, allPleroma 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, usingLet’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          '';        };      };    };  };}

Table of Contents

Quickstart

To fully setup Netbird as a self-hosted server, we need both a Coturn server and an identity provider, the list of supported SSOs and their setup are availableon Netbird’s documentation.

There are quite a few settings that need to be passed to Netbird for it to function, and a minimal config looks like :

{  services.netbird.server = {    enable = true;    domain = "netbird.example.selfhosted";    enableNginx = true;    coturn = {      enable = true;      passwordFile = "/path/to/a/secret/password";    };    management = {      oidcConfigEndpoint = "https://sso.example.selfhosted/oauth2/openid/netbird/.well-known/openid-configuration";      settings = {        TURNConfig = {          Turns = [            {              Proto = "udp";              URI = "turn:netbird.example.selfhosted:3478";              Username = "netbird";              Password._secret = "/path/to/a/secret/password";            }          ];        };      };    };  };}

Table of Contents

Quickstart

Multiple connections setup

Exposing services internally on the Netbird network

The absolute minimal configuration for the Netbird client daemon looks like this:

{ services.netbird.enable = true; }

This will set up a netbird service listening on the port51820 associated to thewt0 interface.

Which is equivalent to:

{  services.netbird.clients.wt0 = {    port = 51820;    name = "netbird";    interface = "wt0";    hardened = false;  };}

This will set up anetbird.service listening on the port51820 associated to thewt0 interface. There will also benetbird-wt0 binary installed in addition tonetbird.

seeclients option documentation for more details.

Using theservices.netbird.clients option, it is possible to define more thanone netbird service running at the same time.

You must at least define aport for the service to listen on, the rest is optional:

{  services.netbird.clients.wt1.port = 51830;  services.netbird.clients.wt2.port = 51831;}

seeclients option documentation for more details.

You can easily expose services exclusively to Netbird network by combiningnetworking.firewall.interfaces ruleswithinterface names:

{  services.netbird.clients.priv.port = 51819;  services.netbird.clients.work.port = 51818;  networking.firewall.interfaces = {    "${config.services.netbird.clients.priv.interface}" = {      allowedUDPPorts = [ 1234 ];    };    "${config.services.netbird.clients.work.interface}" = {      allowedTCPPorts = [ 8080 ];    };  };}

Table of Contents

Quickstart

Configuration

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, allowingread/write access to all topics to any user without password requirements.

User authentication can be configured with theusers key of listeners. A config that givesfull read access to a usermonitor and restricted write access to a userservice could looklike

{  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, allowingconfigurations in which a given user is only allowed to log in to the broker using specificlisteners (eg to configure an admin user with full access to all topics, but restricted tolocalhost).

Almost all options of Mosquitto are available for configuration at their appropriate levels, someas NixOS options written in camel case, the remainders undersettings with their exact names inthe Mosquitto config file. The exceptions areacl_file (which is always set according to theacl attributes of a listener and its users) andper_listener_settings (which is always set totrue).

Table of Contents

Quick Start

Example Configuration

{ services.jotta-cli.enable = true; }

This addsjotta-cli toenvironment.systemPackages and starts a user service that runsjottad with the default options.

{  services.jotta-cli = {    enable = true;    options = [ "slow" ];    package = pkgs.jotta-cli;  };}

This usesjotta-cli andjottad from thepkgs.jotta-cli package and startsjottad in low memory mode.

jottad is also added toenvironment.systemPackages, sojottad --help can be used to explore options.

Table of Contents

Basic Usage

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

Table of Contents

Quickstart

More detailed setup

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 isrunning you can navigate toabout:config in your Firefox profile and setidentity.sync.tokenserver.uri tohttp://localhost:5000/1.0/sync/1.5. Your browserwill now use your local sync server for data storage.

Thefirefox-syncserver service provides a number of options to make setting upsmall deployment easier. These are grouped under thesingleNode element of theoption tree and allow simple configuration of the most important parameters.

Single node setup is split into two kinds of options: those that affect the syncserver itself, and those that affect its surroundings. Options that affect thesync server arecapacity, which configures how many accounts may be active onthis instance, andurl, which holds the URL under which the sync server can beaccessed. Theurl can be configured automatically when using nginx.

Options that affect the surroundings of the sync server areenableNginx,enableTLS andhostname. IfenableNginx is set the sync server module willautomatically add an nginx virtual host to the system usinghostname as thedomain and seturl accordingly. IfenableTLS is set the module will alsoenable ACME certificates on the new virtual host and force all connections tobe made via TLS.

For actual deployment it is also recommended to store thesecrets file in asecure location.

Table of Contents

Quick Start

Setup with Nginx + ACME (recommended):

{  services.doh-server = {    enable = true;    settings = {      upstream = [ "udp:1.1.1.1:53" ];    };  };  services.nginx = {    enable = true;    virtualHosts."doh.example.com" = {      enableACME = true;      forceSSL = true;      http2 = true;      locations."/".return = 404;      locations."/dns-query" = {        proxyPass = "http://127.0.0.1:8053/dns-query";        recommendedProxySettings = true;      };    };    # and other virtual hosts ...  };  security.acme = {    acceptTerms = true;    defaults.email = "you@example.com";  };  networking.firewall.allowedTCPPorts = [    80    443  ];}

doh-server can also work as a standalone HTTPS web server (with SSL cert and key specified), but this is not recommended asdoh-server does not do OCSP Stabbing.

Setup a standalone instance with ACME:

let  domain = "doh.example.com";in{  security.acme.certs.${domain} = {    dnsProvider = "cloudflare";    credentialFiles."CF_DNS_API_TOKEN_FILE" = "/run/secrets/cf-api-token";  };  services.doh-server = {    enable = true;    settings = {      listen = [ ":443" ];      upstream = [ "udp:1.1.1.1:53" ];    };    useACMEHost = domain;  };  networking.firewall.allowedTCPPorts = [ 443 ];}

See a full configuration in https://github.com/m13253/dns-over-https/blob/master/doh-server/doh-server.conf.

Table of Contents

Configuration

References

Table of Contents

Configuration

Troubleshooting

As an example config file using Cloudflare as DoT upstream, you can use thiscrab-hole.toml

The following is a basic nix config using UDP as a downstream and Cloudflare as upstream.

{  services.crab-hole = {    enable = true;    settings = {      blocklist = {        include_subdomains = true;        lists = [          "https://raw.githubusercontent.com/StevenBlack/hosts/master/alternates/fakenews-gambling-porn/hosts"          "https://s3.amazonaws.com/lists.disconnect.me/simple_tracking.txt"        ];      };      downstream = [        {          protocol = "udp";          listen = "127.0.0.1";          port = 53;        }        {          protocol = "udp";          listen = "::1";          port = 53;        }      ];      upstream = {        name_servers = [          {            socket_addr = "1.1.1.1:853";            protocol = "tls";            tls_dns_name = "1dot1dot1dot1.cloudflare-dns.com";            trust_nx_responses = false;          }          {            socket_addr = "[2606:4700:4700::1111]:853";            protocol = "tls";            tls_dns_name = "1dot1dot1dot1.cloudflare-dns.com";            trust_nx_responses = false;          }        ];      };    };  };}

To test your setup, just query the DNS server with any domain likeexample.com.To test if a domain gets blocked, just choose one of the domains from the blocklist.If the server does not return an IP, this worked correctly.

{  services.crab-hole.settings.downstream = [    {      protocol = "udp";      listen = "localhost";      port = 53;    }  ];}

{  services.crab-hole.settings.downstream = [    {      protocol = "tls";      listen = "[::]";      port = 853;      certificate = ./dns.example.com.crt;      key = "/dns.example.com.key";      # optional (default = 3000)      timeout_ms = 3000;    }  ];}

{  services.crab-hole.settings.downstream = [    {      protocol = "https";      listen = "[::]";      port = 443;      certificate = ./dns.example.com.crt;      key = "/dns.example.com.key";      # optional      dns_hostname = "dns.example.com";      # optional (default = 3000)      timeout_ms = 3000;    }  ];}

{  services.crab-hole.settings.downstream = [    {      protocol = "quic";      listen = "127.0.0.1";      port = 853;      certificate = ./dns.example.com.crt;      key = "/dns.example.com.key";      # optional      dns_hostname = "dns.example.com";      # optional (default = 3000)      timeout_ms = 3000;    }  ];}

{  services.crab-hole.settings.upstream.options = {    validate = false;  };}

{  services.crab-hole.settings.api = {    listen = "127.0.0.1";    port = 8080;    # optional (default = false)    show_doc = true; # OpenAPI doc loads content from third party websites    # optional    admin_key = "1234";  };}

You can check for errors usingsystemctl status crab-hole orjournalctl -xeu crab-hole.service.

{ services.crab-hole.supplementaryGroups = [ "acme" ]; }

Table of Contents

Quickstart

Configuration

This module is designed to use Unix domain sockets as the socket paths can be automatically configured for multipleinstances, but TCP sockets are also supported.

A minimal configuration withnginx may look like the following:

{ config, ... }:{  services.anubis.instances.default.settings.TARGET = "http://localhost:8000";  # required due to unix socket permissions  users.users.nginx.extraGroups = [ config.users.groups.anubis.name ];  services.nginx.virtualHosts."example.com" = {    locations = {      "/".proxyPass = "http://unix:${config.services.anubis.instances.default.settings.BIND}";    };  };}

If Unix domain sockets are not needed or desired, this module supports operating with only TCP sockets.

{  services.anubis = {    instances.default = {      settings = {        TARGET = "http://localhost:8080";        BIND = ":9000";        BIND_NETWORK = "tcp";        METRICS_BIND = "127.0.0.1:9001";        METRICS_BIND_NETWORK = "tcp";      };    };  };}

It is possible to configure default settings for all instances of Anubis, viaservices.anubis.defaultOptions.

{  services.anubis.defaultOptions = {    botPolicy = {      dnsbl = false;    };    settings.DIFFICULTY = 3;  };}

Note that at the moment, a custom bot policy is not merged with the baked-in one. That means to only override a settinglikednsbl, copying the entire bot policy is required. Checkthe upstream repositoryfor the policy.

Table of Contents

Basic Usage

Configuring

A minimal configuration looks like this:

{ services.samba.enable = true; }

This configuration automatically enablessmbd,nmbd andwinbindd services by default.

Samba configuration is located in the/etc/samba/smb.conf file.

{  services.samba = {    enable = true;    settings = {      "public" = {        "path" = "/public";        "read only" = "yes";        "browseable" = "yes";        "guest ok" = "yes";        "comment" = "Public samba share.";      };    };  };}

Table of Contents

Configuration

Litestream service is managed by a dedicated user namedlitestreamwhich needs permission to the database file. Here’s an example config which givesrequired permissions to accessgrafana 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"; } ];        }      ];    };  };}

Table of Contents

Configuration

Adding a new exporter

Updating an exporter module

One of the most common exporters is thenode exporter,it provides hardware and OS metrics from the host it’srunning 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 explicitlyenabled and the ones that areenabled by default,via http under/metrics. In thisexample the firewall should just allow incoming connections to theexporter’s port on the bridge interfacebr0 (this wouldhave to be configured separately of course). For more information aboutconfiguration seeman configuration.nix or search throughtheavailable 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 (seenixpkgs/pkgs/servers/monitoring/prometheus/ forexamples), then a module can be added. The postfix exporter is used in thisexample:

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

{  config,  lib,  pkgs,  options,}: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'    (lib.mkRenamedOptionModule [ "telemetryEndpoint" ] [ "telemetryPath" ])    # removed option 'services.prometheus.exporters.nginx.insecure'    (lib.mkRemovedOptionModule [ "insecure" ] ''      This option was replaced by 'prometheus.exporters.nginx.sslVerify' which defaults to true.    '')    ({ options.warnings = options.warnings; })  ];}

Table of Contents

Basic usage

Local mail

Grafana and GeoIP

A very minimal setup which reads incoming reports from an externalemail address and saves them to a local Elasticsearch instance lookslike 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 forsimplicity, but should be turned on for fully functional reports.

Instead of watching an external inbox, a local inbox can beautomatically provisioned. The recipient’s name is by default set todmarc, but can be configured inservices.parsedmarc.provision.localMail.recipientName. Youneed to add an MX record pointing to the host. More concretely: forthe example to work, an MX record needs to be set up formonitoring.example.com and the complete email address that should beconfigured in the domain’s dmarc policy isdmarc@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’sofficial Grafana dashboard. For all views to work, and for the data tobe complete, GeoIP databases are also required. The following exampleshows a basic deployment where the provisioned Elasticsearch instanceis automatically added as a Grafana datasource, and the dashboard isadded 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 = 0;      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" ];}

Table of Contents

Basic Usage

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.

Table of Contents

Basic Usage

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

Table of Contents

Service Configuration

Operation

Hooks

A basic config that notifies you of all certificate changes for yourdomain 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 CertSpotter should monitor not onlyexample.org, but also all of itssubdomains.

By default, NixOS configures Cert Spotter to skip all certificatesissued before its first launch, because checking the entireCertificate Transparency logs requires downloading tens of terabytes ofdata. If you want to check theentire logs for previously issuedcertificates, you have to setservices.certspotter.startAtEnd tofalse and remove all previously saved log state in/var/lib/certspotter/logs. The downloaded logs aren’t saved, so if youadd a new domain to the watchlist and want Cert Spotter to go throughthe logs again, you will have to remove/var/lib/certspotter/logsagain.

After catching up with the logs, Cert Spotter will start monitoring livelogs. As of October 2023, it uses around20 Mbps of traffic onaverage.

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

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

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

For example, you can removeemailRecipients and send emailnotifications 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    '')  ];}

Table of Contents

Basic Usage

Re-attaching to WeeChat

By default, the module creates asystemdunit which runs the chat client in a detachedscreensession.

This can be done by enabling theweechat service:

{ ... }:{  services.weechat.enable = true;}

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

WeeChat runs in a screen session owned by a dedicated user. To explicitlyallow your another user to attach to this session, thescreenrc needs to be tweaked by addingmultiusersupport:

{  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 usingservices.weechat.sessionName.

Table of Contents

Configuration

The nixos-taskserver tool

Declarative/automatic CA management

Manual CA management

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 aknown CA, which allows creation of client certificates. These certificatesare usually advertised as “server certificates”.

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

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

Withnixos-taskserver the client certificate is createdalong with the UUID of the user, so it handles all of the credentials neededin order to setup the Taskwarrior 2 client to work with a Taskserver.

Because Taskserver by default only provides scripts to setup usersimperatively, thenixos-taskserver tool is used foraddition and deletion of organisations along with users and groups definedbyservices.taskserver.organisations and as well forimperative set up.

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

For example if you add a new organisation usingnixos-taskserver org add foo, the organisation is not modified and deleted nomatter what you define inservices.taskserver.organisations, even if you’re addingthe same organisation in that option.

The tool is modelled to imitate the officialtaskdcommand, 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 2 client for synchronisation with aTaskserver instance, you have to transfer the keys and certificates to theclient machine.

This is done usingnixos-taskserver user export $orgname $username which is printing a shell script fragment to stdoutwhich can either be used verbatim or adjusted to import the user on theclient 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 calledmy-company with theuseralice.

Now in order to import thealice user to another machinealicebox, 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 synchronisingyour tasks for the first time withtask sync init onalicebox.

Subsequent synchronisation requests merely require the commandtask sync after that stage.

If you set any options withinservice.taskserver.pki.manual.*,nixos-taskserver won’t issue certificates, but you canstill use it for adding or removing user accounts.

Table of Contents

Basic usage

Configuration

Using an alternative webserver as reverse-proxy (e.g.httpd)

Sourcehut is a Python and Go based set of applications.This NixOS module also provides basic configuration integrating Sourcehut into locally runningservices.nginx,services.redis.servers.sourcehut,services.postfixandservices.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;    };  };}

ThehostName option is used internally to configure the nginxreverse-proxy. Thesettings attribute set isused 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 bythe module and linked from the store to ensure that all values fromconfig.inican be modified by the module.

By default,nginx is used as reverse-proxy forsourcehut.However, it’s possible to use e.g.httpd by explicitly disablingnginx usingservices.nginx.enable and fixing thesettings.

Table of Contents

Prerequisites

Configuring

Maintenance

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

For instance, the following configuration could be used to use nginx asfrontend 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 enableboth services. In the case of PostgreSQL, a database and a role will becreated.

The default state dir is/var/gitlab/state. This is whereall 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 newsecrets. You for instance usetr -dc A-Za-z0-9 < /dev/urandom | head -c 128 > /var/keys/gitlab/db togenerate a new db secret. Make sure the files can be read by, andonly by, the user specified byservices.gitlab.user. GitLabencrypts sensitive data stored in the database. If you’re restoringan existing GitLab instance, you must specify the secrets secretfromconfig/secrets.yml located in your GitLabstate folder.

Whenincoming_mail.enabled is set totrueinextraConfig an additionalservice calledgitlab-mailroom is enabled for fetching incoming mail.

Refer toAppendix A for all available configurationoptions for theservices.gitlab module.

Table of Contents

Migration from Gitea

Warning

Running forgejo usingservices.gitea.package = pkgs.forgejo is no longerrecommended.If you experience issues with your instance usingservices.gitea,DO NOT report them to theservices.gitea module maintainers.DO report them to theservices.forgejo module maintainers instead.

Table of Contents

Configuration

When enabled, this module automatically creates a systemd service to start thedump1090-fa application. The application will then write its JSON output files to/run/dump1090-fa.

Exposing the integrated web interface is left to the user’s configuration. Below is a minimal example demonstrating how to serve it using Nginx:

{ pkgs, ... }:{  services.dump1090-fa.enable = true;  services.nginx = {    enable = true;    virtualHosts."dump1090-fa" = {      locations = {        "/".alias = "${pkgs.dump1090-fa}/share/dump1090/";        "/data/".alias = "/run/dump1090-fa/";      };    };  };}

Table of Contents

Basic Usage

KRaft

Migrating to settings

The Apache Kafka service is configured almost exclusively through itssettings option, with each attributecorresponding to theupstream configurationmanual broker settings.

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

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

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

This means that the upstreamBroker Configs documentation should be followed closely.

Note that dotted options in the upstream docs donot correspond to nested Nix attrsets, but instead as quoted top levelsettings attributes, as inservices.apache-kafka.settings."broker.id",NOTservices.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 viasettings.

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:

Table of Contents

Basic Usage

By default, the module creates asystemdunit which runs the sync server with an isolated user using the systemdDynamicUser option.

This can be done by enabling theanki-sync-server service:

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

It is necessary to set at least one username-password pair underservices.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 inplaintext. Make sure to set permissions to make this file unreadable to anyuser besides root.

By default, synced data are stored in/var/lib/anki-sync-server/ankiuser.You can change the directory by usingservices.anki-sync-server.baseDirectory

{ services.anki-sync-server.baseDirectory = "/home/anki/data"; }

By default, the server listen addressservices.anki-sync-server.hostis set to localhost, listening on portservices.anki-sync-server.port, and does not open the firewall. Thisis suitable for purely local testing, or to be used behind a reverse proxy. Ifyou want to expose the sync server directly to other computers (not recommendedin most circumstances, because the sync server doesn’t use HTTPS), then set thefollowing options:

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

Table of Contents

Synapse Homeserver

Registering Matrix users

Element (formerly known as Riot) Web Client

Synapse isthe reference homeserver implementation of Matrix from the core developmentteam at matrix.org.

Before deploying synapse server, a postgresql database must be set up.For that, please make sure that postgresql is running and the followingSQL statements to create a user & database calledmatrix-synapse wereexecuted before synapse starts up:

CREATE ROLE "matrix-synapse";CREATE DATABASE "matrix-synapse" WITH OWNER "matrix-synapse"  TEMPLATE template0  LC_COLLATE = "C"  LC_CTYPE = "C";

Usually, it’s sufficient to do this once manually beforecontinuing with the installation.

Please make sure to set a different password.

The following configuration example will set up asynapse server for theexample.org domain, served fromthe hostmyhostname.example.org. For more information,please refer to theinstallation 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.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 canthen enableservices.matrix-synapse.settings.enable_registration = true;.Otherwise, or you can generate a registration secret withpwgen -s 64 1 and set it withservices.matrix-synapse.settings.registration_shared_secret.To create a new user or admin from the terminal your client listenermust be configured to use TCP sockets. Then you can run the followingafter 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:8008New user localpart: your-usernamePassword:Confirm password:Make admin [no]:Success!

In the example, this would create a user with the Matrix Identifier@your-username:example.org.

Element Web isthe reference web client for Matrix and developed by the core team atmatrix.org. Element was formerly known as Riot.im, see theElement introductory blog postfor more information. The following snippet can be optionally added to the code beforeto complete the synapse installation with a web client served athttps://element.myhostname.example.org andhttps://element.example.org. Alternatively, you can use the hostedcopy athttps://app.element.io/,or use other web clients or native client applications. Due to the/.well-known urls set up done above, many clients shouldfill in the required connection details automatically when you enter yourMatrix Identifier. SeeTry 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.      };    };  };}

Table of Contents

Mjolnir Setup

Synapse Antispam Module

First create a new Room which will be used as a management room for Mjolnir. Inthis room, Mjolnir will log possible errors and debugging information. You’llneed to set this Room-ID inservices.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.SeeSynapse #6286for 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 usePantalaimon,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, enableservices.mjolnir.pantalaimon. This willautoconfigure a new Pantalaimon instance, which will connect to the homeserverset inservices.mjolnir.homeserverUrl and Mjolnir itselfwill 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 botuses across an entire homeserver.

To use the Antispam Module, addmatrix-synapse-plugins.matrix-synapse-mjolnir-antispamto the Synapse plugin list and enable themjolnir.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"    '';  };}