From 2c0d56f00719f27533a3a1a89d2bd48710735a1e Mon Sep 17 00:00:00 2001 From: Samuel Dionne-Riel Date: Wed, 3 Oct 2018 22:33:03 -0400 Subject: [PATCH 1/4] nixos/doc: Adds sub-folder to input files. --- nixos/doc/manual/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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" From 8192fcd0fdac8d17c5719994a0c60ae0bd1109ed Mon Sep 17 00:00:00 2001 From: Samuel Dionne-Riel Date: Tue, 2 Oct 2018 20:13:18 -0400 Subject: [PATCH 2/4] doc: installing-usb make macOS note a note. While it seemingly brings more attention to the macOS notes with the default docbook template, it better represents which parts of the section are about macOS, and which parts are simply in the flow of the text; otherwise the last paragraph may be lost into the details for macOS. --- .../manual/installation/installing-usb.xml | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/nixos/doc/manual/installation/installing-usb.xml b/nixos/doc/manual/installation/installing-usb.xml index c5934111749c..4315eb5942b9 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,10 +25,12 @@ $ 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. + + From 8467dc857bd1cc9c54a15cd36c062554b61234cf Mon Sep 17 00:00:00 2001 From: Samuel Dionne-Riel Date: Tue, 2 Oct 2018 20:14:45 -0400 Subject: [PATCH 3/4] doc: installing-usb: removes notes about unetbootin. They are known to cause more issues than solving issues; futhermore using `dd` should work everywhere without fail. --- .../manual/installation/installing-usb.xml | 29 ------------------- 1 file changed, 29 deletions(-) diff --git a/nixos/doc/manual/installation/installing-usb.xml b/nixos/doc/manual/installation/installing-usb.xml index 4315eb5942b9..0b311189430c 100644 --- a/nixos/doc/manual/installation/installing-usb.xml +++ b/nixos/doc/manual/installation/installing-usb.xml @@ -36,34 +36,5 @@ $ sudo dd bs=1m if=nix.iso of=/dev/rdiskN 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. - - - From 6cfbf403ca327017257ddbd742e312f3304b64cc Mon Sep 17 00:00:00 2001 From: Samuel Dionne-Riel Date: Mon, 1 Oct 2018 23:57:10 -0400 Subject: [PATCH 4/4] doc: Reviews partitioning instructions to use parted. The tests in are using `parted`, so they are bound to be better tested than `fdisk`. This is brought on by a couple issues, plus reports on IRC that the `fdisk` instructions didn't work as expected. * #39354 * #46309 * #39942 * #45478 Care was taken so that the other documented steps did not need changes. In all this kerfufle, a slight re-organization of the Chapter has been made, allowing better deep linking. --- nixos/doc/manual/installation/installing.xml | 709 +++++++++++-------- 1 file changed, 410 insertions(+), 299 deletions(-) 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 + + + + + + + + + + +