Safely Maintain Linux's Default Kernel Symlinks

linux-update-symlinks maintains the vmlinuz and initrd links your bootloader reads, and this guide shows how to check and call it safely. You will learn what it needs from a kernel package workflow. The command is part of linux-base, version 4.5ubuntu9+24.04.2 on the machine used for this guide.

Allow about fifteen minutes. You need a shell and access to the host's kernel files. Reading the current links is normally unprivileged. Running an update usually needs root because the default links commonly live below / or /boot. This command is intended for kernel package maintainer scripts, so treat a hand-run update as a maintenance operation, not as a casual shortcut.

1. Confirm the installed command

Start with a read-only check. It does not change links and does not need elevated privileges:

$ command -v linux-update-symlinks
/usr/bin/linux-update-symlinks
$ dpkg-query -W -f='${Package} ${Version}\n' linux-base
linux-base 4.5ubuntu9+24.04.2
$ linux-update-symlinks --help
Usage: /usr/bin/linux-update-symlinks {install|upgrade|remove} VERSION IMAGE-PATH

The accepted actions are install, upgrade and remove. The program prints usage and exits with an error if the arguments do not match that shape. The installed help also confirms that the version must match the value shown by uname -r and used in kernel filenames.

Checkpoint: If the package is missing or the command is not at the expected path, stop here. Do not copy a script from another host into a package-maintained directory.

2. Inspect the current defaults

The command maintains a primary and secondary kernel link. Depending on architecture, the kernel link is named vmlinuz or vmlinux. The corresponding secondary link has .old appended. Initramfs links are initrd.img and initrd.img.old.

Inspect both the links and their resolved targets before changing anything:

$ ls -l /vmlinuz /vmlinuz.old /vmlinux /vmlinux.old /initrd.img /initrd.img.old 2>/dev/null
$ readlink -f /vmlinuz 2>/dev/null
$ readlink -f /initrd.img 2>/dev/null

Some of those paths may not exist, and that is expected. Use the names that your system actually has. The targets are normally versioned files such as /boot/vmlinuz-VERSION and /boot/initrd.img-VERSION; do not assume that a broken link identifies an installed kernel.

Configuration can move the links. The default destination is the root directory, while image_dest in /etc/kernel-img.conf selects another directory. link_in_boot requests /boot, and the no_symlinks setting can disable maintenance when configured with the disabling value described by the installed manual. Check the file before diagnosing an apparently missing link:

$ if test -r /etc/kernel-img.conf; then
>     sed -n '1,160p' /etc/kernel-img.conf
> else
>     echo '/etc/kernel-img.conf is absent'
> fi

3. Understand the three actions

install gives the supplied version highest priority. Use it when a fresh kernel image is being installed. upgrade replaces the supplied version's existing entry and keeps the version ordering and current defaults in the package workflow. remove excludes the supplied version, then selects the remaining images.

All three actions receive an absolute image path. A version string alone is not enough:

$ uname -r
CURRENT_VERSION='replace-with-the-version-being-managed'
IMAGE_PATH='/boot/vmlinuz-replace-with-the-version-being-managed'

The assignment example is deliberately a placeholder, not a command to run unchanged. Replace both values with the version and absolute image path supplied by the kernel package operation. Check the path first:

$ test -f "$IMAGE_PATH" && echo "kernel image exists"
kernel image exists

For an installation or upgrade, the command assumes an initramfs for that version unless the environment variable INITRD is exactly No. Set that only when the kernel operation genuinely has no initramfs:

# privileged package-maintenance example, review the values first
$ sudo env INITRD=No linux-update-symlinks upgrade "$CURRENT_VERSION" "$IMAGE_PATH"

Do not use INITRD=No merely because initrd.img-VERSION does not exist yet. The package workflow may create it later, and the command's documented assumption is what keeps the default initramfs link consistent.

4. Run a change only with a recovery plan

Warning: There is no dry-run option in the command's interface. A successful call changes symlinks; removing the last recognised kernel removes the default links. Record the current link targets and make sure the kernel you intend to keep is bootable before using sudo.

A package script normally supplies the action and values. If you must reproduce that operation manually, use explicit shell variables and review the expanded command:

$ VERSION='6.8.0-example'
$ IMAGE_PATH='/boot/vmlinuz-6.8.0-example'
$ printf 'action=%s version=%s image=%s\n' upgrade "$VERSION" "$IMAGE_PATH"
action=upgrade version=6.8.0-example image=/boot/vmlinuz-6.8.0-example
$ sudo linux-update-symlinks upgrade "$VERSION" "$IMAGE_PATH"

The command reports changed links with messages such as I: ... is now a symlink to .... Exact relative targets and paths depend on the destination directory. Verify after the command rather than trusting the message alone:

$ ls -l /vmlinuz /vmlinuz.old /initrd.img /initrd.img.old 2>/dev/null
$ readlink -f /vmlinuz
$ readlink -f /vmlinuz.old

If the result is wrong, stop using the affected host until the package state is understood. The recovery is to rerun the appropriate package action with the correct version and absolute image path, or reinstall the relevant kernel package through the normal package manager. Do not replace links by hand while guessing which kernel should be primary.

5. Diagnose the common traps

Done means