STAPRUN(8)						      System Manager's Manual							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 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.

       -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 op-
	      tion  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 , system-
	      tap 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 val-
	      ue 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
", 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!
"); 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 op-
       tion 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 potential-
       ly 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 con-
	      straints.  (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  adminis-
	      trator.

       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.

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)