Modify an existing image

Modify an existing image#

Files in the existing images can be replaced, by using the l4image tool.

We will show how this works by updating one the of the pre-built images running Linux with a new Linux kernel.

We will do this tutorial for Arm64 with QEMU. So we download the following image along with the l4image tool:

$ wget https://l4re.org/download/snapshots/pre-built-images/arm64/l4re_vm-basic_arm_virt.elf
$ wget https://l4re.org/download/snapshots/pre-built-images/l4image
$ chmod +x l4image

If you like to run it, just do it. It will spin up a Linux VM, and you can type something in the Linux shell.

$ ./l4image -i l4re_vm-basic_arm_virt.elf launch
...

[    4.121751] ALSA device list:
[    4.129502]   No soundcards found.
[    4.144839] uart-pl011 12000.pl011_uart: no DMA platform data
[    4.238744] Freeing unused kernel memory: 9152K
[    4.250614] Run /init as init process

Please press Enter to activate this console.
~ #
~ # uname
Linux
~ #

Updating the Linux kernel in the Image#

First, we need to get and compile a new Linux kernel. You can take any new Linux kernel, for example, go to https://www.kernel.org/ and pick the latest stable one.

And then build it:

$ wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.17.7.tar.xz
$ tar xf linux-6.17.7.tar.xz
$ cd linux-6.17.7
$ make -j$(nproc) ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- defconfig
$ make -j$(nproc) ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

Depending on your machine, compiling the Linux kernel can take a while.

When done, the built kernel should be in arch/arm64/boot:

$ ls -la arch/arm64/boot/Image
arch/arm64/boot/Image
$ cd ..

Now, let’s put the new kernel into the image we previously downloaded. First, let us check what is in the image, by using the list command:

$ ./l4image -i l4re_vm-basic_arm_virt.elf  list -v
T Num     Size Filename
B              bootstrap -modaddr=0x01100000
K   0   547736 fiasco fiasco -serial_esc
S   1    27448 sigma0 sigma0
R   2   241712 moe moe rom/vm-basic.cfg
M   3      795 vm-basic.cfg vm-basic.cfg
M   4   161664 l4re l4re
M   5   593824 ned ned
M   6  1271944 uvmm uvmm
M   7     2288 virt.dtb virt.dtb
M   8 13618690 linux linux
M   9  1195372 ramdisk.cpio.gz ramdisk.cpio.gz
M  10   346744 backtracer backtracer

linux is the Linux kernel binary that we want to replace.

$ ./l4image -i l4re_vm-basic_arm_virt.elf replace --with-name linux --name linux --file linux-6.17.7/arch/arm64/boot/Image

Now launch the image again, as we already did above:

$ ./l4image -i l4re_vm-basic_arm_virt.elf launch
...
[    1.650165] clk: Disabling unused clocks
[    1.652439] PM: genpd: Disabling unused power domains
[    1.873815] Freeing unused kernel memory: 3200K
[    1.877680] Run /init as init process

~ # uname -a
Linux (none) 6.17.7 #1 SMP PREEMPT Sun Nov  9 22:48:05 CET 2025 aarch64 GNU/Linux
~ #

As we see, we updated the image with the new Linux kernel.

Not only the Linux kernel can be updated, but any file that is within the image. l4image also has an edit command to edit text file, like configurations, directly.

Contents