Move all of NixOS to nixos/ in preparation of the repository merge

20 files changed, 3796 insertions, 0 deletions

diff --git a/nixos/doc/config-examples/basic.nix b/nixos/doc/config-examples/basic.nix
new file mode 100644
index 00000000000..da37cfb8c28
--- /dev/null
+++ b/nixos/doc/config-examples/basic.nix
@@ -0,0 +1,21 @@
+{
+  boot = {
+    loader.grub.device = "/dev/sda";
+  };
+
+  fileSystems = [
+    { mountPoint = "/";
+      device = "/dev/sda1";
+    }
+  ];
+
+  swapDevices = [
+    { device = "/dev/sdb1"; }
+  ];
+
+  services = {
+    openssh = {
+      enable = true;
+    };
+  };
+}
diff --git a/nixos/doc/config-examples/closed-install-configuration.nix b/nixos/doc/config-examples/closed-install-configuration.nix
new file mode 100644
index 00000000000..0cebacdb0cc
--- /dev/null
+++ b/nixos/doc/config-examples/closed-install-configuration.nix
@@ -0,0 +1,32 @@
+{
+  boot = {
+    loader.grub.device = "/dev/sda";
+    copyKernels = true;
+    bootMount = "(hd0,0)";
+  };
+
+  fileSystems = [
+    { mountPoint = "/";
+      device = "/dev/sda3";
+    }
+    { mountPoint = "/boot";
+      device = "/dev/sda1";
+      neededForBoot = true;
+    }
+  ];
+
+  swapDevices = [
+    { device = "/dev/sda2"; }
+  ];
+
+  services = {
+    sshd = {
+      enable = true;
+    };
+  };
+
+  fonts = {
+    enableFontConfig = false;
+  };
+
+}
diff --git a/nixos/doc/config-examples/root-on-lvm.nix b/nixos/doc/config-examples/root-on-lvm.nix
new file mode 100644
index 00000000000..2ea1e547921
--- /dev/null
+++ b/nixos/doc/config-examples/root-on-lvm.nix
@@ -0,0 +1,27 @@
+# This configuration has / on a LVM volume.  Since Grub
+# doesn't know about LVM, a separate /boot is therefore
+# needed.
+#
+# In this example, labels are used for file systems and
+# swap devices: "boot" might be /dev/sda1, "root" might be
+# /dev/my-volume-group/root, and "swap" might be /dev/sda2.
+# In particular there is no specific reference to the fact
+# that / is on LVM; that's figured out automatically.
+
+{
+  boot.loader.grub.device = "/dev/sda";
+  boot.initrd.kernelModules = ["ata_piix"];
+
+  fileSystems = [
+    { mountPoint = "/";
+      label = "root";
+    }
+    { mountPoint = "/boot";
+      label = "boot";
+    }
+  ];
+
+  swapDevices = [
+    { label = "swap"; }
+  ];
+}
diff --git a/nixos/doc/config-examples/svn-server.nix b/nixos/doc/config-examples/svn-server.nix
new file mode 100644
index 00000000000..e727007117b
--- /dev/null
+++ b/nixos/doc/config-examples/svn-server.nix
@@ -0,0 +1,36 @@
+{
+  boot = {
+    loader.grub.device = "/dev/sda";
+  };
+
+  fileSystems = [
+    { mountPoint = "/";
+      device = "/dev/sda1";
+    }
+  ];
+
+  services = {
+
+    sshd = {
+      enable = true;
+    };
+
+    httpd = {
+      enable = true;
+      adminAddr = "admin@example.org";
+
+      subservices = {
+
+        subversion = {
+          enable = true;
+          dataDir = "/data/subversion";
+          notificationSender = "svn@example.org";
+        };
+
+      };
+
+    };
+
+  };
+
+}
diff --git a/nixos/doc/config-examples/x86_64-usbstick.nix b/nixos/doc/config-examples/x86_64-usbstick.nix
new file mode 100644
index 00000000000..374d3ba3bc7
--- /dev/null
+++ b/nixos/doc/config-examples/x86_64-usbstick.nix
@@ -0,0 +1,20 @@
+# Configuration file used to install NixOS-x86_64 on a USB stick.
+
+{
+  boot = {
+    loader.grub.device = "/dev/sda";
+    initrd = {
+      kernelModules = ["usb_storage" "ehci_hcd" "ohci_hcd"];
+    };
+  };
+
+  fileSystems = [
+    { mountPoint = "/";
+      label = "nixos-usb";
+    }
+  ];
+
+  fonts = {
+    enableFontConfig = false;
+  };
+}
diff --git a/nixos/doc/manual/configuration.xml b/nixos/doc/manual/configuration.xml
new file mode 100644
index 00000000000..965ba73105a
--- /dev/null
+++ b/nixos/doc/manual/configuration.xml
@@ -0,0 +1,810 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="ch-configuration">
+
+<title>Configuring NixOS</title>
+
+<para>This chapter describes how to configure various aspects of a
+NixOS machine through the configuration file
+<filename>/etc/nixos/configuration.nix</filename>.  As described in
+<xref linkend="sec-changing-config" />, changes to that file only take
+effect after you run <command>nixos-rebuild</command>.</para>
+
+
+<!--===============================================================-->
+
+<section><title>Package management</title>
+
+<para>This section describes how to add additional packages to your
+system.  NixOS has two distinct styles of package management:
+
+<itemizedlist>
+
+  <listitem><para><emphasis>Declarative</emphasis>, where you declare
+  what packages you want in your
+  <filename>configuration.nix</filename>.  Every time you run
+  <command>nixos-rebuild</command>, NixOS will ensure that you get a
+  consistent set of binaries corresponding to your
+  specification.</para></listitem>
+
+  <listitem><para><emphasis>Ad hoc</emphasis>, where you install,
+  upgrade and uninstall packages via the <command>nix-env</command>
+  command.  This style allows mixing packages from different Nixpkgs
+  versions.  It’s the only choice for non-root
+  users.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>The next two sections describe these two styles.</para>
+
+
+<section><title>Declarative package management</title>
+
+<para>With declarative package management, you specify which packages
+you want on your system by setting the option
+<option>environment.systemPackages</option>.  For instance, adding the
+following line to <filename>configuration.nix</filename> enables the
+Mozilla Thunderbird email application:
+
+<programlisting>
+environment.systemPackages = [ pkgs.thunderbird ];
+</programlisting>
+
+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
+<command>nixos-rebuild switch</command>.</para>
+
+<para>You can get a list of the available packages as follows:
+<screen>
+$ nix-env -qaP '*' --description
+nixos.pkgs.firefox   firefox-23.0   Mozilla Firefox - the browser, reloaded
+<replaceable>...</replaceable>
+</screen>
+
+The first column in the output is the <emphasis>attribute
+name</emphasis>, such as
+<literal>nixos.pkgs.thunderbird</literal>. (The
+<literal>nixos</literal> prefix allows distinguishing between
+different channels that you might have.)</para>
+
+<para>To “uninstall” a package, simply remove it from
+<option>environment.systemPackages</option> and run
+<command>nixos-rebuild switch</command>.</para>
+
+
+<section xml:id="sec-customising-packages"><title>Customising packages</title>
+
+<para>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
+<filename>configuration.nix</filename> as follows:
+
+<filename>
+nixpkgs.config.firefox.enableGoogleTalkPlugin = true;
+</filename>
+</para>
+
+<warning><para>Unfortunately, Nixpkgs currently lacks a way to query
+available configuration options.</para></warning>
+
+<para>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:
+
+<programlisting>
+environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+</programlisting>
+
+The function <varname>override</varname> 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
+<varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>,
+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,
+<literal>environment.systemPackages</literal> would be a list with two
+elements.)</para>
+
+<para>Even greater customisation is possible using the function
+<varname>overrideDerivation</varname>.  While the
+<varname>override</varname> mechanism above overrides the arguments of
+a package function, <varname>overrideDerivation</varname> allows
+changing the <emphasis>result</emphasis> 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:
+
+<programlisting>
+environment.systemPackages =
+  [ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: {
+      name = "emacs-25.0-pre";
+      src = /path/to/my/emacs/tree;
+    }))
+  ];
+</programlisting>
+
+Here, <varname>overrideDerivation</varname> takes the Nix derivation
+specified by <varname>pkgs.emacs</varname> and produces a new
+derivation in which the original’s <literal>name</literal> and
+<literal>src</literal> attribute have been replaced by the given
+values.  The original attributes are accessible via
+<varname>attrs</varname>.</para>
+
+<para>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
+<emphasis>global</emphasis> override as follows:
+
+<screen>
+nixpkgs.config.packageOverrides = pkgs:
+  { emacs = pkgs.emacs.override { gtk = pkgs.gtk3; };
+  };
+</screen>
+
+The effect of this definition is essentially equivalent to modifying
+the <literal>emacs</literal> attribute in the Nixpkgs source tree.
+Any package in Nixpkgs that depends on <literal>emacs</literal> will
+be passed your customised instance.  (However, the value
+<literal>pkgs.emacs</literal> in
+<varname>nixpkgs.config.packageOverrides</varname> refers to the
+original rather than overriden instance, to prevent an infinite
+recursion.)</para>
+
+</section>
+
+<section><title>Adding custom packages</title>
+
+<para>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 <link
+xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs manual</link>.
+In short, you clone Nixpkgs:
+
+<screen>
+$ git clone git://github.com/NixOS/nixpkgs.git
+$ cd nixpkgs
+</screen>
+
+Then you write and test the package as described in the Nixpkgs
+manual.  Finally, you add it to
+<literal>environment.systemPackages</literal>, e.g.
+
+<programlisting>
+environment.systemPackages = [ pkgs.my-package ];
+</programlisting>
+
+and you run <command>nixos-rebuild</command>, specifying your own
+Nixpkgs tree:
+
+<screen>
+$ nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
+
+</para>
+
+<para>The second possibility is to add the package outside of the
+Nixpkgs tree.  For instance, here is how you specify a build of the
+<link xlink:href="http://www.gnu.org/software/hello/">GNU Hello</link>
+package directly in <filename>configuration.nix</filename>:
+
+<programlisting>
+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 ];
+</programlisting>
+
+Of course, you can also move the definition of
+<literal>my-hello</literal> into a separate Nix expression, e.g.
+<programlisting>
+environment.systemPackages = [ (import ./my-hello.nix) ];
+</programlisting>
+where <filename>my-hello.nix</filename> contains:
+<programlisting>
+with &lt;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";
+  };
+}
+</programlisting>
+
+This allows testing the package easily:
+<screen>
+$ nix-build my-hello.nix
+$ ./result/bin/hello
+Hello, world!
+</screen>
+
+</para>
+
+</section>
+
+</section>
+
+
+<section><title>Ad hoc package management</title>
+
+<para>With the command <command>nix-env</command>, you can install and
+uninstall packages from the command line.  For instance, to install
+Mozilla Thunderbird:
+
+<screen>
+$ nix-env -iA nixos.pkgs.thunderbird</screen>
+
+If you invoke this as root, the package is installed in the Nix
+profile <filename>/nix/var/nix/profiles/default</filename> and visible
+to all users of the system; otherwise, the package ends up in
+<filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/profile</filename>
+and is not visible to other users.  The <option>-A</option> flag
+specifies the package by its attribute name; without it, the package
+is installed by matching against its package name
+(e.g. <literal>thunderbird</literal>).  The latter is slower because
+it requires matching against all available Nix packages, and is
+ambiguous if there are multiple matching packages.</para>
+
+<para>Packages come from the NixOS channel.  You typically upgrade a
+package by updating to the latest version of the NixOS channel:
+<screen>
+$ nix-channel --update nixos
+</screen>
+and then running <literal>nix-env -i</literal> again.  Other packages
+in the profile are <emphasis>not</emphasis> affected; this is the
+crucial difference with the declarative style of package management,
+where running <command>nixos-rebuild switch</command> 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:
+<screen>
+$ nix-env -u '*'
+</screen>
+</para>
+
+<para>A package can be uninstalled using the <option>-e</option>
+flag:
+<screen>
+$ nix-env -e thunderbird
+</screen>
+</para>
+
+<para>Finally, you can roll back an undesirable
+<command>nix-env</command> action:
+<screen>
+$ nix-env --rollback
+</screen>
+</para>
+
+<para><command>nix-env</command> has many more flags.  For details,
+see the
+<citerefentry><refentrytitle>nix-env</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+manpage or the Nix manual.</para>
+
+</section>
+
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>User management</title>
+
+<para>NixOS supports both declarative and imperative styles of user
+management.  In the declarative style, users are specified in
+<filename>configuration.nix</filename>.  For instance, the following
+states that a user account named <literal>alice</literal> shall exist:
+
+<programlisting>
+users.extraUsers.alice =
+  { createHome = true;
+    home = "/home/alice";
+    description = "Alice Foobar";
+    extraGroups = [ "wheel" ];
+    isSystemUser = false;
+    useDefaultShell = true;
+    openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
+  };
+</programlisting>
+
+Note that <literal>alice</literal> is a member of the
+<literal>wheel</literal> group, which allows her to use
+<command>sudo</command> to execute commands as
+<literal>root</literal>.  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
+<command>passwd</command> program to set a password, which is retained
+across invocations of <command>nixos-rebuild</command>.</para>
+
+<para>A user ID (uid) is assigned automatically.  You can also specify
+a uid manually by adding
+
+<programlisting>
+    uid = 1000;
+</programlisting>
+
+to the user specification.</para>
+
+<para>Groups can be specified similarly.  The following states that a
+group named <literal>students</literal> shall exist:
+
+<programlisting>
+users.extraGroups.students.gid = 1000;
+</programlisting>
+
+As with users, the group ID (gid) is optional and will be assigned
+automatically if it’s missing.</para>
+
+<warning><para>Currently declarative user management is not perfect:
+<command>nixos-rebuild</command> does not know how to realise certain
+configuration changes.  This includes removing a user or group, and
+removing group membership from a user.</para></warning>
+
+<para>In the imperative style, users and groups are managed by
+commands such as <command>useradd</command>,
+<command>groupmod</command> and so on.  For instance, to create a user
+account named <literal>alice</literal>:
+
+<screen>
+$ useradd -m alice</screen>
+
+The flag <option>-m</option> 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 <command>passwd</command> utility:
+
+<screen>
+$ passwd alice
+Enter new UNIX password: ***
+Retype new UNIX password: ***
+</screen>
+
+A user can be deleted using <command>userdel</command>:
+
+<screen>
+$ userdel -r alice</screen>
+
+The flag <option>-r</option> deletes the user’s home directory.
+Accounts can be modified using <command>usermod</command>.  Unix
+groups can be managed using <command>groupadd</command>,
+<command>groupmod</command> and <command>groupdel</command>.</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>File systems</title>
+
+<para>You can define file systems using the
+<option>fileSystems</option> configuration option.  For instance, the
+following definition causes NixOS to mount the Ext4 file system on
+device <filename>/dev/disk/by-label/data</filename> onto the mount
+point <filename>/data</filename>:
+
+<programlisting>
+fileSystems."/data" =
+  { device = "/dev/disk/by-label/data";
+    fsType = "ext4";
+  };
+</programlisting>
+
+Mount points are created automatically if they don’t already exist.
+For <option>device</option>, it’s best to use the topology-independent
+device aliases in <filename>/dev/disk/by-label</filename> and
+<filename>/dev/disk/by-uuid</filename>, as these don’t change if the
+topology changes (e.g. if a disk is moved to another IDE
+controller).</para>
+
+<para>You can usually omit the file system type
+(<option>fsType</option>), since <command>mount</command> 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 <literal>ext2</literal>, <literal>ext3</literal>
+or <literal>ext4</literal>, then it’s best to specify
+<option>fsType</option> to ensure that the kernel module is
+available.</para>
+
+<section><title>LUKS-encrypted file systems</title>
+
+<para>NixOS supports file systems that are encrypted using
+<emphasis>LUKS</emphasis> (Linux Unified Key Setup).  For example,
+here is how you create an encrypted Ext4 file system on the device
+<filename>/dev/sda2</filename>:
+
+<screen>
+$ 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
+</screen>
+
+To ensure that this file system is automatically mounted at boot time
+as <filename>/</filename>, add the following to
+<filename>configuration.nix</filename>:
+
+<programlisting>
+boot.initrd.luks.devices = [ { device = "/dev/sda2"; name = "crypted"; } ];
+fileSystems."/".device = "/dev/mapper/crypted";
+</programlisting>
+
+</para>
+
+</section>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>X Window System</title>
+
+<para>The X Window System (X11) provides the basis of NixOS’ graphical
+user interface.  It can be enabled as follows:
+<programlisting>
+services.xserver.enable = true;
+</programlisting>
+The X server will automatically detect and use the appropriate video
+driver from a set of X.org drivers (such as <literal>vesa</literal>
+and <literal>intel</literal>).  You can also specify a driver
+manually, e.g.
+<programlisting>
+services.xserver.videoDrivers = [ "r128" ];
+</programlisting>
+to enable X.org’s <literal>xf86-video-r128</literal> driver.</para>
+
+<para>You also need to enable at least one desktop or window manager.
+Otherwise, you can only log into a plain undecorated
+<command>xterm</command> window.  Thus you should pick one or more of
+the following lines:
+<programlisting>
+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;
+</programlisting>
+</para>
+
+<para>NixOS’s default <emphasis>display manager</emphasis> (the
+program that provides a graphical login prompt and manages the X
+server) is SLiM.  You can select KDE’s <command>kdm</command> instead:
+<programlisting>
+services.xserver.displayManager.kdm.enable = true;
+</programlisting>
+</para>
+
+<para>The X server is started automatically at boot time.  If you
+don’t want this to happen, you can set:
+<programlisting>
+services.xserver.autorun = false;
+</programlisting>
+The X server can then be started manually:
+<screen>
+$ systemctl start display-manager.service
+</screen>
+</para>
+
+
+<section><title>NVIDIA graphics cards</title>
+
+<para>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:
+<programlisting>
+services.xserver.videoDrivers = [ "nvidia" ];
+</programlisting>
+You may need to reboot after enabling this driver to prevent a clash
+with other kernel modules.</para>
+
+<para>On 64-bit systems, if you want full acceleration for 32-bit
+programs such as Wine, you should also set the following:
+<programlisting>
+service.xserver.driSupport32Bit = true;
+</programlisting>
+</para>
+
+</section>
+
+
+<section><title>Touchpads</title>
+
+<para>Support for Synaptics touchpads (found in many laptops such as
+the Dell Latitude series) can be enabled as follows:
+<programlisting>
+services.xserver.synaptics.enable = true;
+</programlisting>
+The driver has many options (see <xref linkend="ch-options"/>).  For
+instance, the following enables two-finger scrolling:
+<programlisting>
+services.xserver.synaptics.twoFingerScroll = true;
+</programlisting>
+</para>
+
+</section>
+
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Networking</title>
+
+<section><title>Secure shell access</title>
+
+<para>Secure shell (SSH) access to your machine can be enabled by
+setting:
+
+<programlisting>
+services.openssh.enable = true;
+</programlisting>
+
+By default, root logins using a password are disallowed.  They can be
+disabled entirely by setting
+<literal>services.openssh.permitRootLogin</literal> to
+<literal>"no"</literal>.</para>
+
+<para>You can declaratively specify authorised RSA/DSA public keys for
+a user as follows:
+
+<!-- FIXME: this might not work if the user is unmanaged. -->
+<programlisting>
+users.extraUsers.alice.openssh.authorizedKeys.keys =
+  [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
+</programlisting>
+
+</para>
+
+</section>
+
+
+<section><title>IPv4 configuration</title>
+
+<para>By default, NixOS uses DHCP (specifically,
+(<command>dhcpcd</command>)) to automatically configure network
+interfaces.  However, you can configure an interface manually as
+follows:
+
+<programlisting>
+networking.interfaces.eth0 = { ipAddress = "192.168.1.2"; prefixLength = 24; };
+</programlisting>
+
+(The network prefix can also be specified using the option
+<literal>subnetMask</literal>,
+e.g. <literal>"255.255.255.0"</literal>, but this is deprecated.)
+Typically you’ll also want to set a default gateway and set of name
+servers:
+
+<programlisting>
+networking.defaultGateway = "192.168.1.1";
+networking.nameservers = [ "8.8.8.8" ];
+</programlisting>
+
+</para>
+
+<note><para>Statically configured interfaces are set up by the systemd
+service
+<replaceable>interface-name</replaceable><literal>-cfg.service</literal>.
+The default gateway and name server configuration is performed by
+<literal>network-setup.service</literal>.</para></note>
+
+<para>The host name is set using <option>networking.hostName</option>:
+
+<programlisting>
+networking.hostName = "cartman";
+</programlisting>
+
+The default host name is <literal>nixos</literal>.  Set it to the
+empty string (<literal>""</literal>) to allow the DHCP server to
+provide the host name.</para>
+
+</section>
+
+
+<section><title>IPv6 configuration</title>
+
+<para>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:
+
+<programlisting>
+networking.enableIPv6 = false;
+</programlisting>
+
+</para>
+
+</section>
+
+
+<section><title>Firewall</title>
+
+<para>NixOS has a simple stateful firewall that blocks incoming
+connections and other unexpected packets.  The firewall applies to
+both IPv4 and IPv6 traffic.  It can be enabled as follows:
+
+<programlisting>
+networking.firewall.enable = true;
+</programlisting>
+
+You can open specific TCP ports to the outside world:
+
+<programlisting>
+networking.firewall.allowedTCPPorts = [ 80 443 ];
+</programlisting>
+
+Note that TCP port 22 (ssh) is opened automatically if the SSH daemon
+is enabled (<option>services.openssh.enable = true</option>).  UDP
+ports can be opened through
+<option>networking.firewall.allowedUDPPorts</option>.  Also of
+interest is
+
+<programlisting>
+networking.firewall.allowPing = true;
+</programlisting>
+
+to allow the machine to respond to ping requests.  (ICMPv6 pings are
+always allowed.)</para>
+
+</section>
+
+
+<section><title>Wireless networks</title>
+
+<para>
+NixOS will start wpa_supplicant for you if you enable this setting:
+
+<programlisting>
+networking.wireless.enable = true;
+</programlisting>
+
+NixOS currently does not generate wpa_supplicant's
+configuration file, <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file
+yourself to define wireless networks, WPA keys and so on (see
+wpa_supplicant.conf(5)).
+</para>
+
+<para>
+If you are using WPA2 the <command>wpa_passphrase</command> tool might be useful
+to generate the <literal>wpa_supplicant.conf</literal>.
+
+<screen>
+$ wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen>
+
+After you have edited the <literal>wpa_supplicant.conf</literal>,
+you need to restart the wpa_supplicant service.
+
+<screen>
+$ systemctl restart wpa_supplicant.service</screen>
+</para>
+
+
+</section>
+
+
+<section><title>Ad-hoc configuration</title>
+
+<para>You can use <option>networking.localCommands</option> to specify
+shell commands to be run at the end of
+<literal>network-setup.service</literal>.  This is useful for doing
+network configuration not covered by the existing NixOS modules.  For
+instance, to statically configure an IPv6 address:
+
+<programlisting>
+networking.localCommands =
+  ''
+    ip -6 addr add 2001:610:685:1::1/64 dev eth0
+  '';
+</programlisting>
+
+</para>
+
+</section>
+
+
+<!-- TODO: OpenVPN, NAT -->
+
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Linux kernel</title>
+
+<para>You can override the Linux kernel and associated packages using
+the option <option>boot.kernelPackages</option>.  For instance, this
+selects the Linux 3.10 kernel:
+<programlisting>
+boot.kernelPackages = pkgs.linuxPackages_3_10;
+</programlisting>
+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.</para>
+
+<para>The default Linux kernel configuration should be fine for most
+users.  You can see the configuration of your current kernel in
+<filename>/run/booted-system/kernel-modules/config</filename>.  If you
+want to change the kernel configuration, you can use the
+<option>packageOverrides</option> feature (see <xref
+linkend="sec-customising-packages" />).  For instance, to enable
+support for the kernel debugger KGDB:
+
+<programlisting>
+nixpkgs.config.packageOverrides = pkgs:
+  { linux_3_4 = pkgs.linux_3_4.override {
+      extraConfig =
+        ''
+          KGDB y
+        '';
+    };
+  };
+</programlisting>
+
+<varname>extraConfig</varname> takes a list of Linux kernel
+configuration options, one per line.  The name of the option should
+not include the prefix <literal>CONFIG_</literal>.  The option value
+is typically <literal>y</literal>, <literal>n</literal> or
+<literal>m</literal> (to build something as a kernel module).</para>
+
+<para>Kernel modules for hardware devices are generally loaded
+automatically by <command>udev</command>.  You can force a module to
+be loaded via <option>boot.kernelModules</option>, e.g.
+<programlisting>
+boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
+</programlisting>
+If the module is required early during the boot (e.g. to mount the
+root file system), you can use
+<option>boot.initrd.extraKernelModules</option>:
+<programlisting>
+boot.initrd.extraKernelModules = [ "cifs" ];
+</programlisting>
+This causes the specified modules and their dependencies to be added
+to the initial ramdark.</para>
+
+<para>Kernel runtime parameters can be set through
+<option>boot.kernel.sysctl</option>, e.g.
+<programlisting>
+boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
+</programlisting>
+sets the kernel’s TCP keepalive time to 120 seconds.  To see the
+available parameters, run <command>sysctl -a</command>.</para>
+
+</section>
+
+
+<!-- Apache; libvirtd virtualisation -->
+
+
+</chapter>
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
new file mode 100644
index 00000000000..e6edb30985c
--- /dev/null
+++ b/nixos/doc/manual/default.nix
@@ -0,0 +1,98 @@
+{ pkgs, options
+# revision can have multiple values: local, HEAD or any revision number.
+, revision ? "HEAD"
+}:
+
+let
+
+  # To prevent infinite recursion, remove system.path from the
+  # options.  Not sure why this happens.
+  options_ =
+    options //
+    { system = removeAttrs options.system ["path"]; };
+
+  optionsXML = builtins.toFile "options.xml" (builtins.unsafeDiscardStringContext
+    (builtins.toXML (pkgs.lib.optionAttrSetToDocList "" options_)));
+
+  optionsDocBook = pkgs.runCommand "options-db.xml" {} ''
+    ${pkgs.libxslt}/bin/xsltproc \
+      --stringparam revision '${revision}' \
+      -o $out ${./options-to-docbook.xsl} ${optionsXML}
+  '';
+
+in rec {
+
+  # Generate the NixOS manual.
+  manual = pkgs.stdenv.mkDerivation {
+    name = "nixos-manual";
+
+    sources = pkgs.lib.sourceFilesBySuffices ./. [".xml"];
+
+    buildInputs = [ pkgs.libxml2 pkgs.libxslt ];
+
+    xsltFlags = ''
+      --param section.autolabel 1
+      --param section.label.includes.component.label 1
+      --param html.stylesheet 'style.css'
+      --param xref.with.number.and.title 1
+      --param toc.section.depth 3
+      --param admon.style '''
+      --param callout.graphics.extension '.gif'
+    '';
+
+    buildCommand = ''
+      ln -s $sources/*.xml . # */
+      ln -s ${optionsDocBook} options-db.xml
+
+      # Check the validity of the manual sources.
+      xmllint --noout --nonet --xinclude --noxincludenode \
+        --relaxng ${pkgs.docbook5}/xml/rng/docbook/docbook.rng \
+        manual.xml
+
+      # Generate the HTML manual.
+      dst=$out/share/doc/nixos
+      ensureDir $dst
+      xsltproc $xsltFlags --nonet --xinclude \
+        --output $dst/manual.html \
+        ${pkgs.docbook5_xsl}/xml/xsl/docbook/xhtml/docbook.xsl \
+        ./manual.xml
+
+      mkdir -p $dst/images/callouts
+      cp ${pkgs.docbook5_xsl}/xml/xsl/docbook/images/callouts/*.gif $dst/images/callouts/
+
+      cp ${./style.css} $dst/style.css
+
+      ensureDir $out/nix-support
+      echo "doc manual $dst manual.html" >> $out/nix-support/hydra-build-products
+    ''; # */
+  };
+
+  # Generate the NixOS manpages.
+  manpages = pkgs.stdenv.mkDerivation {
+    name = "nixos-manpages";
+
+    sources = pkgs.lib.sourceFilesBySuffices ./. [".xml"];
+
+    buildInputs = [ pkgs.libxml2 pkgs.libxslt ];
+
+    buildCommand = ''
+      ln -s $sources/*.xml . # */
+      ln -s ${optionsDocBook} options-db.xml
+
+      # Check the validity of the manual sources.
+      xmllint --noout --nonet --xinclude --noxincludenode \
+        --relaxng ${pkgs.docbook5}/xml/rng/docbook/docbook.rng \
+        ./man-pages.xml
+
+      # Generate manpages.
+      ensureDir $out/share/man
+      xsltproc --nonet --xinclude \
+        --param man.output.in.separate.dir 1 \
+        --param man.output.base.dir "'$out/share/man/'" \
+        --param man.endnotes.are.numbered 0 \
+        ${pkgs.docbook5_xsl}/xml/xsl/docbook/manpages/docbook.xsl \
+        ./man-pages.xml
+    '';
+  };
+
+}
diff --git a/nixos/doc/manual/development.xml b/nixos/doc/manual/development.xml
new file mode 100644
index 00000000000..d8b5f6f571c
--- /dev/null
+++ b/nixos/doc/manual/development.xml
@@ -0,0 +1,599 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Development</title>
+
+<para>This chapter has some random notes on hacking on
+NixOS.</para>
+
+
+<!--===============================================================-->
+
+<section>
+
+<title>Hacking on NixOS</title>
+
+<para>By default, NixOS’s <command>nixos-rebuild</command> command
+uses the NixOS and Nixpkgs sources provided by the
+<literal>nixos-unstable</literal> channel (kept in
+<filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>).
+To modify NixOS, however, you should check out the latest sources from
+Git.  This is done using the following command:
+
+<screen>
+$ nixos-checkout <replaceable>/my/sources</replaceable>
+</screen>
+
+or
+
+<screen>
+$ mkdir -p <replaceable>/my/sources</replaceable>
+$ cd <replaceable>/my/sources</replaceable>
+$ nix-env -i git
+$ git clone git://github.com/NixOS/nixos.git
+$ git clone git://github.com/NixOS/nixpkgs.git
+</screen>
+
+This will check out the latest NixOS sources to
+<filename><replaceable>/my/sources</replaceable>/nixos</filename> and
+the Nixpkgs sources to
+<filename><replaceable>/my/sources</replaceable>/nixpkgs</filename>.
+If you want to rebuild your system using your (modified) sources, you
+need to tell <command>nixos-rebuild</command> about them using the
+<option>-I</option> flag:
+
+<screen>
+$ nixos-rebuild switch -I <replaceable>/my/sources</replaceable>
+</screen>
+
+</para>
+
+<para><command>nixos-rebuild</command> affects only the system profile.
+To install packages to your user profile from expressions in
+<replaceable>/my/sources</replaceable>, use
+<command>nix-env -f <replaceable>/my/sources</replaceable>/nixpkgs</command>,
+or change the default by replacing the symlink in
+<filename>~/.nix-defexpr</filename>:
+
+<screen>
+$ rm -f ~/.nix-defexpr/channels
+$ ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs
+</screen>
+
+</para>
+
+<para>You should not pass the base directory
+<filename><replaceable>/my/sources</replaceable></filename>
+to <command>nix-env</command>, as it will break after interpreting expressions
+in <filename>nixos/</filename> as packages.</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section>
+
+<title>Extending NixOS</title>
+
+<para>NixOS is based on a modular system for declarative configuration.
+  This system combines multiple <emphasis>modules</emphasis> to produce one
+  configuration.  One of the module which compose your computer
+  configuration is <filename>/etc/nixos/configuration.nix</filename>.  Other
+  modules are available under NixOS <filename>modules</filename>
+  directory</para>
+
+<para>A module is a file which handles one specific part of the
+  configuration.  This part of the configuration could correspond to
+  hardware, a service, network settings, or preferences.  A module
+  configuration does not have to handle everything from scratch, it can base
+  its configuration on other configurations provided by other modules.  Thus
+  a module can <emphasis>define</emphasis> options to setup its
+  configuration, and it can also <emphasis>declare</emphasis> options to be
+  fed by other modules.</para>
+
+<!-- module syntax -->
+
+<para xml:id="para-module-syn">A module is a file which contains a Nix
+  expression.  This expression should be either an expression which gets
+  evaluated into an attribute set or a function which returns an attribute
+  set.</para>
+
+<para>When the expression is a function, it should expect only one argument
+  which is an attribute set containing an attribute
+  named <varname>config</varname> and another attribute
+  named <varname>pkgs</varname>.  The <varname>config</varname> attribute
+  contains the result of the merge of all modules.  This attribute is
+  evaluated lazily, such as any Nix expression.  For more details on how
+  options are merged, see the details in <xref linkend="para-opt-decl"/>.
+  The <varname>pkgs</varname> attribute
+  contains <emphasis>nixpkgs</emphasis> attribute set of packages.  This
+  attribute is necessary for declaring options.</para>
+
+<example xml:id='module-syntax'><title>Usual module content</title>
+<programlisting>
+{ config, pkgs, ... }: <co xml:id='module-syntax-1' />
+
+{
+  imports =
+    [ <co xml:id='module-syntax-2' />
+    ];
+
+  options = {
+    <co xml:id='module-syntax-3' />
+  };
+
+  config = {
+    <co xml:id='module-syntax-4' />
+  };
+}</programlisting>
+</example>
+
+<para><xref linkend='module-syntax' /> Illustrates
+  a <emphasis>module</emphasis> skeleton.
+
+<calloutlist>
+  <callout arearefs='module-syntax-1'>
+    <para>This line makes the current Nix expression a function.  This
+    line can be omitted if there is no reference to <varname>pkgs</varname>
+    and <varname>config</varname> inside the module.</para>
+  </callout>
+
+  <callout arearefs='module-syntax-2'>
+    <para>This list is used to enumerate path to other modules which are
+    declaring options used by the current module.  In NixOS, default modules
+    are listed in the file <filename>modules/module-list.nix</filename>.
+    The default modules don't need to be added in the import list.</para>
+  </callout>
+
+  <callout arearefs='module-syntax-3'>
+    <para>This attribute set contains an attribute set of <emphasis>option
+    declaration</emphasis>.</para>
+  </callout>
+
+  <callout arearefs='module-syntax-4'>
+    <para>This attribute set contains an attribute set of <emphasis>option
+    definitions</emphasis>.  If the module does not have any imported
+    modules or any option declarations, then this attribute set can be used
+    in place of its parent attribute set.  This is a common case for simple
+    modules such
+    as <filename>/etc/nixos/configuration.nix</filename>.</para>
+  </callout>
+</calloutlist>
+
+</para>
+
+<!-- option definitions -->
+
+<para xml:id="para-opt-def">A module defines a configuration which would be
+  interpreted by other modules.  To define a configuration, a module needs
+  to provide option definitions.  An option definition is a simple
+  attribute assignment.</para>
+
+<para>Option definitions are made in a declarative manner.  Without
+  properties, options will always be defined with the same value.  To
+  introduce more flexibility in the system, option definitions are guarded
+  by <emphasis>properties</emphasis>.</para>
+
+<para>Properties are means to introduce conditional values inside option
+  definitions.  This conditional values can be distinguished in two
+  categories.  The condition which are local to the current configuration
+  and conditions which are dependent on others configurations.  Local
+  properties are <varname>mkIf</varname>
+  and <varname>mkAssert</varname>.  Global properties
+  are <varname>mkOverride</varname>, <varname>mkDefault</varname>
+  and <varname>mkOrder</varname>.</para>
+
+<para><varname>mkIf</varname> is used to remove the option definitions which
+  are below it if the condition is evaluated to
+  false.  <varname>mkAssert</varname> expects the condition to be evaluated
+  to true otherwise it raises an error message.</para>
+
+<para><varname>mkOverride</varname> is used to mask previous definitions if
+  the current value has a lower mask number.  The mask value is 100 (default)
+  for any option definition which does not use this property.
+  Thus, <varname>mkDefault</varname> is just a short-cut with a higher mask
+  (1000) than the default mask value.  This means that a module can set an
+  option definition as a preference, and still let another module defining
+  it with a different value without using any property.</para>
+
+<para><varname>mkOrder</varname> is used to sort definitions based on the
+  rank number.  The rank number will sort all options definitions before
+  giving the sorted list of option definition to the merge function defined
+  in the option declaration.  A lower rank will move the definition to the
+  beginning and a higher rank will move the option toward the end.  The
+  default rank is 100.</para>
+
+<!-- option declarations -->
+
+<para xml:id="para-opt-decl">A module may declare options which are used by
+  other module to change the configuration provided by the current module.
+  Changes to the option definitions are made with properties which are using
+  values extracted from the result of the merge of all modules
+  (the <varname>config</varname> argument).</para>
+
+<para>The <varname>config</varname> argument reproduce the same hierarchy of
+  all options declared in all modules.  For each option, the result of the
+  option is available, it is either the default value or the merge of all
+  definitions of the option.</para>
+
+<para>Options are declared with the
+  function <varname>pkgs.lib.mkOption</varname>.  This function expects an
+  attribute set which at least provides a description.  A default value, an
+  example, a type, a merge function and a post-process function can be
+  added.</para>
+
+<para>Types are used to provide a merge strategy for options and to ensure
+  the type of each option definitions.  They are defined
+  in <varname>pkgs.lib.types</varname>.</para>
+
+<para>The merge function expects a list of option definitions and merge
+  them to obtain one result of the same type.</para>
+
+<para>The post-process function (named <varname>apply</varname>) takes the
+  result of the merge or of the default value, and produce an output which
+  could have a different type than the type expected by the option.</para>
+
+<!-- end -->
+
+<example xml:id='locate-example'><title>Locate Module Example</title>
+<programlisting>
+{ config, pkgs, ... }:
+
+with pkgs.lib;
+
+let
+  cfg = config.services.locate;
+  locatedb = "/var/cache/locatedb";
+  logfile = "/var/log/updatedb";
+  cmd =''root  updatedb --localuser=nobody --output=${locatedb} > ${logfile}'';
+in
+
+{
+  imports = [ /etc/nixos/nixos/modules/services/scheduling/cron.nix ];
+
+  options = {
+    services.locate = {
+      enable = mkOption {
+        default = false;
+        example = true;
+        type = with types; bool;
+        description = ''
+          If enabled, NixOS will periodically update the database of
+          files used by the <command>locate</command> command.
+        '';
+      };
+
+      period = mkOption {
+        default = "15 02 * * *";
+        type = with types; uniq string;
+        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 = mkIf cfg.enable {
+    services.cron = {
+      enable = true;
+      systemCronJobs = "${cfg.period}  root ${cmd}";
+    };
+  };
+}</programlisting>
+</example>
+
+<para><xref linkend='locate-example' /> illustrates a module which handles
+  the regular update of the database which index all files on the file
+  system.  This modules has option definitions to rely on the cron service
+  to run the command at predefined dates.  In addition, this modules
+  provides option declarations to enable the indexing and to use different
+  period of time to run the indexing.  Properties are used to prevent
+  ambiguous definitions of option (enable locate service and disable cron
+  services) and to ensure that no options would be defined if the locate
+  service is not enabled.</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section>
+
+<title>Building specific parts of NixOS</title>
+
+<para>
+
+<screen>
+$ nix-build /etc/nixos/nixos -A <replaceable>attr</replaceable></screen>
+
+where <replaceable>attr</replaceable> is an attribute in
+<filename>/etc/nixos/nixos/default.nix</filename>.  Attributes of interest include:
+
+<variablelist>
+
+  <varlistentry>
+    <term><varname>config</varname></term>
+    <listitem><para>The computer configuration generated from
+    the <envar>NIXOS_CONFIG</envar> environment variable (default
+    is <filename>/etc/nixos/configuration.nix</filename>) with the NixOS
+    default set of modules.</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><varname>system</varname></term>
+    <listitem><para>The derivation which build your computer system.  It is
+    built by the command <command>nixos-rebuild
+    build</command></para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><varname>vm</varname></term>
+    <listitem><para>The derivation which build your computer system inside a
+    virtual machine.  It is built by the command <command>nixos-rebuild
+    build-vm</command></para></listitem>
+  </varlistentry>
+</variablelist>
+
+</para>
+
+<para>
+Most parts of NixOS can be built through the <varname>config</varname>
+attribute set.  This attribute set allows you to have a view of the merged
+option definitions and all its derivations.  Important derivations are store
+inside the option <option>system.build</option> and can be listed with the
+command <command>nix-instantiate --xml --eval-only /etc/nixos/nixos -A
+config.system.build</command>
+</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section>
+
+<title>Building your own NixOS CD</title>
+
+<para>Building a NixOS CD is as easy as configuring your own computer. The
+idea is to use another module which will replace
+your <filename>configuration.nix</filename> to configure the system that
+would be installed on the CD.</para>
+
+<para>Default CD/DVD configurations are available
+inside <filename>nixos/modules/installer/cd-dvd</filename>.  To build them
+you have to set <envar>NIXOS_CONFIG</envar> before
+running <command>nix-build</command> to build the ISO.
+
+<screen>
+$ export NIXOS_CONFIG=/etc/nixos/nixos/modules/installer/cd-dvd/installation-cd-minimal.nix
+$ nix-build /etc/nixos/nixos -A config.system.build.isoImage</screen>
+
+</para>
+
+<para>Before burning your CD/DVD, you can check the content of the image by mounting anywhere like
+suggested by the following command:
+
+<screen>
+$ mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>
+
+</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section>
+
+<title>Testing/building the NixOS Manual</title>
+
+<para>A quick way to see if your documentation improvements
+or option descriptions look good:
+
+<screen>
+$ nix-build -A config.system.build.manual</screen>
+
+</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section>
+
+<title>Testing the installer</title>
+
+<para>Building, burning, and
+booting from an installation CD is rather
+tedious, so here is a quick way to see if the installer works
+properly:
+
+<screen>
+$ export NIXOS_CONFIG=/etc/nixos/nixos/modules/installer/cd-dvd/installation-cd-minimal.nix
+$ nix-build /etc/nixos/nixos -A config.system.build.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</screen>
+
+</para>
+
+</section>
+
+
+
+<!--===============================================================-->
+
+<section>
+
+<title>Testing the <literal>initrd</literal></title>
+
+<para>A quick way to test whether the kernel and the initial ramdisk
+boot correctly is to use QEMU’s <option>-kernel</option> and
+<option>-initrd</option> options:
+
+<screen>
+$ nix-build /etc/nixos/nixos -A config.system.build.initialRamdisk -o initrd
+$ nix-build /etc/nixos/nixos -A config.system.build.kernel -o kernel
+$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
+</screen>
+
+</para>
+
+</section>
+
+<section>
+
+  <title>Whole-system testing using virtual machines</title>
+
+  <para>
+    Complete NixOS GNU/Linux systems can be tested in virtual machines
+    (VMs).  This makes it possible to test a system upgrade or
+    configuration change before rebooting into it, using the
+    <command>nixos-rebuild build-vm</command> or
+    <command>nixos-rebuild build-vm-with-bootloader</command> command.
+  </para>
+
+  <para>
+    <!-- The following is adapted from
+         http://wiki.nixos.org/wiki/NixOS_VM_tests, by Eelco Dolstra. -->
+
+    The <filename>tests/</filename> directory in the NixOS source tree
+    contains several <emphasis>whole-system unit tests</emphasis>.
+    These tests can be run<footnote><para>NixOS tests can be run both from
+    NixOS and from a non-NixOS GNU/Linux distribution, provided the
+    Nix package manager is installed.</para></footnote> from the NixOS
+    source tree as follows:
+
+<screen>
+$ nix-build tests/ -A nfs.test
+</screen>
+
+    This performs an automated test of the NFS client and server
+    functionality in the Linux kernel, including file locking
+    semantics (e.g., whether locks are maintained across server
+    crashes).  It will first build or download all the dependencies of
+    the test (e.g., all packages needed to run a NixOS VM). The test
+    is defined in <link
+    xlink:href="https://nixos.org/repos/nix/nixos/trunk/tests/nfs.nix">
+    <filename>tests/nfs.nix</filename></link>.  If the test succeeds,
+    <command>nix-build</command> will place a symlink
+    <filename>./result</filename> in the current directory pointing at
+    the location in the Nix store of the test results (e.g.,
+    screenshots, test reports, and so on).  In particular, a
+    pretty-printed log of the test is written to
+    <filename>log.html</filename>, which can be viewed using a web
+    browser like this:
+
+<screen>
+$ firefox result/log.html
+</screen>
+  </para>
+
+  <para>
+    It is also possible to run the test environment interactively,
+    allowing you to experiment with the VMs.  For example:
+
+<screen>
+$ nix-build tests/ -A nfs.driver
+$ ./result/bin/nixos-run-vms
+</screen>
+
+    The script <command>nixos-run-vms</command> starts the three
+    virtual machines defined in the NFS test using QEMU/KVM.  The root
+    file system of the VMs is created on the fly and kept across VM
+    restarts in
+    <filename>./</filename><varname>hostname</varname><filename>.qcow2</filename>.
+  </para>
+
+  <para>
+    Finally, the test itself can be run interactively.  This is
+    particularly useful when developing or debugging a test:
+
+<screen>
+$ nix-build tests/ -A nfs.driver
+$ ./result/bin/nixos-test-driver
+starting VDE switch for network 1
+&gt;
+</screen>
+
+    Perl statements can now be typed in to start or manipulate the
+    VMs:
+
+<screen>
+&gt; startAll;
+(the VMs start booting)
+&gt; $server-&gt;waitForJob("nfs-kernel-nfsd");
+&gt; $client1-&gt;succeed("flock -x /data/lock -c 'sleep 100000' &amp;");
+&gt; $client2-&gt;fail("flock -n -s /data/lock true");
+&gt; $client1-&gt;shutdown;
+(this releases client1's lock)
+&gt; $client2-&gt;succeed("flock -n -s /data/lock true");
+</screen>
+
+    The function <command>testScript</command> executes the entire
+    test script and drops you back into the test driver command line
+    upon its completion.  This allows you to inspect the state of the
+    VMs after the test (e.g. to debug the test script).
+  </para>
+
+  <para>
+    This and other tests are continuously run on <link
+    xlink:href="http://hydra.nixos.org/jobset/nixos/trunk">the Hydra
+    instance at <literal>nixos.org</literal></link>, which allows
+    developers to be notified of any regressions introduced by a NixOS
+    or Nixpkgs change.
+  </para>
+
+  <para>
+    The actual Nix programming interface to VM testing is in NixOS,
+    under <link
+    xlink:href="https://nixos.org/repos/nix/nixos/trunk/lib/testing.nix">
+    <filename>lib/testing.nix</filename></link>.  This file defines a
+    function which takes an attribute set containing a
+    <literal>nixpkgs</literal> attribute (the path to a Nixpkgs
+    checkout), and a <literal>system</literal> attribute (the system
+    type).  It returns an attribute set containing several utility
+    functions, among which the main entry point is
+    <literal>makeTest</literal>.
+  </para>
+
+  <para>
+    The <literal>makeTest</literal> function takes a function similar to
+    that found in <link
+    xlink:href="https://nixos.org/repos/nix/nixos/trunk/tests/nfs.nix">
+    <filename>tests/nfs.nix</filename></link> (discussed above).  It
+    returns an attribute set containing (among others):
+
+    <variablelist>
+
+      <varlistentry>
+        <term><varname>test</varname></term>
+        <listitem><para>A derivation containing the test log as an HTML file,
+        as seen above, suitable for presentation in the Hydra continuous
+        build system.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>report</varname></term>
+        <listitem><para>A derivation containing a code coverage report, with
+        meta-data suitable for Hydra.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>driver</varname></term>
+        <listitem><para>A derivation containing scripts to run the VM test or
+        interact with the VM network interactively, as seen above.</para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </para>
+
+</section>
+
+</chapter>
diff --git a/nixos/doc/manual/installation.xml b/nixos/doc/manual/installation.xml
new file mode 100644
index 00000000000..3068fa5cb94
--- /dev/null
+++ b/nixos/doc/manual/installation.xml
@@ -0,0 +1,340 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Installing NixOS</title>
+
+
+<!--===============================================================-->
+
+<section>
+
+<title>Obtaining NixOS</title>
+
+<para>NixOS ISO images can be downloaded from the <link
+xlink:href="http://nixos.org/nixos/download.html">NixOS
+homepage</link>.  These can be burned onto a CD.  It is also possible
+to copy them onto a USB stick and install NixOS from there.  For
+details, see the <link
+xlink:href="https://nixos.org/wiki/Installing_NixOS_from_a_USB_stick">NixOS
+Wiki</link>.</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section>
+
+<title>Installation</title>
+
+<orderedlist>
+
+  <listitem><para>Boot from the CD.</para></listitem>
+
+  <listitem><para>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 and brought up networking (check
+  <command>ifconfig</command>).  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 <command>ifconfig</command>.</para></listitem>
+
+  <listitem><para>The NixOS manual is available on virtual console 8
+  (press Alt+F8 to access).</para></listitem>
+
+  <listitem><para>Login as <literal>root</literal>, empty
+  password.</para></listitem>
+
+  <listitem><para>If you downloaded the graphical ISO image, you can
+  run <command>start display-manager</command> to start KDE.</para></listitem>
+
+  <listitem><para>The NixOS installer doesn’t do any partitioning or
+  formatting yet, so you need to that yourself.  Use the following
+  commands:
+
+  <itemizedlist>
+
+    <listitem><para>For partitioning:
+    <command>fdisk</command>.</para></listitem>
+
+    <listitem><para>For initialising Ext4 partitions:
+    <command>mkfs.ext4</command>.  It is recommended that you assign a
+    unique symbolic label to the file system using the option
+    <option>-L <replaceable>label</replaceable></option>.  This will
+    make the file system configuration independent from device
+    changes.</para></listitem>
+
+    <listitem><para>For creating swap partitions:
+    <command>mkswap</command>.  Again it’s recommended to assign a
+    label to the swap partition: <option>-L
+    <replaceable>label</replaceable></option>.</para></listitem>
+
+    <listitem><para>For creating LVM volumes, the LVM commands, e.g.,
+
+<screen>
+$ pvcreate /dev/sda1 /dev/sdb1
+$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1
+$ lvcreate --size 2G --name bigdisk MyVolGroup
+$ lvcreate --size 1G --name smalldisk MyVolGroup</screen>
+
+    </para></listitem>
+
+    <listitem><para>For creating software RAID devices, use
+    <command>mdadm</command>.</para></listitem>
+
+  </itemizedlist>
+
+  </para></listitem>
+
+  <listitem><para>Mount the target file system on which NixOS should
+  be installed on <filename>/mnt</filename>.</para></listitem>
+
+  <listitem>
+
+    <para>You now need to create a file
+    <filename>/mnt/etc/nixos/configuration.nix</filename> that
+    specifies the intended configuration of the system.  This is
+    because NixOS has a <emphasis>declarative</emphasis> configuration
+    model: you create or edit a description of the configuration that
+    you want to be built and activated, and then NixOS takes care of
+    realising that configuration.  The command
+    <command>nixos-option</command> can generate an initial
+    configuration file for you:
+
+<screen>
+$ nixos-option --install</screen>
+
+    It tries to figure out the kernel modules necessary for mounting
+    the root device, as well as various other hardware
+    characteristics.  However, it doesn’t try to figure out the
+    <option>fileSystems</option> option yet.</para>
+
+    <para>You should edit
+    <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your
+    needs.  The text editors <command>nano</command> and
+    <command>vim</command> are available.</para>
+
+    <para>You need to specify a root file system in
+    <option>fileSystems</option> and the target device for the Grub boot
+    loader in <option>boot.loader.grub.device</option>.  See
+    <xref linkend="ch-options"/> for a list of the available configuration
+    options.</para>
+
+    <note><para>It is very important that you specify in the option
+    <option>boot.initrd.kernelModules</option> 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 the CD again, mount the target file system on
+    <filename>/mnt</filename>, fix
+    <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun
+    <filename>nixos-install</filename>.)  In most cases,
+    <command>nixos-option --install</command> will figure out the
+    required modules.</para></note>
+
+    <para>Examples of real-world NixOS configuration files can be
+    found at <link
+    xlink:href="https://nixos.org/repos/nix/configurations/trunk/"/>.</para>
+
+  </listitem>
+
+  <listitem><para>If your machine has a limited amount of memory, you
+  may want to activate swap devices now (<command>swapon
+  <replaceable>device</replaceable></command>).  The installer (or
+  rather, the build actions that it may spawn) may need quite a bit of
+  RAM, depending on your configuration.</para></listitem>
+
+  <!--
+  <listitem><para>Optionally, you can run
+
+<screen>
+$ nixos-checkout</screen>
+
+  to make the installer use the latest NixOS/Nixpkgs sources from the
+  Git repository, rather than the sources on CD.</para></listitem>
+  -->
+
+  <listitem><para>Do the installation:
+
+<screen>
+$ nixos-install</screen>
+
+    Cross fingers.</para></listitem>
+
+  <listitem><para>If everything went well:
+
+<screen>
+$ reboot</screen>
+
+  </para></listitem>
+
+  <listitem>
+
+    <para>You should now be able to boot into the installed NixOS.
+    The Grub boot menu shows a list of <emphasis>available
+    configurations</emphasis> (initially just one).  Every time you
+    change the NixOS configuration (see <xref
+    linkend="sec-changing-config" />), a new item appears in the menu.
+    This allows you to easily roll back to another configuration if
+    something goes wrong.</para>
+
+    <para>You should log in and change the <literal>root</literal>
+    password with <command>passwd</command>.</para>
+
+    <para>You’ll probably want to create some user accounts as well,
+    which can be done with <command>useradd</command>:
+
+<screen>
+$ useradd -c 'Eelco Dolstra' -m eelco
+$ passwd eelco</screen>
+
+    </para>
+
+    <para>You may also want to install some software.  For instance,
+
+<screen>
+$ nix-env -qa \*</screen>
+
+    shows what packages are available, and
+
+<screen>
+$ nix-env -i w3m</screen>
+
+    install the <literal>w3m</literal> browser.</para>
+
+  </listitem>
+
+</orderedlist>
+
+<para><xref linkend="ex-install-sequence" /> shows a typical sequence
+of commands for installing NixOS on an empty hard drive (here
+<filename>/dev/sda</filename>).  <xref linkend="ex-config" /> shows a
+corresponding configuration Nix expression.</para>
+
+<example xml:id='ex-install-sequence'><title>Commands for installing NixOS on <filename>/dev/sda</filename></title>
+<screen>
+$ fdisk /dev/sda <lineannotation>(or whatever device you want to install on)</lineannotation>
+$ mkfs.ext4 -L nixos /dev/sda1 <lineannotation>(idem)</lineannotation>
+$ mkswap -L swap /dev/sda2 <lineannotation>(idem)</lineannotation>
+$ mount LABEL=nixos /mnt
+$ nixos-option --install
+$ nano /mnt/etc/nixos/configuration.nix
+<lineannotation>(in particular, set the fileSystems and swapDevices options)</lineannotation>
+$ nixos-install
+$ reboot</screen>
+</example>
+
+<example xml:id='ex-config'><title>NixOS configuration</title>
+<screen>
+{
+  boot.loader.grub.device = "/dev/sda";
+
+  fileSystems."/".device = "/dev/disk/by-label/nixos";
+
+  swapDevices =
+    [ { device = "/dev/disk/by-label/swap"; } ];
+
+  services.sshd.enable = true;
+}</screen>
+</example>
+
+</section>
+
+
+
+<!--===============================================================-->
+
+<section xml:id="sec-changing-config">
+
+<title>Changing the configuration</title>
+
+<para>The file <filename>/etc/nixos/configuration.nix</filename>
+contains the current configuration of your machine.  Whenever you’ve
+changed something to that file, you should do
+
+<screen>
+$ nixos-rebuild switch</screen>
+
+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).</para>
+
+<para>You can also do
+
+<screen>
+$ nixos-rebuild test</screen>
+
+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.</para>
+
+<para>There is also
+
+<screen>
+$ nixos-rebuild boot</screen>
+
+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).</para>
+
+<para>Finally, you can do
+
+<screen>
+$ nixos-rebuild build</screen>
+
+to build the configuration but nothing more.  This is useful to see
+whether everything compiles cleanly.</para>
+
+<para>If you have a machine that supports hardware virtualisation, you
+can also test the new configuration in a sandbox by building and
+running a <emphasis>virtual machine</emphasis> that contains the
+desired configuration.  Just do
+
+<screen>
+$ nixos-rebuild build-vm
+$ ./result/bin/run-*-vm
+</screen>
+
+The VM does not have use any data from your host system, so your
+existing user accounts and home directories will not be
+available.</para>
+
+</section>
+
+
+
+<!--===============================================================-->
+
+<section xml:id="sec-upgrading">
+
+<title>Upgrading NixOS</title>
+
+<para>The best way to keep your NixOS installation up to date is to
+use the <literal>nixos-unstable</literal> channel.  (A channel is a
+Nix mechanism for distributing Nix expressions and associated
+binaries.)  The NixOS channel is updated automatically from NixOS’s
+Git repository after running certain tests and building most
+packages.</para>
+
+<para>NixOS automatically subscribes you to the NixOS channel.  If for
+some reason this is not the case, just do
+
+<screen>
+$ nix-channel --add http://nixos.org/channels/nixos-unstable
+</screen>
+
+You can then upgrade NixOS to the latest version in the channel by
+running
+
+<screen>
+$ nix-channel --update nixos
+</screen>
+
+and running the <command>nixos-rebuild</command> command as described
+in <xref linkend="sec-changing-config"/>.</para>
+
+</section>
+
+</chapter>
diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml
new file mode 100644
index 00000000000..d49369d2c58
--- /dev/null
+++ b/nixos/doc/manual/man-configuration.xml
@@ -0,0 +1,38 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  
+<refmeta>
+  <refentrytitle><filename>configuration.nix</filename></refentrytitle>
+  <manvolnum>5</manvolnum>
+  <refmiscinfo class="source">NixOS</refmiscinfo>
+  <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
+</refmeta>
+
+<refnamediv>
+  <refname><filename>configuration.nix</filename></refname>
+  <refpurpose>NixOS system configuration specification</refpurpose>
+</refnamediv>
+
+
+<refsection><title>Description</title>
+
+<para>The file <filename>/etc/nixos/configuration.nix</filename>
+contains the declarative specification of your NixOS system
+configuration.  The command <command>nixos-rebuild</command> takes
+this file and realises the system configuration specified
+therein.</para>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<para>You can use the following options in
+<filename>configuration.nix</filename>.</para>
+
+<xi:include href="options-db.xml" />
+
+</refsection>
+  
+</refentry>
diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml
new file mode 100644
index 00000000000..f37677629d0
--- /dev/null
+++ b/nixos/doc/manual/man-nixos-build-vms.xml
@@ -0,0 +1,110 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  
+<refmeta>
+  <refentrytitle><command>nixos-build-vms</command></refentrytitle>
+  <manvolnum>8</manvolnum>
+  <refmiscinfo class="source">NixOS</refmiscinfo>
+  <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
+</refmeta>
+
+<refnamediv>
+  <refname><command>nixos-build-vms</command></refname>
+  <refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nixos-build-vms</command>
+    <arg><option>--show-trace</option></arg>
+    <arg><option>--no-out-link</option></arg>
+    <arg><option>--help</option></arg>
+    <arg choice="plain"><replaceable>network.nix</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsection><title>Description</title>
+
+<para>This command builds a network of QEMU-KVM virtual machines of a Nix expression
+specifying a network of NixOS machines. The virtual network can be started by
+executing the <filename>bin/run-vms</filename> shell script that is generated by
+this command. By default, a <filename>result</filename> symlink is produced that
+points to the generated virtual network.
+</para>
+
+<para>A network Nix expression has the following structure:
+
+<screen>
+{
+  test1 = {pkgs, config, ...}:
+    {
+      services.openssh.enable = true;
+      nixpkgs.system = "i686-linux";
+      deployment.targetHost = "test1.example.net";
+      
+      # Other NixOS options
+    };
+    
+  test2 = {pkgs, config, ...}:
+    {
+      services.openssh.enable = true;
+      services.httpd.enable = true;
+      environment.systemPackages = [ pkgs.lynx ];
+      nixpkgs.system = "x86_64-linux";
+      deployment.targetHost = "test2.example.net";
+      
+      # Other NixOS options
+    };
+}
+</screen>
+
+Each attribute in the expression represents a machine in the network
+(e.g. <varname>test1</varname> and <varname>test2</varname>)
+referring to a function defining a NixOS configuration.
+In each NixOS configuration, two attributes have a special meaning.
+The <varname>deployment.targetHost</varname> specifies the address
+(domain name or IP address)
+of the system which is used by <command>ssh</command> to perform
+remote deployment operations. The <varname>nixpkgs.system</varname>
+attribute can be used to specify an architecture for the target machine,
+such as <varname>i686-linux</varname> which builds a 32-bit NixOS
+configuration. Omitting this property will build the configuration
+for the same architecture as the host system.
+</para>
+
+</refsection>
+
+<refsection><title>Options</title>
+
+<para>This command accepts the following options:</para>
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>--show-trace</option></term>
+    <listitem>
+      <para>Shows a trace of the output.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--no-out-link</option></term>
+    <listitem>
+      <para>Do not create a 'result' symlink.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>-h</option>, <option>--help</option></term>
+    <listitem>
+      <para>Shows the usage of this command to the user.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+</refentry>
diff --git a/nixos/doc/manual/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml
new file mode 100644
index 00000000000..f7a8ce403dc
--- /dev/null
+++ b/nixos/doc/manual/man-nixos-option.xml
@@ -0,0 +1,170 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  
+<refmeta>
+  <refentrytitle><command>nixos-option</command></refentrytitle>
+  <manvolnum>8</manvolnum>
+  <refmiscinfo class="source">NixOS</refmiscinfo>
+  <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
+</refmeta>
+
+<refnamediv>
+  <refname><command>nixos-option</command></refname>
+  <refpurpose>inspect a NixOS configuration</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nixos-option</command>
+    <group choice="opt">
+      <option>-i</option>
+      <option>v</option>
+      <option>d</option>
+      <option>l</option>
+    </group>
+    <arg choice='plain'><replaceable>option.name</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>nixos-option</command>
+    <arg choice='plain'><option>--install</option></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>This command evaluates the configuration specified in
+<filename>/etc/nixos/configuration.nix</filename> and returns the properties
+of the option name given as argument.  By default, it returns the value of
+the option.</para>
+
+<para>When the option name is not an option, the command prints the list of
+attributes in contained in the attribute set.  This could used to provide
+completion in some editors.</para>
+
+<para>When the option <option>--install</option> (or <option>-i</option>) is
+used with no option name, this command generates a template configuration
+with a scan of the target system.  It produces a template configuration
+in <filename>/etc/nixos/configuration.nix</filename>, and a scan of the
+machine in <filename>/etc/nixos/hardware-configuration.nix</filename>.  The
+scan of the machine is produced
+by <command>nixos-hardware-scan</command>.</para>
+
+</refsection>
+
+<refsection><title>Options</title>
+
+<para>This command accepts the following options:</para>
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>--install</option>, <option>-i</option></term>
+    <listitem>
+      <para>Use the installation configuration instead of current system
+      configuration.  Generate a template configuration if no option name is
+      specified.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--value</option>, <option>-v</option></term>
+    <listitem>
+      <para>Returns the value of the option.  This is the default operation
+      if no other options are defined.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--description</option>, <option>-d</option></term>
+    <listitem>
+      <para>Return the default value, the example and the description of the
+      option when available.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--lookup</option>, <option>-l</option></term>
+    <listitem>
+      <para>Return the locations where the option is declared and where it
+      is defined.  This is extremely useful to find sources of errors in
+      your configuration.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Environment</title>
+
+<variablelist>
+
+  <varlistentry>
+    <term><envar>mountPoint</envar></term>
+    <listitem>
+      <para>Location of the target file system.  Defaults to
+      <filename>/mnt</filename>.  This environment variable is only used in
+      combinaison with <option>--install</option> option.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><envar>NIXOS_CONFIG</envar></term>
+    <listitem>
+      <para>Path to the main NixOS configuration module.  Defaults to
+      <filename>/etc/nixos/configuration.nix</filename>.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>Investigate option values:
+
+<screen>$ nixos-option boot.loader
+This attribute set contains:
+generationsDir
+grub
+initScript
+
+$ nixos-option boot.loader.grub.enable
+true</screen></para>
+
+<para>Prints option information:
+
+<screen>$ nixos-option -d networking.hostName
+Default: "nixos"
+Description:
+The name of the machine. Leave it empty if you want to obtain
+it from a DHCP server (if using DHCP).</screen></para>
+
+<para>Find the locations which are declaring and defining an option:
+
+<screen>$ nixos-option -l hardware.firmware
+Declared by:
+  /mnt/data/nix-sources/nixos/modules/services/hardware/udev.nix
+
+Defined by:
+  /etc/nixos/nixos/modules/system/boot/kernel.nix
+  /etc/nixos/nixos/modules/hardware/network/rt73.nix
+  /etc/nixos/nixos/modules/hardware/network/intel-3945abg.nix
+  /etc/nixos/nixos/modules/hardware/network/intel-2200bg.nix</screen></para>
+
+</refsection>
+
+<refsection><title>Bugs</title>
+
+<para>The author listed in the following section is wrong.  If there is any
+  other bug, please report to Nicolas Pierron.</para>
+
+</refsection>
+
+
+</refentry>
diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml
new file mode 100644
index 00000000000..e43dafd3cfe
--- /dev/null
+++ b/nixos/doc/manual/man-nixos-rebuild.xml
@@ -0,0 +1,300 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  
+<refmeta>
+  <refentrytitle><command>nixos-rebuild</command></refentrytitle>
+  <manvolnum>8</manvolnum>
+  <refmiscinfo class="source">NixOS</refmiscinfo>
+  <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
+</refmeta>
+
+<refnamediv>
+  <refname><command>nixos-rebuild</command></refname>
+  <refpurpose>reconfigure a NixOS machine</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nixos-rebuild</command>
+    <group choice='req'>
+      <arg choice='plain'><option>switch</option></arg>
+      <arg choice='plain'><option>boot</option></arg>
+      <arg choice='plain'><option>test</option></arg>
+      <arg choice='plain'><option>build</option></arg>
+      <arg choice='plain'><option>dry-run</option></arg>
+      <arg choice='plain'><option>build-vm</option></arg>
+      <arg choice='plain'><option>build-vm-with-bootloader</option></arg>
+    </group>
+    <sbr />
+    <arg><option>--upgrade</option></arg>
+    <arg><option>--install-grub</option></arg>
+    <arg><option>--no-build-nix</option></arg>
+    <arg><option>--fast</option></arg>
+    <arg><option>--rollback</option></arg>
+    <sbr />
+    <arg><option>--show-trace</option></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>This command updates the system so that it corresponds to the
+configuration specified in
+<filename>/etc/nixos/configuration.nix</filename>.  Thus, every time
+you modify <filename>/etc/nixos/configuration.nix</filename> or any
+NixOS module, you must run <command>nixos-rebuild</command> to make
+the changes take effect.  It builds the new system in
+<filename>/nix/store</filename>, runs its activation script, and stop
+and (re)starts any system services if needed.</para>
+
+<para>This command has one required argument, which specifies the
+desired operation.  It must be one of the following:
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>switch</option></term>
+    <listitem>
+      <para>Build and activate the new configuration, and make it the
+      boot default.  That is, the configuration is added to the GRUB
+      boot menu as the default meny entry, so that subsequent reboots
+      will boot the system into the new configuration.  Previous
+      configurations activated with <command>nixos-rebuild
+      switch</command> or <command>nixos-rebuild boot</command> remain
+      available in the GRUB menu.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>boot</option></term>
+    <listitem>
+      <para>Build the new configuration and make it the boot default
+      (as with <command>nixos-rebuild switch</command>), but do not
+      activate it.  That is, the system continues to run the previous
+      configuration until the next reboot.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>test</option></term>
+    <listitem>
+      <para>Build and activate the new configuration, but do not add
+      it to the GRUB boot menu.  Thus, if you reboot the system (or if
+      it crashes), you will automatically revert to the default
+      configuration (i.e. the configuration resulting from the last
+      call to <command>nixos-rebuild switch</command> or
+      <command>nixos-rebuild boot</command>).</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>build</option></term>
+    <listitem>
+      <para>Build the new configuration, but neither activate it nor
+      add it to the GRUB boot menu.  It leaves a symlink named
+      <filename>result</filename> in the current directory, which
+      points to the output of the top-level “system” derivation.  This
+      is essentially the same as doing
+<screen>
+$ nix-build /etc/nixos/nixos -A system
+</screen>
+      Note that you do not need to be <literal>root</literal> to run
+      <command>nixos-rebuild build</command>.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>dry-run</option></term>
+    <listitem>
+      <para>Simply show what store paths would be built or downloaded
+      by any of the operations above.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>build-vm</option></term>
+    <listitem>
+      <para>Build a script that starts a NixOS virtual machine with
+      the desired configuration.  It leaves a symlink
+      <filename>result</filename> in the current directory that points
+      (under
+      <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>)
+      at the script that starts the VM.  Thus, to test a NixOS
+      configuration in a virtual machine, you should do the following:
+<screen>
+$ nixos-rebuild build-vm
+$ ./result/bin/run-*-vm
+</screen></para>
+
+      <para>The VM is implemented using the <literal>qemu</literal>
+      package.  For best performance, you should load the
+      <literal>kvm-intel</literal> or <literal>kvm-amd</literal>
+      kernel modules to get hardware virtualisation.</para>
+
+      <para>The VM mounts the Nix store of the host through the 9P
+      file system.  The host Nix store is read-only, so Nix commands
+      that modify the Nix store will not work in the VM.  This
+      includes commands such as <command>nixos-rebuild</command>; to
+      change the VM’s configuration, you must halt the VM and re-run
+      the commands above.
+      </para>
+
+      <para>The VM has its own <literal>ext3</literal> root file
+      system, which is automatically created when the VM is first
+      started, and is persistent across reboots of the VM.  It is
+      stored in
+      <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.
+      <!-- The entire file system hierarchy of the host is available in
+      the VM under <filename>/hostfs</filename>.--></para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>build-vm-with-bootloader</option></term>
+    <listitem>
+      <para>Like <option>build-vm</option>, but boots using the
+      regular boot loader of your configuration (e.g., GRUB 1 or 2),
+      rather than booting directly into the kernel and initial ramdisk
+      of the system.  This allows you to test whether the boot loader
+      works correctly.  However, it does not guarantee that your NixOS
+      configuration will boot successfully on the host hardware (i.e.,
+      after running <command>nixos-rebuild switch</command>), because
+      the hardware and boot loader configuration in the VM are
+      different.  The boot loader is installed on an automatically
+      generated virtual disk containing a <filename>/boot</filename>
+      partition, which is mounted read-only in the VM.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<para>This command accepts the following options:</para>
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>--upgrade</option></term>
+    <listitem>
+      <para>Fetch the latest version of NixOS from the NixOS
+      channel.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--install-grub</option></term>
+    <listitem>
+      <para>Causes the GRUB boot loader to be (re)installed on the
+      device specified by the
+      <varname>boot.loader.grub.device</varname> configuration
+      option.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--no-build-nix</option></term>
+    <listitem>
+      <para>Normally, <command>nixos-rebuild</command> first builds
+      the <varname>nixUnstable</varname> attribute in Nixpkgs, and
+      uses the resulting instance of the Nix package manager to build
+      the new system configuration.  This is necessary if the NixOS
+      modules use features not provided by the currently installed
+      version of Nix.  This option disables building a new Nix.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--fast</option></term>
+    <listitem>
+      <para>Equivalent to <option>--no-build-nix</option>
+      <option>--show-trace</option>.  This option is useful if you
+      call <command>nixos-rebuild</command> frequently (e.g. if you’re
+      hacking on a NixOS module).</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--rollback</option></term>
+    <listitem>
+      <para>Instead of building a new configuration as specified by
+      <filename>/etc/nixos/configuration.nix</filename>, roll back to
+      the previous configuration.  (The previous configuration is
+      defined as the one before the “current” generation of the
+      profile <filename>/nix/var/nix/profiles/system</filename>.)</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+<para>In addition, <command>nixos-rebuild</command> accepts various
+Nix-related flags, including <option>--max-jobs</option> /
+<option>-j</option>, <option>--show-trace</option>,
+<option>--keep-failed</option>, <option>--keep-going</option> and
+<option>--verbose</option> / <option>-v</option>.  See
+the Nix manual for details.</para>
+
+</refsection>
+
+
+<refsection><title>Environment</title>
+
+<variablelist>
+
+  <varlistentry>
+    <term><envar>NIXOS_CONFIG</envar></term>
+    <listitem>
+      <para>Path to the main NixOS configuration module.  Defaults to
+      <filename>/etc/nixos/configuration.nix</filename>.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Files</title>
+
+<variablelist>
+
+  <varlistentry>
+    <term><filename>/run/current-system</filename></term>
+    <listitem>
+      <para>A symlink to the currently active system configuration in
+      the Nix store.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><filename>/nix/var/nix/profiles/system</filename></term>
+    <listitem>
+      <para>The Nix profile that contains the current and previous
+      system configurations.  Used to generate the GRUB boot
+      menu.</para>
+    </listitem>
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Bugs</title>
+
+<para>This command should be renamed to something more
+descriptive.</para>
+
+</refsection>
+
+
+
+</refentry>
diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml
new file mode 100644
index 00000000000..7840e1b897b
--- /dev/null
+++ b/nixos/doc/manual/man-pages.xml
@@ -0,0 +1,31 @@
+<reference xmlns="http://docbook.org/ns/docbook"
+           xmlns:xlink="http://www.w3.org/1999/xlink"
+           xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <title>NixOS Reference Pages</title>
+
+  <info>
+
+    <author>
+      <personname>
+        <firstname>Eelco</firstname>
+        <surname>Dolstra</surname>
+      </personname>
+      <contrib>Author</contrib>
+    </author>
+
+    <copyright>
+      <year>2007</year>
+      <year>2008</year>
+      <year>2009</year>
+      <holder>Eelco Dolstra</holder>
+    </copyright>
+    
+  </info>
+  
+  <xi:include href="man-configuration.xml" />
+  <xi:include href="man-nixos-rebuild.xml" />
+  <xi:include href="man-nixos-option.xml" />
+  <xi:include href="man-nixos-build-vms.xml" />
+  
+</reference>
diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml
new file mode 100644
index 00000000000..7d6634bf093
--- /dev/null
+++ b/nixos/doc/manual/manual.xml
@@ -0,0 +1,62 @@
+<book xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <info>
+
+    <title>NixOS Manual</title>
+
+    <author>
+      <personname>
+        <firstname>Eelco</firstname>
+        <surname>Dolstra</surname>
+      </personname>
+    </author>
+
+    <author>
+      <personname>
+        <firstname>Nicolas</firstname>
+        <surname>Pierron</surname>
+      </personname>
+    </author>
+
+    <copyright>
+      <year>2007-2013</year>
+      <holder>Eelco Dolstra</holder>
+    </copyright>
+
+  </info>
+
+
+  <preface>
+    <title>Preface</title>
+
+    <para>This manual describes how to install, use and extend NixOS,
+    a Linux distribution based on the purely functional package
+    management system Nix.</para>
+
+    <para>If you encounter problems, please report them on the
+    <literal
+    xlink:href="http://lists.science.uu.nl/mailman/listinfo/nix-dev">nix-dev@lists.science.uu.nl</literal>
+    mailing list or on the <link
+    xlink:href="irc://irc.freenode.net/#nixos">
+    <literal>#nixos</literal> channel on Freenode</link>.  Bugs should
+    be reported in <link
+    xlink:href="https://github.com/NixOS/nixos/issues">NixOS’ GitHub
+    issue tracker</link>.</para>
+
+  </preface>
+
+
+  <xi:include href="installation.xml" />
+  <xi:include href="configuration.xml" />
+  <xi:include href="running.xml" />
+  <!-- <xi:include href="userconfiguration.xml" /> -->
+  <xi:include href="troubleshooting.xml" />
+  <xi:include href="development.xml" />
+  <chapter xml:id="ch-options">
+    <title>List of Options</title>
+    <xi:include href="options-db.xml" />
+  </chapter>
+
+</book>
diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl
new file mode 100644
index 00000000000..adc6c93c722
--- /dev/null
+++ b/nixos/doc/manual/options-to-docbook.xsl
@@ -0,0 +1,187 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet version="1.0"
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:str="http://exslt.org/strings"
+                xmlns:xlink="http://www.w3.org/1999/xlink"
+                xmlns="http://docbook.org/ns/docbook"
+                extension-element-prefixes="str"
+                >
+
+  <xsl:output method='xml' encoding="UTF-8" />
+
+  <xsl:param name="revision" />
+
+
+  <xsl:template match="/expr/list">
+
+      <variablelist>
+
+        <xsl:for-each select="attrs">
+
+          <varlistentry>
+             <term>
+               <option>
+                 <xsl:for-each select="attr[@name = 'name']/string">
+                   <xsl:value-of select="@value" />
+                   <xsl:if test="position() != last()">.</xsl:if>
+                 </xsl:for-each>
+               </option>
+             </term>
+
+             <listitem>
+
+               <para>
+                 <xsl:value-of disable-output-escaping="yes"
+                               select="attr[@name = 'description']/string/@value" />
+               </para>
+
+               <para>
+                 <emphasis>Default:</emphasis>
+                 <xsl:text> </xsl:text>
+                 <xsl:choose>
+                   <xsl:when test="attr[@name = 'default']">
+                     <literal>
+                       <xsl:apply-templates select="attr[@name = 'default']" />
+                     </literal>
+                   </xsl:when>
+                   <xsl:otherwise>
+                     none
+                   </xsl:otherwise>
+                 </xsl:choose>
+               </para>
+
+               <xsl:if test="attr[@name = 'example']">
+
+                 <para>
+                   <emphasis>Example:</emphasis>
+                   <xsl:text> </xsl:text>
+                   <xsl:choose>
+                     <xsl:when test="attr[@name = 'example']/attrs[attr[@name = '_type' and string[@value = 'literalExample']]]">
+                       <programlisting><xsl:value-of select="attr[@name = 'example']/attrs/attr[@name = 'text']/string/@value" /></programlisting>
+                     </xsl:when>
+                     <xsl:otherwise>
+                       <literal>
+                         <xsl:apply-templates select="attr[@name = 'example']" />
+                       </literal>
+                     </xsl:otherwise>
+                   </xsl:choose>
+                 </para>
+               </xsl:if>
+
+               <xsl:if test="count(attr[@name = 'declarations']/list/*) != 0">
+                 <para>
+                   <emphasis>Declared by:</emphasis>
+                 </para>
+                 <xsl:apply-templates select="attr[@name = 'declarations']" />
+               </xsl:if>
+
+               <xsl:if test="count(attr[@name = 'definitions']/list/*) != 0">
+                 <para>
+                   <emphasis>Defined by:</emphasis>
+                 </para>
+                 <xsl:apply-templates select="attr[@name = 'definitions']" />
+               </xsl:if>
+
+             </listitem>
+
+          </varlistentry>
+
+        </xsl:for-each>
+
+      </variablelist>
+
+  </xsl:template>
+
+
+  <xsl:template match="string">
+    <!-- !!! escaping -->
+    <xsl:text>"</xsl:text><xsl:value-of select="str:replace(str:replace(str:replace(@value, '\', '\\'), '&quot;', '\&quot;'), '&#010;', '\n')" /><xsl:text>"</xsl:text>
+  </xsl:template>
+
+
+  <xsl:template match="int">
+    <xsl:value-of select="@value" />
+  </xsl:template>
+
+
+  <xsl:template match="bool[@value = 'true']">
+    <xsl:text>true</xsl:text>
+  </xsl:template>
+
+
+  <xsl:template match="bool[@value = 'false']">
+    <xsl:text>false</xsl:text>
+  </xsl:template>
+
+
+  <xsl:template match="list">
+    [
+    <xsl:for-each select="*">
+      <xsl:apply-templates select="." />
+      <xsl:text> </xsl:text>
+    </xsl:for-each>
+    ]
+  </xsl:template>
+
+
+  <xsl:template match="attrs">
+    {
+    <xsl:for-each select="attr">
+      <xsl:value-of select="@name" />
+      <xsl:text> = </xsl:text>
+      <xsl:apply-templates select="*" /><xsl:text>; </xsl:text>
+    </xsl:for-each>
+    }
+  </xsl:template>
+
+
+  <xsl:template match="derivation">
+    <xsl:choose>
+      <xsl:when test="attr[@name = 'url']/string/@value">
+        <replaceable>(download of <xsl:value-of select="attr[@name = 'url']/string/@value" />)</replaceable>
+      </xsl:when>
+      <xsl:otherwise>
+        <replaceable>(build of <xsl:value-of select="attr[@name = 'name']/string/@value" />)</replaceable>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <xsl:template match="attr[@name = 'declarations' or @name = 'definitions']">
+    <simplelist>
+      <xsl:for-each select="list/string">
+        <member><filename>
+          <!-- Hyperlink the filename either to the NixOS Subversion
+          repository (if it’s a module and we have a revision number),
+          or to the local filesystem. -->
+          <xsl:choose>
+            <xsl:when test="$revision != 'local' and contains(@value, '/modules/')">
+              <xsl:attribute name="xlink:href">https://github.com/NixOS/nixos/blob/<xsl:value-of select="$revision"/>/modules/<xsl:value-of select="substring-after(@value, '/modules/')"/></xsl:attribute>
+            </xsl:when>
+            <xsl:when test="$revision != 'local' and contains(@value, 'nixops') and contains(@value, '/nix/')">
+              <xsl:attribute name="xlink:href">https://github.com/NixOS/nixops/blob/<xsl:value-of select="$revision"/>/nix/<xsl:value-of select="substring-after(@value, '/nix/')"/></xsl:attribute>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:attribute name="xlink:href">file://<xsl:value-of select="@value"/></xsl:attribute>
+            </xsl:otherwise>
+          </xsl:choose>
+          <!-- Print the filename and make it user-friendly by replacing the
+          /nix/store/<hash> prefix by the default location of nixos
+          sources. -->
+          <xsl:choose>
+            <xsl:when test="contains(@value, '/modules/')">
+              &lt;nixos/modules/<xsl:value-of select="substring-after(@value, '/modules/')"/>&gt;
+            </xsl:when>
+            <xsl:when test="contains(@value, 'nixops') and contains(@value, '/nix/')">
+              &lt;nixops/<xsl:value-of select="substring-after(@value, '/nix/')"/>&gt;
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:value-of select="@value" />
+            </xsl:otherwise>
+          </xsl:choose>
+        </filename></member>
+      </xsl:for-each>
+    </simplelist>
+  </xsl:template>
+
+</xsl:stylesheet>
diff --git a/nixos/doc/manual/running.xml b/nixos/doc/manual/running.xml
new file mode 100644
index 00000000000..e50099707cc
--- /dev/null
+++ b/nixos/doc/manual/running.xml
@@ -0,0 +1,369 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="ch-running">
+
+<title>Running NixOS</title>
+
+<para>This chapter describes various aspects of managing a running
+NixOS system, such as how to use the <command>systemd</command>
+service manager.</para>
+
+
+<!--===============================================================-->
+
+<section><title>Service management</title>
+
+<para>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 <literal>default.target</literal>; 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.</para>
+
+<para>The command <command>systemctl</command> is the main way to
+interact with <command>systemd</command>.  Without any arguments, it
+shows the status of active units:
+
+<screen>
+$ 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
+<replaceable>...</replaceable>
+</screen>
+
+</para>
+
+<para>You can ask for detailed status information about a unit, for
+instance, the PostgreSQL database service:
+
+<screen>
+$ 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.
+</screen>
+
+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.
+
+</para>
+
+<para>Units can be stopped, started or restarted:
+
+<screen>
+$ systemctl stop postgresql.service
+$ systemctl start postgresql.service
+$ systemctl restart postgresql.service
+</screen>
+
+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).</para>
+
+<!-- - cgroups: each service and user session is a cgroup
+
+- cgroup resource management -->
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Rebooting and shutting down</title>
+
+<para>The system can be shut down (and automatically powered off) by
+doing:
+
+<screen>
+$ shutdown
+</screen>
+
+This is equivalent to running <command>systemctl
+poweroff</command>.</para>
+
+<para>To reboot the system, run
+
+<screen>
+$ reboot
+</screen>
+
+which is equivalent to <command>systemctl reboot</command>.
+Alternatively, you can quickly reboot the system using
+<literal>kexec</literal>, which bypasses the BIOS by directly loading
+the new kernel into memory:
+
+<screen>
+$ systemctl kexec
+</screen>
+
+</para>
+
+<para>The machine can be suspended to RAM (if supported) using
+<command>systemctl suspend</command>, and suspended to disk using
+<command>systemctl hibernate</command>.</para>
+
+<para>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.</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>User sessions</title>
+
+<para>Systemd keeps track of all users who are logged into the system
+(e.g. on a virtual console or remotely via SSH).  The command
+<command>loginctl</command> allows querying and manipulating user
+sessions.  For instance, to list all user sessions:
+
+<screen>
+$ loginctl
+   SESSION        UID USER             SEAT
+        c1        500 eelco            seat0
+        c3          0 root             seat0
+        c4        500 alice
+</screen>
+
+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:
+
+<screen>
+$ 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
+</screen>
+
+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:
+
+<screen>
+$ loginctl terminate-session c3
+</screen>
+
+</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Control groups</title>
+
+<para>To keep track of the processes in a running system, systemd uses
+<emphasis>control groups</emphasis> (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.</para>
+
+<para>The command <command>systemd-cgls</command> lists all control
+groups in the <literal>systemd</literal> hierarchy, which is what
+systemd uses to keep track of the processes belonging to each service
+or user session:
+
+<screen>
+$ systemd-cgls
+├─user
+│ └─eelco
+│   └─c1
+│     ├─ 2567 -:0
+│     ├─ 2682 kdeinit4: kdeinit4 Running...
+│     ├─ <replaceable>...</replaceable>
+│     └─10851 sh -c less -R
+└─system
+  ├─httpd.service
+  │ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH
+  │ └─<replaceable>...</replaceable>
+  ├─dhcpcd.service
+  │ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf
+  └─ <replaceable>...</replaceable>
+</screen>
+
+Similarly, <command>systemd-cgls cpu</command> 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
+<literal>httpd.service</literal> cgroup cannot starve the CPU for one
+process in the <literal>postgresql.service</literal> 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 <filename>configuration.nix</filename>:
+
+<programlisting>
+systemd.services.httpd.serviceConfig.CPUShares = 512;
+</programlisting>
+
+By default, every cgroup has 1024 CPU shares, so this will halve the
+CPU allocation of the <literal>httpd.service</literal> cgroup.</para>
+
+<para>There also is a <literal>memory</literal> 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
+<filename>configuration.nix</filename>; for instance, to limit
+<literal>httpd.service</literal> to 512 MiB of RAM (excluding swap)
+and 640 MiB of RAM (including swap):
+
+<programlisting>
+systemd.services.httpd.serviceConfig.MemoryLimit = "512M";
+systemd.services.httpd.serviceConfig.ControlGroupAttribute = [ "memory.memsw.limit_in_bytes 640M" ];
+</programlisting>
+
+</para>
+
+<para>The command <command>systemd-cgtop</command> shows a
+continuously updated list of all cgroups with their CPU and memory
+usage.</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Logging</title>
+
+<para>System-wide logging is provided by systemd’s
+<emphasis>journal</emphasis>, which subsumes traditional logging
+daemons such as syslogd and klogd.  Log entries are kept in binary
+files in <filename>/var/log/journal/</filename>.  The command
+<literal>journalctl</literal> allows you to see the contents of the
+journal.  For example,
+
+<screen>
+$ journalctl -b
+</screen>
+
+shows all journal entries since the last reboot.  (The output of
+<command>journalctl</command> is piped into <command>less</command> 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:
+
+<screen>
+$ 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
+</screen>
+
+Or to get all messages since the last reboot that have at least a
+“critical” severity level:
+
+<screen>
+$ 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)
+</screen>
+
+</para>
+
+<para>The system journal is readable by root and by users in the
+<literal>wheel</literal> and <literal>systemd-journal</literal>
+groups.  All users have a private journal that can be read using
+<command>journalctl</command>.</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Cleaning up the Nix store</title>
+
+<para>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 (<filename>/nix/store</filename>).
+You should periodically run Nix’s <emphasis>garbage
+collector</emphasis> to remove old, unreferenced packages.  This is
+easy:
+
+<screen>
+$ nix-collect-garbage
+</screen>
+
+Alternatively, you can use a systemd unit that does the same in the
+background:
+
+<screen>
+$ systemctl start nix-gc.service
+</screen>
+
+You can tell NixOS in <filename>configuration.nix</filename> to run
+this unit automatically at certain points in time, for instance, every
+night at 03:15:
+
+<programlisting>
+nix.gc.automatic = true;
+nix.gc.dates = "03:15";
+</programlisting>
+
+</para>
+
+<para>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:
+<screen>
+$ nix-collect-garbage -d
+</screen>
+You can also do this for specific profiles, e.g.
+<screen>
+$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old
+</screen>
+Note that NixOS system configurations are stored in the profile
+<filename>/nix/var/nix/profiles/system</filename>.</para>
+
+<para>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.
+<screen>
+$ nix-store --optimise
+</screen>
+Since this command needs to read the entire Nix store, it can take
+quite a while to finish.</para>
+
+</section>
+
+
+</chapter>
diff --git a/nixos/doc/manual/style.css b/nixos/doc/manual/style.css
new file mode 100644
index 00000000000..e2204c159e2
--- /dev/null
+++ b/nixos/doc/manual/style.css
@@ -0,0 +1,268 @@
+/* Copied from http://bakefile.sourceforge.net/, which appears
+   licensed under the GNU GPL. */
+
+
+/***************************************************************************
+                             Basic headers and text:
+ ***************************************************************************/
+
+body
+{
+    font-family: "Nimbus Sans L", sans-serif;
+    background: white;
+    margin: 2em 1em 2em 1em;
+}
+
+h1, h2, h3, h4
+{
+    color: #005aa0;
+}
+
+h1 /* title */
+{
+    font-size: 200%;
+}
+
+h2 /* chapters, appendices, subtitle */
+{
+    font-size: 180%;
+}
+
+/* Extra space between chapters, appendices. */
+div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 
+{ 
+    margin-top: 1.5em;
+}
+
+div.section > div.titlepage h2 /* sections */
+{
+    font-size: 150%;
+    margin-top: 1.5em;
+}
+
+h3 /* subsections */
+{
+    font-size: 125%;
+}
+
+div.simplesect h2
+{
+    font-size: 110%;
+}
+
+div.appendix h3
+{
+    font-size: 150%;
+    margin-top: 1.5em;
+}
+
+div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */
+{
+    margin-top: 1.4em;
+    font-size: 125%;
+}
+
+div.refsection h3
+{
+    font-size: 110%;
+}
+
+
+/***************************************************************************
+                               Examples:
+ ***************************************************************************/
+
+div.example
+{
+    border: 1px solid #b0b0b0;
+    padding: 6px 6px;
+    margin-left: 1.5em;
+    margin-right: 1.5em;
+    background: #f4f4f8;
+    border-radius: 0.4em;
+    box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
+}
+
+div.example p.title
+{
+    margin-top: 0em;
+}
+
+div.example pre
+{
+    box-shadow: none;
+}
+
+
+/***************************************************************************
+                            Screen dumps:
+ ***************************************************************************/
+
+pre.screen, pre.programlisting
+{
+    border: 1px solid #b0b0b0;
+    padding: 3px 3px;
+    margin-left: 1.5em;
+    margin-right: 1.5em;
+    color: #600000;
+    background: #f4f4f8;
+    font-family: monospace;
+    border-radius: 0.4em;
+    box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
+}
+
+div.example pre.programlisting
+{
+    border: 0px;
+    padding: 0 0;
+    margin: 0 0 0 0;
+}
+
+
+/***************************************************************************
+                               Notes, warnings etc:
+ ***************************************************************************/
+
+.note, .warning
+{
+    border: 1px solid #b0b0b0;
+    padding: 3px 3px;
+    margin-left: 1.5em;
+    margin-right: 1.5em;
+    margin-bottom: 1em;
+    padding: 0.3em 0.3em 0.3em 0.3em;
+    background: #fffff5;
+    border-radius: 0.4em;
+    box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
+}
+
+div.note, div.warning
+{
+    font-style: italic;
+}
+
+div.note h3, div.warning h3
+{
+    color: red;
+    font-size: 100%;
+    padding-right: 0.5em;
+    display: inline;
+}
+
+div.note p, div.warning p
+{
+    margin-bottom: 0em;
+}
+
+div.note h3 + p, div.warning h3 + p
+{
+    display: inline;
+}
+
+div.note h3
+{
+    color: blue;
+    font-size: 100%;
+}
+
+div.navfooter *
+{
+    font-size: 90%;
+}
+
+
+/***************************************************************************
+                        Links colors and highlighting: 
+ ***************************************************************************/
+
+a { text-decoration: none; }
+a:hover { text-decoration: underline; }
+a:link { color: #0048b3; }
+a:visited { color: #002a6a; }
+
+
+/***************************************************************************
+                              Table of contents:
+ ***************************************************************************/
+
+div.toc
+{
+    font-size: 90%;
+}
+
+div.toc dl
+{
+    margin-top: 0em;
+    margin-bottom: 0em;
+}
+
+
+/***************************************************************************
+                               Special elements:
+ ***************************************************************************/
+
+tt, code
+{
+    color: #400000;
+}
+
+.term
+{
+    font-weight: bold;
+    
+}
+
+div.variablelist dd p, div.glosslist dd p
+{
+    margin-top: 0em;
+}
+
+div.variablelist dd, div.glosslist dd
+{
+    margin-left: 1.5em;
+}
+
+div.glosslist dt
+{
+    font-style: italic;
+}
+
+.varname
+{
+    color: #400000;
+}
+
+span.command strong
+{
+    font-weight: normal;
+    color: #400000;
+}
+
+div.calloutlist table
+{
+    box-shadow: none;
+}
+
+table
+{
+    border-collapse: collapse;
+    box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
+}
+
+table.simplelist
+{
+    text-align: left;
+    color: #005aa0;
+    border: 0;
+    padding: 5px;
+    background: #fffff5;
+    font-weight: normal;
+    font-style: italic;
+    box-shadow: none;
+    margin-bottom: 1em;
+}
+
+div.affiliation
+{
+    font-style: italic;
+}
\ No newline at end of file
diff --git a/nixos/doc/manual/troubleshooting.xml b/nixos/doc/manual/troubleshooting.xml
new file mode 100644
index 00000000000..c6e0a3a7888
--- /dev/null
+++ b/nixos/doc/manual/troubleshooting.xml
@@ -0,0 +1,198 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Troubleshooting</title>
+
+
+<!--===============================================================-->
+
+<section><title>Boot problems</title>
+
+<para>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
+<literal>linux</literal>.  The following are some useful kernel command
+line parameters that are recognised by the NixOS boot scripts or by
+systemd:
+
+<variablelist>
+
+  <varlistentry><term><literal>boot.shell_on_fail</literal></term>
+    <listitem><para>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.</para></listitem>
+  </varlistentry>
+
+  <varlistentry><term><literal>boot.debug1</literal></term>
+    <listitem><para>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
+    <filename>/proc</filename> and
+    <filename>/sys</filename>.</para></listitem>
+  </varlistentry>
+
+  <varlistentry><term><literal>boot.trace</literal></term>
+    <listitem><para>Print every shell command executed by the stage 1
+    and 2 boot scripts.</para></listitem>
+  </varlistentry>
+
+  <varlistentry><term><literal>single</literal></term>
+    <listitem><para>Boot into rescue mode (a.k.a. single user mode).
+    This will cause systemd to start nothing but the unit
+    <literal>rescue.target</literal>, which runs
+    <command>sulogin</command> 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.</para></listitem>
+  </varlistentry>
+
+  <varlistentry><term><literal>systemd.log_level=debug systemd.log_target=console</literal></term>
+    <listitem><para>Make systemd very verbose and send log messages to
+    the console instead of the journal.</para></listitem>
+  </varlistentry>
+
+</variablelist>
+
+For more parameters recognised by systemd, see
+<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+
+<para>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 <command>agetty</command> login prompts should appear eventually
+unless something is very wrong.)</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Maintenance mode</title>
+
+<para>You can enter rescue mode by running:
+
+<screen>
+$ systemctl rescue</screen>
+
+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.</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Rolling back configuration changes</title>
+
+<para>After running <command>nixos-rebuild</command> 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.</para>
+
+<para>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:
+
+<screen>
+$ /run/current-system/bin/switch-to-configuration boot</screen>
+
+</para>
+
+<para>Second, you can switch to the previous configuration in a running
+system:
+
+<screen>
+$ nixos-rebuild switch --rollback</screen>
+
+This is equivalent to running:
+
+<screen>
+$ /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
+
+where <replaceable>N</replaceable> is the number of the NixOS system
+configuration.  To get a list of the available configurations, do:
+
+<screen>
+$ ls -l /nix/var/nix/profiles/system-*-link
+<replaceable>...</replaceable>
+lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
+</screen>
+
+</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Nix store corruption</title>
+
+<para>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
+<command>sync</command> 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.</para>
+
+<para>If the corruption is in a path in the closure of the NixOS
+system configuration, you can fix it by doing
+
+<screen>
+$ nixos-rebuild switch --repair
+</screen>
+
+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.</para>
+
+<para>You can also scan the entire Nix store for corrupt paths:
+
+<screen>
+$ nix-store --verify --check-contents --repair
+</screen>
+
+Any corrupt paths will be redownloaded if they’re available in a
+binary cache; otherwise, they cannot be repaired.</para>
+
+</section>
+
+
+<!--===============================================================-->
+
+<section><title>Nix network issues</title>
+
+<para>Nix uses a so-called <emphasis>binary cache</emphasis> to
+optimise building a package from source into downloading it as a
+pre-built binary.  That is, whenever a command like
+<command>nixos-rebuild</command> 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
+<uri>http://cache.nixos.org/</uri>.  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>--option
+use-binary-caches false</option>, e.g.
+
+<screen>
+$ nixos-rebuild switch --option use-binary-caches false
+</screen>
+
+If you have an alternative binary cache at your disposal, you can use
+it instead:
+
+<screen>
+$ nixos-rebuild switch --option binary-caches http://my-cache.example.org/
+</screen>
+
+</para>
+
+</section>
+
+
+</chapter>
diff --git a/nixos/doc/manual/userconfiguration.xml b/nixos/doc/manual/userconfiguration.xml
new file mode 100644
index 00000000000..7c6540caf3a
--- /dev/null
+++ b/nixos/doc/manual/userconfiguration.xml
@@ -0,0 +1,80 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Configuration in home directory</title>
+
+
+<!--===============================================================-->
+
+<section>
+<title>Compiz Fusion</title>
+<para>
+	Compiz Fusion is just a set of plugins for 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 
+	/run/current-system/sw/share.
+
+	<orderedlist>
+	<listitem><para><filename>$HOME/.compiz/plugins</filename> 
+	should contain plugins you want to load. All the installed 
+	plugins are available in 
+	<filename>/run/current-system/sw/share/compiz-plugins/compiz/</filename>,
+	so you can use symlinks to this directory.
+	</para></listitem>
+
+	<listitem><para><filename>$HOME/.compiz/metadata</filename> 
+	should contain metadata (definition of configuration options) for plugins 
+	you want to load. All the installed metadata is available in 
+	<filename>/run/current-system/sw/share/compiz/</filename>,
+	so you can use symlinks to this directory.
+	</para></listitem>
+
+	<listitem><para>
+	Probably a way to load <literal>GConf</literal> configuration backend by default 
+	should be found, but if you run <literal>Compiz</literal> with 
+	<literal>GConf</literal> configuration (default for <literal>X server</literal> job
+	for now), you have to link 
+	<filename>/run/current-system/sw/share/compizconfig/backends/</filename>
+	into <filename>$HOME/.compizconfig/backends</filename> directory.
+	</para></listitem>
+
+	</orderedlist>
+
+        To summarize the above, these are the commands you have to execute
+        <command>ln -s /run/current-system/sw/share/compiz/ $HOME/.compiz/metadata</command>
+        <command>ln -s /run/current-system/sw/share/compiz-plugins/compiz/ $HOME/.compiz/plugins</command>
+        <command>ln -s /run/current-system/sw/share/compizconfig/backends/ $HOME/.compizconfig/backends</command>
+
+	Now you can launch <literal>ccsm</literal> and configure everything. You should select
+	GConf as a backend in the preferences menu of <literal>ccsm</literal>
+</para>
+</section>
+
+<section>
+<title>Pidgin-LaTeX</title>
+<para>
+	To have pidgin-latex plugin working after installation, you need the following:
+	<orderedlist>
+	<listitem><para>
+	Symlink <filename>/run/current-system/sw/share/pidgin-latex/pidgin-latex.so</filename>
+	to <filename>$HOME/.purple/plugins/pidgin-latex.so</filename>
+	</para></listitem>
+	<listitem><para>
+	Enable smileys. If you do not want to, you can create 
+	<filename>$HOME/.purple/smileys/empty/theme</filename> with the following contents: 
+	<programlisting>
+	Name=Empty
+	Description=No predefined smileys
+	Author=Nobody
+	</programlisting>	
+	Enabling this theme will enable smileys, but define none.
+	</para></listitem>
+	<listitem><para>
+	Enable the plugin.
+	</para></listitem>	
+	</orderedlist>	
+	</para>
+	</section>
+
+</chapter>