| 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 |
<section id="cross-compiling"> |
| 6 |
<title>Generating Instrumentation for Other Computers</title> |
| 7 |
<indexterm> |
| 8 |
<primary>cross-instrumentation</primary> |
| 9 |
<secondary>building kernel modules from SystemTap scripts</secondary> |
| 10 |
</indexterm> |
| 11 |
<indexterm> |
| 12 |
<primary>cross-instrumentation</primary> |
| 13 |
<secondary>generating instrumentation from SystemTap scripts</secondary> |
| 14 |
</indexterm> |
| 15 |
<remark> |
| 16 |
cross-compiling script from here: |
| 17 |
http://sourceware.org/ml/systemtap/2008-q3/msg00310.html |
| 18 |
</remark> |
| 19 |
|
| 20 |
<indexterm> |
| 21 |
<primary>kernel modules from SystemTap scripts, building</primary> |
| 22 |
</indexterm> |
| 23 |
<indexterm> |
| 24 |
<primary>building kernel modules from SystemTap scripts</primary> |
| 25 |
</indexterm> |
| 26 |
<indexterm> |
| 27 |
<primary>instrumentation modules from SystemTap scripts, building</primary> |
| 28 |
</indexterm> |
| 29 |
<indexterm> |
| 30 |
<primary>building instrumentation modules from SystemTap scripts</primary> |
| 31 |
</indexterm> |
| 32 |
<indexterm> |
| 33 |
<primary>compiling instrumentation/kernel modules from SystemTap scripts</primary> |
| 34 |
</indexterm> |
| 35 |
|
| 36 |
<indexterm> |
| 37 |
<primary>cross-compiling</primary> |
| 38 |
</indexterm> |
| 39 |
<remark> |
| 40 |
above; add short description, significance, howto, script (test first) |
| 41 |
</remark> |
| 42 |
|
| 43 |
<para> |
| 44 |
When users run a SystemTap script, SystemTap builds a kernel module out of |
| 45 |
that script. SystemTap then loads the module into the kernel, allowing it to |
| 46 |
extract the specified data directly from the kernel (refer to |
| 47 |
<xref linkend="systemtapsession"/> in |
| 48 |
<xref linkend="understanding-architecture-tools"/> for more information). |
| 49 |
</para> |
| 50 |
|
| 51 |
<para> |
| 52 |
Normally, however, SystemTap scripts can only be run on systems where SystemTap is deployed (as in <xref linkend="using-setup"/>). This could mean that if you want to run SystemTap on ten systems, you would need to deploy SystemTap on <emphasis>all</emphasis> those systems. In some cases, this may be neither feasible nor desired. For instance, corporate policy may prohibit an administrator from installing RPM packages that provide compilers or debug information on specific machines, and thus prevent the deployment of SystemTap. To work around this problem, SystemTap allows you to use <firstterm>cross-instrumentation</firstterm>. |
| 53 |
</para> |
| 54 |
|
| 55 |
<para> |
| 56 |
Cross-instrumentation is the process of generating SystemTap instrumentation module from a SystemTap script on one computer to be used on another computer. This process offers the following benefits: |
| 57 |
</para> |
| 58 |
<indexterm> |
| 59 |
<primary>cross-instrumentation</primary> |
| 60 |
<secondary>advantages of</secondary> |
| 61 |
</indexterm> |
| 62 |
|
| 63 |
<indexterm> |
| 64 |
<primary>advantages of cross-instrumentation</primary> |
| 65 |
</indexterm> |
| 66 |
|
| 67 |
<itemizedlist> |
| 68 |
<listitem> |
| 69 |
<para> |
| 70 |
The kernel information packages for various machines can be installed on a single <emphasis>host machine</emphasis>. |
| 71 |
</para> |
| 72 |
</listitem> |
| 73 |
|
| 74 |
<listitem> |
| 75 |
<para> |
| 76 |
Each <emphasis>target machine</emphasis> only needs one RPM package to be installed in order to use the generated SystemTap instrumentation module: the <package>systemtap-runtime</package> package. |
| 77 |
</para> |
| 78 |
</listitem> |
| 79 |
</itemizedlist> |
| 80 |
|
| 81 |
<!-- |
| 82 |
|
| 83 |
<para> |
| 84 |
Such a task does not scale well as the number of systems you are monitoring increases. As such, if you need to run a SystemTap script against a wide number of machines, you can simplify your deployment and monitoring through <firstterm>cross-instrumentation</firstterm>. |
| 85 |
</para> |
| 86 |
|
| 87 |
<para> |
| 88 |
<firstterm>Cross-instrumentation</firstterm> is the process of building the resulting kernel module from a SystemTap script on a <emphasis>host</emphasis> machine to be loaded on another <emphasis>target machine</emphasis>. In a manner of speaking, this process allows you to "run" SystemTap scripts on a machine without having to install the necessary debug RPMs for its kernel. |
| 89 |
</para> |
| 90 |
|
| 91 |
|
| 92 |
<para> |
| 93 |
To illustrate; Tom has 25 systems, all of which have the same kernel. If Tom wants to run the SystemTap <filename>script.stp</filename> on all of them, he could install SystemTap and the necessary debug RPMs <emphasis>on each of the 25 machines</emphasis>. This is a tedious enough task to perform on 25 systems; what more if each system had a different kernel? |
| 94 |
</para> |
| 95 |
Alternatively, however, Tom can simply perform cross-instrumentation; this allows him to simply deploy SystemTap fully on one machine, build the necessary kernel module from <filename>script.stp</filename> on that machine, and load that module on each of the other systems. |
| 96 |
</para> |
| 97 |
|
| 98 |
--> |
| 99 |
|
| 100 |
<para> |
| 101 |
For the sake of simplicity, the following terms are used |
| 102 |
throughout this section: |
| 103 |
</para> |
| 104 |
|
| 105 |
<itemizedlist> |
| 106 |
<listitem> |
| 107 |
<para> |
| 108 |
<indexterm> |
| 109 |
<primary>cross-instrumentation</primary> |
| 110 |
<secondary>instrumentation module</secondary> |
| 111 |
</indexterm> |
| 112 |
|
| 113 |
<indexterm> |
| 114 |
<primary>instrumentation module</primary> |
| 115 |
<secondary>cross-instrumentation</secondary> |
| 116 |
</indexterm> |
| 117 |
<emphasis>Instrumentation module</emphasis> — the |
| 118 |
kernel module built from a SystemTap script. The |
| 119 |
<emphasis>SystemTap module</emphasis> is built on the <emphasis>host |
| 120 |
system</emphasis>, and will be loaded on the <emphasis>target |
| 121 |
kernel</emphasis> of <emphasis>target |
| 122 |
system</emphasis>. |
| 123 |
</para> |
| 124 |
</listitem> |
| 125 |
|
| 126 |
<listitem> |
| 127 |
<para> |
| 128 |
<indexterm> |
| 129 |
<primary>cross-instrumentation</primary> |
| 130 |
<secondary>host system</secondary> |
| 131 |
</indexterm> |
| 132 |
|
| 133 |
<indexterm> |
| 134 |
<primary>host system</primary> |
| 135 |
<secondary>cross-instrumentation</secondary> |
| 136 |
</indexterm> |
| 137 |
<emphasis>Host system</emphasis> — the system on |
| 138 |
which you compile the <emphasis>instrumentation modules</emphasis> from SystemTap |
| 139 |
scripts in order to load them on <emphasis>target |
| 140 |
systems</emphasis>. |
| 141 |
</para> |
| 142 |
</listitem> |
| 143 |
|
| 144 |
<listitem> |
| 145 |
<para> |
| 146 |
<indexterm> |
| 147 |
<primary>cross-instrumentation</primary> |
| 148 |
<secondary>target system</secondary> |
| 149 |
</indexterm> |
| 150 |
|
| 151 |
<indexterm> |
| 152 |
<primary>target system</primary> |
| 153 |
<secondary>cross-instrumentation</secondary> |
| 154 |
</indexterm> |
| 155 |
|
| 156 |
<emphasis>Target system</emphasis> — the system for which you |
| 157 |
are building the <emphasis>instrumentation modules</emphasis> from |
| 158 |
SystemTap scripts. |
| 159 |
</para> |
| 160 |
</listitem> |
| 161 |
|
| 162 |
<listitem> |
| 163 |
<para> |
| 164 |
<indexterm> |
| 165 |
<primary>cross-instrumentation</primary> |
| 166 |
<secondary>target kernel</secondary> |
| 167 |
</indexterm> |
| 168 |
|
| 169 |
<indexterm> |
| 170 |
<primary>target kernel</primary> |
| 171 |
<secondary>cross-instrumentation</secondary> |
| 172 |
</indexterm> |
| 173 |
<emphasis>Target kernel</emphasis> — the kernel of |
| 174 |
the <emphasis>target system</emphasis>. This is the kernel on which |
| 175 |
you intend to load or run the <emphasis>instrumentation |
| 176 |
module</emphasis>. |
| 177 |
</para> |
| 178 |
</listitem> |
| 179 |
</itemizedlist> |
| 180 |
|
| 181 |
<!-- |
| 182 |
running a SystemTap script on a target system where SystemTap is not installed. Normally, to run a SystemTap script on a system, you need to deploy SystemTap on it first (as in <xref linkend="installproper"/>). |
| 183 |
</para> --> |
| 184 |
|
| 185 |
<!-- <para> |
| 186 |
This section teaches you how to deploy SystemTap on a host machine, from which you can create the necessary kernel module/s to be loaded on client machines. These kernel modules are built from SystemTap scripts you wish to run on the client machine. |
| 187 |
</para>--> |
| 188 |
|
| 189 |
<para> |
| 190 |
To configure a host system and target systems, complete the following steps: |
| 191 |
</para> |
| 192 |
|
| 193 |
<procedure id="preppingxcompile"> |
| 194 |
<indexterm> |
| 195 |
<primary>cross-instrumentation</primary> |
| 196 |
<secondary>configuration</secondary> |
| 197 |
<tertiary>host system and target system</tertiary> |
| 198 |
</indexterm> |
| 199 |
|
| 200 |
<indexterm> |
| 201 |
<primary>host system and target system</primary> |
| 202 |
<secondary>cross-instrumentation</secondary> |
| 203 |
<tertiary>configuration</tertiary> |
| 204 |
</indexterm> |
| 205 |
|
| 206 |
<indexterm> |
| 207 |
<primary>target system and host system</primary> |
| 208 |
<secondary>configuration</secondary> |
| 209 |
</indexterm> |
| 210 |
<step> |
| 211 |
<para> |
| 212 |
Install the <package>systemtap-runtime</package> package on each |
| 213 |
<emphasis>target system</emphasis>. |
| 214 |
</para> |
| 215 |
</step> |
| 216 |
|
| 217 |
<step> |
| 218 |
<para> |
| 219 |
Determine the kernel running on each <emphasis>target system</emphasis> |
| 220 |
by running the <command>uname -r</command> command on each of these systems. |
| 221 |
</para> |
| 222 |
</step> |
| 223 |
|
| 224 |
<step> |
| 225 |
<para> |
| 226 |
Install SystemTap on the <emphasis>host system</emphasis>. |
| 227 |
You will be building the <emphasis>instrumentation |
| 228 |
module</emphasis> for the <emphasis>target |
| 229 |
systems</emphasis> on the <emphasis>host system</emphasis>. |
| 230 |
For instructions on how to install SystemTap, refer |
| 231 |
to <xref linkend="installproper"/>. |
| 232 |
</para> |
| 233 |
</step> |
| 234 |
|
| 235 |
<step> |
| 236 |
<para> |
| 237 |
Using the <emphasis>target kernel</emphasis> version determined earlier, |
| 238 |
install the <emphasis>target kernel</emphasis> and related RPM packages on the |
| 239 |
<emphasis>host system</emphasis> as described in <xref |
| 240 |
linkend="install-kinfo"/>. If multiple <emphasis>target |
| 241 |
systems</emphasis> use different <emphasis>target kernels</emphasis>, |
| 242 |
repeat this step for each different kernel used on the |
| 243 |
<emphasis>target systems</emphasis>. |
| 244 |
</para> |
| 245 |
</step> |
| 246 |
|
| 247 |
</procedure> |
| 248 |
|
| 249 |
<para> |
| 250 |
After completing these steps, you can now build the |
| 251 |
<emphasis>instrumentation module</emphasis> (for any <emphasis>target |
| 252 |
system</emphasis>) on the <emphasis>host system</emphasis>. |
| 253 |
</para> |
| 254 |
|
| 255 |
<para> |
| 256 |
To build the <emphasis>instrumentation module</emphasis>, run the following |
| 257 |
command on the <emphasis>host system</emphasis> (be sure to specify the |
| 258 |
appropriate values): |
| 259 |
</para> |
| 260 |
|
| 261 |
<screen><command>stap -p4 -r <replaceable>kernel_version</replaceable> <replaceable>script</replaceable> -m <replaceable>module_name</replaceable></command></screen> |
| 262 |
|
| 263 |
<para> |
| 264 |
Here, <replaceable>kernel_version</replaceable> refers to |
| 265 |
the version of the <emphasis>target kernel</emphasis> (the output of |
| 266 |
the <command>uname -r</command> command on the target machine), |
| 267 |
<replaceable>script</replaceable> refers to the script to |
| 268 |
be converted into the <emphasis>instrumentation module</emphasis>, and |
| 269 |
<replaceable>module_name</replaceable> is the desired |
| 270 |
name of the <emphasis>instrumentation module</emphasis>. |
| 271 |
</para> |
| 272 |
|
| 273 |
<note> |
| 274 |
<title>Note</title> |
| 275 |
<indexterm> |
| 276 |
<primary>uname -m</primary> |
| 277 |
</indexterm> |
| 278 |
|
| 279 |
<indexterm> |
| 280 |
<primary>determining architecture notation</primary> |
| 281 |
</indexterm> |
| 282 |
|
| 283 |
<indexterm> |
| 284 |
<primary>architecture notation, determining</primary> |
| 285 |
</indexterm> |
| 286 |
<para> |
| 287 |
To determine the architecture notation of a running kernel, you can run the following command: |
| 288 |
</para> |
| 289 |
|
| 290 |
<screen><command>uname -m</command></screen> |
| 291 |
</note> |
| 292 |
|
| 293 |
<para> |
| 294 |
Once the <emphasis>instrumentation module</emphasis> is compiled, copy |
| 295 |
it to the <emphasis>target system</emphasis> and then load it using: |
| 296 |
</para> |
| 297 |
|
| 298 |
<screen><command>staprun <replaceable>module_name</replaceable>.ko</command></screen> |
| 299 |
|
| 300 |
<para> |
| 301 |
For example, to create the |
| 302 |
<emphasis>instrumentation module</emphasis> <filename>simple.ko</filename> |
| 303 |
from a SystemTap script named |
| 304 |
<filename>simple.stp</filename> for the <emphasis>target kernel</emphasis> |
| 305 |
2.6.18-92.1.10.el5 (on x86_64 architecture), use the following command: |
| 306 |
</para> |
| 307 |
|
| 308 |
<screen><command>stap -r 2.6.18-92.1.10.el5 -e 'probe vfs.read {exit()}' -m simple</command></screen> |
| 309 |
|
| 310 |
<para> |
| 311 |
This creates a module named <filename>simple.ko</filename>. To use this |
| 312 |
<emphasis>instrumentation module</emphasis>, |
| 313 |
copy it to the <emphasis>target system</emphasis> and run the following |
| 314 |
command (on the <emphasis>target system</emphasis>): |
| 315 |
</para> |
| 316 |
|
| 317 |
<screen><command>staprun simple.ko</command></screen> |
| 318 |
|
| 319 |
<!--<procedure id="preppingxcompile"> |
| 320 |
<title>Preparing for a Cross-Compile</title> |
| 321 |
|
| 322 |
<step> |
| 323 |
<para>Note the version of the target system's kernel on which you wish to use SystemTap. You can do this by logging onto the target system and running <command>uname -r</command> (assuming the system is running the kernel on which you wish to use SystemTap), or by inspecting <filename>/boot</filename>.</para> |
| 324 |
</step> --> |
| 325 |
<important> |
| 326 |
<title>Important</title> |
| 327 |
<para> |
| 328 |
The <emphasis>host system</emphasis> must be the same architecture and |
| 329 |
running the same distribution of Linux as the <emphasis>target |
| 330 |
system</emphasis> in order for the built <emphasis>instrumentation |
| 331 |
module</emphasis> to work. |
| 332 |
</para> |
| 333 |
</important> |
| 334 |
|
| 335 |
</section> |