1SYSTEMTAP(8)                System Manager's Manual               SYSTEMTAP(8)
2
3
4

NAME

6       systemtap-service - SystemTap initscript and systemd service
7
8
9

SYNOPSIS

11       systemtap-service COMMAND [OPTIONS] [SCRIPT...]
12
13       service systemtap COMMAND [OPTIONS] [SCRIPT...]
14
15

DESCRIPTION

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
23       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
27       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
31       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
35       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
42

COMMANDS

44       One of the commands below must be specified:
45
46
47       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
54              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
58              - The compiled cache file does not exist.
59
60              - The  mtime (modified timestamp) of the original script file is
61                newer than the time of the compiled script cache.
62
63              - The specified stap options used to compile the script has been
64                changed (see also the SCRIPT PARAMETERS section).
65
66              - The result of `uname -a` has been changed.
67
68
69       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
74
75       restart
76              Stop and start SCRIPTs.
77
78
79       status Show the state of SCRIPTs and their dependencies.
80
81
82       compile
83              Compile SCRIPTs but do not start them. If the scripts  have  al‐
84              ready  been compiled, prompt for confirmation before overwriting
85              cache. Compile for the current kernel,  or  the  kernel  release
86              specified by the -r option.
87
88
89       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
94              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
102              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
107              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
111
112       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
118

OPTIONS

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
124
125       -c CONFIG_FILE
126              Specify a different configuration file in place of  the  default
127              one.
128
129
130       -R     When  using  the  start  and  stop  commands,  also  include the
131              scripts' dependencies (recursively).
132
133
134       -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
139
140       -y     Answer yes for all prompts.
141
142
143       -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
148
149       -b     When using the onboot command, backup an existing initramfs  im‐
150              age by adding a .bak extension rather than overwriting it. With‐
151              out this option, the initramfs is overwritten.
152
153

GLOBAL PARAMETERS

155       These  parameters  affect  the  general  behaviour  of  the   SystemTap
156       initscript service. They can be specified in the configuration file.
157
158
159       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
165
166       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
172
173       CACHE_PATH
174              Specify  the  absolute  path of the cache directory. The default
175              path is /var/cache/systemtap.
176
177
178       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
183
184       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
189
190       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 de‐
193              fault path is /var/log/systemtap.log.
194
195
196       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
202
203       RECURSIVE
204              If this is set yes, the initscript will always follow script de‐
205              pendencies 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
209
210       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
215
216       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
221
222       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
227              WARNING: the initscript may load unexpected obsolete caches with
228              this  option.   The cache directory should be checked before en‐
229              abling this option.
230
231
232       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  /run/system‐
236              tap/$script.log  by setting LOG_BOOT_ERR to yes. If STAT_PATH is
237              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
241
242       Here is a global configuration file example:
243
244              SCRIPT_PATH=/var/systemtap/script.d/
245              PASSALL=yes
246              RECURSIVE=no
247
248
249

SCRIPT PARAMETERS

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
255
256       <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
261              The following options are ignored when  compiling  scripts:  -p,
262              -m, -r, -c, -x, -e, -s, -o, -h, -V, -k.
263
264              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
268
269       <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
274              foo_REQ="bar"
275
276              Specify multiple scripts by separating their names by spaces.
277
278
279       Here is a script configuration file example:
280
281              script1_OPT="-o /var/log/script1.out"
282              script2_OPT="-o /var/log/script2.out"
283              script2_REQ="script1"
284
285
286

EXAMPLES

288       INSTALLING SCRIPTS
289              We  first  copy a SystemTap script (e.g. "script1.stp") into the
290              script directory:
291
292              # cp script1.stp /etc/systemtap/script.d/
293
294              We can then set any script options, for example:
295
296              # vi /etc/systemtap/conf.d/group1.conf
297              script1_OPT="-o /var/log/group1.out"
298
299              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
302              # 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
307              This  way,  if stap(1) fails to run script1, the initscript will
308              not even try to run script2.
309
310
311       TESTING
312              After installing scripts, we can test that they work  by  simply
313              doing:
314
315              # systemtap-service start
316              # systemtap-service stop
317
318              We could be more specific as well, for example:
319
320              # systemtap-service start script1
321              # systemtap-service stop script1
322
323              If there were no errors, we are ready to use it.
324
325
326       ENABLING SERVICE
327              After  we're  satisfied with the scripts and their tests, we can
328              enable the SystemTap initscript service:
329
330              # chkconfig systemtap on
331
332
333
334       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
338              # rm /etc/systemtap/script.d/script2.stp
339              # vi /etc/systemtap/conf.d/group1.conf
340
341              If the script is still running, we also need to stop it:
342
343              # systemtap-service stop script2
344
345              We can then also remove the cache associated with the script:
346
347              # systemtap-service cleanup script2
348
349
350
351       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
358              # systemtap-service compile myscript -r <NEW_KERNEL_VERSION>
359
360
361
362       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
368              # 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
374              And then copy this package to the target machine and extract it.
375
376
377       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
384              We first install the script by copying it into the script direc‐
385              tory as usual and setting whatever options we'd like:
386
387              # cp myscript.stp /etc/systemtap/script.d
388              # vi /etc/systemtap/conf.d/myscript.conf
389
390              To add the script to the initramfs, we use the onboot command:
391
392              # systemtap-service onboot myscript
393
394              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
399
400       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
405              # systemtap-service onboot myscript \
406              >   -o /boot/special_initramfs.img
407
408              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
412
413       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
419              # systemtap-service onboot myscript \
420              >   -r 3.12.6-200.fc19.x86_64
421
422
423
424       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
428              # systemtap-service onboot
429
430              This will simply create a standard initramfs without any System‐
431              Tap modules inserted.
432
433
434       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
442

SEE ALSO

444       stap(1) dracut(8) new-kernel-pkg(8)
445
446

BUGS

448       Use the Bugzilla link of the project web  page  or  our  mailing  list.
449       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
450
451
452
453
454                                                                  SYSTEMTAP(8)
Impressum