tencent cloud

TencentOS Server

DocumentaçãoTencentOS ServerUser GuideKernel FeaturesKernel Version Management and Switching

Kernel Version Management and Switching

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-10-19 17:22:48
Traduzido por IA

Feature Overview

This document describes how to install, upgrade, downgrade, and switch kernels on TencentOS Server, covering both RPM packages and the dnf/yum package manager, helping you perform safe operations and retain rollback capabilities when kernel version changes are required.
Note:
The TencentOS Server kernel (TencentOS Kernel, TK) is distributed as RPM packages. You can upgrade to a newer version to obtain new features and fixes, or downgrade to an older version to avoid compatibility issues introduced by the new version. However, the kernel is a core system component, and improper operations may prevent the system from booting. It is recommended that you follow the principle of backing up first, testing before deployment, and retaining an older kernel for rollback.

Version Number Format Explanation

The kernel version number format of TencentOS Server is <base version>-<patch number>.tl<distribution identifier>.<architecture>, for example, 5.4.241-24.0017.14.tl3.x86_64.
Field
Description
Example
Base version
Major version
5.4.241
Patch number
Minor version iteration
24.0017.14
Distribution identifier
tl3/tl4
tl3(TencentOS Server 3)/tl4(TencentOS Server 4)
Architecture
CPU architecture identifier
x86_64,aarch64

Prerequisites

Before you start kernel version management operations, make sure the following conditions are met:
root/sudo privileges: All installation, upgrade, and downgrade operations in this document must be performed as the root user or with elevated privileges via sudo.
System version confirmation: Run cat /etc/rpm/macros.dist to confirm the distribution identifier (tl3 or tl4) and ensure that the downloaded kernel package suffix matches the system. Packages for tl3 and tl4 are not interchangeable.
grub.cfg backup: Before modifying the default boot kernel, make sure to back up the GRUB configuration so that you can roll back if needed.
The /boot partition must have sufficient space: at least 300 MB of free space is required. Insufficient space will cause the new kernel installation to fail. You can run df -h /boot to check the available space.
Network/RPM package preparation: For online upgrades, network access must be allowed. For offline installation, download the kernel RPM package of the corresponding version in advance and upload it to the OS.
Network configuration for online upgrade: Cloud servers can access TencentOS mirror sources over the private network by default. If a public network upgrade is required, confirm that the security group allows outbound access. You can run dnf repolist to verify source availability.
Offline installation file upload: After downloading the kernel RPM package locally, you can upload it to the target server by using an SCP/SFTP tool (for example, scp kernel-*.rpm root@<target IP>:/root/) or by logging in to the CVM console via VNC and transferring the file.
Test environment recommendation: Before the kernel is upgraded in a production environment, it is strongly recommended to first verify the compatibility and service availability of the new kernel in a test environment.
# Confirm current user privileges
whoami # Expected output: root

# Confirm the system distribution identifier (tl3 or tl4)
cat /etc/rpm/macros.dist 2>/dev/null || rpm --eval '%{dist}'
# Expected output: .tl3 or .tl4

# Confirm the /boot partition space (at least 300 MB)
df -h /boot
# Expected output: The Avail column is no less than 300M.

# Back up the GRUB configuration (perform this step before modifying the default boot kernel)
cp /boot/grub2/grub.cfg /boot/grub2/grub.cfg.bak.$(date +%Y%m%d)
Note: The kernel is the core component of TencentOS Server. Before performing related operations, note the following:
Before upgrading the kernel, make sure to back up important data. For production environments, verify the upgrade in a test environment before performing a full rollout.
Do not delete the currently running kernel (check it by running uname -r). Keep at least one backup kernel so that you can roll back if the system fails to boot.
Using --force --nodeps to force-install a downgraded kernel may cause dependency issues. Make sure you have a backup boot plan, such as a GRUB menu entry that can roll back to the old kernel.

Kernel Version Mapping

System Version
Kernel Series
Base Kernel Version
TencentOS Server 3
Linux 5.4 LTS
5.4.x
TencentOS Server 4
Linux 6.6 LTS
6.6.x

API and Parameter Description

Kernel Package Structure Description

Package name
Description
Applicable Versions
kernel-<version>
Main package
All versions
kernel-<version>-core
Core module package
All versions
kernel-<version>-modules
Driver module package
All versions

Kernel Package Installation Commands

Operation
Command
Description
Install (keep the old kernel).
rpm -ivh
Recommended method. You can roll back to the previous kernel from the GRUB menu.
Upgrade (replace the old kernel).
rpm -Uvh
Deletes the old kernel. Not recommended for production use.
Force install (downgrade).
rpm -ivh --force --nodeps
Used to roll back to an earlier version. May cause dependency issues.

Configuration Example

Viewing the Current Kernel Version

# View the running kernel version
uname -r
# Expected output example: 5.4.241-24.0017.14.tl3.x86_64

# View all installed kernels
rpm -qa | grep kernel | sort
# Expected output: List all installed kernel RPM packages

# View distribution information (determine whether it is .tl3 or .tl4)
cat /etc/rpm/macros.dist 2>/dev/null || rpm --eval '%{dist}'
# Expected output: %dist .tl3 or %dist .tl4 (tl4 can be replaced by rpm --eval)

Online Upgrade via dnf/yum (Recommended)

# View available kernel versions
dnf list kernel* --showduplicates | head -20
# Expected output: List all available kernel version packages

# Upgrade to the latest kernel
dnf update kernel -y
# Expected output: The installation/upgrade process is displayed, and "Complete!" is prompted at the end.

# Or install a specific version (replace <version_number> with the actual version)
dnf install kernel-<version_number> -y

# Restart after the upgrade is complete (a restart will cause service interruption, so make sure a maintenance window has been scheduled before proceeding)
reboot

Offline Installation via RPM Packages

Applicable to scenarios where the public network cannot be accessed or a specific version needs to be installed.
1. Confirm the target system version.
# View the distribution identifier (tl3 or tl4)
cat /etc/rpm/macros.dist 2>/dev/null | grep dist || rpm --eval '%{dist}'
# Expected output: %dist .tl3 or %dist .tl4 (tl4 can be replaced by rpm --eval)
Ensure that you download an RPM package whose suffix matches the target system, either .tl3 or .tl4.
2. Download the kernel RPM package (we recommend that you contact the corresponding business personnel to obtain it).
Multi-package structure: The kernel of TencentOS Server consists of three RPM packages: kernel-* (main package), kernel-*-core (core module package), and kernel-*-modules (driver module package). All three packages must be installed together. When you use dnf for installation, dependencies are handled automatically, so you do not need to specify the three packages manually.
3. Install the kernel.
All three packages must be installed together (missing any one will result in missing driver modules). Use -ivh to keep the old kernel or -Uvh to replace it:
# New installation (keeps the old kernel, recommended — allows rollback from the GRUB menu)
rpm -ivh kernel-5.4.241-24.0017.14.tl3.x86_64.rpm \\
kernel-core-5.4.241-24.0017.14.tl3.x86_64.rpm \\
kernel-modules-5.4.241-24.0017.14.tl3.x86_64.rpm
# Expected output: The three packages are installed one by one, and "##### [100%]" is displayed at the end.
4. Restart and verify.
# Restart the system (a restart will cause service interruption, so make sure a maintenance window has been scheduled before proceeding)
reboot

# Verify the kernel version after restart
uname -r
# Expected output: The newly installed kernel version is displayed, for example, 5.4.241-24.0017.14.tl3.x86_64.

Switching the Default Boot Kernel

When multiple kernels are installed on the system, you can use the grubby tool to set the default kernel version for GRUB boot.
1. View the current default boot kernel.
# View the current default kernel booted by GRUB
grubby --default-kernel
# Expected output: /boot/vmlinuz-5.4.241-24.0017.14.tl3.x86_64
2. View all installed kernels.
# List all installed kernel images
ls /boot/vmlinuz-*
# Expected output:
# /boot/vmlinuz-5.4.119-19.0009.13.tl3.x86_64
# /boot/vmlinuz-5.4.241-24.0017.14.tl3.x86_64

# Or view via rpm
rpm -qa | grep kernel | sort
3. Set the default boot kernel.
# Set the specified kernel as the default boot kernel (replace <kernel-path> with the actual kernel path)
grubby --set-default /boot/vmlinuz-<kernel-version>
# Example: grubby --set-default /boot/vmlinuz-5.4.241-24.0017.14.tl3.x86_64
# Expected output: The default is set to a nonzero entry. Success!
4. Restart and verify.
# Restart the system (a restart will cause service interruption, so make sure a maintenance window has been scheduled before proceeding)
reboot

# After restart, confirm that the currently running kernel is the default kernel you set
uname -r
# Expected output: 5.4.241-24.0017.14.tl3.x86_64 (consistent with the default kernel you set)

# Confirm the default boot kernel configuration again
grubby --default-kernel
# Expected output: /boot/vmlinuz-5.4.241-24.0017.14.tl3.x86_64

Installing an Older Kernel Version (Downgrade)

Downgrade Risk Warning
Force-downgrading the kernel may cause system dependency issues. Proceed with caution and make sure you have a backup boot plan, such as a GRUB menu entry that can roll back to the old kernel. Before downgrading in a production environment, always verify the operation in a test environment first.
# Attempting a regular installation of a lower kernel version will result in an error:
# "package xxx (which is newer than xxx) is already installed"
# Use --force --nodeps to force the installation
rpm -ivh --force --nodeps kernel-5.4.119-19.0009.13.tl3.x86_64.rpm
# Expected output: The installation progress is displayed, and "##### [100%]" is shown at the end.

Deleting Old Kernels

# View all installed kernels
rpm -qa | grep kernel | sort
# Expected output: List all installed kernel RPM packages

# Remove the specified old kernel (make sure not to remove the currently running kernel)
rpm -e kernel-5.4.119-19.0009.13.tl3.x86_64
# Expected output: A message indicating that the uninstallation is complete.

# Check /boot usage
df -h /boot
# Expected output: Available space has increased.

Verify

# 1. Confirm that the new kernel is running.
uname -r
# Expected output: 5.4.241-24.0017.14.tl3.x86_64 (consistent with the target installation version)

# 2. Confirm that the system starts up normally.
systemctl --failed
# Expected output: 0 loaded units listed (no failed services)

# 3. Confirm the kernel boot order.
grubby --default-kernel
# Expected output: /boot/vmlinuz-5.4.241-24.0017.14.tl3.x86_64

Summary of Expected Results

Operation Steps
Expected Output
Verification Method
Upgrade the kernel online
dnf update prompts Complete!
rpm -q kernel-$(uname -r)
Install the kernel offline
rpm -ivh prompts 100%.
ls /boot/vmlinuz-* lists the new kernel.
Set the default boot kernel
grubby prompts Success!
grubby --default-kernel displays the target kernel.
Downgrade installation
rpm -ivh --force prompts 100%.
uname -r displays the version after downgrade.
Remove the old kernel
rpm -e uninstallation completed.
rpm -qa | grep kernel no longer lists the kernel.

FAQs

Q1: The System Still Runs the Old Kernel After a New Kernel Is Installed and the System Is Rebooted

Cause: The GRUB default boot kernel is not pointed to the newly installed kernel.
Solution: Point the GRUB default boot kernel to the newly installed kernel, and then restart the system.
# 1. Confirm that the new kernel is installed.
rpm -qa | grep kernel | sort

# 2. View the current default boot kernel.
grubby --default-kernel

# 3. Set the new kernel as the default boot kernel.
grubby --set-default /boot/vmlinuz-<kernel-version>
# Example: grubby --set-default /boot/vmlinuz-5.4.241-24.0017.14.tl3.x86_64

# 4. Restart and verify (a restart will cause service interruption, so perform this operation within a maintenance window)
reboot
uname -r

Q2: "package xxx is already installed" Error When the Kernel Is Installed

Cause: A higher kernel version is already installed, and rpm -ivh does not allow the installation of a lower version. You need to carefully evaluate the risks before using a force command to install it.
Solution: After evaluating the risks, use a forced installation (downgrade) or the -U parameter to upgrade and replace the package.
# To install a lower version (downgrade), use --force --nodeps to force the installation.
rpm -ivh --force --nodeps kernel-<version>.tl3.x86_64.rpm

# To upgrade or replace with a higher version, use the -U parameter.
rpm -Uvh kernel-<version>.tl3.x86_64.rpm
Warning: Forceful installation with --force --nodeps may cause dependency conflicts or system instability. Ensure that a fallback boot option is available (for example, a rollback entry in the GRUB menu).

Q3: Missing Driver Modules and Abnormal System Functions After Installing a New Kernel

Cause: TencentOS Server uses a multi-package structure. If only the main package is installed without kernel-core and kernel-modules, abnormal errors will occur. For example, the NIC cannot be initialized (ip addr shows no network interface), storage drivers fail to load (disk devices cannot be identified), lsmod shows an incomplete module list, and driver loading error messages appear in dmesg.
Solution: Install the missing kernel-core and kernel-modules packages.
# Install all three packages (replace <version_number> with the actual version)
rpm -ivh kernel-<version>.tl3.x86_64.rpm \\
kernel-core-<version>.tl3.x86_64.rpm \\
kernel-modules-<version>.tl3.x86_64.rpm

# Or use dnf to handle dependencies automatically.
dnf install kernel-<version_number> -y

Q4: "/boot Insufficient Space" Error When the Kernel Is Installed

Cause: The available space in the /boot partition is less than 300 MB, which is insufficient to accommodate the new kernel image.
Solution: Clean up old kernels to free up space, and expand the partition containing /boot if necessary.
# 1. Check the available space in /boot.
df -h /boot

# 2. Clean up old kernels (keep the latest 2)
package-cleanup --oldkernels --count=2

# 3. Or manually remove unused old kernels (first confirm the currently running kernel)
uname -r # Record the current kernel. Do not delete it.
rpm -e kernel-<old_version>.tl3.x86_64

# 4. If space is still insufficient after cleanup, expand the partition containing /boot. Proceed with caution and back up data before the operation.
# On a CVM, /boot is typically located in the root partition. You can first expand the system disk in the console, and then extend the partition and file system:
growpart /dev/vda 1 # Expand the partition (assuming the root partition is /dev/vda1)
xfs_growfs / # Expand the file system (xfs). For ext4, use resize2fs /dev/vda1.

# 5. Reinstall the target kernel.
rpm -ivh kernel-<version>.tl3.x86_64.rpm

Q5: The System Fails to Boot After the Upgrade

Cause: The new kernel is incompatible with the hardware or drivers, or the GRUB configuration is abnormal.
Solution: Boot from an old kernel by selecting it in the GRUB menu, identify the cause of the failure, and then switch back.
1. During system startup, press Esc or Shift to enter the GRUB boot menu.
2. Select an old kernel to boot the system.
3. After logging in, view the logs from the last failed boot:
# View the logs from the last failed boot.
journalctl -b -1 | tail -50
# Expected output: A panic or driver loading failure message is displayed.

# Confirm the system startup status.
systemctl --failed
4. After troubleshooting, you can switch the default boot kernel back to the old version:
Replace <old_version> with the actual kernel version (which can be queried by running rpm -qa | grep kernel):
grubby --set-default /boot/vmlinuz-<old_version>


Ajuda e Suporte

Esta página foi útil?

comentários