Debian Codegraph @

staprun/staprun.8

raw
1 .\" -*- nroff -*-
2 .TH STAPRUN 8
3 .SH NAME
4 staprun \- systemtap runtime
5
6 .SH SYNOPSIS
7
8 .br
9 .B staprun
10 [
11 .I OPTIONS
12 ]
13 .I MODULE
14 [
15 .I MODULE-OPTIONS
16 ]
17
18 .SH DESCRIPTION
19
20 The
21 .I staprun
22 program is the back-end of the Systemtap tool. It expects a kernel
23 module produced by the front-end
24 .I stap
25 tool.
26 .PP
27 Splitting the systemtap tool into a front-end and a back-end allows a
28 user to compile a systemtap script on a development machine that has
29 the kernel development tools (needed to compile the script) and then
30 transfer the resulting kernel module to a production machine that
31 doesn't have any development tools installed.
32 .PP
33 Please refer to stappaths (7) for the version number, or run
34 rpm \-q systemtap (fedora/red hat)
35 apt\-get \-v systemtap (ubuntu)
36
37 .SH OPTIONS
38 The
39 .I staprun
40 program supports the following options. Any other option
41 prints a list of supported options.
42 .TP
43 .B \-v
44 Verbose mode. The level of verbosity is also set in the
45 .I SYSTEMTAP_VERBOSE
46 environment variable.
47 .TP
48 .B \-V
49 Print version number and exit.
50 .TP
51 .B \-w
52 Suppress warnings from the script.
53 .TP
54 .B \-u
55 Load the uprobes.ko module.
56 .TP
57 .B \-c CMD
58 Command CMD will be run and the
59 .I staprun
60 program will exit when CMD
61 does. The '_stp_target' variable will contain the pid for CMD.
62 .TP
63 .B \-x PID
64 The '_stp_target' variable will be set to PID.
65 .TP
66 .B \-N PID
67 Sets the '_stp_namespaces_pid' variable to PID.
68 .TP
69 .B \-o FILE
70 Send output to FILE. If the module uses bulk mode, the output will
71 be in percpu files FILE_x(FILE_cpux in background and bulk mode)
72 where 'x' is the cpu number. This supports strftime(3) formats
73 for FILE.
74 .TP
75 .B \-b BUFFER_SIZE
76 The systemtap module will specify a buffer size.
77 Setting one here will override that value. The value should be
78 an integer between 1 and 4095 which be assumed to be the
79 buffer size in MB. That value will be per-cpu if bulk mode is used.
80 .TP
81 .B \-L
82 Load module and start probes, then detach from the module leaving the
83 probes running. The module can be attached to later by using the
84 .B \-A
85 option.
86 .TP
87 .B \-A
88 Attach to loaded systemtap module.
89 .TP
90 .B \-C WHEN
91 Control coloring of error messages. WHEN must be either
92 .nh
93 "never", "always", or "auto"
94 .hy
95 (i.e. enable only if at a terminal). If the option is missing, then "auto"
96 is assumed. Colors can be modified using the SYSTEMTAP_COLORS environment
97 variable. See the
98 .IR stap (1)
99 manual page for more information on syntax and behaviour.
100 .TP
101 .B \-M INTERVAL
102 Enable monitor mode with INTERVAL seconds between updates.
103 .TP
104 .B \-d
105 Delete a module. Only detached or unused modules
106 the user has permission to access will be deleted. Use "*"
107 (quoted) to delete all unused modules.
108 .TP
109 .BI \-D
110 Run staprun in background as a daemon and show it's pid.
111 .TP
112 .B \-R
113 Rename the module to a unique name before inserting it.
114 .TP
115 .B \-r N:URI
116 Pass the given number and URI data to the tapset functions
117 remote_id() and remote_uri().
118 .TP
119 .BI \-S " size[,N]"
120 Sets the maximum size of output file and the maximum number of output files.
121 If the size of output file will exceed
122 .B size
123 megabytes, systemtap switches output file to the next file. And if the number of
124 output files exceed
125 .B N
126 , systemtap removes the oldest output file. You can omit the second argument.
127 .TP
128 .B \-T timeout
129 Sets maximum time reader thread will wait before dumping trace buffer. Value is
130 in ms, default is 200ms. Setting this to a high value decreases number of stapio
131 wake-ups, allowing deeper sleep for embedded platforms. But it impacts interactivity
132 on terminal as traces are dumped less often in case of low throughput.
133 There is no interactivity or performance impact for high throughput as trace is
134 dumped when buffer is full, before this timeout expires.
135 .TP
136 .B var1=val
137 Sets the value of global variable var1 to val. Global variables contained
138 within a module are treated as module options and can be set from the
139 staprun command line.
140
141 .SH ARGUMENTS
142 .B MODULE
143 is either a module path or a module name. If it is a module name,
144 the module will be looked for in the following directory
145 (where 'VERSION' is the output of "uname \-r"):
146 .IP
147 /lib/modules/VERSION/systemtap
148 .PP
149 .\" TODO - we probably need a better description here.
150 Any additional arguments on the command line are passed to the
151 module. One use of these additional module arguments is to set the value
152 of global variables declared within the module.
153 .PP
154
155 \& $ stap \-p4 \-m mod1 \-e\ \[aq]global var1="foo"; probe begin{printf("%s\\n", var1); exit()}\[aq]
156 .br
157 .PP
158 Running this with an additional module argument:
159 .PP
160
161 \& $ staprun mod1.ko var1="HelloWorld"
162 .br
163 \& HelloWorld
164 .PP
165 Spaces and exclamation marks currently cannot be passed into global variables
166 this way.
167
168 .SH EXAMPLES
169 See the
170 .IR stapex (3stap)
171 manual page for a collection of sample scripts.
172 .PP
173 Here is a very basic example of how to use
174 .I staprun.
175 First, use
176 .I stap
177 to compile a script. The
178 .I stap
179 program will report the pathname to the resulting module.
180 .PP
181 \& $ stap \-p4 \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
182 .br
183 \& /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
184 .PP
185 Run
186 .I staprun
187 with the pathname to the module as an argument.
188 .PP
189 \& $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
190 .br
191 \& Hello World!
192 .SH MODULE DETACHING AND ATTACHING
193 After the
194 .I staprun
195 program installs a Systemtap kernel module, users can detach from the
196 kernel module and reattach to it later. The
197 .B \-L
198 option loads the module and automatically detaches. Users can also
199 detach from the kernel module interactively by sending the SIGQUIT
200 signal from the keyboard (typically by typing Ctrl\-\\).
201 .PP
202 To reattach to a kernel module, the
203 .I staprun
204 .B \-A
205 option would be used.
206
207 .SH FILE SWITCHING BY SIGNAL
208 After
209 .I staprun
210 launched the
211 .I stapio
212 program, users can command it to switch output file to next file when it
213 outputs to file(s) (running staprun with
214 .B \-o
215 option) by sending a
216 .B SIGUSR2
217 signal to the
218 .I stapio
219 process. When it receives SIGUSR2, it will switch output file to
220 new file with suffix
221 .I .N
222 where N is the sequential number.
223 For example,
224 .PP
225 \& $ staprun \-o foo ...
226 .PP
227 outputs trace logs to
228 .I foo
229 and if it receives
230 .B SIGUSR2
231 signal, it switches output to
232 .I foo.1
233 file. And receiving
234 .B SIGUSR2
235 again, it switches to
236 .I foo.2
237 file.
238
239 .SH SAFETY AND SECURITY
240 Systemtap, in the default kernel-module runtime mode, is an
241 administrative tool. It exposes kernel internal data structures and
242 potentially private user information. See the
243 .IR stap (1)
244 manual page for additional information on safety and security.
245 .PP
246 To increase system security, users of systemtap must be root, or in the
247 .I stapusr
248 group in order to execute this setuid
249 .I staprun
250 program.
251 A user may select a particular privilege level with the stap
252 .I \-\-privilege=
253 option, which
254 .I staprun
255 will later enforce.
256 .TP
257 stapdev
258 Members of the
259 .I stapdev
260 group can write and load script modules with root-equivalent
261 privileges, without particular security constraints. (Many safety
262 constraints remain.)
263 .TP
264 stapsys
265 Members of the
266 .I stapsys
267 group have almost all the privileges of
268 .IR stapdev ,
269 except for guru mode constructs.
270 .TP
271 stapusr
272 Members only of the
273 .I stapusr
274 group may any-privileged modules placed into the /lib/modules/VERSION/systemtap
275 by the system administrator.
276 .TP
277 stapusr
278 Members only of the
279 .I stapusr
280 group may also write and load low-privilege script modules, which are normally
281 limited to manipulating their own processes (and not the kernel nor other users'
282 processes).
283 .PP
284 Part of the privilege enforcement mechanism may require using a
285 stap-server and administrative trust in its cryptographic signer; see the
286 .IR stap\-server (8)
287 manual page for a for more information.
288
289 .PP
290 On a kernel with FIPS mode enabled, staprun normally refuses to attempt to
291 load systemtap-generated kernel modules. This is because on some kernels,
292 this results in a panic. If your kernel includes corrections such as
293 linux commit #002c77a48b47, then you can force staprun to attempt module
294 loads anyway, by setting the
295 .BR STAP\_FIPS\_OVERRIDE
296 environment variable to any value.
297
298 .SH FILES
299 .TP
300 /lib/modules/VERSION/systemtap
301 If MODULE is a module name, the module will be looked for in this directory.
302 Users who are only in the
303 .I 'stapusr'
304 group can install modules
305 located in this directory. This directory must be owned by the root
306 user and not be world writable.
307
308 .SH SEE ALSO
309 .IR stap (1),
310 .IR stapprobes (3stap),
311 .IR stap\-server (8),
312 .IR stapdyn (8),
313 .IR stapex (3stap)
314
315 .SH BUGS
316 Use the Bugzilla link of the project web page or our mailing list.
317 .nh
318 .BR http://sourceware.org/systemtap/ ", " <[email protected]> .
319 .hy
320