время выполнения systemtap (systemtap runtime)
Имя (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 stapusr 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.
stapusr
Members only of the stapusr group may any-privileged
modules placed into the /lib/modules/VERSION/systemtap by
the system administrator.
stapusr
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>.
