1STAP-SERVER(8)              System Manager's Manual             STAP-SERVER(8)
2
3
4

NAME

6       stap-server - systemtap compile server management
7
8
9

SYNOPSIS

11       [  service  ]  stap-server  {  start  |  stop | restart | condrestart |
12       try-restart | force-reload | status } [ options ]
13
14

DESCRIPTION

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
21
22       The stap-server script aims to provide:
23
24       ·   management of systemtap compile servers as a service.
25
26       ·   convenient  control over configured servers and individual (ad-hoc)
27           servers.
28
29

ARGUMENTS

31       One of the actions below must be specified:
32
33       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
40
41       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
46
47       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
53
54       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
61
62       try-restart
63              This action is identical to condrestart.
64
65
66       force-reload
67              Stop  all  running  servers, reload config files and restart the
68              service as if start was specified.
69
70
71       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
75

OPTIONS

77       The following options are used to provide additional configuration  and
78       to specify servers to be managed:
79
80
81       -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
88
89       -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
95
96       -r kernel-release
97              This option specifies the target kernel release  of  the  server
98              and  is analogous to the -r option of stap. See the stap(1) man‐
99              ual page for more details.  The default release is that  of  the
100              currently running kernel.
101
102
103       -I path
104              This  option  specifies an additional path to be searched by the
105              server(s) for tapsets and is analogous to the -I option of stap.
106              See the stap(1) manual page for more details.
107
108
109       -R path
110              This  option  specifies the location of the systemtap runtime to
111              be used by the server(s) and is analogous to the  -R  option  of
112              stap.  See the stap(1) manual page for more details.
113
114
115       -B options
116              This option specifies options to be passed to make when building
117              systemtap modules and is analogous to the  -B  option  of  stap.
118              See the stap(1) manual page for more details.
119
120
121       -i     This  option  is  a shortcut which specifies one server for each
122              kernel release installed in /lib/modules/. Previous -I,  -R,  -B
123              and  -u options will be applied to each server, however previous
124              -a options will be ignored and the default architecture will  be
125              used.
126
127
128       -n nickname
129              This  option  allows the specification of a server configuration
130              by nickname.  When -n is specified, a currently  running  server
131              with  the  given  nickname will be searched for. If no currently
132              running server with the given nickname is found, a  server  con‐
133              figuration  with  the given nickname will be searched for in the
134              configuration files for default servers, or the path  configured
135              in the global configuration file or the configuration file spec‐
136              ified by the -c option. If a server configuration for the  given
137              nickname  is  found,  the  -a, -r, -I, -R, -B and -u options for
138              that server will be used as if they were specified on  the  com‐
139              mand line. If no configuration with the given nickname is found,
140              and the action is start (or an action behaving like  start  (see
141              ARGUMENTS),  the server will be started with the given nickname.
142              If no configuration with the given nickname is  found,  and  the
143              action is not start (or an action behaving like start), it is an
144              error. If a nickname is not specified  for  a  server  which  is
145              being started, its nickname will be its process id.
146
147
148       -p pid This  option  allows the specification of a server configuration
149              by process id.  When -p is specified, a currently running server
150              with  the  given  process  id  will  be searched for. If no such
151              server is found, it is an error. If  a  server  with  the  given
152              process  id  is found, the -a, -r, -I, -R, -B and -u options for
153              that server will be used as if they were specified on  the  com‐
154              mand line.
155
156
157       -u user-name
158              Each  systemtap  compile server is normally run by the user name
159              stap-server  (for  the  initscript)  or  as  the  user  invoking
160              stap-server,  unless  otherwise  configured  (see  FILES).  This
161              option specifies the user name used to run  the  server(s).  The
162              user name specified must be a member of the group stap-server.
163
164
165       --log logfile
166              This  option allows the specification of a separate log file for
167              each server.  Each --log option is added to a list which will be
168              applied,  in turn, to each server specified. If more servers are
169              specified than --log options, the default log file  (see  FILES)
170              will be used for subsequent servers.
171
172
173       --port port-number
174              This  option allows the specification of a specific network port
175              for each server. Each --port option is added  to  a  list  which
176              will  be  applied,  in  turn,  to each server specified. If more
177              servers are specified than --port options, a  randomly  selected
178              port is used for subsequent servers.
179
180
181       --ssl certificate-db-path
182              This  option allows the specification of a separate NSS certifi‐
183              cate database for each server. Each --ssl option is added  to  a
184              list  which  will be applied, in turn, to each server specified.
185              If more servers are specified than --ssl  options,  the  default
186              certificate database (see FILES) for subsequent servers.
187
188
189       --max-threads threads
190              This  option  allows  the specification of the maximum number of
191              worker threads to handle concurrent requests. If threads  ==  0,
192              each  request will be handled on the main thread, serially.  The
193              default is the number of available processor cores.
194
195

CONFIGURATION

197       Configuration files allow us to:
198
199       ·   specify  global  configuration  of  logging,  server  configuration
200           files, status files and other global parameters.
201
202       ·   specify which servers are to be started by default.
203
204

Global Configuration

206       The  Global  Configuration  file  contains variable assignments used to
207       configure the overall operation of the service.   Each  line  beginning
208       with  a  '#'  character is ignored. All other lines must be of the form
209       VARIABLE=VALUE. This is not a shell script. The entire contents of  the
210       line after the = will be assigned as-is to the variable.
211
212       The following variables may be assigned:
213
214
215       CONFIG_PATH
216              Specifies  the  absolute  path  of  the directory containing the
217              default server configurations.
218
219
220       STAT_PATH
221              Specifies the absolute path of the running server status  direc‐
222              tory.
223
224
225       LOG_FILE
226              Specifies the absolute path of the log file.
227
228
229       STAP_USER
230              Specifies  the  userid  which  will be used to run the server(s)
231              (default: for the initscript  stap-server,  otherwise  the  user
232              running stap-server).
233
234
235       Here is an example of a Global Configuration file:
236
237              CONFIG_PATH=~<user>/my-stap-server-configs
238              LOG_FILE=/tmp/stap-server/log
239
240
241

Individual Server Configuration

243       Each  server  configuration file configures a server to be started when
244       no server is specified for the start action, or an action behaving like
245       the  start  action  (see  ARGUMENTS).  Each configuration file contains
246       variable assignments used to configure an individual server.
247
248       Each line beginning with a '#' character is ignored.  All  other  lines
249       must be of the form VARIABLE=VALUE. This is not a shell script. The en‐
250       tire contents of the line after the = will be  assigned  as-is  to  the
251       variable.
252
253       Each configuration file must have a filename suffix of .conf. See stap‐
254       paths(7) for the default location of these files.  This  default  loca‐
255       tion  can  be  overridden in the global configuration file using the -c
256       option (see OPTIONS).
257
258       The following variables may be assigned:
259
260       ARCH   Specifies the target architecture for  this  server  and  corre‐
261              sponds  to  the -a option (see OPTIONS). If ARCH is not set, the
262              architecture of the host will be used.
263
264
265       RELEASE
266              Specifies the kernel release for this server and corresponds  to
267              the  -r option (see OPTIONS). If RELEASE is not set, the release
268              of the kernel running on the host will be used.
269
270
271       BUILD  Specifies options to be passed to the make process used by  sys‐
272              temtap  to  build  kernel  modules.  This an array variable with
273              each element corresponding to a -B option (see  OPTIONS).  Using
274              the  form  BUILD=STRING clears the array and sets the first ele‐
275              ment to STRING. Using the form BUILD+=STRING adds STRING  as  an
276              additional element to the array.
277
278
279       INCLUDE
280              Specifies a list of directories to be searched by the server for
281              tapsets.  This is an array variable  with  each  element  corre‐
282              sponding  to  a  -I  option  (see  OPTIONS).  Using the form IN‐
283              CLUDE=PATH clears the array and sets the first element to  PATH.
284              Using  the form INCLUDE+=PATH adds PATH as an additional element
285              to the array.
286
287
288       RUNTIME
289              Specifies the directory which  contains  the  systemtap  runtime
290              code  to be used by this server and corresponds to the -R option
291              (see OPTIONS).
292
293
294       USER   Specifies the user name to be used to run this server and corre‐
295              sponds to the -u option (see OPTIONS).
296
297
298       NICKNAME
299              Specifies  the  nickname  to be used to refer to this server and
300              corresponds to the -n option (see OPTIONS).
301
302
303       LOG    Specifies the location of the log file to be used by this server
304              and corresponds to the --log option (see OPTIONS).
305
306
307       PORT   Specifies  the network port to be used by this server and corre‐
308              sponds to the --port option (see OPTIONS).
309
310
311       SSL    Specifies the location of the NSS  certificate  database  to  be
312              used by this server and corresponds to the --ssl option (see OP‐
313              TIONS).
314
315
316       MAXTHREADS
317              Specifies the maximum number of worker threads to handle concur‐
318              rent  requests  to be used by this server and corresponds to the
319              --max-threads option (see OPTIONS).
320
321
322       Here is an example of a server configuration file:
323
324              ARCH=
325              USER=
326              RELEASE=
327              NICKNAME=native
328
329       By keeping the ARCH, USER, and RELEASE fields blank, they will  default
330       to the current arch and release and use the default user.
331
332       A more specific example:
333
334              ARCH=i386
335              RELEASE=2.6.18-128.el5
336              PORT=5001
337              LOG=/path/to/log/file
338
339
340       And here is a more complicated example:
341
342              USER=serveruser
343              RELEASE=/kernels/2.6.18-92.1.18.el5/build
344              INCLUDE=/mytapsets
345              INCLUDE+=/yourtapsets
346              BUILD='VARIABLE1=VALUE1 VARIABLE2=VALUE2'
347              DEFINE=STP_MAXMEMORY=1024
348              DEFINE+=DEBUG_TRANS
349              RUNTIME=/myruntime
350              NICKNAME=my-server
351              SSL=/path/to/NSS/certificate/database
352
353
354

SERVER AUTHENTICATION

356       The security of the SSL network connection between the client and serv‐
357       er depends on the proper management of server certificates.
358
359
360       The trustworthiness of a given systemtap compile server can not be  de‐
361       termined  automatically without a trusted certificate authority issuing
362       systemtap compile server certificates. This is not practical in  every‐
363       day  use  and  so,  clients must authenticate servers against their own
364       database of trusted server certificates. In this context,  establishing
365       a  given server as trusted by a given client means adding that server's
366       certificate to the client's database of trusted servers.
367
368
369       For the stap-server initscript, on the local host, this is handled  au‐
370       tomatically.  When the systemtap-server package is installed, the serv‐
371       er's certificate for the default user  (stap-server)  is  automatically
372       generated  and  installed.  This  means  that  servers  started  by the
373       stap-server initscript, with the default user, are automatically trust‐
374       ed by clients on the local host, both as an SSL peer and as a systemtap
375       module signer.
376
377       Furthermore, when stap is invoked by an unprivileged  user  (not  root,
378       not  a  member  of the group stapdev, but a member of the group stapusr
379       and possibly the group stapsys), the options --use-server and  --privi‐
380       lege are automatically added to the specified options.  This means that
381       unprivileged users on the local host can use a server on the local host
382       in  unprivileged mode with no further setup or options required. Normal
383       users (those in none of the SystemTap groups)  can  also  use  compile-
384       servers through the --use-server and --privilege options. But they will
385       of course be unable to load the module (the -p4 option can be  used  to
386       stop short of loading).
387
388
389       In  order  to  use a server running on another host, that server's cer‐
390       tificate  must  be  installed  on   the   client's   host.    See   the
391       --trust-servers  option in the stap(1) manual page for more details and
392       README.unprivileged in the systemtap sources for more details.
393
394

EXAMPLES

396       See the stapex(3stap) manual page for a collection of sample  systemtap
397       scripts.
398
399       To  start  the  configured  servers, or the default server, if none are
400       configured:
401
402        $ [ service ] stap-server start
403
404       To start a server for each kernel installed in /lib/modules:
405
406        $ [ service ] stap-server start -i
407
408       To obtain information about the running server(s):
409
410        $ [ service ] stap-server status
411
412       To start a server like another one, except targeting a different archi‐
413       tecture, by referencing the first server's nickname:
414
415        $ [ service ] stap-server start -n NICKNAME -a ARCH
416
417       To start a server for a kernel release not installed (cross-compiling)
418
419        $ [ service ] stap-server start -a ARCH -r /BUILDDIR
420
421       To  stop  one of the servers by referencing its process id (obtained by
422       running stap-server status):
423
424        $ [ service ] stap-server stop -p PID
425
426       To run a script using a compile server:
427
428        $ stap SCRIPT --use-server
429
430       To run a script as an unprivileged user using a compile server:
431
432        $ stap SCRIPT
433
434       To stop all running servers:
435
436        $ [ service ] stap-server stop
437
438       To restart servers after a global configuration change and/or when  de‐
439       fault servers have been added, changed, or removed:
440
441        $ [ service ] stap-server force-reload
442
443

SAFETY AND SECURITY

445       Systemtap  is  an administrative tool.  It exposes kernel internal data
446       structures and potentially private user information.  See  the  stap(1)
447       manual page for additional information on safety and security.
448
449
450       As a network server, stap-server should be activated with care in order
451       to limit the potential effects of bugs or mischevious users.   Consider
452       the following prophylactic measures.
453
454       1      Run stap-server as an unprivileged user, never as root.
455
456              When  invoked  as a service (i.e. service stap-server ...), each
457              server is run, by default, as the user  stap-server.   When  in‐
458              voked  directly  (i.e.  stap-server ...), each server is run, by
459              default, as the invoking user. In each case, another user may be
460              selected  by  using  the  -u option on invocation, by specifying
461              STAP_USER=username in the global configuration file or by speci‐
462              fying  USER=username in an individual server configuration file.
463              The invoking user must have authority to run processes as anoth‐
464              er user.  See CONFIGURATION.
465
466              The selected user must have write access to the server log file.
467              The location of the server log file may be  changed  by  setting
468              LOG_FILE=path  in the global configuration file.  See CONFIGURA‐
469              TION.
470
471              The selected user must have read/write access to  the  directory
472              containing  the server status files.  The location of the server
473              status files may be changed by  setting  STAT_PATH=path  in  the
474              global configuration file.  See CONFIGURATION.
475
476              The  selected user must have read/write access to the uprobes.ko
477              build directory and its files.
478
479              Neither form of stap-server will run if  the  selected  user  is
480              root.
481
482
483       2      Run  stap-server requests with resource limits that impose maxi‐
484              mum cpu time, file size, memory consumption, in order  to  bound
485              the effects of processing excessively large or bogus inputs.
486
487              When the user running the server is stap-server, each server re‐
488              quest is run with limits specified in ~stap-server/.systemtap/rc
489              otherwise, no limits are imposed.
490
491
492       3      Run  stap-server  with a TMPDIR environment variable that points
493              to a separate and/or quota-enforced directory, in order to  pre‐
494              vent filling up of important filesystems.
495
496              The default TMPDIR is /tmp/.
497
498
499       4      Activate  network  firewalls to limit stap client connections to
500              relatively trustworthy networks.
501
502              For automatic selection of servers by clients, avahi must be in‐
503              stalled  on  both  the server and client hosts and mDNS messages
504              must be allowed through the firewall.
505
506
507       The systemtap compile server and its related utilities use  the  Secure
508       Socket  Layer  (SSL)  as implemented by Network Security Services (NSS)
509       for network security. NSS is also used for the generation  and  manage‐
510       ment  of  certificates.  The related certificate databases must be pro‐
511       tected in order to maintain the security of the  system.   Use  of  the
512       utilities  provided  will  help to ensure that the proper protection is
513       maintained. The systemtap client will check for proper  access  permis‐
514       sions before making use of any certificate database.
515
516

FILES

518       Important files and their corresponding paths can be located in the
519              stappaths (7) manual page.
520
521

SEE ALSO

523       stap(1),
524       staprun(8),
525       stapprobes(3stap),
526       stappaths(7),
527       stapex(3stap),
528       avahi,
529       ulimit(1),
530       NSS
531
532

BUGS

534       Use  the  Bugzilla  link  of  the project web page or our mailing list.
535       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
536
537
538
539
540                                                                STAP-SERVER(8)
Impressum