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
mailing list or on the
#nixos
channel on Freenode. Bugs should
be reported in NixOS’ GitHub
issue tracker.
This section describes how to obtain, install, and configure NixOS for first-time use.
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:
Using virtual appliances in Open Virtualization Format (OVF) that can be imported into VirtualBox. These are available from the NixOS download page.
Using AMIs for Amazon’s EC2. To find one for your region and instance type, please refer to the list of most recent AMIs.
Using NixOps, the NixOS-based cloud deployment tool, which allows you to provision VirtualBox and EC2 NixOS instances from declarative specifications. Check out the NixOps homepage for details.
Boot from the CD.
The CD contains a basic NixOS installation. (It also contains Memtest86+, useful if you want to test new hardware). When it’s finished booting, it should have detected most of your hardware.
The NixOS manual is available on virtual console 8 (press Alt+F8 to access).
Login as root
and the empty
password.
If you downloaded the graphical ISO image, you can run start display-manager to start KDE.
The boot process should have brought up networking (check ip a). Networking is necessary for the installer, since it will download lots of stuff (such as source tarballs or Nixpkgs channel binaries). It’s best if you have a DHCP server on your network. Otherwise configure networking manually using ifconfig.
To manually configure the network on the graphical installer, first disable network-manager with systemctl stop network-manager.
The NixOS installer doesn’t do any partitioning or formatting yet, so you need to 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
, since this
makes the file system configuration independent from device
changes. For example:
label
$ mkfs.ext4 -L nixos /dev/sda1
For creating swap partitions:
mkswap. Again it’s 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.
Mount the target file system on which NixOS should
be installed on /mnt
, e.g.
$ mount /dev/disk/by-label/nixos /mnt
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.
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, while a
list of available configuration options appears in Appendix A, Configuration Options. A minimal example is shown in Example 2.2, “NixOS Configuration”.
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
The vim text editor is also available.
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 don’t 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.)
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.
Examples of real-world NixOS configuration files can be found at https://nixos.org/repos/nix/configurations/trunk/.
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: ***
If everything went well:
$ reboot
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 (seeChanging Configuration ), a new item appears in the menu. This allows you to easily roll back to another configuration if something goes wrong.
You should log in and change the root
password with passwd.
You’ll 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
” 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.
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; }
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 manager 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.gummiboot.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.gummiboot
as well.
To see console messages during early boot, add "fbcon"
to your boot.initrd.kernelModules
.
For systems without CD drive, the NixOS livecd can be booted from a usb stick. For non-UEFI installations, unetbootin will work. For UEFI installations, you should 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 documentation on root=
in
the kernel documentation for more details).
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).
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 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:
Stable channels, such as nixos-14.12
.
These only get conservative bug fixes and package upgrades. For
instance, a channel update may cause the Linux kernel on your
system to be upgraded from 3.4.66 to 3.4.67 (a minor bug fix), but
not from 3.4.x
to
3.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
.
This corresponds to NixOS’s main development branch, and may thus
see radical changes between channel updates. It’s not recommended
for production systems.
Small channels, such as nixos-14.12-small
or 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 instance, when a
critical security patch is committed to NixOS’s source tree), but
may require more packages to be built from source than
usual. They’re mostly intended for server environments and as such
contain few GUI applications.
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
.
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 Nix’s database schema. This cannot be undone easily, so in that case you will not be able to go back to your original channel.
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, changes to this file only take
effect after you run nixos-rebuild.
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.
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 ...
}
, where
name
=
value
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.enable
defines a set named
services
that contains a set named
httpd
, which in turn contains an option definition
named enable
with value true
.
This means that the example above can also be written as:
{ config, pkgs, ... }: { services = { httpd = { enable = true; adminAddr = "alice@example.org"; documentRoot = "/webroot"; }; }; }
which may be more convenient if you have lots of option definitions
that share the same prefix (such as
services.httpd
).
NixOS checks your option definitions for correctness. For instance, if you try to define an option that doesn’t exist (that is, doesn’t have a corresponding option declaration), nixos-rebuild will give an error like:
The option `services.httpd.enable' defined in `/etc/nixos/configuration.nix' does not exist.
Likewise, values in option definitions must have a correct type. For
instance, services.httpd.enable
must be a Boolean
(true
or false
). Trying to give
it a value of another type, such as a string, will cause an error:
The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is not a boolean.
Options have various types of values. The most important are:
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 difference is that preceding whitespace is
automatically stripped from each line, and that characters like
"
and \
are not special
(making it more convenient for including things like shell
code).
These can be true
or
false
, e.g.
networking.firewall.enable = true; networking.firewall.allowPing = false;
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 it’s not a
NixOS option but the literal name of a Linux kernel
setting.)
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"; };
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"; } ];
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 NixOS’s PostgreSQL service to 9.0. For more information on packages, including how to add new ones, see Section 6.1.2, “Adding Custom Packages”.
If you find yourself repeating yourself over and over, it’s time to abstract. Take, for instance, this Apache HTTP Server configuration:
{ services.httpd.virtualHosts = [ { 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 difference 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 configuration 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 =
since attributes (as opposed to attribute values) are not
expressions....
; in ...
;
}
Functions provide another method of abstraction. For instance, suppose that we want to generate lots of different virtual hosts, all with identical configuration except for the 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 different documentRoot
for each
virtual host? Then we can make makeVirtualHost
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....
}
The NixOS configuration mechanism is modular. If your
configuration.nix
becomes too big, you can split
it into multiple files. Likewise, if you have multiple NixOS
configurations (e.g. for different computers) with some commonality,
you can move the common configuration into a shared file.
Modules have exactly the same syntax as
configuration.nix
. In fact,
configuration.nix
is itself a module. You can
use other modules by including them from
configuration.nix
, e.g.:
{ config, pkgs, ... }:
{ imports = [ ./vpn.nix ./kde.nix ];
services.httpd.enable = true;
environment.systemPackages = [ pkgs.emacs ];
...
}
Here, we include two modules from the same directory,
vpn.nix
and kde.nix
. The
latter might look like this:
{ config, pkgs, ... }: { services.xserver.enable = true; services.xserver.displayManager.kdm.enable = true; services.xserver.desktopManager.kde4.enable = true; environment.systemPackages = [ pkgs.kde4.kscreensaver ]; }
Note that both configuration.nix
and
kde.nix
define the option
environment.systemPackages
. When multiple modules
define an option, NixOS will try to merge the
definitions. In the case of
environment.systemPackages
, that’s easy: the lists of
packages can simply be concatenated. The value in
configuration.nix
is merged last, so for
list-type options, it will appear at the end of the merged list. If
you want it to appear first, you can use mkBefore
:
boot.kernelModules = mkBefore [ "kvm-intel" ];
This causes the kvm-intel
kernel module to be
loaded before any other kernel modules.
For other types of options, a merge may not be possible. For
instance, if two modules define
services.httpd.adminAddr
,
nixos-rebuild will give an error:
The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc/nixos/httpd.nix' and `/etc/nixos/configuration.nix'.
When that happens, it’s possible to force one definition take precedence over the others:
services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";
When using multiple modules, you may need to access
configuration values defined in other modules. This is what the
config
function argument is for: it contains the
complete, merged system configuration. That is,
config
is the result of combining the
configurations returned by every module[1]. For example, here is a module that adds
some packages to environment.systemPackages
only if
services.xserver.enable
is set to
true
somewhere else:
{ config, pkgs, ... }: { environment.systemPackages = if config.services.xserver.enable then [ pkgs.firefox pkgs.thunderbird ] else [ ]; }
With multiple modules, it may not be obvious what the final
value of a configuration option is. The command
nixos-option
allows you to find out:
$ nixos-option services.xserver.enable
true
$ nixos-option boot.kernelModules
[ "tun" "ipv6" "loop" ...
]
Interactive exploration of the configuration is possible using
nix-repl,
a read-eval-print loop for Nix expressions. It’s not installed by
default; run nix-env -i nix-repl
to get it. A
typical use:
$ nix-repl '<nixos>' nix-repl> config.networking.hostName "mandark" nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts [ "example.org" "example.gov" ]
Below is a summary of the most important syntactic constructs in the Nix expression language. It’s not complete. In particular, there are many other built-in functions. See the Nix manual for the rest.
Example | Description |
---|---|
Basic values | |
"Hello world" | A string |
"${pkgs.bash}/bin/sh" | A string containing an expression (expands to "/nix/store/ ) |
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 |
{ x, y ? "bar" }: x + y | A function that expects a set with required attribute
x and optional y , using
"bar" as default value for
y |
{ x, y, ... }: x + y | A function that expects a set with required attributes
x and y and ignores any
other attributes |
{ x, y } @ args: x + y | A function that expects a set with required attributes
x and y , and binds the
whole set to 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 you’re wondering how it’s possible that the (indirect) result of a function is passed as an input to that same function: that’s because Nix is a “lazy” language — it only computes values when they are needed. This works as long as no individual configuration value depends on itself.
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 different Nixpkgs versions. It’s the only choice for non-root users.
With declarative package management, you specify which packages
you want on your system by setting the option
environment.systemPackages
. For instance, adding the
following line to configuration.nix
enables the
Mozilla Thunderbird email application:
environment.systemPackages = [ pkgs.thunderbird ];
The effect of this specification is that the Thunderbird package from Nixpkgs will be built or downloaded as part of the system when you run nixos-rebuild switch.
You can get a list of the available packages as follows:
$ nix-env -qaP '*' --description
nixos.pkgs.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
...
The first column in the output is the attribute
name, such as
nixos.pkgs.thunderbird
. (The
nixos
prefix allows distinguishing between
different channels that you might have.)
To “uninstall” a package, simply remove it from
environment.systemPackages
and run
nixos-rebuild switch.
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;
Unfortunately, Nixpkgs currently lacks a way to query available configuration options.
Apart from high-level options, it’s 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 necessary
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
overrideDerivation
. While the
override
mechanism above overrides the arguments of
a package function, overrideDerivation
allows
changing the result of the function. 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.lib.overrideDerivation pkgs.emacs (attrs: { name = "emacs-25.0-pre"; src = /path/to/my/emacs/tree; })) ];
Here, overrideDerivation
takes the Nix derivation
specified by pkgs.emacs
and produces a new
derivation in which the original’s name
and
src
attribute have been replaced by the given
values. The original attributes are accessible via
attrs
.
The overrides shown above are not global. They do not affect 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 instances 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 effect 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
original rather than overridden instance, to prevent an infinite
recursion.)
It’s 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 detail in the 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
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!
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.pkgs.thunderbird
If you invoke this as root, the package is installed in the Nix
profile /nix/var/nix/profiles/default
and visible
to all users of the system; otherwise, the package ends up in
/nix/var/nix/profiles/per-user/
and is not visible to other users. The username
/profile-A
flag
specifies the package by its attribute name; without it, the package
is installed by matching against its package name
(e.g. thunderbird
). The latter is slower because
it requires matching against all available Nix packages, and is
ambiguous if there are multiple matching packages.
Packages come from the NixOS channel. You typically upgrade a package by updating to the latest version of the NixOS channel:
$ nix-channel --update nixos
and then running nix-env -i
again. Other packages
in the profile are not affected; this is the
crucial difference with the declarative style of package management,
where running nixos-rebuild switch causes all
packages to be updated to their current versions in the NixOS channel.
You can however upgrade all packages for which there is a newer
version by doing:
$ nix-env -u '*'
A package can be uninstalled using the -e
flag:
$ nix-env -e thunderbird
Finally, you can roll back an undesirable nix-env action:
$ nix-env --rollback
nix-env has many more flags. For details, see the nix-env(1) manpage or the Nix manual.
NixOS supports 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.
NixOS supports file systems that are encrypted using
LUKS (Linux Unified Key Setup). For example,
here is how you create an encrypted Ext4 file system on the device
/dev/sda2
:
$ 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
To ensure that this file system is automatically mounted at boot time
as /
, add the following to
configuration.nix
:
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
NVIDIA provides a proprietary driver for its graphics cards that has better 3D performance than the X.org drivers. It is not enabled by default because it’s not free software. You can enable it as follows:
services.xserver.videoDrivers = [ "nvidia" ];
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 provides a proprietary driver for its graphics cards that has better 3D performance than the X.org drivers. It is not enabled by default because it’s not free software. You can enable it as follows:
services.xserver.videoDrivers = [ "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;
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). For instance, the following enables two-finger scrolling:
services.xserver.synaptics.twoFingerScroll = true;
This section describes how to configure networking components on your NixOS machine.
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.
networking.networkmanager
and
networking.wireless
can not be enabled at the same time:
you can still connect to the wireless networks using
NetworkManager.
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..." ];
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 you’ll also want to set a default gateway and set of name servers:
networking.defaultGateway = "192.168.1.1"; networking.nameservers = [ "8.8.8.8" ];
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.
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;
NixOS has a simple stateful firewall that blocks incoming connections and other unexpected packets. The firewall applies to both IPv4 and IPv6 traffic. It is enabled by default. It can be disabled as follows:
networking.firewall.enable = false;
If the firewall is enabled, you can open specific TCP ports to the outside world:
networking.firewall.allowedTCPPorts = [ 80 443 ];
Note that TCP port 22 (ssh) is opened automatically if the SSH daemon
is enabled (services.openssh.enable = true
). UDP
ports can be opened through
networking.firewall.allowedUDPPorts
. Also of
interest is
networking.firewall.allowPing = true;
to allow the machine to respond to ping requests. (ICMPv6 pings are always allowed.)
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 currently does not generate wpa_supplicant's
configuration file, /etc/wpa_supplicant.conf
. You should edit this file
yourself to define wireless networks, WPA keys and so on (see
wpa_supplicant.conf(5)).
If you are using WPA2 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
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 '';
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.
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 requires a database dump and reload
(see below), NixOS cannot provide a default value for
services.postgresql.package
such as the most recent
release of PostgreSQL.
By default, PostgreSQL stores its databases in
/var/db/postgresql
. You can override this using
services.postgresql.dataDir
, e.g.
services.postgresql.dataDir = "/data/postgresql";
FIXME: document dump/upgrade/load cycle.
FIXME: auto-generated list of module options.
This chapter describes various aspects of managing a running NixOS system, such as how to use the systemd service manager.
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.
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 affect 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 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.
We’ll cover imperative container management using
nixos-container first. You create a container with
identifier foo
as follows:
$ nixos-container create foo
This creates the container’s root directory in
/var/lib/containers/foo
and a small configuration
file in /etc/containers/foo.conf
. It also builds
the container’s initial system configuration and stores it in
/nix/var/nix/profiles/per-container/foo/system
. You
can modify the initial configuration of the container on the command
line. For instance, to create a container that has
sshd running, with the given public key for
root
:
$ nixos-container create foo --config 'services.openssh.enable = true; \ users.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 systemd unit called
container@
.
Thus, if something went wrong, you can get status info using
systemctl:
container-name
.service
$ 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/
,
and run
name
/etc/nixos/configuration.nix
$ 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 container’s
/etc/nixos/configuration.nix
.
Alternatively, you can change the configuration from within the container itself by running nixos-rebuild switch inside the container. Note that the container by default does not have a copy of the NixOS channel, so you should run nix-channel --update first.
Containers can be stopped and started using
nixos-container stop
and nixos-container
start
, respectively, or by using
systemctl on the container’s service unit. To
destroy a container, including its file system, do
$ nixos-container destroy foo
You can also specify containers and their configuration in the
host’s configuration.nix
. For example, the
following specifies that there shall be a container named
database
running PostgreSQL:
containers.database = { config = { config, pkgs, ... }: { services.postgresql.enable = true; services.postgresql.package = pkgs.postgresql92; }; };
If you run nixos-rebuild switch
, the container will
be built and started. If the container was already running, it will be
updated in place, without rebooting.
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
.
Declarative containers can be started and stopped using the
corresponding systemd service, e.g. systemctl start
container@database
.
When you create a container using nixos-container
create
, it gets it own private IPv4 address in the range
10.233.0.0/16
. You can get the container’s IPv4
address as follows:
$ nixos-container show-ip foo 10.233.4.2 $ ping -c1 10.233.4.2 64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms
Networking is implemented using a pair of virtual Ethernet
devices. The network interface in the container is called
eth0
, while the matching interface in the host is
called ve-
(e.g., container-name
ve-foo
). The container has its own network
namespace and the CAP_NET_ADMIN
capability, so it
can perform arbitrary network configuration such as setting up
firewall rules, without affecting or having access to the host’s
network.
By default, containers cannot talk to the outside network. If you want that, you should set up Network Address Translation (NAT) rules on the host to rewrite container traffic to use your external IP address. This can be accomplished using the following configuration on the host:
networking.nat.enable = true; networking.nat.internalInterfaces = ["ve-+"]; networking.nat.externalInterface = "eth0";
where eth0
should be replaced with the desired
external interface. Note that ve-+
is a wildcard
that matches all container interfaces.
This chapter describes solutions to common problems you might encounter when you manage your NixOS system.
If NixOS fails to boot, there are a number of kernel command
line parameters that may help you to identify or fix the issue. You
can add these parameters in the GRUB boot menu by pressing “e” to
modify the selected boot entry and editing the line starting with
linux
. The following are some useful kernel command
line parameters that are recognised by the NixOS boot scripts or by
systemd:
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 authentication 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 you’re lucky, this will start rescue mode (described above). (Also note that since most units have a 90-second timeout before systemd gives up on them, the agetty login prompts should appear eventually unless something is very wrong.)
You can enter rescue mode by running:
$ systemctl rescue
This will eventually give you a single-user root shell. Systemd will stop (almost) all system services. To get out of maintenance mode, just exit from the rescue shell.
After running nixos-rebuild to switch to a new configuration, you may find that the new configuration doesn’t work very well. In that case, there are several ways to return to a previous configuration.
First, the GRUB boot manager allows you to boot into any previous configuration that hasn’t been garbage-collected. These configurations can be found under the GRUB submenu “NixOS - All configurations”. This is especially useful if the new configuration fails to boot. After the system has booted, you can make the selected configuration the default for subsequent boots:
$ /run/current-system/bin/switch-to-configuration boot
Second, you can switch to the previous configuration in a running system:
$ nixos-rebuild switch --rollback
This is equivalent to running:
$ /nix/var/nix/profiles/system-N
-link/bin/switch-to-configuration switch
where N
is the number of the NixOS system
configuration. To get a list of the available configurations, do:
$ ls -l /nix/var/nix/profiles/system-*-link
...
lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
After a system crash, it’s possible for files in the Nix store to become corrupted. (For instance, the Ext4 file system has the tendency to replace un-synced files with zero bytes.) NixOS tries hard to prevent this from happening: it performs a sync before switching to a new configuration, and Nix’s database is fully transactional. If corruption still occurs, you may be able to fix it automatically.
If the corruption is in a path in the closure of the NixOS system configuration, you can fix it by doing
$ nixos-rebuild switch --repair
This will cause Nix to check every path in the closure, and if its cryptographic hash differs from the hash recorded in Nix’s database, the path is rebuilt or redownloaded.
You can also scan the entire Nix store for corrupt paths:
$ nix-store --verify --check-contents --repair
Any corrupt paths will be redownloaded if they’re available in a binary cache; otherwise, they cannot be repaired.
Nix uses a so-called binary cache to
optimise building a package from source into downloading it as a
pre-built binary. That is, whenever a command like
nixos-rebuild needs a path in the Nix store, Nix
will try to download that path from the Internet rather than build it
from source. The default binary cache is
https://cache.nixos.org/
. If this cache is unreachable,
Nix operations may take a long time due to HTTP connection timeouts.
You can disable the use of the binary cache by adding --option
use-binary-caches false
, e.g.
$ nixos-rebuild switch --option use-binary-caches false
If you have an alternative binary cache at your disposal, you can use it instead:
$ nixos-rebuild switch --option binary-caches http://my-cache.example.org/
This chapter describes how you can modify and extend NixOS.
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
and the Nixpkgs sources to
/my/sources
/nixpkgs/nixos
.
(The NixOS source tree lives in a subdirectory of the Nixpkgs
repository.)/my/sources
/nixpkgs
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”.
The meaning of each part is as follows.
This line makes the current Nix expression a function. The
variable | |
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
| |
The attribute | |
The attribute |
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).
Example 22.2. NixOS Module for the “locate” Service
{ 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";
};
}
An option declaration specifies the name, type and description of a NixOS configuration option. It is illegal to define an option that hasn’t been declared in any module. A 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 below). It may be omitted, but that’s 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 ever 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.
Here is a non-exhaustive list of option types:
types.bool
A Boolean.
types.int
An integer.
types.str
A string.
types.lines
A string. If there are multiple definitions, they are concatenated, with newline characters in between.
types.path
A path, defined as anything that, when coerced to a string, starts with a slash. This includes derivations.
types.listOf
t
A list of elements of type t
(e.g., types.listOf types.str
is a list of
strings). Multiple definitions are concatenated together.
types.attrsOf
t
A set of elements of type t
(e.g., types.attrsOf types.int
is a set of
name/value pairs, the values being integers).
types.nullOr
t
Either the value null
or something of
type t
.
You can also create new types using the function
mkOptionType
. See
lib/types.nix
in Nixpkgs for details.
Option definitions are generally straight-forward bindings of values to option names, like
config = { services.httpd.enable = true; };
However, sometimes you need to wrap an option definition or set of option definitions in a property to achieve certain effects:
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 [];...
};
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
.
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 declared in separate modules. This
can be done using mkMerge
:
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:
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.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 QEMU’s -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-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/system
.
That’s why the unit is installed as
tmp-httpd.service
here.
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
This section lists the release notes for each stable version of NixOS and current unstable revision.
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:
Steam now doesn't need root rights to work. Instead of using
*-steam-chrootenv
, you should now just run steam
.
steamChrootEnv
package was renamed to steam
,
and old steam
package -- to steamOriginal
.
CMPlayer has been renamed to bomi upstream. Package cmplayer
was accordingly renamed to bomi
In addition to numerous new and upgraded packages, this release has the following highlights:
Systemd has been updated to version 217, which has numerous improvements.
NixOS is now based on Glibc 2.20.
KDE has been updated to 4.14.
The default Linux kernel has been updated to 3.14.
If users.mutableUsers
is enabled (the
default), changes made to the declaration of a user or group will be
correctly realised when running nixos-rebuild. For
instance, removing a user specification from
configuration.nix
will cause the actual user
account to be deleted. If users.mutableUsers
is
disabled, it is no longer necessary to specify UIDs or GIDs; if
omitted, they are allocated dynamically.
Following new services were added since the last release:
atftpd
bosun
bspwm
chronos
collectd
consul
cpuminer-cryptonight
crashplan
dnscrypt-proxy
docker-registry
docker
etcd
fail2ban
fcgiwrap
fleet
fluxbox
gdm
geoclue2
gitlab
gitolite
gnome3.gnome-documents
gnome3.gnome-online-miners
gnome3.gvfs
gnome3.seahorse
hbase
i2pd
influxdb
kubernetes
liquidsoap
lxc
mailpile
mesos
mlmmj
monetdb
mopidy
neo4j
nsd
openntpd
opentsdb
openvswitch
parallels-guest
peerflix
phd
polipo
prosody
radicale
redmine
riemann
scollector
seeks
siproxd
strongswan
tcsd
teamspeak3
thermald
torque/mrom
torque/server
uhub
unifi
znc
zookeeper
When upgrading from a previous release, please be aware of the following incompatible changes:
The default version of Apache httpd is now 2.4. If
you use the extraConfig
option to pass literal
Apache configuration text, you may need to update it — see Apache’s
documentation for details. If you wish to continue to use
httpd 2.2, add the following line to your NixOS configuration:
services.httpd.package = pkgs.apacheHttpd_2_2;
PHP 5.3 has been removed because it is no longer supported by the PHP project. A migration guide is available.
The host side of a container virtual Ethernet pair
is now called ve-
rather than container-name
c-
.container-name
GNOME 3.10 support has been dropped. The default GNOME version is now 3.12.
VirtualBox has been upgraded to 4.3.20 release. Users
may be required to run rm -rf /tmp/.vbox*. The line
imports = [ <nixpkgs/nixos/modules/programs/virtualbox.nix> ]
is
no longer necessary, use services.virtualboxHost.enable =
true
instead.
Also, hardening mode is now enabled by default, which means that unless you want to use
USB support, you no longer need to be a member of the vboxusers
group.
Chromium has been updated to 39.0.2171.65. enablePepperPDF
is now enabled by default.
chromium*Wrapper
packages no longer exist, because upstream removed NSAPI support.
chromium-stable
has been renamed to chromium
.
Python packaging documentation is now part of nixpkgs manual. To override
the python packages available to a custom python you now use pkgs.pythonFull.buildEnv.override
instead of pkgs.pythonFull.override
.
boot.resumeDevice = "8:6"
is no longer supported. Most users will
want to leave it undefined, which takes the swap partitions automatically. There is an evaluation
assertion to ensure that the string starts with a slash.
The system-wide default timezone for NixOS installations
changed from CET
to UTC
. To choose
a different timezone for your system, configure
time.timeZone
in
configuration.nix
. A fairly complete list of possible
values for that setting is available at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
GNU screen has been updated to 4.2.1, which breaks the ability to connect to sessions created by older versions of screen.
The Intel GPU driver was updated to the 3.x prerelease version (used by most distributions) and supports DRI3 now.
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:
Installation on UEFI systems is now supported. See Section 2.1, “UEFI Installation” for details.
Systemd has been updated to version 212, which has
numerous
improvements. NixOS now automatically starts systemd user
instances when you log in. You can define global user units through
the systemd.unit.*
options.
NixOS is now based on Glibc 2.19 and GCC 4.8.
The default Linux kernel has been updated to 3.12.
KDE has been updated to 4.12.
GNOME 3.10 experimental support has been added.
Nix has been updated to 1.7 (details).
NixOS now supports fully declarative management of
users and groups. 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. If
users.mutableUsers
is true
(the
default), then behaviour is unchanged from NixOS
13.10.
NixOS now has basic container support, meaning you can easily run a NixOS instance as a container in a NixOS host system. These containers are suitable for testing and experimentation but not production use, since they’re not fully isolated from the host. See Chapter 19, Container Management for details.
Systemd units provided by packages can now be
overridden from the NixOS configuration. For instance, if a package
foo
provides systemd units, you can say:
systemd.packages = [ pkgs.foo ];
to enable those units. You can then set or override unit options in the usual way, e.g.
systemd.services.foo.wantedBy = [ "multi-user.target" ]; systemd.services.foo.serviceConfig.MemoryLimit = "512M";
When upgrading from a previous release, please be aware of the following incompatible changes:
Nixpkgs no longer exposes unfree packages by default. If your NixOS configuration requires unfree packages from Nixpkgs, you need to enable support for them explicitly by setting:
nixpkgs.config.allowUnfree = true;
Otherwise, you get an error message such as:
error: package ‘nvidia-x11-331.49-3.12.17’ in ‘…/nvidia-x11/default.nix:56’ has an unfree license, refusing to evaluate
The Adobe Flash player is no longer enabled by default in the Firefox and Chromium wrappers. To enable it, you must set:
nixpkgs.config.allowUnfree = true; nixpkgs.config.firefox.enableAdobeFlash = true; # for Firefox nixpkgs.config.chromium.enableAdobeFlash = true; # for Chromium
The firewall is now enabled by default. If you don’t want this, you need to disable it explicitly:
networking.firewall.enable = false;
The option
boot.loader.grub.memtest86
has been renamed to
boot.loader.grub.memtest86.enable
.
The mysql55
service has been
merged into the mysql
service, which no longer
sets a default for the option
services.mysql.package
.
Package variants are now differentiated by suffixing
the name, rather than the version. For instance,
sqlite-3.8.4.3-interactive
is now called
sqlite-interactive-3.8.4.3
. This ensures that
nix-env -i sqlite
is unambiguous, and that
nix-env -u
won’t “upgrade”
sqlite
to sqlite-interactive
or vice versa. Notably, this change affects the Firefox wrapper
(which provides plugins), as it is now called
firefox-wrapper
. So when using
nix-env, you should do nix-env -e
firefox; nix-env -i firefox-wrapper
if you want to keep
using the wrapper. This change does not affect declarative package
management, since attribute names like
pkgs.firefoxWrapper
were already
unambiguous.
The symlink /etc/ca-bundle.crt
is gone. Programs should instead use the environment variable
OPENSSL_X509_CERT_FILE
(which points to
/etc/ssl/certs/ca-bundle.crt
).
This is the first stable release branch of NixOS.