Merge pull request #129003 from bobby285271/pr10

nixos/doc: convert "2.5. Additional installation notes" to CommonMark

16 files changed, 1033 insertions, 610 deletions

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 000000000000..a551807cd47c
--- /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 000000000000..525531a47813
--- /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 000000000000..1dd15ddacba8
--- /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 a recent version of
+    nixpkgs, you can run:
+  </para>
+  <programlisting>
+nix-build -A netboot.x86_64-linux nixos/release.nix
+</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 000000000000..b46a1d565557
--- /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 000000000000..c8bb286c8f33
--- /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/installation/installing-behind-a-proxy.section.md b/nixos/doc/manual/installation/installing-behind-a-proxy.section.md
new file mode 100644
index 000000000000..aca151531d0f
--- /dev/null
+++ b/nixos/doc/manual/installation/installing-behind-a-proxy.section.md
@@ -0,0 +1,29 @@
+# Installing behind a proxy {#sec-installing-behind-proxy}
+
+To install NixOS behind a proxy, do the following before running
+`nixos-install`.
+
+1.  Update proxy configuration in `/mnt/etc/nixos/configuration.nix` to
+    keep the internet accessible after reboot.
+
+    ```nix
+    networking.proxy.default = "http://user:password@proxy:port/";
+    networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain";
+    ```
+
+1.  Setup the proxy environment variables in the shell where you are
+    running `nixos-install`.
+
+    ```ShellSession
+    # proxy_url="http://user:password@proxy:port/"
+    # export http_proxy="$proxy_url"
+    # export HTTP_PROXY="$proxy_url"
+    # export https_proxy="$proxy_url"
+    # export HTTPS_PROXY="$proxy_url"
+    ```
+
+::: {.note}
+If you are switching networks with different proxy configurations, use
+the `specialisation` option in `configuration.nix` to switch proxies at
+runtime. Refer to [](#ch-options) for more information.
+:::
diff --git a/nixos/doc/manual/installation/installing-behind-a-proxy.xml b/nixos/doc/manual/installation/installing-behind-a-proxy.xml
deleted file mode 100644
index 6788882aa8c0..000000000000
--- a/nixos/doc/manual/installation/installing-behind-a-proxy.xml
+++ /dev/null
@@ -1,48 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         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>
-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>
-<screen>
-<prompt># </prompt>proxy_url=&quot;http://user:password@proxy:port/&quot;
-<prompt># </prompt>export http_proxy=&quot;$proxy_url&quot;
-<prompt># </prompt>export HTTP_PROXY=&quot;$proxy_url&quot;
-<prompt># </prompt>export https_proxy=&quot;$proxy_url&quot;
-<prompt># </prompt>export HTTPS_PROXY=&quot;$proxy_url&quot;
-</screen>
-  </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/installation/installing-from-other-distro.section.md b/nixos/doc/manual/installation/installing-from-other-distro.section.md
new file mode 100644
index 000000000000..d9060eb89c37
--- /dev/null
+++ b/nixos/doc/manual/installation/installing-from-other-distro.section.md
@@ -0,0 +1,279 @@
+# Installing from another Linux distribution {#sec-installing-from-other-distro}
+
+Because Nix (the package manager) & 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:
+
+1.  Install NixOS on another partition, from your existing Linux
+    distribution (without the use of a USB or optical device!)
+
+1.  Install NixOS on the same partition (in place!), from your existing
+    non-NixOS Linux distribution using `NIXOS_LUSTRATE`.
+
+1.  Install NixOS on your hard drive from the Live CD of any Linux
+    distribution.
+
+The first steps to all these are the same:
+
+1.  Install the Nix package manager:
+
+    Short version:
+
+    ```ShellSession
+    $ curl -L https://nixos.org/nix/install | sh
+    $ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell
+    ```
+
+    More details in the [ Nix
+    manual](https://nixos.org/nix/manual/#chap-quick-start)
+
+1.  Switch to the NixOS channel:
+
+    If you\'ve just installed Nix on a non-NixOS distribution, you will
+    be on the `nixpkgs` channel by default.
+
+    ```ShellSession
+    $ nix-channel --list
+    nixpkgs https://nixos.org/channels/nixpkgs-unstable
+    ```
+
+    As that channel gets released without running the NixOS tests, it
+    will be safer to use the `nixos-*` channels instead: