diff options
author | Maximilian Bosch <maximilian@mbosch.me> | 2022-12-09 11:53:53 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-12-09 11:53:53 +0100 |
commit | 539954efab2b023064efd3edeb7912b71193acfd (patch) | |
tree | d0e23ad2bea527c38c5ed36a429b48b568f7f5ed | |
parent | a32b6064c49199c4d42c7a3241ee1a520a51fe19 (diff) | |
parent | 8476b02749ac97b49629745ded7b8b333c8d024a (diff) |
Merge pull request #204780 from Ma27/kernel-maintenance-docs
nixos/manual: document kernel backporting policy and implications of it
-rw-r--r-- | nixos/doc/manual/configuration/linux-kernel.chapter.md | 33 | ||||
-rw-r--r-- | nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml | 47 | ||||
-rw-r--r-- | nixos/modules/system/boot/kernel.nix | 5 |
3 files changed, 85 insertions, 0 deletions
diff --git a/nixos/doc/manual/configuration/linux-kernel.chapter.md b/nixos/doc/manual/configuration/linux-kernel.chapter.md index 1d06543d4f1e3..7b84416a86465 100644 --- a/nixos/doc/manual/configuration/linux-kernel.chapter.md +++ b/nixos/doc/manual/configuration/linux-kernel.chapter.md @@ -17,6 +17,16 @@ you may want to use one of the unversioned `pkgs.linuxPackages_*` aliases such as `pkgs.linuxPackages_latest`, that are kept up to date with new versions. +Please note that the current convention in NixOS is to only keep actively +maintained kernel versions on both unstable and the currently supported stable +release(s) of NixOS. This means that a non-longterm kernel will be removed after it's +abandoned by the kernel developers, even on stable NixOS versions. If you +pin your kernel onto a non-longterm version, expect your evaluation to fail as +soon as the version is out of maintenance. + +Longterm versions of kernels will be removed before the next stable NixOS that will +exceed the maintenance period of the kernel version. + The default Linux kernel configuration should be fine for most users. You can see the configuration of your current kernel with the following command: @@ -138,3 +148,26 @@ $ cd linux-* $ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules # insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko ``` + +## ZFS {#sec-linux-zfs} + +It's a common issue that the latest stable version of ZFS doesn't support the latest +available Linux kernel. It is recommended to use the latest available LTS that's compatible +with ZFS. Usually this is the default kernel provided by nixpkgs (i.e. `pkgs.linuxPackages`). + +Alternatively, it's possible to pin the system to the latest available kernel +version *that is supported by ZFS* like this: + +```nix +{ + boot.kernelPackages = pkgs.zfs.latestCompatibleLinuxPackages; +} +``` + +Please note that the version this attribute points to isn't monotonic because the latest kernel +version only refers to kernel versions supported by the Linux developers. In other words, +the latest kernel version that ZFS is compatible with may decrease over time. + +An example: the latest version ZFS is compatible with is 5.19 which is a non-longterm version. When 5.19 +is out of maintenance, the latest supported kernel version is 5.15 because it's longterm and the versions +5.16, 5.17 and 5.18 are already out of maintenance because they're non-longterm. diff --git a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml index a1d6815af29c1..dd570e1d66c27 100644 --- a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml +++ b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml @@ -22,6 +22,19 @@ boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10; date with new versions. </para> <para> + Please note that the current convention in NixOS is to only keep + actively maintained kernel versions on both unstable and the + currently supported stable release(s) of NixOS. This means that a + non-longterm kernel will be removed after it’s abandoned by the + kernel developers, even on stable NixOS versions. If you pin your + kernel onto a non-longterm version, expect your evaluation to fail + as soon as the version is out of maintenance. + </para> + <para> + Longterm versions of kernels will be removed before the next stable + NixOS that will exceed the maintenance period of the kernel version. + </para> + <para> The default Linux kernel configuration should be fine for most users. You can see the configuration of your current kernel with the following command: @@ -154,4 +167,38 @@ $ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox module # insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko </programlisting> </section> + <section xml:id="sec-linux-zfs"> + <title>ZFS</title> + <para> + It’s a common issue that the latest stable version of ZFS doesn’t + support the latest available Linux kernel. It is recommended to + use the latest available LTS that’s compatible with ZFS. Usually + this is the default kernel provided by nixpkgs (i.e. + <literal>pkgs.linuxPackages</literal>). + </para> + <para> + Alternatively, it’s possible to pin the system to the latest + available kernel version <emphasis>that is supported by + ZFS</emphasis> like this: + </para> + <programlisting language="bash"> +{ + boot.kernelPackages = pkgs.zfs.latestCompatibleLinuxPackages; +} +</programlisting> + <para> + Please note that the version this attribute points to isn’t + monotonic because the latest kernel version only refers to kernel + versions supported by the Linux developers. In other words, the + latest kernel version that ZFS is compatible with may decrease + over time. + </para> + <para> + An example: the latest version ZFS is compatible with is 5.19 + which is a non-longterm version. When 5.19 is out of maintenance, + the latest supported kernel version is 5.15 because it’s longterm + and the versions 5.16, 5.17 and 5.18 are already out of + maintenance because they’re non-longterm. + </para> + </section> </chapter> diff --git a/nixos/modules/system/boot/kernel.nix b/nixos/modules/system/boot/kernel.nix index 6783f8ec62ff9..b13e50cb17d2d 100644 --- a/nixos/modules/system/boot/kernel.nix +++ b/nixos/modules/system/boot/kernel.nix @@ -62,6 +62,11 @@ in configuration. For instance, if you use the NVIDIA X driver, then it also needs to contain an attribute {var}`nvidia_x11`. + + Please note that we strictly support kernel versions that are + maintained by the Linux developers only. More information on the + availability of kernel versions is documented + [in the Linux section of the manual](https://nixos.org/manual/nixos/unstable/index.html#sec-kernel-config). ''; }; |