]>
Commit | Line | Data |
---|---|---|
0d49d7bc FCE |
1 | systemtap: a linux trace/probe tool |
2 | ||
3 | Visit the project web site at <http://sources.redhat.com/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 | ||
9e0abebd | 12 | - linux kernel with kprobes (mainline 2.6.11+ or backport) |
d90adf0d | 13 | - kernel module build environment (kernel-devel rpm) |
27cffb52 FCE |
14 | - kernel debugging information (kernel-debuginfo rpm) |
15 | - C compiler (same as what kernel was compiled with) | |
d90adf0d | 16 | - elfutils with libdwfl for debugging information parsing |
0d49d7bc FCE |
17 | - root privileges |
18 | ||
062f1f1f FCE |
19 | Installation steps: |
20 | ||
50958227 FCE |
21 | - Install the kernel development and gcc packages. |
22 | - Install any debuginfo packages you need, for kernel and/or userspace. | |
23 | (Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc. | |
24 | variants. Each likely has a corresponding development and debuginfo | |
25 | package.) | |
062f1f1f FCE |
26 | - Install the systemtap package, if one already exists. |
27 | ||
28 | Build steps: | |
29 | ||
7115de82 | 30 | - Install the kernel-debuginfo, kernel-devel, gcc and dependent |
530dc83b | 31 | packages (or see below if you are building your own kernels from source). |
ab45bf5d | 32 | |
7115de82 FCE |
33 | - If available, install your distribution's copy of elfutils and its |
34 | development headers/libraries. | |
35 | Or if desired, download an elfutils source release to build in | |
113187f4 FCE |
36 | "bundled mode" (below), and untar it into some new directory. |
37 | Or if desired, build elfutils separately one time, and install | |
38 | it to /usr/local. | |
39 | See http://fedorahosted.org/elfutils/ | |
ab45bf5d FCE |
40 | |
41 | - Download systemtap sources: | |
42 | http://sources.redhat.com/systemtap/ftp/releases/ | |
43 | http://sources.redhat.com/systemtap/ftp/snapshots/ | |
062f1f1f | 44 | (or) |
02c58b37 FCE |
45 | git clone git://sources.redhat.com/git/systemtap.git |
46 | (or) http://sources.redhat.com/git/systemtap.git | |
ab45bf5d | 47 | |
113187f4 FCE |
48 | - Build systemtap normally: |
49 | % .../configure [other autoconf options] | |
50 | Or, with build it with a bundled internal copy of elfutils: | |
51 | % .../configure --with-elfutils=ELFUTILS-SOURCE-DIR [other autoconf options] | |
7115de82 | 52 | |
113187f4 FCE |
53 | Consider configuring with "--enable-dejazilla" to automatically |
54 | contribute to our public test result database. | |
55 | ||
7115de82 FCE |
56 | Consider configuring with "--prefix=DIRECTORY" to specify an |
57 | installation directory other than /usr/local. It can be an ordinary | |
58 | personal directory. | |
59 | ||
034a1d8b | 60 | % make all |
113187f4 | 61 | % sudo make install |
034a1d8b | 62 | |
7115de82 FCE |
63 | To uninstall systemtap: |
64 | % sudo make uninstall | |
65 | ||
66 | - Run systemtap: | |
67 | ||
b586f21f FCE |
68 | To run systemtap after installation, add $prefix/bin to your $PATH, or |
69 | refer to $prefix/bin/stap directly. If you keep your build tree | |
70 | around, you can also use the "stap" binary there. | |
71 | ||
72 | Some samples should be available under $prefix/share/doc/systemtap/examples. | |
7115de82 | 73 | |
d90adf0d FCE |
74 | Normally, run "stap" as root. If desired, create "stapdev" and |
75 | "stapusr" entries in /etc/groups. Any users in "stapdev" will be | |
76 | able to run systemtap as if with root privileges. Users in "stapusr" | |
77 | can only launch (with "staprun") pre-compiled probe modules (created | |
78 | by "stap -p4 ...") that a system administrator copied under | |
79 | /lib/modules/`uname -r`/systemtap. | |
80 | ||
81 | To run the full test suite from the build tree. | |
82 | % sudo make installcheck | |
7115de82 FCE |
83 | |
84 | ||
203a3d5b | 85 | Tips: |
062f1f1f | 86 | |
034a1d8b | 87 | - By default, systemtap looks for the debug info in these locations: |
e5ec4b02 HN |
88 | /boot/vmlinux-`uname -r` |
89 | /usr/lib/debug/lib/modules/`uname -r`/vmlinux | |
90 | /lib/modules/`uname -r`/vmlinux | |
113187f4 | 91 | /lib/modules/`uname -r`/build/vmlinux |
203a3d5b | 92 | |
b5e66ada | 93 | |
203a3d5b FCE |
94 | Building a kernel.org kernel: |
95 | ||
96 | - Build the kernel using your normal procedures. Enable | |
5cf57358 FCE |
97 | CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS, |
98 | CONFIG_MODULES, CONFIG_MODULES_UNLOAD | |
b5e66ada | 99 | - % make modules_install install headers_install |
203a3d5b | 100 | - Boot into the kernel. |
b5e66ada FCE |
101 | |
102 | - If you wish to leave the kernel build tree in place, simply run | |
103 | % stap -r /path/to/kernel/build/tree [...] | |
104 | You're done. | |
105 | ||
106 | - Or else, if you wish to install the kernel build/debuginfo data into | |
107 | a place where systemtap will find it without the "-r" option: | |
108 | % ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build | |
755cdd9b KS |
109 | |
110 | - Instead of using the "-r" option, you can also use the environment | |
111 | variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data. | |
112 |