Include staprep.sh script and make use of it in describing Systemtap setup.

3 files changed, 404 insertions, 234 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
index b0d712bd..6a91beab 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml
@@ -2,35 +2,61 @@
 <!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>
+<section id="cross-compiling">
+  <title>Generating Instrumentation for Other Computers</title>
 
-<remark>cross-compiling script from here: http://sources.redhat.com/ml/systemtap/2008-q3/msg00310.html</remark>
+  <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>
+  <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>
+    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 would need to
+    deploy SystemTap on <emphasis>all</emphasis> those systems.  In some cases,
+    this may be neither feasible nor desired to fully deploy SystemTap on those
+    systems. For instance corporate policy may prohibit an administrator from
+    installing RPMs that proved debug information or compilers on specific
+    machines, which will prevent the deployment of SystemTap.
+  </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>
+  <para>
+    To work around this, you can resort to
+    <firstterm>cross-instrumentation</firstterm>. Cross-instrumentation is the
+    process of generating SystemTap instrumentation module from a SystemTap
+    script on one computer to be used on another 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>
+  <itemizedlist>
+    <listitem>
+      <para>
+	The debug RPMs for various machines can be installed on a single system:
+	the host machine.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+	Each target machine only needs one RPM to installed to use
+	the generated SystemTap instrumentation module:
+	<filename>systemtap-runtime</filename>.
+      </para>
+    </listitem>
+  </itemizedlist>
 	
 <!-- 	
 
@@ -50,20 +76,53 @@
 	</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>
+  <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>host system</emphasis> &mdash; the system on
+	  which you compile the instrumentation 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 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>		
+      <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"/>).
@@ -72,70 +131,113 @@
 <!--	<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 i386 systems running 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>
+  <procedure id="preppingxcompile">
+    <title>Configuring a Host System and Target Systems</title>
 
-<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>
+    <step>
+      <para>
+	Install the <filename>systemtap-runtime</filename> RPM on each
+	<emphasis>target system</emphasis>.
+      </para>
+    </step>	
 
-<para><command>stap -r <replaceable>kernel version</replaceable> <replaceable>script</replaceable> -m <replaceable>module name</replaceable></command></para>
+    <step>
+      <para>
+	Determine the kernel running on each <emphasis>target system</emphasis>
+	by running the by running <command>uname -r</command> on each
+	<emphasis>target system</emphasis>:
+      </para>
+    </step>
 
-<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>
+    <step>
+      <para>
+	Install 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 install SystemTap, refer
+	to <xref linkend="installproper"/>.
+      </para>
+    </step>
 
-<note>
-	<title>Note</title>
-	<para>To determine the architecture notation of a running kernel, run <command>uname -m</command>.</para>
-<!--	<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>	
+    <step>
+      <para>
+	Using the <emphasis>target kernel</emphasis> version determined earlier,
+	install the <emphasis>target kernel</emphasis> and related RPMs on the
+	<emphasis>host system</emphasis> by the method described in <xref
+	linkend="install-kinfo"/>. If multiple <emphasis>target
+	systems</emphasis> use different <emphasis>target kernels</emphasis>,
+	you will need to repeat this step for each different kernel used on the
+	<emphasis>target systems</emphasis>.
+      </para>
+    </step>
 
-<para>Once the the <emphasis>instrumentation module</emphasis> is compiled, copy it to the <emphasis>target system</emphasis> and load it using:</para>
+  </procedure>
 
-<para><command>staprun <replaceable>instrumentation</replaceable></command></para>
+  <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>
-	For example, to create the <emphasis>instrumentation module</emphasis> <filename>simple.ko</filename> from a SystemTap script named <filename>simple.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 simple.stp -m module</command></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 the <emphasis>target kernel</emphasis> (the output of
+    <command>uname -r</command> on the target machine),
+    <command><replaceable>script</replaceable></command> refers to the script to
+    be converted into an <emphasis>instrumentation module</emphasis>, and
+    <command><replaceable>module_name</replaceable></command> is the desired
+    name of the <emphasis>instrumentation module</emphasis>.
+  </para>
+
+  <note>
+    <title>Note</title>
+    <para>
+      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>module_name</replaceable>.ko</command>
+  </para>
+
+  <para>
+    For example, to create the <emphasis>instrumentation module</emphasis>
+    <filename>simple.ko</filename> from a SystemTap script named
+    <filename>simple.stp</filename> for the <emphasis>target kernel</emphasis>
+    2.6.18-92.1.10.el5 (on x86_64 architecture), use the following command:
+  </para>
+
+  <para>
+    <command>stap -r 2.6.18-92.1.10.el5 -e 'probe vfs.read {exit()}' -m simple</command>
+  </para>
 
-<para>This will create a module named <filename>simple.ko</filename>. To use the <emphasis>instrumentation module</emphasis> <filename>simple.ko</filename>, copy it to the <emphasis>target system</emphasis> and run the following command (on the <emphasis>target system</emphasis>):</para>
+  <para>
+    This will create a module named <filename>simple.ko</filename>. To use the
+    <emphasis>instrumentation module</emphasis> <filename>simple.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 simple.ko</command></para>
+  <para><command>staprun simple.ko</command></para>
 	
 <!--<procedure id="preppingxcompile">
 	<title>Preparing for a Cross-Compile</title>
@@ -143,9 +245,14 @@ enabled=1
 <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>	-->
-<important>
-	<title>Important</title>
-	<para>The <emphasis>host system</emphasis> must be the same architecture as the <emphasis>target system</emphasis> in order for the <emphasis>instrumentation module</emphasis> to work.</para>
-</important>	
+  <important>
+    <title>Important</title>
+    <para>
+      The <emphasis>host system</emphasis> must be the same architecture and
+      running the same distribution of Linux as the <emphasis>target
+      system</emphasis> in order for the <emphasis>instrumentation
+      module</emphasis> to work.
+    </para>
+  </important>
 
-	</section>	
\ No newline at end of file
+</section>	
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
index 1bde952e..2d5eb98b 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml
@@ -4,161 +4,189 @@
 
 	
 <section id="using-setup">
-		<title>Setup and Installation</title>
-		<remark>
-			required packages, installation thru yum, repos (?); possibly, a script to install all required packages
-		</remark>
-		
-		<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 <filename>-devel</filename>, <filename>-debuginfo</filename> and <filename>-debuginfo-common</filename> packages for your kernel. This means that if your system has multiple kernels installed, and you wish to use SystemTap on more than one kernel kernel, you will need to install the <filename>-devel</filename> and <filename>-debuginfo</filename> packages for <emphasis>each</emphasis> of those kernel versions.
-		</para>
-		
-		<para>
-			These procedures will be discussed in detail in the following sections.
-		</para>	
-		
-	<important>
-		<title>Important</title>
-		<para>Many users confuse <filename>-debuginfo</filename> with <filename>-debug</filename>. Remember that the deployment of SystemTap requires the installation of the <filename>-debuginfo</filename> version of the kernel, not the <filename>-debug</filename> version.</para>
-	</important>	
-		
-<section id="installprep">
-	<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>
-		
-<screen>
-uname -r
-</screen>
-<!--		
-		<para>
-			Red Hat recommends that you configure <command>yum</command> to point to a repository that houses the necessary debuginfo packages. Otherwise, you will have to manually download the debuginfo packages yourself.
-		</para>-->
-		
-		<para>
-			Most <filename>-debuginfo</filename> packages for Red Hat Enterprise Linux 5 can be found at the following link (under <filename><replaceable>arch</replaceable>/Debuginfo</filename>, where <filename><replaceable>arch</replaceable></filename> is the appropriate architecture for your system:
-		</para>
-		
-		<para><ulink url="ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/">ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/</ulink></para>
-		
-		<remark>find any other such repository, if only for RHEL</remark>	
+  <title>Setup and Installation</title>
+  <remark>
+    required packages, installation thru yum, repos (?); possibly, a script to install all required packages
+  </remark>
+
+  <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 <filename>-devel</filename>,
+    <filename>-debuginfo</filename> and <filename>-debuginfo-common</filename>
+    packages for your kernel. If your system has multiple kernels installed, and
+    you wish to use SystemTap on more than one kernel kernel, you will need to
+    install the <filename>-devel</filename> and <filename>-debuginfo</filename>
+    packages for <emphasis>each</emphasis> of those kernel versions.
+  </para>
 		
+  <para> These procedures will be discussed in detail in the following sections.
+  </para>
 		
-	</section>			
-			
+  <important>
+    <title>Important</title> <para>Many users confuse
+    <filename>-debuginfo</filename> with <filename>-debug</filename>. Remember
+    that the deployment of SystemTap requires the installation of the
+    <filename>-debuginfo</filename> version of the kernel, not the
+    <filename>-debug</filename> version. </para>
+  </important>
+
 <section id="installproper">
-	<title>Deploying SystemTap</title>
-	
-<!-- <step> -->
-	<para>Once you've decided which kernels with which 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>
+    <title>Installating SystemTap</title>
+
+    <para> For the Systemtap Beginner's Guide the following two SystemTap RPMs
+    need to be installed:
+    </para>
+
+    <itemizedlist>
+      <listitem><para><filename>systemtap</filename></para></listitem>
+      <listitem><para><filename>systemtap-runtime</filename></para></listitem>
+    </itemizedlist>
 	
-	<para>To do so, run <command>yum install systemtap systemtap-runtime</command>; this will work if your <application>yum</application> repository is configured accordingly. To configure <application>yum</application>, simply add the following file to <filename>/etc/yum.repos.d</filename>:</para>
+    <para>Assuming that the computer system has been configured to use Red Hat
+      Network (RHN), the two rpms can be installed with <command>yum install
+      systemtap systemtap-runtime</command>. Before you use SystemTap the
+      additional kernel information will need to be installed as described in
+      the following section.
+    </para>
+
+</section>
+
+<section id="install-kinfo">
+    <title>Installing Needed Kernel Information</title>
+
+    <para> SystemTap makes use of the information in additional kernel RPMs to
+      determine where to place instrumentation in the kernel and how to generate
+      code for the instrumentation. You will need to download and install the
+      necessary <filename>-devel</filename> and <filename>-debuginfo</filename>
+      packages for your kernel. The necessary <filename>-devel</filename> and
+      <filename>-debuginfo</filename> packages for the ordinary "vanilla" kernel
+      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> To determine what kernel your system is currently using, use:</para>
+		
+    <screen>
+      uname -r
+    </screen>
+
+    <para>For example, if you wish to use SystemTap on kernel version
+      <filename>2.6.18-53.el5</filename>, then you would need to download and
+      install the following RPMs:
+    </para>
+
+    <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>
+
+    <para> The script <xref linkend="stapprep"/> can be used by normal users to
+	  determine what supporting kernel RPMs need to be installed on the
+	  machine to use SystemTap with a particular kernel.  The script run
+	  without any arguments detemines the RPMs needed for the currently
+	  running kernel. The script can also accept one argument, the output
+	  <command>uname -r</command>, to determine the related RPMs required
+	  for a kernel that may not be currently running on the machine.
+    </para>
+
+    <formalpara id="stapprep">
+      <title>stapprep.sh</title>
+      <para>
+	<programlisting>
+	  <xi:include parse="text" href="extras/stapprep.sh" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	</programlisting>
+      </para>
+    </formalpara>
+
+    <para>
+      If the computer has access to Red Hat Network (RHN) and the yum-utils
+      package is installed, the <command>stapprep.sh</command> script can be run
+      by root to download and install the needed kernel packages via
+      <command>yum</command> and <command>rpm</command> commands. Thus, the
+      system administrator should be able to install the needed RPMs with the
+      script on the machine:
+    </para>
+
+    <screen>
+      ./stapprep.sh
+    </screen>
+<!-- The script assumes the Red Hat Enterprise Linux debuginfo repository,
+<filename>rhel-debuginfo</filename>, but this could be changed.  One could
+search the /etc/yum.repo.d/ directory for debuginfo repositories -->
+
+    <important>
+      <title>Important</title>
 	
-<formalpara id="sampleyum">
-	<title>packages.repo</title>
-<para>
+      <para>
+	The version and architecture of the <filename>-devel</filename>,
+	<filename>-debuginfo</filename> and
+	<filename>-debuginfo-common</filename> packages must match the kernel
+	you wish to probe with SystemTap <emphasis>exactly</emphasis>.
+      </para>
+    </important>
+
+    <para>
+	If the <command>yum</command> repsitories are not accessible from the
+	machine, the following lines of bash script will generate the URL for
+	the Red Hat Enterprise Linux 5 debuginfo RPM directory:
+    </para>
+
 <screen>
-[packages]
-name=Packages for OS
-baseurl=<replaceable>repository</replaceable> 
-enabled=1
-gpgcheck=0
+pkg=`grep distroverpkg /etc/yum.conf |awk -F= '{print $2}'`
+releasever=`rpm -q --qf "%{version}" $pkg`
+base=`uname -m`
+echo "ftp://ftp.redhat.com/pub/redhat/linux/enterprise/$releasever/en/os/$base"
 </screen>
-</para>	
-</formalpara>		
-
-<para>
-	In <xref linkend="sampleyum"/>, <replaceable>repository</replaceable> is the full URL of the repository containing the packages you wish to install. The <computeroutput>name=</computeroutput> parameter, along with the title (<computeroutput>[packages]</computeroutput>) and filename, can be set arbitrarily. Remember to always use the <filename>.repo</filename> filename extension.
-</para>
-	 
-<!-- </step> -->
-<!--<procedure id="deployproper">
-	<title>Deploying SystemTap</title>
-	<step>-->
-		<para>Next, you'll need to download and install the necessary  <filename>-devel</filename> and <filename>-debuginfo</filename> packages for your kernel. The necessary  <filename>-devel</filename> and <filename>-debuginfo</filename> packages for the ordinary "vanilla" kernel are as follows:</para>
-	<!-- Most debugging RPMs for Red Hat Enterprise Linux 5 can be found at the following link:</para>
-
-	<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 and install the following 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>
-
-<para>
-As mentioned earlier in <xref linkend="using-setup"/>, <filename>kernel-debuginfo</filename> should not be confused with <filename>kernel-debug</filename>. Thus, in this example, you do not need to install the <filename>kernel-debug-2.6.18-53.1.13.el5.i686.rpm</filename> package. 
-</para>
-</example>
-
-<important>
-	<title>Important</title>
-	
-	<para>The version and architecture of the <filename>-devel</filename>, <filename>-debuginfo</filename> and <filename>-debuginfo-common</filename> packages must match the kernel you wish to probe with SystemTap <emphasis>exactly</emphasis>.</para>
-</important>
-<para>
-	You can download the necessary packages via your web browser. Once you have downloaded the packages, install them by running <command>rpm -ivh <replaceable>package names</replaceable></command>.
-</para>
-	
-	
-<para>	
-	Alternatively, if the packages are in a <command>yum</command> repository, you can configure <command>yum</command> again to download and install directly from that repository. Once you've configured <command>yum</command> correctly, run <command>yum install <replaceable>full package names</replaceable></command> (as root).
-</para>
+
+    <para>
+      The package RPMs can be downloaded on another machine then copied to the
+      machine.  Once you have downloaded the packages and copied them to the
+      machine, install the RPMs by running <command>rpm -ivh
+      <replaceable>package names</replaceable></command>.
+    </para>
 	
+  </section>
 
-<formalpara id="initialtest">
-	<title>Initial Testing</title>
+  <section id="testing">
+    <title>Initial Testing</title>
 	
-<para>If you are currently using the kernel you wish to probe with SystemTap, you can immediately test whether the deployment was successful. If not, you will need to reboot and load the appropriate kernel.</para>
-</formalpara>
+    <para>If you are currently using the kernel you wish to probe with
+      SystemTap, you can immediately test whether the deployment was
+      successful. If not, you will need to reboot and load the appropriate
+      kernel.
+    </para>
 
-<para>To start the test, run the command <command>stap -v -e 'probe vfs.read {exit()}</command>. This command simply instructs SystemTap to exit properly once a virtual file system read is detected. If the SystemTap deployment was successful, you should get the following verbose output:</para>
+    <para>To start the test, run the command <command>stap -v -e 'probe vfs.read
+      {exit()}'</command>. This command simply instructs SystemTap to exit
+      properly once a virtual file system read is detected. If the SystemTap
+      deployment was successful, you should get output very similar to the
+      following:
+    </para>
 
 <screen>
-Pass 1: parsed user script and 55 library script(s) in 340usr/10sys/380real ms.

-Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 280usr/290sys/745real ms.

-Pass 3: translated to C into "/tmp/stapS1CuuS/stap_dd516743892b10a24cd36ef327265169_323.c" in 0usr/0sys/0real ms.

-Pass 4: compiled C into "stap_dd516743892b10a24cd36ef327265169_323.ko" in 2050usr/220sys/2541real ms.

-Pass 5: starting run.

-Pass 5: run completed in 40usr/210sys/260real ms.

+Pass 1: parsed user script and 55 library script(s) in 340usr/10sys/380real ms.
+Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 280usr/290sys/745real ms.
+Pass 3: translated to C into "/tmp/stapS1CuuS/stap_dd516743892b10a24cd36ef327265169_323.c" in 0usr/0sys/0real ms.
+Pass 4: compiled C into "stap_dd516743892b10a24cd36ef327265169_323.ko" in 2050usr/220sys/2541real ms.
+Pass 5: starting run.
+Pass 5: run completed in 40usr/210sys/260real ms.
 </screen>
 
-<para>
-	The last two lines of the output (i.e. beginning with <computeroutput>Pass 5</computeroutput> indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, detect the event being probed (in this case, a virtual file system read), and close it with no errors.
-</para>	
-
-<!--</step>
-</section>
+    <para> The last two lines of the output (i.e. beginning with
+    <computeroutput>Pass 5</computeroutput> indicate that SystemTap was able to
+    successfully create the instrumentation to probe the kernel, run the
+    instrumentation, detect the event being probed (in this case, a virtual file
+    system read), and close it with no errors.
+    </para>
 
- 		
-<itemizedlist>
-	<listitem><para><filename>systemtap</filename></para></listitem>
-	<listitem><para><filename>systemtap-runtime</filename></para></listitem>
-</itemizedlist>	
-		-->		
+  </section>
 </section>
-</section>
\ No newline at end of file
diff --git a/doc/SystemTap_Beginners_Guide/en-US/extras/stapprep.sh b/doc/SystemTap_Beginners_Guide/en-US/extras/stapprep.sh
new file mode 100644
index 00000000..ba909994
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/extras/stapprep.sh
@@ -0,0 +1,35 @@
+#! /bin/bash
+check_error() { if test $1 != 0; then echo $2; exit $1; fi }
+DEBUGINFOREPO="rhel-debuginfo"
+
+if [ "$#" -lt 1 ]; then
+    UNAME=`uname -r` # determine the kernel running on the machine
+else
+    UNAME=$1 #user passed in uname value
+fi
+UNAME=`echo $UNAME | sed "s/ //"` #strip out any whitespace
+KERNEL="kernel"
+for VARIANT in debug kdump PAE xen; do
+  TMP=`echo $UNAME | sed s/$VARIANT//`
+  if [ "$TMP" != "$UNAME" ]; then
+      UNAME=$TMP; KERNEL="kernel-$VARIANT"
+  fi
+done
+KERN_ARCH=`uname -m`
+KERN_REV=`echo $UNAME | sed s/.$KERN_ARCH//` # strip arch from uname
+CANDIDATES="$KERNEL-$KERN_REV.$KERN_ARCH $KERNEL-devel-$KERN_REV.$KERN_ARCH \
+$KERNEL-debuginfo-$KERN_REV.$KERN_ARCH \
+kernel-debuginfo-common-$KERN_REV.$KERN_ARCH"
+NEEDED=`rpm --qf "%{name}-%{version}-%{release}.%{arch}\n" -q $CANDIDATES | \
+    grep "is not installed" | awk '{print $2}'`
+if [ "$NEEDED" != "" ]; then
+    echo -e "Need to install the following packages:\n$NEEDED"
+    if [ `id -u` = "0" ]; then #attempt download and install
+	DIR=`mktemp -d` || exit 1
+	yumdownloader --enablerepo=$DEBUGINFOREPO $NEEDED --destdir=$DIR
+	check_error $? "problem downloading rpm(s) $NEEDED"
+	rpm --force -ivh $DIR/*.rpm
+	check_error $? "problem installing rpm(s) $NEEDED"
+	rm -r $DIR #cleanup
+    fi
+fi