A guide on how to install Systemtap on an Ubuntu system

Distro Support

Get the systemtap package

sudo apt-get install systemtap

(To build it yourself, see our README file.)

Get access to ddebs containing debug symbols: Follow instructions in https://wiki.ubuntu.com/DebuggingProgramCrash

Kernel support

The generic kernel comes with CONFIG_DEBUG_FS, CONFIG_DEBUG_KERNEL, CONFIG_DEBUG_INFO and CONFIG_KPROBES enabled, so no recompilation needed. For Ubuntu Gutsy (or older version), you have to recompile your kernel: Bug #140784: Enable CONFIG_AUDITSYSCALL in kernel config.

Debug Symbols

General ddeb repository configuration

# cat > /etc/apt/sources.list.d/ddebs.list << EOF
deb http://ddebs.ubuntu.com/ precise main restricted universe multiverse
EOF

etc.

# apt-key adv --keyserver keyserver.ubuntu.com --recv-keys ECDCAD72428D7C01
# apt-get update

NOTE: Ubuntu kernel packages carry a sub-version field that does not show up in uname -r, so there may occur subtle installation errors whereby the -dbgsym appears correct, but doesn't exactly match the kernel image running. For example, here is a mismatch between .41 and .42, which will result in run-time build-id verification errors from systemtap:

% uname -r
3.5.0-26-generic
% dpkg --list | grep linux
linux-image-3.5.0-26-generic_3.5.0-26.41_amd64.deb
linux-image-3.5.0-26-generic-dbgsym_3.5.0-26.42_amd64.ddeb

Ubuntu 9.10 and higher

Kernel debug packages have been removed from the repositories and moved to a dedicated ddebs repository

From the command line run uname -r to find your current running kernel version
sudo apt-get install linux-image-$(uname -r)-dbgsym. If a dbgsym package doesn't exist for your kernel, upgrade your kernel.
Systemtap will now have access to nearly all the information it needs, however, stap -l 'module("*").function("*")' , will produce no results.
systemtap/libelf is looking for modules with a an extension of .ko.debug, where Ubuntu leaves unstripped kos in /usr/lib/debug with the plain .ko extension.
- sudo apt-get install elfutils, for eu-readelf Then run this script as root, whenever you install additional debug symbols
```
for file in `find /usr/lib/debug -name '*.ko' -print`
do
        buildid=`eu-readelf -n $file| grep Build.ID: | awk '{print $3}'`
        dir=`echo $buildid | cut -c1-2`
        fn=`echo $buildid | cut -c3-`
        mkdir -p /usr/lib/debug/.build-id/$dir
        ln -s $file /usr/lib/debug/.build-id/$dir/$fn
        ln -s $file /usr/lib/debug/.build-id/$dir/${fn}.debug
done
```
This makes available the module probes available and is friendly to other debug symbol savvy apps like gdb and oprofile. This convention should make
it's way into Ubuntu in the near future. Tracked by lp #669641, this feature is already integrated into the Linaro (ARM) kernels.

Ubuntu releases 9.04 and older

For Gutsy and Hardy, the easiest way is to use the linux-image-generic meta-package:

sudo apt-get install linux-image-debug-generic

This will install /boot/vmlinux-debug-<yourkernelversion>. Now create a symlink for vmlinux in /lib/modules:

sudo ln -s /boot/vmlinux-debug-$(uname -r) /lib/modules/$(uname -r)/vmlinux

For Intrepid, there's no linux-image-debug-generic metapackage (see https://bugs.launchpad.net/ubuntu/+source/linux/+bug/289087); you have to download the right one from http://ddebs.ubuntu.com/pool/main/l/linux/ instead of getting it from APT (unfortunately getting "the right one" is basically impossible, as only the latest version is available for download). After downloading the one of these that matches your kernel, install it with dpkg -i. This will install /usr/lib/debug/boot/vmlinux-<yourkernelversion>. The system already knows to look there for it, so you don't need to symlink it into /lib/modules.

Devel environment

Kernel headers and gcc are needed for module compilation, so if you have not done so, install them (assuming the usage of generic kernel again): libcap-dev needed for Systemtap packages > 0.6-1

sudo apt-get install linux-headers-generic gcc libcap-dev

Note: Ubuntu does not currently include utrace support, limiting user space functionality. Once utrace is integrated into the upstream kernel this will no longer be an issue. With version 12.10 (Quantal) and the new Kernel 3.5 there is no need anymore to patch the Kernel. Systemtap can use UPROBES that are integrated into the kernel. For earlier releases such as 12.04 using the latest Mainline 3.5 Kernel (https://wiki.ubuntu.com/KernelMainlineBuilds) seems to do the trick.