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

   1 # Linux Kernel {#sec-kernel-config}
   2
   3 You can override the Linux kernel and associated packages using the
   4 option `boot.kernelPackages`. For instance, this selects the Linux 3.10
   5 kernel:
   6
   7 ```nix
   8 {
   9   boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10;
  10 }
  11 ```
  12
  13 Note that this not only replaces the kernel, but also packages that are
  14 specific to the kernel version, such as the NVIDIA video drivers. This
  15 ensures that driver packages are consistent with the kernel.
  16
  17 While `pkgs.linuxKernel.packages` contains all available kernel packages,
  18 you may want to use one of the unversioned `pkgs.linuxPackages_*` aliases
  19 such as `pkgs.linuxPackages_latest`, that are kept up to date with new
  20 versions.
  21
  22 Please note that the current convention in NixOS is to only keep actively
  23 maintained kernel versions on both unstable and the currently supported stable
  24 release(s) of NixOS. This means that a non-longterm kernel will be removed after it's
  25 abandoned by the kernel developers, even on stable NixOS versions. If you
  26 pin your kernel onto a non-longterm version, expect your evaluation to fail as
  27 soon as the version is out of maintenance.
  28
  29 Longterm versions of kernels will be removed before the next stable NixOS that will
  30 exceed the maintenance period of the kernel version.
  31
  32 The default Linux kernel configuration should be fine for most users.
  33 You can see the configuration of your current kernel with the following
  34 command:
  35
  36 ```ShellSession
  37 zcat /proc/config.gz
  38 ```
  39
  40 If you want to change the kernel configuration, you can use the
  41 `packageOverrides` feature (see [](#sec-customising-packages)). For
  42 instance, to enable support for the kernel debugger KGDB:
  43
  44 ```nix
  45 {
  46   nixpkgs.config.packageOverrides = pkgs: pkgs.lib.recursiveUpdate pkgs {
  47     linuxKernel.kernels.linux_5_10 = pkgs.linuxKernel.kernels.linux_5_10.override {
  48       extraConfig = ''
  49         KGDB y
  50       '';
  51     };
  52   };
  53 }
  54 ```
  55
  56 `extraConfig` takes a list of Linux kernel configuration options, one
  57 per line. The name of the option should not include the prefix
  58 `CONFIG_`. The option value is typically `y`, `n` or `m` (to build
  59 something as a kernel module).
  60
  61 Kernel modules for hardware devices are generally loaded automatically
  62 by `udev`. You can force a module to be loaded via
  63 [](#opt-boot.kernelModules), e.g.
  64
  65 ```nix
  66 {
  67   boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
  68 }
  69 ```
  70
  71 If the module is required early during the boot (e.g. to mount the root
  72 file system), you can use [](#opt-boot.initrd.kernelModules):
  73
  74 ```nix
  75 {
  76   boot.initrd.kernelModules = [ "cifs" ];
  77 }
  78 ```
  79
  80 This causes the specified modules and their dependencies to be added to
  81 the initial ramdisk.
  82
  83 Kernel runtime parameters can be set through
  84 [](#opt-boot.kernel.sysctl), e.g.
  85
  86 ```nix
  87 {
  88   boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
  89 }
  90 ```
  91
  92 sets the kernel's TCP keepalive time to 120 seconds. To see the
  93 available parameters, run `sysctl -a`.
  94
  95 ## Building a custom kernel {#sec-linux-config-customizing}
  96
  97 Please refer to the Nixpkgs manual for the various ways of [building a custom kernel](https://nixos.org/nixpkgs/manual#sec-linux-kernel).
  98
  99 To use your custom kernel package in your NixOS configuration, set
 100
 101 ```nix
 102 {
 103   boot.kernelPackages = pkgs.linuxPackagesFor yourCustomKernel;
 104 }
 105 ```
 106
 107 ## Rust {#sec-linux-rust}
 108
 109 The Linux kernel does not have Rust language support enabled by
 110 default. For kernel versions 6.7 or newer, experimental Rust support
 111 can be enabled. In a NixOS configuration, set:
 112
 113 ```nix
 114 {
 115   boot.kernelPatches = [
 116     {
 117       name = "Rust Support";
 118       patch = null;
 119       features = {
 120         rust = true;
 121       };
 122     }
 123   ];
 124 }
 125 ```
 126
 127 ## Developing kernel modules {#sec-linux-config-developing-modules}
 128
 129 This section was moved to the [Nixpkgs manual](https://nixos.org/nixpkgs/manual#sec-linux-kernel-developing-modules).
 130
 131 ## ZFS {#sec-linux-zfs}
 132
 133 It's a common issue that the latest stable version of ZFS doesn't support the latest
 134 available Linux kernel. It is recommended to use the latest available LTS that's compatible
 135 with ZFS. Usually this is the default kernel provided by nixpkgs (i.e. `pkgs.linuxPackages`).