Kernel Debugging with User-Mode Linux(UML) and No KDB

The Quiet Beginning

Kernel development is a quiet storm — a space where clarity must be carved from chaos. Crashes aren't failures; they're whispers from beneath the surface. In this space of disruption, User-Mode Linux (UML) offers a calm sanctuary.

This guide is written to make that storm gentler. To help you find rhythm in the debugging. And to remind you that even the most cryptic kernel bug can carry a lesson. Here, every misstep becomes a message, every freeze a moment of stillness before progress.

User-Mode Linux (UML) for Kernel Debugging 🛠️

User-Mode Linux (UML) is a unique tool that allows a Linux kernel to run as a user-space process inside another Linux system. It offers a lightweight, isolated environment where kernel panics and bugs affect only the UML instance, leaving the host untouched.

This makes UML ideal for debugging, syscall tracing, and kernel development. Unlike full virtual machines, it’s faster to boot, consumes fewer resources, and integrates cleanly with your existing Linux setup.

Whether you're experimenting with custom kernel code or stepping through syscalls in a safe sandbox, UML provides a quiet and controlled space for learning, testing, and evolving as a developer.

Why Choose UML for Debugging?

🛡️ Safety and Isolation

Kernel bugs and panics only affect the UML instance, keeping your host system secure.

⚡️ Flexibility and Speed

Quickly start, stop, snapshot, and revert different configurations and test environments.

🌿 Resource Efficiency

No need for heavy virtual machines or extra hardware; UML runs as a lightweight process.

🧰 Multi-Instance Testing

Run multiple UML kernels simultaneously to simulate varied environments.

🧠 Note on Performance:
UML is strictly uniprocessor — it doesn’t support SMP (multi-core execution). While it spawns threads (e.g., for UBD or memory emulation), only one CPU is used for computation. This simplifies debugging but may limit performance on multi-core systems.
For tuning tips, visit the official UML tuning guide.

Preparing the Ground

Before embarking on setting up UML, ensure you have:

A Linux host (Ubuntu 22.04+ or Debian recommended)
sudo/root privileges
Familiarity with shell and basic kernel concepts

Walking the Path 🧭

🟢 Beginner-Friendly Setup
This guide flows like a gentle stream — no deep kernel wisdom required. Just follow the steps, breathe through the commands, and let the system unfold, one line at a time.

🔧 Step 1: Install Required Packages

sudo apt-get update
sudo apt-get install build-essential flex bison libncurses-dev \
                     git ca-certificates wget bc xz-utils debootstrap

📦 Step 2: Set Up UML Automatically (Recommended)

You can get started quickly by cloning this GitHub repo:

git clone https://github.com/jayapsrivastava/kernel-fs-lab.git
cd kernel-fs-lab/UML-setup

Running the helper in one line:

chmod +x uml-setup.sh                # (first time only, if needed)
sudo ./uml-setup.sh                  # builds kernel, root-fs, TAP device
sudo /usr/bin/run-uml-linux.sh       # boots your UML guest

First run takes about 6–8 minutes while the kernel compiles; repeats are much faster.

Need a different subnet or kernel version? Prefix the call, e.g.

sudo HOST_IP=10.0.0.1/24 KVER=6.9.9 ./uml-setup.sh

This script will:

📥 Download and compile a UML kernel
🏗️ Create a minimal root filesystem using debootstrap
🌐 Configure networking via a TAP device
🚀 Start the UML guest with your custom init.sh script

📝 Note: The repository also includes README files for each script, so you can explore, tweak, and learn from every part of the setup.

🧪 What's Happening Under the Hood?

🔍 For the Curious Tinkerers
For those who seek the root of things — not just what works, but why — this section opens the kernel's soul. Watch it compile, connect, and come alive beneath your fingertips.

📥 Step 3: Download and Extract the Kernel Source

Choose your desired kernel version manually (default shown: 6.12.10).

wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.12.10.tar.xz
tar -xf linux-6.12.10.tar.xz
cd linux-6.12.10

⚙️ Step 4: Configure the Kernel for UML

Use a prebuilt configuration optimized for User-Mode Linux

cp kernel-fs-lab/UML-setup/uml.config .config
make ARCH=um olddefconfig

🏗️ Step 5: Compile the Kernel

Build the UML kernel and its modules

make ARCH=um -j$(nproc)
make ARCH=um modules

🏠 Step 6: Create Root Filesystem

Use debootstrap to create a minimal Debian-based root filesystem and prepare it for boot:

mkdir -p /umlroot
debootstrap buster /umlroot http://deb.debian.org/debian
cp kernel-fs-lab/UML-setup/init.sh /umlroot/init.sh
cp kernel-fs-lab/UML-setup/uml.bashrc /umlroot/.bashrc
chmod +x /umlroot/init.sh

📦 Step 7: Install Kernel Modules into Root Filesystem

Now that /umlroot is ready, install the compiled modules into it:

sudo make ARCH=um modules_install INSTALL_MOD_PATH=/umlroot

🌐 Step 8: Set Up TAP Networking (Host Side)

Configure a TAP device on the host. This allows the UML guest (vec0) to communicate with the host (tap0)using standard IP networking.

ip tuntap add dev tap0 mode tap user $USER
ip addr add 192.168.0.1/24 dev tap0
ip link set tap0 up

🚀 Step 9: Launch UML with HostFS

Boot your UML kernel with networking and your custom root filesystem:
(This is exactly what the run-uml-linux.sh script does for you.)

linux \
  vec0:transport=tap,ifname=tap0,depth=128,gro=1 \
  rootfstype=hostfs rootflags=/umlroot \
  init=/init.sh \
  umid=uml-kdev \
  mem=512M \
  verbose

🎉 Result: What You Should See

As you run run-uml-linux.sh, a steady stream of kernel messages will begin to flow across your screen. Let them pass without alarm — these aren’t warnings, but signs of life, the heartbeat of your virtual system. These are not problems to fear, but rhythms to observe.

📝 Curious about those scrolling messages?
We'll walk through the UML boot log in the next blog — decoding what it really means for debugging and development.

After this graceful stream settles, and if everything went as intended, UML will boot with:

Your custom-compiled Linux kernel
Your own init.sh script executed as PID 1
A functional network interface via the TAP device (vec0)
A working Bash prompt inside the UML instance

Example output:

.
.
Linux uml-kdev 6.12.102020-11-12 #1 Tue Apr 29 15:19:40 UTC 2025 x86_64 GNU/Linux

Welcome to KDEV-UML

root@uml-kdev:/ >

This means the UML instance is live, interactive, and isolated—ready for experimentation or debugging.

🌐 Verify UML Networking

Once inside the UML shell, confirm that the vec0 network interface is up by running:

root@uml-kdev:/ > ip a
vec0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000
    link/ether 0e:ca:c2:5e:02:ad brd ff:ff:ff:ff:ff:ff
    inet 192.168.0.253/24 scope global vec0
       valid_lft forever preferred_lft forever

Next, test connectivity to the host (which holds the tap0 interface - remember we configured earlier in Step 7):

root@uml-kdev:/ > ping 192.168.0.1
PING 192.168.0.1 (192.168.0.1) 56(84) bytes of data.
64 bytes from 192.168.0.1: icmp_seq=1 ttl=64 time=2.30 ms
64 bytes from 192.168.0.1: icmp_seq=2 ttl=64 time=2.65 ms

This confirms that the TAP device is correctly bridged and active, enabling host-to-UML communication.

🧪 A Teaser: Loadable Modules Work Too!

Now that your UML system breathes and connects, the next breath is one of creation.
Modules — once heavy, system-bound creatures — now load gracefully within this sandbox of clarity.

Try this inside your UML shell:

modprobe ext4
lsmod

You'll see something like:

Module                  Size  Used by  
ext4                  589824  -2

Why -2? It’s not a bug, but a clue. The module is loaded, yet untouched — a quiet presence awaiting its first call.

Curious?

🎯 We’ll explore this mystery in the next post — where modules speak, and GDB listens.

📜 This also includes: a walkthrough of the UML boot log — not just what it says, but what it means.
From cryptic lines to calm insights, we’ll trace the story your kernel tells as it comes alive.

🔚 Stopping UML Instances

When your exploration has run its course and the kernel dojo can rest, gently bring your UML instance to a close using one of the following methods:

▶️ From inside UML:

poweroff -f    # Immediately powers off the UML guest
reboot -f      # Immediately reboots the UML guest

💻 From the host system:

Use the UML management console:

uml_mconsole uml-kdev halt

Or, if you've set a custom $UMID:

uml_mconsole $UMID halt

📍 Note: UML creates a control socket at:

~/.uml/uml-kdev/mconsole

Example:

ls -la ~/.uml/uml-kdev/mconsole

This socket allows external control of UML — even after its terminal is closed.

⚠️ When the Calm Breaks: Debugging Common Setup Issues

Even in a quiet dojo, the unexpected can knock at the door. If something doesn’t work, don’t rush — read the signs. Below are common symptoms and mindful ways to resolve them:

🛑 UML Doesn’t Start

Check for leftover UML processes from a failed run:

ps -eaf | grep linux
kill -9 <PID>

Run clean. Stale processes can block new sessions.

🔒 Permissions on Scripts

Make sure your init.sh and other scripts in /umlroot are executable:

chmod +x /umlroot/*.sh

Without this, the system won’t hand off properly to your init process.

⚙️ Compilation Errors

If the kernel build fails, double-check that you've installed all required build tools and libraries:

sudo apt-get install build-essential flex bison libncurses-dev gdb ...

Kernel compilation needs a healthy toolchain.

📂 Filesystem Mount Issues

If UML fails to mount the root filesystem, make sure /umlroot exists and is populated (via debootstrap), and that the path in your boot args is correct:

rootflags=/umlroot rootfstype=hostfs

The mount must point to a real root.

🧪 Try it out and share your first kernel trace. Let the quiet dojo echo with curiosity.

🌅 Closing the Loop: A Calm Exit from the Kernel Lab

The journey from kernel crashes ⚡️ to clarity 💡 doesn’t have to be riddled with fear or frustration. With User-Mode Linux, debugging becomes a calmer practice — a space to experiment, observe, and understand without risking your entire system.

Every crash is a signal. Every bug, a quiet invitation to slow down and look deeper. Kernel development will always carry its storms — but with the right tools and a steady presence of mind, you can begin to find rhythm within the noise.

With UML as your companion, every misstep becomes part of the process.
And clarity 💡 isn’t something to chase — it’s something that unfolds.

🌀 If this journey sparked clarity, pass it on. Share, fork, or reflect—wherever the kernel takes you next.

Questions Along the Way ❓

What makes UML safer for kernel debugging than traditional methods?

UML isolates crashes to user space, protecting the host OS from bugs and system-wide failures.

Can I use UML for production environments?

No. UML is intended for development, testing, and debugging—not production deployment.

How much system resource does UML consume compared to VMs?

UML is extremely lightweight, consuming minimal CPU and RAM compared to full virtual machines.

Is it possible to debug kernel modules using UML?

Yes — UML welcomes your kernel modules. Whether ext4, NFS, or parallel filesystems, each can be built, loaded, and watched under the gentle gaze of GDB.
🎶 Follow my next blog, where the modules speak and the debugger listens.

What are alternatives to User-Mode Linux for kernel debugging?

Options include QEMU, KVM, and physical hardware with crash dump analysis tools.

From Kernel Panics 🌩️ to Clarity 💡: A Developer’s Journey with User-Mode Linux

Table of contents