diff options
Diffstat (limited to 'nixpkgs/nixos/doc/manual/installation')
10 files changed, 1455 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/installation/changing-config.xml b/nixpkgs/nixos/doc/manual/installation/changing-config.xml new file mode 100644 index 000000000000..b77d71389a9d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/changing-config.xml @@ -0,0 +1,90 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + version="5.0" + xml:id="sec-changing-config"> + <title>Changing the Configuration</title> + <para> + The file <filename>/etc/nixos/configuration.nix</filename> contains the + current configuration of your machine. Whenever you’ve + <link linkend="ch-configuration">changed something</link> in that file, you + should do +<screen> +<prompt># </prompt>nixos-rebuild switch +</screen> + 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). + </para> + <warning> + <para> + These commands must be executed as root, so you should either run them from + a root shell or by prefixing them with <literal>sudo -i</literal>. + </para> + </warning> + <para> + You can also do +<screen> +<prompt># </prompt>nixos-rebuild test +</screen> + 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. + </para> + <para> + There is also +<screen> +<prompt># </prompt>nixos-rebuild boot +</screen> + 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). + </para> + <para> + You can make your configuration show up in a different submenu of the GRUB 2 + boot screen by giving it a different <emphasis>profile name</emphasis>, e.g. +<screen> +<prompt># </prompt>nixos-rebuild switch -p test +</screen> + which causes the new configuration (and previous ones created using + <literal>-p test</literal>) to show up in the GRUB submenu “NixOS - Profile + 'test'”. This can be useful to separate test configurations from + “stable” configurations. + </para> + <para> + Finally, you can do +<screen> +<prompt>$ </prompt>nixos-rebuild build +</screen> + to build the configuration but nothing more. This is useful to see whether + everything compiles cleanly. + </para> + <para> + 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 + <emphasis>virtual machine</emphasis> that contains the desired configuration. + Just do +<screen> +<prompt>$ </prompt>nixos-rebuild build-vm +<prompt>$ </prompt>./result/bin/run-*-vm +</screen> + 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 + <literal>mutableUsers = false</literal>. Another way is to temporarily add + the following to your configuration: +<screen> +<link linkend="opt-users.users._name__.initialHashedPassword">users.users.your-user.initialHashedPassword</link> = "test"; +</screen> + <emphasis>Important:</emphasis> 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): +<screen> +<prompt>$ </prompt>QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm +</screen> + allowing you to log in via SSH (assuming you have set the appropriate + passwords or SSH authorized keys): +<screen> +<prompt>$ </prompt>ssh -p 2222 localhost +</screen> + </para> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/installation/installation.xml b/nixpkgs/nixos/doc/manual/installation/installation.xml new file mode 100644 index 000000000000..2901f462dee0 --- /dev/null +++ b/nixpkgs/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="obtaining.xml" /> + <xi:include href="installing.xml" /> + <xi:include href="changing-config.xml" /> + <xi:include href="upgrading.xml" /> +</part> diff --git a/nixpkgs/nixos/doc/manual/installation/installing-behind-a-proxy.xml b/nixpkgs/nixos/doc/manual/installation/installing-behind-a-proxy.xml new file mode 100644 index 000000000000..8f9baff44b51 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing-behind-a-proxy.xml @@ -0,0 +1,48 @@ +<section 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-installing-behind-proxy"> + <title>Installing behind a proxy</title> + + <para> + To install NixOS behind a proxy, do the following before running + <literal>nixos-install</literal>. + </para> + + <orderedlist numeration="arabic"> + <listitem> + <para> + Update proxy configuration in + <literal>/mnt/etc/nixos/configuration.nix</literal> to keep the internet + accessible after reboot. + </para> +<programlisting> +networking.proxy.default = "http://user:password@proxy:port/"; +networking.proxy.noProxy = "127.0.0.1,localhost,internal.domain"; +</programlisting> + </listitem> + <listitem> + <para> + Setup the proxy environment variables in the shell where you are running + <literal>nixos-install</literal>. + </para> +<programlisting> +# 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" +</programlisting> + </listitem> + </orderedlist> + + <note> + <para> + If you are switching networks with different proxy configurations, use the + <literal>nesting.clone</literal> option in + <literal>configuration.nix</literal> to switch proxies at runtime. Refer to + <xref linkend="ch-options" /> for more information. + </para> + </note> +</section> diff --git a/nixpkgs/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixpkgs/nixos/doc/manual/installation/installing-from-other-distro.xml new file mode 100644 index 000000000000..8ed45899fd7f --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing-from-other-distro.xml @@ -0,0 +1,357 @@ +<!-- vim: set expandtab ts=2 softtabstop=2 shiftwidth=2 smarttab textwidth=80 wrapmargin=2 --> +<section + 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-installing-from-other-distro"> + <title>Installing from another Linux distribution</title> + + <para> + 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: + </para> + + <orderedlist> + <listitem> + <para> + Install NixOS on another partition, from your existing Linux distribution + (without the use of a USB or optical device!) + </para> + </listitem> + <listitem> + <para> + Install NixOS on the same partition (in place!), from your existing + non-NixOS Linux distribution using <literal>NIXOS_LUSTRATE</literal>. + </para> + </listitem> + <listitem> + <para> + Install NixOS on your hard drive from the Live CD of any Linux + distribution. + </para> + </listitem> + </orderedlist> + + <para> + The first steps to all these are the same: + </para> + + <orderedlist> + <listitem> + <para> + Install the Nix package manager: + </para> + <para> + Short version: + </para> +<screen> +<prompt>$ </prompt>curl https://nixos.org/nix/install | sh +<prompt>$ </prompt>. $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen> + <para> + More details in the + <link + xlink:href="https://nixos.org/nix/manual/#chap-quick-start"> + Nix manual</link> + </para> + </listitem> + <listitem> + <para> + Switch to the NixOS channel: + </para> + <para> + If you've just installed Nix on a non-NixOS distribution, you will be on + the <literal>nixpkgs</literal> channel by default. + </para> +<screen> +<prompt>$ </prompt>nix-channel --list +nixpkgs https://nixos.org/channels/nixpkgs-unstable</screen> + <para> + As that channel gets released without running the NixOS tests, it will be + safer to use the <literal>nixos-*</literal> channels instead: + </para> +<screen> +<prompt>$ </prompt>nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen> + <para> + You may want to throw in a <literal>nix-channel --update</literal> for good + measure. + </para> + </listitem> + <listitem> + <para> + Install the NixOS installation tools: + </para> + <para> + You'll need <literal>nixos-generate-config</literal> and + <literal>nixos-install</literal> and we'll throw in some man pages and + <literal>nixos-enter</literal> just in case you want to chroot into your + NixOS partition. They are installed by default on NixOS, but you don't have + NixOS yet.. + </para> +<screen><prompt>$ </prompt>nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen> + </listitem> + <listitem> + <note> + <para> + The following 5 steps are only for installing NixOS to another partition. + For installing NixOS in place using <literal>NIXOS_LUSTRATE</literal>, + skip ahead. + </para> + </note> + <para> + Prepare your target partition: + </para> + <para> + At this point it is time to prepare your target partition. Please refer to + the partitioning, file-system creation, and mounting steps of + <xref linkend="sec-installation" /> + </para> + <para> + If you're about to install NixOS in place using + <literal>NIXOS_LUSTRATE</literal> there is nothing to do for this step. + </para> + </listitem> + <listitem> + <para> + Generate your NixOS configuration: + </para> +<screen><prompt>$ </prompt>sudo `which nixos-generate-config` --root /mnt</screen> + <para> + You'll probably want to edit the configuration files. Refer to the + <literal>nixos-generate-config</literal> step in + <xref + linkend="sec-installation" /> for more + information. + </para> + <para> + 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 <literal>configuration.nix</literal>: + </para> +<programlisting> +<xref linkend="opt-boot.loader.grub.extraEntries"/> = '' + menuentry "Ubuntu" { + search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e + configfile "($ubuntu)/boot/grub/grub.cfg" + } +'';</programlisting> + <para> + (You can find the appropriate UUID for your partition in + <literal>/dev/disk/by-uuid</literal>) + </para> + </listitem> + <listitem> + <para> + Create the <literal>nixbld</literal> group and user on your original + distribution: + </para> +<screen> +<prompt>$ </prompt>sudo groupadd -g 30000 nixbld +<prompt>$ </prompt>sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen> + </listitem> + <listitem> + <para> + Download/build/install NixOS: + </para> + <warning> + <para> + 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. + </para> + </warning> +<screen><prompt>$ </prompt>sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen> + <para> + Again, please refer to the <literal>nixos-install</literal> step in + <xref linkend="sec-installation" /> for more information. + </para> + <para> + That should be it for installation to another partition! + </para> + </listitem> + <listitem> + <para> + Optionally, you may want to clean up your non-NixOS distribution: + </para> +<screen> +<prompt>$ </prompt>sudo userdel nixbld +<prompt>$ </prompt>sudo groupdel nixbld</screen> + <para> + If you do not wish to keep the Nix package manager installed either, run + something like <literal>sudo rm -rv ~/.nix-* /nix</literal> and remove the + line that the Nix installer added to your <literal>~/.profile</literal>. + </para> + </listitem> + <listitem> + <note> + <para> + The following steps are only for installing NixOS in place using + <literal>NIXOS_LUSTRATE</literal>: + </para> + </note> + <para> + Generate your NixOS configuration: + </para> +<screen><prompt>$ </prompt>sudo `which nixos-generate-config` --root /</screen> + <para> + Note that this will place the generated configuration files in + <literal>/etc/nixos</literal>. You'll probably want to edit the + configuration files. Refer to the <literal>nixos-generate-config</literal> + step in <xref + linkend="sec-installation" /> for more + information. + </para> + <para> + 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 <literal>sudo passwd -l root</literal> if you + use <literal>sudo</literal>) + </para> +<programlisting> +<link linkend="opt-users.users._name__.initialHashedPassword">users.users.root.initialHashedPassword</link> = ""; +</programlisting> + </listitem> + <listitem> + <para> + Build the NixOS closure and install it in the <literal>system</literal> + profile: + </para> +<screen><prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen> + </listitem> + <listitem> + <para> + Change ownership of the <literal>/nix</literal> tree to root (since your + Nix install was probably single user): + </para> +<screen><prompt>$ </prompt>sudo chown -R 0.0 /nix</screen> + </listitem> + <listitem> + <para> + Set up the <literal>/etc/NIXOS</literal> and + <literal>/etc/NIXOS_LUSTRATE</literal> files: + </para> + <para> + <literal>/etc/NIXOS</literal> officializes that this is now a NixOS + partition (the bootup scripts require its presence). + </para> + <para> + <literal>/etc/NIXOS_LUSTRATE</literal> tells the NixOS bootup scripts to + move <emphasis>everything</emphasis> that's in the root partition to + <literal>/old-root</literal>. 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: + </para> + <itemizedlist> + <listitem> + <para> + The <literal>/nix</literal> directory + </para> + </listitem> + <listitem> + <para> + The <literal>/boot</literal> directory + </para> + </listitem> + <listitem> + <para> + Any file or directory listed in <literal>/etc/NIXOS_LUSTRATE</literal> + (one per line) + </para> + </listitem> + </itemizedlist> + <note> + <para> + Support for <literal>NIXOS_LUSTRATE</literal> was added in NixOS 16.09. + The act of "lustrating" refers to the wiping of the existing distribution. + Creating <literal>/etc/NIXOS_LUSTRATE</literal> can also be used on NixOS + to remove all mutable files from your root partition (anything that's not + in <literal>/nix</literal> or <literal>/boot</literal> gets "lustrated" on + the next boot. + </para> + <para> + lustrate /ˈlʌstreɪt/ verb. + </para> + <para> + purify by expiatory sacrifice, ceremonial washing, or some other ritual + action. + </para> + </note> + <para> + Let's create the files: + </para> +<screen> +<prompt>$ </prompt>sudo touch /etc/NIXOS +<prompt>$ </prompt>sudo touch /etc/NIXOS_LUSTRATE +</screen> + <para> + Let's also make sure the NixOS configuration files are kept once we reboot + on NixOS: + </para> +<screen> +<prompt>$ </prompt>echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE +</screen> + </listitem> + <listitem> + <para> + Finally, move the <literal>/boot</literal> 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: + </para> + <warning> + <para> + 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. + </para> + </warning> +<screen> +<prompt>$ </prompt>sudo mv -v /boot /boot.bak && +sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot +</screen> + <para> + Cross your fingers, reboot, hopefully you should get a NixOS prompt! + </para> + </listitem> + <listitem> + <para> + 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: + </para> +<screen> +# 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</screen> + <para> + This may work as is or you might also need to reinstall the boot loader + </para> + <para> + And of course, if you're happy with NixOS and no longer need the old + distribution: + </para> +<screen>sudo rm -rf /old-root</screen> + </listitem> + <listitem> + <para> + 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, + <link + xlink:href="https://github.com/elitak/nixos-infect">nixos-infect</link> + uses the lustrate process to convert Digital Ocean droplets to NixOS from + other distributions automatically. + </para> + </listitem> + </orderedlist> +</section> diff --git a/nixpkgs/nixos/doc/manual/installation/installing-pxe.xml b/nixpkgs/nixos/doc/manual/installation/installing-pxe.xml new file mode 100644 index 000000000000..94199e5e028d --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing-pxe.xml @@ -0,0 +1,50 @@ +<section 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-booting-from-pxe"> + <title>Booting from the <quote>netboot</quote> media (PXE)</title> + + <para> + Advanced users may wish to install NixOS using an existing PXE or iPXE setup. + </para> + + <para> + 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 a recent version of nixpkgs, you can run: + </para> + +<programlisting> +nix-build -A netboot nixos/release.nix +</programlisting> + + <para> + This will create a <literal>result</literal> directory containing: * + <literal>bzImage</literal> – the Linux kernel * <literal>initrd</literal> + – the initrd file * <literal>netboot.ipxe</literal> – an example ipxe + script demonstrating the appropriate kernel command line arguments for this + image + </para> + + <para> + If you’re using plain PXE, configure your boot loader to use the + <literal>bzImage</literal> and <literal>initrd</literal> files and have it + provide the same kernel command line arguments found in + <literal>netboot.ipxe</literal>. + </para> + + <para> + If you’re using iPXE, depending on how your HTTP/FTP/etc. server is + configured you may be able to use <literal>netboot.ipxe</literal> unmodified, + or you may need to update the paths to the files to match your server’s + directory layout + </para> + + <para> + 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. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/installation/installing-usb.xml b/nixpkgs/nixos/doc/manual/installation/installing-usb.xml new file mode 100644 index 000000000000..83598635acca --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing-usb.xml @@ -0,0 +1,40 @@ +<section 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-booting-from-usb"> + <title>Booting from a USB Drive</title> + + <para> + For systems without CD drive, the NixOS live CD can be booted from a USB + stick. You can use the <command>dd</command> utility to write the image: + <command>dd if=<replaceable>path-to-image</replaceable> + of=<replaceable>/dev/sdX</replaceable></command>. Be careful about specifying + the correct drive; you can use the <command>lsblk</command> command to get a + list of block devices. + <note> + <title>On macOS</title> + <para> +<screen> +<prompt>$ </prompt>diskutil list +[..] +/dev/diskN (external, physical): + #: TYPE NAME SIZE IDENTIFIER +[..] +<prompt>$ </prompt>diskutil unmountDisk diskN +Unmount of all volumes on diskN was successful +<prompt>$ </prompt>sudo dd if=nix.iso of=/dev/rdiskN +</screen> + Using the 'raw' <command>rdiskN</command> device instead of + <command>diskN</command> completes in minutes instead of hours. After + <command>dd</command> completes, a GUI dialog "The disk you inserted was + not readable by this computer" will pop up, which can be ignored. + </para> + </note> + </para> + + <para> + The <command>dd</command> utility will write the image verbatim to the drive, + making it the recommended option for both UEFI and non-UEFI installations. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/installation/installing-virtualbox-guest.xml b/nixpkgs/nixos/doc/manual/installation/installing-virtualbox-guest.xml new file mode 100644 index 000000000000..5c86eacfbf45 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing-virtualbox-guest.xml @@ -0,0 +1,103 @@ +<section 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-instaling-virtualbox-guest"> + <title>Installing in a VirtualBox guest</title> + + <para> + 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 + <link + xlink:href="https://nixos.org/nixos/download.html">the downloads + page</link>. If you want to set up a VirtualBox guest manually, follow these + instructions: + </para> + + <orderedlist> + <listitem> + <para> + Add a New Machine in VirtualBox with OS Type "Linux / Other Linux" + </para> + </listitem> + <listitem> + <para> + Base Memory Size: 768 MB or higher. + </para> + </listitem> + <listitem> + <para> + New Hard Disk of 8 GB or higher. + </para> + </listitem> + <listitem> + <para> + Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM) + </para> + </listitem> + <listitem> + <para> + Click on Settings / System / Processor and enable PAE/NX + </para> + </listitem> + <listitem> + <para> + Click on Settings / System / Acceleration and enable "VT-x/AMD-V" + acceleration + </para> + </listitem> + <listitem> + <para> + Save the settings, start the virtual machine, and continue installation + like normal + </para> + </listitem> + </orderedlist> + + <para> + There are a few modifications you should make in configuration.nix. Enable + booting: + </para> + +<programlisting> +<xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda"; +</programlisting> + + <para> + Also remove the fsck that runs at startup. It will always fail to run, + stopping your boot until you press <literal>*</literal>. + </para> + +<programlisting> +<xref linkend="opt-boot.initrd.checkJournalingFS"/> = false; +</programlisting> + + <para> + 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 + <literal>/etc/nixos/configuration.nix</literal> to auto-mount them. If you do + not add <literal>"nofail"</literal>, the system will no boot properly. The + same goes for disabling <literal>rngd</literal> which is normally used to get + randomness but this does not work in virtual machines. + </para> + +<programlisting> +{ config, pkgs, ...} : +{ + security.rngd.enable = false; // otherwise vm will not boot + ... + + fileSystems."/virtualboxshare" = { + fsType = "vboxsf"; + device = "nameofthesharedfolder"; + options = [ "rw" "nofail" ]; + }; +} +</programlisting> + + <para> + The folder will be available directly under the root directory. + </para> +</section> diff --git a/nixpkgs/nixos/doc/manual/installation/installing.xml b/nixpkgs/nixos/doc/manual/installation/installing.xml new file mode 100644 index 000000000000..742376378dea --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/installing.xml @@ -0,0 +1,562 @@ +<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 on virtual console 8 (press Alt+F8 to access) + or by running <command>nixos-help</command>. + </para> + + <para> + You are logged-in automatically as <literal>root</literal>. (The + <literal>root</literal> user account has an empty password.) + </para> + + <para> + If you downloaded the graphical ISO image, you can run <command>systemctl + start display-manager</command> to start KDE. 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> + + <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 + need to activate the SSH daemon via <literal>systemctl start + sshd</literal>. In order to be able to login you also need to set a + password for <literal>root</literal> using <literal>passwd</literal>. + </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 boot 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 -i 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</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"/>. + </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.) + </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> + 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 <command>nixos-install</command>. Otherwise, fix your + <filename>configuration.nix</filename> and then re-run + <command>nixos-install</command>. + </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... +Enter new UNIX password: *** +Retype new UNIX 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. For instance, +<screen> +<prompt>$ </prompt>nix-env -qa \*</screen> + shows what packages are available, and +<screen> +<prompt>$ </prompt>nix-env -i w3m</screen> + install the <literal>w3m</literal> browser. + </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 boot 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> diff --git a/nixpkgs/nixos/doc/manual/installation/obtaining.xml b/nixpkgs/nixos/doc/manual/installation/obtaining.xml new file mode 100644 index 000000000000..56af5c0e25a0 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/obtaining.xml @@ -0,0 +1,54 @@ +<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-obtaining"> + <title>Obtaining NixOS</title> + <para> + NixOS ISO images can be downloaded from the + <link +xlink:href="http://nixos.org/nixos/download.html">NixOS download + page</link>. 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. <xref linkend="sec-booting-from-usb"/> describes the + preferred method to prepare a USB stick. A number of alternative methods are + presented in the + <link +xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS + Wiki</link>. + </para> + <para> + As an alternative to installing NixOS yourself, you can get a running NixOS + system through several other means: + <itemizedlist> + <listitem> + <para> + Using virtual appliances in Open Virtualization Format (OVF) that can be + imported into VirtualBox. These are available from the + <link xlink:href="http://nixos.org/nixos/download.html">NixOS download + page</link>. + </para> + </listitem> + <listitem> + <para> + Using AMIs for Amazon’s EC2. To find one for your region and instance + type, please refer to the + <link + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list + of most recent AMIs</link>. + </para> + </listitem> + <listitem> + <para> + Using NixOps, the NixOS-based cloud deployment tool, which allows you to + provision VirtualBox and EC2 NixOS instances from declarative + specifications. Check out the + <link + xlink:href="https://nixos.org/nixops">NixOps homepage</link> for + details. + </para> + </listitem> + </itemizedlist> + </para> +</chapter> diff --git a/nixpkgs/nixos/doc/manual/installation/upgrading.xml b/nixpkgs/nixos/doc/manual/installation/upgrading.xml new file mode 100644 index 000000000000..35b4d266e12e --- /dev/null +++ b/nixpkgs/nixos/doc/manual/installation/upgrading.xml @@ -0,0 +1,134 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + version="5.0" + xml:id="sec-upgrading"> + <title>Upgrading NixOS</title> + <para> + The best way to keep your NixOS installation up to date is to use one of the + NixOS <emphasis>channels</emphasis>. 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: + <itemizedlist> + <listitem> + <para> + <emphasis>Stable channels</emphasis>, such as + <literal + xlink:href="https://nixos.org/channels/nixos-19.03">nixos-19.03</literal>. + 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.<replaceable>x</replaceable> to 4.20.<replaceable>x</replaceable> (a + major change that has the potential to break things). Stable channels are + generally maintained until the next stable branch is created. + </para> + <para></para> + </listitem> + <listitem> + <para> + The <emphasis>unstable channel</emphasis>, + <literal + xlink:href="https://nixos.org/channels/nixos-unstable">nixos-unstable</literal>. + This corresponds to NixOS’s main development branch, and may thus see + radical changes between channel updates. It’s not recommended for + production systems. + </para> + </listitem> + <listitem> + <para> + <emphasis>Small channels</emphasis>, such as + <literal + xlink:href="https://nixos.org/channels/nixos-19.03-small">nixos-19.03-small</literal> + or + <literal + xlink:href="https://nixos.org/channels/nixos-unstable-small">nixos-unstable-small</literal>. + 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. + </para> + </listitem> + </itemizedlist> + To see what channels are available, go to + <link xlink:href="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 + <link xlink:href="https://nixos.org/nixos/download.html"/> to find the newest + supported stable release. + </para> + <para> + 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 19.03 ISO, you will be subscribed to the + <literal>nixos-19.03</literal> channel. To see which NixOS channel you’re + subscribed to, run the following as root: +<screen> +# nix-channel --list | grep nixos +nixos https://nixos.org/channels/nixos-unstable +</screen> + To switch to a different NixOS channel, do +<screen> +# nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos +</screen> + (Be sure to include the <literal>nixos</literal> parameter at the end.) For + instance, to use the NixOS 19.03 stable channel: +<screen> +# nix-channel --add https://nixos.org/channels/nixos-19.03 nixos +</screen> + If you have a server, you may want to use the “small” channel instead: +<screen> +# nix-channel --add https://nixos.org/channels/nixos-19.03-small nixos +</screen> + And if you want to live on the bleeding edge: +<screen> +# nix-channel --add https://nixos.org/channels/nixos-unstable nixos +</screen> + </para> + <para> + You can then upgrade NixOS to the latest version in your chosen channel by + running +<screen> +# nixos-rebuild switch --upgrade +</screen> + which is equivalent to the more verbose <literal>nix-channel --update nixos; + nixos-rebuild switch</literal>. + </para> + <note> + <para> + Channels are set per user. This means that running <literal> nix-channel + --add</literal> as a non root user (or without sudo) will not affect + configuration in <literal>/etc/nixos/configuration.nix</literal> + </para> + </note> + <warning> + <para> + 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. + </para> + </warning> + <section xml:id="sec-upgrading-automatic"> + <title>Automatic Upgrades</title> + + <para> + You can keep a NixOS system up-to-date automatically by adding the following + to <filename>configuration.nix</filename>: +<programlisting> +<xref linkend="opt-system.autoUpgrade.enable"/> = true; +</programlisting> + This enables a periodically executed systemd service named + <literal>nixos-upgrade.service</literal>. It runs <command>nixos-rebuild + switch --upgrade</command> to upgrade NixOS to the latest version in the + current channel. (To see when the service runs, see <command>systemctl + list-timers</command>.) You can also specify a channel explicitly, e.g. +<programlisting> +<xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-19.03; +</programlisting> + </para> + </section> +</chapter> |