Kernel/Upgrade

This article Article description::describes the steps to upgrade to a newer version of the Linux [[kernel.]]

Making a new kernel from the new sources is basically the same process as making a kernel when installing the system. The only difference is that one can save time by adjusting the old kernel configuration for the changes made in the new kernel instead of going through all the kernel options (like ) again.

A new kernel may have had options or features added or removed since the old kernel. Hence the configuration file of the new kernel may have new entries the configuration file of the old kernel doesn't have, and it might not have entries which are present in the configuration file of the old kernel anymore.

This article is a guide on how to deal with such changes of the configuration file by converting the old configuration to a configuration that can be used with the new kernel.

Kernel upgrade in Gentoo involves these steps:
 * Step 1: Emerging the new kernel sources.
 * Step 2: Setting the right symlink to the new kernel.
 * Step 3: Moving to the new kernel's folder.
 * Step 4: Adjusting the file for the options introduced to, or removed from the new kernel's configuration.
 * Step 5: Building the kernel and the initramfs.
 * Step 6: Updating the bootloader.
 * Step 7: Removing or keeping the old kernel.

Emerging the new kernel sources
A kernel upgrade may be a good idea when new kernel sources are installed. New kernel sources are sometimes installed while updating the system by running the following command:

Of course, they can be installed directly using the next command (replace gentoo-sources with whatever version of the kernel that is in-use):

Installing new kernel sources does not provide the user with a new kernel. It is necessary to build and install a new kernel from the new sources and then reboot the system to actually run the new kernel.

Set symlink to new kernel sources
The kernel configuration is saved in a file named in the directory that holds the kernel sources, a symlink is used to point to that directory.

The symlink should always point to the directory that holds the sources of the kernel which currently runs. This can be done in one of three ways:


 * 1) Default: Setting the link with eselect.
 * 2) Alternative 1: Manually updating the symbolic link.
 * 3) Alternative 2: Installing the kernel sources with.

Default: Setting the link with eselect
To set the symlink with :

This outputs the available kernel sources. The asterisk indicates the chosen sources.

To change the kernel sources, e.g. to the second entry, do:

Alternative 1: Manually updating the symbolic link
To set the symbolic link manually:

Alternative 2: Installing the kernel sources with the symlink USE flag
This will make the point to the newly installed kernel sources.

If necessary, it can still be modified later with one of the other two methods.

Moving to the new kernel folder
Now that the symbolic link has been modified, change the working directory to the new kernel folder.

Copy the previous kernel configuration
The configuration of the old kernel needs to be copied to the new one. The old configuration can be found in several places:


 * In the procfs filesystem, if the kernel option Enable access to .config through /proc/config.gz (CONFIG_IKCONFIG_PROC) was activated in the present kernel:


 * From the old kernel. This will only work when the old kernel was compiled with CONFIG_IKCONFIG:


 * In the directory, if the configuration was installed there:


 * In the kernel directory of the currently-running kernel:


 * In the directory, if   is set in  and  was previously used:

Update the .config file
A new kernel usually requires a new .config file to support new kernel features. The .config from the old kernel can be converted to be used with the new kernel. The conversion can be done several ways including running either or.

make oldconfig
The following configuration is like the text based configuration with. For new configuration options, the user is asked for a decision. For example:

The string (NEW) at the end of the line marks this option as new. Left to the string in square brackets are the possible answers: Yes, no, module or ? to show the help. The recommend (i.e. default) answer is capitalized (here Y). The help explains the option or driver.

Unfortunately doesn't show a lot more information for each option, such as the context, so it is sometimes difficult to give the right answer. In this case the best way to go is to remember the option name and revise it afterwards through one of the graphical kernel configuration tools. For listing new options and doing research about them, can be used before running.

make olddefconfig
Running will keep all of the options from the old  and set the new options to their recommended (i.e. default) values:

make help
Use to see other conversion methods available:

Observing the difference
A diff tool can be used to compare the old and new files to see what options have been added:

And which have been removed:

Alternatively, the kernel provides a script to cleanly compare two config files even if the options have moved in the file itself:

make menuconfig
The options can then be researched and changed if necessary by running:

The menuconfig target is helpful because it safely handles kernel symbol dependency resolution.

Build
For this step, follow the steps in the manual configuration article.

Automated build and installation
It is possible to automatically build and install the newly emerged kernel using Portage hooks. While other approaches are also possible, the following is based on genkernel and gentoo-sources package. It requires the following prerequisites:


 * 1)  is able to build and install the kernel to which the  symlink points into   and the bootloader.
 * 2) The   use flag is set for the kernel ebuild.

If those are fulfilled, simply install a  Portage hook as shown below.

Reinstalling external kernel modules
Any external kernel modules, such as binary kernel modules, need to be rebuilt for each new kernel. If the kernel has not been built yet, it has to first be prepared for the building of the external kernel modules:

Packages containing kernel modules can be rebuilt using the  set:

Solving build problems
When experiencing build problems while rebuilding the current kernel, it might help to sanitize the kernel sources. Make sure to backup the file first, as the operation will remove it. Make sure not to use a or  suffix as backup as  will clean those up as well.

Update the bootloader
The upgraded and built kernel needs to be set up and eventually a bootloader or boot item updated, see Kernel/Configuration. Users of Grub can use the method below, users of other bootloaders must consult the handbook.

After making sure partition is mounted,

Using grub-mkconfig
The following command can be executed for updating grub's configuration file:

Using systemd-boot-gen to update systemd-boot UEFI configuration
Manual installation of :

Copy the kernel parameters to, the file should contain:

And run it using root privileges:

This will generate the boot configuration in for all the available  that have a matching.

Keeping the old kernel sources
Kernel sources will eventually become unsupported. Some packages require the current sources to build. To protect the new sources from being removed by a depclean, it can be added to the world file (/var/lib/portage/world) by:

Old sources that are no longer supported can be removed from the world file by:

Removing the old kernel
See the kernel removal article.

External resources

 * kernel changelog with some explanations of new features