]>
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 | |
b1e8cd5d | 19 | - Python for tools which are scripts, such as dtrace(1) |
0d49d7bc FCE |
20 | - root privileges |
21 | ||
062f1f1f FCE |
22 | Installation steps: |
23 | ||
a4d7b379 FCE |
24 | - If equipped with elfutils version 0.178 or later, try using debuginfod |
25 | for automatic debuginfo downloading. This experimental public server | |
26 | may be enough: | |
27 | % export DEBUGINFOD_URLS=https://debuginfod.elfutils.org/ | |
28 | % export DEBUGINFOD_PROGRESS=1 | |
29 | See https://sourceware.org/elfutils/Debuginfod.html for more details. | |
30 | ||
31 | - Otherwise, install any debuginfo packages you need, for kernel | |
32 | and/or userspace. On modern Fedora, # debuginfo-install kernel [...] | |
33 | ||
50958227 FCE |
34 | (Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc. |
35 | variants. Each likely has a corresponding development and debuginfo | |
36 | package.) | |
44d7915f DM |
37 | |
38 | - Install the systemtap package. | |
39 | On modern Fedora, # yum install systemtap systemtap-runtime | |
062f1f1f FCE |
40 | |
41 | Build steps: | |
42 | ||
773cf74b FCE |
43 | - Consider installing the kernel-debuginfo, kernel-devel, gcc and |
44 | dependent packages (or see below if you are building your own | |
45 | kernels from source). If using only the pure-userspace dyninst | |
46 | backend, install gcc and dyninst-devel. | |
47 | ||
7115de82 FCE |
48 | - If available, install your distribution's copy of elfutils and its |
49 | development headers/libraries. | |
113187f4 FCE |
50 | Or if desired, build elfutils separately one time, and install |
51 | it to /usr/local. | |
a4d7b379 | 52 | See https://elfutils.org/ |
9c9af271 FCE |
53 | elfutils version 0.178 introduces automatic debuginfo downloading, |
54 | which can makes systemtap usage easier. | |
ab45bf5d | 55 | |
89d60409 FCE |
56 | - On modern Fedora, install general optional build-requisites: |
57 | # yum-builddep systemtap | |
58 | On modern Debian/Ubuntu, similarly: | |
59 | # apt-get build-dep systemtap | |
60 | ||
ab45bf5d | 61 | - Download systemtap sources: |
a4d7b379 FCE |
62 | https://sourceware.org/systemtap/ftp/releases/ |
63 | https://sourceware.org/systemtap/ftp/snapshots/ | |
062f1f1f | 64 | (or) |
306dd4f8 | 65 | git clone git://sourceware.org/git/systemtap.git |
a4d7b379 | 66 | (or) https://sourceware.org/git/systemtap.git |
ab45bf5d | 67 | |
113187f4 FCE |
68 | - Build systemtap normally: |
69 | % .../configure [other autoconf options] | |
580255b6 FCE |
70 | Add env LDFLAGS=-L/path/ CPPFLAGS=-I/path/ before configure |
71 | to locate libraries in non-system directories. | |
7115de82 | 72 | |
7115de82 FCE |
73 | Consider configuring with "--prefix=DIRECTORY" to specify an |
74 | installation directory other than /usr/local. It can be an ordinary | |
75 | personal directory. | |
76 | ||
034a1d8b | 77 | % make all |
015cb0b7 | 78 | # make install |
7115de82 | 79 | To uninstall systemtap: |
015cb0b7 | 80 | # make uninstall |
7115de82 | 81 | |
c59c41d0 FCE |
82 | Alternately, on a Fedora-like system: |
83 | % make rpm | |
84 | # rpm -i /path/to/rpmbuild/.../systemtap*rpm | |
85 | ||
86 | ||
7115de82 FCE |
87 | - Run systemtap: |
88 | ||
b586f21f FCE |
89 | To run systemtap after installation, add $prefix/bin to your $PATH, or |
90 | refer to $prefix/bin/stap directly. If you keep your build tree | |
91 | around, you can also use the "stap" binary there. | |
92 | ||
93 | Some samples should be available under $prefix/share/doc/systemtap/examples. | |
7115de82 | 94 | |
773cf74b FCE |
95 | For the normal linux-kernel-module based backend, run "stap" as |
96 | root. If desired, create "stapdev" and "stapusr" entries in | |
97 | /etc/groups. Any users in "stapdev"+"stapusr" will be able to run | |
98 | systemtap as if with root privileges. Users in "stapusr" only may | |
99 | launch (with "staprun") pre-compiled probe modules (created by "stap | |
100 | -p4 ...") that a system administrator copied under | |
101 | /lib/modules/`uname -r`/systemtap. "stapusr" may also be permitted | |
102 | to create arbitrary unprivileged systemtap scripts of their own. | |
103 | See README.unprivileged for additional setup instructions. | |
d90adf0d | 104 | |
44d7915f DM |
105 | To run a simple test. |
106 | # stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}' | |
107 | ||
69a05c66 FCE |
108 | To run the full test suite from the build tree, install dejagnu, |
109 | then run with root privileges: | |
015cb0b7 | 110 | # make installcheck |
7115de82 | 111 | |
773cf74b FCE |
112 | For the prototype dyninst pure-userspace backend, run "stap" as any user. |
113 | % stap --runtime=dyninst -e 'probe process.function("*") { | |
114 | println(pn(), ":", $$parms) }' -c 'ls' | |
115 | ||
69a05c66 FCE |
116 | For the prototype bpf backend, run "stap" as "root" |
117 | # stap --runtime=bpf -e 'probe kernel.function("do_exit") { | |
118 | printf("bye %d\n", pid()) }' | |
119 | ||
120 | ||
7115de82 | 121 | |
203a3d5b | 122 | Tips: |
062f1f1f | 123 | |
034a1d8b | 124 | - By default, systemtap looks for the debug info in these locations: |
e5ec4b02 HN |
125 | /boot/vmlinux-`uname -r` |
126 | /usr/lib/debug/lib/modules/`uname -r`/vmlinux | |
127 | /lib/modules/`uname -r`/vmlinux | |
113187f4 | 128 | /lib/modules/`uname -r`/build/vmlinux |
203a3d5b | 129 | |
b5e66ada | 130 | |
203a3d5b FCE |
131 | Building a kernel.org kernel: |
132 | ||
133 | - Build the kernel using your normal procedures. Enable | |
5cf57358 | 134 | CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS, |
a4d7b379 | 135 | CONFIG_MODULES, CONFIG_MODULE_UNLOAD, CONFIG_UPROBES if able |
b5e66ada | 136 | - % make modules_install install headers_install |
203a3d5b | 137 | - Boot into the kernel. |
b5e66ada FCE |
138 | |
139 | - If you wish to leave the kernel build tree in place, simply run | |
140 | % stap -r /path/to/kernel/build/tree [...] | |
141 | You're done. | |
142 | ||
143 | - Or else, if you wish to install the kernel build/debuginfo data into | |
144 | a place where systemtap will find it without the "-r" option: | |
145 | % ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build | |
755cdd9b KS |
146 | |
147 | - Instead of using the "-r" option, you can also use the environment | |
148 | variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data. |