Tutorial: Configuring KGDBoE manually

This tutorial shows how to build and configure our KGDBoE module to debug your Linux kernel using a network connection. Before you begin ensure your Linux machine is connected to the same subnet as the developer machine and can be accessed from there.

  1. Ensure you have the debugging symbols for your kernel on the debug machine. If you are using VisualKernel, it will fetch them automatically.
  2. Download, unpack and build kgdboe on the target machine:
    git clone https://github.com/sysprogs/kgdboe.git
    cd kgdboe
    make -C /lib/modules/$(uname -r)/build M=$(pwd)
  3. Find out the address of the kallsyms_lookup_name function in your kernel:
    sudo cat /proc/kallsyms
  4. Load the kgdboe module:
    sudo insmod kgdboe.ko kallsyms_lookup_name_address=0x<address>
  5. Inspect the output of the dmesg command ensuring that kgdboe has initialized correctly:
    dmesg | tail
  6. Start gdb on your debug machine. Run the following command to connect to kgdboe:
    target remote udp:<IP>:<port>
  7. Enjoy debugging!

Configuration parameters

You can tweak the behavior of KGDBoE by specifying some parameters when loading the module. The syntax is simply as follows:

insmod kgdboe.ko param1=val1 param2=val2 ...

The following parameters are supported:

Parameter Default Description
device_name eth0 Ethernet device to use for debugging.
local_ip N/A Local IP address to bind to. Auto-detected if not specified.
udp_port 31337 UDP port to use for debugging.
force_single_core 1 Disable all cores except #0 when the module is loaded. This setting is recommended unless you are debugging SMP-specific issues, as it avoids many synchronization problems. KGDBoE can reliably work in the SMP mode, but it has not been tested on all network drivers, so use caution if you decide to disable this.
kallsyms_lookup_name_address N/A Address of the kallsyms_lookup_name symbol with the 0x prefix. You can find it out by running "sudo cat /proc/kallsyms".