staprun/staprun.8

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