Debian Codegraph @

doc/SystemTap_Beginners_Guide/en-US/Installation.xml

raw
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>