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.
24 The configuration file of the initscript is located at /etc/system‐
26 tap/config. Acceptable parameters are detailed in the GLOBAL PARAMETERS
27 section.
28 Scripts must be placed in the /etc/systemtap/script.d directory and
30 must have a .stp extension. When referring to them on the command-line
31 however, there in no need to include the .stp extension. Script names
32 can only contain alphanumeric characters (and '_') and must not start
33 with a number. The scripts directory may be changed by setting the
34 SCRIPT_PATH parameter in the configuration file.
35
38 One of the commands below must be specified:
39 start Start SCRIPTs. If no scripts are specified, start the scripts
42 specified by the DEFAULT_START configuration. If DEFAULT_START
43 is not set, start all scripts in the script directory. For
44 scripts already started, the command is ignored. The command
45 will fail if the scripts fail to start (see also the PASSALL
46 configuration).
47 If the AUTOCOMPILE configuration is on, the command will try to
49 compile or update the specified scripts when one of the below
50 conditions is true:
51 - The compiled cache file does not exist.
53 - The mtime (modified timestamp) of the original script file is
55 newer than the time of the compiled script cache.
56 - The specified stap options used to compile the script has been
58 changed (see also the SCRIPT PARAMETERS section).
59 - The result of `uname -a` has been changed.
61 stop Stop SCRIPTs. If no scripts are specified, stop all running
64 scripts. For scripts already stopped, the command is ignored.
65 The command will fail if the scripts fail to stop (see also the
66 PASSALL configuration).
67 restart
70 Stop and start SCRIPTs.
71 status Show the state of SCRIPTs and their dependencies.
74 compile
77 Compile SCRIPTs but do not start them. If the scripts have
78 already been compiled, prompt for confirmation before overwrit‐
79 ing cache. Compile for the current kernel, or the kernel release
80 specified by the -r option.
81 onboot Make SCRIPTs part of the initramfs so that they are started ear‐
84 lier during the boot process. This command is only available on
85 dracut-based systems. If no scripts are specified, create a nor‐
86 mal initramfs devoid of any SystemTap files.
87 The initramfs is created for the current kernel, or the kernel
89 release specified by the -r option. The path of the created
90 initramfs defaults to /boot/initramfs-KVER.img, where KVER is
91 the output of `uname -r`. The bootloader is also updated (using
92 new-kernel-pkg(8)) to make the kernel entry use the new
93 initramfs file. Use the -o option to specify a different path
94 (the bootloader will not be updated).
95 If the output file already exists, it is overwritten, unless the
97 -b switch is given, in which case the file is appended .bak
98 rather than overwritten. However, if there is already a .bak
99 version of the file, the backup will not be overwritten.
100 WARNING: do not use the -o option of stap(1) with onboot scripts
102 because the script is started before the root filesystem is even
103 mounted. Increase the buffer size if more space is needed.
104 cleanup
107 Delete the compiled SCRIPTs from cache. If no scripts are speci‐
108 fied, then all compiled scripts are deleted. Only the cache for
109 the current kernel is deleted, or the kernel release specified
110 by the -r option. Prompt for confirmation before deleting.
111
114 Many of the commands can also take options. However, since users can't
115 pass these options on boot, they are only meant for managing scripts
116 after boot and for testing. Available options are:
117 -c CONFIG_FILE
120 Specify a different configuration file in place of the default
121 one.
122 -R When using the start and stop commands, also include the
125 scripts' dependencies (recursively).
126 -r KERNEL_RELEASE
129 When using the compile, onboot, and cleanup commands, specify
130 the target kernel version rather than using the current one.
131 Must be in the same format as `uname -r`.
132 -y Answer yes for all prompts.
135 -o PATH.IMG
138 When using the onboot command, specify the output path of the
139 created initramfs. When specified, the bootloader configuration
140 is not updated.
141 -b When using the onboot command, backup an existing initramfs
144 image by adding a .bak extension rather than overwriting it.
145 Without this option, the initramfs is overwritten.
146
149 These parameters affect the general behaviour of the SystemTap
150 initscript service. They can be specified in the configuration file.
151 SCRIPT_PATH
154 Specify the absolute path of the script directory. These are the
155 scripts on which the initscript can operate. Scripts must have
156 the .stp extension. The default path is /etc/system‐
157 tap/script.d.
158 CONFIG_PATH
161 Specify the absolute path of the script configuration directory.
162 These configuration files contain options for specific scripts.
163 They must have the .conf extension. The default path is
164 /etc/systemtap/conf.d.
165 CACHE_PATH
168 Specify the absolute path of the cache directory. The default
169 path is /var/cache/systemtap.
170 TEMP_PATH
173 Specify the absolute path of the temporary directory in which
174 SystemTap makes temporary directories to compile scripts. The
175 default path is /tmp.
176 STAT_PATH
179 Specify the absolute path of the directory containing PID files
180 used to track the status of SystemTap scripts. The default path
181 is /var/run/systemtap.
182 LOG_FILE
185 Specify the absolute path of the log file. All messages are sent
186 to this file, including compilation and runtime errors. The
187 default path is /var/log/systemtap.log.
188 PASSALL
191 If this is set yes, initscript commands that operate on multiple
192 scripts will report as failed when the action could not be per‐
193 formed on at least one script. If set to no, only a warning is
194 emitted. The default is yes.
195 RECURSIVE
198 If this is set yes, the initscript will always follow script
199 dependencies recursively. This means that there is no need to
200 specify the -R option. This flag is effective only if you spec‐
201 ify script(s) from the command-line. The default is no.
202 AUTOCOMPILE
205 If this is set yes, the initscript automatically tries to com‐
206 pile specified scripts when needed if there is no valid cache.
207 Otherwise, the related command simply fails. The default is yes.
208 DEFAULT_START
211 Specify scripts which will be started by default. If omitted (or
212 empty), all scripts in the script directory will be started. The
213 default is "".
214 ALLOW_CACHEONLY
217 If this is set yes, the initscript will also allow operating on
218 scripts that are located in the cache directory, but not in the
219 script directory. The default is no.
220 WARNING: the initscript may load unexpected obsolete caches with
222 this option. The cache directory should be checked before
223 enabling this option.
224 LOG_BOOT_ERR
227 Because boot-time scripts are run before the root filesystem is
228 mounted, staprun's stderr cannot be logged to the LOG_FILE as
229 usual. However, the log can instead be output to /var/run/sys‐
230 temtap/$script.log by setting LOG_BOOT_ERR to yes. If STAT_PATH
231 is different from the default, the log files will be moved there
232 upon executing any of the initscript commands. The default is
233 no.
234 Here is a global configuration file example:
237 SCRIPT_PATH=/var/systemtap/script.d/
239 PASSALL=yes
240 RECURSIVE=no
241
245 These parameters affect the compilation or runtime behaviour of specif‐
246 ic SystemTap scripts. They must be placed in config files located in
247 the CONFIG_PATH directory.
248 <SCRIPT>_OPT
251 Specify options passed to the stap(1) command for the SCRIPT.
252 Here, SCRIPT is the name of the script file without the .stp ex‐
253 tension. Note that the -F option is always added.
254 The following options are ignored when compiling scripts: -p,
256 -m, -r, -c, -x, -e, -s, -o, -h, -V, -k.
257 The following options are ignored when running starting scripts:
259 -h, -V, -v, -t, -p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u,
260 -q, -w, -l, -d, -L, -F, and all long options.
261 <SCRIPT>_REQ
264 Specify script dependencies (i.e. which script this script re‐
265 quires). For example, if foo.stp requires (or needs to run af‐
266 ter) bar.stp, set
267 foo_REQ="bar"
269 Specify multiple scripts by separating their names by spaces.
271 Here is a script configuration file example:
274 script1_OPT="-o /var/log/script1.out"
276 script2_OPT="-o /var/log/script2.out"
277 script2_REQ="script1"
278
282 INSTALLING SCRIPTS
283 We first copy a SystemTap script (e.g. "script1.stp") into the
284 script directory:
285 # cp script1.stp /etc/systemtap/script.d/
287 We can then set any script options, for example:
289 # vi /etc/systemtap/conf.d/group1
291 script1_OPT="-o /var/log/group1.out"
292 We then install a script (e.g. "script2.stp") which needs to run
294 after script1. In this case, we can do the following:
295 # cp script2.stp /etc/systemtap/script.d/
297 # vi /etc/systemtap/conf.d/group1
298 script2_OPT="-o /var/log/group2.out"
299 script2_REQ="script1"
300 This way, if stap(1) fails to run script1, the initscript will
302 not even try to run script2.
303 TESTING
306 After installing scripts, we can test that they work by simply
307 doing:
308 # service systemtap start
310 # service systemtap stop
311 We could be more specific as well, for example:
313 # service systemtap start script1
315 # service systemtap stop script1
316 If there were no errors, we are ready to use it.
318 ENABLING SERVICE
321 After we're satisfied with the scripts and their tests, we can
322 enable the SystemTap initscript service:
323 # chkconfig systemtap on
325 DELETING SCRIPTS
329 Scripts are deleted by simply removing them from the script di‐
330 rectory and removing any configuration lines specific to them:
331 # rm /etc/systemtap/script.d/script2.stp
333 # vi /etc/systemtap/conf.d/group1
334 If the script is still running, we also need to stop it:
336 # service systemtap stop script2
338 We can then also remove the cache associated with the script:
340 # service systemtap cleanup script2
342 PREPARING FOR KERNEL UPDATES
346 Usually, there is nothing to do when booting into a new kernel.
347 The initscript will see that the kernel version is different and
348 will compile the scripts. The compilation can be done beforehand
349 as well to avoid having to compile during boot by using the -r
350 option:
351 # service systemtap compile myscript -r <NEW_KERNEL_VERSION>
353 IMPORTING COMPILED SCRIPTS
357 For environments which lack compilation infrastructure (e.g. no
358 compilers or debuginfo), such as a production system, the
359 scripts can be compiled on another (development) machine and
360 then transferred over to the production system:
361 # service systemtap compile myscript -r \
363 > <KERNEL_VERSION_OF_TARGET_MACHINE>
364 # tar czf stap-scripts-<kernel-version>.tar.gz \
365 > /var/cache/systemtap/<kernel-version> \
366 > /etc/systemtap/conf.d/<configfile>
367 And then copy this package to the target machine and extract it.
369 STARTING SCRIPTS DURING EARLY-BOOT
372 The initscript also allows us to start scripts earlier during
373 the boot process by creating an initramfs containing the
374 script's module. The system must be dracut-based for this to
375 work. Starting a script at this stage gives access to informa‐
376 tion otherwise very hard to obtain.
377 We first install the script by copying it into the script direc‐
379 tory as usual and setting whatever options we'd like:
380 # cp myscript.stp /etc/systemtap/script.d
382 # vi /etc/systemtap/conf.d/myscript.conf
383 To add the script to the initramfs, we use the onboot command:
385 # service systemtap onboot myscript
387 If the script is not already compiled and cached, it will be
389 done at this point. A new initramfs will then be created at the
390 default location. We can use the -b option to ensure that the
391 existing initramfs is backed up. We can then restart the system.
392 USING A DIFFERENT INITRAMFS
395 If we would prefer to only start the script for one boot and not
396 others, it might be easier to instead use the -o option to spec‐
397 ify a different initramfs output file:
398 # service systemtap onboot myscript \
400 > -o /boot/special_initramfs.img
401 Once the initramfs is created, it's simply a matter of changing
403 the command-line options at boot-time so that the new image is
404 used rather than the usual one.
405 CREATING AN INITRAMFS FOR A DIFFERENT KERNEL
408 Just like the compile command, we can use the -r option to spec‐
409 ify the kernel for which we want to create the initramfs. This
410 is useful when we are about to upgrade and would like to prepare
411 in advance. For example:
412 # service systemtap onboot myscript \
414 > -r 3.12.6-200.fc19.x86_64
415 REMOVING SCRIPTS FROM THE INITRAMFS
419 Finally, to remove all script from the initramfs, we simple run
420 the onboot command without specifying any scripts:
421 # service systemtap onboot
423 This will simply create a standard initramfs without any System‐
425 Tap modules inserted.
426 TROUBLESHOOTING EARLY-BOOT ISSUES
429 There can be many reasons for which the module didn't insert or
430 did not work as expected. It may be useful to turn on dracut de‐
431 bugging by adding 'rdinitdebug' to the kernel command-line and
432 checking dmesg/journalctl -ae. Also, the stderr output of
433 staprun can be captured by setting the LOG_BOOT_ERR option to
434 yes.
435
438 stap(1) dracut(8) new-kernel-pkg(8)
439
442 Use the Bugzilla link of the project web page or our mailing list.
443 http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
444 SYSTEMTAP(8)