diff options
Diffstat (limited to 'nixos/doc/manual/installation')
10 files changed, 1173 insertions, 0 deletions
diff --git a/nixos/doc/manual/installation/changing-config.chapter.md b/nixos/doc/manual/installation/changing-config.chapter.md new file mode 100644 index 00000000000..8a404f085d7 --- /dev/null +++ b/nixos/doc/manual/installation/changing-config.chapter.md @@ -0,0 +1,100 @@ +# Changing the Configuration {#sec-changing-config} + +The file `/etc/nixos/configuration.nix` contains the current +configuration of your machine. Whenever you've [changed +something](#ch-configuration) in that file, you should do + +```ShellSession +# nixos-rebuild switch +``` + +to build the new configuration, make it the default configuration for +booting, and try to realise the configuration in the running system +(e.g., by restarting system services). + +::: {.warning} +This command doesn\'t start/stop [user services](#opt-systemd.user.services) +automatically. `nixos-rebuild` only runs a `daemon-reload` for each user with running +user services. +::: + +::: {.warning} +These commands must be executed as root, so you should either run them +from a root shell or by prefixing them with `sudo -i`. +::: + +You can also do + +```ShellSession +# nixos-rebuild test +``` + +to build the configuration and switch the running system to it, but +without making it the boot default. So if (say) the configuration locks +up your machine, you can just reboot to get back to a working +configuration. + +There is also + +```ShellSession +# nixos-rebuild boot +``` + +to build the configuration and make it the boot default, but not switch +to it now (so it will only take effect after the next reboot). + +You can make your configuration show up in a different submenu of the +GRUB 2 boot screen by giving it a different *profile name*, e.g. + +```ShellSession +# nixos-rebuild switch -p test +``` + +which causes the new configuration (and previous ones created using +`-p test`) to show up in the GRUB submenu "NixOS - Profile \'test\'". +This can be useful to separate test configurations from "stable" +configurations. + +Finally, you can do + +```ShellSession +$ nixos-rebuild build +``` + +to build the configuration but nothing more. This is useful to see +whether everything compiles cleanly. + +If you have a machine that supports hardware virtualisation, you can +also test the new configuration in a sandbox by building and running a +QEMU *virtual machine* that contains the desired configuration. Just do + +```ShellSession +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm +``` + +The VM does not have any data from your host system, so your existing +user accounts and home directories will not be available unless you have +set `mutableUsers = false`. Another way is to temporarily add the +following to your configuration: + +```nix +users.users.your-user.initialHashedPassword = "test"; +``` + +*Important:* delete the \$hostname.qcow2 file if you have started the +virtual machine at least once without the right users, otherwise the +changes will not get picked up. You can forward ports on the host to the +guest. For instance, the following will forward host port 2222 to guest +port 22 (SSH): + +```ShellSession +$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm +``` + +allowing you to log in via SSH (assuming you have set the appropriate +passwords or SSH authorized keys): + +```ShellSession +$ ssh -p 2222 localhost +``` diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml new file mode 100644 index 00000000000..1d443bbd0ee --- /dev/null +++ b/nixos/doc/manual/installation/installation.xml @@ -0,0 +1,17 @@ +<part 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="ch-installation"> + <title>Installation</title> + <partintro xml:id="ch-installation-intro"> + <para> + This section describes how to obtain, install, and configure NixOS for + first-time use. + </para> + </partintro> + <xi:include href="../from_md/installation/obtaining.chapter.xml" /> + <xi:include href="../from_md/installation/installing.chapter.xml" /> + <xi:include href="../from_md/installation/changing-config.chapter.xml" /> + <xi:include href="../from_md/installation/upgrading.chapter.xml" /> +</part> diff --git a/nixos/doc/manual/installation/installing-behind-a-proxy.section.md b/nixos/doc/manual/installation/installing-behind-a-proxy.section.md new file mode 100644 index 00000000000..aca151531d0 --- /dev/null +++ b/nixos/doc/manual/installation/installing-behind-a-proxy.section.md @@ -0,0 +1,29 @@ +# Installing behind a proxy {#sec-installing-behind-proxy} + +To install NixOS behind a proxy, do the following before running +`nixos-install`. + +1. Update proxy configuration in `/mnt/etc/nixos/configuration.nix` to + keep the internet accessible after reboot. + + ```nix + networking.proxy.default = "http://user:password@proxy:port/"; + networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain"; + ``` + +1. Setup the proxy environment variables in the shell where you are + running `nixos-install`. + + ```ShellSession + # proxy_url="http://user:password@proxy:port/" + # export http_proxy="$proxy_url" + # export HTTP_PROXY="$proxy_url" + # export https_proxy="$proxy_url" + # export HTTPS_PROXY="$proxy_url" + ``` + +::: {.note} +If you are switching networks with different proxy configurations, use +the `specialisation` option in `configuration.nix` to switch proxies at +runtime. Refer to [](#ch-options) for more information. +::: diff --git a/nixos/doc/manual/installation/installing-from-other-distro.section.md b/nixos/doc/manual/installation/installing-from-other-distro.section.md new file mode 100644 index 00000000000..d9060eb89c3 --- /dev/null +++ b/nixos/doc/manual/installation/installing-from-other-distro.section.md @@ -0,0 +1,279 @@ +# Installing from another Linux distribution {#sec-installing-from-other-distro} + +Because Nix (the package manager) & Nixpkgs (the Nix packages +collection) can both be installed on any (most?) Linux distributions, +they can be used to install NixOS in various creative ways. You can, for +instance: + +1. Install NixOS on another partition, from your existing Linux + distribution (without the use of a USB or optical device!) + +1. Install NixOS on the same partition (in place!), from your existing + non-NixOS Linux distribution using `NIXOS_LUSTRATE`. + +1. Install NixOS on your hard drive from the Live CD of any Linux + distribution. + +The first steps to all these are the same: + +1. Install the Nix package manager: + + Short version: + + ```ShellSession + $ curl -L https://nixos.org/nix/install | sh + $ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell + ``` + + More details in the [ Nix + manual](https://nixos.org/nix/manual/#chap-quick-start) + +1. Switch to the NixOS channel: + + If you\'ve just installed Nix on a non-NixOS distribution, you will + be on the `nixpkgs` channel by default. + + ```ShellSession + $ nix-channel --list + nixpkgs https://nixos.org/channels/nixpkgs-unstable + ``` + + As that channel gets released without running the NixOS tests, it + will be safer to use the `nixos-*` channels instead: + + ```ShellSession + $ nix-channel --add https://nixos.org/channels/nixos-version nixpkgs + ``` + + You may want to throw in a `nix-channel --update` for good measure. + +1. Install the NixOS installation tools: + + You\'ll need `nixos-generate-config` and `nixos-install`, but this + also makes some man pages and `nixos-enter` available, just in case + you want to chroot into your NixOS partition. NixOS installs these + by default, but you don\'t have NixOS yet.. + + ```ShellSession + $ nix-env -f '<nixpkgs>' -iA nixos-install-tools + ``` + +1. ::: {.note} + The following 5 steps are only for installing NixOS to another + partition. For installing NixOS in place using `NIXOS_LUSTRATE`, + skip ahead. + ::: + + Prepare your target partition: + + At this point it is time to prepare your target partition. Please + refer to the partitioning, file-system creation, and mounting steps + of [](#sec-installation) + + If you\'re about to install NixOS in place using `NIXOS_LUSTRATE` + there is nothing to do for this step. + +1. Generate your NixOS configuration: + + ```ShellSession + $ sudo `which nixos-generate-config` --root /mnt + ``` + + You\'ll probably want to edit the configuration files. Refer to the + `nixos-generate-config` step in [](#sec-installation) for more + information. + + Consider setting up the NixOS bootloader to give you the ability to + boot on your existing Linux partition. For instance, if you\'re + using GRUB and your existing distribution is running Ubuntu, you may + want to add something like this to your `configuration.nix`: + + ```nix + boot.loader.grub.extraEntries = '' + menuentry "Ubuntu" { + search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e + configfile "($ubuntu)/boot/grub/grub.cfg" + } + ''; + ``` + + (You can find the appropriate UUID for your partition in + `/dev/disk/by-uuid`) + +1. Create the `nixbld` group and user on your original distribution: + + ```ShellSession + $ sudo groupadd -g 30000 nixbld + $ sudo useradd -u 30000 -g nixbld -G nixbld nixbld + ``` + +1. Download/build/install NixOS: + + ::: {.warning} + Once you complete this step, you might no longer be able to boot on + existing systems without the help of a rescue USB drive or similar. + ::: + + ::: {.note} + On some distributions there are separate PATHS for programs intended + only for root. In order for the installation to succeed, you might + have to use `PATH="$PATH:/usr/sbin:/sbin"` in the following command. + ::: + + ```ShellSession + $ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt + ``` + + Again, please refer to the `nixos-install` step in + [](#sec-installation) for more information. + + That should be it for installation to another partition! + +1. Optionally, you may want to clean up your non-NixOS distribution: + + ```ShellSession + $ sudo userdel nixbld + $ sudo groupdel nixbld + ``` + + If you do not wish to keep the Nix package manager installed either, + run something like `sudo rm -rv ~/.nix-* /nix` and remove the line + that the Nix installer added to your `~/.profile`. + +1. ::: {.note} + The following steps are only for installing NixOS in place using + `NIXOS_LUSTRATE`: + ::: + + Generate your NixOS configuration: + + ```ShellSession + $ sudo `which nixos-generate-config` --root / + ``` + + Note that this will place the generated configuration files in + `/etc/nixos`. You\'ll probably want to edit the configuration files. + Refer to the `nixos-generate-config` step in + [](#sec-installation) for more information. + + You\'ll likely want to set a root password for your first boot using + the configuration files because you won\'t have a chance to enter a + password until after you reboot. You can initalize the root password + to an empty one with this line: (and of course don\'t forget to set + one once you\'ve rebooted or to lock the account with + `sudo passwd -l root` if you use `sudo`) + + ```nix + users.users.root.initialHashedPassword = ""; + ``` + +1. Build the NixOS closure and install it in the `system` profile: + + ```ShellSession + $ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system + ``` + +1. Change ownership of the `/nix` tree to root (since your Nix install + was probably single user): + + ```ShellSession + $ sudo chown -R 0.0 /nix + ``` + +1. Set up the `/etc/NIXOS` and `/etc/NIXOS_LUSTRATE` files: + + `/etc/NIXOS` officializes that this is now a NixOS partition (the + bootup scripts require its presence). + + `/etc/NIXOS_LUSTRATE` tells the NixOS bootup scripts to move + *everything* that\'s in the root partition to `/old-root`. This will + move your existing distribution out of the way in the very early + stages of the NixOS bootup. There are exceptions (we do need to keep + NixOS there after all), so the NixOS lustrate process will not + touch: + + - The `/nix` directory + + - The `/boot` directory + + - Any file or directory listed in `/etc/NIXOS_LUSTRATE` (one per + line) + + ::: {.note} + Support for `NIXOS_LUSTRATE` was added in NixOS 16.09. The act of + \"lustrating\" refers to the wiping of the existing distribution. + Creating `/etc/NIXOS_LUSTRATE` can also be used on NixOS to remove + all mutable files from your root partition (anything that\'s not in + `/nix` or `/boot` gets \"lustrated\" on the next boot. + + lustrate /ˈlʌstreɪt/ verb. + + purify by expiatory sacrifice, ceremonial washing, or some other + ritual action. + ::: + + Let\'s create the files: + + ```ShellSession + $ sudo touch /etc/NIXOS + $ sudo touch /etc/NIXOS_LUSTRATE + ``` + + Let\'s also make sure the NixOS configuration files are kept once we + reboot on NixOS: + + ```ShellSession + $ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE + ``` + +1. Finally, move the `/boot` directory of your current distribution out + of the way (the lustrate process will take care of the rest once you + reboot, but this one must be moved out now because NixOS needs to + install its own boot files: + + ::: {.warning} + Once you complete this step, your current distribution will no + longer be bootable! If you didn\'t get all the NixOS configuration + right, especially those settings pertaining to boot loading and root + partition, NixOS may not be bootable either. Have a USB rescue + device ready in case this happens. + ::: + + ```ShellSession + $ sudo mv -v /boot /boot.bak && + sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot + ``` + + Cross your fingers, reboot, hopefully you should get a NixOS prompt! + +1. If for some reason you want to revert to the old distribution, + you\'ll need to boot on a USB rescue disk and do something along + these lines: + + ```ShellSession + # mkdir root + # mount /dev/sdaX root + # mkdir root/nixos-root + # mv -v root/* root/nixos-root/ + # mv -v root/nixos-root/old-root/* root/ + # mv -v root/boot.bak root/boot # We had renamed this by hand earlier + # umount root + # reboot + ``` + + This may work as is or you might also need to reinstall the boot + loader. + + And of course, if you\'re happy with NixOS and no longer need the + old distribution: + + ```ShellSession + sudo rm -rf /old-root + ``` + +1. It\'s also worth noting that this whole process can be automated. + This is especially useful for Cloud VMs, where provider do not + provide NixOS. For instance, + [nixos-infect](https://github.com/elitak/nixos-infect) uses the + lustrate process to convert Digital Ocean droplets to NixOS from + other distributions automatically. diff --git a/nixos/doc/manual/installation/installing-pxe.section.md b/nixos/doc/manual/installation/installing-pxe.section.md new file mode 100644 index 00000000000..4fbd6525f8c --- /dev/null +++ b/nixos/doc/manual/installation/installing-pxe.section.md @@ -0,0 +1,32 @@ +# Booting from the "netboot" media (PXE) {#sec-booting-from-pxe} + +Advanced users may wish to install NixOS using an existing PXE or iPXE +setup. + +These instructions assume that you have an existing PXE or iPXE +infrastructure and simply want to add the NixOS installer as another +option. To build the necessary files from your current version of nixpkgs, +you can run: + +```ShellSession +nix-build -A netboot.x86_64-linux '<nixpkgs/nixos/release.nix>' +``` + +This will create a `result` directory containing: \* `bzImage` -- the +Linux kernel \* `initrd` -- the initrd file \* `netboot.ipxe` -- an +example ipxe script demonstrating the appropriate kernel command line +arguments for this image + +If you're using plain PXE, configure your boot loader to use the +`bzImage` and `initrd` files and have it provide the same kernel command +line arguments found in `netboot.ipxe`. + +If you're using iPXE, depending on how your HTTP/FTP/etc. server is +configured you may be able to use `netboot.ipxe` unmodified, or you may +need to update the paths to the files to match your server's directory +layout. + +In the future we may begin making these files available as build +products from hydra at which point we will update this documentation +with instructions on how to obtain them either for placing on a +dedicated TFTP server or to boot them directly over the internet. diff --git a/nixos/doc/manual/installation/installing-usb.section.md b/nixos/doc/manual/installation/installing-usb.section.md new file mode 100644 index 00000000000..ae58c08e523 --- /dev/null +++ b/nixos/doc/manual/installation/installing-usb.section.md @@ -0,0 +1,31 @@ +# Booting from a USB Drive {#sec-booting-from-usb} + +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/sdX`. Be careful about specifying the correct +drive; you can use the `lsblk` command to get a list of block devices. + +::: {.note} +::: {.title} +On macOS +::: + +```ShellSession +$ diskutil list +[..] +/dev/diskN (external, physical): + #: TYPE NAME SIZE IDENTIFIER +[..] +$ diskutil unmountDisk diskN +Unmount of all volumes on diskN was successful +$ sudo dd 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. +::: + +The `dd` utility will write the image verbatim to the drive, making it +the recommended option for both UEFI and non-UEFI installations. diff --git a/nixos/doc/manual/installation/installing-virtualbox-guest.section.md b/nixos/doc/manual/installation/installing-virtualbox-guest.section.md new file mode 100644 index 00000000000..e9c2a621c1b --- /dev/null +++ b/nixos/doc/manual/installation/installing-virtualbox-guest.section.md @@ -0,0 +1,59 @@ +# Installing in a VirtualBox guest {#sec-instaling-virtualbox-guest} + +Installing NixOS into a VirtualBox guest is convenient for users who +want to try NixOS without installing it on bare metal. If you want to +use a pre-made VirtualBox appliance, it is available at [the downloads +page](https://nixos.org/nixos/download.html). If you want to set up a +VirtualBox guest manually, follow these instructions: + +1. Add a New Machine in VirtualBox with OS Type \"Linux / Other Linux\" + +1. Base Memory Size: 768 MB or higher. + +1. New Hard Disk of 8 GB or higher. + +1. Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM) + +1. Click on Settings / System / Processor and enable PAE/NX + +1. Click on Settings / System / Acceleration and enable \"VT-x/AMD-V\" + acceleration + +1. Click on Settings / Display / Screen and select VMSVGA as Graphics + Controller + +1. Save the settings, start the virtual machine, and continue + installation like normal + +There are a few modifications you should make in configuration.nix. +Enable booting: + +```nix +boot.loader.grub.device = "/dev/sda"; +``` + +Also remove the fsck that runs at startup. It will always fail to run, +stopping your boot until you press `*`. + +```nix +boot.initrd.checkJournalingFS = false; +``` + +Shared folders can be given a name and a path in the host system in the +VirtualBox settings (Machine / Settings / Shared Folders, then click on +the \"Add\" icon). Add the following to the +`/etc/nixos/configuration.nix` to auto-mount them. If you do not add +`"nofail"`, the system will not boot properly. + +```nix +{ config, pkgs, ...} : +{ + fileSystems."/virtualboxshare" = { + fsType = "vboxsf"; + device = "nameofthesharedfolder"; + options = [ "rw" "nofail" ]; + }; +} +``` + +The folder will be available directly under the root directory. diff --git a/nixos/doc/manual/installation/installing.chapter.md b/nixos/doc/manual/installation/installing.chapter.md new file mode 100644 index 00000000000..def4f37fbca --- /dev/null +++ b/nixos/doc/manual/installation/installing.chapter.md @@ -0,0 +1,482 @@ +# Installing NixOS {#sec-installation} + +## Booting the system {#sec-installation-booting} + +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 [](#sec-booting-from-usb)). + +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 by running `nixos-help`. + +You are logged-in automatically as `nixos`. The `nixos` user account has +an empty password so you can use `sudo` without a password: +```ShellSession +$ sudo -i +``` + +If you downloaded the graphical ISO image, you can run `systemctl +start display-manager` to start the desktop environment. 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`!) + +If the text is too small to be legible, try `setfont ter-v32n` to +increase the font size. + +To install over a serial port connect with `115200n8` (e.g. +`picocom -b 115200 /dev/ttyUSB0`). When the bootloader lists boot +entries, select the serial console boot entry. + +### Networking in the installer {#sec-installation-booting-networking} + +The boot process should have brought up networking (check `ip +a`). 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 `ifconfig`. + +On the graphical installer, you can configure the network, wifi +included, through NetworkManager. Using the `nmtui` program, you can do +so even in a non-graphical session. If you prefer to configure the +network manually, disable NetworkManager with +`systemctl stop NetworkManager`. + +On the minimal installer, NetworkManager is not available, so +configuration must be perfomed manually. To configure the wifi, first +start wpa_supplicant with `sudo systemctl start wpa_supplicant`, then +run `wpa_cli`. For most home networks, you need to type in the following +commands: + +```plain +> 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 +``` + +For enterprise networks, for example *eduroam*, instead do: + +```plain +> 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 +``` + +When successfully connected, you should see a line such as this one + +```plain +<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=] +``` + +you can now leave `wpa_cli` by typing `quit`. + +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 `/home/nixos/.ssh/authorized_keys` or +`/root/.ssh/authorized_keys` (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 `root` or `nixos` with `passwd` to be +able to login. + +## Partitioning and formatting {#sec-installation-partitioning} + +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) {#sec-installation-partitioning-UEFI} + +Here\'s an example partition scheme for UEFI, using `/dev/sda` as the +device. + +::: {.note} +You can safely ignore `parted`\'s informational message about needing to +update /etc/fstab. +::: + +1. Create a *GPT* partition table. + + ```ShellSession + # parted /dev/sda -- mklabel gpt + ``` + +2. Add the *root* 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. + + ```ShellSession + # parted /dev/sda -- mkpart primary 512MiB -8GiB + ``` + +3. Next, add a *swap* partition. The size required will vary according + to needs, here a 8GiB one is created. + + ```ShellSession + # parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + ``` + + ::: {.note} + The swap partition size rules are no different than for other Linux + distributions. + ::: + +4. 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. + + ```ShellSession + # parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB + # parted /dev/sda -- set 3 esp on + ``` + +Once complete, you can follow with +[](#sec-installation-partitioning-formatting). + +### Legacy Boot (MBR) {#sec-installation-partitioning-MBR} + +Here\'s an example partition scheme for Legacy Boot, using `/dev/sda` as +the device. + +::: {.note} +You can safely ignore `parted`\'s informational message about needing to +update /etc/fstab. +::: + +1. Create a *MBR* partition table. + + ```ShellSession + # parted /dev/sda -- mklabel msdos + ``` + +2. Add the *root* partition. This will fill the the disk except for the + end part, where the swap will live. + + ```ShellSession + # parted /dev/sda -- mkpart primary 1MiB -8GiB + ``` + +3. Finally, add a *swap* partition. The size required will vary + according to needs, here a 8GiB one is created. + + ```ShellSession + # parted /dev/sda -- mkpart primary linux-swap -8GiB 100% + ``` + + ::: {.note} + The swap partition size rules are no different than for other Linux + distributions. + ::: + +Once complete, you can follow with +[](#sec-installation-partitioning-formatting). + +### Formatting {#sec-installation-partitioning-formatting} + +Use the following commands: + +- For initialising Ext4 partitions: `mkfs.ext4`. It is recommended + that you assign a unique symbolic label to the file system using the + option `-L label`, since this makes the file system configuration + independent from device changes. For example: + + ```ShellSession + # mkfs.ext4 -L nixos /dev/sda1 + ``` + +- For creating swap partitions: `mkswap`. Again it's recommended to + assign a label to the swap partition: `-L label`. For example: + + ```ShellSession + # mkswap -L swap /dev/sda2 + ``` + +- **UEFI systems** + + For creating boot partitions: `mkfs.fat`. Again it's recommended + to assign a label to the boot partition: `-n label`. For + example: + + ```ShellSession + # mkfs.fat -F 32 -n boot /dev/sda3 + ``` + +- For creating LVM volumes, the LVM commands, e.g., `pvcreate`, + `vgcreate`, and `lvcreate`. + +- For creating software RAID devices, use `mdadm`. + +## Installing {#sec-installation-installing} + +1. Mount the target file system on which NixOS should be installed on + `/mnt`, e.g. + + ```ShellSession + # mount /dev/disk/by-label/nixos /mnt + ``` + +2. **UEFI systems** + + Mount the boot file system on `/mnt/boot`, e.g. + + ```ShellSession + # mkdir -p /mnt/boot + # mount /dev/disk/by-label/boot /mnt/boot + ``` + +3. 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. + + ```ShellSession + # swapon /dev/sda2 + ``` + +4. 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 [](#sec-configuration-syntax), + while a list of available configuration options appears in + [](#ch-options). A minimal example is shown in + [Example: NixOS Configuration](#ex-config). + + The command `nixos-generate-config` can generate an initial + configuration file for you: + + ```ShellSession + # nixos-generate-config --root /mnt + ``` + + You should then edit `/mnt/etc/nixos/configuration.nix` to suit your + needs: + + ```ShellSession + # 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 -f '<nixpkgs>' -iA emacs`. + + BIOS systems + + : You *must* set the option [](#opt-boot.loader.grub.device) 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 [](#opt-boot.loader.systemd-boot.enable) + 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 + [`boot.loader.efi`](#opt-boot.loader.efi.canTouchEfiVariables) and + [`boot.loader.systemd-boot`](#opt-boot.loader.systemd-boot.enable) + as well. + + If there are other operating systems running on the machine before + installing NixOS, the [](#opt-boot.loader.grub.useOSProber) + option can be set to `true` to automatically add them to the grub + menu. + + If you need to configure networking for your machine the + configuration options are described in [](#sec-networking). In + particular, while wifi is supported on the installation image, it is + not enabled by default in the configuration generated by + `nixos-generate-config`. + + Another critical option is `fileSystems`, 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.) + Additionally, you may want to look at [Hardware configuration for + known-hardware](https://github.com/NixOS/nixos-hardware) at this + point or after installation. + + ::: {.note} + Depending on your hardware configuration or type of file system, you + may need to set the option `boot.initrd.kernelModules` 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. + ::: + +5. Do the installation: + + ```ShellSession + # nixos-install + ``` + + 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 `nixos-install` after + fixing your `configuration.nix`. + + As the last step, `nixos-install` will ask you to set the password + for the `root` user, e.g. + + ```plain + setting root password... + New password: *** + Retype new password: *** + ``` + + ::: {.note} + For unattended installations, it is possible to use + `nixos-install --no-root-passwd` in order to disable the password + prompt entirely. + ::: + +6. If everything went well: + + ```ShellSession + # reboot + ``` + +7. 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](#sec-changing-config)), 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`: + + ```ShellSession + $ useradd -c 'Eelco Dolstra' -m eelco + $ passwd eelco + ``` + + You may also want to install some software. This will be covered in + [](#sec-package-management). + +## Installation summary {#sec-installation-summary} + +To summarise, [Example: Commands for Installing NixOS on `/dev/sda`](#ex-install-sequence) +shows a typical sequence of commands for installing NixOS on an empty hard +drive (here `/dev/sda`). [Example: NixOS Configuration](#ex-config) shows a +corresponding configuration Nix expression. + +::: {#ex-partition-scheme-MBR .example} +::: {.title} +**Example: Example partition schemes for NixOS on `/dev/sda` (MBR)** +::: +```ShellSession +# parted /dev/sda -- mklabel msdos +# parted /dev/sda -- mkpart primary 1MiB -8GiB +# parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +``` +::: + +::: {#ex-partition-scheme-UEFI .example} +::: {.title} +**Example: Example partition schemes for NixOS on `/dev/sda` (UEFI)** +::: +```ShellSession +# 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 +``` +::: + +::: {#ex-install-sequence .example} +::: {.title} +**Example: Commands for Installing NixOS on `/dev/sda`** +::: +With a partitioned disk. + +```ShellSession +# 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 +``` +::: + +::: {#ex-config .example} +::: {.title} +**Example: NixOS Configuration** +::: +```ShellSession +{ 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; +} +``` +::: + +## Additional installation notes {#sec-installation-additional-notes} + +```{=docbook} +<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" /> +``` diff --git a/nixos/doc/manual/installation/obtaining.chapter.md b/nixos/doc/manual/installation/obtaining.chapter.md new file mode 100644 index 00000000000..832ec6146a9 --- /dev/null +++ b/nixos/doc/manual/installation/obtaining.chapter.md @@ -0,0 +1,26 @@ +# Obtaining NixOS {#sec-obtaining} + +NixOS ISO images can be downloaded from the [NixOS download +page](https://nixos.org/nixos/download.html). There are a number of +installation options. If you happen to have an optical drive and a spare +CD, burning the image to CD and booting from that is probably the +easiest option. Most people will need to prepare a USB stick to boot +from. [](#sec-booting-from-usb) describes the preferred method to +prepare a USB stick. A number of alternative methods are presented in +the [NixOS Wiki](https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media). + +As an alternative to installing NixOS yourself, you can get a running +NixOS system through several other means: + +- Using virtual appliances in Open Virtualization Format (OVF) that + can be imported into VirtualBox. These are available from the [NixOS + download page](https://nixos.org/nixos/download.html). + +- Using AMIs for Amazon's EC2. To find one for your region and + instance type, please refer to the [list of most recent + AMIs](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix). + +- Using NixOps, the NixOS-based cloud deployment tool, which allows + you to provision VirtualBox and EC2 NixOS instances from declarative + specifications. Check out the [NixOps + homepage](https://nixos.org/nixops) for details. diff --git a/nixos/doc/manual/installation/upgrading.chapter.md b/nixos/doc/manual/installation/upgrading.chapter.md new file mode 100644 index 00000000000..faeefc4451d --- /dev/null +++ b/nixos/doc/manual/installation/upgrading.chapter.md @@ -0,0 +1,118 @@ +# Upgrading NixOS {#sec-upgrading} + +The best way to keep your NixOS installation up to date is to use one of +the NixOS *channels*. A channel is a Nix mechanism for distributing Nix +expressions and associated binaries. The NixOS channels are updated +automatically from NixOS's Git repository after certain tests have +passed and all packages have been built. These channels are: + +- *Stable channels*, such as [`nixos-21.11`](https://nixos.org/channels/nixos-21.11). + These only get conservative bug fixes and package upgrades. For + instance, a channel update may cause the Linux kernel on your system + to be upgraded from 4.19.34 to 4.19.38 (a minor bug fix), but not + from 4.19.x to 4.20.x (a major change that has the potential to break things). + Stable channels are generally maintained until the next stable + branch is created. + +- The *unstable channel*, [`nixos-unstable`](https://nixos.org/channels/nixos-unstable). + This corresponds to NixOS's main development branch, and may thus see + radical changes between channel updates. It's not recommended for + production systems. + +- *Small channels*, such as [`nixos-21.11-small`](https://nixos.org/channels/nixos-21.11-small) + or [`nixos-unstable-small`](https://nixos.org/channels/nixos-unstable-small). + These are identical to the stable and unstable channels described above, + except that they contain fewer binary packages. This means they get updated + faster than the regular channels (for instance, when a critical security patch + is committed to NixOS's source tree), but may require more packages to be + built from source than usual. They're mostly intended for server environments + and as such contain few GUI applications. + +To see what channels are available, go to <https://nixos.org/channels>. +(Note that the URIs of the various channels redirect to a directory that +contains the channel's latest version and includes ISO images and +VirtualBox appliances.) Please note that during the release process, +channels that are not yet released will be present here as well. See the +Getting NixOS page <https://nixos.org/nixos/download.html> to find the +newest supported stable release. + +When you first install NixOS, you're automatically subscribed to the +NixOS channel that corresponds to your installation source. For +instance, if you installed from a 21.11 ISO, you will be subscribed to +the `nixos-21.11` channel. To see which NixOS channel you're subscribed +to, run the following as root: + +```ShellSession +# nix-channel --list | grep nixos +nixos https://nixos.org/channels/nixos-unstable +``` + +To switch to a different NixOS channel, do + +```ShellSession +# nix-channel --add https://nixos.org/channels/channel-name nixos +``` + +(Be sure to include the `nixos` parameter at the end.) For instance, to +use the NixOS 21.11 stable channel: + +```ShellSession +# nix-channel --add https://nixos.org/channels/nixos-21.11 nixos +``` + +If you have a server, you may want to use the "small" channel instead: + +```ShellSession +# nix-channel --add https://nixos.org/channels/nixos-21.11-small nixos +``` + +And if you want to live on the bleeding edge: + +```ShellSession +# nix-channel --add https://nixos.org/channels/nixos-unstable nixos +``` + +You can then upgrade NixOS to the latest version in your chosen channel +by running + +```ShellSession +# nixos-rebuild switch --upgrade +``` + +which is equivalent to the more verbose `nix-channel --update nixos; nixos-rebuild switch`. + +::: {.note} +Channels are set per user. This means that running `nix-channel --add` +as a non root user (or without sudo) will not affect +configuration in `/etc/nixos/configuration.nix` +::: + +::: {.warning} +It is generally safe to switch back and forth between channels. The only +exception is that a newer NixOS may also have a newer Nix version, which +may involve an upgrade of Nix's database schema. This cannot be undone +easily, so in that case you will not be able to go back to your original +channel. +::: + +## Automatic Upgrades {#sec-upgrading-automatic} + +You can keep a NixOS system up-to-date automatically by adding the +following to `configuration.nix`: + +```nix +system.autoUpgrade.enable = true; +system.autoUpgrade.allowReboot = true; +``` + +This enables a periodically executed systemd service named +`nixos-upgrade.service`. If the `allowReboot` option is `false`, it runs +`nixos-rebuild switch --upgrade` to upgrade NixOS to the latest version +in the current channel. (To see when the service runs, see `systemctl list-timers`.) +If `allowReboot` is `true`, then the system will automatically reboot if +the new generation contains a different kernel, initrd or kernel +modules. You can also specify a channel explicitly, e.g. + +```nix +system.autoUpgrade.channel = https://nixos.org/channels/nixos-21.11; +``` |