Provided by: systemtap-runtime_1.6-1ubuntu1_amd64 bug

NAME

       staprun - systemtap runtime

SYNOPSIS

       staprun [ OPTIONS ] MODULE [ MODULE-OPTIONS ]

DESCRIPTION

       The  staprun  program  is  the back-end of the Systemtap tool.  It expects a kernel module
       produced by the front-end stap tool.

       Splitting the systemtap tool into a front-end and a back-end allows a user  to  compile  a
       systemtap  script on a development machine that has the kernel debugging information (need
       to compile the script) and then transfer the  resulting  kernel  module  to  a  production
       machine that doesn't have any development tools or kernel debugging information installed.

       Please  refer to stappaths (7) for the version number, or run rpm -q systemtap (fedora/red
       hat) apt-get -v systemtap (ubuntu)

OPTIONS

       The staprun program supports the following options.  Any other option  prints  a  list  of
       supported options.

       -v     Verbose mode.

       -w     Suppress warnings from the script.

       -u     Load the uprobes.ko module.

       -c CMD Command  CMD  will  be  run  and  the staprun program will exit when CMD does.  The
              '_stp_target' variable will contain the pid for CMD.

       -x PID The '_stp_target' variable will be set to PID.

       -o FILE
              Send output to FILE. If the module uses bulk mode, the output  will  be  in  percpu
              files  FILE_x(FILE_cpux  in  background and bulk mode) where 'x' is the cpu number.
              This supports strftime(3) formats for FILE.

       -b BUFFER_SIZE
              The systemtap module will specify a buffer size.  Setting one  here  will  override
              that  value.  The value should be an integer between 1 and 4095 which be assumed to
              be the buffer size in MB. That value will be per-cpu if bulk mode is used.

       -L     Load module and start probes, then  detach  from  the  module  leaving  the  probes
              running.  The module can be attached to later by using the -A option.

       -A     Attach to loaded systemtap module.

       -d     Delete a module.  Only detached or unused modules the user has permission to access
              will be deleted. Use "*" (quoted) to delete all unused modules.

       -D     Run staprun in background as a daemon and show it's pid.

       -R     Rename the module to a unique name before inserting it.

       -S size[,N]
              Sets the maximum size of output file and the maximum number of  output  files.   If
              the  size  of  output file will exceed size , systemtap switches output file to the
              next file. And if the number of output files  exceed  N  ,  systemtap  removes  the
              oldest output file. You can omit the second argument.

       var1=val
              Sets  the value of global variable var1 to val. Global variables contained within a
              module are treated as module options and can be set from the staprun command line.

ARGUMENTS

       MODULE is either a module path or a module name.  If it is a module name, the module  will
       be looked for in the following directory (where 'VERSION' is the output of "uname -r"):

              /lib/modules/VERSION/systemtap

       Any  additional  arguments on the command line are passed to the module.  One use of these
       additional module arguments is to set the value of global variables  declared  within  the
       module.

        $ stap -p4 -m mod1 -e 'global var1="foo"; probe begin{printf("%s\n", var1); exit()}'

       Running this with an additional module argument:

        $ staprun mod1.ko var1="HelloWorld"
        HelloWorld

       Spaces and exclamation marks currently cannot be passed into global variables this way.

EXAMPLES

       See the stapex(3stap) manual page for a collection of sample scripts.

       Here  is a very basic example of how to use staprun.  First, use stap to compile a script.
       The stap program will report the pathname to the resulting module.

        $ stap -p4 -e 'probe begin { printf("Hello World!\n"); exit() }'
        /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko

       Run staprun with the pathname to the module as an argument.

        $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
        Hello World!

MODULE DETACHING AND ATTACHING

       After the staprun program installs a Systemtap kernel module, users can  detach  from  the
       kernel  module and reattach to it later.  The -L option loads the module and automatically
       detaches.  Users can also detach from the  kernel  module  interactively  by  sending  the
       SIGQUIT signal from the keyboard (typically by typing Ctrl-\).

       To reattach to a kernel module, the staprun -A option would be used.

FILE SWITCHING BY SIGNAL

       After the staprun launched the stapio , users can command it to switch output file to next
       file when it outputs to file(s) (running staprun with -o  option)  by  sending  a  SIGUSR2
       signal  to the stapio process. When it receives SIGUSR2, it will switch output file to new
       file with suffix .N where N is the sequential number.  For example,

        $ staprun -o foo ...

       outputs trace logs to foo and if it receives SIGUSR2 signal, it switches output  to  foo.1
       file. And receiving SIGUSR2 again, it switches to foo.2 file.

SAFETY AND SECURITY

       Systemtap  is  an  administrative  tool.   It  exposes kernel internal data structures and
       potentially private  user  information.   See  the  stap(1)  manual  page  for  additional
       information on safety and security.

       To  increase system security, only the root user and members of both stapdev  and  staprun
       groups can use staprun to insert systemtap modules (or attach to existing ones).   Members
       of the stapusr group only can use staprun to insert or remove systemtap modules (or attach
       to existing systemtap modules) under the following conditions:

       ·   The module is located in the /lib/modules/VERSION/systemtap directory.  This directory
           must be owned by root and not be world writable.

       ·   The module has been signed by a trusted signer. Trusted signers are normally systemtap
           compile servers which sign modules when the --unprivileged option is specified by  the
           client. See the stap-server(8) manual page for a for more information.

FILES

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

SEE ALSO

       stap(1), stapprobes(3stap), stapfuncs(3stap), stap-server(8), stapex(3stap)

BUGS

       Use   the   Bugzilla   link   of   the   project   web   page   or   our   mailing   list.
       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.

                                                                                       STAPRUN(8)