VM Setup: Debugging Granary

Step 1: Get gdb

Start by downloading gdb on your host machine:

sudo apt-get install gdb

Step 2: Enable auto-loading of Granary's .gdbinit file

Modify ~/.gdbinit and add the following lines:

add-auto-load-safe-path /path/to/Granary

From now on, if you launch gdb from within the /path/to/Granary folder, gdb will auto-load Granary's .gdbinit file. This file defines several convenient commands and breakpoints for debugging Granary and its clients/tools.

You might also find it convenient to add the following, which will maintain GDB's command history, as well as let you perform reverse searches of commands (just like in a normal shell):

set history filename ~/.gdb_history
set history save

Step 3: Extract your VM kernel's vmlinux file

On the guest, make sure that you've got readelf (part of binutils), as the kernel's extract-vmlinux.sh script depends on this:

sudo apt-get install binutils

Next, run the following:

/usr/src/linux-headers-`uname -r`/scripts/extract-vmlinux /boot/vmlinuz-`uname -r` > /tmp/vmlinux

Next, copy the file to the host machine:

scp /tmp/vmlinux sloth:/tmp/vmlinux

Finally, move vmlinux to a more permanent location on the host.

mv /tmp/vmlinux ~/Code

Step 4: Tell Granary about this vmlinux file.

cd /path/to/Granary
./scripts/make_vmlinux_link.sh ~/Code/vmlinux

This will create the vmlinux symbolic link to your local copy of the VM's vmlinux file. We need this local copy so that gdb can see the instructions and symbols of the VM's kernel.

Step 5: Getting the kernel symbols

This step is only necessarily if the vmlinux file is stripped of debugging information. A quick way of testing this is to see if the following command doesn't print any output:

readelf --syms --wide /path/to/Granary/vmlinux | tail

Suggested approach

One way to get debug symbols is to replace your VM's kernel with one that has debugging symbols. The script linked here will fetch and install the appropriate dbgsyms for Ubuntu. Then, run the following command:

scp /usr/lib/debug/boot/vmlinux-`uname -r` sloth:/tmp/vmlinux

Now repeat step 4.

Poor man's approach

Let's assume you don't want to download anything and you want to make life hard. In this case, we won't get debug info, but we will fake ELF symbol information by combining the output of kallsyms with the VM's vmlinux file. Start by extracting your VM's symbols.

Execute the following commands in the guest:

sudo cat /proc/kallsyms > /tmp/kernel.syms
scp /tmp/kernel.syms sloth:/tmp/kernel.syms

Then, execute the following commands in the host:

cd /path/to/Granary
readelf --sections --wide ~/Code/vmlinux > /tmp/kernel.sections
mkdir -p generated
python scripts/generate_kernel_debug.py /tmp/kernel.syms /tmp/kernel.sections > /tmp/kernel.lds
cp ~/Code/vmlinux /tmp
ld -T /tmp/kernel.lds -r /tmp/vmlinux -o ~/Code/vmlinux
rm vmlinux
./scripts/make_vmlinux_link.sh ~/Code/vmlinux

Now ~/Code/vmlinux will be updated with symbol information, and the symbolic /path/to/Granary/vmlinux will point to the updated vmlinux file.