| 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 |
|