systemtap: a linux trace/probe tool

Visit the project web site at <http://sources.redhat.com/systemtap>,
for documentation and mailing lists for developers and users.

This is free software.
See the COPYING file for redistribution/modification terms.
See the INSTALL file for generic build instructions.

Prerequisites:

- linux kernel with kprobes (mainline 2.6.11+ or backport)
- kernel module build environment (kernel-devel rpm)
- kernel debugging information (kernel-debuginfo rpm)
- C compiler (same as what kernel was compiled with)
- elfutils with libdwfl for debugging information parsing
- root privileges

Installation steps:

- Install the kernel-debuginfo, kernel-devel, gcc packages.
- Install the systemtap package, if one already exists.

Build steps:

- Install the kernel-debuginfo, kernel-devel, gcc and dependent
  packages (or see below if you are building your own kernels from source).

- If available, install your distribution's copy of elfutils and its
  development headers/libraries.
  Or if desired, download an elfutils source release to build in
  "bundled mode" (below), and untar it into some new directory.
  Or if desired, build elfutils separately one time, and install
  it to /usr/local.
  See http://fedorahosted.org/elfutils/

- Download systemtap sources:
  http://sources.redhat.com/systemtap/ftp/releases/
  http://sources.redhat.com/systemtap/ftp/snapshots/
  (or)
  git clone git://sources.redhat.com/git/systemtap.git
      (or) http://sources.redhat.com/git/systemtap.git

- Build systemtap normally:
  % .../configure [other autoconf options]
  Or, with build it with a bundled internal copy of elfutils:
  % .../configure --with-elfutils=ELFUTILS-SOURCE-DIR [other autoconf options]

  Consider configuring with "--enable-dejazilla" to automatically
  contribute to our public test result database.

  Consider configuring with "--prefix=DIRECTORY" to specify an
  installation directory other than /usr/local.  It can be an ordinary
  personal directory.

  % make all
  % sudo make install

  To uninstall systemtap:
  % sudo make uninstall

- Run systemtap:

  To run systemtap after installation, add $prefix/bin to your $PATH, or
  refer to $prefix/bin/stap directly.  If you keep your build tree
  around, you can also use the "stap" binary there.  

  Some samples should be available under $prefix/share/doc/systemtap/examples.

  Normally, run "stap" as root.  If desired, create "stapdev" and
  "stapusr" entries in /etc/groups.  Any users in "stapdev" will be
  able to run systemtap as if with root privileges.  Users in "stapusr"
  can only launch (with "staprun") pre-compiled probe modules (created
  by "stap -p4 ...") that a system administrator copied under
  /lib/modules/`uname -r`/systemtap.

  To run the full test suite from the build tree.
  % sudo make installcheck


Tips:

- By default, systemtap looks for the debug info in these locations:
  /boot/vmlinux-`uname -r`
  /usr/lib/debug/lib/modules/`uname -r`/vmlinux
  /lib/modules/`uname -r`/vmlinux
  /lib/modules/`uname -r`/build/vmlinux

Building a kernel.org kernel:

- Build the kernel using your normal procedures.  Enable
  CONFIG_DEBUG_INFO, CONFIG_KPROBES, and optionally CONFIG_RELAY and
  CONFIG_DEBUG_FS.
- Run "make install modules_install headers_install" as needed.
- Boot into the kernel.
- Make sure the large unstripped kernel image 'vmlinux' from your
  build can be found by systemtap (see above)  You can just symlink
  it to one of these locations.
- Symlink your build directory to here:
  /lib/modules/`uname -r`/build
- For example, if your kernel source is in /home/me/linux/2.6.17-rc6
  and you build your kernel in the source directory, you would do
  this (be sure you are running the right kernel or `uname -r`
  will be wrong:)
     ln -s /home/me/linux/2.6.17-rc6/vmlinux /boot/vmlinux-`uname -r`
     mkdir /usr/src/kernels  (if needed)
     ln -s /home/me/linux/2.6.17-rc6 /usr/src/kernels/`uname -r`
     mkdir /lib/modules/`uname -r`  (if needed)
     ln -s /home/me/linux/2.6.17-rc6 /lib/modules/`uname -r`/build
     ln -s /home/me/linux/2.6.17-rc6 /lib/modules/`uname -r`/source