]>
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. | |
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 | 21 | - Install the kernel development and gcc packages. |
44d7915f DM |
22 | On modern Fedora, # yum install kernel-devel-`uname -r` |
23 | ||
50958227 | 24 | - Install any debuginfo packages you need, for kernel and/or userspace. |
44d7915f DM |
25 | On modern Fedora, # debuginfo-install kernel [...] |
26 | ||
50958227 FCE |
27 | (Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc. |
28 | variants. Each likely has a corresponding development and debuginfo | |
29 | package.) | |
44d7915f DM |
30 | |
31 | - Install the systemtap package. | |
32 | On modern Fedora, # yum install systemtap systemtap-runtime | |
062f1f1f FCE |
33 | |
34 | Build steps: | |
35 | ||
7115de82 | 36 | - Install the kernel-debuginfo, kernel-devel, gcc and dependent |
530dc83b | 37 | packages (or see below if you are building your own kernels from source). |
ab45bf5d | 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. | |
45 | See http://fedorahosted.org/elfutils/ | |
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] | |
fffc9716 FCE |
65 | (Note that elfutils > 0.139 requires gcc > 4.0 or else the |
66 | appropriate elfutils-portability.patch.) | |
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 | |
d90adf0d | 89 | Normally, run "stap" as root. If desired, create "stapdev" and |
015cb0b7 FCE |
90 | "stapusr" entries in /etc/groups. Any users in "stapdev"+"stapusr" will |
91 | be able to run systemtap as if with root privileges. Users in "stapusr" | |
92 | only may launch (with "staprun") pre-compiled probe modules (created | |
d90adf0d | 93 | by "stap -p4 ...") that a system administrator copied under |
015cb0b7 FCE |
94 | /lib/modules/`uname -r`/systemtap. "stapusr" may also be permitted to |
95 | create arbitrary unprivileged systemtap scripts of their own. See | |
96 | README.unprivileged for additional setup instructions. | |
d90adf0d | 97 | |
44d7915f DM |
98 | To run a simple test. |
99 | # stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}' | |
100 | ||
d90adf0d | 101 | To run the full test suite from the build tree. |
015cb0b7 | 102 | # make installcheck |
7115de82 FCE |
103 | |
104 | ||
203a3d5b | 105 | Tips: |
062f1f1f | 106 | |
034a1d8b | 107 | - By default, systemtap looks for the debug info in these locations: |
e5ec4b02 HN |
108 | /boot/vmlinux-`uname -r` |
109 | /usr/lib/debug/lib/modules/`uname -r`/vmlinux | |
110 | /lib/modules/`uname -r`/vmlinux | |
113187f4 | 111 | /lib/modules/`uname -r`/build/vmlinux |
203a3d5b | 112 | |
b5e66ada | 113 | |
203a3d5b FCE |
114 | Building a kernel.org kernel: |
115 | ||
015cb0b7 FCE |
116 | - Consider applying the utrace kernel patches, if you wish to probe |
117 | user-space applications. http://sourceware.org/systemtap/wiki/utrace | |
02f582ce | 118 | |
203a3d5b | 119 | - Build the kernel using your normal procedures. Enable |
5cf57358 | 120 | CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS, |
7c65223b | 121 | CONFIG_MODULES, CONFIG_MODULE_UNLOAD, CONFIG_UTRACE if able |
b5e66ada | 122 | - % make modules_install install headers_install |
203a3d5b | 123 | - Boot into the kernel. |
b5e66ada FCE |
124 | |
125 | - If you wish to leave the kernel build tree in place, simply run | |
126 | % stap -r /path/to/kernel/build/tree [...] | |
127 | You're done. | |
128 | ||
129 | - Or else, if you wish to install the kernel build/debuginfo data into | |
130 | a place where systemtap will find it without the "-r" option: | |
131 | % ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build | |
755cdd9b KS |
132 | |
133 | - Instead of using the "-r" option, you can also use the environment | |
134 | variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data. | |
135 |