2.1. Installation and Setup
To deploy SystemTap, you need to install the SystemTap packages along with the corresponding set of -devel
, -debuginfo
and -debuginfo-common
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 -devel
and -debuginfo
packages for each of those kernel versions.
2.1.2. Installing Required Kernel Information RPMs
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 -devel
, -debuginfo
, and -debuginfo-common
packages for your kernel. The necessary -devel
and -debuginfo
packages for the ordinary "vanilla" kernel are as follows:
kernel-debuginfo
kernel-debuginfo-common
kernel-devel
Likewise, the necessary packages for the PAE kernel would be kernel-PAE-debuginfo
, kernel-PAE-debuginfo-common
, and kernel-PAE-devel
.
To determine what kernel your system is currently using, use:
uname -r
For example, if you wish to use SystemTap on kernel version 2.6.18-53.el5
on an i686 machine, then you would need to download and install the following RPMs:
kernel-debuginfo-2.6.18-53.1.13.el5.i686.rpm
kernel-debuginfo-common-2.6.18-53.1.13.el5.i686.rpm
kernel-devel-2.6.18-53.1.13.el5.i686.rpm
Important
The version, variant, and architecture of the -devel
, -debuginfo
and -debuginfo-common
packages must match the kernel you wish to probe with SystemTap exactly.
The easiest way to install the required kernel information packages is through yum install
and debuginfo-install
commands. debuginfo-install
is included with later versions of the yum-utils
package (for example, version 1.1.10), and also requires an appropriate yum
repository from which to download and install -debuginfo
/-debuginfo-common
packages. You can install the required -devel
, -debuginfo
, and -debuginfo-common
packages for your kernel.
For Red Hat Enterprise Linux 6 and newer you need the appropriate channels enabled for the system for yum
to download and install the appropriate packages. Configure the channels with either the rhn-channel
command or the Red Hat Network web interface. To obtain a list of the channels SystemTap needs on the system use the following script:
On a system with Red Hat Enterprise Linux 6 for Workstation running the previous script would return the following list:
rhel-x86_64-workstation-6
rhel-x86_64-workstation-6-debuginfo
rhel-x86_64-workstation-optional-6-debuginfo
rhel-x86_64-workstation-optional-6
The rhn-channel --list
will provide a list of channels the machine is currently subscribed to. If the machine is only subscribed to rhel-x86_64-workstation-6
, then with root and Red Hat Network administrator privileges for the machine the other channels could be added with the following command:
rhn-channel --add \
--channel=rhel-x86_64-workstation-6-debuginfo \
--channel=rhel-x86_64-workstation-optional-6-debuginfo \
--channel=rhel-x86_64-workstation-optional-6
With the appropriate software repositories are enabled, install the corresponding packages for a specific kernel using yum
with the following commands:
Replace kernelname
with the appropriate kernel variant name (for example, kernel-PAE
), and version
with the target kernel's version. For example, to install the required kernel information packages for the kernel-PAE-2.6.18-53.1.13.el5
kernel, run:
If you do not have yum
and yum-utils
installed (and you are unable to install them) on Red Hat Enterprise Linux 4 or 5, 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:
Once you have manually downloaded the required packages to the machine, install the RPMs by running rpm --force -ivh package_names
.
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.
To start the test, run the command stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'
. This command simply instructs SystemTap to print read performed
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:
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.
The last three lines of the output (i.e. beginning with Pass 5
) 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).