diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile
index 2e9adf70c396..b251a1f5e2c3 100644
--- a/nixos/doc/manual/Makefile
+++ b/nixos/doc/manual/Makefile
@@ -4,7 +4,7 @@ all: manual-combined.xml format
.PHONY: debug
debug: generated manual-combined.xml
-manual-combined.xml: generated *.xml
+manual-combined.xml: generated *.xml **/*.xml
rm -f ./manual-combined.xml
nix-shell --packages xmloscopy \
--run "xmloscopy --docbook5 ./manual.xml ./manual-combined.xml"
diff --git a/nixos/doc/manual/installation/installing-usb.xml b/nixos/doc/manual/installation/installing-usb.xml
index c5934111749c..0b311189430c 100644
--- a/nixos/doc/manual/installation/installing-usb.xml
+++ b/nixos/doc/manual/installation/installing-usb.xml
@@ -9,13 +9,12 @@
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/sdb. Be careful about specifying
+ of=/dev/sdX. Be careful about specifying
the correct drive; you can use the lsblk command to get a
list of block devices.
-
-
-
- On macOS:
+
+ On macOS
+
$ diskutil list
[..]
@@ -26,43 +25,16 @@ $ diskutil unmountDisk diskN
Unmount of all volumes on diskN was successful
$ sudo dd bs=1m if=nix.iso of=/dev/rdiskN
- Using the 'raw' rdiskN device instead of
- diskN completes in minutes instead of hours. After
- dd completes, a GUI dialog "The disk you inserted was not
- readable by this computer" will pop up, which can be ignored.
+ Using the 'raw' rdiskN device instead of
+ diskN completes in minutes instead of hours. After
+ dd completes, a GUI dialog "The disk you inserted was
+ not readable by this computer" will pop up, which can be ignored.
+
+
The dd utility will write the image verbatim to the drive,
making it the recommended option for both UEFI and non-UEFI installations.
- For non-UEFI installations, you can alternatively use
- unetbootin. If
- you cannot use dd for a UEFI installation, you can also
- mount the ISO, copy its contents verbatim to your drive, then either:
-
-
-
- Change the label of the disk partition to the label of the ISO (visible
- with the blkid command), or
-
-
-
-
- Edit loader/entries/nixos-livecd.conf on the drive
- and change the root= field in the
- options line to point to your drive (see the
- documentation on root= in
-
- the kernel documentation for more details).
-
-
-
-
- If you want to load the contents of the ISO to ram after bootin (So you
- can remove the stick after bootup) you can append the parameter
- copytoram to the options field.
-
-
-
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml
index 1366e8f93596..2b68def95b70 100644
--- a/nixos/doc/manual/installation/installing.xml
+++ b/nixos/doc/manual/installation/installing.xml
@@ -4,60 +4,46 @@
version="5.0"
xml:id="sec-installation">
Installing NixOS
-
- 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.
-
-
-
-
- Boot from the CD.
-
-
-
-
- UEFI systems
-
-
-
- You should boot the live CD in UEFI mode (consult your specific
- hardware's documentation for instructions). You may find the
- rEFInd boot
- manager useful.
-
-
-
-
-
-
-
- The CD contains a basic NixOS installation. (It also contains Memtest86+,
- useful if you want to test new hardware). When it’s finished booting, it
- should have detected most of your hardware.
-
-
-
-
- The NixOS manual is available on virtual console 8 (press Alt+F8 to access)
- or by running nixos-help.
-
-
-
-
- You get logged in as root (with empty password).
-
-
-
-
- If you downloaded the graphical ISO image, you can run systemctl
- start display-manager to start KDE. 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!)
-
-
-
+
+ Booting the system
+
+
+ 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.
+
+
+
+ The installation media can be burned to a CD, or now more commonly, "burned"
+ to a USB drive (see ).
+
+
+
+ The installation media contains a basic NixOS installation. When it’s
+ finished booting, it should have detected most of your hardware.
+
+
+
+ The NixOS manual is available on virtual console 8 (press Alt+F8 to access)
+ or by running nixos-help.
+
+
+
+ You are logged-in automatically as root. (The
+ root user account has an empty password.)
+
+
+
+ If you downloaded the graphical ISO image, you can run systemctl
+ start display-manager to start KDE. 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!)
+
+
+
+ Networking in the installer
+
The boot process should have brought up networking (check ip
a). Networking is necessary for the installer, since it will
@@ -65,58 +51,165 @@
binaries). It’s best if you have a DHCP server on your network. Otherwise
configure networking manually using ifconfig.
+
To manually configure the network on the graphical installer, first disable
network-manager with systemctl stop network-manager.
+
To manually configure the wifi on the minimal installer, run
wpa_supplicant -B -i interface -c <(wpa_passphrase 'SSID'
'key').
-
-
+
If you would like to continue the installation from a different machine you
need to activate the SSH daemon via systemctl start
sshd. In order to be able to login you also need to set a
password for root using passwd.
-
-
+
+
+
+ Partitioning and formatting
+
+
+ The NixOS installer doesn’t do any partitioning or formatting, so you need
+ to do that yourself.
+
+
+
+ The NixOS installer ships with multiple partitioning tools. The examples
+ below use parted, but also provides
+ fdisk, gdisk,
+ cfdisk, and cgdisk.
+
+
+
+ The recommended partition scheme differs depending if the computer uses
+ Legacy Boot or UEFI.
+
+
+
+ UEFI (GPT)
+
- The NixOS installer doesn’t do any partitioning or formatting yet, so you
- need to do that yourself. Use the following commands:
-
+ Here's an example partition scheme for UEFI, using
+ /dev/sda as the device.
+
+
+ You can safely ignore parted's informational message
+ about needing to update /etc/fstab.
+
+
+
+
+
+
- For partitioning: fdisk.
-
-# fdisk /dev/sda # (or whatever device you want to install on)
--- for UEFI systems only
-> n # (create a new partition for /boot)
-> 3 # (make it a partition number 3)
-> # (press enter to accept the default)
-> +512M # (the size of the UEFI boot partition)
-> t # (change the partition type ...)
-> 3 # (... of the boot partition ...)
-> 1 # (... to 'UEFI System')
--- for BIOS or UEFI systems
-> n # (create a new partition for /swap)
-> 2 # (make it a partition number 2)
-> # (press enter to accept the default)
-> +8G # (the size of the swap partition, set to whatever you like)
-> n # (create a new partition for /)
-> 1 # (make it a partition number 1)
-> # (press enter to accept the default)
-> # (press enter to accept the default and use the rest of the remaining space)
-> a # (make the partition bootable)
-> x # (enter expert mode)
-> f # (fix up the partition ordering)
-> r # (exit expert mode)
-> w # (write the partition table to disk and exit)
+ Create a GPT partition table.
+# parted /dev/sda -- mklabel gpt
+
+
+ Add a swap partition. The size required will vary
+ according to needs, here a 8GiB one is created. The space left in front
+ (512MiB) will be used by the boot partition.
+# parted /dev/sda -- mkpart primary linux-swap 512MiB 8.5GiB
+
+
+ The swap partition size rules are no different than for other Linux
+ distributions.
+
+
+
+
+
+
+ Next, add the root partition. This will fill the
+ remainder ending part of the disk.
+# parted /dev/sda -- mkpart primary 8.5GiB -1MiB
+
+
+
+
+ Finally, the boot partition. NixOS by default uses
+ the ESP (EFI system partition) as its /boot
+ partition. It uses the initially reserved 512MiB at the start of the
+ disk.
+# parted /dev/sda -- mkpart ESP fat32 1M 512MiB
+# parted /dev/sda -- set 3 boot on
+
+
+
+
+
+
+ Once complete, you can follow with
+ .
+
+
+
+
+ Legacy Boot (MBR)
+
+
+ Here's an example partition scheme for Legacy Boot, using
+ /dev/sda as the device.
+
+
+ You can safely ignore parted's informational message
+ about needing to update /etc/fstab.
+
+
+
+
+
+
+
+
+ Create a MBR partition table.
+# parted /dev/sda -- mklabel msdos
+
+
+
+
+ Add a swap partition. The size required will vary
+ according to needs, here a 8GiB one is created.
+# parted /dev/sda -- mkpart primary linux-swap 1M 8GiB
+
+
+ The swap partition size rules are no different than for other Linux
+ distributions.
+
+
+
+
+
+
+ Finally, add the root partition. This will fill the
+ remainder of the disk.
+# parted /dev/sda -- mkpart primary 8GiB -1s
+
+
+
+
+
+
+ Once complete, you can follow with
+ .
+
+
+
+
+ Formatting
+
+
+ Use the following commands:
+
For initialising Ext4 partitions: mkfs.ext4. It is
@@ -169,242 +262,249 @@
-
-
-
- Mount the target file system on which NixOS should be installed on
- /mnt, e.g.
+
+
+
+ Installing
+
+
+
+
+ Mount the target file system on which NixOS should be installed on
+ /mnt, e.g.
# mount /dev/disk/by-label/nixos /mnt
-
-
-
-
-
-
- UEFI systems
-
-
-
- Mount the boot file system on /mnt/boot, e.g.
+
+
+
+
+
+
+ UEFI systems
+
+
+
+ Mount the boot file system on /mnt/boot, e.g.
# mkdir -p /mnt/boot
# mount /dev/disk/by-label/boot /mnt/boot
-
-
-
-
-
-
-
- If your machine has a limited amount of memory, you may want to activate
- swap devices now (swapon
- device). The installer (or rather, the
- build actions that it may spawn) may need quite a bit of RAM, depending on
- your configuration.
+
+
+
+
+
+
+
+ If your machine has a limited amount of memory, you may want to activate
+ swap devices now (swapon
+ device). The installer (or rather,
+ the build actions that it may spawn) may need quite a bit of RAM,
+ depending on your configuration.
# swapon /dev/sda2
-
-
-
-
- You now need to create a file
- /mnt/etc/nixos/configuration.nix that specifies the
- intended configuration of the system. This is because NixOS has a
- declarative configuration model: you create or edit a
- description of the desired configuration of your system, and then NixOS
- takes care of making it happen. The syntax of the NixOS configuration file
- is described in , while a list of
- available configuration options appears in
-
+
+
+
+ You now need to create a file
+ /mnt/etc/nixos/configuration.nix that specifies the
+ intended configuration of the system. This is because NixOS has a
+ declarative configuration model: you create or edit a
+ description of the desired configuration of your system, and then NixOS
+ takes care of making it happen. The syntax of the NixOS configuration file
+ is described in , while a list
+ of available configuration options appears in
+ . A minimal example is shown in
- .
-
-
- The command nixos-generate-config can generate an
- initial configuration file for you:
+
+
+ The command nixos-generate-config can generate an
+ initial configuration file for you:
# nixos-generate-config --root /mnt
- You should then edit /mnt/etc/nixos/configuration.nix
- to suit your needs:
+ You should then edit /mnt/etc/nixos/configuration.nix
+ to suit your needs:
# nano /mnt/etc/nixos/configuration.nix
- If you’re using the graphical ISO image, other editors may be available
- (such as vim). If you have network access, you can also
- install other editors — for instance, you can install Emacs by running
- nix-env -i emacs.
-
-
-
-
- BIOS systems
-
-
-
- You must set the option
- to specify on which disk
- the GRUB boot loader is to be installed. Without it, NixOS cannot boot.
-
-
-
-
-
- UEFI systems
-
-
-
- You must set the option
- to
- true. nixos-generate-config should
- do this automatically for new configurations when booted in UEFI mode.
-
-
- You may want to look at the options starting with
-
- and
-
- as well.
-
-
-
-
-
- If there are other operating systems running on the machine before
- installing NixOS, the
- option can be set to true to automatically add them to
- the grub menu.
-
-
- Another critical option is , specifying the
- file systems that need to be mounted by NixOS. However, you typically
- don’t need to set it yourself, because
- nixos-generate-config sets it automatically in
- /mnt/etc/nixos/hardware-configuration.nix from your
- currently mounted file systems. (The configuration file
- hardware-configuration.nix is included from
- configuration.nix and will be overwritten by future
- invocations of nixos-generate-config; thus, you
- generally should not modify it.)
-
-
-
- Depending on your hardware configuration or type of file system, you may
- need to set the option to
- include the kernel modules that are necessary for mounting the root file
- system, otherwise the installed system will not be able to boot. (If this
- happens, boot from the CD again, mount the target file system on
- /mnt, fix
- /mnt/etc/nixos/configuration.nix and rerun
- nixos-install.) In most cases,
- nixos-generate-config will figure out the required
- modules.
+ If you’re using the graphical ISO image, other editors may be available
+ (such as vim). If you have network access, you can also
+ install other editors — for instance, you can install Emacs by running
+ nix-env -i emacs.
-
-
-
-
- Do the installation:
+
+
+
+ BIOS systems
+
+
+
+ You must set the option
+ to specify on which disk
+ the GRUB boot loader is to be installed. Without it, NixOS cannot boot.
+
+
+
+
+
+ UEFI systems
+
+
+
+ You must set the option
+ to
+ true. nixos-generate-config
+ should do this automatically for new configurations when booted in UEFI
+ mode.
+
+
+ You may want to look at the options starting with
+
+ and
+
+ as well.
+
+
+
+
+
+ If there are other operating systems running on the machine before
+ installing NixOS, the
+ option can be set to true to automatically add them to
+ the grub menu.
+
+
+ Another critical option is , specifying the
+ file systems that need to be mounted by NixOS. However, you typically
+ don’t need to set it yourself, because
+ nixos-generate-config sets it automatically in
+ /mnt/etc/nixos/hardware-configuration.nix from your
+ currently mounted file systems. (The configuration file
+ hardware-configuration.nix is included from
+ configuration.nix and will be overwritten by future
+ invocations of nixos-generate-config; thus, you
+ generally should not modify it.)
+
+
+
+ Depending on your hardware configuration or type of file system, you may
+ need to set the option to
+ include the kernel modules that are necessary for mounting the root file
+ system, otherwise the installed system will not be able to boot. (If this
+ happens, boot from the installation media again, mount the target file
+ system on /mnt, fix
+ /mnt/etc/nixos/configuration.nix and rerun
+ nixos-install.) In most cases,
+ nixos-generate-config will figure out the required
+ modules.
+
+
+
+
+
+ Do the installation:
# nixos-install
- Cross fingers. If this fails due to a temporary problem (such as a network
- issue while downloading binaries from the NixOS binary cache), you can just
- re-run nixos-install. Otherwise, fix your
- configuration.nix and then re-run
- nixos-install.
-
-
- As the last step, nixos-install will ask you to set the
- password for the root user, e.g.
+ Cross fingers. If this fails due to a temporary problem (such as a network
+ issue while downloading binaries from the NixOS binary cache), you can
+ just re-run nixos-install. Otherwise, fix your
+ configuration.nix and then re-run
+ nixos-install.
+
+
+ As the last step, nixos-install will ask you to set the
+ password for the root user, e.g.
setting root password...
Enter new UNIX password: ***
-Retype new UNIX password: ***
-
-
-
- For unattended installations, it is possible to use
- nixos-install --no-root-passwd in order to disable the
- password prompt entirely.
-
-
-
-
-
-
- If everything went well:
+Retype new UNIX password: ***
+
+
+ For unattended installations, it is possible to use
+ nixos-install --no-root-passwd in order to disable
+ the password prompt entirely.
+
+
+
+
+
+
+ If everything went well:
- # reboot
-
-
-
-
- You should now be able to boot into the installed NixOS. The GRUB boot menu
- shows a list of available configurations (initially
- just one). Every time you change the NixOS configuration (see
-
+
+
+
+
+ You should now be able to boot into the installed NixOS. The GRUB boot
+ menu shows a list of available configurations
+ (initially just one). Every time you change the NixOS configuration (see
+ Changing Configuration
- ), a new item is added to the menu. This allows you to easily roll back to
- a previous configuration if something goes wrong.
-
-
- You should log in and change the root password with
- passwd.
-
-
- You’ll probably want to create some user accounts as well, which can be
- done with useradd:
+ ), a new item is added to the menu. This allows you to easily roll back to
+ a previous configuration if something goes wrong.
+
+
+ You should log in and change the root password with
+ passwd.
+
+
+ You’ll probably want to create some user accounts as well, which can be
+ done with useradd:
$ useradd -c 'Eelco Dolstra' -m eelco
$ passwd eelco
-
-
- You may also want to install some software. For instance,
+
+
+ You may also want to install some software. For instance,
$ nix-env -qa \*
- shows what packages are available, and
+ shows what packages are available, and
$ nix-env -i w3m
- install the w3m browser.
-
-
-
-
- To summarise, shows a typical sequence
- of commands for installing NixOS on an empty hard drive (here
- /dev/sda). w3m browser.
+
+
+
+
+
+ Installation summary
+
+
+ To summarise, shows a typical
+ sequence of commands for installing NixOS on an empty hard drive (here
+ /dev/sda). shows a
- corresponding configuration Nix expression.
-
-
- Commands for Installing NixOS on <filename>/dev/sda</filename>
-
-# fdisk /dev/sda # (or whatever device you want to install on)
--- for UEFI systems only
-> n # (create a new partition for /boot)
-> 3 # (make it a partition number 3)
-> # (press enter to accept the default)
-> +512M # (the size of the UEFI boot partition)
-> t # (change the partition type ...)
-> 3 # (... of the boot partition ...)
-> 1 # (... to 'UEFI System')
--- for BIOS or UEFI systems
-> n # (create a new partition for /swap)
-> 2 # (make it a partition number 2)
-> # (press enter to accept the default)
-> +8G # (the size of the swap partition)
-> n # (create a new partition for /)
-> 1 # (make it a partition number 1)
-> # (press enter to accept the default)
-> # (press enter to accept the default and use the rest of the remaining space)
-> a # (make the partition bootable)
-> x # (enter expert mode)
-> f # (fix up the partition ordering)
-> r # (exit expert mode)
-> w # (write the partition table to disk and exit)
+ corresponding configuration Nix expression.
+
+
+
+ Example partition schemes for NixOS on <filename>/dev/sda</filename> (MBR)
+
+# parted /dev/sda -- mklabel msdos
+# parted /dev/sda -- mkpart primary linux-swap 1M 8GiB
+# parted /dev/sda -- mkpart primary 8GiB -1s
+
+
+
+ Example partition schemes for NixOS on <filename>/dev/sda</filename> (UEFI)
+
+# parted /dev/sda -- mklabel gpt
+# parted /dev/sda -- mkpart primary linux-swap 512MiB 8.5GiB
+# parted /dev/sda -- mkpart primary 8.5GiB -1MiB
+# parted /dev/sda -- mkpart ESP fat32 1M 512MiB
+# parted /dev/sda -- set 3 boot on
+
+
+
+ Commands for Installing NixOS on <filename>/dev/sda</filename>
+
+ With a partitioned disk.
+
# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
@@ -416,9 +516,11 @@ $ nix-env -i w3m
# nano /mnt/etc/nixos/configuration.nix
# nixos-install
# reboot
-
-
- NixOS Configuration
+
+
+
+
+ NixOS Configuration
{ config, pkgs, ... }: {
imports = [
@@ -438,10 +540,19 @@ $ nix-env -i w3m
services.sshd.enable = true;
}
-
-
-
-
-
-
+
+
+
+ Additional installation notes
+
+
+
+
+
+
+
+
+
+
+