nixpkgs/INSTALL

Setting up and running Nix UML ("nixu")

It is possible to run Nix inside a User Mode Linux environment (UML). The Nix
expressions for this can be found at
https://svn.cs.uu.nl:12443/repos/trace/nixu/.


  Installation on SuSE Linux 9

Download the latest nixpkgs collection and checkout the nixu trunk with
subversion. Install the uml and uml-utilities packages with Nix and run the
"make-disk.sh" script which can be found in nixu. After it has built
everything (or downloaded everything from the nixpkgs cache which can be
used with nix-pull) you can use the "run.sh" script to start the UML.


  Installation on Fedora Core 1

Installing the Nix UML on Fedora Core 1 is a bit tricky. Nix relies on
Berkeley DB and there are issues with Berkeley DB and NPTL kernels (New POSIX
Thread Library) on Red Hat based systems. Since the system we build inside
UML does not use NPTL we cannot use the Nix we use on the host system to
fill the disk once we've booted our the kernel of our UML.

The solution is as follows:

- install all packages via the nix-pull mechanisms with the MANIFEST from
  the official nix-pkgs site to avoid that impure builds link against the
  NPTL glibc on the host system.
- install Nix in Nix
- in the nixu scripts edit make-disk.sh and fill-disk.sh.
  In make-disk.sh prefix all nix-* commands with the absolute path to the
  host-Nix installation bin directory (for example: /nix/bin). In
  fill-disk.sh replace all /nix/bin paths with a relative path to the Nix
  installed with Nix (for example: /usr/home/nix/.nix-profile/bin).

This should fix the installation problems and the Nix UML should boot
flawlessly.


  Nix UML and 2.6 kernel

Installing the current Nix UML packages with a 2.4 kernel on a 2.6
kernel based host system will most likely fail. Linux kernel 2.6 uses NPTL
by default, but UML itself seems to be broken somewhat so halfway the system
seems to hang.

Installing a 2.6 based UML with Nix is not trivial and is not advised.


  Using the Nix UML

By default, the Nix UML comes with very little configuration. Apart from the
networking information and mount information, there is nothing. One of the
first things to do is to add user and group information, otherwise a lot
of tools won't work. There are empty passwd, shadow and group files. Due
to some limitations in Nix it is only possible to modify the password file
as root.

- add a root user:

useradd root

- edit /etc/passwd and change the UID to 0 ("vim" is provided)
- add a root group:

groupadd root


  Adding packages to the UML Nix installation

Packages can be added the the Nix UML installation by editing a few files.
The first file packages should be added to is 'pkgs.nix'. The other files
that should be edited all reside in the "boot" directory. In default.nix
the packages should be added as an argument (first line) and given as an
argument to the builder (line starting with "inherit"). In "builder.sh"
there is a sed expression which subsitutes all occurences of the names of
the packages in the files with the right value. If the programs that are
added need to be added to $PATH the file "env.sh" has to be edited and the
UML has to be recreated.

Another option would be to enable networking in the UML and use nix-pull to
get all the right packages, however this does not work yet.


  Differences with a normal UML

A lot of packages are still missing from the current UML. User management
is completely lacking, init scripts and system configuration (/etc) are
not there yet.