]>
Commit | Line | Data |
---|---|---|
ec1a2239 | 1 | .\" -*- nroff -*- |
f7470174 | 2 | .TH STAP\-SERVER 8 |
ec1a2239 | 3 | .SH NAME |
aeb9cc10 | 4 | stap\-server \- systemtap compile server management |
ec1a2239 LB |
5 | |
6 | .SH SYNOPSIS | |
7 | ||
8 | .br | |
9 | [ | |
10 | .B service | |
11 | ] | |
12 | .B stap\-server | |
13 | { | |
14 | .B start | |
15 | | | |
16 | .B stop | |
17 | | | |
18 | .B restart | |
19 | | | |
20 | .B condrestart | |
21 | | | |
22 | .B try\-restart | |
23 | | | |
24 | .B force\-reload | |
25 | | | |
26 | .B status | |
27 | } [ | |
28 | .I options | |
29 | ] | |
30 | ||
31 | .SH DESCRIPTION | |
32 | ||
17874af3 | 33 | A systemtap compile server listens for connections from stap clients |
ec1a2239 LB |
34 | on a secure SSL network port and accepts requests to run the |
35 | .I stap | |
36 | front end. Each server advertises its presence and configuration on the local | |
37 | network using mDNS (\fIavahi\fR) allowing for automatic detection by clients. | |
38 | ||
39 | .PP | |
40 | The stap\-server script aims to provide: | |
41 | .IP \(bu 4 | |
42 | management of systemtap compile servers as a service. | |
43 | .IP \(bu 4 | |
44 | convenient control over configured servers and individual (ad\-hoc) servers. | |
45 | ||
46 | .SH ARGUMENTS | |
47 | One of the actions below must be specified: | |
48 | .TP | |
49 | .B start | |
50 | Start servers. The specified servers are started. | |
51 | If no server is specified, the configured servers are started. If no servers | |
52 | are configured, a server for the kernel release and architecture of the host | |
53 | is started. | |
54 | If a specified server is | |
55 | already started, this action will | |
56 | be ignored for that server. If a server fails to start, this action fails. | |
57 | ||
58 | .TP | |
59 | .B stop | |
60 | Stop server(s). The specified servers are stopped. | |
61 | If no server is specified, all currently running servers are stopped. | |
62 | If a specified server is | |
63 | not running, this action | |
64 | will be successful for that server. If a server fails to stop, this action | |
65 | fails. | |
66 | ||
67 | .TP | |
68 | .B restart | |
69 | Stop and restart servers. The specified servers are stopped and restarted. | |
70 | If no server is specified, all currently running servers are stopped and | |
71 | restarted. If no servers are running, this action behaves like \fIstart\fR. | |
72 | ||
73 | .TP | |
74 | .B condrestart | |
75 | Stop and restart servers. The specified servers are stopped and restarted. | |
76 | If a specified server is not running, it is not started. If no server is | |
77 | specified, all currently running servers are stopped and restarted. If no | |
78 | servers are running, none will be started. | |
79 | ||
80 | .TP | |
81 | .B try\-restart | |
82 | This action is identical to \fIcondrestart\fR. | |
83 | ||
84 | .TP | |
85 | .B force\-reload | |
86 | Stop all running servers, reload config files and restart the service as if | |
87 | .I start | |
88 | was specified. | |
89 | ||
90 | .TP | |
91 | .B status | |
92 | Print information about running servers. Information about the specified | |
93 | server(s) will be printed. If no server is specified, information about all | |
94 | running servers will be printed. | |
95 | ||
96 | .SH OPTIONS | |
97 | The following options are used to provide additional configuration and | |
98 | to specify servers to be managed: | |
99 | ||
100 | .TP | |
101 | \fB\-c\fR \fIconfigfile\fR | |
102 | This option specifies a global configuration file in addition to the default | |
103 | global configuration file described | |
104 | below. This file will be processed after the default global | |
105 | configuration file. If the \fB\-c\fR option is specified more than once, the | |
106 | last | |
107 | configuration file specified will be used. | |
108 | ||
109 | .TP | |
110 | \fB\-a\fR \fIarchitecture\fR | |
111 | This option specifies the target architecture of the server and is | |
112 | analogous to the \fB\-a\fR option of \fIstap\fR. See the | |
113 | .IR stap (1) | |
114 | manual page for more details. | |
115 | The default architecture is the architecture of the host. | |
116 | ||
117 | .TP | |
118 | \fB\-r\fR \fIkernel\-release\fR | |
119 | This option specifies the target kernel release of the server and is | |
120 | analogous to the \fB\-r\fR option of \fIstap\fR. See the | |
121 | .IR stap (1) | |
122 | manual page for more details. | |
123 | The default release is that of the currently running kernel. | |
124 | ||
125 | .TP | |
126 | \fB\-I\fR \fIpath\fR | |
127 | This option specifies an additional path to be searched by the server(s) for | |
128 | tapsets and is analogous to the \fB\-I\fR option of \fIstap\fR. | |
129 | See the | |
130 | .IR stap (1) | |
131 | manual page for more details. | |
132 | ||
133 | .TP | |
134 | \fB\-R\fR \fIpath\fR | |
135 | This option specifies the location of the systemtap runtime to be used by the | |
136 | server(s) and is analogous to the \fB\-R\fR option of \fIstap\fR. | |
137 | See the | |
138 | .IR stap (1) | |
139 | manual page for more details. | |
140 | ||
141 | .TP | |
142 | \fB\-B\fR \fIoptions\fR | |
143 | This option specifies options to be passed to \fImake\fR when building systemtap | |
144 | modules and is analogous to the \fB\-B\fR option of \fIstap\fR. | |
145 | See the | |
146 | .IR stap (1) | |
147 | manual page for more details. | |
148 | ||
149 | .TP | |
150 | \fB\-i\fR | |
151 | This option is a shortcut which specifies one server for each kernel | |
152 | release installed in \fI/lib/modules/\fR. Previous | |
153 | \fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options will be | |
154 | applied to each server, however previous \fB\-a\fR options will be ignored and | |
155 | the default architecture will be used. | |
156 | ||
157 | .TP | |
158 | \fB\-n\fR \fInickname\fR | |
159 | This option allows the specification of a server configuration by nickname. | |
160 | When \fB\-n\fR is specified, a currently running server with the given nickname | |
161 | will be searched for. If no currently running server with the given nickname is | |
162 | found, a server configuration with the given nickname will be searched for in | |
80f2faf4 DB |
163 | the configuration files for default servers, |
164 | or the path configured in the global configuration file or | |
165 | the configuration file specified by the | |
ec1a2239 LB |
166 | \fB\-c\fR option. If a server configuration for the given |
167 | nickname is found, the | |
168 | \fB\-a\fR, \fB\-r\fR, \fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options for | |
169 | that server will be used as if they were specified on the command line. If no | |
170 | configuration with the given nickname is found, and the action is | |
171 | .I start | |
172 | (or an action behaving like \fIstart\fR | |
173 | (see \fBARGUMENTS\fR), the server will be started with the given nickname. | |
174 | If no configuration with the given nickname is found, and the action is not | |
175 | .I start | |
176 | (or an action behaving like \fIstart\fR), it is an error. If a nickname is | |
177 | not specified for a server which is being started, its nickname will be its | |
178 | process id. | |
179 | ||
180 | .TP | |
181 | \fB\-p\fR \fIpid\fR | |
182 | This option allows the specification of a server configuration by process id. | |
183 | When \fB\-p\fR is specified, a currently running server with the given process | |
184 | id will be searched for. If no such server is found, it is an error. If a server | |
185 | with the given procss id is found, the | |
186 | \fB\-a\fR, \fB\-r\fR, \fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options for | |
187 | that server will be used as if they were specified on the command line. | |
188 | ||
189 | .TP | |
190 | \fB\-u\fR \fIuser\-name\fR | |
191 | Each systemtap compile server is normally run by the user name | |
192 | \fistap\-server\fR (for the initscript) or as the user invoking | |
f7470174 | 193 | \fIstap\-server\fR, |
ec1a2239 LB |
194 | unless otherwise configured (see \fBFILES\fR). This option |
195 | specifies the user name used to run the server(s). The user name specified | |
196 | must be a member of the group \fIstap\-server\fR. | |
197 | ||
198 | .SH CONFIGURATION | |
199 | ||
200 | Configuration files allow us to: | |
201 | .IP \(bu 4 | |
202 | specify global configuration of logging, server configuration files, status | |
203 | files and other global parameters. | |
204 | .IP \(bu 4 | |
205 | specify which servers are to be started by default. | |
206 | ||
207 | .SH Global Configuration | |
208 | ||
80f2faf4 | 209 | The Global Configuration file contains |
c807ba1b DB |
210 | variable assignments used to configure the overall operation of the service. |
211 | Each line beginning with a '#' character is ignored. All other lines must be | |
212 | of the form \fIVARIABLE=VALUE\fR. This is not a shell script. The entire | |
213 | contents of the line after the = will be assigned as\-is to the variable. | |
214 | ||
215 | The following variables may be assigned: | |
ec1a2239 LB |
216 | |
217 | .TP | |
218 | .B CONFIG_PATH | |
219 | Specifies the absolute path of the directory containing the default server | |
80f2faf4 | 220 | configurations. |
ec1a2239 LB |
221 | |
222 | .TP | |
223 | .B STAT_PATH | |
80f2faf4 | 224 | Specifies the absolute path of the running server status directory. |
ec1a2239 LB |
225 | |
226 | .TP | |
227 | .B LOG_FILE | |
80f2faf4 | 228 | Specifies the absolute path of the log file. |
ec1a2239 LB |
229 | |
230 | .TP | |
231 | .B STAP_USER | |
232 | Specifies the userid which will be used to run the server(s) | |
233 | (default: for the initscript \fIstap\-server\fR, otherwise the user running | |
f7470174 | 234 | \fIstap\-server\fR). |
ec1a2239 LB |
235 | |
236 | .SH Individual Server Configuration | |
237 | ||
238 | Each server configuration file configures a server to be started when no | |
239 | server is specified for the \fIstart\fR action, or an action behaving like the | |
c807ba1b DB |
240 | \fIstart\fR action (see \fIARGUMENTS\fR). Each configuration file contains |
241 | variable assignments used to configure an individual server. | |
242 | ||
243 | Each line beginning with a '#' character is ignored. All other lines must be | |
244 | of the form \fIVARIABLE=VALUE\fR. This is not a shell script. The entire | |
245 | contents of the line after the = will be assigned as\-is to the variable. | |
246 | ||
247 | Each configuration file must have a | |
248 | filename suffix of \fI.conf\fR. The default | |
80f2faf4 | 249 | location of these files can be |
c807ba1b DB |
250 | overridden in the global configuration file using the \fB\-c\fR option |
251 | (see \fIOPTIONS\fR). | |
ec1a2239 | 252 | |
c807ba1b | 253 | The following variables may be assigned: |
ec1a2239 LB |
254 | .TP |
255 | .B ARCH | |
256 | Specifies the target architecture for this server and corresponds to the | |
257 | \fB\-a\fR option (see \fIOPTIONS\fR). If \fBARCH\fR is not set, the | |
258 | architecture of the host will be used. | |
259 | ||
260 | .TP | |
261 | .B RELEASE | |
262 | Specifies the kernel release for this server | |
263 | and corresponds to the | |
264 | \fB\-r\fR option (see \fIOPTIONS\fR). If \fBRELEASE\fR is not set, the | |
265 | release | |
266 | of the kernel running on the host will be used. | |
267 | ||
268 | .TP | |
269 | .B BUILD | |
270 | Specifies options to be passed to the \fImake\fR process used by | |
c807ba1b DB |
271 | \fIsystemtap\fR to build kernel modules. |
272 | This an array variable with each element corresponding to a | |
273 | \fB\-B\fR option (see \fIOPTIONS\fR). Using the form \fBBUILD=STRING\fR clears | |
274 | the array and sets the first element to \fBSTRING\fR. Using the form | |
275 | \fBBUILD+=STRING\fR adds \fBSTRING\fR as an additional element to the array. | |
ec1a2239 LB |
276 | |
277 | .TP | |
278 | .B INCLUDE | |
c807ba1b DB |
279 | Specifies a list of directories to be searched by the server for tapsets. |
280 | This an array variable with each element corresponding to an | |
281 | \fB\-I\fR option (see \fIOPTIONS\fR). Using the form \fBINCLUDE=PATH\fR clears | |
282 | the array and sets the first element to \fBPATH\fR. Using the form | |
283 | \fBINCLUDE+=PATH\fR adds \fBPATH\fR as an additional element to the array. | |
ec1a2239 LB |
284 | |
285 | .TP | |
286 | .B RUNTIME | |
287 | Specifies the directory which contains the systemtap runtime code to be used | |
288 | by this server | |
289 | and corresponds to the | |
290 | \fB\-R\fR option (see \fIOPTIONS\fR). | |
291 | ||
292 | .TP | |
293 | .B USER | |
294 | Specifies the user name to be used to run this server | |
295 | and corresponds to the | |
296 | \fB\-u\fR option (see \fIOPTIONS\fR). | |
297 | ||
298 | .TP | |
299 | .B NICKNAME | |
300 | Specifies the nickname to be used to refer to this server | |
301 | and corresponds to the | |
302 | \fB\-n\fR option (see \fIOPTIONS\fR). | |
303 | ||
304 | .SH SERVER AUTHENTICAION | |
305 | The security of the SSL network connection between the client and server | |
306 | depends on the proper | |
307 | management of server certificates. | |
308 | ||
309 | .PP | |
aeb9cc10 DB |
310 | The trustworthiness of a given systemtap compile server can not be determined |
311 | automatically without a trusted certificate authority issuing systemtap compile server | |
ec1a2239 LB |
312 | certificates. This is |
313 | not practical in everyday use and so, clients must authenticate servers | |
314 | against their own database of trusted server certificates. In this context, | |
315 | establishing a given server as trusted by a given client means adding | |
316 | that server\[aq]s certificate to the | |
317 | client\[aq]s database of trusted servers. | |
318 | ||
319 | .PP | |
320 | For the \fIstap\-server\fR initscript, on the local host, this is handled | |
321 | automatically. | |
322 | When the \fIsystemtap\-server\fR package is installed, the server\[aq]s | |
323 | certificate for the default user (\fIstap\-server\fR) is automatically | |
324 | generated and installed. This means that servers started by the | |
325 | \fIstap\-server\fR initscript, | |
326 | with the default user, are automatically trusted by clients on the local | |
80f2faf4 DB |
327 | host, both as an SSL peer and as a systemtap module signer. Furthermore, |
328 | when stap is invoked by an unprivileged user | |
329 | (not root, not a member of the group stapdev, but a member of the group | |
330 | stapusr), the options \fI\-\-use\-server\fR and \fI\-\-unprivileged\fR | |
331 | are automatically added to the specified options. | |
332 | This means that unprivileged users | |
333 | on the local host can use a server on the local host | |
334 | in unprivileged mode with no further setup or options required. | |
ec1a2239 LB |
335 | |
336 | .PP | |
337 | In order to use a server running on another host, that server\[aq]s certificate | |
338 | must be installed on the client\[aq]s host. | |
17874af3 DB |
339 | See the \fI\-\-trust\-servers\fR option in the |
340 | .IR stap (1) | |
80f2faf4 DB |
341 | manual page for more details and README.unprivileged in the systemtap sources |
342 | for more details.. | |
ec1a2239 LB |
343 | |
344 | .SH EXAMPLES | |
345 | See the | |
346 | .IR stapex (3stap) | |
347 | manual page for a collection of sample \fIsystemtap\fR scripts. | |
348 | .PP | |
349 | To start the configured servers, or the default server, if none are configured: | |
350 | .PP | |
351 | .B \& $ [ service ] stap\-server start | |
352 | .PP | |
353 | To start a server for each kernel installed in /lib/modules: | |
354 | .PP | |
355 | .B \& $ [ service ] stap\-server start \-i | |
356 | .PP | |
357 | To obtain information about the running server(s): | |
358 | .PP | |
359 | .B \& $ [ service ] stap\-server status | |
360 | .PP | |
361 | To start a server like another one, except targeting a different architecture, | |
362 | by referencing the first server\[aq]s nickname: | |
363 | .PP | |
364 | .B \& $ [ service ] stap\-server start \-n \fINICKNAME\fR \-a \fIARCH\fR | |
365 | .PP | |
366 | To stop one of the servers by referencing its process id (obtained by running | |
367 | \fBstap\-server status\fR): | |
368 | .PP | |
369 | .B \& $ [ service ] stap\-server stop \-p \fIPID\fR | |
370 | .PP | |
80f2faf4 DB |
371 | To run a script using a compile server: |
372 | .PP | |
373 | .B \& $ stap SCRIPT \-\-use\-server | |
374 | .PP | |
375 | To run a script as an unprivileged user using a compile server: | |
376 | .PP | |
377 | .B \& $ stap SCRIPT | |
378 | .PP | |
ec1a2239 LB |
379 | To stop all running servers: |
380 | .PP | |
381 | .B \& $ [ service ] stap\-server stop | |
382 | ||
383 | .SH SAFETY AND SECURITY | |
384 | Systemtap is an administrative tool. It exposes kernel internal data | |
385 | structures and potentially private user information. See the | |
386 | .IR stap (1) | |
387 | manual page for additional information on safety and security. | |
388 | ||
389 | .PP | |
f7470174 | 390 | As a network server, stap\-server should be activated with care in |
ec1a2239 LB |
391 | order to limit the potential effects of bugs or mischevious users. |
392 | Consider the following prophylactic measures. | |
393 | .TP | |
394 | 1 | |
b6f2661b DB |
395 | Run stap\-server as an unprivileged user, never as root. |
396 | ||
397 | When invoked as a | |
398 | service (i.e. \fBservice stap\-server\fR ...), each server is run, | |
399 | by default, as the user \fIstap\-server\fR. | |
400 | When invoked directly (i.e. \fBstap\-server\fR ...), each server is run, | |
401 | by default, as the invoking user. In each case, another user may be selected by | |
402 | using the \fI\-u\fR option on invocation, by specifying | |
403 | \fISTAP_USER=\fRusername in the global configuration file or by specifying | |
404 | \fIUSER=\fRusername in an individual server configuration file. The invoking | |
405 | user must have authority to run processes as another user. | |
406 | See \fICONFIGURATION\fR. | |
407 | ||
80f2faf4 DB |
408 | The selected user must have write access to the server log file. |
409 | The location of the server log file may | |
b6f2661b DB |
410 | be changed by setting \fILOG_FILE=\fRpath in the global configuration file. |
411 | See \fICONFIGURATION\fR. | |
412 | ||
413 | The selected user must have | |
80f2faf4 DB |
414 | read/write access to the directory containing the server status files. |
415 | The location of the server | |
b6f2661b DB |
416 | status files may be changed by setting \fISTAT_PATH=\fRpath in the global |
417 | configuration file. | |
418 | See \fICONFIGURATION\fR. | |
419 | ||
420 | The selected user must have | |
80f2faf4 | 421 | read/write access to the uprobes.ko build directory and its files. |
b6f2661b DB |
422 | |
423 | Neither form of stap\-server will run if the selected user is root. | |
424 | ||
ec1a2239 LB |
425 | .TP |
426 | 2 | |
f7470174 | 427 | Run stap\-server with resource limits that impose maximum |
ec1a2239 LB |
428 | cpu time, file size, memory consumption, in order to bound |
429 | the effects of processing excessively large or bogus inputs. | |
b6f2661b DB |
430 | |
431 | When the user running the servers is \fIstap\-server\fR, | |
432 | each server is run with limits equivalent to | |
433 | ||
f7470174 | 434 | ulimit \-f 50000 \-s 1000 \-t 60 \-u 20 \-v 500000 |
b6f2661b DB |
435 | |
436 | otherwise, no limits are imposed. | |
437 | ||
ec1a2239 LB |
438 | .TP |
439 | 3 | |
f7470174 | 440 | Run stap\-server with a TMPDIR environment variable that |
ec1a2239 LB |
441 | points to a separate and/or quota-enforced directory, in |
442 | order to prevent filling up of important filesystems. | |
b6f2661b DB |
443 | |
444 | The default TMPDIR is \fI/tmp/\fR. | |
445 | ||
ec1a2239 LB |
446 | .TP |
447 | 4 | |
17874af3 | 448 | Activate network firewalls to limit stap client connections |
ec1a2239 LB |
449 | to relatively trustworthy networks. |
450 | ||
b6f2661b DB |
451 | For automatic selection of servers by clients, \fIavahi\fR must be installed |
452 | on both the server and client hosts and \fImDNS\fR messages must be allowed through the firewall. | |
453 | ||
ec1a2239 | 454 | .PP |
aeb9cc10 | 455 | The systemtap compile server and its related utilities use the Secure Socket Layer |
ec1a2239 | 456 | (SSL) as implemented by Network Security Services (NSS) |
aeb9cc10 DB |
457 | for network security. NSS is also used |
458 | for the generation and management of certificates. The related | |
ec1a2239 LB |
459 | certificate databases must be protected in order to maintain the security of |
460 | the system. | |
461 | Use of the utilities provided will help to ensure that the proper protection | |
462 | is maintained. The systemtap client will check for proper | |
463 | access permissions before making use of any certificate database. | |
464 | ||
465 | .SH FILES | |
466 | .TP | |
80f2faf4 DB |
467 | Important files and their corresponding paths can be located in the |
468 | stappaths (7) manual page. | |
ec1a2239 LB |
469 | |
470 | .SH SEE ALSO | |
471 | .IR stap (1), | |
472 | .IR staprun (8), | |
ec1a2239 LB |
473 | .IR stapprobes (3stap), |
474 | .IR stapfuncs (3stap), | |
c807ba1b | 475 | .IR stappaths (7), |
ec1a2239 | 476 | .IR stapex (3stap), |
b6f2661b | 477 | .IR avahi , |
ec1a2239 | 478 | .IR ulimit (1), |
aeb9cc10 | 479 | .IR NSS |
ec1a2239 LB |
480 | |
481 | .SH BUGS | |
482 | Use the Bugzilla link of the project web page or our mailing list. | |
483 | .nh | |
306dd4f8 | 484 | .BR http://sourceware.org/systemtap/ ", " <systemtap@sourceware.org> . |
ec1a2239 LB |
485 | .hy |
486 |