summaryrefslogtreecommitdiffstats
path: root/stap-server.8.in
blob: d44b60f0c6831f9fd4cf3f711b8631468e7f73c7 (plain)
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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
.\" -*- nroff -*-
.TH STAP-SERVER 8 @DATE@ "Red Hat"
.SH NAME
stap\-server \- systemtap server management

.SH SYNOPSIS

.br
[
.B service
]
.B stap\-server
{
.B start
|
.B stop
|
.B restart
|
.B condrestart
|
.B try\-restart
|
.B force\-reload
|
.B status
} [
.I options
]

.SH DESCRIPTION

A systemtap compile server listens for connections from clients
(\fIstap\-client\fR)
on a secure SSL network port and accepts requests to run the
.I stap
front end. Each server advertises its presence and configuration on the local
network using mDNS (\fIavahi\fR) allowing for automatic detection by clients.

.PP
The stap\-server script aims to provide:
.IP \(bu 4
management of systemtap compile servers as a service.
.IP \(bu 4
convenient control over configured servers and individual (ad\-hoc) servers.

.SH ARGUMENTS
One of the actions below must be specified:
.TP
.B start
Start servers. The specified servers are started.
If no server is specified, the configured servers are started. If no servers
are configured, a server for the kernel release and architecture of the host
is started.
If a specified server is
already started, this action will
be ignored for that server. If a server fails to start, this action fails.

.TP
.B stop
Stop server(s). The specified servers are stopped.
If no server is specified, all currently running servers are stopped.
If a specified server is
not running, this action
will be successful for that server. If a server fails to stop, this action
fails.

.TP
.B restart
Stop and restart servers. The specified servers are stopped and restarted.
If no server is specified, all currently running servers are stopped and
restarted. If no servers are running, this action behaves like \fIstart\fR.

.TP
.B condrestart
Stop and restart servers. The specified servers are stopped and restarted.
If a specified server is not running, it is not started. If no server is
specified, all currently running servers are stopped and restarted.  If no
servers are running, none will be started.

.TP
.B try\-restart
This action is identical to \fIcondrestart\fR.

.TP
.B force\-reload
Stop all running servers, reload config files and restart the service as if
.I start
was specified.

.TP
.B status
Print information about running servers. Information about the specified
server(s) will be printed. If no server is specified, information about all
running servers will be printed.

.SH OPTIONS
The following options are used to provide additional configuration and
to specify servers to be managed:

.TP
\fB\-c\fR \fIconfigfile\fR
This option specifies a global configuration file in addition to the default
global configuration file described
below. This file will be processed after the default global
configuration file. If the \fB\-c\fR option is specified more than once, the
last
configuration file specified will be used.

.TP
\fB\-a\fR \fIarchitecture\fR
This option specifies the target architecture of the server and is
analogous to the \fB\-a\fR option of \fIstap\fR. See the
.IR stap (1)
manual page for more details.
The default architecture is the architecture of the host.

.TP
\fB\-r\fR \fIkernel\-release\fR
This option specifies the target kernel release of the server and is
analogous to the \fB\-r\fR option of \fIstap\fR. See the
.IR stap (1)
manual page for more details.
The default release is that of the currently running kernel.

.TP
\fB\-I\fR \fIpath\fR
This option specifies an additional path to be searched by the server(s) for
tapsets and is analogous to the \fB\-I\fR option of \fIstap\fR.
See the
.IR stap (1)
manual page for more details.

.TP
\fB\-R\fR \fIpath\fR
This option specifies the location of the systemtap runtime to be used by the
server(s) and is analogous to the \fB\-R\fR option of \fIstap\fR.
See the
.IR stap (1)
manual page for more details.

.TP
\fB\-B\fR \fIoptions\fR
This option specifies options to be passed to \fImake\fR when building systemtap
modules and is analogous to the \fB\-B\fR option of \fIstap\fR.
See the
.IR stap (1)
manual page for more details.

.TP
\fB\-i\fR
This option is a shortcut which specifies one server for each kernel
release installed in \fI/lib/modules/\fR. Previous
\fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options will be
applied to each server, however previous \fB\-a\fR options will be ignored and
the default architecture will be used.

.TP
\fB\-n\fR \fInickname\fR
This option allows the specification of a server configuration by nickname.
When \fB\-n\fR is specified, a currently running server with the given nickname
will be searched for. If no currently running server with the given nickname is
found, a server configuration with the given nickname will be searched for in
\fI/etc/stap\-server/conf.d/*.conf\fR, or the path configured in
\fI/etc/sysconfig/stap\-server\fR or the config file specified by the
\fB\-c\fR option. If a server configuration for the given
nickname is found, the
\fB\-a\fR, \fB\-r\fR, \fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options for
that server will be used as if they were specified on the command line. If no
configuration with the given nickname is found, and the action is
.I start
(or an action behaving like \fIstart\fR
(see \fBARGUMENTS\fR), the server will be started with the given nickname.
If no configuration with the given nickname is found, and the action is not
.I start
(or an action behaving like \fIstart\fR), it is an error. If a nickname is
not specified for a server which is being started, its nickname will be its
process id.

.TP
\fB\-p\fR \fIpid\fR
This option allows the specification of a server configuration by process id.
When \fB\-p\fR is specified, a currently running server with the given process
id will be searched for. If no such server is found, it is an error. If a server
with the given procss id is found, the
\fB\-a\fR, \fB\-r\fR, \fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options for
that server will be used as if they were specified on the command line.

.TP
\fB\-u\fR \fIuser\-name\fR
Each systemtap compile server is normally run by the user name
\fistap\-server\fR (for the initscript) or as the user invoking
\fIstap-server\fR,
unless otherwise configured (see \fBFILES\fR). This option
specifies the user name used to run the server(s). The user name specified
must be a member of the group \fIstap\-server\fR.

.SH CONFIGURATION

Configuration files allow us to:
.IP \(bu 4
specify global configuration of logging, server configuration files, status
files and other global parameters.
.IP \(bu 4
specify which servers are to be started by default.

.SH Global Configuration

The Global Configuration file (\fI/etc/sysconfig/stap\-server\fR)
is a shell script fragment which may contain
settings for the following variables:

.TP
.B CONFIG_PATH
Specifies the absolute path of the directory containing the default server
configurations
(default: \fI/etc/stap\-server/conf.d\fR).

.TP
.B STAT_PATH
Specifies the absolute path of the running server status directory
(default: \fI/var/run/stap\-server\fR).

.TP
.B LOG_FILE
Specifies the absolute path of the log file
(default: \fI/var/log/stap\-server.log\fR).

.TP
.B STAP_USER
Specifies the userid which will be used to run the server(s)
(default: for the initscript \fIstap\-server\fR, otherwise the user running
\fIstap-server\fR).

.SH Individual Server Configuration

Each server configuration file configures a server to be started when no
server is specified for the \fIstart\fR action, or an action behaving like the
\fIstart\fR action (see \fIARGUMENTS\fR).
Each configuration file is a
shell script fragment with a filename suffix of \fI.conf\fR. The default
location of these files is \fI/etc/stap\-server/conf.d/\fR, but this can be
overridden using the \fB\-c\fR option (see \fIOPTIONS\fR).

The following variables may be set:
.TP
.B ARCH
Specifies the target architecture for this server and corresponds to the
\fB\-a\fR option (see \fIOPTIONS\fR). If \fBARCH\fR is not set, the
architecture of the host will be used.

.TP
.B RELEASE
Specifies the kernel release for this server
and corresponds to the
\fB\-r\fR option (see \fIOPTIONS\fR). If \fBRELEASE\fR is not set, the
release
of the kernel running on the host will be used.
 
.TP
.B BUILD
Specifies options to be passed to the \fImake\fR process used by
\fIsystemtap\fR to build kernel modules
and corresponds to one or more
\fB\-B\fR options (see \fIOPTIONS\fR).
 
.TP
.B INCLUDE
Specifies a list of directories to be searched by the server for tapsets
and corresponds to one or more
\fB\-I\fR options (see \fIOPTIONS\fR).

.TP
.B RUNTIME
Specifies the directory which contains the systemtap runtime code to be used
by this server
and corresponds to the
\fB\-R\fR option (see \fIOPTIONS\fR).

.TP
.B USER
Specifies the user name to be used to run this server
and corresponds to the
\fB\-u\fR option (see \fIOPTIONS\fR).

.TP
.B NICKNAME
Specifies the nickname to be used to refer to this server
and corresponds to the
\fB\-n\fR option (see \fIOPTIONS\fR).

.SH SERVER AUTHENTICAION
The security of the SSL network connection between the client and server
depends on the proper
management of server certificates.

.PP
The trustworthiness of a given systemtap server can not be determined
automatically without a trusted certificate authority issuing systemtap server
certificates. This is
not practical in everyday use and so, clients must authenticate servers
against their own database of trusted server certificates. In this context,
establishing a given server as trusted by a given client means adding
that server\[aq]s certificate to the
client\[aq]s database of trusted servers.

.PP
For the \fIstap\-server\fR initscript, on the local host, this is handled
automatically.
When the \fIsystemtap\-server\fR package is installed, the server\[aq]s
certificate for the default user (\fIstap\-server\fR) is automatically
generated and installed. This means that servers started by the
\fIstap\-server\fR initscript,
with the default user, are automatically trusted by clients on the local
host.

.PP
In order to use a server running on another host, that server\[aq]s certificate
must be installed on the client\[aq]s host.
See the
.IR stap\-authorize\-server\-cert (8)
manual page for more details.

.SH EXAMPLES
See the 
.IR stapex (3stap)
manual page for a collection of sample \fIsystemtap\fR scripts.
.PP
To start the configured servers, or the default server, if none are configured:
.PP
.B \& $ [ service ] stap\-server start
.PP
To start a server for each kernel installed in /lib/modules:
.PP
.B \& $ [ service ] stap\-server start \-i
.PP
To obtain information about the running server(s):
.PP
.B \& $ [ service ] stap\-server status
.PP
To start a server like another one, except targeting a different architecture,
by referencing the first server\[aq]s nickname:
.PP
.B \& $ [ service ] stap\-server start \-n \fINICKNAME\fR \-a \fIARCH\fR
.PP
To stop one of the servers by referencing its process id (obtained by running
\fBstap\-server status\fR):
.PP
.B \& $ [ service ] stap\-server stop \-p \fIPID\fR
.PP
To stop all running servers:
.PP
.B \& $ [ service ] stap\-server stop

.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
As a network server, stap-server should be activated with care in
order to limit the potential effects of bugs or mischevious users.
Consider the following prophylactic measures.
.TP
1
Run stap-server as an unprivileged user, never as root.
.TP
2
Run stap-server with resource limits that impose maximum 
cpu time, file size, memory consumption, in order to bound
the effects of processing excessively large or bogus inputs.
.TP
3
Run stap-server with a $TMPDIR environment variable that
points to a separate and/or quota-enforced directory, in
order to prevent filling up of important filesystems.
.TP
4
Activate network firewalls to limit stap-client connections
to relatively trustworthy networks.

.PP
The systemtap server and its related utilities use the Secure Socket Layer
(SSL) as implemented by Network Security Services (NSS)
for network security. The NSS tool
.I certutil
is used for the generation of certificates. The related
certificate databases must be protected in order to maintain the security of
the system.
Use of the utilities provided will help to ensure that the proper protection
is maintained. The systemtap client will check for proper
access permissions before making use of any certificate database.

.SH FILES
.TP
/etc/sysconfig/stap\-server/
Global configuration file.

.TP
/etc/stap\-server/conf.d/*.conf
Configuration files for default servers.

.TP
/var/run/stap\-server/
Default location of status files for running servers.

.TP
/var/log/stap\-server.log
Default log file.

.TP
/lib/modules/
Location of installed kernels.

.SH SEE ALSO
.IR stap (1),
.IR staprun (8),
.IR stap\-client (8),
.IR stap\-authorize\-server\-cert (8),
.IR stapprobes (3stap),
.IR stapfuncs (3stap),
.IR stapex (3stap),
.IR ulimit (1),
.IR NSS ,
.IR certutil

.SH BUGS
Use the Bugzilla link of the project web page or our mailing list.
.nh
.BR http://sources.redhat.com/systemtap/ ", " <systemtap@sources.redhat.com> .
.hy