summary refs log tree commit diff
path: root/nixos/doc/manual/installation/upgrading.chapter.md
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/installation/upgrading.chapter.md')
-rw-r--r--nixos/doc/manual/installation/upgrading.chapter.md118
1 files changed, 118 insertions, 0 deletions
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;
+```