| 1 |
<?xml version='1.0'?> |
| 2 |
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
| 3 |
]> |
| 4 |
|
| 5 |
|
| 6 |
<section id="using-setup"> |
| 7 |
<title>Installation and Setup</title> |
| 8 |
<remark> |
| 9 |
required packages, installation thru yum, repos (?); possibly, a script to install all required packages |
| 10 |
</remark> |
| 11 |
|
| 12 |
<remark> |
| 13 |
notes in ~/Desktop/SystemTap/aug21chatlog and ~/Desktop/SystemTap/noted_wcohenmeeting |
| 14 |
</remark> |
| 15 |
<indexterm> |
| 16 |
<primary>Installation</primary> |
| 17 |
<secondary>Setup and Installation</secondary> |
| 18 |
</indexterm> |
| 19 |
|
| 20 |
<indexterm> |
| 21 |
<primary>Setup and Installation</primary> |
| 22 |
</indexterm> |
| 23 |
<para>To deploy SystemTap, install the SystemTap packages along |
| 24 |
with the corresponding set of <package>-devel</package>, |
| 25 |
<package>-debuginfo</package>, and <package>-debuginfo-common</package> |
| 26 |
packages for your kernel. If your system has multiple kernels installed and |
| 27 |
you intend to use SystemTap on more than one of them, also |
| 28 |
install the <package>-devel</package> and <package>-debuginfo</package> |
| 29 |
packages for <emphasis>each</emphasis> of those kernel versions. |
| 30 |
</para> |
| 31 |
|
| 32 |
<para>The following sections discuss the installation procedures in greater detail. |
| 33 |
</para> |
| 34 |
|
| 35 |
<important> |
| 36 |
<title>Important</title> <para>Many users confuse |
| 37 |
<package>-debuginfo</package> with <package>-debug</package>. Remember |
| 38 |
that the deployment of SystemTap requires the installation of the |
| 39 |
<package>-debuginfo</package> package of the kernel, not the |
| 40 |
<package>-debug</package> version of the kernel.</para> |
| 41 |
</important> |
| 42 |
|
| 43 |
<section id="installproper"> |
| 44 |
<title>Installing SystemTap</title> |
| 45 |
|
| 46 |
<para>To deploy SystemTap, install the following RPM packages: |
| 47 |
</para> |
| 48 |
<indexterm> |
| 49 |
<primary>Installation</primary> |
| 50 |
<secondary>systemtap package</secondary> |
| 51 |
</indexterm> |
| 52 |
|
| 53 |
<indexterm> |
| 54 |
<primary>systemtap package</primary> |
| 55 |
</indexterm> |
| 56 |
|
| 57 |
|
| 58 |
<!-- next 2 indexterms for systemtap-runtime package --> |
| 59 |
|
| 60 |
<indexterm> |
| 61 |
<primary>Installation</primary> |
| 62 |
<secondary>systemtap-runtime package</secondary> |
| 63 |
</indexterm> |
| 64 |
|
| 65 |
<indexterm> |
| 66 |
<primary>systemtap-runtime package</primary> |
| 67 |
</indexterm> |
| 68 |
<itemizedlist> |
| 69 |
<listitem><para><package>systemtap</package></para></listitem> |
| 70 |
<listitem><para><package>systemtap-runtime</package></para></listitem> |
| 71 |
</itemizedlist> |
| 72 |
|
| 73 |
<para> |
| 74 |
To do so, run the following command as root: |
| 75 |
</para> |
| 76 |
|
| 77 |
<screen><command>yum install systemtap systemtap-runtime</command></screen> |
| 78 |
|
| 79 |
<para> |
| 80 |
Note that before using SystemTap, you still need to install the required |
| 81 |
kernel information packages. On modern systems, run the following command |
| 82 |
as root to install these packages: |
| 83 |
</para> |
| 84 |
|
| 85 |
<screen><command>stap-prep</command></screen> |
| 86 |
|
| 87 |
<para> |
| 88 |
If this command does not work, try manual installation as described below. |
| 89 |
</para> |
| 90 |
|
| 91 |
</section> |
| 92 |
|
| 93 |
<section id="install-kinfo"> |
| 94 |
<title>Installing Required Kernel Information Packages Manually</title> |
| 95 |
<indexterm> |
| 96 |
<primary>Installation</primary> |
| 97 |
<secondary>required packages</secondary> |
| 98 |
</indexterm> |
| 99 |
|
| 100 |
<indexterm> |
| 101 |
<primary>required packages</primary> |
| 102 |
</indexterm> |
| 103 |
<indexterm> |
| 104 |
<primary>packages required to run SystemTap</primary> |
| 105 |
</indexterm> |
| 106 |
<indexterm> |
| 107 |
<primary>RPMs required to run SystemTap</primary> |
| 108 |
</indexterm> |
| 109 |
<indexterm> |
| 110 |
<primary>Installation</primary> |
| 111 |
<secondary>kernel information packages</secondary> |
| 112 |
</indexterm> |
| 113 |
|
| 114 |
<indexterm> |
| 115 |
<primary>kernel information packages</primary> |
| 116 |
</indexterm> |
| 117 |
<para> |
| 118 |
SystemTap needs information about the kernel in order to place instrumentation in it (in other words, probe it). This |
| 119 |
information also allows SystemTap to generate the code for the instrumentation. |
| 120 |
</para> |
| 121 |
<para> |
| 122 |
The required information is contained |
| 123 |
in the matching <package>-devel</package>, <package>-debuginfo</package>, and <package>-debuginfo-common</package> |
| 124 |
packages for your kernel. The necessary <package>-devel</package> and <package>-debuginfo</package> packages for the ordinary |
| 125 |
"vanilla" kernel are as follows: |
| 126 |
</para> |
| 127 |
|
| 128 |
<itemizedlist> |
| 129 |
<listitem><para><package>kernel-debuginfo</package></para></listitem> |
| 130 |
<listitem><para><package>kernel-debuginfo-common</package></para></listitem> |
| 131 |
<listitem><para><package>kernel-devel</package></para></listitem> |
| 132 |
</itemizedlist> |
| 133 |
|
| 134 |
<para> |
| 135 |
Likewise, the necessary packages for the PAE kernel are |
| 136 |
<package>kernel-PAE-debuginfo</package>, <package>kernel-PAE-debuginfo-common</package>, |
| 137 |
and <package>kernel-PAE-devel</package>. |
| 138 |
</para> |
| 139 |
|
| 140 |
<indexterm> |
| 141 |
<primary>Installation</primary> |
| 142 |
<secondary>kernel version, determining the</secondary> |
| 143 |
</indexterm> |
| 144 |
|
| 145 |
<indexterm> |
| 146 |
<primary>kernel version, determining the</primary> |
| 147 |
</indexterm> |
| 148 |
|
| 149 |
<indexterm> |
| 150 |
<primary>determining the kernel version</primary> |
| 151 |
</indexterm> |
| 152 |
<indexterm> |
| 153 |
<primary>uname -r</primary> |
| 154 |
</indexterm> |
| 155 |
<para> To determine what kernel your system is currently using, use:</para> |
| 156 |
|
| 157 |
<screen>uname -r</screen> |
| 158 |
|
| 159 |
<para> |
| 160 |
For example, if you intend to use SystemTap on kernel version <emphasis>2.6.18-53.el5</emphasis> on an <emphasis>i686</emphasis> machine, |
| 161 |
download and install the following RPM packages: |
| 162 |
</para> |
| 163 |
|
| 164 |
<itemizedlist> |
| 165 |
<listitem><para><package>kernel-debuginfo-2.6.18-53.1.13.el5.i686.rpm</package></para></listitem> |
| 166 |
<listitem><para><package>kernel-debuginfo-common-2.6.18-53.1.13.el5.i686.rpm</package></para></listitem> |
| 167 |
<listitem><para><package>kernel-devel-2.6.18-53.1.13.el5.i686.rpm</package></para></listitem> |
| 168 |
</itemizedlist> |
| 169 |
|
| 170 |
<important> |
| 171 |
<title>Important</title> |
| 172 |
|
| 173 |
<para> |
| 174 |
The version, variant, and architecture of the <package>-devel</package>, <package>-debuginfo</package> and |
| 175 |
<package>-debuginfo-common</package> packages must match the kernel you wish to probe with SystemTap <emphasis>exactly</emphasis>. |
| 176 |
</para> |
| 177 |
</important> |
| 178 |
|
| 179 |
|
| 180 |
<para> |
| 181 |
The easiest way to install the required kernel information |
| 182 |
packages is through <command>yum install</command> and |
| 183 |
<command>debuginfo-install</command> commands. |
| 184 |
The <command>debuginfo-install</command> command is included with |
| 185 |
later versions of the <package>yum-utils</package> |
| 186 |
package (for example, version 1.1.10) and also requires |
| 187 |
an appropriate <command>yum</command> repository from |
| 188 |
which to download and install |
| 189 |
<package>-debuginfo</package> and <package>-debuginfo-common</package> |
| 190 |
packages. You can install the required |
| 191 |
<package>-devel</package>, |
| 192 |
<package>-debuginfo</package>, and |
| 193 |
<package>-debuginfo-common</package> packages for your |
| 194 |
kernel. |
| 195 |
</para> |
| 196 |
|
| 197 |
|
| 198 |
<!-- next 2 indexterms for rhelchannels.sh --> |
| 199 |
|
| 200 |
<para> |
| 201 |
When the appropriate software repositories are enabled, |
| 202 |
install the corresponding packages for a specific kernel |
| 203 |
with the following commands: |
| 204 |
</para> |
| 205 |
|
| 206 |
<screen><command>yum install <replaceable>kernelname</replaceable>-devel-<replaceable>version</replaceable></command> |
| 207 |
<command>debuginfo-install <replaceable>kernelname</replaceable>-<replaceable>version</replaceable></command></screen> |
| 208 |
|
| 209 |
<para> |
| 210 |
Replace <replaceable>kernelname</replaceable> with the appropriate kernel variant name |
| 211 |
(for example, <option>kernel-PAE</option>), and <replaceable>version</replaceable> |
| 212 |
with the target kernel's version. For example, to install the required kernel information packages for |
| 213 |
the <systemitem>kernel-PAE-2.6.18-53.1.13.el5</systemitem> kernel, run: |
| 214 |
</para> |
| 215 |
|
| 216 |
<screen><command>yum install kernel-PAE-devel-2.6.18-53.1.13.el5</command> |
| 217 |
<command>debuginfo-install kernel-PAE-2.6.18-53.1.13.el5</command></screen> |
| 218 |
|
| 219 |
<para> |
| 220 |
Once you have manually downloaded the required packages to the machine, run the following command as root to install them: |
| 221 |
</para> |
| 222 |
<screen><command>rpm --force -ivh <replaceable>package_names</replaceable></command></screen> |
| 223 |
|
| 224 |
</section> |
| 225 |
|
| 226 |
|
| 227 |
<section id="testing"> |
| 228 |
<title>Initial Testing</title> |
| 229 |
<indexterm> |
| 230 |
<primary>Installation</primary> |
| 231 |
<secondary>initial testing</secondary> |
| 232 |
</indexterm> |
| 233 |
|
| 234 |
<indexterm> |
| 235 |
<primary>initial testing</primary> |
| 236 |
</indexterm> |
| 237 |
|
| 238 |
<indexterm> |
| 239 |
<primary>testing, initial</primary> |
| 240 |
</indexterm> |
| 241 |
<para>If you are currently using the kernel you intend to probe with |
| 242 |
SystemTap, you can immediately test whether the deployment was |
| 243 |
successful. If not, you restart the system and load the appropriate |
| 244 |
kernel. |
| 245 |
</para> |
| 246 |
|
| 247 |
<para> |
| 248 |
To start the test, run the following command: |
| 249 |
</para> |
| 250 |
|
| 251 |
<screen><command>stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'</command></screen> |
| 252 |
|
| 253 |
<para> |
| 254 |
This command instructs SystemTap |
| 255 |
to print <computeroutput>read performed</computeroutput> and then exit |
| 256 |
properly once a virtual file system read is detected. If the SystemTap |
| 257 |
deployment was successful, it prints output similar to the |
| 258 |
following: |
| 259 |
</para> |
| 260 |
<!-- <para>To start the test, run the command <command>stap -v -e 'probe vfs.read |
| 261 |
{exit()}'</command>. This command simply instructs SystemTap to exit |
| 262 |
properly once a virtual file system read is detected. If the SystemTap |
| 263 |
deployment was successful, you should get output very similar to the |
| 264 |
following: |
| 265 |
</para>--> |
| 266 |
|
| 267 |
<screen>Pass 1: parsed user script and 45 library script(s) in 340usr/0sys/358real ms. |
| 268 |
Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 290usr/260sys/568real ms. |
| 269 |
Pass 3: translated to C into "/tmp/stapiArgLX/stap_e5886fa50499994e6a87aacdc43cd392_399.c" in 490usr/430sys/938real ms. |
| 270 |
Pass 4: compiled C into "stap_e5886fa50499994e6a87aacdc43cd392_399.ko" in 3310usr/430sys/3714real ms. |
| 271 |
Pass 5: starting run. |
| 272 |
read performed |
| 273 |
Pass 5: run completed in 10usr/40sys/73real ms.</screen> |
| 274 |
|
| 275 |
<para> The last three lines of the output (beginning with |
| 276 |
<computeroutput>Pass 5</computeroutput>) indicate that SystemTap was able to |
| 277 |
successfully create the instrumentation to probe the kernel, run the |
| 278 |
instrumentation, detect the event being probed (in this case, a virtual file |
| 279 |
system read), and execute a valid handler (print text then close it with no errors). |
| 280 |
</para> |
| 281 |
|
| 282 |
</section> |
| 283 |
</section> |