Unverified Commit 539954ef authored by Maximilian Bosch's avatar Maximilian Bosch Committed by GitHub
Browse files

Merge pull request #204780 from Ma27/kernel-maintenance-docs 

nixos/manual: document kernel backporting policy and implications of it
parents a32b6064 8476b027

nixos/doc/manual/configuration/linux-kernel.chapter.md

+33 −0
Original line number Diff line number Diff line
@@ -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.

nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml

+47 −0
Original line number Diff line number Diff line
@@ -21,6 +21,19 @@ boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10; 
    <literal>pkgs.linuxPackages_latest</literal>, that are kept up to

    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
@@ -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>

nixos/modules/system/boot/kernel.nix

+5 −0
Original line number Diff line number Diff line
@@ -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).

      '';

    };