diff options
Diffstat (limited to 'nixos/doc/manual/from_md/installation/upgrading.chapter.xml')
| -rw-r--r-- | nixos/doc/manual/from_md/installation/upgrading.chapter.xml | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/installation/upgrading.chapter.xml b/nixos/doc/manual/from_md/installation/upgrading.chapter.xml new file mode 100644 index 00000000000..e3b77d4c365 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/upgrading.chapter.xml @@ -0,0 +1,152 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis>Stable channels</emphasis>, such as + <link xlink:href="https://nixos.org/channels/nixos-21.11"><literal>nixos-21.11</literal></link>. + 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. + </para> + </listitem> + <listitem> + <para> + The <emphasis>unstable channel</emphasis>, + <link xlink:href="https://nixos.org/channels/nixos-unstable"><literal>nixos-unstable</literal></link>. + 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 + <link xlink:href="https://nixos.org/channels/nixos-21.11-small"><literal>nixos-21.11-small</literal></link> + or + <link xlink:href="https://nixos.org/channels/nixos-unstable-small"><literal>nixos-unstable-small</literal></link>. + 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> + <para> + To see what channels are available, go to + <link xlink:href="https://nixos.org/channels">https://nixos.org/channels</link>. + (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">https://nixos.org/nixos/download.html</link> + 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 21.11 ISO, you will be subscribed + to the <literal>nixos-21.11</literal> channel. To see which NixOS + channel you’re subscribed to, run the following as root: + </para> + <programlisting> +# nix-channel --list | grep nixos +nixos https://nixos.org/channels/nixos-unstable +</programlisting> + <para> + To switch to a different NixOS channel, do + </para> + <programlisting> +# nix-channel --add https://nixos.org/channels/channel-name nixos +</programlisting> + <para> + (Be sure to include the <literal>nixos</literal> parameter at the + end.) For instance, to use the NixOS 21.11 stable channel: + </para> + <programlisting> +# nix-channel --add https://nixos.org/channels/nixos-21.11 nixos +</programlisting> + <para> + If you have a server, you may want to use the <quote>small</quote> + channel instead: + </para> + <programlisting> +# nix-channel --add https://nixos.org/channels/nixos-21.11-small nixos +</programlisting> + <para> + And if you want to live on the bleeding edge: + </para> + <programlisting> +# nix-channel --add https://nixos.org/channels/nixos-unstable nixos +</programlisting> + <para> + You can then upgrade NixOS to the latest version in your chosen + channel by running + </para> + <programlisting> +# nixos-rebuild switch --upgrade +</programlisting> + <para> + 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 <literal>configuration.nix</literal>: + </para> + <programlisting language="bash"> +system.autoUpgrade.enable = true; +system.autoUpgrade.allowReboot = true; +</programlisting> + <para> + This enables a periodically executed systemd service named + <literal>nixos-upgrade.service</literal>. If the + <literal>allowReboot</literal> option is <literal>false</literal>, + it runs <literal>nixos-rebuild switch --upgrade</literal> to + upgrade NixOS to the latest version in the current channel. (To + see when the service runs, see + <literal>systemctl list-timers</literal>.) If + <literal>allowReboot</literal> is <literal>true</literal>, 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. + </para> + <programlisting language="bash"> +system.autoUpgrade.channel = https://nixos.org/channels/nixos-21.11; +</programlisting> + </section> +</chapter> |