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 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
103
104       -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
109
110       -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
115
116       -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
121
122       -i     This option is a shortcut which specifies a server that  handles
123              every release installed in /lib/modules/.
124
125       -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
144
145       -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
153
154       -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
161
162       --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
169
170       --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
177
178       --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
185
186       --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
192
193       --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
198
199       --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
204

CONFIGURATION

206       Configuration files allow us to:
207
208       ·   specify  global  configuration  of  logging,  server  configuration
209           files, status files and other global parameters.
210
211       ·   specify which servers are to be started by default.
212
213

Global Configuration

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
221       The following variables may be assigned:
222
223
224       CONFIG_PATH
225              Specifies  the  absolute  path  of  the directory containing the
226              default server configurations.
227
228
229       STAT_PATH
230              Specifies the absolute path of the running server status  direc‐
231              tory.
232
233
234       LOG_FILE
235              Specifies the absolute path of the log file.
236
237
238       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
243
244       Here is an example of a Global Configuration file:
245
246              CONFIG_PATH=~<user>/my-stap-server-configs
247              LOG_FILE=/tmp/stap-server/log
248
249
250

Individual Server Configuration

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
257       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
262       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
267       The following variables may be assigned:
268
269       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
273
274       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
279
280       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
287
288       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
296
297       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
302
303       USER   Specifies the user name to be used to run this server and corre‐
304              sponds to the -u option (see OPTIONS).
305
306
307       NICKNAME
308              Specifies  the  nickname  to be used to refer to this server and
309              corresponds to the -n option (see OPTIONS).
310
311
312       LOG    Specifies the location of the log file to be used by this server
313              and corresponds to the --log option (see OPTIONS).
314
315
316       PORT   Specifies  the network port to be used by this server and corre‐
317              sponds to the --port option (see OPTIONS).
318
319
320       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
324
325       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
330
331       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
336
337       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
342
343       Here is an example of a server configuration file:
344
345              ARCH=
346              USER=
347              RELEASE=
348              NICKNAME=native
349
350       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
353       A more specific example:
354
355              ARCH=i386
356              RELEASE=2.6.18-128.el5
357              PORT=5001
358              LOG=/path/to/log/file
359
360
361       And here is a more complicated example:
362
363              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
374
375

SERVER AUTHENTICATION

377       The security of the SSL network connection between the client and serv‐
378       er depends on the proper management of server certificates.
379
380
381       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
389
390       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
398       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
409
410       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
415

EXAMPLES

417       See the stapex(3stap) manual page for a collection of sample  systemtap
418       scripts.
419
420       To  start  the  configured  servers, or the default server, if none are
421       configured:
422
423        $ [ service ] stap-server start
424
425       To start a  server  that  handles  all  kernel  versions  installed  in
426       /lib/modules:
427
428        $ [ service ] stap-server start -i
429
430       To obtain information about the running server(s):
431
432        $ [ service ] stap-server status
433
434       To start a server like another one, except targeting a different archi‐
435       tecture, by referencing the first server's nickname:
436
437        $ [ service ] stap-server start -n NICKNAME -a ARCH
438
439       To start a server for a kernel release not installed (cross-compiling)
440
441        $ [ service ] stap-server start -a ARCH -r /BUILDDIR
442
443       To stop one of the servers by referencing its process id  (obtained  by
444       running stap-server status):
445
446        $ [ service ] stap-server stop -p PID
447
448       To run a script using a compile server:
449
450        $ stap SCRIPT --use-server
451
452       To run a script as an unprivileged user using a compile server:
453
454        $ stap SCRIPT
455
456       To stop all running servers:
457
458        $ [ service ] stap-server stop
459
460       To  restart servers after a global configuration change and/or when de‐
461       fault servers have been added, changed, or removed:
462
463        $ [ service ] stap-server force-reload
464
465

SAFETY AND SECURITY

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
471
472       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
476       1      Run stap-server as an unprivileged user, never as root.
477
478              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
488              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
493              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
498              The selected user must have read/write access to the  uprobes.ko
499              build directory and its files.
500
501              Neither  form  of  stap-server  will run if the selected user is
502              root.
503
504
505       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
509              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
513
514       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
518              The default TMPDIR is /tmp/.
519
520
521       4      Activate network firewalls to limit stap client  connections  to
522              relatively trustworthy networks.
523
524              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
528
529       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
538

FILES

540       Important files and their corresponding paths can be located in the
541              stappaths (7) manual page.
542
543

SEE ALSO

545       stap(1),
546       staprun(8),
547       stapprobes(3stap),
548       stappaths(7),
549       stapex(3stap),
550       avahi,
551       ulimit(1),
552       NSS
553
554

BUGS

556       Use the Bugzilla link of the project web  page  or  our  mailing  list.
557       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
558
559
560
561
562                                                                STAP-SERVER(8)
Impressum