path: root/doc/SystemTap_Beginners_Guide/en-US/Installation.xml

<?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="using-setup">
  <title>Installation and Setup</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>	
<indexterm>
<primary>Installation</primary>
<secondary>Setup and Installation</secondary>
</indexterm>

<indexterm>
<primary>Setup and Installation</primary>
</indexterm>		
  <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>
		
  <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> package of the kernel, not the
    <filename>-debug</filename> version of the kernel. </para>
  </important>

<section id="installproper">
    <title>Installing SystemTap</title>

    <para>To deploy Systemtap, you will need to to install the following RPMs:
    </para>
<indexterm>
<primary>Installation</primary>
<secondary>systemtap package</secondary>
</indexterm>

<indexterm>
<primary>systemtap package</primary>
</indexterm>


<!-- next 2 indexterms for systemtap-runtime package -->

<indexterm>
<primary>Installation</primary>
<secondary>systemtap-runtime package</secondary>
</indexterm>

<indexterm>
<primary>systemtap-runtime package</primary>
</indexterm>
    <itemizedlist>
      <listitem><para><filename>systemtap</filename></para></listitem>
      <listitem><para><filename>systemtap-runtime</filename></para></listitem>
    </itemizedlist>
	
    <para>Assuming that <command>yum</command> is installed in the system, these two rpms can be installed with <command>yum install systemtap systemtap-runtime</command>. Note that before you can use SystemTap, you will still need to install the required kernel information RPMs.
    </para>

</section>

<section id="install-kinfo">
    <title>Installing Required Kernel Information RPMs</title>
<indexterm>
<primary>Installation</primary>
<secondary>required packages</secondary>
</indexterm>

<indexterm>
<primary>required packages</primary>
</indexterm>
<indexterm>
	<primary>packages required to run SystemTap</primary>
</indexterm>
<indexterm>
	<primary>RPMs required to run SystemTap</primary>
</indexterm>
<indexterm>
	<primary>Installation</primary>
	<secondary>kernel information packages</secondary>
</indexterm>

<indexterm>
	<primary>kernel information packages</primary>
</indexterm>
    <para> 
	    SystemTap needs information about the kernel in order to place instrumentation in it (i.e. probe it). This 
	    information also allows SystemTap to generate the code for the instrumentation. This information is contained 
	    in the matching <filename>-devel</filename>, <filename>-debuginfo</filename>, and <filename>-debuginfo-common</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>
	    Likewise, the necessary packages for the PAE kernel would be 
	    <filename>kernel-PAE-debuginfo</filename>, <filename>kernel-PAE-debuginfo-common</filename>,
	    and <filename>kernel-PAE-devel</filename>.
	</para>
		    
<indexterm>
<primary>Installation</primary>
<secondary>kernel version, determining the</secondary>
</indexterm>

<indexterm>
<primary>kernel version, determining the</primary>
</indexterm>

<indexterm>
<primary>determining the kernel version</primary>
</indexterm>
<indexterm>
	<primary>uname -r</primary>
</indexterm>    
    <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> on an i686 machine, 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>

   <important>
      <title>Important</title>
	
      <para>
	The version, variant, 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>
	    The easiest way to install the required kernel information packages is through <command>yum install</command> 
	    and <command>debuginfo-install</command>. <command>debuginfo-install</command> is included with later versions of the
	    <filename>yum-utils</filename> package (for example, version 1.1.10), and also requires an appropriate <command>yum</command>
	    repository from which to download and install <command>-debuginfo</command>/<filename>-debuginfo-common</filename> packages.
    </para>
    
	<para condition="fedora">
	    Most of the required kernel packages can be found at 
	    <ulink url="http://download.fedoraproject.org/pub/fedora/linux/releases/"/>. Configure 
	    <command>yum</command> accordingly by adding a new "debug" <command>yum</command> repository file 
	    under <filename>/etc/yum.repos.d</filename> containing the following lines:
	</para>

<programlisting condition="fedora">
[fedora-debuginfo]
name=Fedora $releasever - $basearch - Debug
failovermethod=priority
baseurl=http://download.fedoraproject.org/pub/fedora/linux/releases/$releasever/Everything/$basearch/debug/
enabled=1
</programlisting>	
	
	
	<para condition="RedHat">
		Most required kernel packages can be found at 
		<ulink url="ftp://ftp.redhat.com/pub/redhat/linux/enterprise/"/>; navigate there until you find the 
		appropriate <filename>Debuginfo</filename> directory for your system. Configure 
		<command>yum</command> accordingly by adding a new "debug" <command>yum</command> repository file under 
		<filename>/etc/yum.repos.d</filename> containing the following lines:
	</para>
<programlisting condition="RedHat">
[rhel-debuginfo]
name=Red Hat Enterprise Linux $releasever - $basearch - Debug
baseurl=ftp://ftp.redhat.com/pub/redhat/linux/enterprise/$releasever/en/os/$basearch/Debuginfo/
enabled=1
</programlisting>

<para>
	After configuring <command>yum</command> with the appropriate repository, you can now install 
	the required <filename>-devel</filename>, <filename>-debuginfo</filename>, and <filename>-debuginfo-common</filename> 
	packages for your kernel. To install the corresponding packages for a specific kernel, run the following commands:
</para>

<itemizedlist>
<listitem><para><command>yum install <replaceable>kernelname</replaceable>-devel-<replaceable>version</replaceable></command></para></listitem>
<listitem><para><command>debuginfo-install <replaceable>kernelname</replaceable>-<replaceable>version</replaceable></command></para></listitem>
</itemizedlist>

<para>
	Replace <command><replaceable>kernelname</replaceable></command> with the appropriate kernel variant name 
	(for example, <filename>kernel-PAE</filename>), and <command><replaceable>version</replaceable></command> 
	with the target kernel's version. For example, to install the required kernel information packages for
	the <command>kernel-PAE-2.6.18-53.1.13.el5</command> kernel, run:
</para>

<itemizedlist>
	<listitem><para><command>yum install kernel-PAE-devel-2.6.18-53.1.13.el5</command></para></listitem>
	<listitem><para><command>debuginfo-install kernel-PAE-2.6.18-53.1.13.el5</command></para></listitem>
</itemizedlist>

<para>
	If you do not have <command>yum</command> and <command>yum-utils</command> installed (and you are unable to install them), you will have to manually download and install the required kernel information packages. To generate the URL from which to download the required packages, use the following script:
</para>	
<indexterm condition="fedora">
<primary>Installation</primary>
<secondary>fedoradebugurl.sh</secondary>
</indexterm>

<indexterm condition="fedora">
<primary>fedoradebugurl.sh</primary>
</indexterm>


<!-- next 2 indexterms for rheldebugurl.sh -->

<indexterm condition="RedHat">
<primary>Installation</primary>
<secondary>rheldebugurl.sh</secondary>
</indexterm>

<indexterm condition="RedHat">
<primary>rheldebugurl.sh</primary>
</indexterm>
<formalpara condition="RedHat">
<title>rheldebugurl.sh</title>
<para>
<programlisting>
<xi:include parse="text" href="extras/rheldebugurl.sh" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>
</para>
</formalpara>


<formalpara condition="fedora">
<title>fedoradebugurl.sh</title>
<para>
<programlisting>
<xi:include parse="text" href="extras/fedoradebugurl.sh" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>
</para>
</formalpara>
    <para>
Once you have manually downloaded the required packages to the machine, install the RPMs by running <command>rpm --force -ivh <replaceable>package_names</replaceable></command>.
    </para>
	
  </section>

	
  <section id="testing">
    <title>Initial Testing</title>
<indexterm>
<primary>Installation</primary>
<secondary>initial testing</secondary>
</indexterm>

<indexterm>
<primary>initial testing</primary>
</indexterm>

<indexterm>
<primary>testing, initial</primary>
</indexterm>	
    <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 {printf("read performed\n"); exit()}'</command>.  This command simply instructs SystemTap 
	    to print <computeroutput>read performed</computeroutput> then exit
	    properly once a virtual file system read is detected. If the SystemTap
	    deployment was successful, you should get output similar to the
	    following:
    </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 45 library script(s) in 340usr/0sys/358real ms.
Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 290usr/260sys/568real ms.
Pass 3: translated to C into "/tmp/stapiArgLX/stap_e5886fa50499994e6a87aacdc43cd392_399.c" in 490usr/430sys/938real ms.
Pass 4: compiled C into "stap_e5886fa50499994e6a87aacdc43cd392_399.ko" in 3310usr/430sys/3714real ms.
Pass 5: starting run.
read performed
Pass 5: run completed in 10usr/40sys/73real ms.
</screen>

    <para> The last three 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 execute a valid handler (print text then close it with no errors).
    </para>

  </section>
</section>