1STAPRUN(8) System Manager's Manual STAPRUN(8)
2
6 staprun - systemtap runtime
7
10 staprun [ OPTIONS ] MODULE [ MODULE-OPTIONS ]
11
14 The staprun program is the back-end of the Systemtap tool. It expects
15 a kernel module produced by the front-end stap tool.
16 Splitting the systemtap tool into a front-end and a back-end allows a
18 user to compile a systemtap script on a development machine that has
19 the kernel debugging information (need to compile the script) and then
20 transfer the resulting kernel module to a production machine that
21 doesn't have any development tools or kernel debugging information
22 installed.
23 This manual corresponds to version 0.6.2.
25
28 The staprun program supports the following options. Any other option
29 prints a list of supported options.
30 -v Verbose mode.
32 -c CMD Command CMD will be run and the staprun program will exit when
34 CMD does. The '_stp_target' variable will contain the pid for
35 CMD.
36 -x PID The '_stp_target' variable will be set to PID.
38 -o FILE
40 Send output to FILE. If the module uses bulk mode, the output
41 will be in percpu files FILE_x where 'x' is the cpu number.
42 -b BUFFER_SIZE
44 The systemtap module will specify a buffer size. Setting one
45 here will override that value. The value should be an integer
46 between 1 and 64 which be assumed to be the buffer size in MB.
47 That value will be per-cpu if bulk mode is used.
48 -L Load module and start probes, then detach from the module leav‐
50 ing the probes running. The module can be attached to later by
51 using the -A option.
52 -A Attach to loaded systemtap module.
54
57 MODULE is either a module path or a module name. If it is a module
58 name, the module will be looked for in the following directory (where
59 'VERSION' is the output of "uname -r"):
60 /lib/modules/VERSION/systemtap
62 Any additional arguments on the command line are passed to the module.
64
67 See the stapex(5) manual page for a collection of sample scripts.
68 Here is a very basic example of how to use staprun. First, use stap to
70 compile a script. The stap program will report the pathname to the
71 resulting module.
72 $ stap -p4 -e 'probe begin { printf("Hello World!\n"); exit() }'
74 /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
75 Run staprun with the pathname to the module as an argument.
77 $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
79 Hello World!
80
82 After the staprun program installs a Systemtap kernel module, users can
83 detach from the kernel module and reattach to it later. The -L option
84 loads the module and automatically detaches. Users can also detach
85 from the kernel module interactively by sending the SIGQUIT signal from
86 the keyboard (typically by typing Ctrl-\).
87 To reattach to a kernel module, the staprun -A option would be used.
89
91 Systemtap is an administrative tool. It exposes kernel internal data
92 structures and potentially private user information. See the stap(1)
93 manual page for additional information on safety and security.
94 To increase system security, only the root user and members of the
96 stapdev group can use staprun to insert systemtap modules (or attach to
97 existing ones). Members of the stapusr group can use staprun to insert
98 systemtap modules (or attach to existing systemtap modules) that are
99 located in the /lib/modules/VERSION/systemtap directory.
100
102 /lib/modules/VERSION/systemtap
103 If MODULE is a module name, the module will be looked for in
104 this directory. Users who are only in the 'stapusr' group can
105 only install modules located in this directory. This directory
106 should be owned by the root user and not be world writable.
107
109 stap(1), stapprobes(5), stapfuncs(5), stapex(5),
110
113 Use the Bugzilla link off of the project web page or our mailing list.
114 http://sources.redhat.com/systemtap/,<systemtap@sources.redhat.com>.
115Red Hat 2008-03-27 STAPRUN(8)