NixOS ISO images can be downloaded from the NixOS download page. There are a number of installation options. 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 people 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 difficulty a number of alternative methods are presented in the NixOS Wiki.

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

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

$ 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

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

The file /etc/nixos/configuration.nix contains the current configuration of your machine. Whenever you’ve changed something to 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 restarting system services).

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 machine, 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 effect after the next reboot).

You can make your configuration show up in a different submenu of the GRUB 2 boot screen by giving it a different 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 virtual 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

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 expressions and associated binaries. The NixOS channels are updated automatically from NixOS’s Git repository after certain tests have passed and all packages have been built. These channels are:

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

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

$ nix-channel --list | grep nixos
nixos https://nixos.org/channels/nixos-unstable

To switch to a different 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 14.12 stable channel:

$ nix-channel --add https://nixos.org/channels/nixos-14.12 nixos

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

$ nix-channel --add https://nixos.org/channels/nixos-14.12-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.

The NixOS configuration file /etc/nixos/configuration.nix is actually a Nix expression, which is the Nix package manager’s 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, but here we give a short overview of the most important constructs useful in NixOS configuration files.

{ config, pkgs, ... }:

{ option definitions
}

{ config, pkgs, ... }:

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

{ config, pkgs, ... }:

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

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

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

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

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

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

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

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

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

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

{ config, pkgs, ... }:

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

{ config, pkgs, ... }:

{ services.xserver.enable = true;
  services.xserver.displayManager.kdm.enable = true;
  services.xserver.desktopManager.kde4.enable = true;
  environment.systemPackages = [ pkgs.kde4.kscreensaver ];
}

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

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

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

{ config, pkgs, ... }:

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

$ nixos-option services.xserver.enable
true

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

$ nix-repl '<nixos>'

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

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

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

environment.systemPackages = [ pkgs.thunderbird ];

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

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

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

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

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

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

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

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

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

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

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

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

$ nix-env -iA nixos.pkgs.thunderbird

$ nix-channel --update nixos

$ nix-env -u '*'

$ nix-env -e thunderbird

$ nix-env --rollback

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

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 it’s 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

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 user’s home directory. Accounts can be modified using usermod. Unix groups can be managed using groupadd, groupmod and groupdel.

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 don’t already exist. For device, it’s best to use the topology-independent device aliases in /dev/disk/by-label and /dev/disk/by-uuid, as these don’t 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 it’s best to specify fsType to ensure that the kernel module is available.

$ cryptsetup luksFormat /dev/sda2

WARNING!
========
This will overwrite data on /dev/sda2 irrevocably.

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

$ cryptsetup luksOpen /dev/sda2 crypted
Enter passphrase for /dev/sda2: ***

$ mkfs.ext4 /dev/mapper/crypted

boot.initrd.luks.devices = [ { device = "/dev/sda2"; name = "crypted"; } ];
fileSystems."/".device = "/dev/mapper/crypted";

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.org’s 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.kde4.enable = true;
services.xserver.desktopManager.xfce.enable = true;
services.xserver.windowManager.xmonad.enable = true;
services.xserver.windowManager.twm.enable = true;
services.xserver.windowManager.icewm.enable = true;

NixOS’s default display manager (the program that provides a graphical login prompt and manages the X server) is SLiM. You can select KDE’s kdm instead:

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

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

services.xserver.autorun = false;

The X server can then be started manually:

$ systemctl start display-manager.service

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

hardware.opengl.driSupport32Bit = true;

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

hardware.opengl.driSupport32Bit = true;

services.xserver.synaptics.enable = true;

services.xserver.synaptics.twoFingerScroll = true;

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

networking.networkmanager.enable = true;

services.openssh.enable = true;

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

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

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

networking.hostName = "cartman";

networking.enableIPv6 = false;

networking.firewall.enable = false;

networking.firewall.allowedTCPPorts = [ 80 443 ];

networking.firewall.allowPing = true;

networking.wireless.enable = true;

$ wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf

$ systemctl restart wpa_supplicant.service

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

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:

cat /proc/config.gz | gunzip

If you want to change the kernel configuration, you can use the packageOverrides feature (see Section 6.1.1, “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 option 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 kernel’s TCP keepalive time to 120 seconds. To see the available parameters, run sysctl -a.

Source: modules/services/databases/postgresql.nix

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

PostgreSQL is an advanced, free relational database.

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

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

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 successfully 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 dependencies of that unit to be started as well (if necessary).

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

$ shutdown

This is equivalent to running systemctl poweroff.

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.

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 querying 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 devices 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 session’s processes are gone:

$ loginctl terminate-session c3

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 resources 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 processes 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 cgroup’s CPU time.) You can limit a service’s CPU share in configuration.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.

System-wide logging is provided by systemd’s 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 operators 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 (total 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.

Nix has a purely functional model, meaning that packages are never upgraded in place. Instead new versions of packages end up in a different location in the Nix store (/nix/store). You should periodically run Nix’s 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 Nix’s 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.

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

NixOS containers can be created in two ways: imperatively, using the command nixos-container, and declaratively, by specifying them in your configuration.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.

$ nixos-container create foo

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

$ nixos-container start foo

$ systemctl status container@foo

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

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

$ 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

$ nixos-container update foo

$ 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">…

$ nixos-container destroy foo

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

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

$ 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.nat.enable = true;
networking.nat.internalInterfaces = ["ve-+"];
networking.nat.externalInterface = "eth0";

This chapter describes solutions to common problems you might encounter when you manage your NixOS system.

$ systemctl rescue

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

$ nixos-rebuild switch --rollback

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

$ 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

$ nixos-rebuild switch --repair

$ nix-store --verify --check-contents --repair

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

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

By default, NixOS’s 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 done using the following command:

$ nixos-checkout /my/sources

or

$ mkdir -p /my/sources
$ cd /my/sources
$ nix-env -i git
$ git clone git://github.com/NixOS/nixpkgs.git

This will check out the latest NixOS sources to /my/sources/nixpkgs/nixos and the Nixpkgs sources to /my/sources/nixpkgs. (The NixOS source tree lives in a subdirectory of the Nixpkgs repository.)

It’s 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 you’ll have to rebuild everything from source. So you may want to create a local branch based on your current NixOS version:

$ /my/sources/nixpkgs/maintainers/scripts/update-channel-branches.sh
Fetching channels from https://nixos.org/channels:
 * [new branch]      cbe467e           -> channels/remotes/nixos-unstable
Fetching channels from nixos-version:
 * [new branch]      9ff4738           -> channels/current-system
Fetching channels from ~/.nix-defexpr:
 * [new branch]      0d4acad           -> channels/root/nixos
$ git checkout -b local channels/current-system

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

$ /my/sources/nixpkgs/maintainers/scripts/update-channel-branches.sh
$ git checkout -b local channels/remotes/nixos-unstable

You can then use git rebase to sync your local branch with the upstream branch, and 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 root’s NixOS channel from clashing with your own tree.

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 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 implementation. For example, the module pam.nix declares the option security.pam.services that allows other modules (e.g. sshd.nix) to define PAM services; and it defines the option environment.etc (declared by etc.nix) to cause files to be created in /etc/pam.d.

In Chapter 5, 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 Example 22.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.

Example 22.2, “NixOS Module for the “locate” Service” 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 user’s configuration.nix): services.locate.enable (whether the database should be updated) and services.locate.period (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 services) and services.cron.systemCronJobs (the list of commands to be executed periodically by cron).

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

with lib;

let locatedb = "/var/cache/locatedb"; 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.
        '';
      };

      period = mkOption {
        type = types.str;
        default = "15 02 * * *";
        description = ''
          This option defines (in the format used by cron) when the
          locate database is updated.  The default is to update at
          02:15 at night every day.
        '';
      };

    };

  };

  config = {

    systemd.services.update-locatedb =
      { description = "Update Locate Database";
        path  = [ pkgs.su ];
        script =
          ''
            mkdir -m 0755 -p $(dirname ${locatedb})
            exec updatedb --localuser=nobody --output=${locatedb} --prunepaths='/tmp /var/tmp /media /run'
          '';
      };

    services.cron.systemCronJobs = optional config.services.locate.enable
      "${config.services.locate.period} root ${config.systemd.package}/bin/systemctl start update-locatedb.service";

  };
}

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

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

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

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

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

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

services.openssh.enable = mkOverride 10 false;

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

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:

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

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

In addition to numerous new and upgraded packages, this release has the following highlights:

Following new services were added since the last release:

When upgrading from a previous release, please be aware of the following incompatible changes:

In addition to numerous new and upgraded packages, this release has the following highlights:

Following new services were added since the last release:

When upgrading from a previous release, please be aware of the following incompatible changes:

This is the second stable release branch of NixOS. In addition to numerous new and upgraded packages and modules, this release has the following highlights:

When upgrading from a previous release, please be aware of the following incompatible changes:

This is the first stable release branch of NixOS.