1STAP-SERVER(8) System Manager's Manual STAP-SERVER(8)
2
6 stap-server - systemtap compile server management
7
11 [ service ] stap-server { start | stop | restart | condrestart |
12 try-restart | force-reload | status } [ options ]
13
16 A systemtap compile server listens for connections from stap clients on
17 a secure SSL network port and accepts requests to run the stap front
18 end. Each server advertises its presence and configuration on the local
19 network using mDNS (avahi) allowing for automatic detection by clients.
20 The stap-server script aims to provide:
23 · management of systemtap compile servers as a service.
25 · convenient control over configured servers and individual (ad-hoc)
27 servers.
28
31 One of the actions below must be specified:
32 start Start servers. The specified servers are started. If no server
34 is specified, the configured servers are started. If no servers
35 are configured, a server for the kernel release and architecture
36 of the host is started. If a specified server is already
37 started, this action will be ignored for that server. If a
38 server fails to start, this action fails.
39 stop Stop server(s). The specified servers are stopped. If no server
42 is specified, all currently running servers are stopped. If a
43 specified server is not running, this action will be successful
44 for that server. If a server fails to stop, this action fails.
45 restart
48 Stop and restart servers. The specified servers are stopped and
49 restarted. If no server is specified, all currently running
50 servers are stopped and restarted. If no servers are running,
51 this action behaves like start.
52 condrestart
55 Stop and restart servers. The specified servers are stopped and
56 restarted. If a specified server is not running, it is not
57 started. If no server is specified, all currently running
58 servers are stopped and restarted. If no servers are running,
59 none will be started.
60 try-restart
63 This action is identical to condrestart.
64 force-reload
67 Stop all running servers, reload config files and restart the
68 service as if start was specified.
69 status Print information about running servers. Information about the
72 specified server(s) will be printed. If no server is specified,
73 information about all running servers will be printed.
74
77 The following options are used to provide additional configuration and
78 to specify servers to be managed:
79 -c configfile
82 This option specifies a global configuration file in addition to
83 the default global configuration file described below. This file
84 will be processed after the default global configuration file.
85 If the -c option is specified more than once, the last configu‐
86 ration file specified will be used.
87 -a architecture
90 This option specifies the target architecture of the server and
91 is analogous to the -a option of stap. See the stap(1) manual
92 page for more details. The default architecture is the archi‐
93 tecture of the host.
94 -r kernel-release
97 This option specifies a target kernel release of the server and
98 is analogous to the -r option of stap. See the stap(1) manual
99 page for more details. The default release is that of the cur‐
100 rently running kernel. A server can handle multiple releases by
101 specifying multiple -r flags.
102 -I path
105 This option specifies an additional path to be searched by the
106 server(s) for tapsets and is analogous to the -I option of stap.
107 See the stap(1) manual page for more details.
108 -R path
111 This option specifies the location of the systemtap runtime to
112 be used by the server(s) and is analogous to the -R option of
113 stap. See the stap(1) manual page for more details.
114 -B options
117 This option specifies options to be passed to make when building
118 systemtap modules and is analogous to the -B option of stap.
119 See the stap(1) manual page for more details.
120 -i This option is a shortcut which specifies a server that handles
123 every release installed in /lib/modules/.
124 -n nickname
126 This option allows the specification of a server configuration
127 by nickname. When -n is specified, a currently running server
128 with the given nickname will be searched for. If no currently
129 running server with the given nickname is found, a server con‐
130 figuration with the given nickname will be searched for in the
131 configuration files for default servers, or the path configured
132 in the global configuration file or the configuration file spec‐
133 ified by the -c option. If a server configuration for the given
134 nickname is found, the -a, -r, -I, -R, -B and -u options for
135 that server will be used as if they were specified on the com‐
136 mand line. If no configuration with the given nickname is found,
137 and the action is start (or an action behaving like start (see
138 ARGUMENTS), the server will be started with the given nickname.
139 If no configuration with the given nickname is found, and the
140 action is not start (or an action behaving like start), it is an
141 error. If a nickname is not specified for a server which is
142 being started, its nickname will be its process id.
143 -p pid This option allows the specification of a server configuration
146 by process id. When -p is specified, a currently running server
147 with the given process id will be searched for. If no such
148 server is found, it is an error. If a server with the given
149 process id is found, the -a, -r, -I, -R, -B and -u options for
150 that server will be used as if they were specified on the com‐
151 mand line.
152 -u user-name
155 Each systemtap compile server is normally run by the user name
156 stap-server (for the initscript) or as the user invoking
157 stap-server, unless otherwise configured (see FILES). This
158 option specifies the user name used to run the server(s). The
159 user name specified must be a member of the group stap-server.
160 --log logfile
163 This option allows the specification of a separate log file for
164 each server. Each --log option is added to a list which will be
165 applied, in turn, to each server specified. If more servers are
166 specified than --log options, the default log file (see FILES)
167 will be used for subsequent servers.
168 --port port-number
171 This option allows the specification of a specific network port
172 for each server. Each --port option is added to a list which
173 will be applied, in turn, to each server specified. If more
174 servers are specified than --port options, a randomly selected
175 port is used for subsequent servers.
176 --ssl certificate-db-path
179 This option allows the specification of a separate NSS certifi‐
180 cate database for each server. Each --ssl option is added to a
181 list which will be applied, in turn, to each server specified.
182 If more servers are specified than --ssl options, the default
183 certificate database (see FILES) for subsequent servers.
184 --max-threads threads
187 This option allows the specification of the maximum number of
188 worker threads to handle concurrent requests. If threads == 0,
189 each request will be handled on the main thread, serially. The
190 default is the number of available processor cores.
191 --max-request-size size
194 This options allows the specification of the maximum size of an
195 uncompressed client request. The arguement size is specified in
196 bytes. The default is the 50000 bytes.
197 --max-compressed-request size
200 This options allows the specification of the maximum size of a
201 compressed client request. The arguement size is specified in
202 bytes. The default is the 5000 bytes.
203
206 Configuration files allow us to:
207 · specify global configuration of logging, server configuration
209 files, status files and other global parameters.
210 · specify which servers are to be started by default.
212
215 The Global Configuration file contains variable assignments used to
216 configure the overall operation of the service. Each line beginning
217 with a '#' character is ignored. All other lines must be of the form
218 VARIABLE=VALUE. This is not a shell script. The entire contents of the
219 line after the = will be assigned as-is to the variable.
220 The following variables may be assigned:
222 CONFIG_PATH
225 Specifies the absolute path of the directory containing the
226 default server configurations.
227 STAT_PATH
230 Specifies the absolute path of the running server status direc‐
231 tory.
232 LOG_FILE
235 Specifies the absolute path of the log file.
236 STAP_USER
239 Specifies the userid which will be used to run the server(s)
240 (default: for the initscript stap-server, otherwise the user
241 running stap-server).
242 Here is an example of a Global Configuration file:
245 CONFIG_PATH=~<user>/my-stap-server-configs
247 LOG_FILE=/tmp/stap-server/log
248
252 Each server configuration file configures a server to be started when
253 no server is specified for the start action, or an action behaving like
254 the start action (see ARGUMENTS). Each configuration file contains
255 variable assignments used to configure an individual server.
256 Each line beginning with a '#' character is ignored. All other lines
258 must be of the form VARIABLE=VALUE. This is not a shell script. The en‐
259 tire contents of the line after the = will be assigned as-is to the
260 variable.
261 Each configuration file must have a filename suffix of .conf. See stap‐
263 paths(7) for the default location of these files. This default loca‐
264 tion can be overridden in the global configuration file using the -c
265 option (see OPTIONS).
266 The following variables may be assigned:
268 ARCH Specifies the target architecture for this server and corre‐
270 sponds to the -a option (see OPTIONS). If ARCH is not set, the
271 architecture of the host will be used.
272 RELEASE
275 Specifies a kernel release for this server and corresponds to
276 the -r option (see OPTIONS). If RELEASE is not set, the release
277 of the kernel running on the host will be used.
278 BUILD Specifies options to be passed to the make process used by sys‐
281 temtap to build kernel modules. This an array variable with
282 each element corresponding to a -B option (see OPTIONS). Using
283 the form BUILD=STRING clears the array and sets the first ele‐
284 ment to STRING. Using the form BUILD+=STRING adds STRING as an
285 additional element to the array.
286 INCLUDE
289 Specifies a list of directories to be searched by the server for
290 tapsets. This is an array variable with each element corre‐
291 sponding to a -I option (see OPTIONS). Using the form IN‐
292 CLUDE=PATH clears the array and sets the first element to PATH.
293 Using the form INCLUDE+=PATH adds PATH as an additional element
294 to the array.
295 RUNTIME
298 Specifies the directory which contains the systemtap runtime
299 code to be used by this server and corresponds to the -R option
300 (see OPTIONS).
301 USER Specifies the user name to be used to run this server and corre‐
304 sponds to the -u option (see OPTIONS).
305 NICKNAME
308 Specifies the nickname to be used to refer to this server and
309 corresponds to the -n option (see OPTIONS).
310 LOG Specifies the location of the log file to be used by this server
313 and corresponds to the --log option (see OPTIONS).
314 PORT Specifies the network port to be used by this server and corre‐
317 sponds to the --port option (see OPTIONS).
318 SSL Specifies the location of the NSS certificate database to be
321 used by this server and corresponds to the --ssl option (see OP‐
322 TIONS).
323 MAXTHREADS
326 Specifies the maximum number of worker threads to handle concur‐
327 rent requests to be used by this server and corresponds to the
328 --max-threads option (see OPTIONS).
329 MAXREQSIZE
332 Specifies the maximum size of an uncompressed client request, to
333 be used by this server and correspnds to the --max-request-size
334 option (see OPTIONS).
335 MAXCOMPRESSEDREQ
338 Specifies the maximum size of an compressed client request, to
339 be used by this server and correspnds to the --max-com‐
340 pressed-request option (see OPTIONS).
341 Here is an example of a server configuration file:
344 ARCH=
346 USER=
347 RELEASE=
348 NICKNAME=native
349 By keeping the ARCH, USER, and RELEASE fields blank, they will default
351 to the current arch and release and use the default user.
352 A more specific example:
354 ARCH=i386
356 RELEASE=2.6.18-128.el5
357 PORT=5001
358 LOG=/path/to/log/file
359 And here is a more complicated example:
362 USER=serveruser
364 RELEASE=/kernels/2.6.18-92.1.18.el5/build
365 INCLUDE=/mytapsets
366 INCLUDE+=/yourtapsets
367 BUILD='VARIABLE1=VALUE1 VARIABLE2=VALUE2'
368 DEFINE=STP_MAXMEMORY=1024
369 DEFINE+=DEBUG_TRANS
370 RUNTIME=/myruntime
371 NICKNAME=my-server
372 SSL=/path/to/NSS/certificate/database
373
377 The security of the SSL network connection between the client and serv‐
378 er depends on the proper management of server certificates.
379 The trustworthiness of a given systemtap compile server can not be de‐
382 termined automatically without a trusted certificate authority issuing
383 systemtap compile server certificates. This is not practical in every‐
384 day use and so, clients must authenticate servers against their own
385 database of trusted server certificates. In this context, establishing
386 a given server as trusted by a given client means adding that server's
387 certificate to the client's database of trusted servers.
388 For the stap-server initscript, on the local host, this is handled au‐
391 tomatically. When the systemtap-server package is installed, the serv‐
392 er's certificate for the default user (stap-server) is automatically
393 generated and installed. This means that servers started by the
394 stap-server initscript, with the default user, are automatically trust‐
395 ed by clients on the local host, both as an SSL peer and as a systemtap
396 module signer.
397 Furthermore, when stap is invoked by an unprivileged user (not root,
399 not a member of the group stapdev, but a member of the group stapusr
400 and possibly the group stapsys), the options --use-server and --privi‐
401 lege are automatically added to the specified options. This means that
402 unprivileged users on the local host can use a server on the local host
403 in unprivileged mode with no further setup or options required. Normal
404 users (those in none of the SystemTap groups) can also use compile-
405 servers through the --use-server and --privilege options. But they will
406 of course be unable to load the module (the -p4 option can be used to
407 stop short of loading).
408 In order to use a server running on another host, that server's cer‐
411 tificate must be installed on the client's host. See the
412 --trust-servers option in the stap(1) manual page for more details and
413 README.unprivileged in the systemtap sources for more details.
414
417 See the stapex(3stap) manual page for a collection of sample systemtap
418 scripts.
419 To start the configured servers, or the default server, if none are
421 configured:
422 $ [ service ] stap-server start
424 To start a server that handles all kernel versions installed in
426 /lib/modules:
427 $ [ service ] stap-server start -i
429 To obtain information about the running server(s):
431 $ [ service ] stap-server status
433 To start a server like another one, except targeting a different archi‐
435 tecture, by referencing the first server's nickname:
436 $ [ service ] stap-server start -n NICKNAME -a ARCH
438 To start a server for a kernel release not installed (cross-compiling)
440 $ [ service ] stap-server start -a ARCH -r /BUILDDIR
442 To stop one of the servers by referencing its process id (obtained by
444 running stap-server status):
445 $ [ service ] stap-server stop -p PID
447 To run a script using a compile server:
449 $ stap SCRIPT --use-server
451 To run a script as an unprivileged user using a compile server:
453 $ stap SCRIPT
455 To stop all running servers:
457 $ [ service ] stap-server stop
459 To restart servers after a global configuration change and/or when de‐
461 fault servers have been added, changed, or removed:
462 $ [ service ] stap-server force-reload
464
467 Systemtap is an administrative tool. It exposes kernel internal data
468 structures and potentially private user information. See the stap(1)
469 manual page for additional information on safety and security.
470 As a network server, stap-server should be activated with care in order
473 to limit the potential effects of bugs or mischevious users. Consider
474 the following prophylactic measures.
475 1 Run stap-server as an unprivileged user, never as root.
477 When invoked as a service (i.e. service stap-server ...), each
479 server is run, by default, as the user stap-server. When in‐
480 voked directly (i.e. stap-server ...), each server is run, by
481 default, as the invoking user. In each case, another user may be
482 selected by using the -u option on invocation, by specifying
483 STAP_USER=username in the global configuration file or by speci‐
484 fying USER=username in an individual server configuration file.
485 The invoking user must have authority to run processes as anoth‐
486 er user. See CONFIGURATION.
487 The selected user must have write access to the server log file.
489 The location of the server log file may be changed by setting
490 LOG_FILE=path in the global configuration file. See CONFIGURA‐
491 TION.
492 The selected user must have read/write access to the directory
494 containing the server status files. The location of the server
495 status files may be changed by setting STAT_PATH=path in the
496 global configuration file. See CONFIGURATION.
497 The selected user must have read/write access to the uprobes.ko
499 build directory and its files.
500 Neither form of stap-server will run if the selected user is
502 root.
503 2 Run stap-server requests with resource limits that impose maxi‐
506 mum cpu time, file size, memory consumption, in order to bound
507 the effects of processing excessively large or bogus inputs.
508 When the user running the server is stap-server, each server re‐
510 quest is run with limits specified in ~stap-server/.systemtap/rc
511 otherwise, no limits are imposed.
512 3 Run stap-server with a TMPDIR environment variable that points
515 to a separate and/or quota-enforced directory, in order to pre‐
516 vent filling up of important filesystems.
517 The default TMPDIR is /tmp/.
519 4 Activate network firewalls to limit stap client connections to
522 relatively trustworthy networks.
523 For automatic selection of servers by clients, avahi must be in‐
525 stalled on both the server and client hosts and mDNS messages
526 must be allowed through the firewall.
527 The systemtap compile server and its related utilities use the Secure
530 Socket Layer (SSL) as implemented by Network Security Services (NSS)
531 for network security. NSS is also used for the generation and manage‐
532 ment of certificates. The related certificate databases must be pro‐
533 tected in order to maintain the security of the system. Use of the
534 utilities provided will help to ensure that the proper protection is
535 maintained. The systemtap client will check for proper access permis‐
536 sions before making use of any certificate database.
537
540 Important files and their corresponding paths can be located in the
541 stappaths (7) manual page.
542
545 stap(1),
546 staprun(8),
547 stapprobes(3stap),
548 stappaths(7),
549 stapex(3stap),
550 avahi,
551 ulimit(1),
552 NSS
553
556 Use the Bugzilla link of the project web page or our mailing list.
557 http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
558 STAP-SERVER(8)