nixos: nixos/doc/manual/installation/installing.xml to CommonMark

4 files changed, 1122 insertions, 617 deletions

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 000000000000..91ab71682977
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/installing.chapter.xml
@@ -0,0 +1,642 @@
+<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>
+    <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/installation/installation.xml b/nixos/doc/manual/installation/installation.xml
index cc18a9c6e9ff..1d443bbd0ee1 100644
--- a/nixos/doc/manual/installation/installation.xml
+++ b/nixos/doc/manual/installation/installation.xml
@@ -11,7 +11,7 @@
   </para>
  </partintro>
  <xi:include href="../from_md/installation/obtaining.chapter.xml" />
- <xi:include href="installing.xml" />
+ <xi:include href="../from_md/installation/installing.chapter.xml" />
  <xi:include href="../from_md/installation/changing-config.chapter.xml" />
  <xi:include href="../from_md/installation/upgrading.chapter.xml" />
 </part>
diff --git a/nixos/doc/manual/installation/installing.chapter.md b/nixos/doc/manual/installation/installing.chapter.md
new file mode 100644
index 000000000000..a0823b51e9cb
--- /dev/null
+++ b/nixos/doc/manual/installation/installing.chapter.md
@@ -0,0 +1,479 @@
+# Installing NixOS {#sec-installation}
+
+## Booting the system {#sec-installation-booting}
+
+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.
+
+The installation media can be burned to a CD, or now more commonly,
+"burned" to a USB drive (see [](#sec-booting-from-usb)).
+
+The installation media contains a basic NixOS installation. When it's
+finished booting, it should have detected most of your hardware.
+
+The NixOS manual is available by running `nixos-help`.
+
+You are logged-in automatically as `nixos`. The `nixos` user account has
+an empty password so you can use `sudo` without a password.
+
+If you downloaded the graphical ISO image, you can run `systemctl
+start display-manager` to start the desktop environment. If you want
+to continue on the terminal, you can use `loadkeys` to switch to your
+preferred keyboard layout. (We even provide neo2 via `loadkeys de
+neo`!)
+
+If the text is too small to be legible, try `setfont ter-v32n` to
+increase the font size.
+
+To install over a serial port connect with `115200n8` (e.g.
+`picocom -b 115200 /dev/ttyUSB0`). When the bootloader lists boot
+entries, select the serial console boot entry.
+
+### Networking in the installer {#sec-installation-booting-networking}
+
+The boot process should have brought up networking (check `ip
+a`). 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 `ifconfig`.
+
+On the graphical installer, you can configure the network, wifi
+included, through NetworkManager. Using the `nmtui` program, you can do
+so even in a non-graphical session. If you prefer to configure the
+network manually, disable NetworkManager with
+`systemctl stop NetworkManager`.
+
+On the minimal installer, NetworkManager is not available, so
+configuration must be perfomed manually. To configure the wifi, first
+start wpa_supplicant with `sudo systemctl start wpa_supplicant`, then
+run `wpa_cli`. For most home networks, you need to type in the following
+commands:
+
+```plain
+> add_network
+0
+> set_network 0 ssid "myhomenetwork"
+OK
+> set_network 0 psk "mypassword"
+OK
+> set_network 0 key_mgmt WPA-PSK
+OK
+> enable_network 0
+OK
+```
+
+For enterprise networks, for example *eduroam*, instead do:
+
+```plain
+> add_network
+0
+> set_network 0 ssid "eduroam"
+OK
+> set_network 0 identity "myname@example.com"
+OK
+> set_network 0 password "mypassword"
+OK
+> set_network 0 key_mgmt WPA-EAP
+OK
+> enable_network 0
+OK
+```
+
+When successfully connected, you should see a line such as this one
+
+```plain
+<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=]
+```
+
+you can now leave `wpa_cli` by typing `quit`.
+
+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 `/home/nixos/.ssh/authorized_keys` or
+`/root/.ssh/authorized_keys` (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 `root` or `nixos` with `passwd` to be
+able to login.
+
+## Partitioning and formatting {#sec-installation-partitioning}
+
+The NixOS installer doesn't do any partitioning or formatting, so you
+need to do that yourself.
+
+The NixOS installer ships with multiple partitioning tools. The examples
+below use `parted`, but also provides `fdisk`, `gdisk`, `cfdisk`, and
+`cgdisk`.
+
+The recommended partition scheme differs depending if the computer uses
+*Legacy Boot* or *UEFI*.
+
+### UEFI (GPT) {#sec-installation-partitioning-UEFI}
+
+Here\'s an example partition scheme for UEFI, using `/dev/sda` as the
+device.
+
+::: {.note}
+You can safely ignore `parted`\'s informational message about needing to
+update /etc/fstab.
+:::
+
+1.  Create a *GPT* partition table.
+
+    ```ShellSession
+    # parted /dev/sda -- mklabel gpt
+    ```
+
+2.  Add the *root* 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.
+
+    ```ShellSession
+    # parted /dev/sda -- mkpart primary 512MiB -8GiB
+    ```
+
+3.  Next, add a *swap* partition. The size required will vary according
+    to needs, here a 8GiB one is created.
+
+    ```ShellSession
+    # parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
+    ```
+
+    ::: {.note}
+    The swap partition size rules are no different than for other Linux
+    distributions.
+    :::
+
+4.  Finally, the *boot* partition. NixOS by default uses the ESP (EFI
+    system partition) as its */boot* partition. It uses the initially
+    reserved 512MiB at the start of the disk.
+
+    ```ShellSession
+    # parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
+    # parted /dev/sda -- set 3 esp on
+    ```
+
+Once complete, you can follow with
+[](#sec-installation-partitioning-formatting).
+
+### Legacy Boot (MBR) {#sec-installation-partitioning-MBR}
+
+Here\'s an example partition scheme for Legacy Boot, using `/dev/sda` as
+the device.
+
+::: {.note}
+You can safely ignore `parted`\'s informational message about needing to
+update /etc/fstab.
+:::
+
+1.  Create a *MBR* partition table.
+
+    ```ShellSession
+    # parted /dev/sda -- mklabel msdos
+    ```
+
+2.  Add the *root* partition. This will fill the the disk except for the
+    end part, where the swap will live.
+
+    ```ShellSession
+    # parted /dev/sda -- mkpart primary 1MiB -8GiB
+    ```
+
+3.  Finally, add a *swap* partition. The size required will vary
+    according to needs, here a 8GiB one is created.
+
+    ```ShellSession
+    # parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
+    ```
+
+    ::: {.note}
+    The swap partition size rules are no different than for other Linux
+    distributions.
+    :::
+
+Once complete, you can follow with
+[](#sec-installation-partitioning-formatting).
+
+### Formatting {#sec-installation-partitioning-formatting}
+
+Use the following commands:
+
+-   For initialising Ext4 partitions: `mkfs.ext4`. It is recommended
+    that you assign a unique symbolic label to the file system using the
+    option `-L label`, since this makes the file system configuration
+