man/systemtap-service.8.in

   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 /var/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/ ", " <systemtap@sourceware.org> .
 452 .hy
 453