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