staprun.8.in

   1 .\" -*- nroff -*-
   2 .TH STAPRUN 8 @DATE@ "Red Hat"
   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 debugging information (need to compile the script) and then
  30 transfer the resulting kernel module to a production machine that
  31 doesn't have any development tools or kernel debugging information installed.
  32 .PP
  33 This manual corresponds to version @VERSION@.
  34
  35 .SH OPTIONS
  36 The
  37 .I staprun
  38 program supports the following options.  Any other option
  39 prints a list of supported options.
  40 .TP
  41 .B \-v
  42 Verbose mode.
  43 .TP
  44 .B \-c CMD
  45 Command CMD will be run and the
  46 .I staprun
  47 program will exit when CMD
  48 does.  The '_stp_target' variable will contain the pid for CMD.
  49 .TP
  50 .B \-x PID
  51 The '_stp_target' variable will be set to PID.
  52 .TP
  53 .B \-o FILE
  54 Send output to FILE. If the module uses bulk mode, the output will
  55 be in percpu files FILE_x(FILE_cpux in background and bulk mode)
  56 where 'x' is the cpu number. This supports strftime(3) formats
  57 for FILE.
  58 .TP
  59 .B \-b BUFFER_SIZE
  60 The systemtap module will specify a buffer size.
  61 Setting one here will override that value. The value should be
  62 an integer between 1 and 4095 which be assumed to be the
  63 buffer size in MB. That value will be per-cpu if bulk mode is used.
  64 .TP
  65 .B \-L
  66 Load module and start probes, then detach from the module leaving the
  67 probes running.  The module can be attached to later by using the
  68 .B \-A
  69 option.
  70 .TP
  71 .B \-A
  72 Attach to loaded systemtap module.
  73 .TP
  74 .B \-d
  75 Delete a module.  Only detached or unused modules
  76 the user has permission to access will be deleted. Use "*"
  77 (quoted) to delete all unused modules.
  78 .TP
  79 .BI \-D
  80 Run staprun in background as a daemon and show it's pid.
  81 .TP
  82 .BI \-S " size[,N]"
  83 Sets the maximum size of output file and the maximum number of output files.
  84 If the size of output file will exceed
  85 .B size
  86 , systemtap switches output file to the next file. And if the number of
  87 output files exceed
  88 .B N
  89 , systemtap removes the oldest output file. You can omit the second argument.
  90
  91 .SH ARGUMENTS
  92 .B MODULE
  93 is either a module path or a module name.  If it is a module name,
  94 the module will be looked for in the following directory
  95 (where 'VERSION' is the output of "uname \-r"):
  96 .IP
  97 /lib/modules/VERSION/systemtap
  98 .PP
  99 .\" TODO - we probably need a better description here.
 100 Any additional arguments on the command line are passed to the
 101 module.
 102
 103 .SH EXAMPLES
 104 See the
 105 .IR stapex (3stap)
 106 manual page for a collection of sample scripts.
 107 .PP
 108 Here is a very basic example of how to use
 109 .I staprun.
 110 First, use
 111 .I stap
 112 to compile a script.  The
 113 .I stap
 114 program will report the pathname to the resulting module.
 115 .PP
 116 \& $ stap \-p4 \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
 117 .br
 118 \& /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
 119 .PP
 120 Run
 121 .I staprun
 122 with the pathname to the module as an argument.
 123 .PP
 124 \& $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
 125 .br
 126 \& Hello World!
 127 .SH MODULE DETACHING AND ATTACHING
 128 After the
 129 .I staprun
 130 program installs a Systemtap kernel module, users can detach from the
 131 kernel module and reattach to it later.  The
 132 .B \-L
 133 option loads the module and automatically detaches.  Users can also
 134 detach from the kernel module interactively by sending the SIGQUIT
 135 signal from the keyboard (typically by typing Ctrl\-\\).
 136 .PP
 137 To reattach to a kernel module, the
 138 .I staprun
 139 .B \-A
 140 option would be used.
 141
 142 .SH FILE SWITCHING BY SIGNAL
 143 After the
 144 .I staprun
 145 launched the
 146 .I stapio
 147 , users can command it to switch output file to next file when it
 148 outputs to file(s) (running staprun with
 149 .B \-o
 150 option) by sending a
 151 .B SIGUSR2
 152 signal to the
 153 .I stapio
 154 process. When it receives SIGUSR2, it will switch output file to
 155 new file with suffix
 156 .I .N
 157 where N is the sequential number.
 158 For example,
 159 .PP
 160 \& $ staprun \-o foo ...
 161 .PP
 162 outputs trace logs to
 163 .I foo
 164 and if it receives
 165 .B SIGUSR2
 166 signal, it switches output to
 167 .I foo.1
 168 file. And receiving
 169 .B SIGUSR2
 170 again, it switches to
 171 .I foo.2
 172 file.
 173
 174 .SH SAFETY AND SECURITY
 175 Systemtap is an administrative tool.  It exposes kernel internal data
 176 structures and potentially private user information.  See the
 177 .IR stap (1)
 178 manual page for additional information on safety and security.
 179 .PP
 180 To increase system security, only the root user and members of the
 181 .I stapdev
 182 group can use
 183 .I staprun
 184 to insert systemtap modules (or attach to existing ones).
 185 Members of the
 186 .I stapusr
 187 group can use
 188 .I staprun
 189 to insert or remove systemtap modules (or attach to existing systemtap modules) that
 190 are located in the /lib/modules/VERSION/systemtap directory.
 191 .SH FILES
 192 .TP
 193 /lib/modules/VERSION/systemtap
 194 If MODULE is a module name, the module will be looked for in this directory.
 195 Users who are only in the
 196 .I 'stapusr'
 197 group can only install modules
 198 located in this directory.  This directory should be owned by the root
 199 user and not be world writable.
 200 .SH SEE ALSO
 201 .IR stap (1),
 202 .IR stapprobes (3stap),
 203 .IR stapfuncs (3stap),
 204 .IR stapex (3stap),
 205
 206 .SH BUGS
 207 Use the Bugzilla link off of the project web page or our mailing list.
 208 .nh
 209 .BR http://sources.redhat.com/systemtap/ ", " <systemtap@sources.redhat.com> .
 210 .hy
 211