Man Linux: Main Page and Category List


       staprun - systemtap runtime


       staprun [ OPTIONS ] MODULE [ MODULE-OPTIONS ]


       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

       This manual corresponds to version 1.2.


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

       -v     Verbose mode.

       -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

       -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.

       -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.

              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.


       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"):


       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"

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


       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() }'

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

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


       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.


       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.


       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  the
       stapdev group can use staprun to insert systemtap modules (or attach to
       existing ones).  Members of the stapusr group 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

       ·   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.


              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.


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


       Use  the  Bugzilla  link  of  the project web page or our mailing list., <>.