diff --git a/nixos/doc/manual/configuration/linux-kernel.chapter.md b/nixos/doc/manual/configuration/linux-kernel.chapter.md
index 1d06543d4f1e..7b84416a8646 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 a1d6815af29c..dd570e1d66c2 100644
--- a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
+++ b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
@@ -21,6 +21,19 @@ boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10;
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
@@ -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
+
+ 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:
+
+
+{
+ 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/modules/system/boot/kernel.nix b/nixos/modules/system/boot/kernel.nix
index 6783f8ec62ff..b13e50cb17d2 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).
'';
};