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       This manual corresponds to version 0.6.2.
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.
32
33       -c CMD Command CMD will be run and the staprun program will  exit  when
34              CMD  does.   The '_stp_target' variable will contain the pid for
35              CMD.
36
37       -x PID The '_stp_target' variable will be set to PID.
38
39       -o FILE
40              Send output to FILE. If the module uses bulk  mode,  the  output
41              will be in percpu files FILE_x where 'x' is the cpu number.
42
43       -b BUFFER_SIZE
44              The  systemtap  module  will specify a buffer size.  Setting one
45              here will override that value. The value should  be  an  integer
46              between  1  and 64 which be assumed to be the buffer size in MB.
47              That value will be per-cpu if bulk mode is used.
48
49       -L     Load module and start probes, then detach from the module  leav‐
50              ing  the probes running.  The module can be attached to later by
51              using the -A option.
52
53       -A     Attach to loaded systemtap module.
54
55

ARGUMENTS

57       MODULE is either a module path or a module name.  If  it  is  a  module
58       name,  the  module will be looked for in the following directory (where
59       'VERSION' is the output of "uname -r"):
60
61              /lib/modules/VERSION/systemtap
62
63       Any additional arguments on the command line are passed to the module.
64
65

EXAMPLES

67       See the stapex(5) manual page for a collection of sample scripts.
68
69       Here is a very basic example of how to use staprun.  First, use stap to
70       compile  a  script.   The  stap program will report the pathname to the
71       resulting module.
72
73        $ stap -p4 -e 'probe begin { printf("Hello World!\n"); exit() }'
74        /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
75
76       Run staprun with the pathname to the module as an argument.
77
78        $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
79        Hello World!
80

MODULE DETACHING AND ATTACHING

82       After the staprun program installs a Systemtap kernel module, users can
83       detach  from the kernel module and reattach to it later.  The -L option
84       loads the module and automatically detaches.   Users  can  also  detach
85       from the kernel module interactively by sending the SIGQUIT signal from
86       the keyboard (typically by typing Ctrl-\).
87
88       To reattach to a kernel module, the staprun -A option would be used.
89

SAFETY AND SECURITY

91       Systemtap is an administrative tool.  It exposes kernel  internal  data
92       structures  and  potentially private user information.  See the stap(1)
93       manual page for additional information on safety and security.
94
95       To increase system security, only the root  user  and  members  of  the
96       stapdev group can use staprun to insert systemtap modules (or attach to
97       existing ones).  Members of the stapusr group can use staprun to insert
98       systemtap  modules  (or  attach to existing systemtap modules) that are
99       located in the /lib/modules/VERSION/systemtap directory.
100

FILES

102       /lib/modules/VERSION/systemtap
103              If MODULE is a module name, the module will  be  looked  for  in
104              this  directory.   Users who are only in the 'stapusr' group can
105              only install modules located in this directory.  This  directory
106              should be owned by the root user and not be world writable.
107

SEE ALSO

109       stap(1), stapprobes(5), stapfuncs(5), stapex(5),
110
111

BUGS

113       Use  the Bugzilla link off of the project web page or our mailing list.
114       http://sources.redhat.com/systemtap/,<systemtap@sources.redhat.com>.
115
116
117
118
119Red Hat                           2008-03-27                        STAPRUN(8)
Impressum