SYSTEMTAP(8)SYSTEMTAP(8)NAMEsystemtap - SystemTap initscript service
SYNOPSIS
service systemtap COMMAND [OPTIONS] [SCRIPT...]
DESCRIPTION
The SystemTap initscript aims to provide a way to run scripts as a ser‐
vice 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.
There are various parameters and options available to modify global be‐
haviour, as well as script behaviour. Dependencies between scripts can
be established so that starting one starts others (especially conve‐
nient when using the -DRELAY_HOST and -DRELAY_GUEST options of
stap(1)).
The configuration file of the initscript is located at /etc/system‐
tap/config. Acceptable parameters are detailed in the GLOBAL PARAMETERS
section.
Scripts must be placed in the /etc/systemtap/script.d directory and
must have a .stp extension. When referring to them on the command-line
however, there in no need to include the .stp extension. The scripts
directory may be changed by setting the SCRIPT_PATH parameter in the
configuration file.
COMMANDS
One of the commands below must be specified:
start Start SCRIPTs. 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:
- The compiled cache file does not exist.
- The mtime (modified timestamp) of the original script file is
newer than the time of the compiled script cache.
- The specified stap options used to compile the script has been
changed (see also the SCRIPT PARAMETERS section).
- The result of `uname -a` has been changed.
stop Stop SCRIPTs. 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).
restart
Stop and start SCRIPTs.
status Show the state of SCRIPTs and their dependencies.
compile
Compile SCRIPTs but do not start them. If the scripts have
already been compiled, prompt for confirmation before overwrit‐
ing cache. Compile for the current kernel, or the kernel release
specified by the -r option.
onboot Make SCRIPTs part of the initramfs so that they are started ear‐
lier during the boot process. This command is only available on
dracut-based systems. If no scripts are specified, create a nor‐
mal initramfs devoid of any SystemTap files.
The initramfs is created for the current kernel, or the kernel
release specified by the -r option. The path of the created
initramfs defaults to /boot/initramfs-KVER.img, where KVER is
the output of `uname -r`. The bootloader is also updated (using
new-kernel-pkg(8)) to make the kernel entry use the new
initramfs file. Use the -o option to specify a different path
(the bootloader will not be updated).
If the output file already exists, it is overwritten, unless the
-b switch is given, in which case the file is appended .bak
rather than overwritten. However, if there is already a .bak
version of the file, the backup will not be overwritten.
WARNING: do not use the -o option of stap(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.
cleanup
Delete the compiled SCRIPTs from cache. If no scripts are speci‐
fied, then all compiled scripts are deleted. Only the cache for
the current kernel is deleted, or the kernel release specified
by the -r option. Prompt for confirmation before deleting.
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:
-c CONFIG_FILE
Specify a different configuration file in place of the default
one.
-R When using the start and stop commands, also include the
scripts' dependencies (recursively).
-r KERNEL_RELEASE
When using the compile, onboot, and cleanup commands, specify
the target kernel version rather than using the current one.
Must be in the same format as `uname -r`.
-y Answer yes for all prompts.
-o PATH.IMG
When using the onboot command, specify the output path of the
created initramfs. When specified, the bootloader configuration
is not updated.
-b When using the onboot command, backup an existing initramfs
image by adding a .bak extension rather than overwriting it.
Without this option, the initramfs is overwritten.
GLOBAL PARAMETERS
These parameters affect the general behaviour of the SystemTap
initscript service. They can be specified in the configuration file.
SCRIPT_PATH
Specify the absolute path of the script directory. These are the
scripts on which the initscript can operate. Scripts must have
the .stp extension. The default path is /etc/system‐
tap/script.d.
CONFIG_PATH
Specify the absolute path of the script configuration directory.
These configuration files contain options for specific scripts.
They must have the .conf extension. The default path is
/etc/systemtap/conf.d.
CACHE_PATH
Specify the absolute path of the cache directory. The default
path is /var/cache/systemtap.
TEMP_PATH
Specify the absolute path of the temporary directory in which
SystemTap makes temporary directories to compile scripts. The
default path is /tmp.
STAT_PATH
Specify the absolute path of the directory containing PID files
used to track the status of SystemTap scripts. The default path
is /var/run/systemtap.
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 /var/log/systemtap.log.
PASSALL
If this is set yes, initscript commands that operate on multiple
scripts will report as failed when the action could not be per‐
formed on at least one script. If set to no, only a warning is
emitted. The default is yes.
RECURSIVE
If this is set yes, the initscript will always follow script
dependencies recursively. This means that there is no need to
specify the -R option. This flag is effective only if you spec‐
ify script(s) from the command-line. The default is no.
AUTOCOMPILE
If this is set yes, the initscript automatically tries to com‐
pile specified scripts when needed if there is no valid cache.
Otherwise, the related command simply fails. The default is yes.
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 "".
ALLOW_CACHEONLY
If this is set yes, the initscript will also allow operating on
scripts that are located in the cache directory, but not in the
script directory. The default is no.
WARNING: the initscript may load unexpected obsolete caches with
this option. The cache directory should be checked before
enabling this option.
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 /var/run/sys‐
temtap/$script.log by setting LOG_BOOT_ERR to yes. 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
no.
Here is a global configuration file example:
SCRIPT_PATH=/var/systemtap/script.d/
PASSALL=yes
RECURSIVE=no
SCRIPT PARAMETERS
These parameters affect the compilation or runtime behaviour of specif‐
ic SystemTap scripts. They must be placed in config files located in
the CONFIG_PATH directory.
<SCRIPT>_OPT
Specify options passed to the stap(1) command for the SCRIPT.
Here, SCRIPT is the name of the script file without the .stp ex‐
tension. Note that the -F 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.
<SCRIPT>_REQ
Specify script dependencies (i.e. which script this script re‐
quires). For example, if foo.stp requires (or needs to run af‐
ter) bar.stp, set
foo_REQ="bar"
Specify multiple scripts by separating their names by spaces.
Here is a script configuration file example:
script1_OPT="-o /var/log/script1.out -DRELAY_HOST=group1"
script2_OPT="-DRELAY_GUEST=group1"
script2_REQ="script1"
EXAMPLES
INSTALLING SCRIPTS
We first copy a SystemTap script (e.g. "script1.stp") into the
script directory:
# cp script1.stp /etc/systemtap/script.d/
We can then set any script options, for example:
# vi /etc/systemtap/conf.d/group1
script1_OPT="-o /var/log/group1.out -DRELAY_HOST=group1"
If we then install a script (e.g. "script2.stp") which shares a
buffer with script1, there is a dependency. In this case, we can
do the following:
# cp script2.stp /etc/systemtap/script.d/
# vi /etc/systemtap/conf.d/group1
script2_OPT="-DRELAY_GUEST=group1"
script2_REQ="script1"
This way, if stap(1) fails to run script1, the initscript will
not even try to run script2.
TESTING
After installing scripts, we can test that they work by simply
doing:
# service systemtap start
# service systemtap stop
We could be more specific as well, for example:
# service systemtap start script1
# service systemtap stop script1
If there were no errors, we are ready to use it.
ENABLING SERVICE
After we're satisfied with the scripts and their tests, we can
enable the SystemTap initscript service:
# chkconfig systemtap on
DELETING SCRIPTS
Scripts are deleted by simply removing them from the script di‐
rectory and removing any configuration lines specific to them:
# rm /etc/systemtap/script.d/script2.stp
# vi /etc/systemtap/conf.d/group1
If the script is still running, we also need to stop it:
# service systemtap stop script2
We can then also remove the cache associated with the script:
# service systemtap cleanup script2
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 -r
option:
# service systemtap compile myscript -r <NEW_KERNEL_VERSION>
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:
# service systemtap compile myscript -r \
> <KERNEL_VERSION_OF_TARGET_MACHINE>
# tar czf stap-scripts-<kernel-version>.tar.gz \
> /var/cache/systemtap/<kernel-version> \
> /etc/systemtap/conf.d/<configfile>
And then copy this package to the target machine and extract it.
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 informa‐
tion otherwise very hard to obtain.
We first install the script by copying it into the script direc‐
tory as usual and setting whatever options we'd like:
# cp myscript.stp /etc/systemtap/script.d
# vi /etc/systemtap/conf.d/myscript.conf
To add the script to the initramfs, we use the onboot command:
# service systemtap onboot myscript
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 -b option to ensure that the
existing initramfs is backed up. We can then restart the system.
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 -o option to spec‐
ify a different initramfs output file:
# service systemtap onboot myscript \
> -o /boot/special_initramfs.img
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.
CREATING AN INITRAMFS FOR A DIFFERENT KERNEL
Just like the compile command, we can use the -r option to spec‐
ify 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:
# service systemtap onboot myscript \
> -r 3.12.6-200.fc19.x86_64
REMOVING SCRIPTS FROM THE INITRAMFS
Finally, to remove all script from the initramfs, we simple run
the onboot command without specifying any scripts:
# service systemtap onboot
This will simply create a standard initramfs without any System‐
Tap modules inserted.
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 de‐
bugging 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
yes.
SEE ALSOstap(1)dracut(8)new-kernel-pkg(8)BUGS
Use the Bugzilla link of the project web page or our mailing list.
http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
SYSTEMTAP(8)
