Last good Nixpkgs for Weston+nouveau? archive

I came this commit hash to terwiz[m] on IRC, who is trying to figure out
what the last version of Spectrum that worked on their NUC with Nvidia
graphics is.

9 files changed, 1560 insertions, 0 deletions

diff --git a/nixos/doc/manual/from_md/installation/changing-config.chapter.xml b/nixos/doc/manual/from_md/installation/changing-config.chapter.xml
new file mode 100644
index 00000000000..86f0b15b41c
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/changing-config.chapter.xml
@@ -0,0 +1,117 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-changing-config">
+  <title>Changing the Configuration</title>
+  <para>
+    The file <literal>/etc/nixos/configuration.nix</literal> contains
+    the current configuration of your machine. Whenever you’ve
+    <link linkend="ch-configuration">changed something</link> in that
+    file, you should do
+  </para>
+  <programlisting>
+# nixos-rebuild switch
+</programlisting>
+  <para>
+    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>
+  <warning>
+    <para>
+      This command doesn't start/stop
+      <link linkend="opt-systemd.user.services">user services</link>
+      automatically. <literal>nixos-rebuild</literal> only runs a
+      <literal>daemon-reload</literal> for each user with running user
+      services.
+    </para>
+  </warning>
+  <warning>
+    <para>
+      These commands must be executed as root, so you should either run
+      them from a root shell or by prefixing them with
+      <literal>sudo -i</literal>.
+    </para>
+  </warning>
+  <para>
+    You can also do
+  </para>
+  <programlisting>
+# nixos-rebuild test
+</programlisting>
+  <para>
+    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
+  </para>
+  <programlisting>
+# nixos-rebuild boot
+</programlisting>
+  <para>
+    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>
+    You can make your configuration show up in a different submenu of
+    the GRUB 2 boot screen by giving it a different <emphasis>profile
+    name</emphasis>, e.g.
+  </para>
+  <programlisting>
+# nixos-rebuild switch -p test
+</programlisting>
+  <para>
+    which causes the new configuration (and previous ones created using
+    <literal>-p test</literal>) to show up in the GRUB submenu
+    <quote>NixOS - Profile 'test'</quote>. This can be useful to
+    separate test configurations from <quote>stable</quote>
+    configurations.
+  </para>
+  <para>
+    Finally, you can do
+  </para>
+  <programlisting>
+$ nixos-rebuild build
+</programlisting>
+  <para>
+    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 QEMU <emphasis>virtual machine</emphasis> that contains the
+    desired configuration. Just do
+  </para>
+  <programlisting>
+$ nixos-rebuild build-vm
+$ ./result/bin/run-*-vm
+</programlisting>
+  <para>
+    The VM does not have any data from your host system, so your
+    existing user accounts and home directories will not be available
+    unless you have set <literal>mutableUsers = false</literal>. Another
+    way is to temporarily add the following to your configuration:
+  </para>
+  <programlisting language="bash">
+users.users.your-user.initialHashedPassword = &quot;test&quot;;
+</programlisting>
+  <para>
+    <emphasis>Important:</emphasis> delete the $hostname.qcow2 file if
+    you have started the virtual machine at least once without the right
+    users, otherwise the changes will not get picked up. You can forward
+    ports on the host to the guest. For instance, the following will
+    forward host port 2222 to guest port 22 (SSH):
+  </para>
+  <programlisting>
+$ QEMU_NET_OPTS=&quot;hostfwd=tcp::2222-:22&quot; ./result/bin/run-*-vm
+</programlisting>
+  <para>
+    allowing you to log in via SSH (assuming you have set the
+    appropriate passwords or SSH authorized keys):
+  </para>
+  <programlisting>
+$ ssh -p 2222 localhost
+</programlisting>
+</chapter>
diff --git a/nixos/doc/manual/from_md/installation/installing-behind-a-proxy.section.xml b/nixos/doc/manual/from_md/installation/installing-behind-a-proxy.section.xml
new file mode 100644
index 00000000000..a551807cd47
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/installing-behind-a-proxy.section.xml
@@ -0,0 +1,41 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-installing-behind-proxy">
+  <title>Installing behind a proxy</title>
+  <para>
+    To install NixOS behind a proxy, do the following before running
+    <literal>nixos-install</literal>.
+  </para>
+  <orderedlist numeration="arabic">
+    <listitem>
+      <para>
+        Update proxy configuration in
+        <literal>/mnt/etc/nixos/configuration.nix</literal> to keep the
+        internet accessible after reboot.
+      </para>
+      <programlisting language="bash">
+networking.proxy.default = &quot;http://user:password@proxy:port/&quot;;
+networking.proxy.noProxy = &quot;127.0.0.1,localhost,internal.domain&quot;;
+</programlisting>
+    </listitem>
+    <listitem>
+      <para>
+        Setup the proxy environment variables in the shell where you are
+        running <literal>nixos-install</literal>.
+      </para>
+      <programlisting>
+# proxy_url=&quot;http://user:password@proxy:port/&quot;
+# export http_proxy=&quot;$proxy_url&quot;
+# export HTTP_PROXY=&quot;$proxy_url&quot;
+# export https_proxy=&quot;$proxy_url&quot;
+# export HTTPS_PROXY=&quot;$proxy_url&quot;
+</programlisting>
+    </listitem>
+  </orderedlist>
+  <note>
+    <para>
+      If you are switching networks with different proxy configurations,
+      use the <literal>specialisation</literal> option in
+      <literal>configuration.nix</literal> to switch proxies at runtime.
+      Refer to <xref linkend="ch-options" /> for more information.
+    </para>
+  </note>
+</section>
diff --git a/nixos/doc/manual/from_md/installation/installing-from-other-distro.section.xml b/nixos/doc/manual/from_md/installation/installing-from-other-distro.section.xml
new file mode 100644
index 00000000000..525531a4781
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/installing-from-other-distro.section.xml
@@ -0,0 +1,388 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-installing-from-other-distro">
+  <title>Installing from another Linux distribution</title>
+  <para>
+    Because Nix (the package manager) &amp; Nixpkgs (the Nix packages
+    collection) can both be installed on any (most?) Linux
+    distributions, they can be used to install NixOS in various creative
+    ways. You can, for instance:
+  </para>
+  <orderedlist numeration="arabic">
+    <listitem>
+      <para>
+        Install NixOS on another partition, from your existing Linux
+        distribution (without the use of a USB or optical device!)
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Install NixOS on the same partition (in place!), from your
+        existing non-NixOS Linux distribution using
+        <literal>NIXOS_LUSTRATE</literal>.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Install NixOS on your hard drive from the Live CD of any Linux
+        distribution.
+      </para>
+    </listitem>
+  </orderedlist>
+  <para>
+    The first steps to all these are the same:
+  </para>
+  <orderedlist numeration="arabic">
+    <listitem>
+      <para>
+        Install the Nix package manager:
+      </para>
+      <para>
+        Short version:
+      </para>
+      <programlisting>
+$ curl -L https://nixos.org/nix/install | sh
+$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell
+</programlisting>
+      <para>
+        More details in the
+        <link xlink:href="https://nixos.org/nix/manual/#chap-quick-start">
+        Nix manual</link>
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Switch to the NixOS channel:
+      </para>
+      <para>
+        If you've just installed Nix on a non-NixOS distribution, you
+        will be on the <literal>nixpkgs</literal> channel by default.
+      </para>
+      <programlisting>
+$ nix-channel --list
+nixpkgs https://nixos.org/channels/nixpkgs-unstable
+</programlisting>
+      <para>
+        As that channel gets released without running the NixOS tests,
+        it will be safer to use the <literal>nixos-*</literal> channels
+        instead:
+      </para>
+      <programlisting>
+$ nix-channel --add https://nixos.org/channels/nixos-version nixpkgs
+</programlisting>
+      <para>
+        You may want to throw in a
+        <literal>nix-channel --update</literal> for good measure.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Install the NixOS installation tools:
+      </para>
+      <para>
+        You'll need <literal>nixos-generate-config</literal> and
+        <literal>nixos-install</literal>, but this also makes some man
+        pages and <literal>nixos-enter</literal> available, just in case
+        you want to chroot into your NixOS partition. NixOS installs
+        these by default, but you don't have NixOS yet..
+      </para>
+      <programlisting>
+$ nix-env -f '&lt;nixpkgs&gt;' -iA nixos-install-tools
+</programlisting>
+    </listitem>
+    <listitem>
+      <note>
+        <para>
+          The following 5 steps are only for installing NixOS to another
+          partition. For installing NixOS in place using
+          <literal>NIXOS_LUSTRATE</literal>, skip ahead.
+        </para>
+      </note>
+      <para>
+        Prepare your target partition:
+      </para>
+      <para>
+        At this point it is time to prepare your target partition.
+        Please refer to the partitioning, file-system creation, and
+        mounting steps of <xref linkend="sec-installation" />
+      </para>
+      <para>
+        If you're about to install NixOS in place using
+        <literal>NIXOS_LUSTRATE</literal> there is nothing to do for
+        this step.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Generate your NixOS configuration:
+      </para>
+      <programlisting>
+$ sudo `which nixos-generate-config` --root /mnt
+</programlisting>
+      <para>
+        You'll probably want to edit the configuration files. Refer to
+        the <literal>nixos-generate-config</literal> step in
+        <xref linkend="sec-installation" /> for more information.
+      </para>
+      <para>
+        Consider setting up the NixOS bootloader to give you the ability
+        to boot on your existing Linux partition. For instance, if
+        you're using GRUB and your existing distribution is running
+        Ubuntu, you may want to add something like this to your
+        <literal>configuration.nix</literal>:
+      </para>
+      <programlisting language="bash">
+boot.loader.grub.extraEntries = ''
+  menuentry &quot;Ubuntu&quot; {
+    search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
+    configfile &quot;($ubuntu)/boot/grub/grub.cfg&quot;
+  }
+'';
+</programlisting>
+      <para>
+        (You can find the appropriate UUID for your partition in
+        <literal>/dev/disk/by-uuid</literal>)
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Create the <literal>nixbld</literal> group and user on your
+        original distribution:
+      </para>
+      <programlisting>
+$ sudo groupadd -g 30000 nixbld
+$ sudo useradd -u 30000 -g nixbld -G nixbld nixbld
+</programlisting>
+    </listitem>
+    <listitem>
+      <para>
+        Download/build/install NixOS:
+      </para>
+      <warning>
+        <para>
+          Once you complete this step, you might no longer be able to
+          boot on existing systems without the help of a rescue USB
+          drive or similar.
+        </para>
+      </warning>
+      <note>
+        <para>
+          On some distributions there are separate PATHS for programs
+          intended only for root. In order for the installation to
+          succeed, you might have to use
+          <literal>PATH=&quot;$PATH:/usr/sbin:/sbin&quot;</literal> in
+          the following command.
+        </para>
+      </note>
+      <programlisting>
+$ sudo PATH=&quot;$PATH&quot; NIX_PATH=&quot;$NIX_PATH&quot; `which nixos-install` --root /mnt
+</programlisting>
+      <para>
+        Again, please refer to the <literal>nixos-install</literal> step
+        in <xref linkend="sec-installation" /> for more information.
+      </para>
+      <para>
+        That should be it for installation to another partition!
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Optionally, you may want to clean up your non-NixOS
+        distribution:
+      </para>
+      <programlisting>
+$ sudo userdel nixbld
+$ sudo groupdel nixbld
+</programlisting>
+      <para>
+        If you do not wish to keep the Nix package manager installed
+        either, run something like
+        <literal>sudo rm -rv ~/.nix-* /nix</literal> and remove the line
+        that the Nix installer added to your
+        <literal>~/.profile</literal>.
+      </para>
+    </listitem>
+    <listitem>
+      <note>
+        <para>
+          The following steps are only for installing NixOS in place
+          using <literal>NIXOS_LUSTRATE</literal>:
+        </para>
+      </note>
+      <para>
+        Generate your NixOS configuration:
+      </para>
+      <programlisting>
+$ sudo `which nixos-generate-config` --root /
+</programlisting>
+      <para>
+        Note that this will place the generated configuration files in
+        <literal>/etc/nixos</literal>. You'll probably want to edit the
+        configuration files. Refer to the
+        <literal>nixos-generate-config</literal> step in
+        <xref linkend="sec-installation" /> for more information.
+      </para>
+      <para>
+        You'll likely want to set a root password for your first boot
+        using the configuration files because you won't have a chance to
+        enter a password until after you reboot. You can initalize the
+        root password to an empty one with this line: (and of course
+        don't forget to set one once you've rebooted or to lock the
+        account with <literal>sudo passwd -l root</literal> if you use
+        <literal>sudo</literal>)
+      </para>
+      <programlisting language="bash">
+users.users.root.initialHashedPassword = &quot;&quot;;
+</programlisting>
+    </listitem>
+    <listitem>
+      <para>
+        Build the NixOS closure and install it in the
+        <literal>system</literal> profile:
+      </para>
+      <programlisting>
+$ nix-env -p /nix/var/nix/profiles/system -f '&lt;nixpkgs/nixos&gt;' -I nixos-config=/etc/nixos/configuration.nix -iA system
+</programlisting>
+    </listitem>
+    <listitem>
+      <para>
+        Change ownership of the <literal>/nix</literal> tree to root
+        (since your Nix install was probably single user):
+      </para>
+      <programlisting>
+$ sudo chown -R 0.0 /nix
+</programlisting>
+    </listitem>
+    <listitem>
+      <para>
+        Set up the <literal>/etc/NIXOS</literal> and
+        <literal>/etc/NIXOS_LUSTRATE</literal> files:
+      </para>
+      <para>
+        <literal>/etc/NIXOS</literal> officializes that this is now a
+        NixOS partition (the bootup scripts require its presence).
+      </para>
+      <para>
+        <literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup
+        scripts to move <emphasis>everything</emphasis> that's in the
+        root partition to <literal>/old-root</literal>. This will move
+        your existing distribution out of the way in the very early
+        stages of the NixOS bootup. There are exceptions (we do need to
+        keep NixOS there after all), so the NixOS lustrate process will
+        not touch:
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>
+            The <literal>/nix</literal> directory
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            The <literal>/boot</literal> directory
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Any file or directory listed in
+            <literal>/etc/NIXOS_LUSTRATE</literal> (one per line)
+          </para>
+        </listitem>
+      </itemizedlist>
+      <note>
+        <para>
+          Support for <literal>NIXOS_LUSTRATE</literal> was added in
+          NixOS 16.09. The act of &quot;lustrating&quot; refers to the
+          wiping of the existing distribution. Creating
+          <literal>/etc/NIXOS_LUSTRATE</literal> can also be used on
+          NixOS to remove all mutable files from your root partition
+          (anything that's not in <literal>/nix</literal> or
+          <literal>/boot</literal> gets &quot;lustrated&quot; on the
+          next boot.
+        </para>
+        <para>
+          lustrate /ˈlʌstreɪt/ verb.
+        </para>
+        <para>
+          purify by expiatory sacrifice, ceremonial washing, or some
+          other ritual action.
+        </para>
+      </note>
+      <para>
+        Let's create the files:
+      </para>
+      <programlisting>
+$ sudo touch /etc/NIXOS
+$ sudo touch /etc/NIXOS_LUSTRATE
+</programlisting>
+      <para>
+        Let's also make sure the NixOS configuration files are kept once
+        we reboot on NixOS:
+      </para>
+      <programlisting>
+$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE
+</programlisting>
+    </listitem>
+    <listitem>
+      <para>
+        Finally, move the <literal>/boot</literal> directory of your
+        current distribution out of the way (the lustrate process will
+        take care of the rest once you reboot, but this one must be
+        moved out now because NixOS needs to install its own boot files:
+      </para>
+      <warning>
+        <para>
+          Once you complete this step, your current distribution will no
+          longer be bootable! If you didn't get all the NixOS
+          configuration right, especially those settings pertaining to
+          boot loading and root partition, NixOS may not be bootable
+          either. Have a USB rescue device ready in case this happens.
+        </para>
+      </warning>
+      <programlisting>
+$ sudo mv -v /boot /boot.bak &amp;&amp;
+sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot
+</programlisting>
+      <para>
+        Cross your fingers, reboot, hopefully you should get a NixOS
+        prompt!
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        If for some reason you want to revert to the old distribution,
+        you'll need to boot on a USB rescue disk and do something along
+        these lines:
+      </para>
+      <programlisting>
+# mkdir root
+# mount /dev/sdaX root
+# mkdir root/nixos-root
+# mv -v root/* root/nixos-root/
+# mv -v root/nixos-root/old-root/* root/
+# mv -v root/boot.bak root/boot  # We had renamed this by hand earlier
+# umount root
+# reboot
+</programlisting>
+      <para>
+        This may work as is or you might also need to reinstall the boot
+        loader.
+      </para>
+      <para>
+        And of course, if you're happy with NixOS and no longer need the
+        old distribution:
+      </para>
+      <programlisting>
+sudo rm -rf /old-root
+</programlisting>
+    </listitem>
+    <listitem>
+      <para>
+        It's also worth noting that this whole process can be automated.
+        This is especially useful for Cloud VMs, where provider do not
+        provide NixOS. For instance,
+        <link xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link>
+        uses the lustrate process to convert Digital Ocean droplets to
+        NixOS from other distributions automatically.
+      </para>
+    </listitem>
+  </orderedlist>
+</section>
diff --git a/nixos/doc/manual/from_md/installation/installing-pxe.section.xml b/nixos/doc/manual/from_md/installation/installing-pxe.section.xml
new file mode 100644
index 00000000000..94172de65ea
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/installing-pxe.section.xml
@@ -0,0 +1,42 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-booting-from-pxe">
+  <title>Booting from the <quote>netboot</quote> media (PXE)</title>
+  <para>
+    Advanced users may wish to install NixOS using an existing PXE or
+    iPXE setup.
+  </para>
+  <para>
+    These instructions assume that you have an existing PXE or iPXE
+    infrastructure and simply want to add the NixOS installer as another
+    option. To build the necessary files from your current version of
+    nixpkgs, you can run:
+  </para>
+  <programlisting>
+nix-build -A netboot.x86_64-linux '&lt;nixpkgs/nixos/release.nix&gt;'
+</programlisting>
+  <para>
+    This will create a <literal>result</literal> directory containing: *
+    <literal>bzImage</literal> – the Linux kernel *
+    <literal>initrd</literal> – the initrd file *
+    <literal>netboot.ipxe</literal> – an example ipxe script
+    demonstrating the appropriate kernel command line arguments for this
+    image
+  </para>
+  <para>
+    If you’re using plain PXE, configure your boot loader to use the
+    <literal>bzImage</literal> and <literal>initrd</literal> files and
+    have it provide the same kernel command line arguments found in
+    <literal>netboot.ipxe</literal>.
+  </para>
+  <para>
+    If you’re using iPXE, depending on how your HTTP/FTP/etc. server is
+    configured you may be able to use <literal>netboot.ipxe</literal>
+    unmodified, or you may need to update the paths to the files to
+    match your server’s directory layout.
+  </para>
+  <para>
+    In the future we may begin making these files available as build
+    products from hydra at which point we will update this documentation
+    with instructions on how to obtain them either for placing on a
+    dedicated TFTP server or to boot them directly over the internet.
+  </para>
+</section>
diff --git a/nixos/doc/manual/from_md/installation/installing-usb.section.xml b/nixos/doc/manual/from_md/installation/installing-usb.section.xml
new file mode 100644
index 00000000000..b46a1d56555
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/installing-usb.section.xml
@@ -0,0 +1,35 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-booting-from-usb">
+  <title>Booting from a USB Drive</title>
+  <para>
+    For systems without CD drive, the NixOS live CD can be booted from a
+    USB stick. You can use the <literal>dd</literal> utility to write
+    the image: <literal>dd if=path-to-image of=/dev/sdX</literal>. Be
+    careful about specifying the correct drive; you can use the
+    <literal>lsblk</literal> command to get a list of block devices.
+  </para>
+  <note>
+    <title>On macOS</title>
+    <programlisting>
+$ diskutil list
+[..]
+/dev/diskN (external, physical):
+   #:                       TYPE NAME                    SIZE       IDENTIFIER
+[..]
+$ diskutil unmountDisk diskN
+Unmount of all volumes on diskN was successful
+$ sudo dd if=nix.iso of=/dev/rdiskN
+</programlisting>
+    <para>
+      Using the 'raw' <literal>rdiskN</literal> device instead of
+      <literal>diskN</literal> completes in minutes instead of hours.
+      After <literal>dd</literal> completes, a GUI dialog &quot;The disk
+      you inserted was not readable by this computer&quot; will pop up,
+      which can be ignored.
+    </para>
+  </note>
+  <para>
+    The <literal>dd</literal> utility will write the image verbatim to
+    the drive, making it the recommended option for both UEFI and
+    non-UEFI installations.
+  </para>
+</section>
diff --git a/nixos/doc/manual/from_md/installation/installing-virtualbox-guest.section.xml b/nixos/doc/manual/from_md/installation/installing-virtualbox-guest.section.xml
new file mode 100644
index 00000000000..c8bb286c8f3
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/installing-virtualbox-guest.section.xml
@@ -0,0 +1,92 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-instaling-virtualbox-guest">
+  <title>Installing in a VirtualBox guest</title>
+  <para>
+    Installing NixOS into a VirtualBox guest is convenient for users who
+    want to try NixOS without installing it on bare metal. If you want
+    to use a pre-made VirtualBox appliance, it is available at
+    <link xlink:href="https://nixos.org/nixos/download.html">the
+    downloads page</link>. If you want to set up a VirtualBox guest
+    manually, follow these instructions:
+  </para>
+  <orderedlist numeration="arabic">
+    <listitem>
+      <para>
+        Add a New Machine in VirtualBox with OS Type &quot;Linux / Other
+        Linux&quot;
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Base Memory Size: 768 MB or higher.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        New Hard Disk of 8 GB or higher.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM)
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Click on Settings / System / Processor and enable PAE/NX
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Click on Settings / System / Acceleration and enable
+        &quot;VT-x/AMD-V&quot; acceleration
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Click on Settings / Display / Screen and select VMSVGA as
+        Graphics Controller
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Save the settings, start the virtual machine, and continue
+        installation like normal
+      </para>
+    </listitem>
+  </orderedlist>
+  <para>
+    There are a few modifications you should make in configuration.nix.
+    Enable booting:
+  </para>
+  <programlisting language="bash">
+boot.loader.grub.device = &quot;/dev/sda&quot;;
+</programlisting>
+  <para>
+    Also remove the fsck that runs at startup. It will always fail to
+    run, stopping your boot until you press <literal>*</literal>.
+  </para>
+  <programlisting language="bash">
+boot.initrd.checkJournalingFS = false;
+</programlisting>
+  <para>
+    Shared folders can be given a name and a path in the host system in
+    the VirtualBox settings (Machine / Settings / Shared Folders, then
+    click on the &quot;Add&quot; icon). Add the following to the
+    <literal>/etc/nixos/configuration.nix</literal> to auto-mount them.
+    If you do not add <literal>&quot;nofail&quot;</literal>, the system
+    will not boot properly.
+  </para>
+  <programlisting language="bash">
+{ config, pkgs, ...} :
+{
+  fileSystems.&quot;/virtualboxshare&quot; = {
+    fsType = &quot;vboxsf&quot;;
+    device = &quot;nameofthesharedfolder&quot;;
+    options = [ &quot;rw&quot; &quot;nofail&quot; ];
+  };
+}
+</programlisting>
+  <para>
+    The folder will be available directly under the root directory.
+  </para>
+</section>
diff --git a/nixos/doc/manual/from_md/installation/installing.chapter.xml b/nixos/doc/manual/from_md/installation/installing.chapter.xml
new file mode 100644
index 00000000000..db073fa8396
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/installing.chapter.xml
@@ -0,0 +1,645 @@
+<chapter xmlns="http://docbook.org/ns/docbook"  xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-installation">
+  <title>Installing NixOS</title>
+  <section xml:id="sec-installation-booting">
+    <title>Booting the system</title>
+    <para>
+      NixOS can be installed on BIOS or UEFI systems. The procedure for
+      a UEFI installation is by and large the same as a BIOS
+      installation. The differences are mentioned in the steps that
+      follow.
+    </para>
+    <para>
+      The installation media can be burned to a CD, or now more
+      commonly, <quote>burned</quote> to a USB drive (see
+      <xref linkend="sec-booting-from-usb" />).
+    </para>
+    <para>
+      The installation media contains a basic NixOS installation. When
+      it’s finished booting, it should have detected most of your
+      hardware.
+    </para>
+    <para>
+      The NixOS manual is available by running
+      <literal>nixos-help</literal>.
+    </para>
+    <para>
+      You are logged-in automatically as <literal>nixos</literal>. The
+      <literal>nixos</literal> user account has an empty password so you
+      can use <literal>sudo</literal> without a password:
+    </para>
+    <programlisting>
+$ sudo -i
+</programlisting>
+    <para>
+      If you downloaded the graphical ISO image, you can run
+      <literal>systemctl start display-manager</literal> to start the
+      desktop environment. If you want to continue on the terminal, you
+      can use <literal>loadkeys</literal> to switch to your preferred
+      keyboard layout. (We even provide neo2 via
+      <literal>loadkeys de neo</literal>!)
+    </para>
+    <para>
+      If the text is too small to be legible, try
+      <literal>setfont ter-v32n</literal> to increase the font size.
+    </para>
+    <para>
+      To install over a serial port connect with
+      <literal>115200n8</literal> (e.g.
+      <literal>picocom -b 115200 /dev/ttyUSB0</literal>). When the
+      bootloader lists boot entries, select the serial console boot
+      entry.
+    </para>
+    <section xml:id="sec-installation-booting-networking">
+      <title>Networking in the installer</title>
+      <para>
+        The boot process should have brought up networking (check
+        <literal>ip a</literal>). 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 <literal>ifconfig</literal>.
+      </para>
+      <para>
+        On the graphical installer, you can configure the network, wifi
+        included, through NetworkManager. Using the
+        <literal>nmtui</literal> program, you can do so even in a
+        non-graphical session. If you prefer to configure the network
+        manually, disable NetworkManager with
+        <literal>systemctl stop NetworkManager</literal>.
+      </para>
+      <para>
+        On the minimal installer, NetworkManager is not available, so
+        configuration must be perfomed manually. To configure the wifi,
+        first start wpa_supplicant with
+        <literal>sudo systemctl start wpa_supplicant</literal>, then run
+        <literal>wpa_cli</literal>. For most home networks, you need to
+        type in the following commands:
+      </para>
+      <programlisting>
+&gt; add_network
+0
+&gt; set_network 0 ssid &quot;myhomenetwork&quot;
+OK
+&gt; set_network 0 psk &quot;mypassword&quot;
+OK
+&gt; set_network 0 key_mgmt WPA-PSK
+OK
+&gt; enable_network 0
+OK
+</programlisting>
+      <para>
+        For enterprise networks, for example
+        <emphasis>eduroam</emphasis>, instead do:
+      </para>
+      <programlisting>
+&gt; add_network
+0
+&gt; set_network 0 ssid &quot;eduroam&quot;
+OK
+&gt; set_network 0 identity &quot;myname@example.com&quot;
+OK
+&gt; set_network 0 password &quot;mypassword&quot;
+OK
+&gt; set_network 0 key_mgmt WPA-EAP
+OK
+&gt; enable_network 0
+OK
+</programlisting>
+      <para>
+        When successfully connected, you should see a line such as this
+        one
+      </para>
+      <programlisting>
+&lt;3&gt;CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=]
+</programlisting>
+      <para>
+        you can now leave <literal>wpa_cli</literal> by typing
+        <literal>quit</literal>.
+      </para>
+      <para>
+        If you would like to continue the installation from a different
+        machine you can use activated SSH daemon. You need to copy your
+        ssh key to either
+        <literal>/home/nixos/.ssh/authorized_keys</literal> or
+        <literal>/root/.ssh/authorized_keys</literal> (Tip: For
+        installers with a modifiable filesystem such as the sd-card
+        installer image a key can be manually placed by mounting the
+        image on a different machine). Alternatively you must set a
+        password for either <literal>root</literal> or
+        <literal>nixos</literal> with <literal>passwd</literal> to be
+        able to login.
+      </para>
+    </section>
+  </section>
+  <section xml:id="sec-installation-partitioning">
+    <title>Partitioning and formatting</title>
+    <para>
+      The NixOS installer doesn’t do any partitioning or formatting, so
+      you need to do that yourself.
+    </para>
+    <para>
+      The NixOS installer ships with multiple partitioning tools. The
+      examples below use <literal>parted</literal>, but also provides
+      <literal>fdisk</literal>, <literal>gdisk</literal>,
+      <literal>cfdisk</literal>, and <literal>cgdisk</literal>.
+    </para>
+    <para>
+      The recommended partition scheme differs depending if the computer
+      uses <emphasis>Legacy Boot</emphasis> or
+      <emphasis>UEFI</emphasis>.
+    </para>
+    <section xml:id="sec-installation-partitioning-UEFI">
+      <title>UEFI (GPT)</title>
+      <para>
+        Here's an example partition scheme for UEFI, using
+        <literal>/dev/sda</literal> as the device.
+      </para>
+      <note>
+        <para>
+          You can safely ignore <literal>parted</literal>'s
+          informational message about needing to update /etc/fstab.
+        </para>
+      </note>
+      <orderedlist numeration="arabic">
+        <listitem>
+          <para>
+            Create a <emphasis>GPT</emphasis> partition table.
+          </para>
+          <programlisting>
+# parted /dev/sda -- mklabel gpt
+</programlisting>
+        </listitem>
+        <listitem>
+          <para>
+            Add the <emphasis>root</emphasis> partition. This will fill
+            the disk except for the end part, where the swap will live,
+            and the space left in front (512MiB) which will be used by
+            the boot partition.
+          </para>
+          <programlisting>
+# parted /dev/sda -- mkpart primary 512MiB -8GiB
+</programlisting>
+        </listitem>
+        <listitem>
+          <para>
+            Next, add a <emphasis>swap</emphasis> partition. The size
+            required will vary according to needs, here a 8GiB one is
+            created.
+          </para>
+          <programlisting>
+# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
+</programlisting>
+          <note>
+            <para>
+              The swap partition size rules are no different than for
+              other Linux distributions.
+            </para>
+          </note>
+        </listitem>
+        <listitem>
+          <para>
+            Finally, the <emphasis>boot</emphasis> partition. NixOS by
+            default uses the ESP (EFI system partition) as its
+            <emphasis>/boot</emphasis> partition. It uses the initially
+            reserved 512MiB at the start of the disk.
+          </para>
+          <programlisting>
+# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
+# parted /dev/sda -- set 3 esp on
+</programlisting>
+        </listitem>
+      </orderedlist>
+      <para>
+        Once complete, you can follow with
+        <xref linkend="sec-installation-partitioning-formatting" />.
+      </para>
+    </section>
+    <section xml:id="sec-installation-partitioning-MBR">
+      <title>Legacy Boot (MBR)</title>
+      <para>
+        Here's an example partition scheme for Legacy Boot, using
+        <literal>/dev/sda</literal> as the device.
+      </para>
+      <note>
+        <para>
+          You can safely ignore <literal>parted</literal>'s
+          informational message about needing to update /etc/fstab.
+        </para>
+      </note>
+      <orderedlist numeration="arabic">
+        <listitem>
+          <para>
+            Create a <emphasis>MBR</emphasis> partition table.
+          </para>
+          <programlisting>
+# parted /dev/sda -- mklabel msdos
+</programlisting>
+        </listitem>
+        <listitem>
+          <para>
+            Add the <emphasis>root</emphasis> partition. This will fill
+            the the disk except for the end part, where the swap will
+            live.
+          </para>
+          <programlisting>
+# parted /dev/sda -- mkpart primary 1MiB -8GiB
+</programlisting>
+        </listitem>
+        <listitem>
+          <para>
+            Finally, add a <emphasis>swap</emphasis> partition. The size
+            required will vary according to needs, here a 8GiB one is
+            created.
+          </para>
+          <programlisting>
+# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
+</programlisting>
+          <note>
+            <para>
+              The swap partition size rules are no different than for
+              other Linux distributions.
+            </para>
+          </note>
+        </listitem>
+      </orderedlist>
+      <para>
+        Once complete, you can follow with
+        <xref linkend="sec-installation-partitioning-formatting" />.
+      </para>
+    </section>
+    <section xml:id="sec-installation-partitioning-formatting">
+      <title>Formatting</title>
+      <para>
+        Use the following commands:
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>
+            For initialising Ext4 partitions:
+            <literal>mkfs.ext4</literal>. It is recommended that you
+            assign a unique symbolic label to the file system using the
+            option <literal>-L label</literal>, since this makes the
+            file system configuration independent from device changes.
+            For example:
+          </para>
+          <programlisting>
+# mkfs.ext4 -L nixos /dev/sda1
+</programlisting>
+        </listitem>
+        <listitem>
+          <para>
+            For creating swap partitions: <literal>mkswap</literal>.
+            Again it’s recommended to assign a label to the swap
+            partition: <literal>-L label</literal>. For example:
+          </para>
+          <programlisting>
+# mkswap -L swap /dev/sda2
+</programlisting>
+        </listitem>
+        <listitem>
+          <para>
+            <emphasis role="strong">UEFI systems</emphasis>
+          </para>
+          <para>
+            For creating boot partitions: <literal>mkfs.fat</literal>.
+            Again it’s recommended to assign a label to the boot
+            partition: <literal>-n label</literal>. For example:
+          </para>
+          <programlisting>
+# mkfs.fat -F 32 -n boot /dev/sda3
+</programlisting>
+        </listitem>
+        <listitem>
+          <para>
+            For creating LVM volumes, the LVM commands, e.g.,
+            <literal>pvcreate</literal>, <literal>vgcreate</literal>,
+            and <literal>lvcreate</literal>.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            For creating software RAID devices, use
+            <literal>mdadm</literal>.
+          </para>
+        </listitem>
+      </itemizedlist>
+    </section>
+  </section>
+  <section xml:id="sec-installation-installing">
+    <title>Installing</title>
+    <orderedlist numeration="arabic">
+      <listitem>
+        <para>
+          Mount the target file system on which NixOS should be
+          installed on <literal>/mnt</literal>, e.g.
+        </para>
+        <programlisting>
+# mount /dev/disk/by-label/nixos /mnt
+</programlisting>
+      </listitem>
+      <listitem>
+        <para>
+          <emphasis role="strong">UEFI systems</emphasis>
+        </para>
+        <para>
+          Mount the boot file system on <literal>/mnt/boot</literal>,
+          e.g.
+        </para>
+        <programlisting>
+# mkdir -p /mnt/boot
+# mount /dev/disk/by-label/boot /mnt/boot
+</programlisting>
+      </listitem>
+      <listitem>
+        <para>
+          If your machine has a limited amount of memory, you may want
+          to activate swap devices now
+          (<literal>swapon device</literal>). The installer (or rather,
+          the build actions that it may spawn) may need quite a bit of
+          RAM, depending on your configuration.
+        </para>
+        <programlisting>
+# swapon /dev/sda2
+</programlisting>
+      </listitem>
+      <listitem>
+        <para>
+          You now need to create a file
+          <literal>/mnt/etc/nixos/configuration.nix</literal> 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
+          desired configuration of your system, and then NixOS takes
+          care of making it happen. The syntax of the NixOS
+          configuration file is described in
+          <xref linkend="sec-configuration-syntax" />, while a list of
+          available configuration options appears in
+          <xref linkend="ch-options" />. A minimal example is shown in
+          <link linkend="ex-config">Example: NixOS Configuration</link>.
+        </para>
+        <para>
+          The command <literal>nixos-generate-config</literal> can
+          generate an initial configuration file for you:
+        </para>
+        <programlisting>
+# nixos-generate-config --root /mnt
+</programlisting>
+        <para>
+          You should then edit
+          <literal>/mnt/etc/nixos/configuration.nix</literal> to suit
+          your needs:
+        </para>
+        <programlisting>
+# nano /mnt/etc/nixos/configuration.nix
+</programlisting>
+        <para>
+          If you’re using the graphical ISO image, other editors may be
+          available (such as <literal>vim</literal>). If you have
+          network access, you can also install other editors – for
+          instance, you can install Emacs by running
+          <literal>nix-env -f '&lt;nixpkgs&gt;' -iA emacs</literal>.
+        </para>
+        <variablelist>
+          <varlistentry>
+            <term>
+              BIOS systems
+            </term>
+            <listitem>
+              <para>
+                You <emphasis>must</emphasis> set the option
+                <xref linkend="opt-boot.loader.grub.device" /> to
+                specify on which disk the GRUB boot loader is to be
+                installed. Without it, NixOS cannot boot.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>
+              UEFI systems
+            </term>
+            <listitem>
+              <para>
+                You <emphasis>must</emphasis> set the option
+                <xref linkend="opt-boot.loader.systemd-boot.enable" />
+                to <literal>true</literal>.
+                <literal>nixos-generate-config</literal> should do this
+                automatically for new configurations when booted in UEFI
+                mode.
+              </para>
+              <para>
+                You may want to look at the options starting with
+                <link linkend="opt-boot.loader.efi.canTouchEfiVariables"><literal>boot.loader.efi</literal></link>
+                and
+                <link linkend="opt-boot.loader.systemd-boot.enable"><literal>boot.loader.systemd-boot</literal></link>
+                as well.
+              </para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+        <para>
+          If there are other operating systems running on the machine
+          before installing NixOS, the
+          <xref linkend="opt-boot.loader.grub.useOSProber" /> option can
+          be set to <literal>true</literal> to automatically add them to
+          the grub menu.
+        </para>
+        <para>
+          If you need to configure networking for your machine the
+          configuration options are described in
+          <xref linkend="sec-networking" />. In particular, while wifi
+          is supported on the installation image, it is not enabled by
+          default in the configuration generated by
+          <literal>nixos-generate-config</literal>.
+        </para>
+        <para>
+          Another critical option is <literal>fileSystems</literal>,
+          specifying the file systems that need to be mounted by NixOS.
+          However, you typically don’t need to set it yourself, because
+          <literal>nixos-generate-config</literal> sets it automatically
+          in
+          <literal>/mnt/etc/nixos/hardware-configuration.nix</literal>
+          from your currently mounted file systems. (The configuration
+          file <literal>hardware-configuration.nix</literal> is included
+          from <literal>configuration.nix</literal> and will be
+          overwritten by future invocations of
+          <literal>nixos-generate-config</literal>; thus, you generally
+          should not modify it.) Additionally, you may want to look at
+          <link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware
+          configuration for known-hardware</link> at this point or after
+          installation.
+        </para>
+        <note>
+          <para>
+            Depending on your hardware configuration or type of file
+            system, you may need to set the option
+            <literal>boot.initrd.kernelModules</literal> to include the
+            kernel modules that are necessary for mounting the root file
+            system, otherwise the installed system will not be able to
+            boot. (If this happens, boot from the installation media
+            again, mount the target file system on
+            <literal>/mnt</literal>, fix
+            <literal>/mnt/etc/nixos/configuration.nix</literal> and
+            rerun <literal>nixos-install</literal>.) In most cases,
+            <literal>nixos-generate-config</literal> will figure out the
+            required modules.
+          </para>
+        </note>
+      </listitem>
+      <listitem>
+        <para>
+          Do the installation:
+        </para>
+        <programlisting>
+# nixos-install
+</programlisting>
+        <para>
+          This will install your system based on the configuration you
+          provided. If anything fails due to a configuration problem or
+          any other issue (such as a network outage while downloading
+          binaries from the NixOS binary cache), you can re-run
+          <literal>nixos-install</literal> after fixing your
+          <literal>configuration.nix</literal>.
+        </para>
+        <para>
+          As the last step, <literal>nixos-install</literal> will ask
+          you to set the password for the <literal>root</literal> user,
+          e.g.
+        </para>
+        <programlisting>
+setting root password...
+New password: ***
+Retype new password: ***
+</programlisting>
+        <note>
+          <para>
+            For unattended installations, it is possible to use
+            <literal>nixos-install --no-root-passwd</literal> in order
+            to disable the password prompt entirely.
+          </para>
+        </note>
+      </listitem>
+      <listitem>
+        <para>
+          If everything went well:
+        </para>
+        <programlisting>
+# reboot
+</programlisting>
+      </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
+          <link linkend="sec-changing-config">Changing
+          Configuration</link>), a new item is added to the menu. This
+          allows you to easily roll back to a previous configuration if
+          something goes wrong.
+        </para>
+        <para>
+          You should log in and change the <literal>root</literal>
+          password with <literal>passwd</literal>.
+        </para>
+        <para>
+          You’ll probably want to create some user accounts as well,
+          which can be done with <literal>useradd</literal>:
+        </para>
+        <programlisting>
+$ useradd -c 'Eelco Dolstra' -m eelco
+$ passwd eelco
+</programlisting>
+        <para>
+          You may also want to install some software. This will be
+          covered in <xref linkend="sec-package-management" />.
+        </para>
+      </listitem>
+    </orderedlist>
+  </section>
+  <section xml:id="sec-installation-summary">
+    <title>Installation summary</title>
+    <para>
+      To summarise, <link linkend="ex-install-sequence">Example:
+      Commands for Installing NixOS on
+      <literal>/dev/sda</literal></link> shows a typical sequence of
+      commands for installing NixOS on an empty hard drive (here
+      <literal>/dev/sda</literal>). <link linkend="ex-config">Example:
+      NixOS Configuration</link> shows a corresponding configuration Nix
+      expression.
+    </para>
+    <anchor xml:id="ex-partition-scheme-MBR" />
+    <para>
+      <emphasis role="strong">Example: Example partition schemes for
+      NixOS on <literal>/dev/sda</literal> (MBR)</emphasis>
+    </para>
+    <programlisting>
+# parted /dev/sda -- mklabel msdos
+# parted /dev/sda -- mkpart primary 1MiB -8GiB
+# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
+</programlisting>
+    <anchor xml:id="ex-partition-scheme-UEFI" />
+    <para>
+      <emphasis role="strong">Example: Example partition schemes for
+      NixOS on <literal>/dev/sda</literal> (UEFI)</emphasis>
+    </para>
+    <programlisting>
+# parted /dev/sda -- mklabel gpt
+# parted /dev/sda -- mkpart primary 512MiB -8GiB
+# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
+# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
+# parted /dev/sda -- set 3 esp on
+</programlisting>
+    <anchor xml:id="ex-install-sequence" />
+    <para>
+      <emphasis role="strong">Example: Commands for Installing NixOS on
+      <literal>/dev/sda</literal></emphasis>
+    </para>
+    <para>
+      With a partitioned disk.
+    </para>
+    <programlisting>
+# mkfs.ext4 -L nixos /dev/sda1
+# mkswap -L swap /dev/sda2
+# swapon /dev/sda2
+# mkfs.fat -F 32 -n boot /dev/sda3        # (for UEFI systems only)
+# mount /dev/disk/by-label/nixos /mnt
+# mkdir -p /mnt/boot                      # (for UEFI systems only)
+# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
+# nixos-generate-config --root /mnt
+# nano /mnt/etc/nixos/configuration.nix
+# nixos-install
+# reboot
+</programlisting>
+    <anchor xml:id="ex-config" />
+    <para>
+      <emphasis role="strong">Example: NixOS Configuration</emphasis>
+    </para>
+    <programlisting>
+{ config, pkgs, ... }: {
+  imports = [
+    # Include the results of the hardware scan.
+    ./hardware-configuration.nix
+  ];
+
+  boot.loader.grub.device = &quot;/dev/sda&quot;;   # (for BIOS systems only)
+  boot.loader.systemd-boot.enable = true; # (for UEFI systems only)
+
+  # Note: setting fileSystems is generally not
+  # necessary, since nixos-generate-config figures them out
+  # automatically in hardware-configuration.nix.
+  #fileSystems.&quot;/&quot;.device = &quot;/dev/disk/by-label/nixos&quot;;
+
+  # Enable the OpenSSH server.
+  services.sshd.enable = true;
+}
+</programlisting>
+  </section>
+  <section xml:id="sec-installation-additional-notes">
+    <title>Additional installation notes</title>
+    <xi:include href="installing-usb.section.xml" />
+    <xi:include href="installing-pxe.section.xml" />
+    <xi:include href="installing-virtualbox-guest.section.xml" />
+    <xi:include href="installing-from-other-distro.section.xml" />
+    <xi:include href="installing-behind-a-proxy.section.xml" />
+  </section>
+</chapter>
diff --git a/nixos/doc/manual/from_md/installation/obtaining.chapter.xml b/nixos/doc/manual/from_md/installation/obtaining.chapter.xml
new file mode 100644
index 00000000000..a922feda253
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/obtaining.chapter.xml
@@ -0,0 +1,48 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-obtaining">
+  <title>Obtaining NixOS</title>
+  <para>
+    NixOS ISO images can be downloaded from the
+    <link xlink:href="https://nixos.org/nixos/download.html">NixOS
+    download page</link>. There are a number of installation options. If
+    you happen to have an optical drive and a spare CD, burning the
+    image to CD and booting from that is probably the easiest option.
+    Most people will need to prepare a USB stick to boot from.
+    <xref linkend="sec-booting-from-usb" /> describes the preferred
+    method to prepare a USB stick. A number of alternative methods are
+    presented in the
+    <link xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS
+    Wiki</link>.
+  </para>
+  <para>
+    As an alternative to installing NixOS yourself, you can get a
+    running NixOS system through several other means:
+  </para>
+  <itemizedlist>
+    <listitem>
+      <para>
+        Using virtual appliances in Open Virtualization Format (OVF)
+        that can be imported into VirtualBox. These are available from
+        the
+        <link xlink:href="https://nixos.org/nixos/download.html">NixOS
+        download page</link>.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Using AMIs for Amazon’s EC2. To find one for your region and
+        instance type, please refer to the
+        <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list
+        of most recent AMIs</link>.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Using NixOps, the NixOS-based cloud deployment tool, which
+        allows you to provision VirtualBox and EC2 NixOS instances from
+        declarative specifications. Check out the
+        <link xlink:href="https://nixos.org/nixops">NixOps
+        homepage</link> for details.
+      </para>
+    </listitem>
+  </itemizedlist>
+</chapter>
diff --git a/nixos/doc/manual/from_md/installation/upgrading.chapter.xml b/nixos/doc/manual/from_md/installation/upgrading.chapter.xml
new file mode 100644
index 00000000000..e3b77d4c365
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/upgrading.chapter.xml
@@ -0,0 +1,152 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-upgrading">
+  <title>Upgrading NixOS</title>
+  <para>
+    The best way to keep your NixOS installation up to date is to use
+    one of the NixOS <emphasis>channels</emphasis>. A channel is a Nix
+    mechanism for distributing Nix expressions and associated binaries.
+    The NixOS channels are updated automatically from NixOS’s Git
+    repository after certain tests have passed and all packages have
+    been built. These channels are:
+  </para>
+  <itemizedlist>
+    <listitem>
+      <para>
+        <emphasis>Stable channels</emphasis>, such as
+        <link xlink:href="https://nixos.org/channels/nixos-21.11"><literal>nixos-21.11</literal></link>.
+        These only get conservative bug fixes and package upgrades. For
+        instance, a channel update may cause the Linux kernel on your
+        system to be upgraded from 4.19.34 to 4.19.38 (a minor bug fix),
+        but not from 4.19.x to 4.20.x (a major change that has the
+        potential to break things). Stable channels are generally
+        maintained until the next stable branch is created.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        The <emphasis>unstable channel</emphasis>,
+        <link xlink:href="https://nixos.org/channels/nixos-unstable"><literal>nixos-unstable</literal></link>.
+        This corresponds to NixOS’s main development branch, and may
+        thus see radical changes between channel updates. It’s not
+        recommended for production systems.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <emphasis>Small channels</emphasis>, such as
+        <link xlink:href="https://nixos.org/channels/nixos-21.11-small"><literal>nixos-21.11-small</literal></link>
+        or
+        <link xlink:href="https://nixos.org/channels/nixos-unstable-small"><literal>nixos-unstable-small</literal></link>.
+        These are identical to the stable and unstable channels
+        described above, except that they contain fewer binary packages.
+        This means they get updated faster than the regular channels
+        (for instance, when a critical security patch is committed to
+        NixOS’s source tree), but may require more packages to be built
+        from source than usual. They’re mostly intended for server
+        environments and as such contain few GUI applications.
+      </para>
+    </listitem>
+  </itemizedlist>
+  <para>
+    To see what channels are available, go to
+    <link xlink:href="https://nixos.org/channels">https://nixos.org/channels</link>.
+    (Note that the URIs of the various channels redirect to a directory
+    that contains the channel’s latest version and includes ISO images
+    and VirtualBox appliances.) Please note that during the release
+    process, channels that are not yet released will be present here as
+    well. See the Getting NixOS page
+    <link xlink:href="https://nixos.org/nixos/download.html">https://nixos.org/nixos/download.html</link>
+    to find the newest supported stable release.
+  </para>
+  <para>
+    When you first install NixOS, you’re automatically subscribed to the
+    NixOS channel that corresponds to your installation source. For
+    instance, if you installed from a 21.11 ISO, you will be subscribed
+    to the <literal>nixos-21.11</literal> channel. To see which NixOS
+    channel you’re subscribed to, run the following as root:
+  </para>
+  <programlisting>
+# nix-channel --list | grep nixos
+nixos https://nixos.org/channels/nixos-unstable
+</programlisting>
+  <para>
+    To switch to a different NixOS channel, do
+  </para>
+  <programlisting>
+# nix-channel --add https://nixos.org/channels/channel-name nixos
+</programlisting>
+  <para>
+    (Be sure to include the <literal>nixos</literal> parameter at the
+    end.) For instance, to use the NixOS 21.11 stable channel:
+  </para>
+  <programlisting>
+# nix-channel --add https://nixos.org/channels/nixos-21.11 nixos
+</programlisting>
+  <para>
+    If you have a server, you may want to use the <quote>small</quote>
+    channel instead:
+  </para>
+  <programlisting>
+# nix-channel --add https://nixos.org/channels/nixos-21.11-small nixos
+</programlisting>
+  <para>
+    And if you want to live on the bleeding edge:
+  </para>
+  <programlisting>
+# nix-channel --add https://nixos.org/channels/nixos-unstable nixos
+</programlisting>
+  <para>
+    You can then upgrade NixOS to the latest version in your chosen
+    channel by running
+  </para>
+  <programlisting>
+# nixos-rebuild switch --upgrade
+</programlisting>
+  <para>
+    which is equivalent to the more verbose
+    <literal>nix-channel --update nixos; nixos-rebuild switch</literal>.
+  </para>
+  <note>
+    <para>
+      Channels are set per user. This means that running
+      <literal>nix-channel --add</literal> as a non root user (or
+      without sudo) will not affect configuration in
+      <literal>/etc/nixos/configuration.nix</literal>
+    </para>
+  </note>
+  <warning>
+    <para>
+      It is generally safe to switch back and forth between channels.
+      The only exception is that a newer NixOS may also have a newer Nix
+      version, which may involve an upgrade of Nix’s database schema.
+      This cannot be undone easily, so in that case you will not be able
+      to go back to your original channel.
+    </para>
+  </warning>
+  <section xml:id="sec-upgrading-automatic">
+    <title>Automatic Upgrades</title>
+    <para>
+      You can keep a NixOS system up-to-date automatically by adding the
+      following to <literal>configuration.nix</literal>:
+    </para>
+    <programlisting language="bash">
+system.autoUpgrade.enable = true;
+system.autoUpgrade.allowReboot = true;
+</programlisting>
+    <para>
+      This enables a periodically executed systemd service named
+      <literal>nixos-upgrade.service</literal>. If the
+      <literal>allowReboot</literal> option is <literal>false</literal>,
+      it runs <literal>nixos-rebuild switch --upgrade</literal> to
+      upgrade NixOS to the latest version in the current channel. (To
+      see when the service runs, see
+      <literal>systemctl list-timers</literal>.) If
+      <literal>allowReboot</literal> is <literal>true</literal>, then
+      the system will automatically reboot if the new generation
+      contains a different kernel, initrd or kernel modules. You can
+      also specify a channel explicitly, e.g.
+    </para>
+    <programlisting language="bash">
+system.autoUpgrade.channel = https://nixos.org/channels/nixos-21.11;
+</programlisting>
+  </section>
+</chapter>