NixOS Manual

Version 17.03

Preface (index.html#idm140737316949424)

I. Installation (index.html#ch-installation)

1. Obtaining NixOS (index.html#sec-obtaining)

2. Installing NixOS (index.html#sec-installation)

2.1. UEFI Installation (index.html#sec-uefi-installation)

2.2. Booting from a USB Drive (index.html#sec-booting-from-usb)

2.3. Booting from the netboot media (PXE) (index.html#sec-booting-from-pxe)

2.4. Installing in a Virtualbox guest (index.html#sec-instaling-virtualbox-guest)

3. Changing the Configuration (index.html#sec-changing-config)

4. Upgrading NixOS (index.html#sec-upgrading)

4.1. Automatic Upgrades (index.html#idm140737316657968)

II. Configuration (index.html#ch-configuration)

5. Configuration Syntax (index.html#sec-configuration-syntax)

5.1. NixOS Configuration File (index.html#sec-configuration-file)

5.2. Abstractions (index.html#sec-module-abstractions)

5.3. Modularity (index.html#sec-modularity)

5.4. Syntax Summary (index.html#sec-nix-syntax-summary)

6. Package Management (index.html#sec-package-management)

6.1. Declarative Package Management (index.html#sec-declarative-package-mgmt)

6.1.1. Customising Packages (index.html#sec-customising-packages)

6.1.2. Adding Custom Packages (index.html#sec-custom-packages)

6.2. Ad-Hoc Package Management (index.html#sec-ad-hoc-packages)

7. User Management (index.html#sec-user-management)

8. File Systems (index.html#ch-file-systems)

8.1. LUKS-Encrypted File Systems (index.html#sec-luks-file-systems)

9. X Window System (index.html#sec-x11)

10. Xfce Desktop Environment (index.html#sec-xfce)

11. Networking (index.html#sec-networking)

 11.1. NetworkManager (index.html#sec-networkmanager)

11.2. Secure Shell Access (index.html#sec-ssh)

11.3. IPv4 Configuration (index.html#sec-ipv4)

11.4. IPv6 Configuration (index.html#sec-ipv6)

11.5. Firewall (index.html#sec-firewall)

11.6. Wireless Networks (index.html#sec-wireless)

11.7. Ad-Hoc Configuration (index.html#ad-hoc-network-config)

12. Linux Kernel (index.html#sec-kernel-config)

12.1. Developing kernel modules (index.html#idm140737315713552)

13. DNSCrypt client proxy (index.html#sec-dnscrypt-proxy)

13.1. Basic configuration (index.html#idm140737315708048)

13.2. As a forwarder for another DNS client (index.html#idm140737315704912)

13.2.1. dnsmasq (index.html#idm140737315703216)

13.2.2. unbound (index.html#idm140737315701488)

14. Taskserver (index.html#module-taskserver)

14.1. Configuration (index.html#idm140737315695488)

14.2. The nixos-taskserver tool (index.html#idm140737315690672)

14.3. Declarative/automatic CA management (index.html#idm140737315684624)

14.4. Manual CA management (index.html#idm140737315675440)

15. Gitlab (index.html#module-services-gitlab)

15.1. Prerequisites (index.html#idm140737315670496)

15.2. Configuring (index.html#idm140737315667392)

15.3. Maintenance (index.html#idm140737315660080)

16. Emacs (index.html#module-services-emacs)

16.1. Installing Emacs (index.html#idm140737315649312)

16.1.1. The Dierent Releases of Emacs (index.html#idm140737315646752)

16.1.2. Adding Packages to Emacs (index.html#idm140737315633872)

16.1.3. Advanced Emacs Configuration (index.html#idm140737315583600)

16.2. Running Emacs as a Service (index.html#idm140737315576832)

16.2.1. Enabling the Service (index.html#idm140737315572528)

16.2.2. Starting the client (index.html#idm140737315565216)

16.2.3. Configuring the EDITOR variable (index.html#idm140737315561360)

16.2.4. Per-User Enabling of the Service (index.html#idm140737315552608)

16.3. Configuring Emacs (index.html#idm140737315547616)

 16.3.1. A Major Mode for Nix Expressions (index.html#idm140737315543088)

16.3.2. Accessing man pages (index.html#idm140737315541136)

16.3.3. Editing DocBook 5 XML Documents (index.html#sec-emacs-docbook-xml)

17. PostgreSQL (index.html#module-postgresql)

17.1. Configuring (index.html#idm140737315521456)

17.2. Upgrading (index.html#idm140737315515760)

17.3. Options (index.html#idm140737315514544)

18. Hiding process information (index.html#sec-hidepid)

19. Grsecurity/PaX (index.html#sec-grsecurity)

19.1. Enabling grsecurity/PaX (index.html#sec-grsec-enable)

19.2. Declarative tuning (index.html#sec-grsec-declarative-tuning)

19.3. Manual tuning (index.html#sec-grsec-manual-tuning)

19.4. Security considerations (index.html#sec-grsec-security)

19.5. Using a custom grsecurity/PaX kernel (index.html#sec-grsec-custom-kernel)

19.6. Per-executable PaX flags (index.html#sec-grsec-pax-flags)

19.7. Issues and work-arounds (index.html#sec-grsec-issues)

19.8. Grsecurity/PaX kernel parameters (index.html#sec-grsec-kernel-params)

20. SSL/TLS Certificates with ACME (index.html#module-security-acme)

20.1. Prerequisites (index.html#idm140737315428640)

20.2. Configuring (index.html#idm140737315425680)

20.3. Using ACME certificates in Nginx (index.html#idm140737315419200)

21. Input Methods (index.html#module-services-input-methods)

21.1. IBus (index.html#idm140737315409456)

21.2. Fcitx (index.html#idm140737315396864)

21.3. Nabi (index.html#idm140737315385200)

21.4. Uim (index.html#idm140737315382912)

III. Administration (index.html#ch-running)

22. Service Management (index.html#sec-systemctl)

23. Rebooting and Shutting Down (index.html#sec-rebooting)

24. User Sessions (index.html#sec-user-sessions)

25. Control Groups (index.html#sec-cgroups)

26. Logging (index.html#sec-logging)

27. Cleaning the Nix Store (index.html#sec-nix-gc)

28. Container Management (index.html#ch-containers)

 28.1. Imperative Container Management (index.html#sec-imperative-containers)

28.2. Declarative Container Specification (index.html#sec-declarative-containers)

28.3. Container Networking (index.html#sec-container-networking)

29. Troubleshooting (index.html#ch-troubleshooting)

29.1. Boot Problems (index.html#sec-boot-problems)

29.2. Maintenance Mode (index.html#sec-maintenance-mode)

29.3. Rolling Back Configuration Changes (index.html#sec-rollback)

29.4. Nix Store Corruption (index.html#sec-nix-store-corruption)

29.5. Network Problems (index.html#sec-nix-network-issues)

IV. Development (index.html#ch-development)

30. Getting the Sources (index.html#sec-getting-sources)

31. Writing NixOS Modules (index.html#sec-writing-modules)

31.1. Option Declarations (index.html#sec-option-declarations)

31.1.1. Extensible Option Types (index.html#sec-option-declarations-eot)

31.2. Options Types (index.html#sec-option-types)

31.2.1. Basic Types (index.html#idm140737315354208)

31.2.2. Value Types (index.html#idm140737315336720)

31.2.3. Composed Types (index.html#idm140737315324880)

31.2.4. Submodule (index.html#section-option-types-submodule)

31.2.4.1. Composed with listOf (index.html#idm140737315295328)

31.2.4.2. Composed with attrsOf (index.html#idm140737315290160)

31.2.5. Extending types (index.html#idm140737315284752)

31.2.6. Custom Types (index.html#idm140737315272880)

31.3. Option Definitions (index.html#sec-option-definitions)

31.4. Meta Attributes (index.html#sec-meta-attributes)

32. Building Specific Parts of NixOS (index.html#sec-building-parts)

33. Writing NixOS Documentation (index.html#sec-writing-documentation)

33.1. Building the Manual (index.html#idm140737315165616)

33.2. Editing DocBook XML (index.html#idm140737315160688)

33.3. Creating a Topic (index.html#idm140737315152400)

33.4. Adding a Topic to the Book (index.html#idm140737315141984)

34. Building Your Own NixOS CD (index.html#sec-building-cd)

35. NixOS Tests (index.html#sec-nixos-tests)

35.1. Writing Tests (index.html#sec-writing-nixos-tests)

 35.2. Running Tests (index.html#sec-running-nixos-tests-interactively)

35.3. Running Tests interactively (index.html#sec-running-nixos-tests)

36. Testing the Installer (index.html#ch-testing-installer)

37. Releases (index.html#ch-releases)

37.1. Release process (index.html#release-process)

37.1.1. One month before the beta (index.html#one-month-before-the-beta)

37.1.2. At beta release time (index.html#at-beta-release-time)

37.1.3. Before the final release (index.html#before-the-final-release)

37.1.4. At final release time (index.html#at-final-release-time)

37.2. Release schedule (index.html#release-schedule)

A. Configuration Options (options.html)

B. Release Notes (release-notes.html)

B.1. Release 17.03 (Gorilla, 2017/03/31) (release-notes.html#sec-release-17.03)

B.1.1. Highlights (release-notes.html#sec-release-17.03-highlights)

B.1.2. New Services (release-notes.html#sec-release-17.03-new-services)

B.1.3. Backward Incompatibilities (release-notes.html#sec-release-17.03-incompatibilities)

B.1.4. Other Notable Changes (release-notes.html#sec-release-17.03-notable-changes)

B.2. Release 16.09 (Flounder, 2016/09/30) (release-notes.html#sec-release-16.09)

B.3. Release 16.03 (Emu, 2016/03/31) (release-notes.html#sec-release-16.03)

B.4. Release 15.09 (Dingo, 2015/09/30) (release-notes.html#sec-release-15.09)

B.5. Release 14.12 (Caterpillar, 2014/12/30) (release-notes.html#sec-release-14.12)

B.6. Release 14.04 (Baboon, 2014/04/30) (release-notes.html#sec-release-14.04)

B.7. Release 13.10 (Aardvark, 2013/10/31) (release-notes.html#sec-release-13.10)

Preface

This manual describes how to install, use and extend NixOS, a Linux distribution based on the purely functional package management system Nix.

If you encounter problems, please report them on the

nix-dev@lists.science.uu.nl (http://lists.science.uu.nl/mailman/listinfo/nix-dev) mailing list or on the #nixos channel on
Freenode (irc://irc.freenode.net/#nixos). Bugs should be reported in NixOS GitHub issue tracker (https://github.com/NixOS/nixpkgs/issues).

Note: Commands prefixed with # have to be run as root, either requiring to login as root user or temporarily switching to it using sudo for
example.
Part I. Installation

This section describes how to obtain, install, and configure NixOS for first-time use.

Chapter 1. Obtaining NixOS

NixOS ISO images can be downloaded from the NixOS download page (http://nixos.org/nixos/download.html). There are a number of installation op
tions. If you happen to have an optical drive and a spare CD, burning the image to CD and booting from that is probably the easiest option. Most peo
ple will need to prepare a USB stick to boot from. Unetbootin is recommended and the process is described in brief below. Note that systems which
use UEFI require some additional manual steps. If you run into diculty a number of alternative methods are presented in the NixOS Wiki
(https://nixos.org/wiki/Installing_NixOS_from_a_USB_stick).

As an alternative to installing NixOS yourself, you can get a running NixOS system through several other means:

Using virtual appliances in Open Virtualization Format (OVF) that can be imported into VirtualBox. These are available from the NixOS download
page (http://nixos.org/nixos/download.html).

Using AMIs for Amazons EC2. To find one for your region and instance type, please refer to the list of most recent AMIs (https://github.
com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix).

Using NixOps, the NixOS-based cloud deployment tool, which allows you to provision VirtualBox and EC2 NixOS instances from declarative spec
ifications. Check out the NixOps homepage (https://nixos.org/nixops) for details.

Chapter 2. Installing NixOS

1. Boot from the CD.

2. The CD contains a basic NixOS installation. (It also contains Memtest86+, useful if you want to test new hardware). When its finished booting, it
should have detected most of your hardware.

3. The NixOS manual is available on virtual console 8 (press Alt+F8 to access).

4. You get logged in as root (with empty password).

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

6. The boot process should have brought up networking (check ip a). Networking is necessary for the installer, since it will download lots of stu
(such as source tarballs or Nixpkgs channel binaries). Its best if you have a DHCP server on your network. Otherwise configure networking manu
ally using ifconfig.

To manually configure the network on the graphical installer, first disable network-manager with systemctl stop network-manager.

7. If you would like to continue the installation from a dierent machine you need to activate the SSH daemon via systemctl start sshd. In or
der to be able to login you also need to set a password for root using passwd.

8. The NixOS installer doesnt do any partitioning or formatting yet, so you need to do that yourself. Use the following commands:

For partitioning: fdisk.

For initialising Ext4 partitions: mkfs.ext4. It is recommended that you assign a unique symbolic label to the file system using the option
-L label, since this makes the file system configuration independent from device changes. For example:

# mkfs.ext4 -L nixos /dev/sda1

For creating swap partitions: mkswap. Again its recommended to assign a label to the swap partition: -L label.

For creating LVM volumes, the LVM commands, e.g.,

 # pvcreate /dev/sda1 /dev/sdb1
# vgcreate MyVolGroup /dev/sda1 /dev/sdb1
# lvcreate --size 2G --name bigdisk MyVolGroup
# lvcreate --size 1G --name smalldisk MyVolGroup

For creating software RAID devices, use mdadm.

9. Mount the target file system on which NixOS should be installed on /mnt, e.g.

# mount /dev/disk/by-label/nixos /mnt

10. If your machine has a limited amount of memory, you may want to activate swap devices now (swapon device ). The installer (or rather, the build
actions that it may spawn) may need quite a bit of RAM, depending on your configuration.

11. You now need to create a file /mnt/etc/nixos/configuration.nix that specifies the intended configuration of the system. This is because
NixOS has a declarative configuration model: you create or edit a description of the desired configuration of your system, and then NixOS takes
care of making it happen. The syntax of the NixOS configuration file is described in Chapter 5, Configuration Syntax (index.html#sec-configura
tion-syntax), while a list of available configuration options appears in Appendix A, Configuration Options (options.html). A minimal example is
shown in Example 2.2, NixOS Configuration (index.html#ex-config).

The command nixos-generate-config can generate an initial configuration file for you:

# nixos-generate-config --root /mnt

You should then edit /mnt/etc/nixos/configuration.nix to suit your needs:

# nano /mnt/etc/nixos/configuration.nix

If youre using the graphical ISO image, other editors may be available (such as vim). If you have network access, you can also install other editors
for instance, you can install Emacs by running nix-env -i emacs.

You must set the option boot.loader.grub.device to specify on which disk the GRUB boot loader is to be installed. Without it, NixOS cannot
boot.

Another critical option is fileSystems, specifying the file systems that need to be mounted by NixOS. However, you typically dont need to set it
yourself, because nixos-generate-config sets it automatically in /mnt/etc/nixos/hardware-configuration.nix from your currently
mounted file systems. (The configuration file hardware-configuration.nix is included from configuration.nix and will be overwritten by
future invocations of nixos-generate-config; thus, you generally should not modify it.)

Note: Depending on your hardware configuration or type of file system, you may need to set the option boot.initrd.kernelModules
to include the kernel modules that are necessary for mounting the root file system, otherwise the installed system will not be able to boot.
(If this happens, boot from the CD again, mount the target file system on /mnt, fix /mnt/etc/nixos/configuration.nix and rerun
nixos-install.) In most cases, nixos-generate-config will figure out the required modules.

12. Do the installation:

# nixos-install

Cross fingers. If this fails due to a temporary problem (such as a network issue while downloading binaries from the NixOS binary cache), you can
just re-run nixos-install. Otherwise, fix your configuration.nix and then re-run nixos-install.

As the last step, nixos-install will ask you to set the password for the root user, e.g.

setting root password...

Enter new UNIX password: ***
Retype new UNIX password: ***

13. If everything went well:

# reboot
14. You should now be able to boot into the installed NixOS. The GRUB boot menu shows a list of available configurations (initially just one). Every
time you change the NixOS configuration (see Changing Configuration (index.html#sec-changing-config) ), a new item is added to the menu. This
allows you to easily roll back to a previous configuration if something goes wrong.

You should log in and change the root password with passwd.

Youll probably want to create some user accounts as well, which can be done with useradd:

$ useradd -c 'Eelco Dolstra' -m eelco

$ passwd eelco

You may also want to install some software. For instance,

$ nix-env -qa \*

shows what packages are available, and

$ nix-env -i w3m

install the w3m browser.

To summarise, Example 2.1, Commands for Installing NixOS on /dev/sda (index.html#ex-install-sequence) shows a typical sequence of com
mands for installing NixOS on an empty hard drive (here /dev/sda). Example 2.2, NixOS Configuration (index.html#ex-config) shows a correspond
ing configuration Nix expression.

Example 2.1. Commands for Installing NixOS on /dev/sda

# fdisk /dev/sda # (or whatever device you want to install on)

# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
# mount /dev/disk/by-label/nixos /mnt
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
# nixos-install
# reboot

Example 2.2. NixOS Configuration

{ config, pkgs, ... }:

{
imports =
[ # Include the results of the hardware scan.
./hardware-configuration.nix
];

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

# 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;
}
2.1. UEFI Installation
NixOS can also be installed on UEFI systems. The procedure is by and large the same as a BIOS installation, with the following changes:

You should boot the live CD in UEFI mode (consult your specific hardware's documentation for instructions). You may find the rEFInd boot manag
er (http://www.rodsbooks.com/refind) useful.

Instead of fdisk, you should use gdisk to partition your disks. You will need to have a separate partition for /boot with partition code EF00, and it
should be formatted as a vfat filesystem.

You must set boot.loader.systemd-boot.enable to true. nixos-generate-config should do this automatically for new configurations
when booted in UEFI mode.

After having mounted your installation partition to /mnt, you must mount the boot partition to /mnt/boot.

You may want to look at the options starting with boot.loader.efi and boot.loader.systemd-boot as well.

2.2. Booting from a USB Drive

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

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

Change the label of the disk partition to the label of the ISO (visible with the blkid command), or

Edit loader/entries/nixos-livecd.conf on the drive and change the root= field in the options line to point to your drive (see the docu
mentation on root= in the kernel documentation (https://www.kernel.org/doc/Documentation/kernel-parameters.txt) for more details).

2.3. Booting from the netboot media (PXE)

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

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

nix-build -A netboot nixos/release.nix

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

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

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

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

2.4. Installing in a Virtualbox guest

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

1. Add a New Machine in Virtualbox with OS Type "Linux / Other Linux"

2. Base Memory Size: 768 MB or higher.

3. New Hard Disk of 8 GB or higher.

4. Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM)

5. Click on Settings / System / Processor and enable PAE/NX

6. Click on Settings / System / Acceleration and enable "VT-x/AMD-V" acceleration

7. Save the settings, start the virtual machine, and continue installation like normal

There are a few modifications you should make in configuration.nix. Enable the virtualbox guest service in the main block:

virtualisation.virtualbox.guest.enable = true;

Enable booting:

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

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

boot.initrd.checkJournalingFS = false;

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

{ config, pkgs, ...} :

{
...

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

The folder will be available directly under the root directory.

Chapter 3. Changing the Configuration

The file /etc/nixos/configuration.nix contains the current configuration of your machine. Whenever youve changed something (in
dex.html#ch-configuration) in that file, you should do

# nixos-rebuild switch

to build the new configuration, make it the default configuration for booting, and try to realise the configuration in the running system (e.g., by restart
ing system services).

Warning: These commands must be executed as root, so you should either run them from a root shell or by prefixing them with sudo -i.

You can also do

# nixos-rebuild test

to build the configuration and switch the running system to it, but without making it the boot default. So if (say) the configuration locks up your ma
chine, you can just reboot to get back to a working configuration.

There is also

# nixos-rebuild boot
to build the configuration and make it the boot default, but not switch to it now (so it will only take eect after the next reboot).

You can make your configuration show up in a dierent submenu of the GRUB 2 boot screen by giving it a dierent profile name, e.g.

# nixos-rebuild switch -p test

which causes the new configuration (and previous ones created using -p test) to show up in the GRUB submenu NixOS - Profile 'test'. This can
be useful to separate test configurations from stable configurations.

Finally, you can do

$ nixos-rebuild build

to build the configuration but nothing more. This is useful to see whether everything compiles cleanly.

If you have a machine that supports hardware virtualisation, you can also test the new configuration in a sandbox by building and running a QEMU vir
tual machine that contains the desired configuration. Just do

$ nixos-rebuild build-vm
$ ./result/bin/run-*-vm

The VM does not have any data from your host system, so your existing user accounts and home directories will not be available. You can forward
ports on the host to the guest. For instance, the following will forward host port 2222 to guest port 22 (SSH):

$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm

allowing you to log in via SSH (assuming you have set the appropriate passwords or SSH authorized keys):

$ ssh -p 2222 localhost

Chapter 4. Upgrading NixOS

The best way to keep your NixOS installation up to date is to use one of the NixOS channels. A channel is a Nix mechanism for distributing Nix ex
pressions and associated binaries. The NixOS channels are updated automatically from NixOSs Git repository after certain tests have passed and all
packages have been built. These channels are:

Stable channels, such as nixos-17.03 (https://nixos.org/channels/nixos-17.03). These only get conservative bug fixes and pack
age upgrades. For instance, a channel update may cause the Linux kernel on your system to be upgraded from 4.9.16 to 4.9.17 (a minor bug fix),
but not from 4.9.x to 4.11.x (a major change that has the potential to break things). Stable channels are generally maintained until the next stable
branch is created.

The unstable channel, nixos-unstable (https://nixos.org/channels/nixos-unstable). This corresponds to NixOSs main develop
ment branch, and may thus see radical changes between channel updates. Its not recommended for production systems.

Small channels, such as nixos-17.03-small (https://nixos.org/channels/nixos-17.03-small) or

nixos-unstable-small (https://nixos.org/channels/nixos-unstable-small). These are identical to the stable and unstable
channels described above, except that they contain fewer binary packages. This means they get updated faster than the regular channels (for in
stance, when a critical security patch is committed to NixOSs source tree), but may require more packages to be built from source than usual.
Theyre mostly intended for server environments and as such contain few GUI applications.

To see what channels are available, go to https://nixos.org/channels (https://nixos.org/channels). (Note that the URIs of the various channels redirect
to a directory that contains the channels latest version and includes ISO images and VirtualBox appliances.)

When you first install NixOS, youre automatically subscribed to the NixOS channel that corresponds to your installation source. For instance, if you
installed from a 17.03 ISO, you will be subscribed to the nixos-17.03 channel. To see which NixOS channel youre subscribed to, run the following
as root:

# nix-channel --list | grep nixos

nixos https://nixos.org/channels/nixos-unstable

To switch to a dierent NixOS channel, do

 # nix-channel --add https://nixos.org/channels/channel-name nixos

(Be sure to include the nixos parameter at the end.) For instance, to use the NixOS 17.03 stable channel:

# nix-channel --add https://nixos.org/channels/nixos-17.03 nixos

If you have a server, you may want to use the small channel instead:

# nix-channel --add https://nixos.org/channels/nixos-17.03-small nixos

And if you want to live on the bleeding edge:

# nix-channel --add https://nixos.org/channels/nixos-unstable nixos

You can then upgrade NixOS to the latest version in your chosen channel by running

# nixos-rebuild switch --upgrade

which is equivalent to the more verbose nix-channel --update nixos; nixos-rebuild switch.

Note: Channels are set per user. This means that running nix-channel --add as a non root user (or without sudo) will not aect
configuration in /etc/nixos/configuration.nix

Warning: It is generally safe to switch back and forth between channels. The only exception is that a newer NixOS may also have a newer Nix
version, which may involve an upgrade of Nixs database schema. This cannot be undone easily, so in that case you will not be able to go
back to your original channel.

4.1. Automatic Upgrades

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

system.autoUpgrade.enable = true;

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

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

Part II. Configuration

This chapter describes how to configure various aspects of a NixOS machine through the configuration file /etc/nixos/configuration.nix. As
described in Chapter 3, Changing the Configuration (index.html#sec-changing-config), changes to this file only take eect after you run nixos-rebuild.

Chapter 5. Configuration Syntax

The NixOS configuration file /etc/nixos/configuration.nix is actually a Nix expression, which is the Nix package managers purely functional
language for describing how to build packages and configurations. This means you have all the expressive power of that language at your disposal,
including the ability to abstract over common patterns, which is very useful when managing complex systems. The syntax and semantics of the Nix
language are fully described in the Nix manual (http://nixos.org/nix/manual/#chap-writing-nix-expressions), but here we give a short overview of the
most important constructs useful in NixOS configuration files.
5.1. NixOS Configuration File
The NixOS configuration file generally looks like this:

{ config, pkgs, ... }:

{ option definitions
}

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

{ config, pkgs, ... }:

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

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

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

{ config, pkgs, ... }:

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

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

NixOS checks your option definitions for correctness. For instance, if you try to define an option that doesnt exist (that is, doesnt have a correspond
ing option declaration), nixos-rebuild will give an error like:

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

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

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

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

Strings
Strings are enclosed in double quotes, e.g.

networking.hostName = "dexter";

Special characters can be escaped by prefixing them with a backslash (e.g. \").

Multi-line strings can be enclosed in double single quotes, e.g.

 networking.extraHosts =
''
127.0.0.2 other-localhost
10.0.0.1 server
'';

The main dierence is that it strips from each line a number of spaces equal to the minimal indentation of the string as a whole (disregarding the in
dentation of empty lines), and that characters like " and \ are not special (making it more convenient for including things like shell code). See more
info about this in the Nix manual here (https://nixos.org/nix/manual/#ssec-values).

Booleans
These can be true or false, e.g.

networking.firewall.enable = true;
networking.firewall.allowPing = false;

Integers
For example,

boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;

(Note that here the attribute name net.ipv4.tcp_keepalive_time is enclosed in quotes to prevent it from being interpreted as a set named net
containing a set named ipv4, and so on. This is because its not a NixOS option but the literal name of a Linux kernel setting.)

Sets
Sets were introduced above. They are name/value pairs enclosed in braces, as in the option definition

fileSystems."/boot" =
{ device = "/dev/sda1";
fsType = "ext4";
options = [ "rw" "data=ordered" "relatime" ];
};

Lists
The important thing to note about lists is that list elements are separated by whitespace, like this:

boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];

List elements can be any other type, e.g. sets:

swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];

Packages
Usually, the packages you need are already part of the Nix Packages collection, which is a set that can be accessed through the function argument
pkgs. Typical uses:

environment.systemPackages =
[ pkgs.thunderbird
pkgs.emacs
];

postgresql.package = pkgs.postgresql90;

The latter option definition changes the default PostgreSQL package used by NixOSs PostgreSQL service to 9.0. For more information on pack
ages, including how to add new ones, see Section 6.1.2, Adding Custom Packages (index.html#sec-custom-packages).

5.2. Abstractions
If you find yourself repeating yourself over and over, its time to abstract. Take, for instance, this Apache HTTP Server configuration:

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

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

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

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

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

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

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

Functions provide another method of abstraction. For instance, suppose that we want to generate lots of dierent virtual hosts, all with identical con
figuration except for the host name. This can be done as follows:
 {
services.httpd.virtualHosts =
let
makeVirtualHost = name:
{ hostName = name;
documentRoot = "/webroot";
adminAddr = "alice@example.org";
};
in
[ (makeVirtualHost "example.org")
(makeVirtualHost "example.com")
(makeVirtualHost "example.gov")
(makeVirtualHost "example.nl")
];
}

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

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

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

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

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

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

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

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

Here, the construct ${...} allows the result of an expression to be spliced into a string.
5.3. Modularity
The NixOS configuration mechanism is modular. If your configuration.nix becomes too big, you can split it into multiple files. Likewise, if you
have multiple NixOS configurations (e.g. for dierent computers) with some commonality, you can move the common configuration into a shared file.

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

{ config, pkgs, ... }:

{ imports = [ ./vpn.nix ./kde.nix ];

services.httpd.enable = true;
environment.systemPackages = [ pkgs.emacs ];
...
}

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

{ config, pkgs, ... }:

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

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

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

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

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

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

When that happens, its possible to force one definition take precedence over the others:

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

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

{ config, pkgs, ... }:

{ environment.systemPackages =
if config.services.xserver.enable then
[ pkgs.firefox
pkgs.thunderbird
]
else
[ ];
}
With multiple modules, it may not be obvious what the final value of a configuration option is. The command nixos-option allows you to find out:

$ nixos-option services.xserver.enable
true

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

Interactive exploration of the configuration is possible using nix-repl (https://github.com/edolstra/nix-repl), a read-eval-print loop for Nix expres
sions. Its not installed by default; run nix-env -i nix-repl to get it. A typical use:

$ nix-repl '<nixpkgs/nixos>'

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

nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts

[ "example.org" "example.gov" ]

5.4. Syntax Summary

Below is a summary of the most important syntactic constructs in the Nix expression language. Its not complete. In particular, there are many other
built-in functions. See the Nix manual (http://nixos.org/nix/manual/#chap-writing-nix-expressions) for the rest.

Example Description
Basic values
"Hello world" A string
A string containing an expression (expands to
"${pkgs.bash}/bin/sh"
"/nix/store/hash-bash-version/bin/sh")
true, false Booleans
123 An integer
./foo.png A path (relative to the containing Nix expression)
Compound values
{ x = 1; y = 2; } An set with attributes names x and y
{ foo.bar = 1; } A nested set, equivalent to { foo = { bar = 1; }; }
rec { x = "foo"; y = x + "bar"; } A recursive set, equivalent to { x = "foo"; y = "foobar"; }
[ "foo" "bar" ] A list with two elements
Operators
"foo" + "bar" String concatenation
1 + 2 Integer addition
"foo" == "f" + "oo" Equality test (evaluates to true)
"foo" != "bar" Inequality test (evaluates to true)
!true Boolean negation
{ x = 1; y = 2; }.x Attribute selection (evaluates to 1)
{ x = 1; y = 2; }.z or 3 Attribute selection with default (evaluates to 3)
{ x = 1; y = 2; } // { z = 3; } Merge two sets (attributes in the right-hand set taking precedence)
Control structures
if 1 + 1 == 2 then "yes!" else "no!" Conditional expression
assert 1 + 1 == 2; "yes!" Assertion check (evaluates to "yes!")
let x = "foo"; y = "bar"; in x + y Variable definition
with pkgs.lib; head [ 1 2 3 ] Add all attributes from the given set to the scope (evaluates to 1)
Functions (lambdas)
x: x + 1 A function that expects an integer and returns it increased by 1
(x: x + 1) 100 A function call (evaluates to 101)
let inc = x: x + 1; in inc (inc (inc 100)) A function bound to a variable and subsequently called by name (evaluates to 103)
{ x, y }: x + y A function that expects a set with required attributes x and y and concatenates them
A function that expects a set with required attribute x and optional y, using "bar" as default
{ x, y ? "bar" }: x + y
value for y
{ x, y, ... }: x + y A function that expects a set with required attributes x and y and ignores any other attributes
A function that expects a set with required attributes x and y, and binds the whole set to
{ x, y } @ args: x + y
args
Built-in functions
import ./foo.nix Load and return Nix expression in given file
map (x: x + x) [ 1 2 3 ] Apply a function to every element of a list (evaluates to [ 2 4 6 ])

[1] If
youre wondering how its possible that the (indirect) result of a function is passed as an input to that same function: thats because Nix is a lazy
language it only computes values when they are needed. This works as long as no individual configuration value depends on itself.

Chapter 6. Package Management

This section describes how to add additional packages to your system. NixOS has two distinct styles of package management:

Declarative, where you declare what packages you want in your configuration.nix. Every time you run nixos-rebuild, NixOS will ensure that
you get a consistent set of binaries corresponding to your specification.

Ad hoc, where you install, upgrade and uninstall packages via the nix-env command. This style allows mixing packages from dierent Nixpkgs
versions. Its the only choice for non-root users.

6.1. Declarative Package Management

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

environment.systemPackages = [ pkgs.thunderbird ];

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

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

$ nix-env -qaP '*' --description

nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
...

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

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

6.1.1. Customising Packages

Some packages in Nixpkgs have options to enable or disable optional functionality or change other aspects of the package. For instance, the Firefox
wrapper package (which provides Firefox with a set of plugins such as the Adobe Flash player) has an option to enable the Google Talk plugin. It can
be set in configuration.nix as follows: nixpkgs.config.firefox.enableGoogleTalkPlugin = true;

Warning: Unfortunately, Nixpkgs currently lacks a way to query available configuration options.

Apart from high-level options, its possible to tweak a package in almost arbitrary ways, such as changing or disabling dependencies of a package.
For instance, the Emacs package in Nixpkgs by default has a dependency on GTK+ 2. If you want to build it against GTK+ 3, you can specify that as
follows:
 environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];

The function override performs the call to the Nix function that produces Emacs, with the original arguments amended by the set of arguments
specified by you. So here the function argument gtk gets the value pkgs.gtk3, causing Emacs to depend on GTK+ 3. (The parentheses are neces
sary because in Nix, function application binds more weakly than list construction, so without them, environment.systemPackages would be a list
with two elements.)

Even greater customisation is possible using the function overrideAttrs. While the override mechanism above overrides the arguments of a
package function, overrideAttrs allows changing the attributes passed to mkDerivation. This permits changing any aspect of the package,
such as the source code. For instance, if you want to override the source code of Emacs, you can say:

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

Here, overrideAttrs takes the Nix derivation specified by pkgs.emacs and produces a new derivation in which the originals name and src at
tribute have been replaced by the given values by re-calling stdenv.mkDerivation. The original attributes are accessible via the function argument,
which is conventionally named oldAttrs.

The overrides shown above are not global. They do not aect the original package; other packages in Nixpkgs continue to depend on the original
rather than the customised package. This means that if another package in your system depends on the original package, you end up with two in
stances of the package. If you want to have everything depend on your customised instance, you can apply a global override as follows:

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

The eect of this definition is essentially equivalent to modifying the emacs attribute in the Nixpkgs source tree. Any package in Nixpkgs that depends
on emacs will be passed your customised instance. (However, the value pkgs.emacs in nixpkgs.config.packageOverrides refers to the origi
nal rather than overridden instance, to prevent an infinite recursion.)

6.1.2. Adding Custom Packages

Its possible that a package you need is not available in NixOS. In that case, you can do two things. First, you can clone the Nixpkgs repository, add
the package to your clone, and (optionally) submit a patch or pull request to have it accepted into the main Nixpkgs repository. This is described in de
tail in the Nixpkgs manual (http://nixos.org/nixpkgs/manual). In short, you clone Nixpkgs:

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

$ cd nixpkgs

Then you write and test the package as described in the Nixpkgs manual. Finally, you add it to environment.systemPackages, e.g.

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

and you run nixos-rebuild, specifying your own Nixpkgs tree:

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

The second possibility is to add the package outside of the Nixpkgs tree. For instance, here is how you specify a build of the GNU Hello
(http://www.gnu.org/software/hello/) package directly in configuration.nix:
 environment.systemPackages =
let
my-hello = with pkgs; stdenv.mkDerivation rec {
name = "hello-2.8";
src = fetchurl {
url = "mirror://gnu/hello/${name}.tar.gz";
sha256 = "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6";
};
};
in
[ my-hello ];

Of course, you can also move the definition of my-hello into a separate Nix expression, e.g.

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

where my-hello.nix contains:

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

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

This allows testing the package easily:

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

6.2. Ad-Hoc Package Management

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

$ nix-env -iA nixos.thunderbird

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

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

$ nix-channel --update nixos

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

$ nix-env -u '*'

A package can be uninstalled using the -e flag:

 $ nix-env -e thunderbird

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

$ nix-env --rollback

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

Chapter 7. User Management

NixOS supports both declarative and imperative styles of user management. In the declarative style, users are specified in configuration.nix. For
instance, the following states that a user account named alice shall exist:

users.extraUsers.alice =
{ isNormalUser = true;
home = "/home/alice";
description = "Alice Foobar";
extraGroups = [ "wheel" "networkmanager" ];
openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
};

Note that alice is a member of the wheel and networkmanager groups, which allows her to use sudo to execute commands as root and to con
figure the network, respectively. Also note the SSH public key that allows remote logins with the corresponding private key. Users created in this way
do not have a password by default, so they cannot log in via mechanisms that require a password. However, you can use the passwd program to set
a password, which is retained across invocations of nixos-rebuild.

If you set users.mutableUsers to false, then the contents of /etc/passwd and /etc/group will be congruent to your NixOS configuration. For instance, if
you remove a user from users.extraUsers and run nixos-rebuild, the user account will cease to exist. Also, imperative commands for managing users
and groups, such as useradd, are no longer available. Passwords may still be assigned by setting the user's hashedPassword option. A hashed
password can be generated using mkpasswd -m sha-512 after installing the mkpasswd package.

A user ID (uid) is assigned automatically. You can also specify a uid manually by adding

uid = 1000;

to the user specification.

Groups can be specified similarly. The following states that a group named students shall exist:

users.extraGroups.students.gid = 1000;

As with users, the group ID (gid) is optional and will be assigned automatically if its missing.

In the imperative style, users and groups are managed by commands such as useradd, groupmod and so on. For instance, to create a user account
named alice:

# useradd -m alice

To make all nix tools available to this new user use `su - USER` which opens a login shell (==shell that loads the profile) for given user. This will create
the ~/.nix-defexpr symlink. So run:

# su - alice -c "true"

The flag -m causes the creation of a home directory for the new user, which is generally what you want. The user does not have an initial password
and therefore cannot log in. A password can be set using the passwd utility:

# passwd alice
Enter new UNIX password: ***
Retype new UNIX password: ***
A user can be deleted using userdel:

# userdel -r alice

The flag -r deletes the users home directory. Accounts can be modified using usermod. Unix groups can be managed using groupadd, groupmod
and groupdel.

Chapter 8. File Systems

You can define file systems using the fileSystems configuration option. For instance, the following definition causes NixOS to mount the Ext4 file
system on device /dev/disk/by-label/data onto the mount point /data:

fileSystems."/data" =
{ device = "/dev/disk/by-label/data";
fsType = "ext4";
};

Mount points are created automatically if they dont already exist. For device, its best to use the topology-independent device aliases in
/dev/disk/by-label and /dev/disk/by-uuid, as these dont change if the topology changes (e.g. if a disk is moved to another IDE controller).

You can usually omit the file system type (fsType), since mount can usually detect the type and load the necessary kernel module automatically.
However, if the file system is needed at early boot (in the initial ramdisk) and is not ext2, ext3 or ext4, then its best to specify fsType to ensure
that the kernel module is available.

8.1. LUKS-Encrypted File Systems

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

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

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

Are you sure? (Type uppercase yes): YES

Enter LUKS passphrase: ***
Verify passphrase: ***

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

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

# mkfs.ext4 /dev/mapper/crypted

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

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

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

boot.loader.grub.enableCryptodisk = true;

Chapter 9. X Window System

The X Window System (X11) provides the basis of NixOS graphical user interface. It can be enabled as follows:
 services.xserver.enable = true;

The X server will automatically detect and use the appropriate video driver from a set of X.org drivers (such as vesa and intel). You can also specify
a driver manually, e.g.

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

to enable X.orgs xf86-video-r128 driver.

You also need to enable at least one desktop or window manager. Otherwise, you can only log into a plain undecorated xterm window. Thus you
should pick one or more of the following lines:

services.xserver.desktopManager.plasma5.enable = true;
services.xserver.desktopManager.xfce.enable = true;
services.xserver.desktopManager.gnome3.enable = true;
services.xserver.windowManager.xmonad.enable = true;
services.xserver.windowManager.twm.enable = true;
services.xserver.windowManager.icewm.enable = true;
services.xserver.windowManager.i3.enable = true;

NixOSs default display manager (the program that provides a graphical login prompt and manages the X server) is SLiM. You can select an alternative
one by picking one of the following lines:

services.xserver.displayManager.sddm.enable = true;
services.xserver.displayManager.lightdm.enable = true;

The X server is started automatically at boot time. If you dont want this to happen, you can set:

services.xserver.autorun = false;

The X server can then be started manually:

# systemctl start display-manager.service

NVIDIA Graphics Cards

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

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

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

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

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

On 64-bit systems, if you want full acceleration for 32-bit programs such as Wine, you should also set the following:

hardware.opengl.driSupport32Bit = true;

AMD Graphics Cards

AMD provides a proprietary driver for its graphics cards that has better 3D performance than the X.org drivers. It is not enabled by default because its
not free software. You can enable it as follows:
 services.xserver.videoDrivers = [ "ati_unfree" ];

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

On 64-bit systems, if you want full acceleration for 32-bit programs such as Wine, you should also set the following:

hardware.opengl.driSupport32Bit = true;

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

services.xserver.synaptics.enable = true;

The driver has many options (see Appendix A, Configuration Options (options.html)). For instance, the following enables two-finger scrolling:

services.xserver.synaptics.twoFingerScroll = true;

GTK/Qt themes
GTK themes can be installed either to user profile or system-wide (via system.environmentPackages). To make Qt 5 applications look similar to
GTK2 ones, you can install qt5.qtbase.gtk package into your system environment. It should work for all Qt 5 library versions.

Chapter 10. Xfce Desktop Environment

To enable the Xfce Desktop Environment, set

services.xserver.desktopManager = {
xfce.enable = true;
default = "xfce";
};

Optionally, compton can be enabled for nice graphical eects, some example settings:

services.compton = {
enable = true;
fade = true;
inactiveOpacity = "0.9";
shadow = true;
fadeDelta = 4;
};

Some Xfce programs are not installed automatically. To install them manually (system wide), put them into your environment.systemPackages.

NixOSs default display manager is SLiM. (DM is the program that provides a graphical login prompt and manages the X server.) You can, for example,
select KDEs sddm instead:

services.xserver.displayManager.sddm.enable = true;

Thunar Volume Support

To enable Thunar volume support, put
 services.xserver.desktopManager.xfce.enable = true;

into your configuration.nix.

Polkit Authentication Agent

There is no authentication agent automatically installed alongside Xfce. To allow mounting of local (non-removable) filesystems, you will need to install
one. Installing polkit_gnome, a rebuild, logout and login did the trick.

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

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

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

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

A log-out and re-log will be needed for this to take eect.

Chapter 11. Networking

This section describes how to configure networking components on your NixOS machine.

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

networking.networkmanager.enable = true;

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

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

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

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

Note: networking.networkmanager and networking.wireless (WPA Supplicant) cannot be enabled at the same time: you can still
connect to the wireless networks using NetworkManager.

11.2. Secure Shell Access

Secure shell (SSH) access to your machine can be enabled by setting:
 services.openssh.enable = true;

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

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

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

11.3. IPv4 Configuration

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

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

Typically youll also want to set a default gateway and set of name servers:

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

Note: Statically configured interfaces are set up by the systemd service interface-name-cfg.service. The default gateway and name
server configuration is performed by network-setup.service.

The host name is set using networking.hostName:

networking.hostName = "cartman";

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

11.4. IPv6 Configuration

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

networking.enableIPv6 = false;

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

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

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

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

For configuring a gateway, optionally with explicitly specified interface:

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

See Section 11.3, IPv4 Configuration (index.html#sec-ipv4) for similar examples and additional information.
11.5. Firewall
NixOS has a simple stateful firewall that blocks incoming connections and other unexpected packets. The firewall applies to both IPv4 and IPv6 trac.
It is enabled by default. It can be disabled as follows:

networking.firewall.enable = false;

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

networking.firewall.allowedTCPPorts = [ 80 443 ];

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

networking.firewall.allowPing = true;

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

11.6. Wireless Networks

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

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

networking.wireless.enable = true;

NixOS lets you specify networks for wpa_supplicant declaratively:

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

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

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

# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf

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

# systemctl restart wpa_supplicant.service

11.7. Ad-Hoc Configuration

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

networking.localCommands =
''
ip -6 addr add 2001:610:685:1::1/64 dev eth0
'';
Chapter 12. Linux Kernel
You can override the Linux kernel and associated packages using the option boot.kernelPackages. For instance, this selects the Linux 3.10
kernel:

boot.kernelPackages = pkgs.linuxPackages_3_10;

Note that this not only replaces the kernel, but also packages that are specific to the kernel version, such as the NVIDIA video drivers. This ensures
that driver packages are consistent with the kernel.

The default Linux kernel configuration should be fine for most users. You can see the configuration of your current kernel with the following command:

zcat /proc/config.gz

If you want to change the kernel configuration, you can use the packageOverrides feature (see Section 6.1.1, Customising Packages (in
dex.html#sec-customising-packages)). For instance, to enable support for the kernel debugger KGDB:

nixpkgs.config.packageOverrides = pkgs:
{ linux_3_4 = pkgs.linux_3_4.override {
extraConfig =
''
KGDB y
'';
};
};

extraConfig takes a list of Linux kernel configuration options, one per line. The name of the option should not include the prefix CONFIG_. The op
tion value is typically y, n or m (to build something as a kernel module).

Kernel modules for hardware devices are generally loaded automatically by udev. You can force a module to be loaded via boot.kernelModules,
e.g.

boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];

If the module is required early during the boot (e.g. to mount the root file system), you can use boot.initrd.extraKernelModules:

boot.initrd.extraKernelModules = [ "cifs" ];

This causes the specified modules and their dependencies to be added to the initial ramdisk.

Kernel runtime parameters can be set through boot.kernel.sysctl, e.g.

boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;

sets the kernels TCP keepalive time to 120 seconds. To see the available parameters, run sysctl -a.

12.1. Developing kernel modules

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

$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev

$ nix-shell '<nixpkgs>' -A linuxPackages.kernel
$ unpackPhase
$ cd linux-*
$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
Chapter 13. DNSCrypt client proxy
The DNSCrypt client proxy relays DNS queries to a DNSCrypt enabled upstream resolver. The trac between the client and the upstream resolver is
encrypted and authenticated, mitigating the risk of MITM attacks, DNS poisoning attacks, and third-party snooping (assuming the upstream is
trustworthy).

13.1. Basic configuration

To enable the client proxy, set

services.dnscrypt-proxy.enable = true;

Enabling the client proxy does not alter the system nameserver; to relay local queries, prepend 127.0.0.1 to networking.nameservers.

13.2. As a forwarder for another DNS client

To run the DNSCrypt proxy client as a forwarder for another DNS client, change the default proxy listening port to a non-standard value and point the
other client to it:

services.dnscrypt-proxy.localPort = 43;

13.2.1. dnsmasq

{
services.dnsmasq.enable = true;
services.dnsmasq.servers = [ "127.0.0.1#43" ];
}

13.2.2. unbound

{
services.unbound.enable = true;
services.unbound.forwardAddresses = [ "127.0.0.1@43" ];
}

Chapter 14. Taskserver

Taskserver is the server component of Taskwarrior (https://taskwarrior.org/), a free and open source todo list application.

Upstream documentation: https://taskwarrior.org/docs/#taskd (https://taskwarrior.org/docs/#taskd)

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

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

While the client certificates in Taskserver only authenticate whether a user is allowed to connect, every user has its own UUID which identifies it as an
entity.
With nixos-taskserver the client certificate is created along with the UUID of the user, so it handles all of the credentials needed in order to setup the
Taskwarrior client to work with a Taskserver.

14.2. The nixos-taskserver tool

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

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

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

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

14.3. Declarative/automatic CA management

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

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

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

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

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

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

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

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

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

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

14.4. Manual CA management

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

Chapter 15. Gitlab

Gitlab is a feature-rich git hosting service.

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

For instance, the following configuration could be used to use nginx as frontend proxy:
 services.nginx = {
enable = true;
recommendedGzipSettings = true;
recommendedOptimisation = true;
recommendedProxySettings = true;
recommendedTlsSettings = true;
virtualHosts."git.example.com" = {
enableACME = true;
forceSSL = true;
locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";
};
};
'';

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

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

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

services.gitlab = {
enable = true;
databasePassword = "eXaMpl3";
initialRootPassword = "UseNixOS!";
https = true;
host = "git.example.com";
port = 443;
user = "git";
group = "git";
smtp = {
enable = true;
address = "localhost";
port = 25;
};
secrets = {
db = "uPgq1gtwwHiatiuE0YHqbGa5lEIXH7fMsvuTNgdzJi8P0Dg12gibTzBQbq5LT7PNzcc3BP9P1snHVnduqtGF43PgrQtU7XL93ts6gqe9CBN
hjtaqUwutQUDkygP5NrV6";
secret = "devzJ0Tz0POiDBlrpWmcsjjrLaltyiAdS8TtgT9YNBOoUcDsfppiY3IXZjMVtKgXrFImIennFGOpPN8IkP8ATXpRgDD5rxVnKuTTwYQ
aci2NtaV1XxOQGjdIE50VGsR3";
otp = "e1GATJVuS2sUh7jxiPzZPre4qtzGGaS22FR50Xs1TerRVdgI3CBVUi5XYtQ38W4xFeS4mDqi5cQjExE838iViSzCdcG19XSL6qNsfokQP9
JugwiftmhmCadtsnHErBMI";
};
extraConfig = {
gitlab = {
email_from = "gitlab-no-reply@example.com";
email_display_name = "Example GitLab";
email_reply_to = "gitlab-no-reply@example.com";
default_projects_features = { builds = false; };
};
};
};

If you're setting up a new Gitlab instance, generate new secrets. You for instance use tr -dc A-Za-z0-9 < /dev/urandom | head -c 128 to
generate a new secret. Gitlab encrypts sensitive data stored in the database. If you're restoring an existing Gitlab instance, you must specify the se
crets secret from config/secrets.yml located in your Gitlab state folder.
Refer to Appendix A, Configuration Options (options.html) for all available configuration options for the services.gitlab module.

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

For example, to backup a Gitlab instance:

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

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

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

Chapter 16. Emacs

Emacs (http://www.gnu.org/software/emacs/) is an extensible, customizable, self-documenting real-time display editor and more. At its core is an
interpreter for Emacs Lisp, a dialect of the Lisp programming language with extensions to support text editing.

Emacs runs within a graphical desktop environment using the X Window System, but works equally well on a text terminal. Under OS X, a "Mac port"
edition is available, which uses Apple's native GUI frameworks.

Nixpkgs provides a superior environment for running Emacs. It's simple to create custom builds by overriding the default packages. Chaotic collec
tions of Emacs Lisp code and extensions can be brought under control using declarative package management. NixOS even provides a systemd user
service for automatically starting the Emacs daemon.

16.1. Installing Emacs

Emacs can be installed in the normal way for Nix (see Chapter 6, Package Management (index.html#sec-package-management)). In addition, a NixOS
service can be enabled.

16.1.1. The Dierent Releases of Emacs

Nixpkgs defines several basic Emacs packages. The following are attributes belonging to the pkgs set:

emacs
emacs, emacs25
The latest stable version of Emacs 25 using the GTK+ 2 (http://www.gtk.org) widget toolkit.

emacs25-nox
Emacs 25 built without any dependency on X11 libraries.

emacs24Macport
Emacs 24 with the "Mac port" patches, providing a more native look and feel under OS X.

If those aren't suitable, then the following imitation Emacs editors are also available in Nixpkgs: Zile (https://www.gnu.org/software/zile/), mg
(http://homepage.boetes.org/software/mg/), Yi (http://yi-editor.github.io/).

16.1.2. Adding Packages to Emacs

Emacs includes an entire ecosystem of functionality beyond text editing, including a project planner, mail and news reader, debugger interface, calen
dar, and more.

Most extensions are gotten with the Emacs packaging system (package.el) from Emacs Lisp Package Archive (ELPA) (https://elpa.gnu.org/), MELPA
(https://melpa.org/), MELPA Stable (https://stable.melpa.org/), and Org ELPA (http://orgmode.org/elpa.html). Nixpkgs is regularly updated to mirror all
these archives.

Under NixOS, you can continue to use package-list-packages and package-install to install packages. You can also declare the set of
Emacs packages you need using the derivations from Nixpkgs. The rest of this section discusses declarative installation of Emacs packages through
nixpkgs.

Note: This documentation describes the new Emacs packages framework in NixOS 16.03 (emacsPackagesNg) which should not be
confused with the previous and deprecated framework (emacs24Packages).

The first step to declare the list of packages you want in your Emacs installation is to create a dedicated derivation. This can be done in a dedicated
emacs.nix file such as:

emacs.nix)
Example 16.1. Nix expression to build Emacs with packages (emacs.nix

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

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

$ nix-build emacs.nix

To run the newly compiled executable:

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

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

The first non-comment line in this file ({ pkgs ? ... }) indicates that the whole file represents a function.

The let expression below defines a myEmacs binding pointing to the current stable version of Emacs. This binding is here to separate the
choice of the Emacs binary from the specification of the required packages.

This generates an emacsWithPackages function. It takes a single argument: a function from a package set to a list of packages (the pack
ages that will be available in Emacs).

The rest of the file specifies the list of packages to install. In the example, two packages (magit and zerodark-theme) are taken from
MELPA stable.
 Two packages (undo-tree and zoom-frm) are taken from MELPA.

Three packages are taken from GNU ELPA.

notmuch is taken from a nixpkgs derivation which contains an Emacs mode.

The result of this configuration will be an emacs command which launches Emacs with all of your chosen packages in the load-path.

You can check that it works by executing this in a terminal:

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

and then typing M-x package-initialize. Check that you can use all the packages you want in this Emacs instance. For example, try switching
to the zerodark theme through M-x load-theme <RET> zerodark <RET> y.

Tip
A few popular extensions worth checking out are: auctex, company, edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile, and
yasnippet.

The list of available packages in the various ELPA repositories can be seen with the following commands:

Example 16.2. Querying Emacs packages

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

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

If you are on NixOS, you can install this particular Emacs for all users by adding it to the list of system packages (see Section 6.1, Declarative Pack
age Management (index.html#sec-declarative-package-mgmt)). Simply modify your file configuration.nix to make it contain:

Example 16.3. Custom Emacs in configuration.nix

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

In this case, the next nixos-rebuild switch will take care of adding your emacs to the PATH environment variable (see Chapter 3, Changing the Con
figuration (index.html#sec-changing-config)).

If you are not on NixOS or want to install this particular Emacs only for yourself, you can do so by adding it to your ~/.config/nixpkgs/con
fig.nix (see Nixpkgs manual (http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides)):

Example 16.4. Custom Emacs in ~/.config/nixpkgs/config.nix

{
packageOverrides = super: let self = super.pkgs; in {
myemacs = import /path/to/emacs.nix { pkgs = self; };
};
}
In this case, the next nix-env -f '<nixpkgs>' -iA myemacs will take care of adding your emacs to the PATH environment variable.

16.1.3. Advanced Emacs Configuration

If you want, you can tweak the Emacs package itself from your emacs.nix. For example, if you want to have a GTK+3-based Emacs instead of the
default GTK+2-based binary and remove the automatically generated emacs.desktop (useful is you only use emacsclient), you can change your file
emacs.nix in this way:

Example 16.5. Custom Emacs build

{ pkgs ? import <nixpkgs> {} }:

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

After building this file as shown in Example 16.1, Nix expression to build Emacs with packages (emacs.nix) (index.html#ex-emacsNix), you will get
an GTK3-based Emacs binary pre-loaded with your favorite packages.

16.2. Running Emacs as a Service

NixOS provides an optional systemd service which launches Emacs daemon (https://www.gnu.org/software/emacs/manual/html_n
ode/emacs/Emacs-Server.html) with the user's login session.

Source: modules/services/editors/emacs.nix

16.2.1. Enabling the Service

To install and enable the systemd user service for Emacs daemon, add the following to your configuration.nix:

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

The services.emacs.package option allows a custom derivation to be used, for example, one created by emacsWithPackages.

Ensure that the Emacs server is enabled for your user's Emacs configuration, either by customizing the server-mode variable, or by adding
(server-start) to ~/.emacs.d/init.el.

To start the daemon, execute the following:

$ nixos-rebuild switch # to activate the new configuration.nix

$ systemctl --user daemon-reload # to force systemd reload
$ systemctl --user start emacs.service # to start the Emacs daemon

The server should now be ready to serve Emacs clients.

16.2.2. Starting the client
Ensure that the emacs server is enabled, either by customizing the server-mode variable, or by adding (server-start) to ~/.emacs.

To connect to the emacs daemon, run one of the following:

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

16.2.3. Configuring the EDITOR variable

If services.emacs.defaultEditor is true, the EDITOR variable will be set to a wrapper script which launches emacsclient.

Any setting of EDITOR in the shell config files will override services.emacs.defaultEditor. To make sure EDITOR refers to the Emacs wrapper
script, remove any existing EDITOR assignment from .profile, .bashrc, .zshenv or any other shell config file.

If you have formed certain bad habits when editing files, these can be corrected with a shell alias to the wrapper script:

alias vi=$EDITOR

16.2.4. Per-User Enabling of the Service

In general, systemd user services are globally enabled by symlinks in /etc/systemd/user. In the case where Emacs daemon is not wanted for all
users, it is possible to install the service but not globally enable it:

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

To enable the systemd user service for just the currently logged in user, run:

systemctl --user enable emacs

This will add the symlink ~/.config/systemd/user/emacs.service.

16.3. Configuring Emacs

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

Example 16.6. Package initialization in .emacs

(require 'package)

;; optional. makes unpure packages archives unavailable

(setq package-archives nil)

(setq package-enable-at-startup nil)

(package-initialize)

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

16.3.1. A Major Mode for Nix Expressions

Of interest may be melpaPackages.nix-mode, which provides syntax highlighting for the Nix language. This is particularly convenient if you regular
ly edit Nix files.

16.3.2. Accessing man pages

You can use woman to get completion of all available man pages. For example, type M-x woman <RET> nixos-rebuild <RET>.

16.3.3. Editing DocBook 5 XML Documents

Emacs includes nXML (https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html), a major-mode for validating and edit
ing XML documents. When editing DocBook 5.0 documents, such as this one (index.html), nXML needs to be configured with the relevant schema,
which is not included.

To install the DocBook 5.0 schemas, either add pkgs.docbook5 to environment.systemPackages (NixOS (index.html#sec-declarative-package-
mgmt)), or run nix-env -i pkgs.docbook5 (Nix (index.html#sec-ad-hoc-packages)).

Then customize the variable rng-schema-locating-files to include ~/.emacs.d/schemas.xml and put the following text into that file:

~/.emacs.d/schemas.xml)
Example 16.7. nXML Schema Configuration (~/.emacs.d/schemas.xml

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

Chapter 17. PostgreSQL

Source: modules/services/databases/postgresql.nix

Upstream documentation: http://www.postgresql.org/docs/ (http://www.postgresql.org/docs/)

PostgreSQL is an advanced, free relational database.

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

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

Note that you are required to specify the desired version of PostgreSQL (e.g. pkgs.postgresql94). Since upgrading your PostgreSQL version re
quires a database dump and reload (see below), NixOS cannot provide a default value for services.postgresql.package such as the most re
cent release of PostgreSQL.
By default, PostgreSQL stores its databases in /var/db/postgresql. You can override this using services.postgresql.dataDir, e.g.

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

17.2. Upgrading
FIXME: document dump/upgrade/load cycle.

17.3. Options
FIXME: auto-generated list of module options.

Chapter 18. Hiding process information

Setting

security.hideProcessInformation = true;

ensures that access to process information is restricted to the owning user. This implies, among other things, that command-line arguments remain
private. Unless your deployment relies on unprivileged users being able to inspect the process information of other users, this option should be safe to
enable.

Members of the proc group are exempt from process information hiding.

To allow a service foo to run without process information hiding, set

systemd.services.foo.serviceConfig.SupplementaryGroups = [ "proc" ];

Chapter 19. Grsecurity/PaX

Grsecurity/PaX is a set of patches against the Linux kernel that implements an extensive suite of features (https://grsecurity.net/features.php) de
signed to increase the diculty of exploiting kernel and application bugs.

The NixOS grsecurity/PaX module is designed with casual users in mind and is intended to be compatible with normal desktop usage, without unnec
essarily compromising security. The following sections describe the configuration and administration of a grsecurity/PaX enabled NixOS system. For
more comprehensive coverage, please refer to the grsecurity wikibook (https://en.wikibooks.org/wiki/Grsecurity) and the Arch Linux wiki page on grse
curity (https://wiki.archlinux.org/index.php/Grsecurity).

Note: grsecurity/PaX is only available for the latest linux -stable kernel; patches against older kernels are available from upstream only for a
fee.

Note: We standardise on a desktop oriented configuration primarily due to lack of resources. The grsecurity/PaX configuration state space is
huge and each configuration requires quite a bit of testing to ensure that the resulting packages work as advertised. Defining additional
package sets would likely result in a large number of functionally broken packages, to nobody's benefit.

19.1. Enabling grsecurity/PaX

To make use of grsecurity/PaX on NixOS, add the following to your configuration.nix:

security.grsecurity.enable = true;
followed by

# nixos-rebuild boot
# reboot

Note: Enabling the grsecurity module overrides boot.kernelPackages, to reduce the risk of misconfiguration. Section 19.5, Using a
custom grsecurity/PaX kernel (index.html#sec-grsec-custom-kernel) describes how to use a custom kernel package set.

For most users, further configuration should be unnecessary. All users are encouraged to look over Section 19.4, Security considerations (in
dex.html#sec-grsec-security) before using the system, however. If you experience problems, please refer to Section 19.7, Issues and work-arounds
(index.html#sec-grsec-issues).

Once booted into the new system, you can optionally use paxtest to exercise various PaX features:

# nix-shell -p paxtest --command 'paxtest blackhat'

Executable anonymous mapping : Killed
Executable bss : Killed
# ... remaining output truncated for brevity

19.2. Declarative tuning

The default configuration mode is strictly declarative. Some features simply cannot be changed at all after boot, while others are locked once the sys
tem is up and running. Moreover, changes to the configuration enter into eect only upon booting into the new system.

The NixOS module exposes a limited number of options for tuning the behavior of grsecurity/PaX. These are options thought to be of particular inter
est to most users. For experts, further tuning is possible via boot.kernelParams (see Section 19.8, Grsecurity/PaX kernel parameters (in
dex.html#sec-grsec-kernel-params)) and boot.kernel.sysctl."kernel.grsecurity.*" (the wikibook contains an exhaustive listing of grsecu
rity sysctl tunables (https://en.wikibooks.org/wiki/Grsecurity/Appendix/Sysctl_Options)).

19.3. Manual tuning

To permit manual tuning of grsecurity runtime parameters, set:

security.grsecurity.lockTunables = false;

Once booted into this system, grsecurity features that have a corresponding sysctl tunable can be changed without rebooting, either by switching into
a new system profile or via the sysctl utility.

To lock all grsecurity tunables until the next boot, do:

# systemctl start grsec-lock

19.4. Security considerations

The NixOS kernel is built using upstream's recommended settings for a desktop deployment that generally favours security over performance. This
section details deviations from upstream's recommendations that may compromise security.

Warning: There may be additional problems not covered here!

The following hardening features are disabled in the NixOS kernel:

Kernel symbol hiding: rendered useless by redistributing kernel objects.

Randomization of kernel structures: rendered useless by redistributing kernel objects.

 TCP simultaneous OPEN connection is permitted: breaking strict TCP conformance is inappropriate for a general purpose kernel. The trade-
o is that an attacker may be able to deny outgoing connections if they are able to guess the source port allocated by your OS for that con
nection and also manage to initiate a TCP simultaneous OPEN on that port before the connection is actually established.

Trusted path execution: a desirable feature, but requires some more work to operate smoothly on NixOS.

The NixOS module conditionally weakens chroot restrictions to accommodate NixOS lightweight containers and sandboxed Nix builds. This can
be problematic if the deployment also runs privileged network facing processes that rely on chroot for isolation.

The NixOS kernel is patched to allow usermode helpers from anywhere in the Nix store. A usermode helper is an executable called by the kernel in
certain circumstances, e.g., modprobe. Vanilla grsecurity only allows usermode helpers from paths typically owned by the super user. The NixOS
kernel allows an attacker to inject malicious code into the Nix store which could then be executed by the kernel as a usermode helper.

The following features are disabled because they overlap with vanilla kernel mechanisms:

/proc hardening: use security.hideProcessInformation instead. This trades weaker protection for greater compatibility.

dmesg restrictions: use boot.kernel.sysctl."kernel.dmesg_restrict" instead

19.5. Using a custom grsecurity/PaX kernel

The NixOS kernel is likely to be either too permissive or too restrictive for many deployment scenarios. In addition to producing a kernel more suitable
for a particular deployment, a custom kernel may improve security by depriving an attacker the ability to study the kernel object code, adding yet
more guesswork to successfully carry out certain exploits.

To build a custom kernel using upstream's recommended settings for server deployments, while still using the NixOS module:

nixpkgs.config.packageOverrides = super: {
linux_grsec_nixos = super.linux_grsec_nixos.override {
extraConfig = ''
GRKERNSEC_CONFIG_AUTO y
GRKERNSEC_CONFIG_SERVER y
GRKERNSEC_CONFIG_SECURITY y
'';
};
};

The grsecurity/PaX wikibook provides an exhaustive listing of kernel configuration options (https://en.wikibooks.org/wiki/Grsecurity/Appendix/Grsecu
rity_and_PaX_Configuration_Options).

The NixOS module makes several assumptions about the kernel and so may be incompatible with your customised kernel. Currently, the only way to
work around these incompatibilities is to eschew the NixOS module.

If not using the NixOS module, a custom grsecurity package set can be specified inline instead, as in

boot.kernelPackages =
let
kernel = pkgs.linux_grsec_nixos.override {
extraConfig = /* as above */;
};
self = pkgs.linuxPackagesFor kernel self;
in self;

19.6. Per-executable PaX flags

Manual tuning of per-file PaX flags for executables in the Nix store is impossible on a properly configured system. If a package in Nixpkgs fails due to
PaX, that is a bug in the package recipe and should be reported to the maintainer (including relevant dmesg output).

For executables installed outside of the Nix store, PaX flags can be set using the paxctl utility:
 paxctl -czem foo

Warning: paxctl overwrites files in-place.

Equivalently, on file systems that support extended attributes:

setfattr -n user.pax.flags -v em foo

19.7. Issues and work-arounds

User namespaces require CAP_SYS_ADMIN: consequently, unprivileged namespaces are unsupported. Applications that rely on namespaces for
sandboxing must use a privileged helper. For chromium there is security.chromiumSuidSandbox.enable.

Access to EFI runtime services is disabled by default: this plugs a potential code injection attack vector; use security.grsecurity.disable
EfiRuntimeServices to override this behavior.

User initiated autoloading of modules (e.g., when using fuse or loop devices) is disallowed; either load requisite modules as root or add them to
boot.kernelModules.

Virtualization: KVM is the preferred virtualization solution. Xen, Virtualbox, and VMWare are unsupported and most likely require a custom kernel.

Attaching gdb to a running process is disallowed by default: unprivileged users can only ptrace processes that are children of the ptracing
process. To relax this restriction, set

boot.kernel.sysctl."kernel.grsecurity.harden_ptrace" = 0;

Overflows in boot critical code (e.g., the root filesystem module) can render the system unbootable. Work around by setting

boot.kernelParams = [ "pax_size_overflow_report_only" ];

The modify_ldt (2) syscall is disabled by default. This restriction can interfere with programs designed to run legacy 16-bit or segmented 32-bit
code. To support applications that rely on this syscall, set

boot.kernel.sysctl."kernel.modify_ldt" = 1;

The gitlab service (Chapter 15, Gitlab (index.html#module-services-gitlab)) requires a variant of the ruby interpreter built without `mprotect()` hard
ening, as in

services.gitlab.packages.gitlab = pkgs.gitlab.override {
ruby = pkgs.ruby.overrideAttrs (attrs: {
postFixup = "paxmark m $out/bin/ruby";
});
};

19.8. Grsecurity/PaX kernel parameters

The NixOS kernel supports the following kernel command line parameters:

pax_nouderef: disable UDEREF (separate kernel and user address spaces).

pax_weakuderef: enable a faster but weaker variant of UDEREF on 64-bit processors with PCID support (check grep pcid /proc/cpuinfo).

pax_sanitize_slab={off|fast|full}: control kernel slab object sanitization. Defaults to fast

pax_size_overflow_report_only: log size overflow violations but leave the violating task running
 grsec_sysfs_restrict=[0|1]: toggle sysfs restrictions. The NixOS module sets this to 0 for systemd compatibility

Chapter 20. SSL/TLS Certificates with ACME

NixOS supports automatic domain validation & certificate retrieval and renewal using the ACME protocol. This is currently only implemented by and
for Let's Encrypt. The alternative ACME client simp_le is used under the hood.

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

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

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

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

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

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

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

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

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

20.3. Using ACME certificates in Nginx

NixOS supports fetching ACME certificates for you by setting enableACME = true; in a virtualHost config. We first create self-signed placeholder
certificates in place of the real ACME certs. The placeholder certs are overwritten when the ACME certs arrive. For foo.example.com the config
would look like.
 services.nginx = {
enable = true;
virtualHosts = {
"foo.example.com" = {
forceSSL = true;
enableACME = true;
locations."/" = {
root = "/var/www";
};
};
};
}

At the moment you still have to restart Nginx after the ACME certs arrive.

Chapter 21. Input Methods

Input methods are an operating system component that allows any data, such as keyboard strokes or mouse movements, to be received as input. In
this way users can enter characters and symbols not found on their input devices. Using an input method is obligatory for any language that has more
graphemes than there are keys on the keyboard.

The following input methods are available in NixOS:

IBus: The intelligent input bus.

Fcitx: A customizable lightweight input method.

Nabi: A Korean input method based on XIM.

Uim: The universal input method, is a library with a XIM bridge.

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

The following snippet can be used to configure IBus:

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

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

Available extra IBus engines are:

Anthy (ibus-engines.anthy): Anthy is a system for Japanese input method. It converts Hiragana text to Kana Kanji mixed text.

Hangul (ibus-engines.hangul): Korean input method.

m17n (ibus-engines.m17n): m17n is an input method that uses input methods and corresponding icons in the m17n database.

mozc (ibus-engines.mozc): A Japanese input method from Google.

Table (ibus-engines.table): An input method that load tables of input methods.

table-others (ibus-engines.table-others): Various table-based input methods. To use this, and any other table-based input methods, it
must appear in the list of engines along with table. For example:

ibus.engines = with pkgs.ibus-engines; [ table table-others ];

To use any input method, the package must be added in the configuration, as shown above, and also (after running nixos-rebuild) the input
method must be added from IBus' preference dialog.
21.2. Fcitx
Fcitx is an input method framework with extension support. It has three built-in Input Method Engine, Pinyin, QuWei and Table-based input methods.

The following snippet can be used to configure Fcitx:

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

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

Available extra Fcitx engines are:

Anthy (fcitx-engines.anthy): Anthy is a system for Japanese input method. It converts Hiragana text to Kana Kanji mixed text.

Chewing (fcitx-engines.chewing): Chewing is an intelligent Zhuyin input method. It is one of the most popular input methods among Tradi
tional Chinese Unix users.

Hangul (fcitx-engines.hangul): Korean input method.

Unikey (fcitx-engines.unikey): Vietnamese input method.

m17n (fcitx-engines.m17n): m17n is an input method that uses input methods and corresponding icons in the m17n database.

mozc (fcitx-engines.mozc): A Japanese input method from Google.

table-others (fcitx-engines.table-others): Various table-based input methods.

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

The following snippet can be used to configure Nabi:

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

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

The following snippet can be used to configure uim:

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

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

Part III. Administration

This chapter describes various aspects of managing a running NixOS system, such as how to use the systemd service manager.
Chapter 22. Service Management
In NixOS, all system services are started and monitored using the systemd program. Systemd is the init process of the system (i.e. PID 1), the parent
of all other processes. It manages a set of so-called units, which can be things like system services (programs), but also mount points, swap files,
devices, targets (groups of units) and more. Units can have complex dependencies; for instance, one unit can require that another unit must be suc
cessfully started before the first unit can be started. When the system boots, it starts a unit named default.target; the dependencies of this unit
cause all system services to be started, file systems to be mounted, swap files to be activated, and so on.

The command systemctl is the main way to interact with systemd. Without any arguments, it shows the status of active units:

$ systemctl
-.mount loaded active mounted /
swapfile.swap loaded active active /swapfile
sshd.service loaded active running SSH Daemon
graphical.target loaded active active Graphical Interface
...

You can ask for detailed status information about a unit, for instance, the PostgreSQL database service:

$ systemctl status postgresql.service

postgresql.service - PostgreSQL Server
Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)
Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago
Main PID: 2390 (postgres)
CGroup: name=systemd:/system/postgresql.service
"#2390 postgres
"#2418 postgres: writer process
"#2419 postgres: wal writer process
"#2420 postgres: autovacuum launcher process
"#2421 postgres: stats collector process
$#2498 postgres: zabbix zabbix [local] idle

Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET
Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections
Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started
Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.

Note that this shows the status of the unit (active and running), all the processes belonging to the service, as well as the most recent log messages
from the service.

Units can be stopped, started or restarted:

# systemctl stop postgresql.service

# systemctl start postgresql.service
# systemctl restart postgresql.service

These operations are synchronous: they wait until the service has finished starting or stopping (or has failed). Starting a unit will cause the dependen
cies of that unit to be started as well (if necessary).

Chapter 23. Rebooting and Shutting Down

The system can be shut down (and automatically powered o) by doing:

# shutdown

This is equivalent to running systemctl powero.

To reboot the system, run

 # reboot

which is equivalent to systemctl reboot. Alternatively, you can quickly reboot the system using kexec, which bypasses the BIOS by directly loading
the new kernel into memory:

# systemctl kexec

The machine can be suspended to RAM (if supported) using systemctl suspend, and suspended to disk using systemctl hibernate.

These commands can be run by any user who is logged in locally, i.e. on a virtual console or in X11; otherwise, the user is asked for authentication.

Chapter 24. User Sessions

Systemd keeps track of all users who are logged into the system (e.g. on a virtual console or remotely via SSH). The command loginctl allows query
ing and manipulating user sessions. For instance, to list all user sessions:

$ loginctl
SESSION UID USER SEAT
c1 500 eelco seat0
c3 0 root seat0
c4 500 alice

This shows that two users are logged in locally, while another is logged in remotely. (Seats are essentially the combinations of displays and input de
vices attached to the system; usually, there is only one seat.) To get information about a session:

$ loginctl session-status c3
c3 - root (0)
Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago
Leader: 2536 (login)
Seat: seat0; vc3
TTY: /dev/tty3
Service: login; type tty; class user
State: online
CGroup: name=systemd:/user/root/c3
"# 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login --
"#10339 -bash
$#10355 w3m nixos.org

This shows that the user is logged in on virtual console 3. It also lists the processes belonging to this session. Since systemd keeps track of this, you
can terminate a session in a way that ensures that all the sessions processes are gone:

# loginctl terminate-session c3

Chapter 25. Control Groups

To keep track of the processes in a running system, systemd uses control groups (cgroups). A control group is a set of processes used to allocate re
sources such as CPU, memory or I/O bandwidth. There can be multiple control group hierarchies, allowing each kind of resource to be managed
independently.

The command systemd-cgls lists all control groups in the systemd hierarchy, which is what systemd uses to keep track of the processes belonging
to each service or user session:
 $ systemd-cgls
"#user
% $#eelco
% $#c1
% "# 2567 -:0
% "# 2682 kdeinit4: kdeinit4 Running...
% "# ...
% $#10851 sh -c less -R
$#system
"#httpd.service
% "#2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH
% $#...
"#dhcpcd.service
% $#2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf
$# ...

Similarly, systemd-cgls cpu shows the cgroups in the CPU hierarchy, which allows per-cgroup CPU scheduling priorities. By default, every systemd
service gets its own CPU cgroup, while all user sessions are in the top-level CPU cgroup. This ensures, for instance, that a thousand run-away pro
cesses in the httpd.service cgroup cannot starve the CPU for one process in the postgresql.service cgroup. (By contrast, it they were in the
same cgroup, then the PostgreSQL process would get 1/1001 of the cgroups CPU time.) You can limit a services CPU share in configura
tion.nix:

systemd.services.httpd.serviceConfig.CPUShares = 512;

By default, every cgroup has 1024 CPU shares, so this will halve the CPU allocation of the httpd.service cgroup.

There also is a memory hierarchy that controls memory allocation limits; by default, all processes are in the top-level cgroup, so any service or session
can exhaust all available memory. Per-cgroup memory limits can be specified in configuration.nix; for instance, to limit httpd.service to 512
MiB of RAM (excluding swap):

systemd.services.httpd.serviceConfig.MemoryLimit = "512M";

The command systemd-cgtop shows a continuously updated list of all cgroups with their CPU and memory usage.

Chapter 26. Logging

System-wide logging is provided by systemds journal, which subsumes traditional logging daemons such as syslogd and klogd. Log entries are kept
in binary files in /var/log/journal/. The command journalctl allows you to see the contents of the journal. For example,

$ journalctl -b

shows all journal entries since the last reboot. (The output of journalctl is piped into less by default.) You can use various options and match opera
tors to restrict output to messages of interest. For instance, to get all messages from PostgreSQL:

$ journalctl -u postgresql.service
-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. --
...
Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down
-- Reboot --
Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET
Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections

Or to get all messages since the last reboot that have at least a critical severity level:

$ journalctl -b -p crit
Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice]
Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (t
otal events = 1)
The system journal is readable by root and by users in the wheel and systemd-journal groups. All users have a private journal that can be read
using journalctl.

Chapter 27. Cleaning the Nix Store

Nix has a purely functional model, meaning that packages are never upgraded in place. Instead new versions of packages end up in a dierent loca
tion in the Nix store (/nix/store). You should periodically run Nixs garbage collector to remove old, unreferenced packages. This is easy:

$ nix-collect-garbage

Alternatively, you can use a systemd unit that does the same in the background:

# systemctl start nix-gc.service

You can tell NixOS in configuration.nix to run this unit automatically at certain points in time, for instance, every night at 03:15:

nix.gc.automatic = true;
nix.gc.dates = "03:15";

The commands above do not remove garbage collector roots, such as old system configurations. Thus they do not remove the ability to roll back to
previous configurations. The following command deletes old roots, removing the ability to roll back to them:

$ nix-collect-garbage -d

You can also do this for specific profiles, e.g.

$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old

Note that NixOS system configurations are stored in the profile /nix/var/nix/profiles/system.

Another way to reclaim disk space (often as much as 40% of the size of the Nix store) is to run Nixs store optimiser, which seeks out identical files in
the store and replaces them with hard links to a single copy.

$ nix-store --optimise

Since this command needs to read the entire Nix store, it can take quite a while to finish.

Chapter 28. Container Management

NixOS allows you to easily run other NixOS instances as containers. Containers are a light-weight approach to virtualisation that runs software in the
container at the same speed as in the host system. NixOS containers share the Nix store of the host, making container creation very ecient.

Warning: Currently, NixOS containers are not perfectly isolated from the host system. This means that a user with root access to the container
can do things that aect the host. So you should not give container root access to untrusted users.

NixOS containers can be created in two ways: imperatively, using the command nixos-container, and declaratively, by specifying them in your con
figuration.nix. The declarative approach implies that containers get upgraded along with your host system when you run nixos-rebuild, which is
often not what you want. By contrast, in the imperative approach, containers are configured and updated independently from the host system.

28.1. Imperative Container Management

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

You create a container with identifier foo as follows:

# nixos-container create foo

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

# nixos-container create foo --config 'services.openssh.enable = true; \

users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N"];'

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

# nixos-container start foo

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

# systemctl status container@foo

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

# nixos-container root-login foo

[root@foo:~]#

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

# nixos-container login foo

foo login: alice
Password: ***

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

# nixos-container run foo -- uname -a

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

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

# nixos-container update foo

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

# nixos-container update foo --config 'services.httpd.enable = true; \

services.httpd.adminAddr = "foo@example.org";'

# curl http://$(nixos-container show-ip foo)/

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

However, note that this will overwrite the containers /etc/nixos/configuration.nix.

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

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

# nixos-container destroy foo

28.2. Declarative Container Specification

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

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

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

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

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

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

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

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

28.3. Container Networking

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

# nixos-container show-ip foo

10.233.4.2

$ ping -c1 10.233.4.2

64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms

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

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

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

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

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

networking.networkmanager.unmanaged = [ "interface-name:ve-*" ];
Chapter 29. Troubleshooting
This chapter describes solutions to common problems you might encounter when you manage your NixOS system.

29.1. Boot Problems

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

boot.shell_on_fail
Start a root shell if something goes wrong in stage 1 of the boot process (the initial ramdisk). This is disabled by default because there is no authenti
cation for the root shell.

boot.debug1
Start an interactive shell in stage 1 before anything useful has been done. That is, no modules have been loaded and no file systems have been
mounted, except for /proc and /sys.

boot.trace
Print every shell command executed by the stage 1 and 2 boot scripts.

single
Boot into rescue mode (a.k.a. single user mode). This will cause systemd to start nothing but the unit rescue.target, which runs sulogin to
prompt for the root password and start a root login shell. Exiting the shell causes the system to continue with the normal boot process.

systemd.log_level=debug systemd.log_target=console
Make systemd very verbose and send log messages to the console instead of the journal.

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

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

29.2. Maintenance Mode

You can enter rescue mode by running:

# systemctl rescue

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

29.3. Rolling Back Configuration Changes

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

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

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

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

# nixos-rebuild switch --rollback

This is equivalent to running:

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

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

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

29.4. Nix Store Corruption

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

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

# nixos-rebuild switch --repair

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

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

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

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

29.5. Network Problems

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

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

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

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

Part IV. Development

This chapter describes how you can modify and extend NixOS.

Chapter 30. Getting the Sources

By default, NixOSs nixos-rebuild command uses the NixOS and Nixpkgs sources provided by the nixos-unstable channel (kept in
/nix/var/nix/profiles/per-user/root/channels/nixos). To modify NixOS, however, you should check out the latest sources from Git.
This is as follows:
 $ git clone git://github.com/NixOS/nixpkgs.git
$ cd nixpkgs
$ git remote add channels git://github.com/NixOS/nixpkgs-channels.git
$ git remote update channels

This will check out the latest Nixpkgs sources to ./nixpkgs the NixOS sources to ./nixpkgs/nixos. (The NixOS source tree lives in a subdirecto
ry of the Nixpkgs repository.) The remote channels refers to a read-only repository that tracks the Nixpkgs/NixOS channels (see Chapter 4, Upgrad
ing NixOS (index.html#sec-upgrading) for more information about channels). Thus, the Git branch channels/nixos-17.03 will contain the latest
built and tested version available in the nixos-17.03 channel.

Its often inconvenient to develop directly on the master branch, since if somebody has just committed (say) a change to GCC, then the binary cache
may not have caught up yet and youll have to rebuild everything from source. So you may want to create a local branch based on your current NixOS
version:

$ nixos-version
17.09pre104379.6e0b727 (Hummingbird)

$ git checkout -b local e3938c8

Or, to base your local branch on the latest version available in a NixOS channel:

$ git remote update channels

$ git checkout -b local channels/nixos-17.03

(Replace nixos-17.03 with the name of the channel you want to use.) You can use git merge or git rebase to keep your local branch in sync with
the channel, e.g.

$ git remote update channels

$ git merge channels/nixos-17.03

You can use git cherry-pick to copy commits from your local branch to the upstream branch.

If you want to rebuild your system using your (modified) sources, you need to tell nixos-rebuild about them using the -I flag:

# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs

If you want nix-env to use the expressions in /my/sources, use nix-env -f /my/sources /nixpkgs, or change the default by adding a symlink in
~/.nix-defexpr:

$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs

You may want to delete the symlink ~/.nix-defexpr/channels_root to prevent roots NixOS channel from clashing with your own tree.

Chapter 31. Writing NixOS Modules

NixOS has a modular system for declarative configuration. This system combines multiple modules to produce the full system configuration. One of
the modules that constitute the configuration is /etc/nixos/configuration.nix. Most of the others live in the nixos/modules (https://github.
com/NixOS/nixpkgs/tree/master/nixos/modules) subdirectory of the Nixpkgs tree.

Each NixOS module is a file that handles one logical aspect of the configuration, such as a specific kind of hardware, a service, or network settings. A
module configuration does not have to handle everything from scratch; it can use the functionality provided by other modules for its implementation.
Thus a module can declare options that can be used by other modules, and conversely can define options provided by other modules in its own im
plementation. For example, the module pam.nix (https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix) declares the op
tion security.pam.services that allows other modules (e.g. sshd.nix (https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/ser
vices/networking/ssh/sshd.nix)) to define PAM services; and it defines the option environment.etc (declared by etc.nix (https://github.
com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix)) to cause files to be created in /etc/pam.d.

In Chapter 5, Configuration Syntax (index.html#sec-configuration-syntax), we saw the following structure of NixOS modules:
 { config, pkgs, ... }:

{ option definitions
}

This is actually an abbreviated form of module that only defines options, but does not declare any. The structure of full NixOS modules is shown in Ex
ample 31.1, Structure of NixOS Modules (index.html#ex-module-syntax).

Example 31.1. Structure of NixOS Modules

{ config, pkgs, ... }:

{
imports =
[ paths of other modules
];

options = {
option declarations
};

config = {
option definitions
};
}

The meaning of each part is as follows.

This line makes the current Nix expression a function. The variable pkgs contains Nixpkgs, while config contains the full system configura
tion. This line can be omitted if there is no reference to pkgs and config inside the module.

This list enumerates the paths to other NixOS modules that should be included in the evaluation of the system configuration. A default set of
modules is defined in the file modules/module-list.nix. These don't need to be added in the import list.

The attribute options is a nested set of option declarations (described below).

The attribute config is a nested set of option definitions (also described below).

Example 31.2, NixOS Module for the locate Service (index.html#locate-example) shows a module that handles the regular update of the locate
database, an index of all files in the file system. This module declares two options that can be defined by other modules (typically the users config
uration.nix): services.locate.enable (whether the database should be updated) and services.locate.interval (when the update
should be done). It implements its functionality by defining two options declared by other modules: systemd.services (the set of all systemd ser
vices) and systemd.timers (the list of commands to be executed periodically by systemd).

Example 31.2. NixOS Module for the locate Service

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

with lib;

let
cfg = config.services.locate;
in {
options.services.locate = {
enable = mkOption {
type = types.bool;
default = false;
description = ''
If enabled, NixOS will periodically update the database of
files used by the locate command.
'';
};

interval = mkOption {
type = types.str;
default = "02:15";
example = "hourly";
description = ''
Update the locate database at this interval. Updates by
default at 2:15 AM every day.

The format is described in

systemd.time(7).
'';
};

# Other options omitted for documentation

};

config = {
systemd.services.update-locatedb =
{ description = "Update Locate Database";
path = [ pkgs.su ];
script =
''
mkdir -m 0755 -p $(dirname ${toString cfg.output})
exec updatedb \
--localuser=${cfg.localuser} \
${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \
--output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags}
'';
};

systemd.timers.update-locatedb = mkIf cfg.enable

{ description = "Update timer for locate database";
partOf = [ "update-locatedb.service" ];
wantedBy = [ "timers.target" ];
timerConfig.OnCalendar = cfg.interval;
};
};
}
31.1. Option Declarations
An option declaration specifies the name, type and description of a NixOS configuration option. It is invalid to define an option that hasnt been de
clared in any module. An option declaration generally looks like this:

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

The function mkOption accepts the following arguments.

type
The type of the option (see Section 31.2, Options Types (index.html#sec-option-types)). It may be omitted, but thats not advisable since it may
lead to errors that are hard to diagnose.

default
The default value used if no value is defined by any module. A default is not required; in that case, if the option value is never used, an error will be
thrown.

example
An example value that will be shown in the NixOS manual.

description
A textual description of the option, in DocBook format, that will be included in the NixOS manual.

31.1.1. Extensible Option Types

Extensible option types is a feature that allow to extend certain types declaration through multiple module files. This feature only work with a restricted
set of types, namely enum and submodules and any composed forms of them.

Extensible option types can be used for enum options that aects multiple modules, or as an alternative to related enable options.

As an example, we will take the case of display managers. There is a central display manager module for generic display manager options and a mod
ule file per display manager backend (slim, sddm, gdm ...).

There are two approach to this module structure:

Managing the display managers independently by adding an enable option to every display manager module backend. (NixOS)

Managing the display managers in the central module by adding an option to select which display manager backend to use.

Both approachs have problems.

Making backends independent can quickly become hard to manage. For display managers, there can be only one enabled at a time, but the type sys
tem can not enforce this restriction as there is no relation between each backend enable option. As a result, this restriction has to be done explicitely
by adding assertions in each display manager backend module.

On the other hand, managing the display managers backends in the central module will require to change the central module option every time a new
backend is added or removed.

By using extensible option types, it is possible to create a placeholder option in the central module (Example 31.3, Extensible type placeholder in the
service module (index.html#ex-option-declaration-eot-service)), and to extend it in each backend module (Example 31.4, Extending ser
vices.xserver.displayManager.enable in the slim module (index.html#ex-option-declaration-eot-backend-slim), Example 31.5, Extending
services.foo.backend in the sddm module (index.html#ex-option-declaration-eot-backend-sddm)).

As a result, displayManager.enable option values can be added without changing the main service module file and the type system automatically
enforce that there can only be a single display manager enabled.

Example 31.3. Extensible type placeholder in the service module

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

Example 31.4. Extending services.xserver.displayManager.enable in the slim module

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

Example 31.5. Extending services.foo.backend in the sddm module

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

The placeholder declaration is a standard mkOption declaration, but it is important that extensible option declarations only use the type argument.

Extensible option types work with any of the composed variants of enum such as with types; nullOr (enum [ "foo" "bar" ]) or
with types; listOf (enum [ "foo" "bar" ]).

31.2. Options Types

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

31.2.1. Basic Types

Basic types are the simplest available types in the module system. Basic types include multiple string types that mainly dier in how definition merging
is handled.

types.bool
A boolean, its values can be true or false.

types.int
An integer.

types.path
A filesystem path, defined as anything that when coerced to a string starts with a slash. Even if derivations can be considered as path, the more spe
cific types.package should be preferred.

types.package
A derivation or a store path.

String related types:

types.str
A string. Multiple definitions cannot be merged.

types.lines
A string. Multiple definitions are concatenated with a new line "\n".

types.commas
 A string. Multiple definitions are concatenated with a comma ",".

types.envVar
A string. Multiple definitions are concatenated with a collon ":".

31.2.2. Value Types

Value types are type that take a value parameter. The only value type in the library is enum.

types.enum l
One element of the list l, e.g. types.enum [ "left" "right" ]. Multiple definitions cannot be merged.

types.separatedString sep
A string with a custom separator sep, e.g. types.separatedString "|".

types.submodule o
A set of sub options o. o can be an attribute set or a function returning an attribute set. Submodules are used in composed types to create modular
options. Submodule are detailed in Section 31.2.4, Submodule (index.html#section-option-types-submodule).

31.2.3. Composed Types

Composed types are types that take a type as parameter. listOf int and either int str are examples of composed types.

types.listOf t
A list of t type, e.g. types.listOf int. Multiple definitions are merged with list concatenation.

types.attrsOf t
An attribute set of where all the values are of t type. Multiple definitions result in the joined attribute set.

types.loaOf t
An attribute set or a list of t type. Multiple definitions are merged according to the value.

types.nullOr t
null or type t. Multiple definitions are merged according to type t.

types.uniq t
Ensures that type t cannot be merged. It is used to ensure option definitions are declared only once.

types.either t1 t2
Type t1 or type t2, e.g. with types; either int str. Multiple definitions cannot be merged.

31.2.4. Submodule
Submodule is a very powerful type that defines a set of sub-options that are handled like a separate module. It is especially interesting when used
with composed types like attrsOf or listOf.

The submodule type take a parameter o, that should be a set, or a function returning a set with an options key defining the sub-options. The option
set can be defined directly (Example 31.6, Directly defined submodule (index.html#ex-submodule-direct)) or as reference (Example 31.7, Submod
ule defined as a reference (index.html#ex-submodule-reference)).

Submodule option definitions are type-checked accordingly to the options declarations. It is possible to declare submodule options inside a submod
ule sub-options for even higher modularity.

Example 31.6. Directly defined submodule

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

Example 31.7. Submodule defined as a reference

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

31.2.4.1. Composed with listOf

When composed with listOf, submodule allows multiple definitions of the submodule option set.

Example 31.8. Declaration of a list of submodules

options.mod = mkOption {
description = "submodule example";
type = with types; listOf (submodule {
options = {
foo = mkOption {
type = int;
};
bar = mkOption {
type = str;
};
};
});
};
Example 31.9. Definition of a list of submodules

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

31.2.4.2. Composed with attrsOf

When composed with attrsOf, submodule allows multiple named definitions of the submodule option set.

Example 31.10. Declaration of attribute sets of submodules

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

Example 31.11. Declaration of attribute sets of submodules

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

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

31.2.5. Extending types

Types are mainly characterized by their check and merge functions.

check
The function to type check the value. Takes a value as parameter and return a boolean. It is possible to extend a type check with the addCheck
function (Example 31.12, Adding a type check (index.html#ex-extending-type-check-1)), or to fully override the check function (Example 31.13,
Overriding a type check (index.html#ex-extending-type-check-2)).

Example 31.12. Adding a type check

byte = mkOption {
description = "An integer between 0 and 255.";
type = addCheck (x: x >= 0 && x <= 255) types.int;
};

Example 31.13. Overriding a type check

 nixThings = mkOption {
description = "words that start with 'nix'";
type = types.str // {
check = (x: lib.hasPrefix "nix" x)
};
};

merge
Function to merge the options values when multiple values are set. The function takes two parameters, loc the option path as a list of strings, and
defs the list of defined values as a list. It is possible to override a type merge function for custom needs.

31.2.6. Custom Types

Custom types can be created with the mkOptionType function. As type creation includes some more complex topics such as submodule handling, it
is recommended to get familiar with types.nix (https://github.com/NixOS/nixpkgs/blob/master/lib/types.nix) code before creat
ing a new type.

The only required parameter is name.

name
A string representation of the type function name.

definition
Description of the type used in documentation. Give information of the type and any of its arguments.

check
A function to type check the definition value. Takes the definition value as a parameter and returns a boolean indicating the type check result, true
for success and false for failure.

merge
A function to merge multiple definitions values. Takes two parameters:

loc
The option path as a list of strings, e.g. ["boot" "loader "grub" "enable"].

defs
The list of sets of defined value and file where the value was defined, e.g.
[ { file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 } ]. The merge function should return the merged value
or throw an error in case the values are impossible or not meant to be merged.

getSubOptions
For composed types that can take a submodule as type parameter, this function generate sub-options documentation. It takes the current option
prefix as a list and return the set of sub-options. Usually defined in a recursive manner by adding a term to the prefix, e.g.
prefix: elemType.getSubOptions (prefix ++ ["prefix"]) where "prefix" is the newly added prefix.

getSubModules
For composed types that can take a submodule as type parameter, this function should return the type parameters submodules. If the type parame
ter is called elemType, the function should just recursively look into submodules by returning elemType.getSubModules;.

substSubModules
For composed types that can take a submodule as type parameter, this function can be used to substitute the parameter of a submodule type. It
takes a module as parameter and return the type with the submodule options substituted. It is usally defined as a type function call with a recursive
call to substSubModules, e.g for a type composedType that take an elemtype type parameter, this function should be defined as
m: composedType (elemType.substSubModules m).

typeMerge
A function to merge multiple type declarations. Takes the type to merge functor as parameter. A null return value means that type cannot be
merged.

f
 The type to merge functor.

Note: There is a generic defaultTypeMerge that work with most of value and composed types.

functor
An attribute set representing the type. It is used for type operations and has the following keys:

type
The type function.

wrapped
Holds the type parameter for composed types.

payload
Holds the value parameter for value types. The types that have a payload are the enum, separatedString and submodule types.

binOp
A binary operation that can merge the payloads of two same types. Defined as a function that take two payloads as parameters and return the pay
loads merged.

31.3. Option Definitions

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

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

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

Delaying Conditionals
If a set of option definitions is conditional on the value of another option, you may need to use mkIf. Consider, for instance:

config = if config.services.httpd.enable then {

environment.systemPackages = [ ... ];
...
} else {};

This definition will cause Nix to fail with an infinite recursion error. Why? Because the value of config.services.httpd.enable depends on the
value being constructed here. After all, you could also write the clearly circular and contradictory:

config = if config.services.httpd.enable then {

services.httpd.enable = false;
} else {
services.httpd.enable = true;
};

The solution is to write:

config = mkIf config.services.httpd.enable {

environment.systemPackages = [ ... ];
...
};

The special function mkIf causes the evaluation of the conditional to be pushed down into the individual definitions, as if you had written:
 config = {
environment.systemPackages = if config.services.httpd.enable then [ ... ] else [];
...
};

Setting Priorities
A module can override the definitions of an option in other modules by setting a priority. All option definitions that do not have the lowest priority value
are discarded. By default, option definitions have priority 1000. You can specify an explicit priority by using mkOverride, e.g.

services.openssh.enable = mkOverride 10 false;

This definition causes all other definitions with priorities above 10 to be discarded. The function mkForce is equal to mkOverride 50.

Merging Configurations
In conjunction with mkIf, it is sometimes useful for a module to return multiple sets of option definitions, to be merged together as if they were de
clared in separate modules. This can be done using mkMerge:

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

31.4. Meta Attributes

Like Nix packages, NixOS modules can declare meta-attributes to provide extra information. Module meta attributes are defined in the
meta.nix (https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/misc/meta.nix) special module.

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

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

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

{
options = {
...
};

config = {
...
};

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

maintainers contains a list of the module maintainers.

 doc points to a valid DocBook file containing the module documentation. Its contents is automatically added to Part II, Configuration (in
dex.html#ch-configuration). Changes to a module documentation have to be checked to not break building the NixOS manual:

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

Chapter 32. Building Specific Parts of NixOS

With the command nix-build, you can build specific parts of your NixOS configuration. This is done as follows:

$ cd /path/to/nixpkgs/nixos
$ nix-build -A config.option

where option is a NixOS option with type derivation (i.e. something that can be built). Attributes of interest include:

system.build.toplevel
The top-level option that builds the entire NixOS system. Everything else in your configuration is indirectly pulled in by this option. This is what
nixos-rebuild builds and what /run/current-system points to afterwards.

A shortcut to build this is:

$ nix-build -A system

system.build.manual.manual
The NixOS manual.

system.build.etc
A tree of symlinks that form the static parts of /etc.

system.build.initialRamdisk
system.build.initialRamdisk, system.build.kernel
The initial ramdisk and kernel of the system. This allows a quick way to test whether the kernel and the initial ramdisk boot correctly, by using
QEMUs -kernel and -initrd options:

$ nix-build -A config.system.build.initialRamdisk -o initrd

$ nix-build -A config.system.build.kernel -o kernel
$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null

system.build.nixos-rebuild
system.build.nixos-rebuild, system.build.nixos-install
system.build.nixos-install, system.build.nixos-generate-config
These build the corresponding NixOS commands.

systemd.units. unit-name .unit

This builds the unit with the specified name. Note that since unit names contain dots (e.g. httpd.service), you need to put them between quotes,
like this:

$ nix-build -A 'config.systemd.units."httpd.service".unit'

You can also test individual units, without rebuilding the whole system, by putting them in /run/systemd/system:

$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
/run/systemd/system/tmp-httpd.service
# systemctl daemon-reload
# systemctl start tmp-httpd.service

Note that the unit must not have the same name as any unit in /etc/systemd/system since those take precedence over /run/systemd/sys
tem. Thats why the unit is installed as tmp-httpd.service here.

Chapter 33. Writing NixOS Documentation

As NixOS grows, so too does the need for a catalogue and explanation of its extensive functionality. Collecting pertinent information from disparate
sources and presenting it in an accessible style would be a worthy contribution to the project.

33.1. Building the Manual

The DocBook sources of the NixOS Manual (index.html) are in the nixos/doc/manual (https://github.com/NixOS/nixpkgs/tree/mas
ter/nixos/doc/manual) subdirectory of the Nixpkgs repository. If you make modifications to the manual, it's important to build it before committing. You
can do that as follows:

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

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

33.2. Editing DocBook XML

For general information on how to write in DocBook, see DocBook 5: The Definitive Guide (http://www.docbook.org/tdg5/en/html/docbook.html).

Emacs nXML Mode is very helpful for editing DocBook XML because it validates the document as you write, and precisely locates errors. To use it,
see Section 16.3.3, Editing DocBook 5 XML Documents (index.html#sec-emacs-docbook-xml).

Pandoc (http://pandoc.org) can generate DocBook XML from a multitude of formats, which makes a good starting point.

Example 33.1. Pandoc invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML

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

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

Sometimes writing valid DocBook is simply too dicult. In this case, submit your documentation updates in a GitHub Issue (https://github.
com/NixOS/nixpkgs/issues/new) and someone will handle the conversion to XML for you.

33.3. Creating a Topic

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

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

The NixOS book (http://www.docbook.org/tdg5/en/html/book.html) element is in nixos/doc/manual/manual.xml. It includes several parts

(http://www.docbook.org/tdg5/en/html/book.html) which are in subdirectories.

Store the topic file in the same directory as the part to which it belongs. If your topic is about configuring a NixOS module, then the XML file can
be stored alongside the module definition nix file.

If you include multiple words in the file name, separate the words with a dash. For example: ipv6-config.xml.

Make sure that the xml:id value is unique. You can use abbreviations if the ID is too long. For example: nixos-config.

Determine whether your topic is a chapter or a section. If you are unsure, open an existing topic file and check whether the main element is chap
ter or section.

33.4. Adding a Topic to the Book

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

If the topic is about configuring a NixOS module, it can be automatically included in the manual by using the meta.doc attribute. See Section 31.4,
Meta Attributes (index.html#sec-meta-attributes) for an explanation.
Chapter 34. Building Your Own NixOS CD
Building a NixOS CD is as easy as configuring your own computer. The idea is to use another module which will replace your configuration.nix
to configure the system that would be installed on the CD.

Default CD/DVD configurations are available inside nixos/modules/installer/cd-dvd. To build them you have to set NIXOS_CONFIG before
running nix-build to build the ISO.

$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix

Before burning your CD/DVD, you can check the content of the image by mounting anywhere like suggested by the following command:

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

Chapter 35. NixOS Tests

When you add some feature to NixOS, you should write a test for it. NixOS tests are kept in the directory nixos/tests (https://github.
com/NixOS/nixpkgs/tree/master/nixos/tests), and are executed (using Nix) by a testing framework that automatically starts one or more
virtual machines containing the NixOS system(s) required for the test.

35.1. Writing Tests

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

import ./make-test.nix {

# Either the configuration of a single machine:

machine =
{ config, pkgs, ... }:
{ configuration
};

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

};

testScript =
''
Perl code
'';
}

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

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

virtualisation.memorySize
 The memory of the VM in megabytes.

virtualisation.vlans
The virtual networks to which the VM is connected. See nat.nix (https://github.com/NixOS/nixpkgs/blob/mas
ter/nixos/tests/nat.nix) for an example.

virtualisation.writableStore
By default, the Nix store in the VM is not writable. If you enable this option, a writable union file system is mounted on top of the Nix store to make it
appear writable. This is necessary for tests that run Nix operations that modify the store.

For more options, see the module

qemu-vm.nix (https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix).

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

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

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

startAll;

The following methods are available on machine objects:

start
Start the virtual machine. This method is asynchronous it does not wait for the machine to finish booting.

shutdown
Shut down the machine, waiting for the VM to exit.

crash
Simulate a sudden power failure, by telling the VM to exit immediately.

block
Simulate unplugging the Ethernet cable that connects the machine to the other machines.

unblock
Undo the eect of block.

screenshot
Take a picture of the display of the virtual machine, in PNG format. The screenshot is linked from the HTML log.

getScreenText
Return a textual representation of what is currently visible on the machine's screen using optical character recognition.

Note: This requires passing enableOCR to the test attribute set.

sendMonitorCommand
Send a command to the QEMU monitor. This is rarely used, but allows doing stu such as attaching virtual USB disks to a running machine.

sendKeys
Simulate pressing keys on the virtual keyboard, e.g., sendKeys("ctrl-alt-delete").

sendChars
Simulate typing a sequence of characters on the virtual keyboard, e.g., sendKeys("foobar\n") will type the string foobar followed by the Enter
key.

execute
 Execute a shell command, returning a list (status, stdout).

succeed
Execute a shell command, raising an exception if the exit status is not zero, otherwise returning the standard output.

fail
Like succeed, but raising an exception if the command returns a zero status.

waitUntilSucceeds
Repeat a shell command with 1-second intervals until it succeeds.

waitUntilFails
Repeat a shell command with 1-second intervals until it fails.

waitForUnit
Wait until the specified systemd unit has reached the active state.

waitForFile
Wait until the specified file exists.

waitForOpenPort
Wait until a process is listening on the given TCP port (on localhost, at least).

waitForClosedPort
Wait until nobody is listening on the given TCP port.

waitForX
Wait until the X11 server is accepting connections.

waitForText
Wait until the supplied regular expressions matches the textual contents of the screen by using optical character recognition (see getScreenText).

Note: This requires passing enableOCR to the test attribute set.

waitForWindow
NixOS
Wait until an X11 window has appeared whose name matches the given regular expression, e.g., waitForWindow(qr/Terminal/).

About (../../../nixos/about.html) Download (../../../nixos/download.html) Support (../../../nixos/support.html)

35.2. Running Tests

Packages (../../../nixos/packages.html) Options (../../../nixos/options.html) Community (../../../nixos/community.html)

You can run tests using nix-build. For example, to run the test login.nix (https://github.com/NixOS/nixpkgs/blob/mas
Security (../../../nixos/security.html)
ter/nixos/tests/login.nix), you just do:

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

or, if you dont want to rely on NIX_PATH:

$ cd /my/nixpkgs/nixos/tests
$ nix-build login.nix

running the VM test script
machine: QEMU running (pid 8841)

6 out of 6 tests succeeded

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

$ firefox result/log.html
35.3. Running Tests interactively
The test itself can be run interactively. This is particularly useful when developing or debugging a test:

$ nix-build nixos/tests/login.nix -A driver

$ ./result/bin/nixos-test-driver
starting VDE switch for network 1
>

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

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

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

To just start and experiment with the VMs, run:

$ nix-build nixos/tests/login.nix -A driver

$ ./result/bin/nixos-run-vms

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

Chapter 36. Testing the Installer

Building, burning, and booting from an installation CD is rather tedious, so here is a quick way to see if the installer works properly:

$ nix-build -A config.system.build.nixos-install
# mount -t tmpfs none /mnt
# ./result/bin/nixos-install

To start a login shell in the new NixOS installation in /mnt:

# ./result/bin/nixos-install --chroot

Chapter 37. Releases

37.1. Release process

Going through an example of releasing NixOS 15.09:

37.1.1. One month before the beta

Send an email to nix-dev mailinglist as a warning about upcoming beta "feature freeze" in a month.

Discuss with Eelco Dolstra and the community (via IRC, ML) about what will reach the deadline. Any issue or Pull Request targeting the release
should have assigned milestone.

37.1.2. At beta release time

Rename rl-unstable.xml -> rl-1509.xml.
 git tag -a -m "Release 15.09-beta" 15.09-beta && git push --tags

From the master branch run git checkout -B release-15.09.

Make sure channel is created at http://nixos.org/channels/. (https://github.com/NixOS/nixos-org-configurations/pull/18)

Lock the branch on github (so developers cant force push) (https://github.com/NixOS/nixpkgs/settings/branches)

bump system.defaultChannel attribute in nixos/modules/misc/version.nix (https://github.com/NixOS/nixpkgs/compare/bd

f161ed8d21...6b63c4616790)

update versionSuffix in nixos/release.nix (https://github.com/NixOS/nixpkgs/commit/d6b08acd1ccac0d9d502c4b635e00b04d3387f06),

use git log --format=%an|wc -l to get commit count

echo -n "16.03" > .version in master.

pick a new name for unstable branch. (https://github.com/NixOS/nixpkgs/commit/b8a4095003e27659092892a4708bb3698231a842)

Create an issue for tracking Zero Hydra Failures progress. ZHF is an eort to get build failures down to zero. (https://github.com/NixOS/nixp
kgs/issues/13559)

Use https://lwn.net/Vulnerabilities/ and triage vulnerabilities in an issue (https://github.com/NixOS/nixpkgs/search?utf8=%E2%9C%93&q=vulner

abilities&type=Issues).

Create two Hydra jobsets: release-15.09 and release-15.09-small with stableBranch set to false

Edit changelog at nixos/doc/manual/release-notes/rl-1509.xml (double check desktop versions are noted)

Get all new NixOS modules git diff release-14.12..release-15.09 nixos/modules/module-list.nix|grep ^+

Note systemd, kernel, glibc and Nix upgrades.

37.1.3. Before the final release

Release Nix (currently only Eelco Dolstra can do that). Make sure fallback is updated. (https://github.com/NixOS/nixpkgs/com
mit/53710c752a85f00658882531bc90a23a3d1287e4)

Update README.md with new stable NixOS version information. (https://github.com/NixOS/nixpkgs/commit/40fd9ae3ac8048758abd

cfc7d28a78b5f22fe97e)

Change stableBranch to true and wait for channel to update.

37.1.4. At final release time

git tag -s -a -m "Release 15.09" 15.09

Update http://nixos.org/nixos/download.html and http://nixos.org/nixos/manual in https://github.com/NixOS/nixos-org-configurations

Get number of commits for the release: git log release-14.04..release-14.12 --format=%an|wc -l

Commits by contributor: git log release-14.04..release-14.12 --format=%an|sort|uniq -c|sort -rn

Send an email to nix-dev to announce the release with above information. Best to check how previous email was formulated to see what needs to
be included.

37.2. Release schedule

Date Event
2016-07-25 Send email to nix-dev about upcoming branch-o
2016-09-01 release-16.09 branch and corresponding jobsets are created, change freeze
2016-09-30 NixOS 16.09 released

Source (https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)