nixpkgs/nixos/doc/manual/installation/upgrading.xml
Jan Tojnar e6ce041cae
nixos/doc: Improve code listings
By adding prompts and replaceables and removing unnecessary indentation.
2020-09-23 01:25:25 +02:00

140 lines
6.1 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<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 NixOSs 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-20.03">nixos-20.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 NixOSs main development branch, and may thus see
radical changes between channel updates. Its not recommended for
production systems.
</para>
</listitem>
<listitem>
<para>
<emphasis>Small channels</emphasis>, such as
<literal
xlink:href="https://nixos.org/channels/nixos-20.03-small">nixos-20.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 NixOSs source tree), but may require
more packages to be built from source than usual. Theyre 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 channels 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, youre automatically subscribed to the NixOS
channel that corresponds to your installation source. For instance, if you
installed from a 20.03 ISO, you will be subscribed to the
<literal>nixos-20.03</literal> channel. To see which NixOS channel youre
subscribed to, run the following as root:
<screen>
<prompt># </prompt>nix-channel --list | grep nixos
nixos https://nixos.org/channels/nixos-unstable
</screen>
To switch to a different NixOS channel, do
<screen>
<prompt># </prompt>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 20.03 stable channel:
<screen>
<prompt># </prompt>nix-channel --add https://nixos.org/channels/nixos-20.03 nixos
</screen>
If you have a server, you may want to use the “small” channel instead:
<screen>
<prompt># </prompt>nix-channel --add https://nixos.org/channels/nixos-20.03-small nixos
</screen>
And if you want to live on the bleeding edge:
<screen>
<prompt># </prompt>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>
<prompt># </prompt>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 Nixs 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;
<xref linkend="opt-system.autoUpgrade.allowReboot"/> = true;
</programlisting>
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 <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>.)
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.
<programlisting>
<xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-20.03;
</programlisting>
</para>
</section>
</chapter>