staprun

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.

       This manual corresponds to version 0.6.2.


OPTIONS
       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
	      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 where ’x’ is the cpu number.

       -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 64 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 leav-
	      ing the probes running.  The module can be attached to later by
	      using the -A option.

       -A     Attach to loaded systemtap module.


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.


EXAMPLES
       See the stapex(5) 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.

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 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 systemtap modules (or attach  to	existing  systemtap  modules)
       that are located in the /lib/modules/VERSION/systemtap directory.

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
	      only install modules located in this directory.  This directory
	      should be owned by the root user and not be world writable.

SEE ALSO
       stap(1), stapprobes(5), stapfuncs(5), stapex(5),


BUGS
       Use the Bugzilla link off of the project web page or our mailing list.
       http://sources.redhat.com/systemtap/,<systemtap@sources.redhat.com>.




Red Hat				  2009-04-20			   STAPRUN(8)