added cross-instrumentation, deploying systemtap

4 files changed, 237 insertions, 8 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
new file mode 100644
index 00000000..cf57f5b2
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
@@ -0,0 +1,147 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+	<section id="cross-compiling">
+		<title>Cross-Instrumentation</title>
+
+<remark>cross-compiling script from here: http://sources.redhat.com/ml/systemtap/2008-q3/msg00310.html</remark>
+		
+<remark>above; add short description, significance, howto, script (test first)</remark>		
+	<para>
+		When users run a SystemTap script, SystemTap builds a kernel module out of that script. SystemTap then loads the module onto the kernel, allowing it to extract the specified data directly from the kernel (refer to <xref linkend="systemtapsession"/> in <xref linkend="understanding-architecture-tools"/> for more information).
+	</para>
+	
+	<para>
+		Normally, however, SystemTap scripts can only be run on systems where SystemTap is deployed (as in <xref linkend="installproper"/>). This could mean that if you want to run SystemTap on ten systems, you'd need to deploy SystemTap on <emphasis>all</emphasis> those systems.
+	</para>	
+		
+	<para>
+		In some cases, this may be neither feasible nor desired. For instance, running SystemTap on 25 systems &mdash; all of which are using a different kernel &mdash; may require fully deploying SystemTap on all 25 machines. This task may even increase in complexity if some (or all) systems are remote from the administrator. Sometimes, corporate policy may prohibit an administrator from installing a debug version of an RPM on specific machines, which will prevent the deployment of SystemTap altogether.
+	</para>	
+	
+	<para>
+		To work around this, you can resort to <firstterm>cross-instrumentation</firstterm>. Cross-instrumentation is the process of compiling a kernel module (out of a SystemTap script) to be used on a different machine. This process offers the following benefits:
+	</para>
+	
+	<itemizedlist>
+		<listitem><para>The debug RPMs for all target machines can be installed into one system: the host machine.</para></listitem>
+		
+		<listitem><para>Each target machine only needs one RPM to load and use the compiled kernel module: <filename>systemtap-runtime</filename>.</para></listitem>
+		
+		<listitem><para>You do not need to restart any of the target machines.</para></listitem>
+	</itemizedlist>
+	
+<!-- 	
+
+	<para>
+		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>.
+	</para>	
+	
+	<para>
+		<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.
+	</para>	
+	
+	
+	<para>
+		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?
+	</para>	
+		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. 
+	</para>	
+	
+	-->	
+<note>
+<title>Note</title>
+<para>For the sake of simplicity, we will be using the following terms throughout this section:</para>
+				
+<itemizedlist>
+	<listitem><para><emphasis>instrumentation module</emphasis> &mdash; the kernel module built from a SystemTap script; i.e. the <emphasis>SystemTap module</emphasis> is built on the <emphasis>host system</emphasis>, and will be loaded on the <emphasis>target kernel</emphasis> of <emphasis>target system</emphasis>.</para></listitem>
+	
+	<listitem><para><emphasis>host system</emphasis> &mdash; the system on which you compile the kernel modules (from SystemTap scripts), to be loaded on <emphasis>target systems</emphasis>.</para></listitem>
+	
+	<listitem><para><emphasis>target system</emphasis> &mdash; the system for which you are building the <emphasis>instrumentation module</emphasis> (from SystemTap scripts).</para></listitem> 
+	
+	<listitem><para><emphasis>target kernel</emphasis> &mdash; the kernel of the <emphasis>target system</emphasis>. This is the kernel on which you wish to load/run the <emphasis>instrumentation module</emphasis>.</para></listitem>
+</itemizedlist>	
+</note>		
+		
+<!--		
+		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"/>).
+	</para>	-->
+	
+<!--	<para>
+		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.
+	</para>-->
+	
+<procedure id="preppingxcompile">
+	<title>Configuring a Host System and Target Systems</title>
+	
+<step>
+		<para>Configure <command>yum</command> on the <emphasis>host system</emphasis> to point to a repository containing the necessary debug RPMs for the <emphasis>target kernels</emphasis>. The following <command>yum</command> repository file (which you can add to <filename>/etc/yum.repos.d/</filename> points to a popular debug RPM repository for Red Hat Enterprise Linux 5:</para>
+<screen>
+[rhel-debuginfo]
+name=Red Hat Enterprise Linux $releasever - $basearch - Debug
+
+baseurl=ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/i386/Debuginfo/
+enabled=1
+</screen>
+	</step>	
+	
+	<step>
+		<para>Deploy SystemTap on the <emphasis>host system</emphasis>. It is from this machine that you will be building the <emphasis>instrumentation module</emphasis> (to be used on <emphasis>target systems</emphasis>). For instructions on how to deploy SystemTap, refer to <xref linkend="installproper"/>.</para>
+	</step>	
+		
+	<step>
+		<para>Install the <emphasis>target kernel</emphasis> on the <emphasis>host system</emphasis>. If multiple <emphasis>target systems</emphasis> use different <emphasis>target kernel</emphasis>, you will need to install each <emphasis>target kernel</emphasis>.</para>
+	</step>
+	
+	<step>
+		<para>
+			Install the corresponding debug RPMs for the <emphasis>target kernel</emphasis> of each <emphasis>target system</emphasis> on the <emphasis>host system</emphasis>.
+		</para>		
+	</step>
+	<step>
+		<para>Install <filename>yum-utils</filename> on the <emphasis>host system</emphasis>.</para>		
+	</step>
+	
+	<step>
+		<para>Install <filename>systemtap-runtime</filename> on each <emphasis>target system</emphasis>.</para>
+	</step>	
+</procedure>	
+
+<para>After performing <xref linkend="preppingxcompile"/>, you can now build the <emphasis>instrumentation module</emphasis> (for any <emphasis>target system</emphasis>) on the <emphasis>host system</emphasis>. </para>
+
+<para>To build the <emphasis>instrumentation module</emphasis>, run the following command on the <emphasis>host system</emphasis> (be sure to specify the appropriate values):</para>
+
+<para><command>stap -r <replaceable>[kernel version]</replaceable> <replaceable>[script]</replaceable> -m <replaceable>[module name]</replaceable></command></para>
+
+<para>Here, <command><replaceable>[kernel version]</replaceable></command> refers to the version of <emphasis>target kernel</emphasis> (including the architecture notation), <command><replaceable>[script]</replaceable></command> refers to the script to be converted into an <emphasis>instrumentation module</emphasis>, and <command><replaceable>[instrumentation name]</replaceable></command> is the desired name of the <emphasis>instrumentation module</emphasis>.</para>
+
+<note>
+	<title>Note</title>
+	<para>To determine the version of a running kernel, run <command>uname -r</command>. To determine the architecture notation of a running kernel, run <command>uname -m</command>.</para>
+</note>	
+
+<para>Once the the <emphasis>instrumentation module</emphasis>is compiled, copy it to the <emphasis>target system</emphasis> and load it using:</para>
+
+<para><command>staprun <replaceable>[instrumentation]</replaceable></command></para>
+
+<para>
+	For example, to create the <emphasis>instrumentation module</emphasis> <filename>module.ko</filename> from the SystemTap script <filename>script.stp</filename> for the <emphasis>target kernel</emphasis> 2.6.25.9-76.fc9 (on i686 architecture), use the following command:
+</para>
+
+<para><command>stap -r 2.6.25.9-76.fc9.x86_64 script.stp -m module</command></para>
+
+<para>This will create a module named <filename>module.ko</filename>. To use the <emphasis>instrumentation module</emphasis> <filename>module.ko</filename>, copy it to the <emphasis>target system</emphasis> and run the following command (on the <emphasis>target system</emphasis>):</para>
+
+<para><command>staprun module.ko</command></para>
+	
+<!--<procedure id="preppingxcompile">
+	<title>Preparing for a Cross-Compile</title>
+	
+<step>
+	<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>
+</step>	-->
+		
+
+	</section>	
\ No newline at end of file
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Tips_Tricks.xml b/doc/SystemTap_Beginners_Guide/en-US/Tips_Tricks.xml
index 662d5b3d..0377c499 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Tips_Tricks.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Tips_Tricks.xml
@@ -7,5 +7,8 @@
 	<remark>This chapter covers miscellaneous tips/tricks</remark>
 	
 	<remark>This is a tentative section, and will only be included if content can be provided</remark>
+	
+	
+
 </chapter>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
index 116e7453..c3fc0d9d 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml
@@ -30,7 +30,7 @@
 		
 		<para>A SystemTap session begins when you run a SystemTap script. This session occurs in the following fashion:</para>
 			
-<procedure>
+<procedure id="systemtapsession">
 	<title>SystemTap Session</title>
 	<step><para>SystemTap first translates the script to C, running the system C compiler to create a kernel module from it.</para></step>
 	
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
index dfb345c8..da6d4d4c 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml
@@ -7,6 +7,11 @@
 	<remark>
 		short intro, contents of chapter
 	</remark>
+	
+	<para>
+		This chapter instructs users how to install SystemTap, and provides an introduction on how to run SystemTap scripts.
+	</para>	
+	
 	<section id="using-setup">
 		<title>Setup and Installation</title>
 		<remark>
@@ -16,16 +21,90 @@
 		<remark>
 			notes in ~/Desktop/SystemTap/aug21chatlog and ~/Desktop/SystemTap/noted_wcohenmeeting 
 		</remark>	
+		
+		<para>
+			To deploy SystemTap, you need to install the SystemTap packages along with the corresponding set of debug RPMs of your kernel. This means that if your system has multiple kernels installed, and you wish to use SystemTap on more than one kernel, you will need to install the debug RPMs for <emphasis>each</emphasis> of those kernels.
+		</para>
 <formalpara>
-	<title>Cross-Compiling</title>
-	<para>TBD</para>
-</formalpara>	
-<remark>cross-compiling script from here: http://sources.redhat.com/ml/systemtap/2008-q3/msg00310.html</remark>
-
-<remark>above; add short description, significance, howto, script (test first)</remark>
+	<title>Preparing For Installation</title>
+		<para>
+			To view what kernels and kernel versions are installed on your system, check the contents of <filename>/boot</filename>. Each installed kernel/kernel version has a corresponding <filename>vmlinuz-<replaceable>[kernel version]</replaceable></filename> there.
+		</para>
+</formalpara>		
+		<para>
+			To determine what kernel your system is currently using, use:
+		</para>
 		
-	</section>
+<screen>
+uname -r
+</screen>
+		
+		<para>
+			You will also need to configure <command>yum</command> to point to a repository that houses the necessary debug RPMs. One such repository is:
+		</para>
+		
+		<para><ulink url="	ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/i386/Debuginfo/"/></para>
+		
+		<remark>find any other such repository, if only for RHEL</remark>	
+			
+			
+<procedure id="installproper">
+	<title>Deploying SystemTap</title>
+	
+<step>
+	<para>Once you've decided which kernels you need to use SystemTap with, install the following packages:</para>
+	
+	<itemizedlist>
+		<listitem><para><filename>systemtap</filename></para></listitem>
+		<listitem><para><filename>systemtap-runtime</filename></para></listitem>
+	</itemizedlist>
 	
+	<para>This will install the SystemTap suite of tools.</para> 
+</step>
+
+<step>
+	<para>Next, you'll need to download and install the necessary debug RPMs for your kernel. Most debugging RPMs for Red Hat Enterprise Linux 5 can be found at the following link:</para>
+	
+	<para>The necessary debugging RPMs are as follows:</para>
+	
+<itemizedlist>
+	<listitem><para><filename>kernel-debuginfo</filename></para></listitem>
+	<listitem><para><filename>kernel-debuginfo-common</filename></para></listitem>
+	<listitem><para><filename>kernel-devel</filename></para></listitem>
+</itemizedlist>
+
+<para>For example, if you wish to use SystemTap on kernel version <filename>2.6.18-53.el5</filename>, then you need to download the following debugging RPMs:</para>
+
+<example id="debuggingrpmlist">
+	<title>Sample List of Debugging RPMs</title>
+<itemizedlist>
+	<listitem><para><filename>kernel-debuginfo-2.6.18-53.1.13.el5.i686.rpm</filename></para></listitem>
+	<listitem><para><filename>kernel-debuginfo-common-2.6.18-53.1.13.el5.i686.rpm</filename></para></listitem>
+	<listitem><para><filename>kernel-devel-2.6.18-53.1.13.el5.i686.rpm</filename></para></listitem>
+</itemizedlist>
+</example>
+</step>
+
+<step>
+	<para>Install the debugging RPMs using <command>rpm -ivh <replaceable>[RPM]</replaceable></command> or <command>yum localinstall <replaceable>[RPM]</replaceable></command>.</para>
+</step>
+
+<step>
+	<para>
+		Restart the system, loading the appropriate kernel at the <command>grub</command> screen.
+	</para>	
+</step>	
+</procedure>
+
+
+<!--		
+<itemizedlist>
+	<listitem><para><filename>systemtap</filename></para></listitem>
+	<listitem><para><filename>systemtap-runtime</filename></para></listitem>
+</itemizedlist>	
+		-->		
+	</section>
+	<xi:include href="CrossInstrumenting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />	
 	<section id="using-usage">
 		<title>Usage</title>
 		<remark>