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
  10 Prerequisites:
  11
  12 - linux kernel with kprobes (mainline 2.6.11+ or backport)
  13 - kernel module build environment (kernel-devel rpm)
  14 - kernel debugging information (kernel-debuginfo rpm)
  15 - C compiler (same as what kernel was compiled with)
  16 - elfutils with libdwfl for debugging information parsing
  17 - root privileges
  18
  19 Installation steps:
  20
  21 - Install the kernel development and gcc packages.
  22   On modern Fedora, # yum install kernel-devel-`uname -r`
  23
  24 - Install any debuginfo packages you need, for kernel and/or userspace.
  25   On modern Fedora, # debuginfo-install kernel [...]
  26
  27   (Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc.
  28   variants.  Each likely has a corresponding development and debuginfo
  29   package.)
  30
  31 - Install the systemtap package.
  32   On modern Fedora, # yum install systemtap systemtap-runtime
  33
  34 Build steps:
  35
  36 - Install the kernel-debuginfo, kernel-devel, gcc and dependent
  37   packages (or see below if you are building your own kernels from source).
  38
  39 - If available, install your distribution's copy of elfutils and its
  40   development headers/libraries.
  41   Or if desired, download an elfutils source release to build in
  42   "bundled mode" (below), and untar it into some new directory.
  43   Or if desired, build elfutils separately one time, and install
  44   it to /usr/local.
  45   See http://fedorahosted.org/elfutils/
  46   Version 0.151 is recommended for i386 hosts probing prelinked programs.
  47   (PR12141)
  48
  49 - On modern Fedora, install general optional build-requisites:
  50   # yum-builddep systemtap
  51   On modern Debian/Ubuntu, similarly:
  52   # apt-get build-dep systemtap
  53
  54 - Download systemtap sources:
  55   http://sourceware.org/systemtap/ftp/releases/
  56   http://sourceware.org/systemtap/ftp/snapshots/
  57   (or)
  58   git clone git://sourceware.org/git/systemtap.git
  59       (or) http://sourceware.org/git/systemtap.git
  60
  61 - Build systemtap normally:
  62   % .../configure [other autoconf options]
  63   Or, with build it with a bundled internal copy of elfutils:
  64   % .../configure --with-elfutils=ELFUTILS-SOURCE-DIR [other autoconf options]
  65   (Note that elfutils > 0.139 requires gcc > 4.0 or else the
  66   appropriate elfutils-portability.patch.)
  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   Normally, run "stap" as root.  If desired, create "stapdev" and
  90   "stapusr" entries in /etc/groups.  Any users in "stapdev"+"stapusr" will
  91   be able to run systemtap as if with root privileges.  Users in "stapusr"
  92   only may launch (with "staprun") pre-compiled probe modules (created
  93   by "stap -p4 ...") that a system administrator copied under
  94   /lib/modules/`uname -r`/systemtap.  "stapusr" may also be permitted to
  95   create arbitrary unprivileged systemtap scripts of their own.  See
  96   README.unprivileged for additional setup instructions.
  97
  98   To run a simple test.
  99   # stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'
 100
 101   To run the full test suite from the build tree.
 102   # make installcheck
 103
 104
 105 Tips:
 106
 107 - By default, systemtap looks for the debug info in these locations:
 108   /boot/vmlinux-`uname -r`
 109   /usr/lib/debug/lib/modules/`uname -r`/vmlinux
 110   /lib/modules/`uname -r`/vmlinux
 111   /lib/modules/`uname -r`/build/vmlinux
 112
 113
 114 Building a kernel.org kernel:
 115
 116 - Consider applying the utrace kernel patches, if you wish to probe
 117   user-space applications.  http://sourceware.org/systemtap/wiki/utrace
 118
 119 - Build the kernel using your normal procedures.  Enable
 120   CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS,
 121   CONFIG_MODULES, CONFIG_MODULE_UNLOAD, CONFIG_UTRACE if able
 122 - % make modules_install install headers_install
 123 - Boot into the kernel.
 124
 125 - If you wish to leave the kernel build tree in place, simply run
 126   % stap -r /path/to/kernel/build/tree [...]
 127   You're done.
 128
 129 - Or else, if you wish to install the kernel build/debuginfo data into
 130   a place where systemtap will find it without the "-r" option:
 131   % ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build
 132
 133 - Instead of using the "-r" option, you can also use the environment
 134   variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data.
 135