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 development tools (needed to compile the script) and then
20 transfer the resulting kernel module to a production machine that
21 doesn't have any development tools installed.
22 Please refer to stappaths (7) for the version number, or run rpm -q
24 systemtap (fedora/red hat) apt-get -v systemtap (ubuntu)
25
28 The staprun program supports the following options. Any other option
29 prints a list of supported options.
30 -v Verbose mode. The level of verbosity is also set in the SYSTEM‐
32 TAP_VERBOSE environment variable.
33 -V Print version number and exit.
35 -w Suppress warnings from the script.
37 -u Load the uprobes.ko module.
39 -c CMD Command CMD will be run and the staprun program will exit when
41 CMD does. The '_stp_target' variable will contain the pid for
42 CMD.
43 -x PID The '_stp_target' variable will be set to PID.
45 -N PID Sets the '_stp_namespaces_pid' variable to PID.
47 -o FILE
49 Send output to FILE. If the module uses bulk mode, the output
50 will be in percpu files FILE_x(FILE_cpux in background and bulk
51 mode) where 'x' is the cpu number. This supports strftime(3)
52 formats for FILE.
53 -b BUFFER_SIZE
55 The systemtap module will specify a buffer size. Setting one
56 here will override that value. The value should be an integer
57 between 1 and 4095 which be assumed to be the buffer size in MB.
58 That value will be per-cpu if bulk mode is used.
59 -L Load module and start probes, then detach from the module leav‐
61 ing the probes running. The module can be attached to later by
62 using the -A option.
63 -A Attach to loaded systemtap module.
65 -C WHEN
67 Control coloring of error messages. WHEN must be either "never",
68 "always", or "auto" (i.e. enable only if at a terminal). If the
69 option is missing, then "auto" is assumed. Colors can be modi‐
70 fied using the SYSTEMTAP_COLORS environment variable. See the
71 stap(1) manual page for more information on syntax and behav‐
72 iour.
73 -M INTERVAL
75 Enable monitor mode with INTERVAL seconds between updates.
76 -d Delete a module. Only detached or unused modules the user has
78 permission to access will be deleted. Use "*" (quoted) to delete
79 all unused modules.
80 -D Run staprun in background as a daemon and show it's pid.
82 -R Rename the module to a unique name before inserting it.
84 -r N:URI
86 Pass the given number and URI data to the tapset functions re‐
87 mote_id() and remote_uri().
88 -S size[,N]
90 Sets the maximum size of output file and the maximum number of
91 output files. If the size of output file will exceed size ,
92 systemtap switches output file to the next file. And if the num‐
93 ber of output files exceed N , systemtap removes the oldest out‐
94 put file. You can omit the second argument.
95 -T timeout
97 Sets maximum time reader thread will wait before dumping trace
98 buffer. Value is in ms, default is 200ms. Setting this to a high
99 value decreases number of stapio wake-ups, allowing deeper sleep
100 for embedded platforms. But it impacts interactivity on terminal
101 as traces are dumped less often in case of low throughput.
102 There is no interactivity or performance impact for high
103 throughput as trace is dumped when buffer is full, before this
104 timeout expires.
105 var1=val
107 Sets the value of global variable var1 to val. Global variables
108 contained within a module are treated as module options and can
109 be set from the staprun command line.
110
113 MODULE is either a module path or a module name. If it is a module
114 name, the module will be looked for in the following directory (where
115 'VERSION' is the output of "uname -r"):
116 /lib/modules/VERSION/systemtap
118 Any additional arguments on the command line are passed to the module.
120 One use of these additional module arguments is to set the value of
121 global variables declared within the module.
122 $ stap -p4 -m mod1 -e 'global var1="foo"; probe begin{printf("%s\n",
124 var1); exit()}'
125 Running this with an additional module argument:
127 $ staprun mod1.ko var1="HelloWorld"
129 HelloWorld
130 Spaces and exclamation marks currently cannot be passed into global
132 variables this way.
133
136 See the stapex(3stap) manual page for a collection of sample scripts.
137 Here is a very basic example of how to use staprun. First, use stap to
139 compile a script. The stap program will report the pathname to the re‐
140 sulting module.
141 $ stap -p4 -e 'probe begin { printf("Hello World!\n"); exit() }'
143 /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
144 Run staprun with the pathname to the module as an argument.
146 $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
148 Hello World!
149
151 After the staprun program installs a Systemtap kernel module, users can
152 detach from the kernel module and reattach to it later. The -L option
153 loads the module and automatically detaches. Users can also detach
154 from the kernel module interactively by sending the SIGQUIT signal from
155 the keyboard (typically by typing Ctrl-\).
156 To reattach to a kernel module, the staprun -A option would be used.
158
161 After staprun launched the stapio program, users can command it to
162 switch output file to next file when it outputs to file(s) (running
163 staprun with -o option) by sending a SIGUSR2 signal to the stapio
164 process. When it receives SIGUSR2, it will switch output file to new
165 file with suffix .N where N is the sequential number. For example,
166 $ staprun -o foo ...
168 outputs trace logs to foo and if it receives SIGUSR2 signal, it switch‐
170 es output to foo.1 file. And receiving SIGUSR2 again, it switches to
171 foo.2 file.
172
175 Systemtap, in the default kernel-module runtime mode, is an administra‐
176 tive tool. It exposes kernel internal data structures and potentially
177 private user information. See the stap(1) manual page for additional
178 information on safety and security.
179 To increase system security, users of systemtap must be root, or in the
181 stapusr group in order to execute this setuid staprun program. A user
182 may select a particular privilege level with the stap --privilege= op‐
183 tion, which staprun will later enforce.
184 stapdev
186 Members of the stapdev group can write and load script modules
187 with root-equivalent privileges, without particular security
188 constraints. (Many safety constraints remain.)
189 stapsys
191 Members of the stapsys group have almost all the privileges of
192 stapdev, except for guru mode constructs.
193 stapusr
195 Members only of the stapusr group may any-privileged modules
196 placed into the /lib/modules/VERSION/systemtap by the system ad‐
197 ministrator.
198 stapusr
200 Members only of the stapusr group may also write and load low-
201 privilege script modules, which are normally limited to manipu‐
202 lating their own processes (and not the kernel nor other users'
203 processes).
204 Part of the privilege enforcement mechanism may require using a stap-
206 server and administrative trust in its cryptographic signer; see the
207 stap-server(8) manual page for a for more information.
208 On a kernel with FIPS mode enabled, staprun normally refuses to attempt
211 to load systemtap-generated kernel modules. This is because on some
212 kernels, this results in a panic. If your kernel includes corrections
213 such as linux commit #002c77a48b47, then you can force staprun to at‐
214 tempt module loads anyway, by setting the STAP_FIPS_OVERRIDE environ‐
215 ment variable to any value.
216
219 /lib/modules/VERSION/systemtap
220 If MODULE is a module name, the module will be looked for in
221 this directory. Users who are only in the 'stapusr' group can
222 install modules located in this directory. This directory must
223 be owned by the root user and not be world writable.
224
227 stap(1), stapprobes(3stap), stap-server(8), stapdyn(8), stapex(3stap)
228
231 Use the Bugzilla link of the project web page or our mailing list.
232 http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
233 STAPRUN(8)