bionic (8) staprun.8.gz

Provided by: systemtap-runtime_3.1-3ubuntu0.1_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 development tools (needed to compile the script) and then
       transfer the resulting kernel module to a production machine that  doesn't  have  any  development  tools
       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. The level of verbosity is also set in the SYSTEMTAP_VERBOSE environment variable.

       -V     Print version number and exit.

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

       -C WHEN
              Control coloring of error messages. WHEN must be either "never", "always", or "auto" (i.e.  enable
              only  if  at a terminal). If the option is missing, then "auto" is assumed. Colors can be modified
              using the SYSTEMTAP_COLORS environment variable. See the stap(1) manual page for more  information
              on syntax and behaviour.

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

       -r N:URI
              Pass the given number and URI data to the tapset functions remote_id() and remote_uri().

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

       -T timeout
              Sets  maximum time reader thread will wait before dumping trace buffer. Value is in ms, default is
              200ms. Setting this to a high value decreases number of stapio wake-ups, allowing deeper sleep for
              embedded  platforms.  But  it impacts interactivity on terminal as traces are dumped less often in
              case of low throughput.  There is no interactivity or performance impact for  high  throughput  as
              trace is dumped when buffer is full, before this timeout expires.

       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 staprun launched the stapio program, 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, in the default kernel-module runtime mode, 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, users of systemtap must be root, or in the staprun group in order to execute
       this  setuid  staprun program.  A user may select a particular privilege level with the stap --privilege=
       option, which staprun will later enforce.

       stapdev
              Members of the stapdev group can write and load script modules  with  root-equivalent  privileges,
              without particular security constraints.  (Many safety constraints remain.)

       stapsys
              Members  of  the  stapsys  group  have  almost all the privileges of stapdev, except for guru mode
              constructs.

       staprun
              Members   only   of   the   stapusr   group   may   any-privileged   modules   placed   into   the
              /lib/modules/VERSION/systemtap by the system administrator.

       staprun
              Members  only of the stapusr group may also write and load low-privilege script modules, which are
              normally limited to manipulating their  own  processes  (and  not  the  kernel  nor  other  users'
              processes).

       Part  of  the privilege enforcement mechanism may require using a stap-server and administrative trust in
       its cryptographic signer; see the stap-server(8) manual page for a for more information.

       On a kernel with FIPS mode enabled, staprun normally  refuses  to  attempt  to  load  systemtap-generated
       kernel  modules.   This  is  because  on  some kernels, this results in a panic.  If your kernel includes
       corrections such as linux commit #002c77a48b47, then you  can  force  staprun  to  attempt  module  loads
       anyway, by setting the STAP_FIPS_OVERRIDE environment variable to any value.

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), stap-server(8), stapdyn(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)