]>
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 |
8f2f3433 FCE |
16 | - C compiler (same as what kernel was compiled with), to build kernel modules |
17 | - C++11 compiler such as gcc 4.8+, to build systemtap itself | |
18 | - elfutils 0.151+ with libdwfl for debugging information parsing | |
0d49d7bc FCE |
19 | - root privileges |
20 | ||
062f1f1f FCE |
21 | Installation steps: |
22 | ||
50958227 | 23 | - Install any debuginfo packages you need, for kernel and/or userspace. |
44d7915f | 24 | On modern Fedora, # debuginfo-install kernel [...] |
50958227 FCE |
25 | (Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc. |
26 | variants. Each likely has a corresponding development and debuginfo | |
27 | package.) | |
44d7915f DM |
28 | |
29 | - Install the systemtap package. | |
30 | On modern Fedora, # yum install systemtap systemtap-runtime | |
062f1f1f FCE |
31 | |
32 | Build steps: | |
33 | ||
773cf74b FCE |
34 | - Consider installing the kernel-debuginfo, kernel-devel, gcc and |
35 | dependent packages (or see below if you are building your own | |
36 | kernels from source). If using only the pure-userspace dyninst | |
37 | backend, install gcc and dyninst-devel. | |
38 | ||
7115de82 FCE |
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 | |
113187f4 FCE |
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. | |
7e8210ae | 45 | See http://elfutils.org/ |
23dd51cf FCE |
46 | Version 0.151 is recommended for i386 hosts probing prelinked programs. |
47 | (PR12141) | |
ab45bf5d | 48 | |
89d60409 FCE |
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 | ||
ab45bf5d | 54 | - Download systemtap sources: |
306dd4f8 FCE |
55 | http://sourceware.org/systemtap/ftp/releases/ |
56 | http://sourceware.org/systemtap/ftp/snapshots/ | |
062f1f1f | 57 | (or) |
306dd4f8 FCE |
58 | git clone git://sourceware.org/git/systemtap.git |
59 | (or) http://sourceware.org/git/systemtap.git | |
ab45bf5d | 60 | |
113187f4 FCE |
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] | |
8f2f3433 | 65 | (Ensure decompression library headers/libraries are installed for elfutils' use.) |
7115de82 | 66 | |
113187f4 FCE |
67 | Consider configuring with "--enable-dejazilla" to automatically |
68 | contribute to our public test result database. | |
69 | ||
7115de82 FCE |
70 | Consider configuring with "--prefix=DIRECTORY" to specify an |
71 | installation directory other than /usr/local. It can be an ordinary | |
72 | personal directory. | |
73 | ||
034a1d8b | 74 | % make all |
015cb0b7 | 75 | # make install |
7115de82 | 76 | To uninstall systemtap: |
015cb0b7 | 77 | # make uninstall |
7115de82 | 78 | |
c59c41d0 FCE |
79 | Alternately, on a Fedora-like system: |
80 | % make rpm | |
81 | # rpm -i /path/to/rpmbuild/.../systemtap*rpm | |
82 | ||
83 | ||
7115de82 FCE |
84 | - Run systemtap: |
85 | ||
b586f21f FCE |
86 | To run systemtap after installation, add $prefix/bin to your $PATH, or |
87 | refer to $prefix/bin/stap directly. If you keep your build tree | |
88 | around, you can also use the "stap" binary there. | |
89 | ||
90 | Some samples should be available under $prefix/share/doc/systemtap/examples. | |
7115de82 | 91 | |
773cf74b FCE |
92 | For the normal linux-kernel-module based backend, run "stap" as |
93 | root. If desired, create "stapdev" and "stapusr" entries in | |
94 | /etc/groups. Any users in "stapdev"+"stapusr" will be able to run | |
95 | systemtap as if with root privileges. Users in "stapusr" only may | |
96 | launch (with "staprun") pre-compiled probe modules (created by "stap | |
97 | -p4 ...") that a system administrator copied under | |
98 | /lib/modules/`uname -r`/systemtap. "stapusr" may also be permitted | |
99 | to create arbitrary unprivileged systemtap scripts of their own. | |
100 | See README.unprivileged for additional setup instructions. | |
d90adf0d | 101 | |
44d7915f DM |
102 | To run a simple test. |
103 | # stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}' | |
104 | ||
69a05c66 FCE |
105 | To run the full test suite from the build tree, install dejagnu, |
106 | then run with root privileges: | |
015cb0b7 | 107 | # make installcheck |
7115de82 | 108 | |
773cf74b FCE |
109 | For the prototype dyninst pure-userspace backend, run "stap" as any user. |
110 | % stap --runtime=dyninst -e 'probe process.function("*") { | |
111 | println(pn(), ":", $$parms) }' -c 'ls' | |
112 | ||
69a05c66 FCE |
113 | For the prototype bpf backend, run "stap" as "root" |
114 | # stap --runtime=bpf -e 'probe kernel.function("do_exit") { | |
115 | printf("bye %d\n", pid()) }' | |
116 | ||
117 | ||
7115de82 | 118 | |
203a3d5b | 119 | Tips: |
062f1f1f | 120 | |
034a1d8b | 121 | - By default, systemtap looks for the debug info in these locations: |
e5ec4b02 HN |
122 | /boot/vmlinux-`uname -r` |
123 | /usr/lib/debug/lib/modules/`uname -r`/vmlinux | |
124 | /lib/modules/`uname -r`/vmlinux | |
113187f4 | 125 | /lib/modules/`uname -r`/build/vmlinux |
203a3d5b | 126 | |
b5e66ada | 127 | |
203a3d5b FCE |
128 | Building a kernel.org kernel: |
129 | ||
015cb0b7 FCE |
130 | - Consider applying the utrace kernel patches, if you wish to probe |
131 | user-space applications. http://sourceware.org/systemtap/wiki/utrace | |
db67fe59 FCE |
132 | Or if your kernel is near 3.5, apply the uprobes and related patches |
133 | (see NEWS). Or if your kernel is >= 3.5, enjoy the built-in uprobes. | |
02f582ce | 134 | |
203a3d5b | 135 | - Build the kernel using your normal procedures. Enable |
5cf57358 | 136 | CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS, |
7c65223b | 137 | CONFIG_MODULES, CONFIG_MODULE_UNLOAD, CONFIG_UTRACE if able |
b5e66ada | 138 | - % make modules_install install headers_install |
203a3d5b | 139 | - Boot into the kernel. |
b5e66ada FCE |
140 | |
141 | - If you wish to leave the kernel build tree in place, simply run | |
142 | % stap -r /path/to/kernel/build/tree [...] | |
143 | You're done. | |
144 | ||
145 | - Or else, if you wish to install the kernel build/debuginfo data into | |
146 | a place where systemtap will find it without the "-r" option: | |
147 | % ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build | |
755cdd9b KS |
148 | |
149 | - Instead of using the "-r" option, you can also use the environment | |
150 | variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data. |