# Installation and Setup

To deploy SystemTap, 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 intend to use SystemTap on more than one of them, also install the `-devel` and `-debuginfo` packages for each of those kernel versions.

The following sections discuss the installation procedures in greater detail.

## Important

Many users confuse `-debuginfo` with `-debug`. Remember that the deployment of SystemTap requires the installation of the `-debuginfo` package of the kernel, not the `-debug` version of the kernel.

## Installing SystemTap

To deploy SystemTap, install the following RPM packages:

- `systemtap`

- `systemtap-runtime`

To do so, run the following command as root:

    yum install systemtap systemtap-runtime

Note that before using SystemTap, you still need to install the required kernel information packages. On modern systems, run the following command as root to install these packages:

    stap-prep

If this command does not work, try manual installation as described below.

## Installing Required Kernel Information Packages Manually

SystemTap needs information about the kernel in order to place instrumentation in it (in other words, probe it). This information also allows SystemTap to generate the code for the instrumentation.

The required 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 are `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 intend to use SystemTap on kernel version 2.6.18-53.el5 on an i686 machine, download and install the following RPM packages:

- `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. The `debuginfo-install` command 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` and `-debuginfo-common` packages. You can install the required `-devel`, `-debuginfo`, and `-debuginfo-common` packages for your kernel.

Note that Red Hat provides several software update services. Red Hat Enterprise Linux 6 uses RHN by default, whereas the default for Red Hat Enterprise Linux 7 is CDN.

For Red Hat Enterprise Linux 6 registered with RHN, appropriate channels must be enabled for `yum` to download and install the relevant 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:

## rhelchannels.sh

On a system with Red Hat Enterprise Linux 6 for Workstation, running the above script returns 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` command provides a list of channels the machine is currently subscribed to. If the machine is only subscribed to `rhel-x86_64-workstation-6`, use the following command with root and Red Hat Network administrator privileges for the machine to add the other channels:

    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

When the appropriate software repositories are enabled, install the corresponding packages for a specific kernel with the following commands:

    yum install kernelname-devel-version
    debuginfo-install kernelname-version

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:

    yum install kernel-PAE-devel-2.6.18-53.1.13.el5
    debuginfo-install kernel-PAE-2.6.18-53.1.13.el5

With Red Hat Enterprise Linux 7 system registered with CDN, all needed channels, or repositories in the CDN terminology, are available by default. Running the `stap-prep` command is sufficient to install all needed kernel information packages. During it operation, the `stap-prep` command temporarily enables any repositories that are needed and available, but disabled by default.

If you do not have `yum` and `yum-utils` installed and you are unable to install these packages, download and install the required kernel information packages manually. To generate the URL from which to download the required packages, use the following script:

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, download and install the required kernel information packages manually. To generate the URL from which to download the required packages, use the following script:

## rheldebugurl.sh

## fedoradebugurl.sh

Once you have manually downloaded the required packages to the machine, run the following command as root to install them:

    rpm --force -ivh package_names

## Initial Testing

If you are currently using the kernel you intend to probe with SystemTap, you can immediately test whether the deployment was successful. If not, you restart the system and load the appropriate kernel.

To start the test, run the following command:

    stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'

This command instructs SystemTap to print `read performed` and then exit properly once a virtual file system read is detected. If the SystemTap deployment was successful, it prints 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 (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).