stap-server.8.in

   1 .\" -*- nroff -*-
   2 .TH STAP-SERVER 8
   3 .SH NAME
   4 stap\-server \- systemtap server management
   5
   6 .SH SYNOPSIS
   7
   8 .br
   9 [
  10 .B service
  11 ]
  12 .B stap\-server
  13 {
  14 .B start
  15 |
  16 .B stop
  17 |
  18 .B restart
  19 |
  20 .B condrestart
  21 |
  22 .B try\-restart
  23 |
  24 .B force\-reload
  25 |
  26 .B status
  27 } [
  28 .I options
  29 ]
  30
  31 .SH DESCRIPTION
  32
  33 A systemtap compile server listens for connections from stap clients
  34 on a secure SSL network port and accepts requests to run the
  35 .I stap
  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.
  38
  39 .PP
  40 The stap\-server script aims to provide:
  41 .IP \(bu 4
  42 management of systemtap compile servers as a service.
  43 .IP \(bu 4
  44 convenient control over configured servers and individual (ad\-hoc) servers.
  45
  46 .SH ARGUMENTS
  47 One of the actions below must be specified:
  48 .TP
  49 .B start
  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
  53 is started.
  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.
  57
  58 .TP
  59 .B stop
  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
  65 fails.
  66
  67 .TP
  68 .B restart
  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.
  72
  73 .TP
  74 .B condrestart
  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.
  79
  80 .TP
  81 .B try\-restart
  82 This action is identical to \fIcondrestart\fR.
  83
  84 .TP
  85 .B force\-reload
  86 Stop all running servers, reload config files and restart the service as if
  87 .I start
  88 was specified.
  89
  90 .TP
  91 .B status
  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.
  95
  96 .SH OPTIONS
  97 The following options are used to provide additional configuration and
  98 to specify servers to be managed:
  99
 100 .TP
 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
 106 last
 107 configuration file specified will be used.
 108
 109 .TP
 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
 113 .IR stap (1)
 114 manual page for more details.
 115 The default architecture is the architecture of the host.
 116
 117 .TP
 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
 121 .IR stap (1)
 122 manual page for more details.
 123 The default release is that of the currently running kernel.
 124
 125 .TP
 126 \fB\-I\fR \fIpath\fR
 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.
 129 See the
 130 .IR stap (1)
 131 manual page for more details.
 132
 133 .TP
 134 \fB\-R\fR \fIpath\fR
 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.
 137 See the
 138 .IR stap (1)
 139 manual page for more details.
 140
 141 .TP
 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.
 145 See the
 146 .IR stap (1)
 147 manual page for more details.
 148
 149 .TP
 150 \fB\-i\fR
 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.
 156
 157 .TP
 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 \fI@prefix@/etc/stap\-server/conf.d/*.conf\fR, or the path configured in
 164 \fI@prefix@/etc/sysconfig/stap\-server\fR or the config file specified by the
 165 \fB\-c\fR option. If a server configuration for the given
 166 nickname is found, the
 167 \fB\-a\fR, \fB\-r\fR, \fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options for
 168 that server will be used as if they were specified on the command line. If no
 169 configuration with the given nickname is found, and the action is
 170 .I start
 171 (or an action behaving like \fIstart\fR
 172 (see \fBARGUMENTS\fR), the server will be started with the given nickname.
 173 If no configuration with the given nickname is found, and the action is not
 174 .I start
 175 (or an action behaving like \fIstart\fR), it is an error. If a nickname is
 176 not specified for a server which is being started, its nickname will be its
 177 process id.
 178
 179 .TP
 180 \fB\-p\fR \fIpid\fR
 181 This option allows the specification of a server configuration by process id.
 182 When \fB\-p\fR is specified, a currently running server with the given process
 183 id will be searched for. If no such server is found, it is an error. If a server
 184 with the given procss id is found, the
 185 \fB\-a\fR, \fB\-r\fR, \fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options for
 186 that server will be used as if they were specified on the command line.
 187
 188 .TP
 189 \fB\-u\fR \fIuser\-name\fR
 190 Each systemtap compile server is normally run by the user name
 191 \fistap\-server\fR (for the initscript) or as the user invoking
 192 \fIstap-server\fR,
 193 unless otherwise configured (see \fBFILES\fR). This option
 194 specifies the user name used to run the server(s). The user name specified
 195 must be a member of the group \fIstap\-server\fR.
 196
 197 .SH CONFIGURATION
 198
 199 Configuration files allow us to:
 200 .IP \(bu 4
 201 specify global configuration of logging, server configuration files, status
 202 files and other global parameters.
 203 .IP \(bu 4
 204 specify which servers are to be started by default.
 205
 206 .SH Global Configuration
 207
 208 The Global Configuration file (\fI@prefix@/etc/sysconfig/stap\-server\fR) contains
 209 variable assignments used to configure the overall operation of the service.
 210 Each line beginning with a '#' character is ignored. All other lines must be
 211 of the form \fIVARIABLE=VALUE\fR. This is not a shell script. The entire
 212 contents of the line after the = will be assigned as\-is to the variable.
 213
 214 The following variables may be assigned:
 215
 216 .TP
 217 .B CONFIG_PATH
 218 Specifies the absolute path of the directory containing the default server
 219 configurations
 220 (default: \fI@prefix@/etc/stap\-server/conf.d\fR).
 221
 222 .TP
 223 .B STAT_PATH
 224 Specifies the absolute path of the running server status directory
 225 (default: \fI@prefix@/var/run/stap\-server\fR).
 226
 227 .TP
 228 .B LOG_FILE
 229 Specifies the absolute path of the log file
 230 (default: \fI@prefix@/var/log/stap\-server.log\fR).
 231
 232 .TP
 233 .B STAP_USER
 234 Specifies the userid which will be used to run the server(s)
 235 (default: for the initscript \fIstap\-server\fR, otherwise the user running
 236 \fIstap-server\fR).
 237
 238 .SH Individual Server Configuration
 239
 240 Each server configuration file configures a server to be started when no
 241 server is specified for the \fIstart\fR action, or an action behaving like the
 242 \fIstart\fR action (see \fIARGUMENTS\fR). Each configuration file contains
 243 variable assignments used to configure an individual server.
 244
 245 Each line beginning with a '#' character is ignored. All other lines must be
 246 of the form \fIVARIABLE=VALUE\fR. This is not a shell script. The entire
 247 contents of the line after the = will be assigned as\-is to the variable.
 248
 249 Each configuration file must have a
 250 filename suffix of \fI.conf\fR. The default
 251 location of these files is \fI@prefix@/etc/stap\-server/conf.d/\fR, but this can be
 252 overridden in the global configuration file using the \fB\-c\fR option
 253 (see \fIOPTIONS\fR).
 254
 255 The following variables may be assigned:
 256 .TP
 257 .B ARCH
 258 Specifies the target architecture for this server and corresponds to the
 259 \fB\-a\fR option (see \fIOPTIONS\fR). If \fBARCH\fR is not set, the
 260 architecture of the host will be used.
 261
 262 .TP
 263 .B RELEASE
 264 Specifies the kernel release for this server
 265 and corresponds to the
 266 \fB\-r\fR option (see \fIOPTIONS\fR). If \fBRELEASE\fR is not set, the
 267 release
 268 of the kernel running on the host will be used.
 269
 270 .TP
 271 .B BUILD
 272 Specifies options to be passed to the \fImake\fR process used by
 273 \fIsystemtap\fR to build kernel modules.
 274 This an array variable with each element corresponding to a
 275 \fB\-B\fR option (see \fIOPTIONS\fR). Using the form \fBBUILD=STRING\fR clears
 276 the array and sets the first element to \fBSTRING\fR. Using the form
 277 \fBBUILD+=STRING\fR adds \fBSTRING\fR as an additional element to the array.
 278
 279 .TP
 280 .B INCLUDE
 281 Specifies a list of directories to be searched by the server for tapsets.
 282 This an array variable with each element corresponding to an
 283 \fB\-I\fR option (see \fIOPTIONS\fR). Using the form \fBINCLUDE=PATH\fR clears
 284 the array and sets the first element to \fBPATH\fR. Using the form
 285 \fBINCLUDE+=PATH\fR adds \fBPATH\fR as an additional element to the array.
 286
 287 .TP
 288 .B RUNTIME
 289 Specifies the directory which contains the systemtap runtime code to be used
 290 by this server
 291 and corresponds to the
 292 \fB\-R\fR option (see \fIOPTIONS\fR).
 293
 294 .TP
 295 .B USER
 296 Specifies the user name to be used to run this server
 297 and corresponds to the
 298 \fB\-u\fR option (see \fIOPTIONS\fR).
 299
 300 .TP
 301 .B NICKNAME
 302 Specifies the nickname to be used to refer to this server
 303 and corresponds to the
 304 \fB\-n\fR option (see \fIOPTIONS\fR).
 305
 306 .SH SERVER AUTHENTICAION
 307 The security of the SSL network connection between the client and server
 308 depends on the proper
 309 management of server certificates.
 310
 311 .PP
 312 The trustworthiness of a given systemtap server can not be determined
 313 automatically without a trusted certificate authority issuing systemtap server
 314 certificates. This is
 315 not practical in everyday use and so, clients must authenticate servers
 316 against their own database of trusted server certificates. In this context,
 317 establishing a given server as trusted by a given client means adding
 318 that server\[aq]s certificate to the
 319 client\[aq]s database of trusted servers.
 320
 321 .PP
 322 For the \fIstap\-server\fR initscript, on the local host, this is handled
 323 automatically.
 324 When the \fIsystemtap\-server\fR package is installed, the server\[aq]s
 325 certificate for the default user (\fIstap\-server\fR) is automatically
 326 generated and installed. This means that servers started by the
 327 \fIstap\-server\fR initscript,
 328 with the default user, are automatically trusted by clients on the local
 329 host.
 330
 331 .PP
 332 In order to use a server running on another host, that server\[aq]s certificate
 333 must be installed on the client\[aq]s host.
 334 See the \fI\-\-trust\-servers\fR option in the
 335 .IR stap (1)
 336 manual page for more details.
 337
 338 .SH EXAMPLES
 339 See the
 340 .IR stapex (3stap)
 341 manual page for a collection of sample \fIsystemtap\fR scripts.
 342 .PP
 343 To start the configured servers, or the default server, if none are configured:
 344 .PP
 345 .B \& $ [ service ] stap\-server start
 346 .PP
 347 To start a server for each kernel installed in /lib/modules:
 348 .PP
 349 .B \& $ [ service ] stap\-server start \-i
 350 .PP
 351 To obtain information about the running server(s):
 352 .PP
 353 .B \& $ [ service ] stap\-server status
 354 .PP
 355 To start a server like another one, except targeting a different architecture,
 356 by referencing the first server\[aq]s nickname:
 357 .PP
 358 .B \& $ [ service ] stap\-server start \-n \fINICKNAME\fR \-a \fIARCH\fR
 359 .PP
 360 To stop one of the servers by referencing its process id (obtained by running
 361 \fBstap\-server status\fR):
 362 .PP
 363 .B \& $ [ service ] stap\-server stop \-p \fIPID\fR
 364 .PP
 365 To stop all running servers:
 366 .PP
 367 .B \& $ [ service ] stap\-server stop
 368
 369 .SH SAFETY AND SECURITY
 370 Systemtap is an administrative tool.  It exposes kernel internal data
 371 structures and potentially private user information.  See the
 372 .IR stap (1)
 373 manual page for additional information on safety and security.
 374
 375 .PP
 376 As a network server, stap-server should be activated with care in
 377 order to limit the potential effects of bugs or mischevious users.
 378 Consider the following prophylactic measures.
 379 .TP
 380 1
 381 Run stap-server as an unprivileged user, never as root.
 382 .TP
 383 2
 384 Run stap-server with resource limits that impose maximum
 385 cpu time, file size, memory consumption, in order to bound
 386 the effects of processing excessively large or bogus inputs.
 387 .TP
 388 3
 389 Run stap-server with a $TMPDIR environment variable that
 390 points to a separate and/or quota-enforced directory, in
 391 order to prevent filling up of important filesystems.
 392 .TP
 393 4
 394 Activate network firewalls to limit stap client connections
 395 to relatively trustworthy networks.
 396
 397 .PP
 398 The systemtap server and its related utilities use the Secure Socket Layer
 399 (SSL) as implemented by Network Security Services (NSS)
 400 for network security. The NSS tool
 401 .I certutil
 402 is used for the generation of certificates. The related
 403 certificate databases must be protected in order to maintain the security of
 404 the system.
 405 Use of the utilities provided will help to ensure that the proper protection
 406 is maintained. The systemtap client will check for proper
 407 access permissions before making use of any certificate database.
 408
 409 .SH FILES
 410 .TP
 411 @prefix@/etc/sysconfig/stap\-server/
 412 Global configuration file.
 413
 414 .TP
 415 @prefix@/etc/stap\-server/conf.d/*.conf
 416 Configuration files for default servers.
 417
 418 .TP
 419 @prefix@/var/run/stap\-server/
 420 Default location of status files for running servers.
 421
 422 .TP
 423 @prefix@/var/log/stap\-server.log
 424 Default log file.
 425
 426 .TP
 427 /lib/modules/
 428 Location of installed kernels.
 429
 430 .SH SEE ALSO
 431 .IR stap (1),
 432 .IR staprun (8),
 433 .IR stapprobes (3stap),
 434 .IR stapfuncs (3stap),
 435 .IR stappaths (7),
 436 .IR stapex (3stap),
 437 .IR ulimit (1),
 438 .IR NSS ,
 439 .IR certutil
 440
 441 .SH BUGS
 442 Use the Bugzilla link of the project web page or our mailing list.
 443 .nh
 444 .BR http://sources.redhat.com/systemtap/ ", " <systemtap@sources.redhat.com> .
 445 .hy
 446