STAPRUN(8)                                                                                                            STAPRUN(8)



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  back-
              ground 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  ,  sys-
              temtap 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 interac-
       tively 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  informa-
       tion.  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:

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

       o   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/,
       <systemtapATsourceware.org>.




                                                                                                                      STAPRUN(8)