LIVE-KERNEL-UPDATER(1)

NAME
live-kernel-updater - update the kernel on a live-usb

SYNOPSIS
live-kernel-updater [options]

DESCRIPTION
live-kernel-updater updates the live kernels on a live-usb system. It can add new live kernels, update or remove existing ones. For a kernel to be live-bootable it must be present in the squashfs (linuxfs) image.

The tool supports two methods of booting a live system:

Shared-initrd mode
    The kernel modules of all live kernels are stored together in one shared initramfs (initrd.gz). Two live kernels are supported: vmlinuz and vmlinuz1, sharing one initrd.gz.

Multi-kernel mode
    Each live kernel vmlinuzN has its own initramfs initrdN.gz. Up to ten live kernels are supported (vmlinuz through vmlinuz9).

The tool writes a small vmlinuzN.ver version file alongside each live kernel for use by GRUB menu entries. Microcode (AMD and Intel) is automatically added into the initrd via uc-tool when available.

BASIC OPERATION
When options do not fully specify what to do, menus are presented at each step.

Select the system to update
    If running from a live-usb the current system is offered first. Any other plugged-in USB devices that contain a live system are also listed. A directory path may be given directly via --device to skip this menu.

Select an action to perform
    Available actions depend on the mode and the state of the live system.

In multi-kernel mode:

    •   Update vmlinuzN from ... – replace vmlinuzN with another kernel. When a kernel not yet assigned to any vmlinuzN is available it appears as a plain update; otherwise it appears as (reassign), allowing any installed kernel to be selected.

    •   Add new kernel to vmlinuzN – install a kernel into the next free vmlinuzN

    •   Remove kernel vmlinuzN – remove vmlinuzN and its initrd from the live-usb, taking it out of the GRUB boot menu

In shared-initrd mode:

    •   Update vmlinuz from ... and Update vmlinuz1 from ... – replace the kernel in vmlinuz or vmlinuz1 with another installed kernel. Only kernels not already assigned to either vmlinuz or vmlinuz1 are offered.

    •   Rollback vmlinuz and Rollback vmlinuz1 – revert to the previous kernel (only shown after an update has been done)

    •   Update initrd – recreate the initrd from scratch using the template initrd, without changing the kernel. Useful to pick up initrd changes independently of a kernel update.

The currently running live kernel is marked with * in the menu. vmlinuzN kernels that were uninstalled under root persistence and may not boot are marked with ?.

Select new kernel
    When an update or add action is chosen and more than one kernel is available, a list is presented. The kernel being replaced is marked with *. When adding a new vmlinuzN on a running live system, the currently running kernel is marked with *.

OPTIONS

-C, --color=scheme
    Set the color scheme. Valid values: off, low, low1, bw, dark, high.

-d, --device=device
    The live-usb device to update. Use live to explicitly target the running live system. A block device path (e.g. /dev/sdb1) causes the tool to mount and update that device. A directory path (e.g. /mnt/usb) is used directly as the live mount point without mounting.

-e, --encrypt
    Force cryptsetup to be copied into the initrd regardless of whether the boot environment uses disk encryption. Useful for testing on non-encrypted live systems.

-F, --force=list
    Force one or more comma-separated options:

    flock
        ignore a missing flock program

    usb allow updating non-USB devices (dangerous)

    clear
        remove the previous initrd working directory before unpacking

-G, --graphic-ui
    Use the interactive terminal menu interface with keyboard navigation. This is the default.

-h, --help
    Show usage summary and exit.

-i, --initrd
    Only rebuild the initrd from the default template; do not change the kernel. Uses /usr/lib/iso-template/template-initrd.gz or /usr/local/lib/iso-template/template-initrd.gz. Shared-initrd mode only; not supported in multi-kernel mode.

--initrd=file
    In shared-initrd mode: rebuild the initrd using file as the template instead of the default; do not change the kernel. In multi-kernel mode: use file as the template initrd for the selected vmlinuzN slot instead of the default template. The normal slot-selection menu is shown; kernel modules for the chosen kernel are installed into the per-slot initrdN.gz as usual. Any modules already present in file are removed before the new kernel modules are added, so any existing initrd or backup copy can be used as the template.

-I, --ignore-config
    Do not read the configuration file.

-k, --kernel=version
    Select the new kernel by version string (as reported by uname -r). Skips the kernel selection menu. Shared-initrd mode only; not supported in multi-kernel mode.

-K, --keep-old
    Keep the old kernel module directory inside the initrd instead of removing it. Shared-initrd mode only.

--live-dir=dir
    Specify the subdirectory within the live-usb that holds the boot files (e.g. antiX or antiXFrugal). Skips the automatic search and any interactive prompt when multiple live directories are found.

-m, --modules=list
    Add the listed comma-separated kernel modules to the initrd. In shared-initrd mode the listed modules are added to the existing initrd.gz without rebuilding it from the template. In multi-kernel mode the listed modules are added in addition to the standard kernel modules during a normal vmlinuzN update.

--multi-kernel
    Force multi-kernel mode. Auto-detected as the default on MX Linux.

-N, --numeric-ui
    Use the legacy numbered-list menu interface instead of the interactive one.

-p, --pretend
    Dry-run mode. Show what would be done without writing any files.

-q, --quiet
    Print less output.

-R, --reset-config
    Write a configuration template with all entries commented out and exit. Useful as a starting point for customisation.

--shared-initrd
    Force shared-initrd mode. Used as the default when multi-kernel mode is not auto-detected.

-U, --no-ucode
    Skip microcode injection when repacking the initrd.

-v, --version
    Show version information and exit.

-V, --verbose
    Print more output, including the output of sub-commands.

-VV, --very-verbose
    Also print each command before it is run.

-W, --write-config
    Write a configuration template with all entries commented out and exit. Identical in effect to --reset-config.

FILES

/etc/live-kernel-updater/live-kernel-updater.conf
    Configuration file. Sourced as a shell snippet if present. Created automatically with defaults on first run. Use --reset-config or --write-config to write a fresh commented template.

/usr/lib/iso-template/template-initrd.gz
    Default initrd template used when rebuilding the initrd. Falls back to /usr/lib/iso-template/initrd.gz if not found. When targeting an external USB the template inside the squashfs image is preferred to ensure the correct distro version is used.

/etc/live/config/persist-root
    Flag file written by the live init when root persistence is active. Used by the tool to detect whether vmlinuzN kernels may be affected by packages uninstalled under persistence.

AUTHORS
Original man page by BitJam for antiX.
Rewritten for MX Linux by the MX development team.