path: root/nixos/doc/manual/installation/installing.xml

<chapter 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-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, "burned"
   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 on virtual console 8 (press Alt+F8 to access)
   or by running <command>nixos-help</command>.
  </para>

  <para>
   You are logged-in automatically as <literal>root</literal>. (The
   <literal>root</literal> user account has an empty password.)
  </para>

  <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 the
   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>

  <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
    download lots of stuff (such as source tarballs or Nixpkgs channel
    binaries). It’s best if you have a DHCP server on your network. Otherwise
    configure networking manually using <command>ifconfig</command>.
   </para>

   <para>
    To manually configure the network on the graphical installer, first disable
    network-manager with <command>systemctl stop NetworkManager</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>

   <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>
  </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>
       Create a <emphasis>GPT</emphasis> partition table.
<screen language="commands"># parted /dev/sda -- mklabel gpt</screen>
      </para>
     </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.
<screen language="commands"># parted /dev/sda -- mkpart primary 512MiB -8GiB</screen>
      </para>
     </listitem>
     <listitem>
      <para>
       Next, 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 -8GiB 100%</screen>
       <note>
        <para>
         The swap partition size rules are no different than for other Linux
         distributions.
        </para>
       </note>
      </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 1MiB 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 the <emphasis>root</emphasis> partition. This will fill the the disk
       except for the end part, where the swap will live.
<screen language="commands"># parted /dev/sda -- mkpart primary 1MiB -8GiB</screen>
      </para>
     </listitem>
     <listitem>
      <para>
       Finally, 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 -8GiB 100%</screen>
       <note>
        <para>
         The swap partition size rules are no different than for other Linux
         distributions.
        </para>
       </note>
      </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
       recommended that you assign a unique symbolic label to the file system
       using the option <option>-L <replaceable>label</replaceable></option>,
       since this makes the file system configuration independent from device
       changes. For example:
<screen>
# mkfs.ext4 -L nixos /dev/sda1</screen>
      </para>
     </listitem>
     <listitem>
      <para>
       For creating swap partitions: <command>mkswap</command>. Again it’s
       recommended to assign a label to the swap partition: <option>-L
       <replaceable>label</replaceable></option>. For example:
<screen>
# mkswap -L swap /dev/sda2</screen>
      </para>
     </listitem>
     <listitem>
      <variablelist>
       <varlistentry>