.\" -*- nroff -*-
.TH SYSTEMTAP 8
.SH NAME
systemtap-service \- SystemTap initscript and systemd service

.\" macros
.de SAMPLE

.nr oldin \\n(.i
.br
.RS
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
.in \\n[oldin]u

..

.SH SYNOPSIS
.B systemtap-service
.IR COMMAND " [" OPTIONS "] [" SCRIPT ...]

.B service systemtap
.IR COMMAND " [" OPTIONS "] [" SCRIPT ...]

.SH DESCRIPTION
The SystemTap initscript aims to provide a way to run scripts as a service and
easily control them individually. Scripts can be configured to start upon manual
request, or during system startup. On dracut-based systems, it is also possible
to integrate scripts in the initramfs and have them start during early-boot.

The SystemTap initscript can be invoked manually using the
.B systemtap-service
command. On systemd-based systems, the initscript is controlled by
.B systemctl
with the service file
\fBsystemtap.service\fR.

There are various parameters and options available to modify global behaviour,
as well as script behaviour. Dependencies between scripts can be established so
that starting one starts others.

The configuration file of the initscript is located at
\fB@sysconfdir@/systemtap/config\fR. Acceptable parameters are detailed in the
GLOBAL PARAMETERS section.

Scripts must be placed in the \fB@sysconfdir@/systemtap/script.d\fR directory
and must have a \fB.stp\fR extension. When referring to them on the
command-line however, there in no need to include the \fB.stp\fR extension.
Script names can only contain alphanumeric characters (and '_') and must not
start with a number. The scripts directory may be changed by setting the
SCRIPT_PATH parameter in the configuration file.

.SH COMMANDS
One of the commands below must be specified:

.TP
.B start
Start \fISCRIPT\fRs. If no scripts are specified, start the scripts specified by
the DEFAULT_START configuration. If DEFAULT_START is not set, start all scripts
in the script directory. For scripts already started, the command is ignored.
The command will fail if the scripts fail to start (see also the PASSALL
configuration).

If the AUTOCOMPILE configuration is on, the command will try to compile or
update the specified scripts when one of the below conditions is true:
.RS
.IP - 2
The compiled cache file does not exist.
.IP -
The mtime (modified timestamp) of the original script file is newer than the
time of the compiled script cache.
.IP -
The specified stap options used to compile the script has been changed (see
also the SCRIPT PARAMETERS section).
.IP -
The result of `uname -a` has been changed.
.RE

.TP
.B stop
Stop \fISCRIPT\fRs. If no scripts are specified, stop all running scripts. For
scripts already stopped, the command is ignored. The command will fail if the
scripts fail to stop (see also the PASSALL configuration).

.TP
.B restart
Stop and start \fISCRIPT\fRs.

.TP
.B status
Show the state of \fISCRIPT\fRs and their dependencies.

.TP
.B compile
Compile \fISCRIPT\fRs but do not start them. If the scripts have already been
compiled, prompt for confirmation before overwriting cache. Compile for the
current kernel, or the kernel release specified by the \fB-r\fR option.

.TP
.B onboot
Make \fISCRIPT\fRs part of the initramfs so that they are started earlier during
the boot process. This command is only available on dracut-based systems. If no
scripts are specified, create a normal initramfs devoid of any SystemTap files.

The initramfs is created for the current kernel, or the kernel release specified
by the \fB-r\fR option. The path of the created initramfs defaults to
\fB/boot/initramfs-KVER.img\fR, where KVER is the output of `uname -r`. The
bootloader is also updated (using \fInew-kernel-pkg\fR(8)) to make the kernel
entry use the new initramfs file. Use the \fB-o\fR option to specify a different
path (the bootloader will not be updated).

If the output file already exists, it is overwritten, unless the \fB-b\fR switch
is given, in which case the file is appended \fB.bak\fR rather than overwritten.
However, if there is already a \fB.bak\fR version of the file, the backup will
not be overwritten.

WARNING: do not use the \fB-o\fR option of \fIstap\fR(1) with onboot scripts
because the script is started before the root filesystem is even mounted.
Increase the buffer size if more space is needed.

.TP
.B cleanup
Delete the compiled \fISCRIPT\fRs from cache. If no scripts are specified, then
all compiled scripts are deleted. Only the cache for the current kernel is
deleted, or the kernel release specified by the \fB-r\fR option. Prompt for
confirmation before deleting.

.SH OPTIONS
Many of the commands can also take options. However, since users can't pass
these options on boot, they are only meant for managing scripts after boot and
for testing. Available options are:

.TP
.BI "-c " CONFIG_FILE
Specify a different configuration file in place of the default one.

.TP
.B -R
When using the \fBstart\fR and \fBstop\fR commands, also include the scripts'
dependencies (recursively).

.TP
.BI "-r " KERNEL_RELEASE
When using the \fBcompile\fR, \fBonboot\fR, and \fBcleanup\fR commands, specify
the target kernel version rather than using the current one. Must be in the same
format as `uname -r`.

.TP
.B -y
Answer yes for all prompts.

.TP
.BI "-o " PATH.IMG
When using the \fBonboot\fR command, specify the output path of the created
initramfs. When specified, the bootloader configuration is not updated.

.TP
.B -b
When using the \fBonboot\fR command, backup an existing initramfs image by
adding a \fB.bak\fR extension rather than overwriting it. Without this option,
the initramfs is overwritten.

.SH GLOBAL PARAMETERS
These parameters affect the general behaviour of the SystemTap initscript
service. They can be specified in the configuration file.

.TP
.B SCRIPT_PATH
Specify the absolute path of the script directory. These are the scripts on
which the initscript can operate. Scripts must have the \fB.stp\fR extension.
The default path is \fB@sysconfdir@/systemtap/script.d\fR.

.TP
.B CONFIG_PATH
Specify the absolute path of the script configuration directory. These
configuration files contain options for specific scripts. They must have the
\fB.conf\fR extension. The default path is \fB@sysconfdir@/systemtap/conf.d\fR.

.TP
.B CACHE_PATH
Specify the absolute path of the cache directory. The default path is
\fB@localstatedir@/cache/systemtap\fR.

.TP
.B TEMP_PATH
Specify the absolute path of the temporary directory in which SystemTap
makes temporary directories to compile scripts. The default path is \fB/tmp\fR.

.TP
.B STAT_PATH
Specify the absolute path of the directory containing PID files used to track
the status of SystemTap scripts. The default path is
\fB@localstatedir@/run/systemtap\fR.

.TP
.B LOG_FILE
Specify the absolute path of the log file. All messages are sent to this file,
including compilation and runtime errors. The default path is
\fB@localstatedir@/log/systemtap.log\fR.

.TP
.B PASSALL
If this is set \fByes\fR, initscript commands that operate on multiple scripts
will report as failed when the action could not be performed on at least one
script. If set to \fBno\fR, only a warning is emitted. The default is \fByes\fR.

.TP
.B RECURSIVE
If this is set \fByes\fR, the initscript will always follow script dependencies
recursively. This means that there is no need to specify the \fB-R\fR option.
This flag is effective only if you specify script(s) from the command-line. The
default is \fBno\fR.

.TP
.B AUTOCOMPILE
If this is set \fByes\fR, the initscript automatically tries to compile
specified scripts when needed if there is no valid cache. Otherwise, the related
command simply fails. The default is \fByes\fR.

.TP
.B DEFAULT_START
Specify scripts which will be started by default. If omitted (or empty), all
scripts in the script directory will be started. The default is \fB""\fR.

.TP
.B ALLOW_CACHEONLY
If this is set \fByes\fR, the initscript will also allow operating on scripts
that are located in the cache directory, but not in the script directory. The
default is \fBno\fR.

WARNING: the initscript may load unexpected obsolete caches with this option.
The cache directory should be checked before enabling this option.

.TP
.B LOG_BOOT_ERR
Because boot-time scripts are run before the root filesystem is mounted,
staprun's stderr cannot be logged to the LOG_FILE as usual. However, the log
can instead be output to /run/systemtap/$script.log by setting LOG_BOOT_ERR
to \fByes\fR. If STAT_PATH is different from the default, the log files will be
moved there upon executing any of the initscript commands. The default is
\fBno\fR.

.PP
Here is a global configuration file example:
.SAMPLE
SCRIPT_PATH=/var/systemtap/script.d/
PASSALL=yes
RECURSIVE=no
.ESAMPLE

.SH SCRIPT PARAMETERS
These parameters affect the compilation or runtime behaviour of specific
SystemTap scripts. They must be placed in config files located in the
CONFIG_PATH directory.

.TP
.B <SCRIPT>_OPT
Specify options passed to the \fIstap\fR(1) command for the SCRIPT. Here, SCRIPT
is the name of the script file without the \fB.stp\fR extension. Note that the
\fB-F\fR option is always added.

The following options are ignored when compiling scripts: -p, -m, -r, -c, -x,
-e, -s, -o, -h, -V, -k.

The following options are ignored when running starting scripts: -h, -V, -v, -t,
-p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u, -q, -w, -l, -d, -L, -F, and all
long options.

.TP
.B <SCRIPT>_REQ
Specify script dependencies (i.e. which script this script requires). For
example, if foo.stp requires (or needs to run after) bar.stp, set
.SAMPLE
foo_REQ="bar"
.ESAMPLE
Specify multiple scripts by separating their names by spaces.

.PP
Here is a script configuration file example:
.SAMPLE
script1_OPT="-o /var/log/script1.out"
script2_OPT="-o /var/log/script2.out"
script2_REQ="script1"
.ESAMPLE

.SH EXAMPLES

.TP
.B INSTALLING SCRIPTS
We first copy a SystemTap script (e.g. "script1.stp") into the script directory:
.SAMPLE
\fB#\fR cp script1.stp /etc/systemtap/script.d/
.ESAMPLE
We can then set any script options, for example:
.SAMPLE
\fB#\fR vi /etc/systemtap/conf.d/group1.conf
script1_OPT="-o /var/log/group1.out"
.ESAMPLE
We then install a script (e.g. "script2.stp") which needs to run after
script1. In this case, we can do the following:
.SAMPLE
\fB#\fR cp script2.stp /etc/systemtap/script.d/
\fB#\fR vi /etc/systemtap/conf.d/group1.conf
script2_OPT="-o /var/log/group2.out"
script2_REQ="script1"
.ESAMPLE
This way, if \fIstap\fR(1) fails to run script1, the initscript will not even
try to run script2.

.TP
.B TESTING
After installing scripts, we can test that they work by simply doing:
.SAMPLE
\fB#\fR systemtap-service start
\fB#\fR systemtap-service stop
.ESAMPLE
We could be more specific as well, for example:
.SAMPLE
\fB#\fR systemtap-service start script1
\fB#\fR systemtap-service stop script1
.ESAMPLE
If there were no errors, we are ready to use it.

.TP
.B ENABLING SERVICE
After we're satisfied with the scripts and their tests, we can enable the
SystemTap initscript service:
.SAMPLE
\fB#\fR chkconfig systemtap on
.ESAMPLE

.TP
.B DELETING SCRIPTS
Scripts are deleted by simply removing them from the script directory and
removing any configuration lines specific to them:
.SAMPLE
\fB#\fR rm /etc/systemtap/script.d/script2.stp
\fB#\fR vi /etc/systemtap/conf.d/group1.conf
.ESAMPLE
If the script is still running, we also need to stop it:
.SAMPLE
\fB#\fR systemtap-service stop script2
.ESAMPLE
We can then also remove the cache associated with the script:
.SAMPLE
\fB#\fR systemtap-service cleanup script2
.ESAMPLE

.TP
.B PREPARING FOR KERNEL UPDATES
Usually, there is nothing to do when booting into a new kernel. The initscript
will see that the kernel version is different and will compile the scripts. The
compilation can be done beforehand as well to avoid having to compile during
boot by using the \fB-r\fR option:
.SAMPLE
\fB#\fR systemtap-service compile myscript -r <NEW_KERNEL_VERSION>
.ESAMPLE

.TP
.B IMPORTING COMPILED SCRIPTS
For environments which lack compilation infrastructure (e.g. no compilers or
debuginfo), such as a production system, the scripts can be compiled on another
(development) machine and then transferred over to the production system:
.SAMPLE
\fB#\fR systemtap-service compile myscript -r \\
.br
>   <KERNEL_VERSION_OF_TARGET_MACHINE>
\fB#\fR tar czf stap-scripts-<kernel-version>.tar.gz \\
.br
>   /var/cache/systemtap/<kernel-version> \\
.br
>   /etc/systemtap/conf.d/<configfile>
.ESAMPLE
And then copy this package to the target machine and extract it.

.TP
.B STARTING SCRIPTS DURING EARLY-BOOT
The initscript also allows us to start scripts earlier during the boot process
by creating an initramfs containing the script's module. The system must be
dracut-based for this to work. Starting a script at this stage gives access to
information otherwise very hard to obtain.

We first install the script by copying it into the script directory as usual and
setting whatever options we'd like:
.SAMPLE
\fB#\fR cp myscript.stp /etc/systemtap/script.d
\fB#\fR vi /etc/systemtap/conf.d/myscript.conf
.ESAMPLE
To add the script to the initramfs, we use the \fBonboot\fR command:
.SAMPLE
\fB#\fR systemtap-service onboot myscript
.ESAMPLE
If the script is not already compiled and cached, it will be done at this point.
A new initramfs will then be created at the default location. We can use the
\fB-b\fR option to ensure that the existing initramfs is backed up. We can then
restart the system.

.TP
.B USING A DIFFERENT INITRAMFS
If we would prefer to only start the script for one boot and not others, it
might be easier to instead use the \fB-o\fR option to specify a different
initramfs output file:
.SAMPLE
\fB#\fR systemtap-service onboot myscript \\
>   -o /boot/special_initramfs.img
.ESAMPLE
Once the initramfs is created, it's simply a matter of changing the command-line
options at boot-time so that the new image is used rather than the usual one.

.TP
.B CREATING AN INITRAMFS FOR A DIFFERENT KERNEL
Just like the compile command, we can use the \fB-r\fR option to specify the
kernel for which we want to create the initramfs. This is useful when we are
about to upgrade and would like to prepare in advance. For example:
.SAMPLE
\fB#\fR systemtap-service onboot myscript \\
>   -r 3.12.6-200.fc19.x86_64
.ESAMPLE

.TP
.B REMOVING SCRIPTS FROM THE INITRAMFS
Finally, to remove all script from the initramfs, we simple run the \fBonboot\fR
command without specifying any scripts:
.SAMPLE
\fB#\fR systemtap-service onboot
.ESAMPLE
This will simply create a standard initramfs without any SystemTap modules
inserted.

.TP
.B TROUBLESHOOTING EARLY-BOOT ISSUES
There can be many reasons for which the module didn't insert or did not work as
expected. It may be useful to turn on dracut debugging by adding 'rdinitdebug'
to the kernel command-line and checking dmesg/journalctl -ae. Also, the stderr
output of staprun can be captured by setting the LOG_BOOT_ERR option to
\fByes\fR.

.SH SEE ALSO
.IR stap (1)
.IR dracut (8)
.IR new-kernel-pkg (8)

.SH BUGS
Use the Bugzilla link of the project web page or our mailing list.
.nh
.BR http://sourceware.org/systemtap/ ", " <systemtap@sourceware.org> .
.hy