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 refere 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 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.
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 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 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 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:
· The module is located in the /lib/modules/VERSION/systemtap
directory. This directory must be owned by root and not be world
writable.
· 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://sources.redhat.com/systemtap/, <systemtap@sources.redhat.com>.
STAPRUN(8)