1STAP-SERVER(8) System Manager's Manual STAP-SERVER(8)
2
6 stap-server - systemtap compile server management
7
10 [ service ] stap-server { start | stop | restart | condrestart |
11 try-restart | force-reload | status } [ options ]
12
15 A systemtap compile server listens for connections from stap clients on
16 a secure SSL network port and accepts requests to run the stap front
17 end. Each server advertises its presence and configuration on the local
18 network using mDNS (avahi) allowing for automatic detection by clients.
19 The stap-server script aims to provide:
22 · management of systemtap compile servers as a service.
24 · convenient control over configured servers and individual (ad-hoc)
26 servers.
27
30 One of the actions below must be specified:
31 start Start servers. The specified servers are started. If no server
33 is specified, the configured servers are started. If no servers
34 are configured, a server for the kernel release and architecture
35 of the host is started. If a specified server is already
36 started, this action will be ignored for that server. If a
37 server fails to start, this action fails.
38 stop Stop server(s). The specified servers are stopped. If no server
41 is specified, all currently running servers are stopped. If a
42 specified server is not running, this action will be successful
43 for that server. If a server fails to stop, this action fails.
44 restart
47 Stop and restart servers. The specified servers are stopped and
48 restarted. If no server is specified, all currently running
49 servers are stopped and restarted. If no servers are running,
50 this action behaves like start.
51 condrestart
54 Stop and restart servers. The specified servers are stopped and
55 restarted. If a specified server is not running, it is not
56 started. If no server is specified, all currently running
57 servers are stopped and restarted. If no servers are running,
58 none will be started.
59 try-restart
62 This action is identical to condrestart.
63 force-reload
66 Stop all running servers, reload config files and restart the
67 service as if start was specified.
68 status Print information about running servers. Information about the
71 specified server(s) will be printed. If no server is specified,
72 information about all running servers will be printed.
73
76 The following options are used to provide additional configuration and
77 to specify servers to be managed:
78 -c configfile
81 This option specifies a global configuration file in addition to
82 the default global configuration file described below. This file
83 will be processed after the default global configuration file.
84 If the -c option is specified more than once, the last configu‐
85 ration file specified will be used.
86 -a architecture
89 This option specifies the target architecture of the server and
90 is analogous to the -a option of stap. See the stap(1) manual
91 page for more details. The default architecture is the archi‐
92 tecture of the host.
93 -r kernel-release
96 This option specifies the target kernel release of the server
97 and is analogous to the -r option of stap. See the stap(1) man‐
98 ual page for more details. The default release is that of the
99 currently running kernel.
100 -I path
103 This option specifies an additional path to be searched by the
104 server(s) for tapsets and is analogous to the -I option of stap.
105 See the stap(1) manual page for more details.
106 -R path
109 This option specifies the location of the systemtap runtime to
110 be used by the server(s) and is analogous to the -R option of
111 stap. See the stap(1) manual page for more details.
112 -B options
115 This option specifies options to be passed to make when building
116 systemtap modules and is analogous to the -B option of stap.
117 See the stap(1) manual page for more details.
118 -i This option is a shortcut which specifies one server for each
121 kernel release installed in /lib/modules/. Previous -I, -R, -B
122 and -u options will be applied to each server, however previous
123 -a options will be ignored and the default architecture will be
124 used.
125 -n nickname
128 This option allows the specification of a server configuration
129 by nickname. When -n is specified, a currently running server
130 with the given nickname will be searched for. If no currently
131 running server with the given nickname is found, a server con‐
132 figuration with the given nickname will be searched for in the
133 configuration files for default servers, or the path configured
134 in the global configuration file or the configuration file spec‐
135 ified by the -c option. If a server configuration for the given
136 nickname is found, the -a, -r, -I, -R, -B and -u options for
137 that server will be used as if they were specified on the com‐
138 mand line. If no configuration with the given nickname is found,
139 and the action is start (or an action behaving like start (see
140 ARGUMENTS), the server will be started with the given nickname.
141 If no configuration with the given nickname is found, and the
142 action is not start (or an action behaving like start), it is an
143 error. If a nickname is not specified for a server which is
144 being started, its nickname will be its process id.
145 -p pid This option allows the specification of a server configuration
148 by process id. When -p is specified, a currently running server
149 with the given process id will be searched for. If no such
150 server is found, it is an error. If a server with the given
151 procss id is found, the -a, -r, -I, -R, -B and -u options for
152 that server will be used as if they were specified on the com‐
153 mand line.
154 -u user-name
157 Each systemtap compile server is normally run by the user name
158 stap-server (for the initscript) or as the user invoking
159 stap-server, unless otherwise configured (see FILES). This
160 option specifies the user name used to run the server(s). The
161 user name specified must be a member of the group stap-server.
162
165 Configuration files allow us to:
166 · specify global configuration of logging, server configuration
168 files, status files and other global parameters.
169 · specify which servers are to be started by default.
171
174 The Global Configuration file contains variable assignments used to
175 configure the overall operation of the service. Each line beginning
176 with a '#' character is ignored. All other lines must be of the form
177 VARIABLE=VALUE. This is not a shell script. The entire contents of the
178 line after the = will be assigned as-is to the variable.
179 The following variables may be assigned:
181 CONFIG_PATH
184 Specifies the absolute path of the directory containing the
185 default server configurations.
186 STAT_PATH
189 Specifies the absolute path of the running server status direc‐
190 tory.
191 LOG_FILE
194 Specifies the absolute path of the log file.
195 STAP_USER
198 Specifies the userid which will be used to run the server(s)
199 (default: for the initscript stap-server, otherwise the user
200 running stap-server).
201
204 Each server configuration file configures a server to be started when
205 no server is specified for the start action, or an action behaving like
206 the start action (see ARGUMENTS). Each configuration file contains
207 variable assignments used to configure an individual server.
208 Each line beginning with a '#' character is ignored. All other lines
210 must be of the form VARIABLE=VALUE. This is not a shell script. The
211 entire contents of the line after the = will be assigned as-is to the
212 variable.
213 Each configuration file must have a filename suffix of .conf. The
215 default location of these files can be overridden in the global config‐
216 uration file using the -c option (see OPTIONS).
217 The following variables may be assigned:
219 ARCH Specifies the target architecture for this server and corre‐
221 sponds to the -a option (see OPTIONS). If ARCH is not set, the
222 architecture of the host will be used.
223 RELEASE
226 Specifies the kernel release for this server and corresponds to
227 the -r option (see OPTIONS). If RELEASE is not set, the release
228 of the kernel running on the host will be used.
229 BUILD Specifies options to be passed to the make process used by sys‐
232 temtap to build kernel modules. This an array variable with
233 each element corresponding to a -B option (see OPTIONS). Using
234 the form BUILD=STRING clears the array and sets the first ele‐
235 ment to STRING. Using the form BUILD+=STRING adds STRING as an
236 additional element to the array.
237 INCLUDE
240 Specifies a list of directories to be searched by the server for
241 tapsets. This an array variable with each element corresponding
242 to an -I option (see OPTIONS). Using the form INCLUDE=PATH
243 clears the array and sets the first element to PATH. Using the
244 form INCLUDE+=PATH adds PATH as an additional element to the
245 array.
246 RUNTIME
249 Specifies the directory which contains the systemtap runtime
250 code to be used by this server and corresponds to the -R option
251 (see OPTIONS).
252 USER Specifies the user name to be used to run this server and corre‐
255 sponds to the -u option (see OPTIONS).
256 NICKNAME
259 Specifies the nickname to be used to refer to this server and
260 corresponds to the -n option (see OPTIONS).
261
264 The security of the SSL network connection between the client and
265 server depends on the proper management of server certificates.
266 The trustworthiness of a given systemtap compile server can not be
269 determined automatically without a trusted certificate authority issu‐
270 ing systemtap compile server certificates. This is not practical in
271 everyday use and so, clients must authenticate servers against their
272 own database of trusted server certificates. In this context, estab‐
273 lishing a given server as trusted by a given client means adding that
274 server's certificate to the client's database of trusted servers.
275 For the stap-server initscript, on the local host, this is handled
278 automatically. When the systemtap-server package is installed, the
279 server's certificate for the default user (stap-server) is automati‐
280 cally generated and installed. This means that servers started by the
281 stap-server initscript, with the default user, are automatically
282 trusted by clients on the local host, both as an SSL peer and as a sys‐
283 temtap module signer. Furthermore, when stap is invoked by an unprivi‐
284 leged user (not root, not a member of the group stapdev, but a member
285 of the group stapusr), the options --use-server and --unprivileged are
286 automatically added to the specified options. This means that unprivi‐
287 leged users on the local host can use a server on the local host in
288 unprivileged mode with no further setup or options required.
289 In order to use a server running on another host, that server's cer‐
292 tificate must be installed on the client's host. See the
293 --trust-servers option in the stap(1) manual page for more details and
294 README.unprivileged in the systemtap sources for more details..
295
298 See the stapex(3stap) manual page for a collection of sample systemtap
299 scripts.
300 To start the configured servers, or the default server, if none are
302 configured:
303 $ [ service ] stap-server start
305 To start a server for each kernel installed in /lib/modules:
307 $ [ service ] stap-server start -i
309 To obtain information about the running server(s):
311 $ [ service ] stap-server status
313 To start a server like another one, except targeting a different archi‐
315 tecture, by referencing the first server's nickname:
316 $ [ service ] stap-server start -n NICKNAME -a ARCH
318 To stop one of the servers by referencing its process id (obtained by
320 running stap-server status):
321 $ [ service ] stap-server stop -p PID
323 To run a script using a compile server:
325 $ stap SCRIPT --use-server
327 To run a script as an unprivileged user using a compile server:
329 $ stap SCRIPT
331 To stop all running servers:
333 $ [ service ] stap-server stop
335
338 Systemtap is an administrative tool. It exposes kernel internal data
339 structures and potentially private user information. See the stap(1)
340 manual page for additional information on safety and security.
341 As a network server, stap-server should be activated with care in order
344 to limit the potential effects of bugs or mischevious users. Consider
345 the following prophylactic measures.
346 1 Run stap-server as an unprivileged user, never as root.
348 When invoked as a service (i.e. service stap-server ...), each
350 server is run, by default, as the user stap-server. When
351 invoked directly (i.e. stap-server ...), each server is run, by
352 default, as the invoking user. In each case, another user may be
353 selected by using the -u option on invocation, by specifying
354 STAP_USER=username in the global configuration file or by speci‐
355 fying USER=username in an individual server configuration file.
356 The invoking user must have authority to run processes as
357 another user. See CONFIGURATION.
358 The selected user must have write access to the server log file.
360 The location of the server log file may be changed by setting
361 LOG_FILE=path in the global configuration file. See CONFIGURA‐
362 TION.
363 The selected user must have read/write access to the directory
365 containing the server status files. The location of the server
366 status files may be changed by setting STAT_PATH=path in the
367 global configuration file. See CONFIGURATION.
368 The selected user must have read/write access to the uprobes.ko
370 build directory and its files.
371 Neither form of stap-server will run if the selected user is
373 root.
374 2 Run stap-server with resource limits that impose maximum cpu
377 time, file size, memory consumption, in order to bound the
378 effects of processing excessively large or bogus inputs.
379 When the user running the servers is stap-server, each server is
381 run with limits equivalent to
382 ulimit -f 50000 -s 1000 -t 60 -u 20 -v 500000
384 otherwise, no limits are imposed.
386 3 Run stap-server with a TMPDIR environment variable that points
389 to a separate and/or quota-enforced directory, in order to pre‐
390 vent filling up of important filesystems.
391 The default TMPDIR is /tmp/.
393 4 Activate network firewalls to limit stap client connections to
396 relatively trustworthy networks.
397 For automatic selection of servers by clients, avahi must be
399 installed on both the server and client hosts and mDNS messages
400 must be allowed through the firewall.
401 The systemtap compile server and its related utilities use the Secure
404 Socket Layer (SSL) as implemented by Network Security Services (NSS)
405 for network security. NSS is also used for the generation and manage‐
406 ment of certificates. The related certificate databases must be pro‐
407 tected in order to maintain the security of the system. Use of the
408 utilities provided will help to ensure that the proper protection is
409 maintained. The systemtap client will check for proper access permis‐
410 sions before making use of any certificate database.
411
414 Important files and their corresponding paths can be located in the
415 stappaths (7) manual page.
416
419 stap(1), staprun(8), stapprobes(3stap), stapfuncs(3stap), stappaths(7),
420 stapex(3stap), avahi, ulimit(1), NSS
421
424 Use the Bugzilla link of the project web page or our mailing list.
425 http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
426 STAP-SERVER(8)