Commit f701bd59 authored by davidak's avatar davidak
Browse files

nixos/doc: improve install instructions 

- Update download URLs
- Replace "USB stick"/"USB Drive" with "USB flash drive" as that seem more correct

  https://en.wikipedia.org/wiki/USB_flash_drive
  https://elementary.io/docs/installation#choose-operating-system

- Don't mention CD as easiest option anymore,
  as all modern systems should be able to boot from USB,
  but many don't have a CD drive. Burning CDs is also usually wasteful as you
  can't burn them again.
- Remove link to NixOS Wiki (Making_the_installation_media) as it is not needed
- Add Etcher and USBImager as graphical tools to create install drive
- Make dd command consistent and use block size of 4 MB for faster flashing
- More consistent text
- Add instructions for "Booting from the install medium"

  Inspired by https://github.com/elementary/website/blob/9a91b0f4956b059db02122fbc738c4c067e033a7/docs/installation.md#booting-from-the-install-drive-booting-from-the-installation-medium-clear-float-2



- Add instructions for "Graphical Installation"
- Restructure headings and anchors for "Manual Installation"
- Adding legacy anchors for "Manual Installation" to not break links

Co-authored-by: default avatarj-k <dev@j-k.io>
Co-authored-by: default avatarSandro <sandro.jaeckel@gmail.com>
Co-authored-by: default avatarRobert Schütz <github@dotlambda.de>
Co-authored-by: default avatarJörg Thalheim <Mic92@users.noreply.github.com>
Co-authored-by: default avatarThiago Kenji Okada <thiagokokada@gmail.com>
parent fa285355

nixos/doc/manual/from_md/installation/installing-usb.section.xml

+124 −24
Original line number Diff line number Diff line 
<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>

  <title>Booting from a USB flash 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.

    The image has to be written verbatim to the USB flash drive for it

    to be bootable on UEFI and BIOS systems. Here are the recommended

    tools to do that.

  </para>

  <note>

    <title>On macOS</title>

  <section xml:id="sec-booting-from-usb-graphical">

    <title>Creating bootable USB flash drive with a graphical

    tool</title>

    <para>

      Etcher is a popular and user-friendly tool. It works on Linux,

      Windows and macOS.

    </para>

    <para>

      Download it from

      <link xlink:href="https://www.balena.io/etcher/">balena.io</link>,

      start the program, select the downloaded NixOS ISO, then select

      the USB flash drive and flash it.

    </para>

    <warning>

      <para>

        Etcher reports errors and usage statistics by default, which can

        be disabled in the settings.

      </para>

    </warning>

    <para>

      An alternative is

      <link xlink:href="https://bztsrc.gitlab.io/usbimager">USBImager</link>,

      which is very simple and does not connect to the internet.

      Download the version with write-only (wo) interface for your

      system. Start the program, select the image, select the USB flash

      drive and click <quote>Write</quote>.

    </para>

  </section>

  <section xml:id="sec-booting-from-usb-linux">

    <title>Creating bootable USB flash drive from a Terminal on

    Linux</title>

    <orderedlist numeration="arabic" spacing="compact">

      <listitem>

        <para>

          Plug in the USB flash drive.

        </para>

      </listitem>

      <listitem>

        <para>

          Find the corresponding device with <literal>lsblk</literal>.

          You can distinguish them by their size.

        </para>

      </listitem>

      <listitem>

        <para>

          Make sure all partitions on the device are properly unmounted.

          Replace <literal>sdX</literal> with your device (e.g.

          <literal>sdb</literal>).

        </para>

      </listitem>

    </orderedlist>

    <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 bs=1M

sudo umount /dev/sdX*

</programlisting>

    <orderedlist numeration="arabic" spacing="compact">

      <listitem override="4">

        <para>

          Then use the <literal>dd</literal> utility to write the image

          to the USB flash drive.

        </para>

      </listitem>

    </orderedlist>

    <programlisting>

sudo dd if=&lt;path-to-image&gt; of=/dev/sdX bs=4M conv=fsync

</programlisting>

  </section>

  <section xml:id="sec-booting-from-usb-macos">

    <title>Creating bootable USB flash drive from a Terminal on

    macOS</title>

    <orderedlist numeration="arabic" spacing="compact">

      <listitem>

        <para>

          Plug in the USB flash drive.

        </para>

      </listitem>

      <listitem>

        <para>

          Find the corresponding device with

          <literal>diskutil list</literal>. You can distinguish them by

          their size.

        </para>

      </listitem>

      <listitem>

        <para>

          Make sure all partitions on the device are properly unmounted.

          Replace <literal>diskX</literal> with your device (e.g.

          <literal>disk1</literal>).

        </para>

      </listitem>

    </orderedlist>

    <programlisting>

diskutil unmountDisk diskX

</programlisting>

    <orderedlist numeration="arabic" spacing="compact">

      <listitem override="4">

        <para>

          Then use the <literal>dd</literal> utility to write the image

          to the USB flash drive.

        </para>

      </listitem>

    </orderedlist>

    <programlisting>

sudo dd if=&lt;path-to-image&gt; of=/dev/rdiskX bs=4m

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

        Using the 'raw' <literal>rdiskX</literal> device instead of

        <literal>diskX</literal> with dd completes in minutes instead of

        hours.

      </para>

    </note>

    <orderedlist numeration="arabic" spacing="compact">

      <listitem override="5">

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

          Eject the disk when it is finished.

        </para>

      </listitem>

    </orderedlist>

    <programlisting>

diskutil eject /dev/diskX

</programlisting>

  </section>

</section>

nixos/doc/manual/from_md/installation/installing.chapter.xml

+646 −433

File changed.

Preview size limit exceeded, changes collapsed.

nixos/doc/manual/from_md/installation/obtaining.chapter.xml

+14 −15
Original line number Diff line number Diff line
@@ -2,16 +2,15 @@ 
  <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>.

    <link xlink:href="https://nixos.org/download.html#nixos-iso">NixOS

    download page</link>. Follow the instructions in

    <xref linkend="sec-booting-from-usb" /> to create a bootable USB

    flash drive.

  </para>

  <para>

    If you have a very old system that can’t boot from USB, you can burn

    the image to an empty CD. NixOS might not work very well on such

    systems.

  </para>

  <para>

    As an alternative to installing NixOS yourself, you can get a
@@ -23,16 +22,16 @@ 
        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

        <link xlink:href="https://nixos.org/download.html#nixos-virtualbox">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>.

        Using AMIs for Amazon’s EC2. To find one for your region, please

        refer to the

        <link xlink:href="https://nixos.org/download.html#nixos-amazon">download

        page</link>.

      </para>

    </listitem>

    <listitem>

nixos/doc/manual/installation/installing-usb.section.md

+67 −26
Original line number Diff line number Diff line 
# Booting from a USB Drive {#sec-booting-from-usb}

# Booting from a USB flash drive {#sec-booting-from-usb}



For systems without CD drive, the NixOS live CD can be booted from a USB

stick. You can use the `dd` utility to write the image:

`dd if=path-to-image of=/dev/sdX`. Be careful about specifying the correct

drive; you can use the `lsblk` command to get a list of block devices.

The image has to be written verbatim to the USB flash drive for it to be

bootable on UEFI and BIOS systems. Here are the recommended tools to do that.



::: {.note}

::: {.title}

On macOS

## Creating bootable USB flash drive with a graphical tool {#sec-booting-from-usb-graphical}



Etcher is a popular and user-friendly tool. It works on Linux, Windows and macOS.



Download it from [balena.io](https://www.balena.io/etcher/), start the program,

select the downloaded NixOS ISO, then select the USB flash drive and flash it.



::: {.warning}

Etcher reports errors and usage statistics by default, which can be disabled in

the settings.

:::



An alternative is [USBImager](https://bztsrc.gitlab.io/usbimager),

which is very simple and does not connect to the internet. Download the version

with write-only (wo) interface for your system. Start the program,

select the image, select the USB flash drive and click "Write".



## Creating bootable USB flash drive from a Terminal on Linux {#sec-booting-from-usb-linux}



1. Plug in the USB flash drive.

2. Find the corresponding device with `lsblk`. You can distinguish them by

   their size.

3. Make sure all partitions on the device are properly unmounted. Replace `sdX`

   with your device (e.g. `sdb`).



  ```ShellSession

$ 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 bs=1M

  sudo umount /dev/sdX*

  ```



Using the \'raw\' `rdiskN` device instead of `diskN` completes in

minutes instead of hours. After `dd` completes, a GUI dialog \"The disk

4. Then use the `dd` utility to write the image to the USB flash drive.



  ```ShellSession

  sudo dd if=<path-to-image> of=/dev/sdX bs=4M conv=fsync

  ```



## Creating bootable USB flash drive from a Terminal on macOS {#sec-booting-from-usb-macos}



1. Plug in the USB flash drive.

2. Find the corresponding device with `diskutil list`. You can distinguish them

   by their size.

3. Make sure all partitions on the device are properly unmounted. Replace `diskX`

   with your device (e.g. `disk1`).



  ```ShellSession

  diskutil unmountDisk diskX

  ```



4. Then use the `dd` utility to write the image to the USB flash drive.



  ```ShellSession

  sudo dd if=<path-to-image> of=/dev/rdiskX bs=4m

  ```



  After `dd` completes, a GUI dialog \"The disk

  you inserted was not readable by this computer\" will pop up, which can

  be ignored.



  ::: {.note}

  Using the \'raw\' `rdiskX` device instead of `diskX` with dd completes in

  minutes instead of hours.

  :::



The `dd` utility will write the image verbatim to the drive, making it

the recommended option for both UEFI and non-UEFI installations.
 
5. Eject the disk when it is finished.



  ```ShellSession

  diskutil eject /dev/diskX

  ```

nixos/doc/manual/installation/installing.chapter.md

+143 −23
Original line number Diff line number Diff line 
# Installing NixOS {#sec-installation}



## Booting the system {#sec-installation-booting}

## Booting from the install medium {#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.

To begin the installation, you have to boot your computer from the install drive.



1.   Plug in the install drive. Then turn on or restart your computer.



2.   Open the boot menu by pressing the appropriate key, which is usually shown

     on the display on early boot.

     Select the USB flash drive (the option usually contains the word "USB").

     If you choose the incorrect drive, your computer will likely continue to

     boot as normal. In that case restart your computer and pick a

     different drive.



     ::: {.note}

     The key to open the boot menu is different across computer brands and even

     models. It can be <kbd>F12</kbd>, but also <kbd>F1</kbd>,

     <kbd>F9</kbd>, <kbd>F10</kbd>, <kbd>Enter</kbd>, <kbd>Del</kbd>,

     <kbd>Esc</kbd> or another function key. If you are unsure and don't see

     it on the early boot screen, you can search online for your computers

     brand, model followed by "boot from usb".

     The computer might not even have that feature, so you have to go into the

     BIOS/UEFI settings to change the boot order. Again, search online for

     details about your specific computer model.



     For Apple computers with Intel processors press and hold the <kbd>⌥</kbd>

     (Option or Alt) key until you see the boot menu. On Apple silicon press

     and hold the power button.

     :::



     ::: {.note}

     If your computer supports both BIOS and UEFI boot, choose the UEFI option.

     :::



     ::: {.note}

     If you use a CD for the installation, the computer will probably boot from

     it automatically. If not, choose the option containing the word "CD" from

     the boot menu.

     :::



3.   Shortly after selecting the appropriate boot drive, you should be

     presented with a menu with different installer options. Leave the default

     and wait (or press <kbd>Enter</kbd> to speed up).



4.   The graphical images will start their corresponding desktop environment

     and the graphical installer, which can take some time. The minimal images

     will boot to a command line. You have to follow the instructions in

     [](#sec-installation-manual) there.



## Graphical Installation {#sec-installation-graphical}



The graphical installer is recommended for desktop users and will guide you

through the installation.



1.   In the "Welcome" screen, you can select the language of the Installer and

     the installed system.



The installation media can be burned to a CD, or now more commonly,

"burned" to a USB drive (see [](#sec-booting-from-usb)).

     ::: {.tip}

     Leaving the language as "American English" will make it easier to search for

     error messages in a search engine or to report an issue.

     :::



2.   Next you should choose your location to have the timezone set correctly.

     You can actually click on the map!



     ::: {.note}

     The installer will use an online service to guess your location based on

     your public IP address.

     :::



The installation media contains a basic NixOS installation. When it's

finished booting, it should have detected most of your hardware.

3.   Then you can select the keyboard layout. The default keyboard model should

     work well with most desktop keyboards. If you have a special keyboard or

     notebook, your model might be in the list. Select the language you are most

     comfortable typing in.



The NixOS manual is available by running `nixos-help`.

4.   On the "Users" screen, you have to type in your display name, login name

     and password. You can also enable an option to automatically login to the

     desktop.



5.   Then you have the option to choose a desktop environment. If you want to

     create a custom setup with a window manager, you can select "No desktop".



     ::: {.tip}

     If you don't have a favorite desktop and don't know which one to choose,

     you can stick to either GNOME or Plasma. They have a quite different

     design, so you should choose whichever you like better.

     They are both popular choices and well tested on NixOS.

     :::



6.   You have the option to allow unfree software in the next screen.



7.   The easiest option in the "Partitioning" screen is "Erase disk", which will

     delete all data from the selected disk and install the system on it.

     Also select "Swap (with Hibernation)" in the dropdown below it.

     You have the option to encrypt the whole disk with LUKS.



     ::: {.note}

     At the top left you see if the Installer was booted with BIOS or UEFI. If

     you know your system supports UEFI and it shows "BIOS", reboot with the

     correct option.

     :::



     ::: {.warning}

     Make sure you have selected the correct disk at the top and that no

     valuable data is still on the disk! It will be deleted when

     formatting the disk.

     :::



8.   Check the choices you made in the "Summary" and click "Install".



     ::: {.note}

     The installation takes about 15 minutes. The time varies based on the

     selected desktop environment, internet connection speed and disk write speed.

     :::



9.  When the install is complete, remove the USB flash drive and

    reboot into your new system!



## Manual Installation {#sec-installation-manual}



NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI

installation is broadly the same as for a BIOS installation. The differences

are mentioned in the following steps.



The NixOS manual is available by running `nixos-help` in the command line

or from the application menu in the desktop environment.



To have access to the command line on the graphical images, open

Terminal (GNOME) or Konsole (Plasma) from the application menu.



You are logged-in automatically as `nixos`. The `nixos` user account has

an empty password so you can use `sudo` without a password:



```ShellSession

$ sudo -i

```



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`!)

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.
@@ -33,7 +146,8 @@ 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}

### Networking in the installer {#sec-installation-manual-networking}

[]{#sec-installation-booting-networking} <!-- legacy anchor -->



The boot process should have brought up networking (check `ip

a`). Networking is necessary for the installer, since it will
@@ -100,7 +214,8 @@ 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}

### Partitioning and formatting {#sec-installation-manual-partitioning}

[]{#sec-installation-partitioning} <!-- legacy anchor -->



The NixOS installer doesn't do any partitioning or formatting, so you

need to do that yourself.
@@ -112,7 +227,8 @@ below use `parted`, but also provides `fdisk`, `gdisk`, `cfdisk`, and 
The recommended partition scheme differs depending if the computer uses

*Legacy Boot* or *UEFI*.



### UEFI (GPT) {#sec-installation-partitioning-UEFI}

#### UEFI (GPT) {#sec-installation-manual-partitioning-UEFI}

[]{#sec-installation-partitioning-UEFI} <!-- legacy anchor -->



Here\'s an example partition scheme for UEFI, using `/dev/sda` as the

device.
@@ -158,9 +274,10 @@ update /etc/fstab. 
    ```



Once complete, you can follow with

[](#sec-installation-partitioning-formatting).

[](#sec-installation-manual-partitioning-formatting).



### Legacy Boot (MBR) {#sec-installation-partitioning-MBR}

#### Legacy Boot (MBR) {#sec-installation-manual-partitioning-MBR}

[]{#sec-installation-partitioning-MBR} <!-- legacy anchor -->



Here\'s an example partition scheme for Legacy Boot, using `/dev/sda` as

the device.
@@ -202,9 +319,10 @@ update /etc/fstab. 
    :::



Once complete, you can follow with

[](#sec-installation-partitioning-formatting).

[](#sec-installation-manual-partitioning-formatting).



### Formatting {#sec-installation-partitioning-formatting}

#### Formatting {#sec-installation-manual-partitioning-formatting}

[]{#sec-installation-partitioning-formatting} <!-- legacy anchor -->



Use the following commands:
@@ -239,7 +357,8 @@ Use the following commands: 


-   For creating software RAID devices, use `mdadm`.



## Installing {#sec-installation-installing}

### Installing {#sec-installation-manual-installing}

[]{#sec-installation-installing} <!-- legacy anchor -->



1.  Mount the target file system on which NixOS should be installed on

    `/mnt`, e.g.
@@ -410,7 +529,8 @@ Use the following commands: 
    You may also want to install some software. This will be covered in

    [](#sec-package-management).



## Installation summary {#sec-installation-summary}

### Installation summary {#sec-installation-manual-summary}

[]{#sec-installation-summary} <!-- legacy anchor -->



To summarise, [Example: Commands for Installing NixOS on `/dev/sda`](#ex-install-sequence)

shows a typical sequence of commands for installing NixOS on an empty hard