diff --git a/nixos/doc/manual/installation.xml b/nixos/doc/manual/installation.xml index 9dcf9f82463a..0bf92b7d5bc6 100644 --- a/nixos/doc/manual/installation.xml +++ b/nixos/doc/manual/installation.xml @@ -89,9 +89,14 @@ running NixOS system through several other means: For initialising Ext4 partitions: mkfs.ext4. It is recommended that you assign a unique symbolic label to the file system using the option - . This will - make the file system configuration independent from device - changes. + , since this + makes the file system configuration independent from device + changes. For example: + + +$ mkfs.ext4 -L nixos /dev/sda1 + + For creating swap partitions: mkswap. Again it’s recommended to assign a @@ -124,6 +129,12 @@ $ mount /dev/disk/by-label/nixos /mnt + 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. + You now need to create a file @@ -188,28 +199,16 @@ $ nano /mnt/etc/nixos/configuration.nix - 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. - - - Do the installation: $ nixos-install - Cross fingers. + 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. If everything went well: @@ -221,7 +220,7 @@ $ reboot You should now be able to boot into the installed NixOS. - The Grub boot menu shows a list of available + The GRUB boot menu shows a list of available configurations (initially just one). Every time you change the NixOS configuration (see ), a new item appears in the menu. @@ -256,20 +255,20 @@ $ nix-env -i w3m - shows a typical sequence -of commands for installing NixOS on an empty hard drive (here -/dev/sda). shows a -corresponding configuration Nix expression. +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) -$ mkfs.ext4 -L nixos /dev/sda1 (idem) -$ mkswap -L swap /dev/sda2 (idem) -$ mount LABEL=nixos /mnt -$ nixos-generate-config +$ fdisk /dev/sda # (or whatever device you want to install on) +$ mkfs.ext4 -L nixos /dev/sda1 +$ mkswap -L swap /dev/sda2 +$ swapon /dev/sda2 +$ mount /dev/disk/by-label/nixos /mnt +$ nixos-generate-config --root /mnt $ nano /mnt/etc/nixos/configuration.nix -(in particular, set the fileSystems and swapDevices options) $ nixos-install $ reboot @@ -284,14 +283,12 @@ $ reboot boot.loader.grub.device = "/dev/sda"; - # Note: setting fileSystems and swapDevices is generally not - # necessary, since nixos-generate-config has set them automatically - # in hardware-configuration.nix. - fileSystems."/".device = "/dev/disk/by-label/nixos"; - - swapDevices = - [ { device = "/dev/disk/by-label/swap"; } ]; + # 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; } @@ -317,6 +314,10 @@ 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). +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 @@ -336,6 +337,18 @@ 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. + + +$ 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 @@ -346,7 +359,7 @@ 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 virtual machine that contains the +running a QEMU virtual machine that contains the desired configuration. Just do @@ -361,7 +374,6 @@ available. -
@@ -369,28 +381,85 @@ available. Upgrading NixOS The best way to keep your NixOS installation up to date is to -use the nixos-unstable channel. (A channel is a +use one of the NixOS channels. A channel is a Nix mechanism for distributing Nix expressions and associated -binaries.) The NixOS channel is updated automatically from NixOS’s -Git repository after running certain tests and building most -packages. +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: -NixOS automatically subscribes you to the NixOS channel. If for -some reason this is not the case, just do + + + Stable channels, such as nixos-13.10. + 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 3.4.66 to 3.4.67 (a minor bug fix), but + not from 3.4.x to + 3.11.x (a major change that has the + potential to break things). + + + The unstable channel, 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. + + + +To see what channels are available, go to . (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.) + +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 13.10 ISO, you will be subscribed to +the nixos-13.10 channel. To see which NixOS +channel you’re subscribed to, run the following as root: -$ nix-channel --add http://nixos.org/channels/nixos-unstable +$ nix-channel --list | grep nixos +nixos https://nixos.org/channels/nixos-unstable -You can then upgrade NixOS to the latest version in the channel by -running +To switch to a different NixOS channel, do -$ nix-channel --update nixos +$ nix-channel --add http://nixos.org/channels/channel-name nixos -and running the nixos-rebuild command as described -in . +(Be sure to include the nixos parameter at the +end.) For instance, to use the NixOS 13.10 stable channel: + + +$ nix-channel --add http://nixos.org/channels/nixos-13.10 nixos + + +But it you want to live on the bleeding edge: + + +$ nix-channel --add http://nixos.org/channels/nixos-unstable nixos + + + + +You can then upgrade NixOS to the latest version in your chosen +channel by running + + +$ nixos-rebuild switch --upgrade + + +which is equivalent to the more verbose nix-channel --update +nixos; nixos-rebuild switch. + +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.