service systemtap COMMAND [OPTIONS] [SCRIPT...]
The SystemTap initscript can be invoked manually using the systemtap-service command. On systemd-based systems, the initscript is controlled by systemctl with the service file systemtap.service.
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 ${prefix}/etc/systemtap/config. Acceptable parameters are detailed in the GLOBAL PARAMETERS section.
Scripts must be placed in the ${prefix}/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. 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.
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 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.
WARNING: the initscript may load unexpected obsolete caches with this option. The cache directory should be checked before enabling this option.
Here is a global configuration file example:
SCRIPT_PATH=/var/systemtap/script.d/ PASSALL=yes RECURSIVE=no
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.
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" script2_OPT="-o /var/log/script2.out" script2_REQ="script1"
# cp script1.stp /etc/systemtap/script.d/
We can then set any script options, for example:
# vi /etc/systemtap/conf.d/group1.conf script1_OPT="-o /var/log/group1.out"
We then install a script (e.g. "script2.stp") which needs to run after script1. In this case, we can do the following:
# cp script2.stp /etc/systemtap/script.d/ # vi /etc/systemtap/conf.d/group1.conf script2_OPT="-o /var/log/group2.out" script2_REQ="script1"
This way, if stap(1) fails to run script1, the initscript will not even try to run script2.
# systemtap-service start # systemtap-service stop
We could be more specific as well, for example:
# systemtap-service start script1 # systemtap-service stop script1
If there were no errors, we are ready to use it.
# chkconfig systemtap on
# rm /etc/systemtap/script.d/script2.stp # vi /etc/systemtap/conf.d/group1.conf
If the script is still running, we also need to stop it:
# systemtap-service stop script2
We can then also remove the cache associated with the script:
# systemtap-service cleanup script2
# systemtap-service compile myscript -r <NEW_KERNEL_VERSION>
# systemtap-service 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.
We first install the script by copying it into the script directory 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:
# systemtap-service 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.
# systemtap-service 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.
# systemtap-service onboot myscript \ > -r 3.12.6-200.fc19.x86_64
# systemtap-service onboot
This will simply create a standard initramfs without any SystemTap modules inserted.