BoomMicrophone/nixpkgs-suyu
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

nixos/doc: improve install instructions

Browse source 
- 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 9a91b0f495/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: j-k <dev@j-k.io>
Co-authored-by: Sandro <sandro.jaeckel@gmail.com>
Co-authored-by: Robert Schütz <github@dotlambda.de>
Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>
Co-authored-by: Thiago Kenji Okada <thiagokokada@gmail.com>
This commit is contained in:
davidak 2022-05-27 23:38:35 +02:00
parent fa285355ee
commit f701bd5986
6 changed files with 1023 additions and 553 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1,35 +1,135 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-booting-from-usb"> <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> <para>
For systems without CD drive, the NixOS live CD can be booted from a The image has to be written verbatim to the USB flash drive for it
USB stick. You can use the <literal>dd</literal> utility to write to be bootable on UEFI and BIOS systems. Here are the recommended
the image: <literal>dd if=path-to-image of=/dev/sdX</literal>. Be tools to do that.
careful about specifying the correct drive; you can use the
<literal>lsblk</literal> command to get a list of block devices.
</para> </para>
<note> <section xml:id="sec-booting-from-usb-graphical">
<title>On macOS</title> <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> <programlisting>
$ diskutil list sudo umount /dev/sdX*
[..] </programlisting>
/dev/diskN (external, physical): <orderedlist numeration="arabic" spacing="compact">
#: TYPE NAME SIZE IDENTIFIER <listitem override="4">
[..] <para>
$ diskutil unmountDisk diskN Then use the <literal>dd</literal> utility to write the image
Unmount of all volumes on diskN was successful to the USB flash drive.
$ sudo dd if=nix.iso of=/dev/rdiskN bs=1M </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> </programlisting>
<para> <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 After <literal>dd</literal> completes, a GUI dialog &quot;The disk
you inserted was not readable by this computer&quot; will pop up, you inserted was not readable by this computer&quot; will pop up,
which can be ignored. which can be ignored.
</para> </para>
</note> <note>
<para> <para>
The <literal>dd</literal> utility will write the image verbatim to Using the 'raw' <literal>rdiskX</literal> device instead of
the drive, making it the recommended option for both UEFI and <literal>diskX</literal> with dd completes in minutes instead of
non-UEFI installations. hours.
</para> </para>
</note>
<orderedlist numeration="arabic" spacing="compact">
<listitem override="5">
<para>
Eject the disk when it is finished.
</para>
</listitem>
</orderedlist>
<programlisting>
diskutil eject /dev/diskX
</programlisting>
</section>
</section> </section>

395
nixos/doc/manual/from_md/installation/installing.chapter.xml
View file

@ -1,26 +1,212 @@
<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"> <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> <title>Installing NixOS</title>
<section xml:id="sec-installation-booting"> <section xml:id="sec-installation-booting">
<title>Booting the system</title> <title>Booting from the install medium</title>
<para>
To begin the installation, you have to boot your computer from the
install drive.
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
Plug in the install drive. Then turn on or restart your
computer.
</para>
</listitem>
<listitem>
<para>
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
<quote>USB</quote>). 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.
</para>
<note>
<para>
The key to open the boot menu is different across computer
brands and even models. It can be <keycap>F12</keycap>, but
also <keycap>F1</keycap>, <keycap>F9</keycap>,
<keycap>F10</keycap>, <keycap>Enter</keycap>,
<keycap>Del</keycap>, <keycap>Esc</keycap> 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 <quote>boot from usb</quote>. 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.
</para>
<para>
For Apple computers with Intel processors press and hold the
<keycap>⌥</keycap> (Option or Alt) key until you see the
boot menu. On Apple silicon press and hold the power button.
</para>
</note>
<note>
<para>
If your computer supports both BIOS and UEFI boot, choose
the UEFI option.
</para>
</note>
<note>
<para>
If you use a CD for the installation, the computer will
probably boot from it automatically. If not, choose the
option containing the word <quote>CD</quote> from the boot
menu.
</para>
</note>
</listitem>
<listitem>
<para>
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 <keycap>Enter</keycap> to
speed up).
</para>
</listitem>
<listitem>
<para>
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
<xref linkend="sec-installation-manual" /> there.
</para>
</listitem>
</orderedlist>
</section>
<section xml:id="sec-installation-graphical">
<title>Graphical Installation</title>
<para>
The graphical installer is recommended for desktop users and will
guide you through the installation.
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
In the <quote>Welcome</quote> screen, you can select the
language of the Installer and the installed system.
</para>
<tip>
<para>
Leaving the language as <quote>American English</quote> will
make it easier to search for error messages in a search
engine or to report an issue.
</para>
</tip>
</listitem>
<listitem>
<para>
Next you should choose your location to have the timezone set
correctly. You can actually click on the map!
</para>
<note>
<para>
The installer will use an online service to guess your
location based on your public IP address.
</para>
</note>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
On the <quote>Users</quote> 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.
</para>
</listitem>
<listitem>
<para>
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 <quote>No desktop</quote>.
</para>
<tip>
<para>
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.
</para>
</tip>
</listitem>
<listitem>
<para>
You have the option to allow unfree software in the next
screen.
</para>
</listitem>
<listitem>
<para>
The easiest option in the <quote>Partitioning</quote> screen
is <quote>Erase disk</quote>, which will delete all data from
the selected disk and install the system on it. Also select
<quote>Swap (with Hibernation)</quote> in the dropdown below
it. You have the option to encrypt the whole disk with LUKS.
</para>
<note>
<para>
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 <quote>BIOS</quote>, reboot with the correct option.
</para>
</note>
<warning>
<para>
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.
</para>
</warning>
</listitem>
<listitem>
<para>
Check the choices you made in the <quote>Summary</quote> and
click <quote>Install</quote>.
</para>
<note>
<para>
The installation takes about 15 minutes. The time varies
based on the selected desktop environment, internet
connection speed and disk write speed.
</para>
</note>
</listitem>
<listitem>
<para>
When the install is complete, remove the USB flash drive and
reboot into your new system!
</para>
</listitem>
</orderedlist>
</section>
<section xml:id="sec-installation-manual">
<title>Manual Installation</title>
<para> <para>
NixOS can be installed on BIOS or UEFI systems. The procedure for NixOS can be installed on BIOS or UEFI systems. The procedure for
a UEFI installation is by and large the same as a BIOS a UEFI installation is broadly the same as for a BIOS
installation. The differences are mentioned in the steps that installation. The differences are mentioned in the following
follow. steps.
</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>
<para> <para>
The NixOS manual is available by running The NixOS manual is available by running
<literal>nixos-help</literal>. <literal>nixos-help</literal> in the command line or from the
application menu in the desktop environment.
</para>
<para>
To have access to the command line on the graphical images, open
Terminal (GNOME) or Konsole (Plasma) from the application menu.
</para> </para>
<para> <para>
You are logged-in automatically as <literal>nixos</literal>. The You are logged-in automatically as <literal>nixos</literal>. The
@ -31,11 +217,8 @@
$ sudo -i $ sudo -i
</programlisting> </programlisting>
<para> <para>
If you downloaded the graphical ISO image, you can run You can use <literal>loadkeys</literal> to switch to your
<literal>systemctl start display-manager</literal> to start the preferred keyboard layout. (We even provide neo2 via
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>!) <literal>loadkeys de neo</literal>!)
</para> </para>
<para> <para>
@ -49,8 +232,12 @@ $ sudo -i
bootloader lists boot entries, select the serial console boot bootloader lists boot entries, select the serial console boot
entry. entry.
</para> </para>
<section xml:id="sec-installation-booting-networking"> <section xml:id="sec-installation-manual-networking">
<title>Networking in the installer</title> <title>Networking in the installer</title>
<para>
<anchor xml:id="sec-installation-booting-networking" />
<!-- legacy anchor -->
</para>
<para> <para>
The boot process should have brought up networking (check The boot process should have brought up networking (check
<literal>ip a</literal>). Networking is necessary for the <literal>ip a</literal>). Networking is necessary for the
@ -130,12 +317,15 @@ OK
able to login. able to login.
</para> </para>
</section> </section>
</section> <section xml:id="sec-installation-manual-partitioning">
<section xml:id="sec-installation-partitioning">
<title>Partitioning and formatting</title> <title>Partitioning and formatting</title>
<para> <para>
The NixOS installer doesn’t do any partitioning or formatting, so <anchor xml:id="sec-installation-partitioning" />
you need to do that yourself. <!-- legacy anchor -->
</para>
<para>
The NixOS installer doesn’t do any partitioning or formatting,
so you need to do that yourself.
</para> </para>
<para> <para>
The NixOS installer ships with multiple partitioning tools. The The NixOS installer ships with multiple partitioning tools. The
@ -144,12 +334,16 @@ OK
<literal>cfdisk</literal>, and <literal>cgdisk</literal>. <literal>cfdisk</literal>, and <literal>cgdisk</literal>.
</para> </para>
<para> <para>
The recommended partition scheme differs depending if the computer The recommended partition scheme differs depending if the
uses <emphasis>Legacy Boot</emphasis> or computer uses <emphasis>Legacy Boot</emphasis> or
<emphasis>UEFI</emphasis>. <emphasis>UEFI</emphasis>.
</para> </para>
<section xml:id="sec-installation-partitioning-UEFI"> <section xml:id="sec-installation-manual-partitioning-UEFI">
<title>UEFI (GPT)</title> <title>UEFI (GPT)</title>
<para>
<anchor xml:id="sec-installation-partitioning-UEFI" />
<!-- legacy anchor -->
</para>
<para> <para>
Here's an example partition scheme for UEFI, using Here's an example partition scheme for UEFI, using
<literal>/dev/sda</literal> as the device. <literal>/dev/sda</literal> as the device.
@ -171,10 +365,10 @@ OK
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Add the <emphasis>root</emphasis> partition. This will fill Add the <emphasis>root</emphasis> partition. This will
the disk except for the end part, where the swap will live, fill the disk except for the end part, where the swap will
and the space left in front (512MiB) which will be used by live, and the space left in front (512MiB) which will be
the boot partition. used by the boot partition.
</para> </para>
<programlisting> <programlisting>
# parted /dev/sda -- mkpart primary 512MB -8GB # parted /dev/sda -- mkpart primary 512MB -8GB
@ -200,8 +394,8 @@ OK
<para> <para>
Finally, the <emphasis>boot</emphasis> partition. NixOS by Finally, the <emphasis>boot</emphasis> partition. NixOS by
default uses the ESP (EFI system partition) as its default uses the ESP (EFI system partition) as its
<emphasis>/boot</emphasis> partition. It uses the initially <emphasis>/boot</emphasis> partition. It uses the
reserved 512MiB at the start of the disk. initially reserved 512MiB at the start of the disk.
</para> </para>
<programlisting> <programlisting>
# parted /dev/sda -- mkpart ESP fat32 1MB 512MB # parted /dev/sda -- mkpart ESP fat32 1MB 512MB
@ -211,11 +405,15 @@ OK
</orderedlist> </orderedlist>
<para> <para>
Once complete, you can follow with Once complete, you can follow with
<xref linkend="sec-installation-partitioning-formatting" />. <xref linkend="sec-installation-manual-partitioning-formatting" />.
</para> </para>
</section> </section>
<section xml:id="sec-installation-partitioning-MBR"> <section xml:id="sec-installation-manual-partitioning-MBR">
<title>Legacy Boot (MBR)</title> <title>Legacy Boot (MBR)</title>
<para>
<anchor xml:id="sec-installation-partitioning-MBR" />
<!-- legacy anchor -->
</para>
<para> <para>
Here's an example partition scheme for Legacy Boot, using Here's an example partition scheme for Legacy Boot, using
<literal>/dev/sda</literal> as the device. <literal>/dev/sda</literal> as the device.
@ -237,9 +435,9 @@ OK
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Add the <emphasis>root</emphasis> partition. This will fill Add the <emphasis>root</emphasis> partition. This will
the the disk except for the end part, where the swap will fill the the disk except for the end part, where the swap
live. will live.
</para> </para>
<programlisting> <programlisting>
# parted /dev/sda -- mkpart primary 1MB -8GB # parted /dev/sda -- mkpart primary 1MB -8GB
@ -256,9 +454,9 @@ OK
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Finally, add a <emphasis>swap</emphasis> partition. The size Finally, add a <emphasis>swap</emphasis> partition. The
required will vary according to needs, here a 8GiB one is size required will vary according to needs, here a 8GiB
created. one is created.
</para> </para>
<programlisting> <programlisting>
# parted /dev/sda -- mkpart primary linux-swap -8GB 100% # parted /dev/sda -- mkpart primary linux-swap -8GB 100%
@ -273,11 +471,15 @@ OK
</orderedlist> </orderedlist>
<para> <para>
Once complete, you can follow with Once complete, you can follow with
<xref linkend="sec-installation-partitioning-formatting" />. <xref linkend="sec-installation-manual-partitioning-formatting" />.
</para> </para>
</section> </section>
<section xml:id="sec-installation-partitioning-formatting"> <section xml:id="sec-installation-manual-partitioning-formatting">
<title>Formatting</title> <title>Formatting</title>
<para>
<anchor xml:id="sec-installation-partitioning-formatting" />
<!-- legacy anchor -->
</para>
<para> <para>
Use the following commands: Use the following commands:
</para> </para>
@ -286,10 +488,10 @@ OK
<para> <para>
For initialising Ext4 partitions: For initialising Ext4 partitions:
<literal>mkfs.ext4</literal>. It is recommended that you <literal>mkfs.ext4</literal>. It is recommended that you
assign a unique symbolic label to the file system using the assign a unique symbolic label to the file system using
option <literal>-L label</literal>, since this makes the the option <literal>-L label</literal>, since this makes
file system configuration independent from device changes. the file system configuration independent from device
For example: changes. For example:
</para> </para>
<programlisting> <programlisting>
# mkfs.ext4 -L nixos /dev/sda1 # mkfs.ext4 -L nixos /dev/sda1
@ -334,8 +536,12 @@ OK
</itemizedlist> </itemizedlist>
</section> </section>
</section> </section>
<section xml:id="sec-installation-installing"> <section xml:id="sec-installation-manual-installing">
<title>Installing</title> <title>Installing</title>
<para>
<anchor xml:id="sec-installation-installing" />
<!-- legacy anchor -->
</para>
<orderedlist numeration="arabic"> <orderedlist numeration="arabic">
<listitem> <listitem>
<para> <para>
@ -363,9 +569,9 @@ OK
<para> <para>
If your machine has a limited amount of memory, you may want If your machine has a limited amount of memory, you may want
to activate swap devices now to activate swap devices now
(<literal>swapon device</literal>). The installer (or rather, (<literal>swapon device</literal>). The installer (or
the build actions that it may spawn) may need quite a bit of rather, the build actions that it may spawn) may need quite
RAM, depending on your configuration. a bit of RAM, depending on your configuration.
</para> </para>
<programlisting> <programlisting>
# swapon /dev/sda2 # swapon /dev/sda2
@ -384,7 +590,8 @@ OK
<xref linkend="sec-configuration-syntax" />, while a list of <xref linkend="sec-configuration-syntax" />, while a list of
available configuration options appears in available configuration options appears in
<xref linkend="ch-options" />. A minimal example is shown in <xref linkend="ch-options" />. A minimal example is shown in
<link linkend="ex-config">Example: NixOS Configuration</link>. <link linkend="ex-config">Example: NixOS
Configuration</link>.
</para> </para>
<para> <para>
The command <literal>nixos-generate-config</literal> can The command <literal>nixos-generate-config</literal> can
@ -402,8 +609,8 @@ OK
# nano /mnt/etc/nixos/configuration.nix # nano /mnt/etc/nixos/configuration.nix
</programlisting> </programlisting>
<para> <para>
If you’re using the graphical ISO image, other editors may be If you’re using the graphical ISO image, other editors may
available (such as <literal>vim</literal>). If you have be available (such as <literal>vim</literal>). If you have
network access, you can also install other editors – for network access, you can also install other editors – for
instance, you can install Emacs by running instance, you can install Emacs by running
<literal>nix-env -f '&lt;nixpkgs&gt;' -iA emacs</literal>. <literal>nix-env -f '&lt;nixpkgs&gt;' -iA emacs</literal>.
@ -440,9 +647,9 @@ OK
option option
<xref linkend="opt-boot.loader.systemd-boot.enable" /> <xref linkend="opt-boot.loader.systemd-boot.enable" />
to <literal>true</literal>. to <literal>true</literal>.
<literal>nixos-generate-config</literal> should do this <literal>nixos-generate-config</literal> should do
automatically for new configurations when booted in UEFI this automatically for new configurations when booted
mode. in UEFI mode.
</para> </para>
<para> <para>
You may want to look at the options starting with You may want to look at the options starting with
@ -481,35 +688,36 @@ OK
</para> </para>
<para> <para>
Another critical option is <literal>fileSystems</literal>, Another critical option is <literal>fileSystems</literal>,
specifying the file systems that need to be mounted by NixOS. specifying the file systems that need to be mounted by
However, you typically don’t need to set it yourself, because NixOS. However, you typically don’t need to set it yourself,
<literal>nixos-generate-config</literal> sets it automatically because <literal>nixos-generate-config</literal> sets it
in automatically in
<literal>/mnt/etc/nixos/hardware-configuration.nix</literal> <literal>/mnt/etc/nixos/hardware-configuration.nix</literal>
from your currently mounted file systems. (The configuration from your currently mounted file systems. (The configuration
file <literal>hardware-configuration.nix</literal> is included file <literal>hardware-configuration.nix</literal> is
from <literal>configuration.nix</literal> and will be included from <literal>configuration.nix</literal> and will
overwritten by future invocations of be overwritten by future invocations of
<literal>nixos-generate-config</literal>; thus, you generally <literal>nixos-generate-config</literal>; thus, you
should not modify it.) Additionally, you may want to look at generally should not modify it.) Additionally, you may want
to look at
<link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware <link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware
configuration for known-hardware</link> at this point or after configuration for known-hardware</link> at this point or
installation. after installation.
</para> </para>
<note> <note>
<para> <para>
Depending on your hardware configuration or type of file Depending on your hardware configuration or type of file
system, you may need to set the option system, you may need to set the option
<literal>boot.initrd.kernelModules</literal> to include the <literal>boot.initrd.kernelModules</literal> to include
kernel modules that are necessary for mounting the root file the kernel modules that are necessary for mounting the
system, otherwise the installed system will not be able to root file system, otherwise the installed system will not
boot. (If this happens, boot from the installation media be able to boot. (If this happens, boot from the
again, mount the target file system on installation media again, mount the target file system on
<literal>/mnt</literal>, fix <literal>/mnt</literal>, fix
<literal>/mnt/etc/nixos/configuration.nix</literal> and <literal>/mnt/etc/nixos/configuration.nix</literal> and
rerun <literal>nixos-install</literal>.) In most cases, rerun <literal>nixos-install</literal>.) In most cases,
<literal>nixos-generate-config</literal> will figure out the <literal>nixos-generate-config</literal> will figure out
required modules. the required modules.
</para> </para>
</note> </note>
</listitem> </listitem>
@ -522,16 +730,16 @@ OK
</programlisting> </programlisting>
<para> <para>
This will install your system based on the configuration you This will install your system based on the configuration you
provided. If anything fails due to a configuration problem or provided. If anything fails due to a configuration problem
any other issue (such as a network outage while downloading or any other issue (such as a network outage while
binaries from the NixOS binary cache), you can re-run downloading binaries from the NixOS binary cache), you can
<literal>nixos-install</literal> after fixing your re-run <literal>nixos-install</literal> after fixing your
<literal>configuration.nix</literal>. <literal>configuration.nix</literal>.
</para> </para>
<para> <para>
As the last step, <literal>nixos-install</literal> will ask As the last step, <literal>nixos-install</literal> will ask
you to set the password for the <literal>root</literal> user, you to set the password for the <literal>root</literal>
e.g. user, e.g.
</para> </para>
<programlisting> <programlisting>
setting root password... setting root password...
@ -558,12 +766,12 @@ Retype new password: ***
<para> <para>
You should now be able to boot into the installed NixOS. The You should now be able to boot into the installed NixOS. The
GRUB boot menu shows a list of <emphasis>available GRUB boot menu shows a list of <emphasis>available
configurations</emphasis> (initially just one). Every time you configurations</emphasis> (initially just one). Every time
change the NixOS configuration (see you change the NixOS configuration (see
<link linkend="sec-changing-config">Changing <link linkend="sec-changing-config">Changing
Configuration</link>), a new item is added to the menu. This Configuration</link>), a new item is added to the menu. This
allows you to easily roll back to a previous configuration if allows you to easily roll back to a previous configuration
something goes wrong. if something goes wrong.
</para> </para>
<para> <para>
You should log in and change the <literal>root</literal> You should log in and change the <literal>root</literal>
@ -584,16 +792,20 @@ $ passwd eelco
</listitem> </listitem>
</orderedlist> </orderedlist>
</section> </section>
<section xml:id="sec-installation-summary"> <section xml:id="sec-installation-manual-summary">
<title>Installation summary</title> <title>Installation summary</title>
<para>
<anchor xml:id="sec-installation-summary" />
<!-- legacy anchor -->
</para>
<para> <para>
To summarise, <link linkend="ex-install-sequence">Example: To summarise, <link linkend="ex-install-sequence">Example:
Commands for Installing NixOS on Commands for Installing NixOS on
<literal>/dev/sda</literal></link> shows a typical sequence of <literal>/dev/sda</literal></link> shows a typical sequence of
commands for installing NixOS on an empty hard drive (here commands for installing NixOS on an empty hard drive (here
<literal>/dev/sda</literal>). <link linkend="ex-config">Example: <literal>/dev/sda</literal>). <link linkend="ex-config">Example:
NixOS Configuration</link> shows a corresponding configuration Nix NixOS Configuration</link> shows a corresponding configuration
expression. Nix expression.
</para> </para>
<anchor xml:id="ex-partition-scheme-MBR" /> <anchor xml:id="ex-partition-scheme-MBR" />
<para> <para>
@ -619,8 +831,8 @@ $ passwd eelco
</programlisting> </programlisting>
<anchor xml:id="ex-install-sequence" /> <anchor xml:id="ex-install-sequence" />
<para> <para>
<emphasis role="strong">Example: Commands for Installing NixOS on <emphasis role="strong">Example: Commands for Installing NixOS
<literal>/dev/sda</literal></emphasis> on <literal>/dev/sda</literal></emphasis>
</para> </para>
<para> <para>
With a partitioned disk. With a partitioned disk.
@ -662,6 +874,7 @@ $ passwd eelco
} }
</programlisting> </programlisting>
</section> </section>
</section>
<section xml:id="sec-installation-additional-notes"> <section xml:id="sec-installation-additional-notes">
<title>Additional installation notes</title> <title>Additional installation notes</title>
<xi:include href="installing-usb.section.xml" /> <xi:include href="installing-usb.section.xml" />

29
nixos/doc/manual/from_md/installation/obtaining.chapter.xml
View file

@ -2,16 +2,15 @@
<title>Obtaining NixOS</title> <title>Obtaining NixOS</title>
<para> <para>
NixOS ISO images can be downloaded from the NixOS ISO images can be downloaded from the
<link xlink:href="https://nixos.org/nixos/download.html">NixOS <link xlink:href="https://nixos.org/download.html#nixos-iso">NixOS
download page</link>. There are a number of installation options. If download page</link>. Follow the instructions in
you happen to have an optical drive and a spare CD, burning the <xref linkend="sec-booting-from-usb" /> to create a bootable USB
image to CD and booting from that is probably the easiest option. flash drive.
Most people will need to prepare a USB stick to boot from. </para>
<xref linkend="sec-booting-from-usb" /> describes the preferred <para>
method to prepare a USB stick. A number of alternative methods are If you have a very old system that can’t boot from USB, you can burn
presented in the the image to an empty CD. NixOS might not work very well on such
<link xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS systems.
Wiki</link>.
</para> </para>
<para> <para>
As an alternative to installing NixOS yourself, you can get a As an alternative to installing NixOS yourself, you can get a
@ -23,16 +22,16 @@
Using virtual appliances in Open Virtualization Format (OVF) Using virtual appliances in Open Virtualization Format (OVF)
that can be imported into VirtualBox. These are available from that can be imported into VirtualBox. These are available from
the 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>. download page</link>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Using AMIs for Amazon’s EC2. To find one for your region and Using AMIs for Amazon’s EC2. To find one for your region, please
instance type, please refer to the refer to the
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list <link xlink:href="https://nixos.org/download.html#nixos-amazon">download
of most recent AMIs</link>. page</link>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>

81
nixos/doc/manual/installation/installing-usb.section.md
View file

@ -1,31 +1,72 @@
# 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 The image has to be written verbatim to the USB flash drive for it to be
stick. You can use the `dd` utility to write the image: bootable on UEFI and BIOS systems. Here are the recommended tools to do that.
`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.
::: {.note} ## Creating bootable USB flash drive with a graphical tool {#sec-booting-from-usb-graphical}
::: {.title}
On macOS 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 ```ShellSession
$ diskutil list sudo umount /dev/sdX*
[..]
/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
``` ```
Using the \'raw\' `rdiskN` device instead of `diskN` completes in 4. Then use the `dd` utility to write the image to the USB flash drive.
minutes instead of hours. After `dd` completes, a GUI dialog \"The disk
```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 you inserted was not readable by this computer\" will pop up, which can
be ignored. 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 5. Eject the disk when it is finished.
the recommended option for both UEFI and non-UEFI installations.
```ShellSession
diskutil eject /dev/diskX
```

166
nixos/doc/manual/installation/installing.chapter.md
View file

@ -1,30 +1,143 @@
# Installing NixOS {#sec-installation} # Installing NixOS {#sec-installation}
## Booting the system {#sec-installation-booting} ## Booting from the install medium {#sec-installation-booting}
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.
::: {.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.
:::
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.
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 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 installation is broadly the same as for a BIOS installation. The differences
differences are mentioned in the steps that follow. are mentioned in the following steps.
The installation media can be burned to a CD, or now more commonly, The NixOS manual is available by running `nixos-help` in the command line
"burned" to a USB drive (see [](#sec-booting-from-usb)). or from the application menu in the desktop environment.
The installation media contains a basic NixOS installation. When it's To have access to the command line on the graphical images, open
finished booting, it should have detected most of your hardware. Terminal (GNOME) or Konsole (Plasma) from the application menu.
The NixOS manual is available by running `nixos-help`.
You are logged-in automatically as `nixos`. The `nixos` user account has You are logged-in automatically as `nixos`. The `nixos` user account has
an empty password so you can use `sudo` without a password: an empty password so you can use `sudo` without a password:
```ShellSession ```ShellSession
$ sudo -i $ sudo -i
``` ```
If you downloaded the graphical ISO image, you can run `systemctl You can use `loadkeys` to switch to your preferred keyboard layout.
start display-manager` to start the desktop environment. If you want (We even provide neo2 via `loadkeys de neo`!)
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 If the text is too small to be legible, try `setfont ter-v32n` to
increase the font size. 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 `picocom -b 115200 /dev/ttyUSB0`). When the bootloader lists boot
entries, select the serial console boot entry. 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 The boot process should have brought up networking (check `ip
a`). Networking is necessary for the installer, since it will 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 must set a password for either `root` or `nixos` with `passwd` to be
able to login. 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 The NixOS installer doesn't do any partitioning or formatting, so you
need to do that yourself. 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 The recommended partition scheme differs depending if the computer uses
*Legacy Boot* or *UEFI*. *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 Here\'s an example partition scheme for UEFI, using `/dev/sda` as the
device. device.
@ -158,9 +274,10 @@ update /etc/fstab.
``` ```
Once complete, you can follow with 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 Here\'s an example partition scheme for Legacy Boot, using `/dev/sda` as
the device. the device.
@ -202,9 +319,10 @@ update /etc/fstab.
::: :::
Once complete, you can follow with 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: Use the following commands:
@ -239,7 +357,8 @@ Use the following commands:
- For creating software RAID devices, use `mdadm`. - 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 1. Mount the target file system on which NixOS should be installed on
`/mnt`, e.g. `/mnt`, e.g.
@ -410,7 +529,8 @@ Use the following commands:
You may also want to install some software. This will be covered in You may also want to install some software. This will be covered in
[](#sec-package-management). [](#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) 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 shows a typical sequence of commands for installing NixOS on an empty hard

19
nixos/doc/manual/installation/obtaining.chapter.md
View file

@ -1,24 +1,21 @@
# Obtaining NixOS {#sec-obtaining} # Obtaining NixOS {#sec-obtaining}
NixOS ISO images can be downloaded from the [NixOS download NixOS ISO images can be downloaded from the [NixOS download
page](https://nixos.org/nixos/download.html). There are a number of page](https://nixos.org/download.html#nixos-iso). Follow the instructions in
installation options. If you happen to have an optical drive and a spare [](#sec-booting-from-usb) to create a bootable USB flash drive.
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 If you have a very old system that can't boot from USB, you can burn the image
from. [](#sec-booting-from-usb) describes the preferred method to to an empty CD. NixOS might not work very well on such systems.
prepare a USB stick. A number of alternative methods are presented in
the [NixOS Wiki](https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media).
As an alternative to installing NixOS yourself, you can get a running As an alternative to installing NixOS yourself, you can get a running
NixOS system through several other means: NixOS system through several other means:
- Using virtual appliances in Open Virtualization Format (OVF) that - Using virtual appliances in Open Virtualization Format (OVF) that
can be imported into VirtualBox. These are available from the [NixOS can be imported into VirtualBox. These are available from the [NixOS
download page](https://nixos.org/nixos/download.html). download page](https://nixos.org/download.html#nixos-virtualbox).
- Using AMIs for Amazon's EC2. To find one for your region and - Using AMIs for Amazon's EC2. To find one for your region, please refer
instance type, please refer to the [list of most recent to the [download page](https://nixos.org/download.html#nixos-amazon).
AMIs](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix).
- Using NixOps, the NixOS-based cloud deployment tool, which allows - Using NixOps, the NixOS-based cloud deployment tool, which allows
you to provision VirtualBox and EC2 NixOS instances from declarative you to provision VirtualBox and EC2 NixOS instances from declarative