Table of Contents
List of Examples
This manual describes NixOS, a Linux distribution based on the purely functional package management system Nix.
NixOS is rather bleeding edge, and this manual is
correspondingly sketchy and quite possibly out of date. It gives
basic information on how to get NixOS up and running, but since
NixOS is very much a work in progress, you are likely to encounter
problems here and there. Extensive familiarity with Linux is
recommended. If you encounter problems, please report them on the
nix-dev@cs.uu.nl mailing list or on irc://irc.freenode.net/#trace.
Table of Contents
Instead of building an installation CD, you could just download one from http://nixos.org/nixos/. If you want (or need) to build it yourself:
Make sure that you have a very recent pre-release version of Nix installed (http://nixos.org/releases/nix/nix-unstable/). The NixOS Nix expressions frequently use bleeding-edge features. If you get any kind of expression evaluation error, try to upgrade your Nix.
Optional but strongly recommended (and currently
required for building the
x86_64 ISO): subscribe/pull from the Nixpkgs
channel to speed up building, i.e.,
$ nix-channel --add http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable $ nix-channel --update
Check out NixOS from https://svn.nixos.org/repos/nix/nixos/trunk as
nixos.
If you don’t already have Nixpkgs checkout, Check
out Nixpkgs from https://svn.nixos.org/repos/nix/nixos/trunk as
nixpkgs.
In the directory nixos, make a
symbolic link pkgs to the pkgs
directory of the Nixpkgs tree, e.g.,
$ ln -s nixpkgs/pkgs nixos/
Build the ISO image:
$ nix-build configuration/rescue-cd.nix -A rescueCD
If everything goes well, you’ll end up with an ISO image in
./result/iso/nixos-
that you can burn onto a CD or attach to a virtual CD-ROM drive in
your favourite virtual machine software.version-platform.iso
Boot from the CD.
The CD contains a basic NixOS installation. (It also contain Memtest86+, useful if you want to test new hardware.) When it’s finished booting, it should have detected most of your hardware and brought up networking (check ifconfig). 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 manually.
The NixOS manual is available on virtual console 7 (press Alt+F7 to access).
Login as root, empty
password.
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 Ext2/Ext3 partitions:
mke2fs. Ext3 is recommended; use the
-j to create a journalled file system. It is
also recommended that you assign a unique symbolic label to the
file system using the option -L
. This will make the
file system configuration independent from device
changes.label
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
Possibly you’ll need to do initctl start
lvm after this (TODO: check whether this is
needed).
For creating software RAID devices: mdadm.
Mount the target file system on
/mnt.
The installation is declarative; you need to write a
description of the configuration that you want to be built and
activated. The configuration is specified in a Nix expression and
must be stored on the target file system in
/mnt/etc/nixos/configuration.nix. See
/etc/nixos/nixos/doc/config-examples for
example machine configurations. You can copy and edit one of
those (e.g., copy
/etc/nixos/nixos/doc/config-examples/basic.nix
to /mnt/etc/nixos/configuration.nix). See
??? for a list of the available
configuration options. The text editors nano
and vim are available.
In particular you need to specify a root file system in
fileSystems and the target device for the Grub
boot loader in boot.grubDevice.
The command nixos-hardware-scan can generate an initial configuration file for you, i.e.,
$ mkdir -p /mnt/etc/nixos $ nixos-hardware-scan > /mnt/etc/nixos/configuration.nix
It tries to figure out the modules necessary for mounting the root
device, as well as various other hardware characteristics.
However, it doesn’t try to figure out the
fileSystems option yet.
More examples of NixOS configurations for some actual machines can be found at https://svn.nixos.org/repos/nix/configurations/trunk/.
It is very important that you specify in the option
boot.initrd.extraKernelModules all 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 CD again, mount the target file system on
/mnt, fix
/mnt/etc/nixos/configuration.nix and rerun
nixos-install.)
nixos-hardware-scan should figure out the
required modules in most cases.
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.
Optionally, you can run
$ nixos-checkout
to make the installer use the latest NixOS/Nixpkgs sources from the Subversion repository, rather than the sources on CD.
Do the installation:
$ nixos-install
Cross fingers.
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 (see Section 1.3, “Changing the configuration”), a new item appears in the menu. This allows you to go back easily 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.
Example 1.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 1.2, “NixOS configuration” shows a
corresponding configuration Nix expression.
Example 1.1. Commands for installing NixOS on /dev/sda
$ fdisk /dev/sda (or whatever device you want to install on) $ mke2fs -j -L nixos /dev/sda1 (idem) $ mkswap -L swap /dev/sda2 (idem) $ mount LABEL=nixos /mnt $ mkdir -p /mnt/etc/nixos $ nixos-hardware-scan > /mnt/etc/nixos/configuration.nix $ nano /mnt/etc/nixos/configuration.nix (in particular, set the fileSystems and swapDevices options) $ nixos-install $ reboot
Example 1.2. NixOS configuration
{
boot = {
initrd = {
extraKernelModules = [ "ata_piix" ];
};
grubDevice = "/dev/sda";
};
fileSystems = [
{ mountPoint = "/";
label = "nixos";
}
];
swapDevices = [
{ label = "swap"; }
];
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, or to the NixOS/Nixpkgs sources in
/etc/nixos/nixos and
/etc/nixos/nixpkgs, respectively, you should do
$ nixos-rebuild switch
to build the new configuration, make it the default configuration for booting, and try to effect 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).
Finally, you can do
$ nixos-rebuild build
to build the configuration but nothing more. This is useful to see whether everything compiles cleanly.
The currently best way to keep your NixOS installation up to
date is to track the NixOS Subversion repository. You should replace
the static NixOS/Nixpkgs sources installed in
/etc/nixos with a Subversion checkout. The
program nixos-checkout does that for you (and it
also installs Subversion into your current profile).
To build the latest and greatest, do
$ svn up /etc/nixos/nixos $ svn up /etc/nixos/nixpkgs $ nixos-rebuild switch
(Or instead of switch, use any of the alternatives
shown in Section 1.3, “Changing the configuration”.)
Table of Contents
Compiz Fusion is just a set of plugins fr Compiz. Your best interest is to have them found both by Compiz and by Compiz Configuration Settings (also in Compiz Fusion distribution). By default they look in Compiz installation path and in home directory. You do not need to track /nix/store manually - everything is already in /var/run/current-system/sw/share.
$HOME/.compiz/plugins
should contain plugins you want to load. All the installed
plugins are available in
/var/run/current-system/sw/share/compiz-plugins/compiz/,
so you can use symlinks to this directory.
$HOME/.compiz/metadata
should contain metadata (definition of configuration options) for plugins
you want to load. All the installed metadata is available in
/var/run/current-system/sw/share/compiz/,
so you can use symlinks to this directory.
Probably a way to load GConf configuration backend by default
should be found, but if you run Compiz with
GConf configuration (default for X server job
for now), you have to link
/var/run/current-system/sw/share/compizconfig/backends/
into $HOME/.compizconfig/backends directory.
To summarize the above, these are the commands you have to execute
ln -s /var/run/current-system/sw/share/compiz/ $HOME/.compiz/metadata
ln -s /var/run/current-system/sw/share/compiz-plugins/compiz/ $HOME/.compiz/plugins
ln -s /var/run/current-system/sw/share/compizconfig/backends/ $HOME/.compizconfig/backends
Now you can launch ccsm and configure everything. You should select
GConf as a backend in the preferences menu of ccsm
To have pidgin-latex plugin working after installation, you need the following:
Symlink /var/run/current-system/sw/share/pidgin-latex/pidgin-latex.so
to $HOME/.purple/plugins/pidgin-latex.so
Enable smileys. If you do not want to, you can create
$HOME/.purple/smileys/empty/theme with the following contents:
Name=Empty Description=No predefined smileys Author=Nobody
Enabling this theme will enable smileys, but define none.
Enable the plugin.
Table of Contents
To get a Stage 1 shell (i.e., a shell in the initial ramdisk),
add debug1 to the kernel command line. The shell
gets started 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.
To get a Stage 2 shell (i.e., a shell in the actual root file
system), add debug2 to the kernel command
line. This shell is started right after stage 1 calls the stage 2
init script, so the root file system is there but
no services have been started.
If the hardware autodetection (in
upstart-jobs/hardware-scan) causes problems, add
safemode to the kernel command line. This will
disable auto-loading of modules for your PCI devices. However, you
will probably need to explicitly add modules to
boot.extraKernelModules to get network support
etc.
Table of Contents
This chapter has some random notes on hacking on NixOS.
$ nix-build /etc/nixos/nixos attr
where attr is an attribute in
/etc/nixos/nixos/default.nix. Attributes of interest include:
kernelThe kernel.
initialRamdiskThe initial ramdisk (initrd) for this configuration.
bootStage1The stage 1 (initrd) init script.
bootStage2The stage 2 init script.
etcThe statically computed parts of /etc.
upstartJobsAn attribute set containing the Upstart jobs. For
instance, the sshd Upstart job can be built by
doing nix-build /etc/nixos/nixos -A
upstartJobs.sshd.
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 .../nixos/configuration/rescue-cd.nix -A system.nixosInstall $ dd if=/dev/zero of=diskimage seek=2G count=0 bs=1 $ yes | mke2fs -j diskimage $ mount -o loop diskimage /mnt $ ./result/bin/nixos-install
A quick way to test whether the kernel and the initial ramdisk
boot correctly is to use QEMU’s -kernel and
-initrd options:
$ nix-build /etc/nixos/nixos -A initialRamdisk -o initrd $ nix-build /etc/nixos/nixos -A kernel -o kernel $ qemu-system-x86_64 -kernel ./kernel/vmlinuz -initrd ./initrd/initrd -hda /dev/null