4 stap\-server \- systemtap compile server management
33 A systemtap compile server listens for connections from stap clients
34 on a secure SSL network port and accepts requests to run the
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.
40 The stap\-server script aims to provide:
42 management of systemtap compile servers as a service.
44 convenient control over configured servers and individual (ad\-hoc) servers.
47 One of the actions below must be specified:
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
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.
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
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.
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.
82 This action is identical to \fIcondrestart\fR.
86 Stop all running servers, reload config files and restart the service as if
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.
97 The following options are used to provide additional configuration and
98 to specify servers to be managed:
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
107 configuration file specified will be used.
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
114 manual page for more details.
115 The default architecture is the architecture of the host.
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
122 manual page for more details.
123 The default release is that of the currently running kernel.
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.
131 manual page for more details.
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.
139 manual page for more details.
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.
147 manual page for more details.
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.
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
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
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
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
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
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.
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
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.
200 Configuration files allow us to:
202 specify global configuration of logging, server configuration files, status
203 files and other global parameters.
205 specify which servers are to be started by default.
207 .SH Global Configuration
209 The Global Configuration file contains
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.
215 The following variables may be assigned:
219 Specifies the absolute path of the directory containing the default server
224 Specifies the absolute path of the running server status directory.
228 Specifies the absolute path of the log file.
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
236 .SH Individual Server Configuration
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
240 \fIstart\fR action (see \fIARGUMENTS\fR). Each configuration file contains
241 variable assignments used to configure an individual server.
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.
247 Each configuration file must have a
248 filename suffix of \fI.conf\fR. The default
249 location of these files can be
250 overridden in the global configuration file using the \fB\-c\fR option
253 The following variables may be assigned:
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.
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
266 of the kernel running on the host will be used.
270 Specifies options to be passed to the \fImake\fR process used by
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.
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.
287 Specifies the directory which contains the systemtap runtime code to be used
289 and corresponds to the
290 \fB\-R\fR option (see \fIOPTIONS\fR).
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).
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).
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.
310 The trustworthiness of a given systemtap compile server can not be determined
311 automatically without a trusted certificate authority issuing systemtap compile server
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.
320 For the \fIstap\-server\fR initscript, on the local host, this is handled
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
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.
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.
339 See the \fI\-\-trust\-servers\fR option in the
341 manual page for more details and README.unprivileged in the systemtap sources
347 manual page for a collection of sample \fIsystemtap\fR scripts.
349 To start the configured servers, or the default server, if none are configured:
351 .B \& $ [ service ] stap\-server start
353 To start a server for each kernel installed in /lib/modules:
355 .B \& $ [ service ] stap\-server start \-i
357 To obtain information about the running server(s):
359 .B \& $ [ service ] stap\-server status
361 To start a server like another one, except targeting a different architecture,
362 by referencing the first server\[aq]s nickname:
364 .B \& $ [ service ] stap\-server start \-n \fINICKNAME\fR \-a \fIARCH\fR
366 To stop one of the servers by referencing its process id (obtained by running
367 \fBstap\-server status\fR):
369 .B \& $ [ service ] stap\-server stop \-p \fIPID\fR
371 To run a script using a compile server:
373 .B \& $ stap SCRIPT \-\-use\-server
375 To run a script as an unprivileged user using a compile server:
379 To stop all running servers:
381 .B \& $ [ service ] stap\-server stop
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
387 manual page for additional information on safety and security.
390 As a network server, stap\-server should be activated with care in
391 order to limit the potential effects of bugs or mischevious users.
392 Consider the following prophylactic measures.
395 Run stap\-server as an unprivileged user, never as root.
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.
408 The selected user must have write access to the server log file.
409 The location of the server log file may
410 be changed by setting \fILOG_FILE=\fRpath in the global configuration file.
411 See \fICONFIGURATION\fR.
413 The selected user must have
414 read/write access to the directory containing the server status files.
415 The location of the server
416 status files may be changed by setting \fISTAT_PATH=\fRpath in the global
418 See \fICONFIGURATION\fR.
420 The selected user must have
421 read/write access to the uprobes.ko build directory and its files.
423 Neither form of stap\-server will run if the selected user is root.
427 Run stap\-server with resource limits that impose maximum
428 cpu time, file size, memory consumption, in order to bound
429 the effects of processing excessively large or bogus inputs.
431 When the user running the servers is \fIstap\-server\fR,
432 each server is run with limits equivalent to
434 ulimit \-f 50000 \-s 1000 \-t 60 \-u 20 \-v 500000
436 otherwise, no limits are imposed.
440 Run stap\-server with a TMPDIR environment variable that
441 points to a separate and/or quota-enforced directory, in
442 order to prevent filling up of important filesystems.
444 The default TMPDIR is \fI/tmp/\fR.
448 Activate network firewalls to limit stap client connections
449 to relatively trustworthy networks.
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.
455 The systemtap compile server and its related utilities use the Secure Socket Layer
456 (SSL) as implemented by Network Security Services (NSS)
457 for network security. NSS is also used
458 for the generation and management of certificates. The related
459 certificate databases must be protected in order to maintain the security of
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.
467 Important files and their corresponding paths can be located in the
468 stappaths (7) manual page.
473 .IR stapprobes (3stap),
474 .IR stapfuncs (3stap),
482 Use the Bugzilla link of the project web page or our mailing list.
484 .BR http://sourceware.org/systemtap/ ", " <systemtap@sourceware.org> .