1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
.\" -*- nroff -*-
.TH STAPRUN 8 @DATE@ "Red Hat"
.SH NAME
staprun \- systemtap runtime
.SH SYNOPSIS
.br
.B staprun
[
.I OPTIONS
]
.I MODULE
[
.I MODULE-OPTIONS
]
.SH DESCRIPTION
The
.I staprun
program is the back-end of the Systemtap tool. It expects a kernel
module produced by the front-end
.I stap
tool.
.PP
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.
.PP
This manual corresponds to version @VERSION@.
.SH OPTIONS
The
.I staprun
program supports the following options. Any other option
prints a list of supported options.
.TP
.B \-v
Verbose mode.
.TP
.B \-c CMD
Command CMD will be run and the
.I staprun
program will exit when CMD
does. The '_stp_target' variable will contain the pid for CMD.
.TP
.B \-x PID
The '_stp_target' variable will be set to PID.
.TP
.B \-o FILE
Send output to FILE. If the module uses bulk mode, the output will
be in percpu files FILE_x where 'x' is the cpu number.
.TP
.B \-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.
.TP
.B \-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
.B \-A
option.
.TP
.B \-A
Attach to loaded systemtap module.
.TP
.B \-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.
.SH ARGUMENTS
.B 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"):
.IP
/lib/modules/VERSION/systemtap
.PP
.\" TODO - we probably need a better description here.
Any additional arguments on the command line are passed to the
module.
.SH EXAMPLES
See the
.IR stapex (5)
manual page for a collection of sample scripts.
.PP
Here is a very basic example of how to use
.I staprun.
First, use
.I stap
to compile a script. The
.I stap
program will report the pathname to the resulting module.
.PP
\& $ stap \-p4 \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
.PP
Run
.I staprun
with the pathname to the module as an argument.
.PP
\& $ staprun /home/user/.systemtap/cache/85/stap_8553d83f78c_265.ko
.br
\& Hello World!
.SH MODULE DETACHING AND ATTACHING
After the
.I staprun
program installs a Systemtap kernel module, users can detach from the
kernel module and reattach to it later. The
.B \-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\-\\).
.PP
To reattach to a kernel module, the
.I staprun
.B \-A
option would be used.
.SH SAFETY AND SECURITY
Systemtap is an administrative tool. It exposes kernel internal data
structures and potentially private user information. See the
.IR stap (1)
manual page for additional information on safety and security.
.PP
To increase system security, only the root user and members of the
.I stapdev
group can use
.I staprun
to insert systemtap modules (or attach to existing ones).
Members of the
.I stapusr
group can use
.I staprun
to insert or remove systemtap modules (or attach to existing systemtap modules) that
are located in the /lib/modules/VERSION/systemtap directory.
.SH FILES
.TP
/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
.I 'stapusr'
group can only install modules
located in this directory. This directory should be owned by the root
user and not be world writable.
.SH SEE ALSO
.IR stap (1),
.IR stapprobes (5),
.IR stapfuncs (5),
.IR stapex (5),
.SH BUGS
Use the Bugzilla link off of the project web page or our mailing list.
.nh
.BR http://sources.redhat.com/systemtap/ ", " <systemtap@sources.redhat.com> .
.hy
|
