1SYSTEMTAP(8) System Manager's Manual SYSTEMTAP(8)
2
6 systemtap - SystemTap initscript service
7
11 service systemtap COMMAND [OPTIONS] [SCRIPT...]
12
15 The SystemTap initscript aims to provide a way to run scripts as a ser‐
16 vice and easily control them individually. Scripts can be configured to
17 start upon manual request, or during system startup. On dracut-based
18 systems, it is also possible to integrate scripts in the initramfs and
19 have them start during early-boot.
20 There are various parameters and options available to modify global be‐
22 haviour, as well as script behaviour. Dependencies between scripts can
23 be established so that starting one starts others (especially conve‐
24 nient when using the -DRELAY_HOST and -DRELAY_GUEST options of
25 stap(1)).
26 The configuration file of the initscript is located at /etc/system‐
28 tap/config. Acceptable parameters are detailed in the GLOBAL PARAMETERS
29 section.
30 Scripts must be placed in the /etc/systemtap/script.d directory and
32 must have a .stp extension. When referring to them on the command-line
33 however, there in no need to include the .stp extension. Script names
34 can only contain alphanumeric characters (and '_') and must not start
35 with a number. The scripts directory may be changed by setting the
36 SCRIPT_PATH parameter in the configuration file.
37
40 One of the commands below must be specified:
41 start Start SCRIPTs. If no scripts are specified, start the scripts
44 specified by the DEFAULT_START configuration. If DEFAULT_START
45 is not set, start all scripts in the script directory. For
46 scripts already started, the command is ignored. The command
47 will fail if the scripts fail to start (see also the PASSALL
48 configuration).
49 If the AUTOCOMPILE configuration is on, the command will try to
51 compile or update the specified scripts when one of the below
52 conditions is true:
53 - The compiled cache file does not exist.
55 - The mtime (modified timestamp) of the original script file is
57 newer than the time of the compiled script cache.
58 - The specified stap options used to compile the script has been
60 changed (see also the SCRIPT PARAMETERS section).
61 - The result of `uname -a` has been changed.
63 stop Stop SCRIPTs. If no scripts are specified, stop all running
66 scripts. For scripts already stopped, the command is ignored.
67 The command will fail if the scripts fail to stop (see also the
68 PASSALL configuration).
69 restart
72 Stop and start SCRIPTs.
73 status Show the state of SCRIPTs and their dependencies.
76 compile
79 Compile SCRIPTs but do not start them. If the scripts have
80 already been compiled, prompt for confirmation before overwrit‐
81 ing cache. Compile for the current kernel, or the kernel release
82 specified by the -r option.
83 onboot Make SCRIPTs part of the initramfs so that they are started ear‐
86 lier during the boot process. This command is only available on
87 dracut-based systems. If no scripts are specified, create a nor‐
88 mal initramfs devoid of any SystemTap files.
89 The initramfs is created for the current kernel, or the kernel
91 release specified by the -r option. The path of the created
92 initramfs defaults to /boot/initramfs-KVER.img, where KVER is
93 the output of `uname -r`. The bootloader is also updated (using
94 new-kernel-pkg(8)) to make the kernel entry use the new
95 initramfs file. Use the -o option to specify a different path
96 (the bootloader will not be updated).
97 If the output file already exists, it is overwritten, unless the
99 -b switch is given, in which case the file is appended .bak
100 rather than overwritten. However, if there is already a .bak
101 version of the file, the backup will not be overwritten.
102 WARNING: do not use the -o option of stap(1) with onboot scripts
104 because the script is started before the root filesystem is even
105 mounted. Increase the buffer size if more space is needed.
106 cleanup
109 Delete the compiled SCRIPTs from cache. If no scripts are speci‐
110 fied, then all compiled scripts are deleted. Only the cache for
111 the current kernel is deleted, or the kernel release specified
112 by the -r option. Prompt for confirmation before deleting.
113
116 Many of the commands can also take options. However, since users can't
117 pass these options on boot, they are only meant for managing scripts
118 after boot and for testing. Available options are:
119 -c CONFIG_FILE
122 Specify a different configuration file in place of the default
123 one.
124 -R When using the start and stop commands, also include the
127 scripts' dependencies (recursively).
128 -r KERNEL_RELEASE
131 When using the compile, onboot, and cleanup commands, specify
132 the target kernel version rather than using the current one.
133 Must be in the same format as `uname -r`.
134 -y Answer yes for all prompts.
137 -o PATH.IMG
140 When using the onboot command, specify the output path of the
141 created initramfs. When specified, the bootloader configuration
142 is not updated.
143 -b When using the onboot command, backup an existing initramfs
146 image by adding a .bak extension rather than overwriting it.
147 Without this option, the initramfs is overwritten.
148
151 These parameters affect the general behaviour of the SystemTap
152 initscript service. They can be specified in the configuration file.
153 SCRIPT_PATH
156 Specify the absolute path of the script directory. These are the
157 scripts on which the initscript can operate. Scripts must have
158 the .stp extension. The default path is /etc/system‐
159 tap/script.d.
160 CONFIG_PATH
163 Specify the absolute path of the script configuration directory.
164 These configuration files contain options for specific scripts.
165 They must have the .conf extension. The default path is
166 /etc/systemtap/conf.d.
167 CACHE_PATH
170 Specify the absolute path of the cache directory. The default
171 path is /var/cache/systemtap.
172 TEMP_PATH
175 Specify the absolute path of the temporary directory in which
176 SystemTap makes temporary directories to compile scripts. The
177 default path is /tmp.
178 STAT_PATH
181 Specify the absolute path of the directory containing PID files
182 used to track the status of SystemTap scripts. The default path
183 is /var/run/systemtap.
184 LOG_FILE
187 Specify the absolute path of the log file. All messages are sent
188 to this file, including compilation and runtime errors. The
189 default path is /var/log/systemtap.log.
190 PASSALL
193 If this is set yes, initscript commands that operate on multiple
194 scripts will report as failed when the action could not be per‐
195 formed on at least one script. If set to no, only a warning is
196 emitted. The default is yes.
197 RECURSIVE
200 If this is set yes, the initscript will always follow script
201 dependencies recursively. This means that there is no need to
202 specify the -R option. This flag is effective only if you spec‐
203 ify script(s) from the command-line. The default is no.
204 AUTOCOMPILE
207 If this is set yes, the initscript automatically tries to com‐
208 pile specified scripts when needed if there is no valid cache.
209 Otherwise, the related command simply fails. The default is yes.
210 DEFAULT_START
213 Specify scripts which will be started by default. If omitted (or
214 empty), all scripts in the script directory will be started. The
215 default is "".
216 ALLOW_CACHEONLY
219 If this is set yes, the initscript will also allow operating on
220 scripts that are located in the cache directory, but not in the
221 script directory. The default is no.
222 WARNING: the initscript may load unexpected obsolete caches with
224 this option. The cache directory should be checked before
225 enabling this option.
226 LOG_BOOT_ERR
229 Because boot-time scripts are run before the root filesystem is
230 mounted, staprun's stderr cannot be logged to the LOG_FILE as
231 usual. However, the log can instead be output to /var/run/sys‐
232 temtap/$script.log by setting LOG_BOOT_ERR to yes. If STAT_PATH
233 is different from the default, the log files will be moved there
234 upon executing any of the initscript commands. The default is
235 no.
236 Here is a global configuration file example:
239 SCRIPT_PATH=/var/systemtap/script.d/
241 PASSALL=yes
242 RECURSIVE=no
243
247 These parameters affect the compilation or runtime behaviour of specif‐
248 ic SystemTap scripts. They must be placed in config files located in
249 the CONFIG_PATH directory.
250 <SCRIPT>_OPT
253 Specify options passed to the stap(1) command for the SCRIPT.
254 Here, SCRIPT is the name of the script file without the .stp ex‐
255 tension. Note that the -F option is always added.
256 The following options are ignored when compiling scripts: -p,
258 -m, -r, -c, -x, -e, -s, -o, -h, -V, -k.
259 The following options are ignored when running starting scripts:
261 -h, -V, -v, -t, -p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u,
262 -q, -w, -l, -d, -L, -F, and all long options.
263 <SCRIPT>_REQ
266 Specify script dependencies (i.e. which script this script re‐
267 quires). For example, if foo.stp requires (or needs to run af‐
268 ter) bar.stp, set
269 foo_REQ="bar"
271 Specify multiple scripts by separating their names by spaces.
273 Here is a script configuration file example:
276 script1_OPT="-o /var/log/script1.out -DRELAY_HOST=group1"
278 script2_OPT="-DRELAY_GUEST=group1"
279 script2_REQ="script1"
280
284 INSTALLING SCRIPTS
285 We first copy a SystemTap script (e.g. "script1.stp") into the
286 script directory:
287 # cp script1.stp /etc/systemtap/script.d/
289 We can then set any script options, for example:
291 # vi /etc/systemtap/conf.d/group1
293 script1_OPT="-o /var/log/group1.out -DRELAY_HOST=group1"
294 If we then install a script (e.g. "script2.stp") which shares a
296 buffer with script1, there is a dependency. In this case, we can
297 do the following:
298 # cp script2.stp /etc/systemtap/script.d/
300 # vi /etc/systemtap/conf.d/group1
301 script2_OPT="-DRELAY_GUEST=group1"
302 script2_REQ="script1"
303 This way, if stap(1) fails to run script1, the initscript will
305 not even try to run script2.
306 TESTING
309 After installing scripts, we can test that they work by simply
310 doing:
311 # service systemtap start
313 # service systemtap stop
314 We could be more specific as well, for example:
316 # service systemtap start script1
318 # service systemtap stop script1
319 If there were no errors, we are ready to use it.
321 ENABLING SERVICE
324 After we're satisfied with the scripts and their tests, we can
325 enable the SystemTap initscript service:
326 # chkconfig systemtap on
328 DELETING SCRIPTS
332 Scripts are deleted by simply removing them from the script di‐
333 rectory and removing any configuration lines specific to them:
334 # rm /etc/systemtap/script.d/script2.stp
336 # vi /etc/systemtap/conf.d/group1
337 If the script is still running, we also need to stop it:
339 # service systemtap stop script2
341 We can then also remove the cache associated with the script:
343 # service systemtap cleanup script2
345 PREPARING FOR KERNEL UPDATES
349 Usually, there is nothing to do when booting into a new kernel.
350 The initscript will see that the kernel version is different and
351 will compile the scripts. The compilation can be done beforehand
352 as well to avoid having to compile during boot by using the -r
353 option:
354 # service systemtap compile myscript -r <NEW_KERNEL_VERSION>
356 IMPORTING COMPILED SCRIPTS
360 For environments which lack compilation infrastructure (e.g. no
361 compilers or debuginfo), such as a production system, the
362 scripts can be compiled on another (development) machine and
363 then transferred over to the production system:
364 # service systemtap compile myscript -r \
366 > <KERNEL_VERSION_OF_TARGET_MACHINE>
367 # tar czf stap-scripts-<kernel-version>.tar.gz \
368 > /var/cache/systemtap/<kernel-version> \
369 > /etc/systemtap/conf.d/<configfile>
370 And then copy this package to the target machine and extract it.
372 STARTING SCRIPTS DURING EARLY-BOOT
375 The initscript also allows us to start scripts earlier during
376 the boot process by creating an initramfs containing the
377 script's module. The system must be dracut-based for this to
378 work. Starting a script at this stage gives access to informa‐
379 tion otherwise very hard to obtain.
380 We first install the script by copying it into the script direc‐
382 tory as usual and setting whatever options we'd like:
383 # cp myscript.stp /etc/systemtap/script.d
385 # vi /etc/systemtap/conf.d/myscript.conf
386 To add the script to the initramfs, we use the onboot command:
388 # service systemtap onboot myscript
390 If the script is not already compiled and cached, it will be
392 done at this point. A new initramfs will then be created at the
393 default location. We can use the -b option to ensure that the
394 existing initramfs is backed up. We can then restart the system.
395 USING A DIFFERENT INITRAMFS
398 If we would prefer to only start the script for one boot and not
399 others, it might be easier to instead use the -o option to spec‐
400 ify a different initramfs output file:
401 # service systemtap onboot myscript \
403 > -o /boot/special_initramfs.img
404 Once the initramfs is created, it's simply a matter of changing
406 the command-line options at boot-time so that the new image is
407 used rather than the usual one.
408 CREATING AN INITRAMFS FOR A DIFFERENT KERNEL
411 Just like the compile command, we can use the -r option to spec‐
412 ify the kernel for which we want to create the initramfs. This
413 is useful when we are about to upgrade and would like to prepare
414 in advance. For example:
415 # service systemtap onboot myscript \
417 > -r 3.12.6-200.fc19.x86_64
418 REMOVING SCRIPTS FROM THE INITRAMFS
422 Finally, to remove all script from the initramfs, we simple run
423 the onboot command without specifying any scripts:
424 # service systemtap onboot
426 This will simply create a standard initramfs without any System‐
428 Tap modules inserted.
429 TROUBLESHOOTING EARLY-BOOT ISSUES
432 There can be many reasons for which the module didn't insert or
433 did not work as expected. It may be useful to turn on dracut de‐
434 bugging by adding 'rdinitdebug' to the kernel command-line and
435 checking dmesg/journalctl -ae. Also, the stderr output of
436 staprun can be captured by setting the LOG_BOOT_ERR option to
437 yes.
438
441 stap(1) dracut(8) new-kernel-pkg(8)
442
445 Use the Bugzilla link of the project web page or our mailing list.
446 http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
447 SYSTEMTAP(8)