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