pyrox.dev
1# Linux Kernel {#sec-kernel-config}
2
3You can override the Linux kernel and associated packages using the
4option `boot.kernelPackages`. For instance, this selects the Linux 3.10
5kernel:
6
7```nix
8boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10;
9```
10
11Note that this not only replaces the kernel, but also packages that are
12specific to the kernel version, such as the NVIDIA video drivers. This
13ensures that driver packages are consistent with the kernel.
14
15While `pkgs.linuxKernel.packages` contains all available kernel packages,
16you may want to use one of the unversioned `pkgs.linuxPackages_*` aliases
17such as `pkgs.linuxPackages_latest`, that are kept up to date with new
18versions.
19
20Please note that the current convention in NixOS is to only keep actively
21maintained kernel versions on both unstable and the currently supported stable
22release(s) of NixOS. This means that a non-longterm kernel will be removed after it's
23abandoned by the kernel developers, even on stable NixOS versions. If you
24pin your kernel onto a non-longterm version, expect your evaluation to fail as
25soon as the version is out of maintenance.
26
27Longterm versions of kernels will be removed before the next stable NixOS that will
28exceed the maintenance period of the kernel version.
29
30The default Linux kernel configuration should be fine for most users.
31You can see the configuration of your current kernel with the following
32command:
33
34```ShellSession
35zcat /proc/config.gz
36```
37
38If you want to change the kernel configuration, you can use the
39`packageOverrides` feature (see [](#sec-customising-packages)). For
40instance, to enable support for the kernel debugger KGDB:
41
42```nix
43nixpkgs.config.packageOverrides = pkgs: pkgs.lib.recursiveUpdate pkgs {
44 linuxKernel.kernels.linux_5_10 = pkgs.linuxKernel.kernels.linux_5_10.override {
45 extraConfig = ''
46 KGDB y
47 '';
48 };
49};
50```
51
52`extraConfig` takes a list of Linux kernel configuration options, one
53per line. The name of the option should not include the prefix
54`CONFIG_`. The option value is typically `y`, `n` or `m` (to build
55something as a kernel module).
56
57Kernel modules for hardware devices are generally loaded automatically
58by `udev`. You can force a module to be loaded via
59[](#opt-boot.kernelModules), e.g.
60
61```nix
62boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
63```
64
65If the module is required early during the boot (e.g. to mount the root
66file system), you can use [](#opt-boot.initrd.kernelModules):
67
68```nix
69boot.initrd.kernelModules = [ "cifs" ];
70```
71
72This causes the specified modules and their dependencies to be added to
73the initial ramdisk.
74
75Kernel runtime parameters can be set through
76[](#opt-boot.kernel.sysctl), e.g.
77
78```nix
79boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
80```
81
82sets the kernel's TCP keepalive time to 120 seconds. To see the
83available parameters, run `sysctl -a`.
84
85## Building a custom kernel {#sec-linux-config-customizing}
86
87You can customize the default kernel configuration by overriding the arguments for your kernel package:
88
89```nix
90pkgs.linux_latest.override {
91 ignoreConfigErrors = true;
92 autoModules = false;
93 kernelPreferBuiltin = true;
94 extraStructuredConfig = with lib.kernel; {
95 DEBUG_KERNEL = yes;
96 FRAME_POINTER = yes;
97 KGDB = yes;
98 KGDB_SERIAL_CONSOLE = yes;
99 DEBUG_INFO = yes;
100 };
101}
102```
103
104See `pkgs/os-specific/linux/kernel/generic.nix` for details on how these arguments
105affect the generated configuration. You can also build a custom version of Linux by calling
106`pkgs.buildLinux` directly, which requires the `src` and `version` arguments to be specified.
107
108To use your custom kernel package in your NixOS configuration, set
109
110```nix
111boot.kernelPackages = pkgs.linuxPackagesFor yourCustomKernel;
112```
113
114Note that this method will use the common configuration defined in `pkgs/os-specific/linux/kernel/common-config.nix`,
115which is suitable for a NixOS system.
116
117If you already have a generated configuration file, you can build a kernel that uses it with `pkgs.linuxManualConfig`:
118
119```nix
120let
121 baseKernel = pkgs.linux_latest;
122in pkgs.linuxManualConfig {
123 inherit (baseKernel) src modDirVersion;
124 version = "${baseKernel.version}-custom";
125 configfile = ./my_kernel_config;
126 allowImportFromDerivation = true;
127}
128```
129
130::: {.note}
131The build will fail if `modDirVersion` does not match the source's `kernel.release` file,
132so `modDirVersion` should remain tied to `src`.
133:::
134
135To edit the `.config` file for Linux X.Y, proceed as follows:
136
137```ShellSession
138$ nix-shell '<nixpkgs>' -A linuxKernel.kernels.linux_X_Y.configEnv
139$ unpackPhase
140$ cd linux-*
141$ make nconfig
142```
143
144## Developing kernel modules {#sec-linux-config-developing-modules}
145
146When developing kernel modules it's often convenient to run
147edit-compile-run loop as quickly as possible. See below snippet as an
148example of developing `mellanox` drivers.
149
150```ShellSession
151$ nix-build '<nixpkgs>' -A linuxPackages.kernel.dev
152$ nix-shell '<nixpkgs>' -A linuxPackages.kernel
153$ unpackPhase
154$ cd linux-*
155$ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
156# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
157```
158
159## ZFS {#sec-linux-zfs}
160
161It's a common issue that the latest stable version of ZFS doesn't support the latest
162available Linux kernel. It is recommended to use the latest available LTS that's compatible
163with ZFS. Usually this is the default kernel provided by nixpkgs (i.e. `pkgs.linuxPackages`).
164
165Alternatively, it's possible to pin the system to the latest available kernel
166version *that is supported by ZFS* like this:
167
168```nix
169{
170 boot.kernelPackages = pkgs.zfs.latestCompatibleLinuxPackages;
171}
172```
173
174Please note that the version this attribute points to isn't monotonic because the latest kernel
175version only refers to kernel versions supported by the Linux developers. In other words,
176the latest kernel version that ZFS is compatible with may decrease over time.
177
178An example: the latest version ZFS is compatible with is 5.19 which is a non-longterm version. When 5.19
179is out of maintenance, the latest supported kernel version is 5.15 because it's longterm and the versions
1805.16, 5.17 and 5.18 are already out of maintenance because they're non-longterm.