1STAPRUN(8)                  System Manager's Manual                 STAPRUN(8)
2
3
4

NAME

6       staprun - systemtap runtime
7
8

SYNOPSIS

10       staprun [ OPTIONS ] MODULE [ MODULE-OPTIONS ]
11
12

DESCRIPTION

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
17       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
23       Please refer to stappaths (7) for the version number,  or  run  rpm  -q
24       systemtap (fedora/red hat) apt-get -v systemtap (ubuntu)
25
26

OPTIONS

28       The  staprun  program supports the following options.  Any other option
29       prints a list of supported options.
30
31       -v     Verbose mode. The level of verbosity is also set in the  SYSTEM‐
32              TAP_VERBOSE environment variable.
33
34       -V     Print version number and exit.
35
36       -w     Suppress warnings from the script.
37
38       -u     Load the uprobes.ko module.
39
40       -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
44       -x PID The '_stp_target' variable will be set to PID.
45
46       -N PID Sets the '_stp_namespaces_pid' variable to PID.
47
48       -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
54       -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
60       -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
64       -A     Attach to loaded systemtap module.
65
66       -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
74       -M INTERVAL
75              Enable monitor mode with INTERVAL seconds between updates.
76
77       -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
81       -D     Run staprun in background as a daemon and show it's pid.
82
83       -R     Rename the module to a unique name before inserting it.
84
85       -r N:URI
86              Pass the given number and URI data to the tapset  functions  re‐
87              mote_id() and remote_uri().
88
89       -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              megabytes,  systemtap switches output file to the next file. And
93              if the number of output files exceed N , systemtap  removes  the
94              oldest output file. You can omit the second argument.
95
96       -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
106       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
111

ARGUMENTS

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
117              /lib/modules/VERSION/systemtap
118
119       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
123        $ stap -p4 -m mod1 -e 'global var1="foo";  probe  begin{printf("%s\n",
124       var1); exit()}'
125
126       Running this with an additional module argument:
127
128        $ staprun mod1.ko var1="HelloWorld"
129        HelloWorld
130
131       Spaces  and  exclamation  marks  currently cannot be passed into global
132       variables this way.
133
134

EXAMPLES

136       See the stapex(3stap) manual page for a collection of sample scripts.
137
138       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
142        $ stap -p4 -e 'probe begin { printf("Hello World!\n"); exit() }'
143        /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
144
145       Run staprun with the pathname to the module as an argument.
146
147        $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
148        Hello World!
149

MODULE DETACHING AND ATTACHING

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
157       To reattach to a kernel module, the staprun -A option would be used.
158
159

FILE SWITCHING BY SIGNAL

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
167        $ staprun -o foo ...
168
169       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
173

SAFETY AND SECURITY

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
180       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
185       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
190       stapsys
191              Members of the stapsys group have almost all the  privileges  of
192              stapdev, except for guru mode constructs.
193
194       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
199       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
205       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
209
210       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
217

FILES

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
225

SEE ALSO

227       stap(1), stapprobes(3stap), stap-server(8), stapdyn(8), stapex(3stap)
228
229

BUGS

231       Use the Bugzilla link of the project web  page  or  our  mailing  list.
232       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
233
234
235
236
237                                                                    STAPRUN(8)
Impressum