]>
Commit | Line | Data |
---|---|---|
0d49d7bc FCE |
1 | systemtap: a linux trace/probe tool |
2 | ||
306dd4f8 | 3 | Visit the project web site at <http://sourceware.org/systemtap>, |
0d49d7bc FCE |
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. | |
dfd9ca8c | 9 | See the HACKING file for contribution advice. |
0d49d7bc FCE |
10 | |
11 | Prerequisites: | |
12 | ||
db67fe59 | 13 | - linux kernel |
773cf74b | 14 | - kernel module build environment (kernel-devel rpm) and/or dyninst |
b48233fd | 15 | - optionally, debugging information for kernel/user-space being instrumented |
27cffb52 | 16 | - C compiler (same as what kernel was compiled with) |
d90adf0d | 17 | - elfutils with libdwfl for debugging information parsing |
0d49d7bc FCE |
18 | - root privileges |
19 | ||
062f1f1f FCE |
20 | Installation steps: |
21 | ||
50958227 | 22 | - Install any debuginfo packages you need, for kernel and/or userspace. |
44d7915f | 23 | On modern Fedora, # debuginfo-install kernel [...] |
50958227 FCE |
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.) | |
44d7915f DM |
27 | |
28 | - Install the systemtap package. | |
29 | On modern Fedora, # yum install systemtap systemtap-runtime | |
062f1f1f FCE |
30 | |
31 | Build steps: | |
32 | ||
773cf74b FCE |
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 | ||
7115de82 FCE |
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 | |
113187f4 FCE |
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/ | |
23dd51cf FCE |
45 | Version 0.151 is recommended for i386 hosts probing prelinked programs. |
46 | (PR12141) | |
ab45bf5d | 47 | |
89d60409 FCE |
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 | ||
ab45bf5d | 53 | - Download systemtap sources: |
306dd4f8 FCE |
54 | http://sourceware.org/systemtap/ftp/releases/ |
55 | http://sourceware.org/systemtap/ftp/snapshots/ | |
062f1f1f | 56 | (or) |
306dd4f8 FCE |
57 | git clone git://sourceware.org/git/systemtap.git |
58 | (or) http://sourceware.org/git/systemtap.git | |
ab45bf5d | 59 | |
113187f4 FCE |
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] | |
fffc9716 | 64 | (Note that elfutils > 0.139 requires gcc > 4.0 or else the |
d6fa7e47 FCE |
65 | appropriate elfutils-portability.patch. Ensure decompression |
66 | library headers/libraries are installed for elfutils' use.) | |
7115de82 | 67 | |
113187f4 FCE |
68 | Consider configuring with "--enable-dejazilla" to automatically |
69 | contribute to our public test result database. | |
70 | ||
7115de82 FCE |
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 | ||
034a1d8b | 75 | % make all |
015cb0b7 | 76 | # make install |
034a1d8b | 77 | |
7115de82 | 78 | To uninstall systemtap: |
015cb0b7 | 79 | # make uninstall |
7115de82 FCE |
80 | |
81 | - Run systemtap: | |
82 | ||
b586f21f FCE |
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. | |
7115de82 | 88 | |
773cf74b FCE |
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. | |
d90adf0d | 98 | |
44d7915f DM |
99 | To run a simple test. |
100 | # stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}' | |
101 | ||
d90adf0d | 102 | To run the full test suite from the build tree. |
015cb0b7 | 103 | # make installcheck |
7115de82 | 104 | |
773cf74b FCE |
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 | ||
7115de82 | 109 | |
203a3d5b | 110 | Tips: |
062f1f1f | 111 | |
034a1d8b | 112 | - By default, systemtap looks for the debug info in these locations: |
e5ec4b02 HN |
113 | /boot/vmlinux-`uname -r` |
114 | /usr/lib/debug/lib/modules/`uname -r`/vmlinux | |
115 | /lib/modules/`uname -r`/vmlinux | |
113187f4 | 116 | /lib/modules/`uname -r`/build/vmlinux |
203a3d5b | 117 | |
b5e66ada | 118 | |
203a3d5b FCE |
119 | Building a kernel.org kernel: |
120 | ||
015cb0b7 FCE |
121 | - Consider applying the utrace kernel patches, if you wish to probe |
122 | user-space applications. http://sourceware.org/systemtap/wiki/utrace | |
db67fe59 FCE |
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. | |
02f582ce | 125 | |
203a3d5b | 126 | - Build the kernel using your normal procedures. Enable |
5cf57358 | 127 | CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS, |
7c65223b | 128 | CONFIG_MODULES, CONFIG_MODULE_UNLOAD, CONFIG_UTRACE if able |
b5e66ada | 129 | - % make modules_install install headers_install |
203a3d5b | 130 | - Boot into the kernel. |
b5e66ada FCE |
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 | |
755cdd9b KS |
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 |