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. 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)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
