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 sys‐
temtap (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.
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 em‐
bedded 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 ar‐
guments 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.
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 informa‐
tion 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 con‐
structs.
staprun
Members only of the stapusr group may any-privileged modules placed into the /lib/modules/VERSION/sys‐
temtap by the system administrator.
staprun
Members only of the stapusr group may also write and load low-privilege script modules, which are nor‐
mally 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/,
<[email protected]>.
Back to main site | Back to man page index