Unverified Commit 73ba4de3 authored by Thiago Kenji Okada's avatar Thiago Kenji Okada Committed by GitHub
Browse files

Merge pull request #175128 from davidak/doc-graphical-installer 

nixos/doc: improve install instructions
parents 216a1bfb f701bd59

doc/build-aux/pandoc-filters/docbook-writer/html-elements.lua

0 → 100644
+11 −0
Original line number Diff line number Diff line 
--[[

Converts some HTML elements commonly used in Markdown to corresponding DocBook elements.

]]



function RawInline(elem)

  if elem.format == 'html' and elem.text == '<kbd>' then

    return pandoc.RawInline('docbook', '<keycap>')

  elseif elem.format == 'html' and elem.text == '</kbd>' then

    return pandoc.RawInline('docbook', '</keycap>')

  end

end

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

  ```