diff options
Diffstat (limited to 'nixos/doc/manual/from_md/installation/installing.chapter.xml')
| -rw-r--r-- | nixos/doc/manual/from_md/installation/installing.chapter.xml | 645 |
1 files changed, 645 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/installation/installing.chapter.xml b/nixos/doc/manual/from_md/installation/installing.chapter.xml new file mode 100644 index 00000000000..db073fa8396 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing.chapter.xml @@ -0,0 +1,645 @@ +<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> + <section xml:id="sec-installation-booting"> + <title>Booting the system</title> + <para> + 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. + </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> + The NixOS manual is available by running + <literal>nixos-help</literal>. + </para> + <para> + You are logged-in automatically as <literal>nixos</literal>. The + <literal>nixos</literal> user account has an empty password so you + can use <literal>sudo</literal> without a password: + </para> + <programlisting> +$ sudo -i +</programlisting> + <para> + If you downloaded the graphical ISO image, you can run + <literal>systemctl start display-manager</literal> to start the + 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>!) + </para> + <para> + If the text is too small to be legible, try + <literal>setfont ter-v32n</literal> to increase the font size. + </para> + <para> + To install over a serial port connect with + <literal>115200n8</literal> (e.g. + <literal>picocom -b 115200 /dev/ttyUSB0</literal>). When the + bootloader lists boot entries, select the serial console boot + entry. + </para> + <section xml:id="sec-installation-booting-networking"> + <title>Networking in the installer</title> + <para> + The boot process should have brought up networking (check + <literal>ip a</literal>). Networking is necessary for the + installer, since it will download lots of stuff (such as source + tarballs or Nixpkgs channel binaries). It’s best if you have a + DHCP server on your network. Otherwise configure networking + manually using <literal>ifconfig</literal>. + </para> + <para> + On the graphical installer, you can configure the network, wifi + included, through NetworkManager. Using the + <literal>nmtui</literal> program, you can do so even in a + non-graphical session. If you prefer to configure the network + manually, disable NetworkManager with + <literal>systemctl stop NetworkManager</literal>. + </para> + <para> + On the minimal installer, NetworkManager is not available, so + configuration must be perfomed manually. To configure the wifi, + first start wpa_supplicant with + <literal>sudo systemctl start wpa_supplicant</literal>, then run + <literal>wpa_cli</literal>. For most home networks, you need to + type in the following commands: + </para> + <programlisting> +> add_network +0 +> set_network 0 ssid "myhomenetwork" +OK +> set_network 0 psk "mypassword" +OK +> set_network 0 key_mgmt WPA-PSK +OK +> enable_network 0 +OK +</programlisting> + <para> + For enterprise networks, for example + <emphasis>eduroam</emphasis>, instead do: + </para> + <programlisting> +> add_network +0 +> set_network 0 ssid "eduroam" +OK +> set_network 0 identity "myname@example.com" +OK +> set_network 0 password "mypassword" +OK +> set_network 0 key_mgmt WPA-EAP +OK +> enable_network 0 +OK +</programlisting> + <para> + When successfully connected, you should see a line such as this + one + </para> + <programlisting> +<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=] +</programlisting> + <para> + you can now leave <literal>wpa_cli</literal> by typing + <literal>quit</literal>. + </para> + <para> + If you would like to continue the installation from a different + machine you can use activated SSH daemon. You need to copy your + ssh key to either + <literal>/home/nixos/.ssh/authorized_keys</literal> or + <literal>/root/.ssh/authorized_keys</literal> (Tip: For + installers with a modifiable filesystem such as the sd-card + installer image a key can be manually placed by mounting the + image on a different machine). Alternatively you must set a + password for either <literal>root</literal> or + <literal>nixos</literal> with <literal>passwd</literal> to be + able to login. + </para> + </section> + </section> + <section xml:id="sec-installation-partitioning"> + <title>Partitioning and formatting</title> + <para> + The NixOS installer doesn’t do any partitioning or formatting, so + you need to do that yourself. + </para> + <para> + The NixOS installer ships with multiple partitioning tools. The + examples below use <literal>parted</literal>, but also provides + <literal>fdisk</literal>, <literal>gdisk</literal>, + <literal>cfdisk</literal>, and <literal>cgdisk</literal>. + </para> + <para> + The recommended partition scheme differs depending if the computer + uses <emphasis>Legacy Boot</emphasis> or + <emphasis>UEFI</emphasis>. + </para> + <section xml:id="sec-installation-partitioning-UEFI"> + <title>UEFI (GPT)</title> + <para> + Here's an example partition scheme for UEFI, using + <literal>/dev/sda</literal> as the device. + </para> + <note> + <para> + You can safely ignore <literal>parted</literal>'s + informational message about needing to update /etc/fstab. + </para> + </note> + <orderedlist numeration="arabic"> + <listitem> + <para> + Create a <emphasis>GPT</emphasis> partition table. + </para> + <programlisting> +# parted /dev/sda -- mklabel gpt +</programlisting> + </listitem> + <listitem> + <para> + Add the <emphasis>root</emphasis> partition. This will fill + the disk except for the end part, where the swap will live, + and the space left in front (512MiB) which will be used by + the boot partition. + </para> + <programlisting> +# parted /dev/sda -- mkpart primary 512MiB -8GiB +</programlisting> + </listitem> + <listitem> + <para> + Next, add a <emphasis>swap</emphasis> partition. The size + required will vary according to needs, here a 8GiB one is + created. + </para> + <programlisting> +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +</programlisting> + <note> + <para> + The swap partition size rules are no different than for + other Linux distributions. + </para> + </note> + </listitem> + <listitem> + <para> + Finally, the <emphasis>boot</emphasis> partition. NixOS by + default uses the ESP (EFI system partition) as its + <emphasis>/boot</emphasis> partition. It uses the initially + reserved 512MiB at the start of the disk. + </para> + <programlisting> +# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +# parted /dev/sda -- set 3 esp on +</programlisting> + </listitem> + </orderedlist> + <para> + Once complete, you can follow with + <xref linkend="sec-installation-partitioning-formatting" />. + </para> + </section> + <section xml:id="sec-installation-partitioning-MBR"> + <title>Legacy Boot (MBR)</title> + <para> + Here's an example partition scheme for Legacy Boot, using + <literal>/dev/sda</literal> as the device. + </para> + <note> + <para> + You can safely ignore <literal>parted</literal>'s + informational message about needing to update /etc/fstab. + </para> + </note> + <orderedlist numeration="arabic"> + <listitem> + <para> + Create a <emphasis>MBR</emphasis> partition table. + </para> + <programlisting> +# parted /dev/sda -- mklabel msdos +</programlisting> + </listitem> + <listitem> + <para> + Add the <emphasis>root</emphasis> partition. This will fill + the the disk except for the end part, where the swap will + live. + </para> + <programlisting> +# parted /dev/sda -- mkpart primary 1MiB -8GiB +</programlisting> + </listitem> + <listitem> + <para> + Finally, add a <emphasis>swap</emphasis> partition. The size + required will vary according to needs, here a 8GiB one is + created. + </para> + <programlisting> +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +</programlisting> + <note> + <para> + The swap partition size rules are no different than for + other Linux distributions. + </para> + </note> + </listitem> + </orderedlist> + <para> + Once complete, you can follow with + <xref linkend="sec-installation-partitioning-formatting" />. + </para> + </section> + <section xml:id="sec-installation-partitioning-formatting"> + <title>Formatting</title> + <para> + Use the following commands: + </para> + <itemizedlist> + <listitem> + <para> + For initialising Ext4 partitions: + <literal>mkfs.ext4</literal>. It is recommended that you + assign a unique symbolic label to the file system using the + option <literal>-L label</literal>, since this makes the + file system configuration independent from device changes. + For example: + </para> + <programlisting> +# mkfs.ext4 -L nixos /dev/sda1 +</programlisting> + </listitem> + <listitem> + <para> + For creating swap partitions: <literal>mkswap</literal>. + Again it’s recommended to assign a label to the swap + partition: <literal>-L label</literal>. For example: + </para> + <programlisting> +# mkswap -L swap /dev/sda2 +</programlisting> + </listitem> + <listitem> + <para> + <emphasis role="strong">UEFI systems</emphasis> + </para> + <para> + For creating boot partitions: <literal>mkfs.fat</literal>. + Again it’s recommended to assign a label to the boot + partition: <literal>-n label</literal>. For example: + </para> + <programlisting> +# mkfs.fat -F 32 -n boot /dev/sda3 +</programlisting> + </listitem> + <listitem> + <para> + For creating LVM volumes, the LVM commands, e.g., + <literal>pvcreate</literal>, <literal>vgcreate</literal>, + and <literal>lvcreate</literal>. + </para> + </listitem> + <listitem> + <para> + For creating software RAID devices, use + <literal>mdadm</literal>. + </para> + </listitem> + </itemizedlist> + </section> + </section> + <section xml:id="sec-installation-installing"> + <title>Installing</title> + <orderedlist numeration="arabic"> + <listitem> + <para> + Mount the target file system on which NixOS should be + installed on <literal>/mnt</literal>, e.g. + </para> + <programlisting> +# mount /dev/disk/by-label/nixos /mnt +</programlisting> + </listitem> + <listitem> + <para> + <emphasis role="strong">UEFI systems</emphasis> + </para> + <para> + Mount the boot file system on <literal>/mnt/boot</literal>, + e.g. + </para> + <programlisting> +# mkdir -p /mnt/boot +# mount /dev/disk/by-label/boot /mnt/boot +</programlisting> + </listitem> + <listitem> + <para> + If your machine has a limited amount of memory, you may want + to activate swap devices now + (<literal>swapon device</literal>). The installer (or rather, + the build actions that it may spawn) may need quite a bit of + RAM, depending on your configuration. + </para> + <programlisting> +# swapon /dev/sda2 +</programlisting> + </listitem> + <listitem> + <para> + You now need to create a file + <literal>/mnt/etc/nixos/configuration.nix</literal> that + specifies the intended configuration of the system. This is + because NixOS has a <emphasis>declarative</emphasis> + 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 + <xref linkend="sec-configuration-syntax" />, while a list of + available configuration options appears in + <xref linkend="ch-options" />. A minimal example is shown in + <link linkend="ex-config">Example: NixOS Configuration</link>. + </para> + <para> + The command <literal>nixos-generate-config</literal> can + generate an initial configuration file for you: + </para> + <programlisting> +# nixos-generate-config --root /mnt +</programlisting> + <para> + You should then edit + <literal>/mnt/etc/nixos/configuration.nix</literal> to suit + your needs: + </para> + <programlisting> +# nano /mnt/etc/nixos/configuration.nix +</programlisting> + <para> + If you’re using the graphical ISO image, other editors may be + available (such as <literal>vim</literal>). If you have + network access, you can also install other editors – for + instance, you can install Emacs by running + <literal>nix-env -f '<nixpkgs>' -iA emacs</literal>. + </para> + <variablelist> + <varlistentry> + <term> + BIOS systems + </term> + <listitem> + <para> + You <emphasis>must</emphasis> set the option + <xref linkend="opt-boot.loader.grub.device" /> to + specify on which disk the GRUB boot loader is to be + installed. Without it, NixOS cannot boot. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + You <emphasis>must</emphasis> set the option + <xref linkend="opt-boot.loader.systemd-boot.enable" /> + to <literal>true</literal>. + <literal>nixos-generate-config</literal> should do this + automatically for new configurations when booted in UEFI + mode. + </para> + <para> + You may want to look at the options starting with + <link linkend="opt-boot.loader.efi.canTouchEfiVariables"><literal>boot.loader.efi</literal></link> + and + <link linkend="opt-boot.loader.systemd-boot.enable"><literal>boot.loader.systemd-boot</literal></link> + as well. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + If there are other operating systems running on the machine + before installing NixOS, the + <xref linkend="opt-boot.loader.grub.useOSProber" /> option can + be set to <literal>true</literal> to automatically add them to + the grub menu. + </para> + <para> + If you need to configure networking for your machine the + configuration options are described in + <xref linkend="sec-networking" />. In particular, while wifi + is supported on the installation image, it is not enabled by + default in the configuration generated by + <literal>nixos-generate-config</literal>. + </para> + <para> + Another critical option is <literal>fileSystems</literal>, + specifying the file systems that need to be mounted by NixOS. + However, you typically don’t need to set it yourself, because + <literal>nixos-generate-config</literal> sets it automatically + in + <literal>/mnt/etc/nixos/hardware-configuration.nix</literal> + from your currently mounted file systems. (The configuration + file <literal>hardware-configuration.nix</literal> is included + from <literal>configuration.nix</literal> and will be + overwritten by future invocations of + <literal>nixos-generate-config</literal>; thus, you generally + should not modify it.) Additionally, you may want to look at + <link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware + configuration for known-hardware</link> at this point or after + installation. + </para> + <note> + <para> + Depending on your hardware configuration or type of file + system, you may need to set the option + <literal>boot.initrd.kernelModules</literal> 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 + <literal>/mnt</literal>, fix + <literal>/mnt/etc/nixos/configuration.nix</literal> and + rerun <literal>nixos-install</literal>.) In most cases, + <literal>nixos-generate-config</literal> will figure out the + required modules. + </para> + </note> + </listitem> + <listitem> + <para> + Do the installation: + </para> + <programlisting> +# nixos-install +</programlisting> + <para> + This will install your system based on the configuration you + provided. If anything fails due to a configuration problem or + any other issue (such as a network outage while downloading + binaries from the NixOS binary cache), you can re-run + <literal>nixos-install</literal> after fixing your + <literal>configuration.nix</literal>. + </para> + <para> + As the last step, <literal>nixos-install</literal> will ask + you to set the password for the <literal>root</literal> user, + e.g. + </para> + <programlisting> +setting root password... +New password: *** +Retype new password: *** +</programlisting> + <note> + <para> + For unattended installations, it is possible to use + <literal>nixos-install --no-root-passwd</literal> in order + to disable the password prompt entirely. + </para> + </note> + </listitem> + <listitem> + <para> + If everything went well: + </para> + <programlisting> +# reboot +</programlisting> + </listitem> + <listitem> + <para> + You should now be able to boot into the installed NixOS. The + GRUB boot menu shows a list of <emphasis>available + configurations</emphasis> (initially just one). Every time you + change the NixOS configuration (see + <link linkend="sec-changing-config">Changing + Configuration</link>), a new item is added to the menu. This + allows you to easily roll back to a previous configuration if + something goes wrong. + </para> + <para> + You should log in and change the <literal>root</literal> + password with <literal>passwd</literal>. + </para> + <para> + You’ll probably want to create some user accounts as well, + which can be done with <literal>useradd</literal>: + </para> + <programlisting> +$ useradd -c 'Eelco Dolstra' -m eelco +$ passwd eelco +</programlisting> + <para> + You may also want to install some software. This will be + covered in <xref linkend="sec-package-management" />. + </para> + </listitem> + </orderedlist> + </section> + <section xml:id="sec-installation-summary"> + <title>Installation summary</title> + <para> + To summarise, <link linkend="ex-install-sequence">Example: + Commands for Installing NixOS on + <literal>/dev/sda</literal></link> shows a typical sequence of + commands for installing NixOS on an empty hard drive (here + <literal>/dev/sda</literal>). <link linkend="ex-config">Example: + NixOS Configuration</link> shows a corresponding configuration Nix + expression. + </para> + <anchor xml:id="ex-partition-scheme-MBR" /> + <para> + <emphasis role="strong">Example: Example partition schemes for + NixOS on <literal>/dev/sda</literal> (MBR)</emphasis> + </para> + <programlisting> +# parted /dev/sda -- mklabel msdos +# parted /dev/sda -- mkpart primary 1MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +</programlisting> + <anchor xml:id="ex-partition-scheme-UEFI" /> + <para> + <emphasis role="strong">Example: Example partition schemes for + NixOS on <literal>/dev/sda</literal> (UEFI)</emphasis> + </para> + <programlisting> +# parted /dev/sda -- mklabel gpt +# parted /dev/sda -- mkpart primary 512MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +# parted /dev/sda -- set 3 esp on +</programlisting> + <anchor xml:id="ex-install-sequence" /> + <para> + <emphasis role="strong">Example: Commands for Installing NixOS on + <literal>/dev/sda</literal></emphasis> + </para> + <para> + With a partitioned disk. + </para> + <programlisting> +# mkfs.ext4 -L nixos /dev/sda1 +# mkswap -L swap /dev/sda2 +# swapon /dev/sda2 +# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only) +# mount /dev/disk/by-label/nixos /mnt +# mkdir -p /mnt/boot # (for UEFI systems only) +# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only) +# nixos-generate-config --root /mnt +# nano /mnt/etc/nixos/configuration.nix +# nixos-install +# reboot +</programlisting> + <anchor xml:id="ex-config" /> + <para> + <emphasis role="strong">Example: NixOS Configuration</emphasis> + </para> + <programlisting> +{ config, pkgs, ... }: { + imports = [ + # Include the results of the hardware scan. + ./hardware-configuration.nix + ]; + + boot.loader.grub.device = "/dev/sda"; # (for BIOS systems only) + boot.loader.systemd-boot.enable = true; # (for UEFI systems only) + + # Note: setting fileSystems is generally not + # necessary, since nixos-generate-config figures them out + # automatically in hardware-configuration.nix. + #fileSystems."/".device = "/dev/disk/by-label/nixos"; + + # Enable the OpenSSH server. + services.sshd.enable = true; +} +</programlisting> + </section> + <section xml:id="sec-installation-additional-notes"> + <title>Additional installation notes</title> + <xi:include href="installing-usb.section.xml" /> + <xi:include href="installing-pxe.section.xml" /> + <xi:include href="installing-virtualbox-guest.section.xml" /> + <xi:include href="installing-from-other-distro.section.xml" /> + <xi:include href="installing-behind-a-proxy.section.xml" /> + </section> +</chapter> |