Skip to main content

1.4 Setting Up the Workbench

The gruesome case studies from the previous section should have left you with enough psychological shadow. Now, carrying this sense of "walking on thin ice" reverence, we can finally get our hands dirty.

We are going to build a laboratory for wreaking havoc—er, I mean, debugging.

But before typing that first command, we must make a decision: where do you plan to build this lab?

Bare Metal or Virtual Machine?​

If you have the hardware, the ideal scenario is to run a modern Linux distribution (Ubuntu, Fedora, etc.) directly on bare metal. For most of the demonstrations in this book, I will use Ubuntu 20.04 LTS as the baseline system.

The advantages of this approach are obvious: direct performance and authentic feedback.

However, there is a massive ⚠️ pitfall warning here:

Since we are going deep into the kernel level for debugging, crashes will be a daily occurrence. And don't assume it's just a simple freeze—data loss is entirely possible. Although the probability is low, if it happens, you won't even have a place to cry.

So, if you choose bare metal, make sure this machine contains absolutely no valuable data. Treat it as a disposable test bench, not your primary workstation.

If bare metal isn't realistic (after all, nobody wants to constantly crash their main machine), then the most practical alternative is a Virtual Machine (VM).

While a VM certainly can't match bare metal in performance (no matter how high you spec it, the virtualization layer overhead is always there), it wins hands down in safety. This is especially critical during kernel debugging: when you completely crash the system or trigger a Panic, you simply reset the VM software (like Oracle VirtualBox) instead of having to reboot physical hardware.

The psychological sense of security this brings is immense—you'd dare to try any crazy operation in a VM, whereas on physical hardware, you'd hesitate for a long time.

Alternative Route: ARM and Raspberry Pi​

Although the default architecture for this book is x86_64, if you want to make this journey more interesting—or closer to real embedded development—I highly recommend running the example code in this book on the ARM architecture.

The current embedded Linux world (whether 32-bit ARM or 64-bit AArch64) is almost entirely dominated by ARM.

In this domain, the Raspberry Pi is the perfect test bed:

  • It's cheap enough;
  • Community support is extremely strong;
  • You get to physically touch real hardware (rather than an abstract virtualized layer).

I will weave in some ARM-related content in later chapters. If you want to follow along, the official Raspberry Pi documentation already explains installation and configuration thoroughly: Raspberry Pi Documentation.

Besides the Raspberry Pi, TI's BeagleBone Black (BBB) is also an excellent choice, especially for those who want to dig deep into low-level hardware interaction. The getting started guide is here: BeagleBoard.org - Black.

Choosing VM Software​

If you decide to go the VM route, my top recommendation is Oracle VirtualBox 6.x (or the latest stable version).

Of course, VMware Workstation or QEMU are also fine; they are all free software. But all the code in this book has been practically tested on VirtualBox 6.1, so I can guarantee it won't lead you astray. VirtualBox is open-source software (under the GPL v2 license, just like the Linux kernel), and you can download it directly from the official website: VirtualBox Downloads.

The host system can be Windows 10/11, Linux (Ubuntu/Fedora), or macOS.

As for the OS installed inside the VM, I suggest sticking with Ubuntu 20.04 LTS just like me. A unified environment saves you a lot of "why is my error different from the book" headaches.

🔍 A Few Practical Tips

How to check the system version? On Debian/Ubuntu systems, using lsb_release reveals everything at a glance:

$ lsb_release -a 2> /dev/null
Distributor ID: Ubuntu
Description:    Ubuntu 20.04.2 LTS
Release:        20.04
Codename:       focal

How to tell if the current system is a VM or bare metal? Sometimes you might forget. In that case, you can use a few commands to self-check:

  • virt-what (we'll install this shortly)
  • systemd-detect-virt (if your init system is systemd)
  • Or simply and bluntly check dmesg | grep -i hypervisor

The Lazy Route: OSBoxes Pre-built Images​

If you don't want to install the OS from scratch, there's a website called OSBoxes that is an absolute godsend for the lazy.

They provide ready-to-use VirtualBox (and VMware) images, and Ubuntu 20.04.3 is naturally on the list. The best part is that these images come with Guest Additions pre-installed (we'll talk about this thing in a moment).

Download link: OSBoxes Ubuntu. The default username and password are usually osboxes / osboxes.org.

If you're a veteran, you might prefer using QEMU to spin up a custom lightweight system, which is totally fine too. For that approach, you can skip the next section.

Installing VirtualBox Guest Additions​

If your Linux is running inside VirtualBox, do not skip this step.

Guest Additions are essentially a set of drivers and applications. They serve two purposes:

  1. Performance acceleration: After installation, you'll noticeably feel that the mouse stops being laggy and the display becomes smooth.
  2. Enhanced experience: They support seamless mouse integration, shared clipboard, shared folders, and drag-and-drop file transfer.

Before installing them, using the VM is pure torture; after installing them, it feels as smooth as a native application.

Before installing, make sure you have booted into the system and done an update:

sudo apt update
sudo apt upgrade

Step 1: Prepare the build environment Installing the Guest Additions requires compiling kernel modules, so we need to get the toolchain ready first. Open a terminal and run:

sudo apt install build-essential dkms linux-headers-$(uname -r) ssh -y

Note that linux-headers-$(uname -r) will automatically match your current kernel version. This step is crucial; otherwise, the compilation will fail.

Step 2: Install the Guest Additions This step is most convenient to do from the GUI. In the VirtualBox menu bar, click Devices -> Insert Guest Additions CD Image. This usually mounts a virtual CD inside the VM. You need to navigate to the CD directory and run the autorun.sh script with root privileges. (If you don't want to click through manually, you can refer to this step-by-step tutorial: How to Install VirtualBox Guest Additions in Ubuntu)

Step 3: Set up shared folder permissions After installation, if you want to transfer files between the host and the VM (e.g., via shared folders), you need to add your current user to the vboxsf group:

sudo usermod -G vboxsf -a ${USER}

After running this, you need to log out and back in (sometimes even a reboot is required) for the permissions to take effect. Otherwise, you'll see the shared folder sitting right there, but you won't be able to open it—which is incredibly frustrating.

Installing Basic Development Tools​

Alright, the VM is tuned, and the system is updated. Now it's time to arm our compilers.

Kernel compilation isn't something you can do with just any text editor; it requires a whole bunch of specific libraries and tools.

Assuming you followed my recommendation and are using Ubuntu 20.04 LTS, we need to proceed in two steps.

Step 1: Kernel build essentials

Update the index first (even though we did it earlier, it's a good habit):

sudo apt update

Then, install the packages absolutely required for building the kernel (this is one long command, don't break it up):

sudo apt install bison flex libncurses5-dev ncurses-dev xz-utils libssl-dev libelf-dev util-linux tar -y

Here's a quick explanation of what exactly we're installing:

  • bison / flex: A significant portion of the kernel code relies on script-generated syntax parsers; without these two, things won't run.
  • libncurses5-dev / ncurses-dev: Required for the make menuconfig graphical configuration interface. Without this, you'd be left staring blind at pure text configuration files.
  • libssl-dev / libelf-dev: Needed for kernel image signing and module processing.
  • -y: This flag tells apt "don't ask me Yes/No, just install everything." While a bit aggressive, it saves a lot of trouble in this deterministic environment.

Step 2: Debugging and analysis toolset

To run all the examples in this book (including BPF and performance analysis that we'll cover later), you'll need even more tools.

Again, just copy and paste this long string (watch out for line breaks):

sudo apt install bc bpfcc-tools bsdmainutils clang cmake cppcheck cscope curl \
dwarves exuberant-ctags fakeroot flawfinder git gnome-system-monitor gnuplot \
hwloc indent kernelshark libnuma-dev libjson-c-dev linux-tools-$(uname -r) \
net-tools numactl openjdk-16-jre openssh-server perf-tools-unstable psmisc \
python3-distutils rt-tests smem sparse stress sysfsutils tldr-py trace-cmd \
tree tuna virt-what -y

⚠️ Note: Some of these packages you might only use once in your life. For example, flawfinder is for statically scanning code for security vulnerabilities, and openjdk-16-jre is for running certain specific Java userspace test programs. If you're tight on disk space, you can pick and choose. But for modern hard drives, this step only takes up a few hundred megabytes, so I recommend just installing everything for peace of mind.

💡 The Lazy Script

I know looking at that long apt install command gives you a headache.

I've wrapped all the above steps into a script called pkg_install4ubuntu_lkd.sh, which is available in this book's GitHub repository. If you're using the OSBoxes Ubuntu 20.04.3 image, running this script directly is the safest bet.

If you want to investigate which packages are hogging your disk space later, you can install wajig and run:

sudo wajig large

Alright, now the software packages are all in place, and our toolbox feels satisfyingly heavy.

We are only one final piece of the puzzle away from compiling the kernel—and you might not know this, but a kernel developer's desk usually has two kernels on it.

In the next section, we'll talk about this "dual-kernel" spectacle.