From 6cfbf403ca327017257ddbd742e312f3304b64cc Mon Sep 17 00:00:00 2001 From: Samuel Dionne-Riel Date: Mon, 1 Oct 2018 23:57:10 -0400 Subject: 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 | 707 ++++++++++++++++----------- 1 file changed, 409 insertions(+), 298 deletions(-) (limited to 'nixos') 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.) - - + 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. + + + + - 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 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. - - - - - Do the installation: + + 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 + + + + + + + + + + +
-- cgit 1.4.1