doc: Reviews partitioning instructions to use parted.

The tests in <nixos/tests/installer.nix> are using `parted`, so they are
bound to be better tested than `fdisk`.

This is brought on by a couple issues, plus reports on IRC that the
`fdisk` instructions didn't work as expected.

 * #39354
 * #46309
 * #39942
 * #45478

Care was taken so that the other documented steps did not need changes.

In all this kerfufle, a slight re-organization of the Chapter has been
made, allowing better deep linking.

nixos/doc/manual/installation/installing.xml

@@ -4,60 +4,46 @@
             version="5.0"
             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
+   installation is by and large the same as a BIOS installation. The
-  are mentioned in the steps that follow.
+   differences are mentioned in the steps that follow.
   </para>
- <orderedlist>
+
-  <listitem>
   <para>
-    Boot from the CD.
+   The installation media can be burned to a CD, or now more commonly, "burned"
+   to a USB drive (see <xref linkend="sec-booting-from-usb"/>).
   </para>
-   <variablelist>
+
-    <varlistentry>
-     <term>
-      UEFI systems
-     </term>
-     <listitem>
   <para>
-       You should boot the live CD in UEFI mode (consult your specific
+   The installation media contains a basic NixOS installation. When it’s
-       hardware's documentation for instructions). You may find the
+   finished booting, it should have detected most of your hardware.
-       <link xlink:href="http://www.rodsbooks.com/refind">rEFInd boot
-       manager</link> useful.
   </para>
-     </listitem>
+
-    </varlistentry>
-   </variablelist>
-  </listitem>
-  <listitem>
-   <para>
-    The CD contains a basic NixOS installation. (It also contains Memtest86+,
-    useful if you want to test new hardware). When it’s finished booting, it
-    should have detected most of your hardware.
-   </para>
-  </listitem>
-  <listitem>
   <para>
    The NixOS manual is available on virtual console 8 (press Alt+F8 to access)
    or by running <command>nixos-help</command>.
   </para>
-  </listitem>
+
-  <listitem>
   <para>
-    You get logged in as <literal>root</literal> (with empty password).
+   You are logged-in automatically as <literal>root</literal>. (The
+   <literal>root</literal> user account has an empty password.)
   </para>
-  </listitem>
+
-  <listitem>
   <para>
    If you downloaded the graphical ISO image, you can run <command>systemctl
-    start display-manager</command> to start KDE. If you want to continue on
+   start display-manager</command> to start KDE. If you want to continue on the
-    the terminal, you can use <command>loadkeys</command> to switch to your
+   terminal, you can use <command>loadkeys</command> to switch to your
    preferred keyboard layout. (We even provide neo2 via <command>loadkeys de
    neo</command>!)
   </para>
-  </listitem>
+
-  <listitem>
+  <section xml:id="sec-installation-booting-networking">
+   <title>Networking in the installer</title>
+
    <para>
     The boot process should have brought up networking (check <command>ip
     a</command>). Networking is necessary for the installer, since it will
@@ -65,58 +51,165 @@
     binaries). It’s best if you have a DHCP server on your network. Otherwise
     configure networking manually using <command>ifconfig</command>.
    </para>
+
    <para>
     To manually configure the network on the graphical installer, first disable
     network-manager with <command>systemctl stop network-manager</command>.
    </para>
+
    <para>
     To manually configure the wifi on the minimal installer, run
     <command>wpa_supplicant -B -i interface -c &lt;(wpa_passphrase 'SSID'
     'key')</command>.
    </para>
-  </listitem>
+
-  <listitem>
    <para>
     If you would like to continue the installation from a different machine you
     need to activate the SSH daemon via <literal>systemctl start
     sshd</literal>. In order to be able to login you also need to set a
     password for <literal>root</literal> using <literal>passwd</literal>.
    </para>
-  </listitem>
+  </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 <command>parted</command>, but also provides
+   <command>fdisk</command>, <command>gdisk</command>,
+   <command>cfdisk</command>, and <command>cgdisk</command>.
+  </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
+    <filename>/dev/sda</filename> as the device.
+    <note>
+     <para>
+      You can safely ignore <command>parted</command>'s informational message
+      about needing to update /etc/fstab.
+     </para>
+    </note>
+   </para>
+
+   <para>
+    <orderedlist>
      <listitem>
       <para>
-    The NixOS installer doesn’t do any partitioning or formatting yet, so you
+       Create a <emphasis>GPT</emphasis> partition table.
-    need to do that yourself. Use the following commands:
+<screen language="commands"># parted /dev/sda -- mklabel gpt</screen>
-    <itemizedlist>
-     <listitem>
-      <para>
-       For partitioning: <command>fdisk</command>.
-<screen>
-# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
--- for UEFI systems only
-> n      # <lineannotation>(create a new partition for /boot)</lineannotation>
-> 3      # <lineannotation>(make it a partition number 3)</lineannotation>
->        # <lineannotation>(press enter to accept the default)</lineannotation>
-> +512M  # <lineannotation>(the size of the UEFI boot partition)</lineannotation>
-> t      # <lineannotation>(change the partition type ...)</lineannotation>
-> 3      # <lineannotation>(... of the boot partition ...)</lineannotation>
-> 1      # <lineannotation>(... to 'UEFI System')</lineannotation>
--- for BIOS or UEFI systems
-> n      # <lineannotation>(create a new partition for /swap)</lineannotation>
-> 2      # <lineannotation>(make it a partition number 2)</lineannotation>
->        # <lineannotation>(press enter to accept the default)</lineannotation>
-> +8G    # <lineannotation>(the size of the swap partition, set to whatever you like)</lineannotation>
-> n      # <lineannotation>(create a new partition for /)</lineannotation>
-> 1      # <lineannotation>(make it a partition number 1)</lineannotation>
->        # <lineannotation>(press enter to accept the default)</lineannotation>
->        # <lineannotation>(press enter to accept the default and use the rest of the remaining space)</lineannotation>
-> a      # <lineannotation>(make the partition bootable)</lineannotation>
-> x      # <lineannotation>(enter expert mode)</lineannotation>
-> f      # <lineannotation>(fix up the partition ordering)</lineannotation>
-> r      # <lineannotation>(exit expert mode)</lineannotation>
-> w      # <lineannotation>(write the partition table to disk and exit)</lineannotation></screen>
       </para>
      </listitem>
+     <listitem>
+      <para>
+       Add a <emphasis>swap</emphasis> partition. The size required will vary
+       according to needs, here a 8GiB one is created. The space left in front
+       (512MiB) will be used by the boot partition.
+<screen language="commands"># parted /dev/sda -- mkpart primary linux-swap 512MiB 8.5GiB</screen>
+       <note>
+        <para>
+         The swap partition size rules are no different than for other Linux
+         distributions.
+        </para>
+       </note>
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       Next, add the <emphasis>root</emphasis> partition. This will fill the
+       remainder ending part of the disk.
+<screen language="commands"># parted /dev/sda -- mkpart primary 8.5GiB -1MiB</screen>
+      </para>
+     </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.
+<screen language="commands"># parted /dev/sda -- mkpart ESP fat32 1M 512MiB
+# parted /dev/sda -- set 3 boot on</screen>
+      </para>
+     </listitem>
+    </orderedlist>
+   </para>
+
+   <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
+    <filename>/dev/sda</filename> as the device.
+    <note>
+     <para>
+      You can safely ignore <command>parted</command>'s informational message
+      about needing to update /etc/fstab.
+     </para>
+    </note>
+   </para>
+
+   <para>
+    <orderedlist>
+     <listitem>
+      <para>
+       Create a <emphasis>MBR</emphasis> partition table.
+<screen language="commands"># parted /dev/sda -- mklabel msdos</screen>
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       Add a <emphasis>swap</emphasis> partition. The size required will vary
+       according to needs, here a 8GiB one is created.
+<screen language="commands"># parted /dev/sda -- mkpart primary linux-swap 1M 8GiB</screen>
+       <note>
+        <para>
+         The swap partition size rules are no different than for other Linux
+         distributions.
+        </para>
+       </note>
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       Finally, add the <emphasis>root</emphasis> partition. This will fill the
+       remainder of the disk.
+<screen language="commands"># parted /dev/sda -- mkpart primary 8GiB -1s</screen>
+      </para>
+     </listitem>
+    </orderedlist>
+   </para>
+
+   <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:
+    <itemizedlist>
      <listitem>
       <para>
        For initialising Ext4 partitions: <command>mkfs.ext4</command>. It is
@@ -169,7 +262,12 @@
      </listitem>
     </itemizedlist>
    </para>
-  </listitem>
+  </section>
+ </section>
+ <section xml:id="sec-installation-installing">
+  <title>Installing</title>
+
+  <orderedlist>
    <listitem>
     <para>
      Mount the target file system on which NixOS should be installed on
@@ -201,9 +299,9 @@
     <para>
      If your machine has a limited amount of memory, you may want to activate
      swap devices now (<command>swapon
-    <replaceable>device</replaceable></command>). The installer (or rather, the
+     <replaceable>device</replaceable></command>). The installer (or rather,
-    build actions that it may spawn) may need quite a bit of RAM, depending on
+     the build actions that it may spawn) may need quite a bit of RAM,
-    your configuration.
+     depending on your configuration.
 <screen>
 # swapon /dev/sda2</screen>
     </para>
@@ -216,8 +314,8 @@
      <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
+     is described in <xref linkend="sec-configuration-syntax"/>, while a list
-    available configuration options appears in
+     of available configuration options appears in
      <xref
     linkend="ch-options"/>. A minimal example is shown in
      <xref
@@ -259,8 +357,9 @@
        <para>
         You <emphasis>must</emphasis> set the option
         <xref linkend="opt-boot.loader.systemd-boot.enable"/> to
-       <literal>true</literal>. <command>nixos-generate-config</command> should
+        <literal>true</literal>. <command>nixos-generate-config</command>
-       do this automatically for new configurations when booted in UEFI mode.
+        should do this automatically for new configurations when booted in UEFI
+        mode.
        </para>
        <para>
         You may want to look at the options starting with
@@ -296,8 +395,8 @@
       need to set the option <option>boot.initrd.kernelModules</option> 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 CD again, mount the target file system on
+      happens, boot from the installation media again, mount the target file
-     <filename>/mnt</filename>, fix
+      system on <filename>/mnt</filename>, fix
       <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun
       <filename>nixos-install</filename>.) In most cases,
       <command>nixos-generate-config</command> will figure out the required
@@ -311,8 +410,8 @@
 <screen>
 # nixos-install</screen>
      Cross fingers. If this fails due to a temporary problem (such as a network
-    issue while downloading binaries from the NixOS binary cache), you can just
+     issue while downloading binaries from the NixOS binary cache), you can
-    re-run <command>nixos-install</command>. Otherwise, fix your
+     just re-run <command>nixos-install</command>. Otherwise, fix your
      <filename>configuration.nix</filename> and then re-run
      <command>nixos-install</command>.
     </para>
@@ -322,13 +421,12 @@
 <screen>
 setting root password...
 Enter new UNIX password: ***
-Retype new UNIX password: ***
+Retype new UNIX password: ***</screen>
-    </screen>
      <note>
       <para>
        For unattended installations, it is possible to use
-      <command>nixos-install --no-root-passwd</command> in order to disable the
+       <command>nixos-install --no-root-passwd</command> in order to disable
-      password prompt entirely.
+       the password prompt entirely.
       </para>
      </note>
     </para>
@@ -337,14 +435,14 @@ Retype new UNIX password: ***
     <para>
      If everything went well:
 <screen>
-        # reboot</screen>
+# reboot</screen>
     </para>
    </listitem>
    <listitem>
     <para>
-    You should now be able to boot into the installed NixOS. The GRUB boot menu
+     You should now be able to boot into the installed NixOS. The GRUB boot
-    shows a list of <emphasis>available configurations</emphasis> (initially
+     menu shows a list of <emphasis>available configurations</emphasis>
-    just one). Every time you change the NixOS configuration (see
+     (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
@@ -372,39 +470,41 @@ $ nix-env -i w3m</screen>
     </para>
    </listitem>
   </orderedlist>
+ </section>
+ <section xml:id="sec-installation-summary">
+  <title>Installation summary</title>
+
   <para>
-  To summarise, <xref linkend="ex-install-sequence" /> shows a typical sequence
+   To summarise, <xref linkend="ex-install-sequence" /> shows a typical
-  of commands for installing NixOS on an empty hard drive (here
+   sequence of commands for installing NixOS on an empty hard drive (here
    <filename>/dev/sda</filename>). <xref linkend="ex-config"
 /> shows a
    corresponding configuration Nix expression.
   </para>
- <example xml:id='ex-install-sequence'>
+
+  <example xml:id="ex-partition-scheme-MBR">
+   <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (MBR)</title>
+<screen language="commands">
+# parted /dev/sda -- mklabel msdos
+# parted /dev/sda -- mkpart primary linux-swap 1M 8GiB
+# parted /dev/sda -- mkpart primary 8GiB -1s</screen>
+  </example>
+
+  <example xml:id="ex-partition-scheme-UEFI">
+   <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (UEFI)</title>
+<screen language="commands">
+# parted /dev/sda -- mklabel gpt
+# parted /dev/sda -- mkpart primary linux-swap 512MiB 8.5GiB
+# parted /dev/sda -- mkpart primary 8.5GiB -1MiB
+# parted /dev/sda -- mkpart ESP fat32 1M 512MiB
+# parted /dev/sda -- set 3 boot on</screen>
+  </example>
+
+  <example xml:id="ex-install-sequence">
    <title>Commands for Installing NixOS on <filename>/dev/sda</filename></title>
-<screen>
+   <para>
-# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
+    With a partitioned disk.
--- for UEFI systems only
+<screen language="commands">
-> n      # <lineannotation>(create a new partition for /boot)</lineannotation>
-> 3      # <lineannotation>(make it a partition number 3)</lineannotation>
->        # <lineannotation>(press enter to accept the default)</lineannotation>
-> +512M  # <lineannotation>(the size of the UEFI boot partition)</lineannotation>
-> t      # <lineannotation>(change the partition type ...)</lineannotation>
-> 3      # <lineannotation>(... of the boot partition ...)</lineannotation>
-> 1      # <lineannotation>(... to 'UEFI System')</lineannotation>
--- for BIOS or UEFI systems
-> n      # <lineannotation>(create a new partition for /swap)</lineannotation>
-> 2      # <lineannotation>(make it a partition number 2)</lineannotation>
->        # <lineannotation>(press enter to accept the default)</lineannotation>
-> +8G    # <lineannotation>(the size of the swap partition)</lineannotation>
-> n      # <lineannotation>(create a new partition for /)</lineannotation>
-> 1      # <lineannotation>(make it a partition number 1)</lineannotation>
->        # <lineannotation>(press enter to accept the default)</lineannotation>
->        # <lineannotation>(press enter to accept the default and use the rest of the remaining space)</lineannotation>
-> a      # <lineannotation>(make the partition bootable)</lineannotation>
-> x      # <lineannotation>(enter expert mode)</lineannotation>
-> f      # <lineannotation>(fix up the partition ordering)</lineannotation>
-> r      # <lineannotation>(exit expert mode)</lineannotation>
-> w      # <lineannotation>(write the partition table to disk and exit)</lineannotation>
 # mkfs.ext4 -L nixos /dev/sda1
 # mkswap -L swap /dev/sda2
 # swapon /dev/sda2
@@ -416,7 +516,9 @@ $ nix-env -i w3m</screen>
 # nano /mnt/etc/nixos/configuration.nix
 # nixos-install
 # reboot</screen>
+   </para>
   </example>
+
   <example xml:id='ex-config'>
    <title>NixOS Configuration</title>
 <screen>
@@ -439,9 +541,18 @@ $ nix-env -i w3m</screen>
 }
   </screen>
   </example>
+ </section>
+ <section xml:id="sec-installation-additional-notes">
+  <title>Additional installation notes</title>
+
   <xi:include href="installing-usb.xml" />
+
   <xi:include href="installing-pxe.xml" />
+
   <xi:include href="installing-virtualbox-guest.xml" />
+
   <xi:include href="installing-from-other-distro.xml" />
+
   <xi:include href="installing-behind-a-proxy.xml" />
+ </section>
 </chapter>