1SYSTEMTAP(8) System Manager's Manual SYSTEMTAP(8)
2
6 systemtap-service - SystemTap initscript and systemd service
7
11 systemtap-service COMMAND [OPTIONS] [SCRIPT...]
12 service systemtap COMMAND [OPTIONS] [SCRIPT...]
14
17 The SystemTap initscript aims to provide a way to run scripts as a ser‐
18 vice and easily control them individually. Scripts can be configured to
19 start upon manual request, or during system startup. On dracut-based
20 systems, it is also possible to integrate scripts in the initramfs and
21 have them start during early-boot.
22 The SystemTap initscript can be invoked manually using the systemtap-
24 service command. On systemd-based systems, the initscript is controlled
25 by systemctl with the service file systemtap.service.
26 There are various parameters and options available to modify global be‐
28 haviour, as well as script behaviour. Dependencies between scripts can
29 be established so that starting one starts others.
30 The configuration file of the initscript is located at /etc/system‐
32 tap/config. Acceptable parameters are detailed in the GLOBAL PARAMETERS
33 section.
34 Scripts must be placed in the /etc/systemtap/script.d directory and
36 must have a .stp extension. When referring to them on the command-line
37 however, there in no need to include the .stp extension. Script names
38 can only contain alphanumeric characters (and '_') and must not start
39 with a number. The scripts directory may be changed by setting the
40 SCRIPT_PATH parameter in the configuration file.
41
44 One of the commands below must be specified:
45 start Start SCRIPTs. If no scripts are specified, start the scripts
48 specified by the DEFAULT_START configuration. If DEFAULT_START
49 is not set, start all scripts in the script directory. For
50 scripts already started, the command is ignored. The command
51 will fail if the scripts fail to start (see also the PASSALL
52 configuration).
53 If the AUTOCOMPILE configuration is on, the command will try to
55 compile or update the specified scripts when one of the below
56 conditions is true:
57 - The compiled cache file does not exist.
59 - The mtime (modified timestamp) of the original script file is
61 newer than the time of the compiled script cache.
62 - The specified stap options used to compile the script has been
64 changed (see also the SCRIPT PARAMETERS section).
65 - The result of `uname -a` has been changed.
67 stop Stop SCRIPTs. If no scripts are specified, stop all running
70 scripts. For scripts already stopped, the command is ignored.
71 The command will fail if the scripts fail to stop (see also the
72 PASSALL configuration).
73 restart
76 Stop and start SCRIPTs.
77 status Show the state of SCRIPTs and their dependencies.
80 compile
83 Compile SCRIPTs but do not start them. If the scripts have
84 already been compiled, prompt for confirmation before overwrit‐
85 ing cache. Compile for the current kernel, or the kernel release
86 specified by the -r option.
87 onboot Make SCRIPTs part of the initramfs so that they are started ear‐
90 lier during the boot process. This command is only available on
91 dracut-based systems. If no scripts are specified, create a nor‐
92 mal initramfs devoid of any SystemTap files.
93 The initramfs is created for the current kernel, or the kernel
95 release specified by the -r option. The path of the created
96 initramfs defaults to /boot/initramfs-KVER.img, where KVER is
97 the output of `uname -r`. The bootloader is also updated (using
98 new-kernel-pkg(8)) to make the kernel entry use the new
99 initramfs file. Use the -o option to specify a different path
100 (the bootloader will not be updated).
101 If the output file already exists, it is overwritten, unless the
103 -b switch is given, in which case the file is appended .bak
104 rather than overwritten. However, if there is already a .bak
105 version of the file, the backup will not be overwritten.
106 WARNING: do not use the -o option of stap(1) with onboot scripts
108 because the script is started before the root filesystem is even
109 mounted. Increase the buffer size if more space is needed.
110 cleanup
113 Delete the compiled SCRIPTs from cache. If no scripts are speci‐
114 fied, then all compiled scripts are deleted. Only the cache for
115 the current kernel is deleted, or the kernel release specified
116 by the -r option. Prompt for confirmation before deleting.
117
120 Many of the commands can also take options. However, since users can't
121 pass these options on boot, they are only meant for managing scripts
122 after boot and for testing. Available options are:
123 -c CONFIG_FILE
126 Specify a different configuration file in place of the default
127 one.
128 -R When using the start and stop commands, also include the
131 scripts' dependencies (recursively).
132 -r KERNEL_RELEASE
135 When using the compile, onboot, and cleanup commands, specify
136 the target kernel version rather than using the current one.
137 Must be in the same format as `uname -r`.
138 -y Answer yes for all prompts.
141 -o PATH.IMG
144 When using the onboot command, specify the output path of the
145 created initramfs. When specified, the bootloader configuration
146 is not updated.
147 -b When using the onboot command, backup an existing initramfs
150 image by adding a .bak extension rather than overwriting it.
151 Without this option, the initramfs is overwritten.
152
155 These parameters affect the general behaviour of the SystemTap
156 initscript service. They can be specified in the configuration file.
157 SCRIPT_PATH
160 Specify the absolute path of the script directory. These are the
161 scripts on which the initscript can operate. Scripts must have
162 the .stp extension. The default path is /etc/system‐
163 tap/script.d.
164 CONFIG_PATH
167 Specify the absolute path of the script configuration directory.
168 These configuration files contain options for specific scripts.
169 They must have the .conf extension. The default path is
170 /etc/systemtap/conf.d.
171 CACHE_PATH
174 Specify the absolute path of the cache directory. The default
175 path is /var/cache/systemtap.
176 TEMP_PATH
179 Specify the absolute path of the temporary directory in which
180 SystemTap makes temporary directories to compile scripts. The
181 default path is /tmp.
182 STAT_PATH
185 Specify the absolute path of the directory containing PID files
186 used to track the status of SystemTap scripts. The default path
187 is /var/run/systemtap.
188 LOG_FILE
191 Specify the absolute path of the log file. All messages are sent
192 to this file, including compilation and runtime errors. The
193 default path is /var/log/systemtap.log.
194 PASSALL
197 If this is set yes, initscript commands that operate on multiple
198 scripts will report as failed when the action could not be per‐
199 formed on at least one script. If set to no, only a warning is
200 emitted. The default is yes.
201 RECURSIVE
204 If this is set yes, the initscript will always follow script
205 dependencies recursively. This means that there is no need to
206 specify the -R option. This flag is effective only if you spec‐
207 ify script(s) from the command-line. The default is no.
208 AUTOCOMPILE
211 If this is set yes, the initscript automatically tries to com‐
212 pile specified scripts when needed if there is no valid cache.
213 Otherwise, the related command simply fails. The default is yes.
214 DEFAULT_START
217 Specify scripts which will be started by default. If omitted (or
218 empty), all scripts in the script directory will be started. The
219 default is "".
220 ALLOW_CACHEONLY
223 If this is set yes, the initscript will also allow operating on
224 scripts that are located in the cache directory, but not in the
225 script directory. The default is no.
226 WARNING: the initscript may load unexpected obsolete caches with
228 this option. The cache directory should be checked before
229 enabling this option.
230 LOG_BOOT_ERR
233 Because boot-time scripts are run before the root filesystem is
234 mounted, staprun's stderr cannot be logged to the LOG_FILE as
235 usual. However, the log can instead be output to /var/run/sys‐
236 temtap/$script.log by setting LOG_BOOT_ERR to yes. If STAT_PATH
237 is different from the default, the log files will be moved there
238 upon executing any of the initscript commands. The default is
239 no.
240 Here is a global configuration file example:
243 SCRIPT_PATH=/var/systemtap/script.d/
245 PASSALL=yes
246 RECURSIVE=no
247
251 These parameters affect the compilation or runtime behaviour of specif‐
252 ic SystemTap scripts. They must be placed in config files located in
253 the CONFIG_PATH directory.
254 <SCRIPT>_OPT
257 Specify options passed to the stap(1) command for the SCRIPT.
258 Here, SCRIPT is the name of the script file without the .stp ex‐
259 tension. Note that the -F option is always added.
260 The following options are ignored when compiling scripts: -p,
262 -m, -r, -c, -x, -e, -s, -o, -h, -V, -k.
263 The following options are ignored when running starting scripts:
265 -h, -V, -v, -t, -p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u,
266 -q, -w, -l, -d, -L, -F, and all long options.
267 <SCRIPT>_REQ
270 Specify script dependencies (i.e. which script this script re‐
271 quires). For example, if foo.stp requires (or needs to run af‐
272 ter) bar.stp, set
273 foo_REQ="bar"
275 Specify multiple scripts by separating their names by spaces.
277 Here is a script configuration file example:
280 script1_OPT="-o /var/log/script1.out"
282 script2_OPT="-o /var/log/script2.out"
283 script2_REQ="script1"
284
288 INSTALLING SCRIPTS
289 We first copy a SystemTap script (e.g. "script1.stp") into the
290 script directory:
291 # cp script1.stp /etc/systemtap/script.d/
293 We can then set any script options, for example:
295 # vi /etc/systemtap/conf.d/group1.conf
297 script1_OPT="-o /var/log/group1.out"
298 We then install a script (e.g. "script2.stp") which needs to run
300 after script1. In this case, we can do the following:
301 # cp script2.stp /etc/systemtap/script.d/
303 # vi /etc/systemtap/conf.d/group1.conf
304 script2_OPT="-o /var/log/group2.out"
305 script2_REQ="script1"
306 This way, if stap(1) fails to run script1, the initscript will
308 not even try to run script2.
309 TESTING
312 After installing scripts, we can test that they work by simply
313 doing:
314 # systemtap-service start
316 # systemtap-service stop
317 We could be more specific as well, for example:
319 # systemtap-service start script1
321 # systemtap-service stop script1
322 If there were no errors, we are ready to use it.
324 ENABLING SERVICE
327 After we're satisfied with the scripts and their tests, we can
328 enable the SystemTap initscript service:
329 # chkconfig systemtap on
331 DELETING SCRIPTS
335 Scripts are deleted by simply removing them from the script di‐
336 rectory and removing any configuration lines specific to them:
337 # rm /etc/systemtap/script.d/script2.stp
339 # vi /etc/systemtap/conf.d/group1.conf
340 If the script is still running, we also need to stop it:
342 # systemtap-service stop script2
344 We can then also remove the cache associated with the script:
346 # systemtap-service cleanup script2
348 PREPARING FOR KERNEL UPDATES
352 Usually, there is nothing to do when booting into a new kernel.
353 The initscript will see that the kernel version is different and
354 will compile the scripts. The compilation can be done beforehand
355 as well to avoid having to compile during boot by using the -r
356 option:
357 # systemtap-service compile myscript -r <NEW_KERNEL_VERSION>
359 IMPORTING COMPILED SCRIPTS
363 For environments which lack compilation infrastructure (e.g. no
364 compilers or debuginfo), such as a production system, the
365 scripts can be compiled on another (development) machine and
366 then transferred over to the production system:
367 # systemtap-service compile myscript -r \
369 > <KERNEL_VERSION_OF_TARGET_MACHINE>
370 # tar czf stap-scripts-<kernel-version>.tar.gz \
371 > /var/cache/systemtap/<kernel-version> \
372 > /etc/systemtap/conf.d/<configfile>
373 And then copy this package to the target machine and extract it.
375 STARTING SCRIPTS DURING EARLY-BOOT
378 The initscript also allows us to start scripts earlier during
379 the boot process by creating an initramfs containing the
380 script's module. The system must be dracut-based for this to
381 work. Starting a script at this stage gives access to informa‐
382 tion otherwise very hard to obtain.
383 We first install the script by copying it into the script direc‐
385 tory as usual and setting whatever options we'd like:
386 # cp myscript.stp /etc/systemtap/script.d
388 # vi /etc/systemtap/conf.d/myscript.conf
389 To add the script to the initramfs, we use the onboot command:
391 # systemtap-service onboot myscript
393 If the script is not already compiled and cached, it will be
395 done at this point. A new initramfs will then be created at the
396 default location. We can use the -b option to ensure that the
397 existing initramfs is backed up. We can then restart the system.
398 USING A DIFFERENT INITRAMFS
401 If we would prefer to only start the script for one boot and not
402 others, it might be easier to instead use the -o option to spec‐
403 ify a different initramfs output file:
404 # systemtap-service onboot myscript \
406 > -o /boot/special_initramfs.img
407 Once the initramfs is created, it's simply a matter of changing
409 the command-line options at boot-time so that the new image is
410 used rather than the usual one.
411 CREATING AN INITRAMFS FOR A DIFFERENT KERNEL
414 Just like the compile command, we can use the -r option to spec‐
415 ify the kernel for which we want to create the initramfs. This
416 is useful when we are about to upgrade and would like to prepare
417 in advance. For example:
418 # systemtap-service onboot myscript \
420 > -r 3.12.6-200.fc19.x86_64
421 REMOVING SCRIPTS FROM THE INITRAMFS
425 Finally, to remove all script from the initramfs, we simple run
426 the onboot command without specifying any scripts:
427 # systemtap-service onboot
429 This will simply create a standard initramfs without any System‐
431 Tap modules inserted.
432 TROUBLESHOOTING EARLY-BOOT ISSUES
435 There can be many reasons for which the module didn't insert or
436 did not work as expected. It may be useful to turn on dracut de‐
437 bugging by adding 'rdinitdebug' to the kernel command-line and
438 checking dmesg/journalctl -ae. Also, the stderr output of
439 staprun can be captured by setting the LOG_BOOT_ERR option to
440 yes.
441
444 stap(1) dracut(8) new-kernel-pkg(8)
445
448 Use the Bugzilla link of the project web page or our mailing list.
449 http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
450 SYSTEMTAP(8)