diff options
Diffstat (limited to 'nixpkgs/nixos/doc/manual/installation/installing.xml')
| -rw-r--r-- | nixpkgs/nixos/doc/manual/installation/installing.xml | 579 |
1 files changed, 579 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/installation/installing.xml b/nixpkgs/nixos/doc/manual/installation/installing.xml new file mode 100644 index 000000000000..d019bb318096 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing.xml @@ -0,0 +1,579 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + 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, "burned" + 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 <command>nixos-help</command>. + </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 <command>sudo</command> without a password. + </para> + + <para> + If you downloaded the graphical ISO image, you can run <command>systemctl + start display-manager</command> to start the desktop environment. If you want to continue on the + terminal, you can use <command>loadkeys</command> to switch to your + preferred keyboard layout. (We even provide neo2 via <command>loadkeys de + neo</command>!) + </para> + + <para> + If the text is too small to be legible, try <command>setfont ter-v32n</command> + to increase the font size. + </para> + + <para> + To install over a serial port connect with <literal>115200n8</literal> + (e.g. <command>picocom -b 115200 /dev/ttyUSB0</command>). 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 <command>ip + a</command>). 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 <command>ifconfig</command>. + </para> + + <para> + To manually configure the network on the graphical installer, first disable + network-manager with <command>systemctl stop NetworkManager</command>. + </para> + + <para> + To manually configure the wifi on the minimal installer, run + <command>wpa_supplicant -B -i interface -c <(wpa_passphrase 'SSID' + 'key')</command>. + </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 + <command>passwd</command> 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 <command>parted</command>, but also provides + <command>fdisk</command>, <command>gdisk</command>, + <command>cfdisk</command>, and <command>cgdisk</command>. + </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 + <filename>/dev/sda</filename> as the device. + <note> + <para> + You can safely ignore <command>parted</command>'s informational message + about needing to update /etc/fstab. + </para> + </note> + </para> + + <para> + <orderedlist> + <listitem> + <para> + Create a <emphasis>GPT</emphasis> partition table. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel gpt</screen> + </para> + </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. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB</screen> + </para> + </listitem> + <listitem> + <para> + Next, add a <emphasis>swap</emphasis> partition. The size required will + vary according to needs, here a 8GiB one is created. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> + <note> + <para> + The swap partition size rules are no different than for other Linux + distributions. + </para> + </note> + </para> + </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. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +<prompt># </prompt>parted /dev/sda -- set 3 esp on</screen> + </para> + </listitem> + </orderedlist> + </para> + + <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 + <filename>/dev/sda</filename> as the device. + <note> + <para> + You can safely ignore <command>parted</command>'s informational message + about needing to update /etc/fstab. + </para> + </note> + </para> + + <para> + <orderedlist> + <listitem> + <para> + Create a <emphasis>MBR</emphasis> partition table. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel msdos</screen> + </para> + </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. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB</screen> + </para> + </listitem> + <listitem> + <para> + Finally, add a <emphasis>swap</emphasis> partition. The size required + will vary according to needs, here a 8GiB one is created. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> + <note> + <para> + The swap partition size rules are no different than for other Linux + distributions. + </para> + </note> + </para> + </listitem> + </orderedlist> + </para> + + <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: + <itemizedlist> + <listitem> + <para> + For initialising Ext4 partitions: <command>mkfs.ext4</command>. It is + recommended that you assign a unique symbolic label to the file system + using the option <option>-L <replaceable>label</replaceable></option>, + since this makes the file system configuration independent from device + changes. For example: +<screen> +<prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1</screen> + </para> + </listitem> + <listitem> + <para> + For creating swap partitions: <command>mkswap</command>. Again it’s + recommended to assign a label to the swap partition: <option>-L + <replaceable>label</replaceable></option>. For example: +<screen> +<prompt># </prompt>mkswap -L swap /dev/sda2</screen> + </para> + </listitem> + <listitem> + <variablelist> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + For creating boot partitions: <command>mkfs.fat</command>. Again + it’s recommended to assign a label to the boot partition: + <option>-n <replaceable>label</replaceable></option>. For example: +<screen> +<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3</screen> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + <listitem> + <para> + For creating LVM volumes, the LVM commands, e.g., + <command>pvcreate</command>, <command>vgcreate</command>, and + <command>lvcreate</command>. + </para> + </listitem> + <listitem> + <para> + For creating software RAID devices, use <command>mdadm</command>. + </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + <section xml:id="sec-installation-installing"> + <title>Installing</title> + + <orderedlist> + <listitem> + <para> + Mount the target file system on which NixOS should be installed on + <filename>/mnt</filename>, e.g. +<screen> +<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt +</screen> + </para> + </listitem> + <listitem> + <variablelist> + <varlistentry> + <term> + UEFI systems + </term> + <listitem> + <para> + Mount the boot file system on <filename>/mnt/boot</filename>, e.g. +<screen> +<prompt># </prompt>mkdir -p /mnt/boot +<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot +</screen> + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + <listitem> + <para> + If your machine has a limited amount of memory, you may want to activate + swap devices now (<command>swapon + <replaceable>device</replaceable></command>). The installer (or rather, + the build actions that it may spawn) may need quite a bit of RAM, + depending on your configuration. +<screen> +<prompt># </prompt>swapon /dev/sda2</screen> + </para> + </listitem> + <listitem> + <para> + You now need to create a file + <filename>/mnt/etc/nixos/configuration.nix</filename> 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 + <xref + linkend="ex-config"/>. + </para> + <para> + The command <command>nixos-generate-config</command> can generate an + initial configuration file for you: +<screen> +<prompt># </prompt>nixos-generate-config --root /mnt</screen> + You should then edit <filename>/mnt/etc/nixos/configuration.nix</filename> + to suit your needs: +<screen> +<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix +</screen> + If you’re using the graphical ISO image, other editors may be available + (such as <command>vim</command>). 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>. <command>nixos-generate-config</command> + should do this automatically for new configurations when booted in UEFI + mode. + </para> + <para> + You may want to look at the options starting with + <option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option> + and + <option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd-boot</link></option> + 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 + <command>nixos-generate-config</command>. + </para> + <para> + Another critical option is <option>fileSystems</option>, specifying the + file systems that need to be mounted by NixOS. However, you typically + don’t need to set it yourself, because + <command>nixos-generate-config</command> sets it automatically in + <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> from your + currently mounted file systems. (The configuration file + <filename>hardware-configuration.nix</filename> is included from + <filename>configuration.nix</filename> and will be overwritten by future + invocations of <command>nixos-generate-config</command>; 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 <option>boot.initrd.kernelModules</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 <filename>/mnt</filename>, fix + <filename>/mnt/etc/nixos/configuration.nix</filename> and rerun + <filename>nixos-install</filename>.) In most cases, + <command>nixos-generate-config</command> will figure out the required + modules. + </para> + </note> + </listitem> + <listitem> + <para> + Do the installation: +<screen> +<prompt># </prompt>nixos-install</screen> + 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 <command>nixos-install</command> after + fixing your <filename>configuration.nix</filename>. + </para> + <para> + As the last step, <command>nixos-install</command> will ask you to set the + password for the <literal>root</literal> user, e.g. +<screen> +setting root password... +New password: *** +Retype new password: ***</screen> + <note> + <para> + For unattended installations, it is possible to use + <command>nixos-install --no-root-passwd</command> in order to disable + the password prompt entirely. + </para> + </note> + </para> + </listitem> + <listitem> + <para> + If everything went well: +<screen> +<prompt># </prompt>reboot</screen> + </para> + </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 + <command>passwd</command>. + </para> + <para> + You’ll probably want to create some user accounts as well, which can be + done with <command>useradd</command>: +<screen> +<prompt>$ </prompt>useradd -c 'Eelco Dolstra' -m eelco +<prompt>$ </prompt>passwd eelco</screen> + </para> + <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, <xref linkend="ex-install-sequence" /> shows a typical + sequence of commands for installing NixOS on an empty hard drive (here + <filename>/dev/sda</filename>). <xref linkend="ex-config" +/> shows a + corresponding configuration Nix expression. + </para> + + <example xml:id="ex-partition-scheme-MBR"> + <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (MBR)</title> +<screen language="commands"> +<prompt># </prompt>parted /dev/sda -- mklabel msdos +<prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB +<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> + </example> + + <example xml:id="ex-partition-scheme-UEFI"> + <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (UEFI)</title> +<screen language="commands"> +<prompt># </prompt>parted /dev/sda -- mklabel gpt +<prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB +<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +<prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +<prompt># </prompt>parted /dev/sda -- set 3 esp on</screen> + </example> + + <example xml:id="ex-install-sequence"> + <title>Commands for Installing NixOS on <filename>/dev/sda</filename></title> + <para> + With a partitioned disk. +<screen language="commands"> +<prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1 +<prompt># </prompt>mkswap -L swap /dev/sda2 +<prompt># </prompt>swapon /dev/sda2 +<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3 # <lineannotation>(for UEFI systems only)</lineannotation> +<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt +<prompt># </prompt>mkdir -p /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> +<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> +<prompt># </prompt>nixos-generate-config --root /mnt +<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix +<prompt># </prompt>nixos-install +<prompt># </prompt>reboot</screen> + </para> + </example> + + <example xml:id='ex-config'> + <title>NixOS Configuration</title> +<programlisting> +{ config, pkgs, ... }: { + imports = [ + # Include the results of the hardware scan. + ./hardware-configuration.nix + ]; + + <xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda"; # <lineannotation>(for BIOS systems only)</lineannotation> + <xref linkend="opt-boot.loader.systemd-boot.enable"/> = true; # <lineannotation>(for UEFI systems only)</lineannotation> + + # Note: setting fileSystems is generally not + # necessary, since nixos-generate-config figures them out + # automatically in hardware-configuration.nix. + #<link linkend="opt-fileSystems._name_.device">fileSystems."/".device</link> = "/dev/disk/by-label/nixos"; + + # Enable the OpenSSH server. + services.sshd.enable = true; +} +</programlisting> + </example> + </section> + <section xml:id="sec-installation-additional-notes"> + <title>Additional installation notes</title> + + <xi:include href="installing-usb.xml" /> + + <xi:include href="installing-pxe.xml" /> + + <xi:include href="installing-virtualbox-guest.xml" /> + + <xi:include href="installing-from-other-distro.xml" /> + + <xi:include href="installing-behind-a-proxy.xml" /> + </section> +</chapter> |