README

   1 systemtap: a linux trace/probe tool
   2
   3 Visit the project web site at <http://sourceware.org/systemtap>,
   4 for documentation and mailing lists for developers and users.
   5
   6 This is free software.
   7 See the COPYING file for redistribution/modification terms.
   8 See the INSTALL file for generic build instructions.
   9 See the HACKING file for contribution advice.
  10
  11 Prerequisites:
  12
  13 - linux kernel
  14 - kernel module build environment (kernel-devel rpm) and/or dyninst
  15 - optionally, debugging information for kernel/user-space being instrumented
  16 - C compiler (same as what kernel was compiled with)
  17 - elfutils with libdwfl for debugging information parsing
  18 - root privileges
  19
  20 Installation steps:
  21
  22 - Install any debuginfo packages you need, for kernel and/or userspace.
  23   On modern Fedora, # debuginfo-install kernel [...]
  24   (Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc.
  25   variants.  Each likely has a corresponding development and debuginfo
  26   package.)
  27
  28 - Install the systemtap package.
  29   On modern Fedora, # yum install systemtap systemtap-runtime
  30
  31 Build steps:
  32
  33 - Consider installing the kernel-debuginfo, kernel-devel, gcc and
  34   dependent packages (or see below if you are building your own
  35   kernels from source).  If using only the pure-userspace dyninst
  36   backend, install gcc and dyninst-devel.
  37
  38 - If available, install your distribution's copy of elfutils and its
  39   development headers/libraries.
  40   Or if desired, download an elfutils source release to build in
  41   "bundled mode" (below), and untar it into some new directory.
  42   Or if desired, build elfutils separately one time, and install
  43   it to /usr/local.
  44   See http://fedorahosted.org/elfutils/
  45   Version 0.151 is recommended for i386 hosts probing prelinked programs.
  46   (PR12141)
  47
  48 - On modern Fedora, install general optional build-requisites:
  49   # yum-builddep systemtap
  50   On modern Debian/Ubuntu, similarly:
  51   # apt-get build-dep systemtap
  52
  53 - Download systemtap sources:
  54   http://sourceware.org/systemtap/ftp/releases/
  55   http://sourceware.org/systemtap/ftp/snapshots/
  56   (or)
  57   git clone git://sourceware.org/git/systemtap.git
  58       (or) http://sourceware.org/git/systemtap.git
  59
  60 - Build systemtap normally:
  61   % .../configure [other autoconf options]
  62   Or, with build it with a bundled internal copy of elfutils:
  63   % .../configure --with-elfutils=ELFUTILS-SOURCE-DIR [other autoconf options]
  64   (Note that elfutils > 0.139 requires gcc > 4.0 or else the
  65   appropriate elfutils-portability.patch.  Ensure decompression
  66   library headers/libraries are installed for elfutils' use.)
  67
  68   Consider configuring with "--enable-dejazilla" to automatically
  69   contribute to our public test result database.
  70
  71   Consider configuring with "--prefix=DIRECTORY" to specify an
  72   installation directory other than /usr/local.  It can be an ordinary
  73   personal directory.
  74
  75   % make all
  76   # make install
  77
  78   To uninstall systemtap:
  79   # make uninstall
  80
  81 - Run systemtap:
  82
  83   To run systemtap after installation, add $prefix/bin to your $PATH, or
  84   refer to $prefix/bin/stap directly.  If you keep your build tree
  85   around, you can also use the "stap" binary there.
  86
  87   Some samples should be available under $prefix/share/doc/systemtap/examples.
  88
  89   For the normal linux-kernel-module based backend, run "stap" as
  90   root.  If desired, create "stapdev" and "stapusr" entries in
  91   /etc/groups.  Any users in "stapdev"+"stapusr" will be able to run
  92   systemtap as if with root privileges.  Users in "stapusr" only may
  93   launch (with "staprun") pre-compiled probe modules (created by "stap
  94   -p4 ...") that a system administrator copied under
  95   /lib/modules/`uname -r`/systemtap.  "stapusr" may also be permitted
  96   to create arbitrary unprivileged systemtap scripts of their own.
  97   See README.unprivileged for additional setup instructions.
  98
  99   To run a simple test.
 100   # stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'
 101
 102   To run the full test suite from the build tree.
 103   # make installcheck
 104
 105   For the prototype dyninst pure-userspace backend, run "stap" as any user.
 106   % stap --runtime=dyninst -e 'probe process.function("*") {
 107                                println(pn(), ":", $$parms) }' -c 'ls'
 108
 109
 110 Tips:
 111
 112 - By default, systemtap looks for the debug info in these locations:
 113   /boot/vmlinux-`uname -r`
 114   /usr/lib/debug/lib/modules/`uname -r`/vmlinux
 115   /lib/modules/`uname -r`/vmlinux
 116   /lib/modules/`uname -r`/build/vmlinux
 117
 118
 119 Building a kernel.org kernel:
 120
 121 - Consider applying the utrace kernel patches, if you wish to probe
 122   user-space applications.  http://sourceware.org/systemtap/wiki/utrace
 123   Or if your kernel is near 3.5, apply the uprobes and related patches
 124   (see NEWS).  Or if your kernel is >= 3.5, enjoy the built-in uprobes.
 125
 126 - Build the kernel using your normal procedures.  Enable
 127   CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS,
 128   CONFIG_MODULES, CONFIG_MODULE_UNLOAD, CONFIG_UTRACE if able
 129 - % make modules_install install headers_install
 130 - Boot into the kernel.
 131
 132 - If you wish to leave the kernel build tree in place, simply run
 133   % stap -r /path/to/kernel/build/tree [...]
 134   You're done.
 135
 136 - Or else, if you wish to install the kernel build/debuginfo data into
 137   a place where systemtap will find it without the "-r" option:
 138   % ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build
 139
 140 - Instead of using the "-r" option, you can also use the environment
 141   variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data.
 142