| 1 |
.\" -*- nroff -*- |
| 2 |
.TH SYSTEMTAP 8 |
| 3 |
.SH NAME |
| 4 |
systemtap-service \- SystemTap initscript and systemd service |
| 5 |
|
| 6 |
.\" macros |
| 7 |
.de SAMPLE |
| 8 |
|
| 9 |
.nr oldin \\n(.i |
| 10 |
.br |
| 11 |
.RS |
| 12 |
.nf |
| 13 |
.nh |
| 14 |
.. |
| 15 |
.de ESAMPLE |
| 16 |
.hy |
| 17 |
.fi |
| 18 |
.RE |
| 19 |
.in \\n[oldin]u |
| 20 |
|
| 21 |
.. |
| 22 |
|
| 23 |
.SH SYNOPSIS |
| 24 |
.B systemtap-service |
| 25 |
.IR COMMAND " [" OPTIONS "] [" SCRIPT ...] |
| 26 |
|
| 27 |
.B service systemtap |
| 28 |
.IR COMMAND " [" OPTIONS "] [" SCRIPT ...] |
| 29 |
|
| 30 |
.SH DESCRIPTION |
| 31 |
The SystemTap initscript aims to provide a way to run scripts as a service and |
| 32 |
easily control them individually. Scripts can be configured to start upon manual |
| 33 |
request, or during system startup. On dracut-based systems, it is also possible |
| 34 |
to integrate scripts in the initramfs and have them start during early-boot. |
| 35 |
|
| 36 |
The SystemTap initscript can be invoked manually using the |
| 37 |
.B systemtap-service |
| 38 |
command. On systemd-based systems, the initscript is controlled by |
| 39 |
.B systemctl |
| 40 |
with the service file |
| 41 |
\fBsystemtap.service\fR. |
| 42 |
|
| 43 |
There are various parameters and options available to modify global behaviour, |
| 44 |
as well as script behaviour. Dependencies between scripts can be established so |
| 45 |
that starting one starts others. |
| 46 |
|
| 47 |
The configuration file of the initscript is located at |
| 48 |
\fB@sysconfdir@/systemtap/config\fR. Acceptable parameters are detailed in the |
| 49 |
GLOBAL PARAMETERS section. |
| 50 |
|
| 51 |
Scripts must be placed in the \fB@sysconfdir@/systemtap/script.d\fR directory |
| 52 |
and must have a \fB.stp\fR extension. When referring to them on the |
| 53 |
command-line however, there in no need to include the \fB.stp\fR extension. |
| 54 |
Script names can only contain alphanumeric characters (and '_') and must not |
| 55 |
start with a number. The scripts directory may be changed by setting the |
| 56 |
SCRIPT_PATH parameter in the configuration file. |
| 57 |
|
| 58 |
.SH COMMANDS |
| 59 |
One of the commands below must be specified: |
| 60 |
|
| 61 |
.TP |
| 62 |
.B start |
| 63 |
Start \fISCRIPT\fRs. If no scripts are specified, start the scripts specified by |
| 64 |
the DEFAULT_START configuration. If DEFAULT_START is not set, start all scripts |
| 65 |
in the script directory. For scripts already started, the command is ignored. |
| 66 |
The command will fail if the scripts fail to start (see also the PASSALL |
| 67 |
configuration). |
| 68 |
|
| 69 |
If the AUTOCOMPILE configuration is on, the command will try to compile or |
| 70 |
update the specified scripts when one of the below conditions is true: |
| 71 |
.RS |
| 72 |
.IP - 2 |
| 73 |
The compiled cache file does not exist. |
| 74 |
.IP - |
| 75 |
The mtime (modified timestamp) of the original script file is newer than the |
| 76 |
time of the compiled script cache. |
| 77 |
.IP - |
| 78 |
The specified stap options used to compile the script has been changed (see |
| 79 |
also the SCRIPT PARAMETERS section). |
| 80 |
.IP - |
| 81 |
The result of `uname -a` has been changed. |
| 82 |
.RE |
| 83 |
|
| 84 |
.TP |
| 85 |
.B stop |
| 86 |
Stop \fISCRIPT\fRs. If no scripts are specified, stop all running scripts. For |
| 87 |
scripts already stopped, the command is ignored. The command will fail if the |
| 88 |
scripts fail to stop (see also the PASSALL configuration). |
| 89 |
|
| 90 |
.TP |
| 91 |
.B restart |
| 92 |
Stop and start \fISCRIPT\fRs. |
| 93 |
|
| 94 |
.TP |
| 95 |
.B status |
| 96 |
Show the state of \fISCRIPT\fRs and their dependencies. |
| 97 |
|
| 98 |
.TP |
| 99 |
.B compile |
| 100 |
Compile \fISCRIPT\fRs but do not start them. If the scripts have already been |
| 101 |
compiled, prompt for confirmation before overwriting cache. Compile for the |
| 102 |
current kernel, or the kernel release specified by the \fB-r\fR option. |
| 103 |
|
| 104 |
.TP |
| 105 |
.B onboot |
| 106 |
Make \fISCRIPT\fRs part of the initramfs so that they are started earlier during |
| 107 |
the boot process. This command is only available on dracut-based systems. If no |
| 108 |
scripts are specified, create a normal initramfs devoid of any SystemTap files. |
| 109 |
|
| 110 |
The initramfs is created for the current kernel, or the kernel release specified |
| 111 |
by the \fB-r\fR option. The path of the created initramfs defaults to |
| 112 |
\fB/boot/initramfs-KVER.img\fR, where KVER is the output of `uname -r`. The |
| 113 |
bootloader is also updated (using \fInew-kernel-pkg\fR(8)) to make the kernel |
| 114 |
entry use the new initramfs file. Use the \fB-o\fR option to specify a different |
| 115 |
path (the bootloader will not be updated). |
| 116 |
|
| 117 |
If the output file already exists, it is overwritten, unless the \fB-b\fR switch |
| 118 |
is given, in which case the file is appended \fB.bak\fR rather than overwritten. |
| 119 |
However, if there is already a \fB.bak\fR version of the file, the backup will |
| 120 |
not be overwritten. |
| 121 |
|
| 122 |
WARNING: do not use the \fB-o\fR option of \fIstap\fR(1) with onboot scripts |
| 123 |
because the script is started before the root filesystem is even mounted. |
| 124 |
Increase the buffer size if more space is needed. |
| 125 |
|
| 126 |
.TP |
| 127 |
.B cleanup |
| 128 |
Delete the compiled \fISCRIPT\fRs from cache. If no scripts are specified, then |
| 129 |
all compiled scripts are deleted. Only the cache for the current kernel is |
| 130 |
deleted, or the kernel release specified by the \fB-r\fR option. Prompt for |
| 131 |
confirmation before deleting. |
| 132 |
|
| 133 |
.SH OPTIONS |
| 134 |
Many of the commands can also take options. However, since users can't pass |
| 135 |
these options on boot, they are only meant for managing scripts after boot and |
| 136 |
for testing. Available options are: |
| 137 |
|
| 138 |
.TP |
| 139 |
.BI "-c " CONFIG_FILE |
| 140 |
Specify a different configuration file in place of the default one. |
| 141 |
|
| 142 |
.TP |
| 143 |
.B -R |
| 144 |
When using the \fBstart\fR and \fBstop\fR commands, also include the scripts' |
| 145 |
dependencies (recursively). |
| 146 |
|
| 147 |
.TP |
| 148 |
.BI "-r " KERNEL_RELEASE |
| 149 |
When using the \fBcompile\fR, \fBonboot\fR, and \fBcleanup\fR commands, specify |
| 150 |
the target kernel version rather than using the current one. Must be in the same |
| 151 |
format as `uname -r`. |
| 152 |
|
| 153 |
.TP |
| 154 |
.B -y |
| 155 |
Answer yes for all prompts. |
| 156 |
|
| 157 |
.TP |
| 158 |
.BI "-o " PATH.IMG |
| 159 |
When using the \fBonboot\fR command, specify the output path of the created |
| 160 |
initramfs. When specified, the bootloader configuration is not updated. |
| 161 |
|
| 162 |
.TP |
| 163 |
.B -b |
| 164 |
When using the \fBonboot\fR command, backup an existing initramfs image by |
| 165 |
adding a \fB.bak\fR extension rather than overwriting it. Without this option, |
| 166 |
the initramfs is overwritten. |
| 167 |
|
| 168 |
.SH GLOBAL PARAMETERS |
| 169 |
These parameters affect the general behaviour of the SystemTap initscript |
| 170 |
service. They can be specified in the configuration file. |
| 171 |
|
| 172 |
.TP |
| 173 |
.B SCRIPT_PATH |
| 174 |
Specify the absolute path of the script directory. These are the scripts on |
| 175 |
which the initscript can operate. Scripts must have the \fB.stp\fR extension. |
| 176 |
The default path is \fB@sysconfdir@/systemtap/script.d\fR. |
| 177 |
|
| 178 |
.TP |
| 179 |
.B CONFIG_PATH |
| 180 |
Specify the absolute path of the script configuration directory. These |
| 181 |
configuration files contain options for specific scripts. They must have the |
| 182 |
\fB.conf\fR extension. The default path is \fB@sysconfdir@/systemtap/conf.d\fR. |
| 183 |
|
| 184 |
.TP |
| 185 |
.B CACHE_PATH |
| 186 |
Specify the absolute path of the cache directory. The default path is |
| 187 |
\fB@localstatedir@/cache/systemtap\fR. |
| 188 |
|
| 189 |
.TP |
| 190 |
.B TEMP_PATH |
| 191 |
Specify the absolute path of the temporary directory in which SystemTap |
| 192 |
makes temporary directories to compile scripts. The default path is \fB/tmp\fR. |
| 193 |
|
| 194 |
.TP |
| 195 |
.B STAT_PATH |
| 196 |
Specify the absolute path of the directory containing PID files used to track |
| 197 |
the status of SystemTap scripts. The default path is |
| 198 |
\fB@localstatedir@/run/systemtap\fR. |
| 199 |
|
| 200 |
.TP |
| 201 |
.B LOG_FILE |
| 202 |
Specify the absolute path of the log file. All messages are sent to this file, |
| 203 |
including compilation and runtime errors. The default path is |
| 204 |
\fB@localstatedir@/log/systemtap.log\fR. |
| 205 |
|
| 206 |
.TP |
| 207 |
.B PASSALL |
| 208 |
If this is set \fByes\fR, initscript commands that operate on multiple scripts |
| 209 |
will report as failed when the action could not be performed on at least one |
| 210 |
script. If set to \fBno\fR, only a warning is emitted. The default is \fByes\fR. |
| 211 |
|
| 212 |
.TP |
| 213 |
.B RECURSIVE |
| 214 |
If this is set \fByes\fR, the initscript will always follow script dependencies |
| 215 |
recursively. This means that there is no need to specify the \fB-R\fR option. |
| 216 |
This flag is effective only if you specify script(s) from the command-line. The |
| 217 |
default is \fBno\fR. |
| 218 |
|
| 219 |
.TP |
| 220 |
.B AUTOCOMPILE |
| 221 |
If this is set \fByes\fR, the initscript automatically tries to compile |
| 222 |
specified scripts when needed if there is no valid cache. Otherwise, the related |
| 223 |
command simply fails. The default is \fByes\fR. |
| 224 |
|
| 225 |
.TP |
| 226 |
.B DEFAULT_START |
| 227 |
Specify scripts which will be started by default. If omitted (or empty), all |
| 228 |
scripts in the script directory will be started. The default is \fB""\fR. |
| 229 |
|
| 230 |
.TP |
| 231 |
.B ALLOW_CACHEONLY |
| 232 |
If this is set \fByes\fR, the initscript will also allow operating on scripts |
| 233 |
that are located in the cache directory, but not in the script directory. The |
| 234 |
default is \fBno\fR. |
| 235 |
|
| 236 |
WARNING: the initscript may load unexpected obsolete caches with this option. |
| 237 |
The cache directory should be checked before enabling this option. |
| 238 |
|
| 239 |
.TP |
| 240 |
.B LOG_BOOT_ERR |
| 241 |
Because boot-time scripts are run before the root filesystem is mounted, |
| 242 |
staprun's stderr cannot be logged to the LOG_FILE as usual. However, the log |
| 243 |
can instead be output to /run/systemtap/$script.log by setting LOG_BOOT_ERR |
| 244 |
to \fByes\fR. If STAT_PATH is different from the default, the log files will be |
| 245 |
moved there upon executing any of the initscript commands. The default is |
| 246 |
\fBno\fR. |
| 247 |
|
| 248 |
.PP |
| 249 |
Here is a global configuration file example: |
| 250 |
.SAMPLE |
| 251 |
SCRIPT_PATH=/var/systemtap/script.d/ |
| 252 |
PASSALL=yes |
| 253 |
RECURSIVE=no |
| 254 |
.ESAMPLE |
| 255 |
|
| 256 |
.SH SCRIPT PARAMETERS |
| 257 |
These parameters affect the compilation or runtime behaviour of specific |
| 258 |
SystemTap scripts. They must be placed in config files located in the |
| 259 |
CONFIG_PATH directory. |
| 260 |
|
| 261 |
.TP |
| 262 |
.B <SCRIPT>_OPT |
| 263 |
Specify options passed to the \fIstap\fR(1) command for the SCRIPT. Here, SCRIPT |
| 264 |
is the name of the script file without the \fB.stp\fR extension. Note that the |
| 265 |
\fB-F\fR option is always added. |
| 266 |
|
| 267 |
The following options are ignored when compiling scripts: -p, -m, -r, -c, -x, |
| 268 |
-e, -s, -o, -h, -V, -k. |
| 269 |
|
| 270 |
The following options are ignored when running starting scripts: -h, -V, -v, -t, |
| 271 |
-p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u, -q, -w, -l, -d, -L, -F, and all |
| 272 |
long options. |
| 273 |
|
| 274 |
.TP |
| 275 |
.B <SCRIPT>_REQ |
| 276 |
Specify script dependencies (i.e. which script this script requires). For |
| 277 |
example, if foo.stp requires (or needs to run after) bar.stp, set |
| 278 |
.SAMPLE |
| 279 |
foo_REQ="bar" |
| 280 |
.ESAMPLE |
| 281 |
Specify multiple scripts by separating their names by spaces. |
| 282 |
|
| 283 |
.PP |
| 284 |
Here is a script configuration file example: |
| 285 |
.SAMPLE |
| 286 |
script1_OPT="-o /var/log/script1.out" |
| 287 |
script2_OPT="-o /var/log/script2.out" |
| 288 |
script2_REQ="script1" |
| 289 |
.ESAMPLE |
| 290 |
|
| 291 |
.SH EXAMPLES |
| 292 |
|
| 293 |
.TP |
| 294 |
.B INSTALLING SCRIPTS |
| 295 |
We first copy a SystemTap script (e.g. "script1.stp") into the script directory: |
| 296 |
.SAMPLE |
| 297 |
\fB#\fR cp script1.stp /etc/systemtap/script.d/ |
| 298 |
.ESAMPLE |
| 299 |
We can then set any script options, for example: |
| 300 |
.SAMPLE |
| 301 |
\fB#\fR vi /etc/systemtap/conf.d/group1.conf |
| 302 |
script1_OPT="-o /var/log/group1.out" |
| 303 |
.ESAMPLE |
| 304 |
We then install a script (e.g. "script2.stp") which needs to run after |
| 305 |
script1. In this case, we can do the following: |
| 306 |
.SAMPLE |
| 307 |
\fB#\fR cp script2.stp /etc/systemtap/script.d/ |
| 308 |
\fB#\fR vi /etc/systemtap/conf.d/group1.conf |
| 309 |
script2_OPT="-o /var/log/group2.out" |
| 310 |
script2_REQ="script1" |
| 311 |
.ESAMPLE |
| 312 |
This way, if \fIstap\fR(1) fails to run script1, the initscript will not even |
| 313 |
try to run script2. |
| 314 |
|
| 315 |
.TP |
| 316 |
.B TESTING |
| 317 |
After installing scripts, we can test that they work by simply doing: |
| 318 |
.SAMPLE |
| 319 |
\fB#\fR systemtap-service start |
| 320 |
\fB#\fR systemtap-service stop |
| 321 |
.ESAMPLE |
| 322 |
We could be more specific as well, for example: |
| 323 |
.SAMPLE |
| 324 |
\fB#\fR systemtap-service start script1 |
| 325 |
\fB#\fR systemtap-service stop script1 |
| 326 |
.ESAMPLE |
| 327 |
If there were no errors, we are ready to use it. |
| 328 |
|
| 329 |
.TP |
| 330 |
.B ENABLING SERVICE |
| 331 |
After we're satisfied with the scripts and their tests, we can enable the |
| 332 |
SystemTap initscript service: |
| 333 |
.SAMPLE |
| 334 |
\fB#\fR chkconfig systemtap on |
| 335 |
.ESAMPLE |
| 336 |
|
| 337 |
.TP |
| 338 |
.B DELETING SCRIPTS |
| 339 |
Scripts are deleted by simply removing them from the script directory and |
| 340 |
removing any configuration lines specific to them: |
| 341 |
.SAMPLE |
| 342 |
\fB#\fR rm /etc/systemtap/script.d/script2.stp |
| 343 |
\fB#\fR vi /etc/systemtap/conf.d/group1.conf |
| 344 |
.ESAMPLE |
| 345 |
If the script is still running, we also need to stop it: |
| 346 |
.SAMPLE |
| 347 |
\fB#\fR systemtap-service stop script2 |
| 348 |
.ESAMPLE |
| 349 |
We can then also remove the cache associated with the script: |
| 350 |
.SAMPLE |
| 351 |
\fB#\fR systemtap-service cleanup script2 |
| 352 |
.ESAMPLE |
| 353 |
|
| 354 |
.TP |
| 355 |
.B PREPARING FOR KERNEL UPDATES |
| 356 |
Usually, there is nothing to do when booting into a new kernel. The initscript |
| 357 |
will see that the kernel version is different and will compile the scripts. The |
| 358 |
compilation can be done beforehand as well to avoid having to compile during |
| 359 |
boot by using the \fB-r\fR option: |
| 360 |
.SAMPLE |
| 361 |
\fB#\fR systemtap-service compile myscript -r <NEW_KERNEL_VERSION> |
| 362 |
.ESAMPLE |
| 363 |
|
| 364 |
.TP |
| 365 |
.B IMPORTING COMPILED SCRIPTS |
| 366 |
For environments which lack compilation infrastructure (e.g. no compilers or |
| 367 |
debuginfo), such as a production system, the scripts can be compiled on another |
| 368 |
(development) machine and then transferred over to the production system: |
| 369 |
.SAMPLE |
| 370 |
\fB#\fR systemtap-service compile myscript -r \\ |
| 371 |
.br |
| 372 |
> <KERNEL_VERSION_OF_TARGET_MACHINE> |
| 373 |
\fB#\fR tar czf stap-scripts-<kernel-version>.tar.gz \\ |
| 374 |
.br |
| 375 |
> /var/cache/systemtap/<kernel-version> \\ |
| 376 |
.br |
| 377 |
> /etc/systemtap/conf.d/<configfile> |
| 378 |
.ESAMPLE |
| 379 |
And then copy this package to the target machine and extract it. |
| 380 |
|
| 381 |
.TP |
| 382 |
.B STARTING SCRIPTS DURING EARLY-BOOT |
| 383 |
The initscript also allows us to start scripts earlier during the boot process |
| 384 |
by creating an initramfs containing the script's module. The system must be |
| 385 |
dracut-based for this to work. Starting a script at this stage gives access to |
| 386 |
information otherwise very hard to obtain. |
| 387 |
|
| 388 |
We first install the script by copying it into the script directory as usual and |
| 389 |
setting whatever options we'd like: |
| 390 |
.SAMPLE |
| 391 |
\fB#\fR cp myscript.stp /etc/systemtap/script.d |
| 392 |
\fB#\fR vi /etc/systemtap/conf.d/myscript.conf |
| 393 |
.ESAMPLE |
| 394 |
To add the script to the initramfs, we use the \fBonboot\fR command: |
| 395 |
.SAMPLE |
| 396 |
\fB#\fR systemtap-service onboot myscript |
| 397 |
.ESAMPLE |
| 398 |
If the script is not already compiled and cached, it will be done at this point. |
| 399 |
A new initramfs will then be created at the default location. We can use the |
| 400 |
\fB-b\fR option to ensure that the existing initramfs is backed up. We can then |
| 401 |
restart the system. |
| 402 |
|
| 403 |
.TP |
| 404 |
.B USING A DIFFERENT INITRAMFS |
| 405 |
If we would prefer to only start the script for one boot and not others, it |
| 406 |
might be easier to instead use the \fB-o\fR option to specify a different |
| 407 |
initramfs output file: |
| 408 |
.SAMPLE |
| 409 |
\fB#\fR systemtap-service onboot myscript \\ |
| 410 |
> -o /boot/special_initramfs.img |
| 411 |
.ESAMPLE |
| 412 |
Once the initramfs is created, it's simply a matter of changing the command-line |
| 413 |
options at boot-time so that the new image is used rather than the usual one. |
| 414 |
|
| 415 |
.TP |
| 416 |
.B CREATING AN INITRAMFS FOR A DIFFERENT KERNEL |
| 417 |
Just like the compile command, we can use the \fB-r\fR option to specify the |
| 418 |
kernel for which we want to create the initramfs. This is useful when we are |
| 419 |
about to upgrade and would like to prepare in advance. For example: |
| 420 |
.SAMPLE |
| 421 |
\fB#\fR systemtap-service onboot myscript \\ |
| 422 |
> -r 3.12.6-200.fc19.x86_64 |
| 423 |
.ESAMPLE |
| 424 |
|
| 425 |
.TP |
| 426 |
.B REMOVING SCRIPTS FROM THE INITRAMFS |
| 427 |
Finally, to remove all script from the initramfs, we simple run the \fBonboot\fR |
| 428 |
command without specifying any scripts: |
| 429 |
.SAMPLE |
| 430 |
\fB#\fR systemtap-service onboot |
| 431 |
.ESAMPLE |
| 432 |
This will simply create a standard initramfs without any SystemTap modules |
| 433 |
inserted. |
| 434 |
|
| 435 |
.TP |
| 436 |
.B TROUBLESHOOTING EARLY-BOOT ISSUES |
| 437 |
There can be many reasons for which the module didn't insert or did not work as |
| 438 |
expected. It may be useful to turn on dracut debugging by adding 'rdinitdebug' |
| 439 |
to the kernel command-line and checking dmesg/journalctl -ae. Also, the stderr |
| 440 |
output of staprun can be captured by setting the LOG_BOOT_ERR option to |
| 441 |
\fByes\fR. |
| 442 |
|
| 443 |
.SH SEE ALSO |
| 444 |
.IR stap (1) |
| 445 |
.IR dracut (8) |
| 446 |
.IR new-kernel-pkg (8) |
| 447 |
|
| 448 |
.SH BUGS |
| 449 |
Use the Bugzilla link of the project web page or our mailing list. |
| 450 |
.nh |
| 451 |
.BR http://sourceware.org/systemtap/ ", " <[email protected]> . |
| 452 |
.hy |
| 453 |
|