staprun(8)

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 debugging information (need to compile the script) and  then
20       transfer  the  resulting  kernel  module  to  a production machine that
21       doesn't have any development  tools  or  kernel  debugging  information
22       installed.
23
24       Please  refer  to  stappaths  (7) for the version number, or run rpm -q
25       systemtap (fedora/red hat) apt-get -v systemtap (ubuntu)
26
27

OPTIONS

29       The staprun program supports the following options.  Any  other  option
30       prints a list of supported options.
31
32       -v     Verbose mode.
33
34       -w     Suppress warnings from the script.
35
36       -u     Load the uprobes.ko module.
37
38       -c CMD Command  CMD  will be run and the staprun program will exit when
39              CMD does.  The '_stp_target' variable will contain the  pid  for
40              CMD.
41
42       -x PID The '_stp_target' variable will be set to PID.
43
44       -o FILE
45              Send  output  to  FILE. If the module uses bulk mode, the output
46              will be in percpu files FILE_x(FILE_cpux in background and  bulk
47              mode)  where  'x'  is  the cpu number. This supports strftime(3)
48              formats for FILE.
49
50       -b BUFFER_SIZE
51              The systemtap module will specify a buffer  size.   Setting  one
52              here  will  override  that value. The value should be an integer
53              between 1 and 4095 which be assumed to be the buffer size in MB.
54              That value will be per-cpu if bulk mode is used.
55
56       -L     Load  module and start probes, then detach from the module leav‐
57              ing the probes running.  The module can be attached to later  by
58              using the -A option.
59
60       -A     Attach to loaded systemtap module.
61
62       -d     Delete  a  module.  Only detached or unused modules the user has
63              permission to access will be deleted. Use "*" (quoted) to delete
64              all unused modules.
65
66       -D     Run staprun in background as a daemon and show it's pid.
67
68       -R     Rename the module to a unique name before inserting it.
69
70       -S size[,N]
71              Sets  the  maximum size of output file and the maximum number of
72              output files.  If the size of output file  will  exceed  size  ,
73              systemtap switches output file to the next file. And if the num‐
74              ber of output files exceed N , systemtap removes the oldest out‐
75              put file. You can omit the second argument.
76
77       var1=val
78              Sets  the value of global variable var1 to val. Global variables
79              contained within a module are treated as module options and  can
80              be set from the staprun command line.
81
82

ARGUMENTS

84       MODULE  is  either  a  module path or a module name.  If it is a module
85       name, the module will be looked for in the following  directory  (where
86       'VERSION' is the output of "uname -r"):
87
88              /lib/modules/VERSION/systemtap
89
90       Any  additional arguments on the command line are passed to the module.
91       One use of these additional module arguments is to  set  the  value  of
92       global variables declared within the module.
93
94         $  stap -p4 -m mod1 -e 'global var1="foo"; probe begin{printf("%s\n",
95       var1); exit()}'
96
97       Running this with an additional module argument:
98
99        $ staprun mod1.ko var1="HelloWorld"
100        HelloWorld
101
102       Spaces and exclamation marks currently cannot  be  passed  into  global
103       variables this way.
104
105

EXAMPLES

107       See the stapex(3stap) manual page for a collection of sample scripts.
108
109       Here is a very basic example of how to use staprun.  First, use stap to
110       compile a script.  The stap program will report  the  pathname  to  the
111       resulting module.
112
113        $ stap -p4 -e 'probe begin { printf("Hello World!\n"); exit() }'
114        /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
115
116       Run staprun with the pathname to the module as an argument.
117
118        $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
119        Hello World!
120

MODULE DETACHING AND ATTACHING

122       After the staprun program installs a Systemtap kernel module, users can
123       detach from the kernel module and reattach to it later.  The -L  option
124       loads  the  module  and  automatically detaches.  Users can also detach
125       from the kernel module interactively by sending the SIGQUIT signal from
126       the keyboard (typically by typing Ctrl-\).
127
128       To reattach to a kernel module, the staprun -A option would be used.
129
130

FILE SWITCHING BY SIGNAL

132       After  the staprun launched the stapio , users can command it to switch
133       output file to next file when it outputs to  file(s)  (running  staprun
134       with -o option) by sending a SIGUSR2 signal to the stapio process. When
135       it receives SIGUSR2, it will switch output file to new file with suffix
136       .N where N is the sequential number.  For example,
137
138        $ staprun -o foo ...
139
140       outputs  trace  logs  to  foo  and  if  it  receives SIGUSR2 signal, it
141       switches output to foo.1 file. And receiving SIGUSR2 again, it switches
142       to foo.2 file.
143
144

SAFETY AND SECURITY

146       Systemtap  is  an administrative tool.  It exposes kernel internal data
147       structures and potentially private user information.  See  the  stap(1)
148       manual page for additional information on safety and security.
149
150       To  increase  system  security,  only the root user and members of both
151       stapdev  and  staprun groups can use staprun to insert  systemtap  mod‐
152       ules  (or  attach to existing ones).  Members of the stapusr group only
153       can use staprun to insert or remove systemtap  modules  (or  attach  to
154       existing systemtap modules) under the following conditions:
155
156       ·   The  module is located in the /lib/modules/VERSION/systemtap direc‐
157           tory.  This directory must be  owned  by  root  and  not  be  world
158           writable.
159
160       ·   The module has been signed by a trusted signer. Trusted signers are
161           normally systemtap compile servers  which  sign  modules  when  the
162           --unprivileged   option   is  specified  by  the  client.  See  the
163           stap-server(8) manual page for a for more information.
164

FILES

166       /lib/modules/VERSION/systemtap
167              If MODULE is a module name, the module will  be  looked  for  in
168              this  directory.   Users who are only in the 'stapusr' group can
169              install modules located in this directory.  This directory  must
170              be owned by the root user and not be world writable.
171

BUGS

178       Use the Bugzilla link of the project web  page  or  our  mailing  list.
179       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
180
181
182
183
184                                                                    STAPRUN(8)