| 1 |
.\" -*- nroff -*- |
| 2 |
.TH STAP\-SERVER 8 |
| 3 |
.SH NAME |
| 4 |
stap\-server \- systemtap compile server management |
| 5 |
|
| 6 |
.\" macros |
| 7 |
.de SAMPLE |
| 8 |
|
| 9 |
.nr oldin \\n(.i |
| 10 |
.br |
| 11 |
.RS |
| 12 |
.nf |
| 13 |
.nh |
| 14 |
.. |
| 15 |
.de ESAMPLE |
| 16 |
.hy |
| 17 |
.fi |
| 18 |
.RE |
| 19 |
.in \\n[oldin]u |
| 20 |
|
| 21 |
.. |
| 22 |
|
| 23 |
.SH SYNOPSIS |
| 24 |
|
| 25 |
.br |
| 26 |
[ |
| 27 |
.B service |
| 28 |
] |
| 29 |
.B stap\-server |
| 30 |
{ |
| 31 |
.B start |
| 32 |
| |
| 33 |
.B stop |
| 34 |
| |
| 35 |
.B restart |
| 36 |
| |
| 37 |
.B condrestart |
| 38 |
| |
| 39 |
.B try\-restart |
| 40 |
| |
| 41 |
.B force\-reload |
| 42 |
| |
| 43 |
.B status |
| 44 |
} [ |
| 45 |
.I options |
| 46 |
] |
| 47 |
|
| 48 |
.SH DESCRIPTION |
| 49 |
|
| 50 |
A systemtap compile server listens for connections from stap clients |
| 51 |
on a secure SSL network port and accepts requests to run the |
| 52 |
.I stap |
| 53 |
front end. Each server advertises its presence and configuration on the local |
| 54 |
network using mDNS (\fIavahi\fR) allowing for automatic detection by clients. |
| 55 |
|
| 56 |
.PP |
| 57 |
The stap\-server script aims to provide: |
| 58 |
.IP \(bu 4 |
| 59 |
management of systemtap compile servers as a service. |
| 60 |
.IP \(bu 4 |
| 61 |
convenient control over configured servers and individual (ad\-hoc) servers. |
| 62 |
|
| 63 |
.SH ARGUMENTS |
| 64 |
One of the actions below must be specified: |
| 65 |
.TP |
| 66 |
.B start |
| 67 |
Start servers. The specified servers are started. |
| 68 |
If no server is specified, the configured servers are started. If no servers |
| 69 |
are configured, a server for the kernel release and architecture of the host |
| 70 |
is started. |
| 71 |
If a specified server is |
| 72 |
already started, this action will |
| 73 |
be ignored for that server. If a server fails to start, this action fails. |
| 74 |
|
| 75 |
.TP |
| 76 |
.B stop |
| 77 |
Stop server(s). The specified servers are stopped. |
| 78 |
If no server is specified, all currently running servers are stopped. |
| 79 |
If a specified server is |
| 80 |
not running, this action |
| 81 |
will be successful for that server. If a server fails to stop, this action |
| 82 |
fails. |
| 83 |
|
| 84 |
.TP |
| 85 |
.B restart |
| 86 |
Stop and restart servers. The specified servers are stopped and restarted. |
| 87 |
If no server is specified, all currently running servers are stopped and |
| 88 |
restarted. If no servers are running, this action behaves like \fIstart\fR. |
| 89 |
|
| 90 |
.TP |
| 91 |
.B condrestart |
| 92 |
Stop and restart servers. The specified servers are stopped and restarted. |
| 93 |
If a specified server is not running, it is not started. If no server is |
| 94 |
specified, all currently running servers are stopped and restarted. If no |
| 95 |
servers are running, none will be started. |
| 96 |
|
| 97 |
.TP |
| 98 |
.B try\-restart |
| 99 |
This action is identical to \fIcondrestart\fR. |
| 100 |
|
| 101 |
.TP |
| 102 |
.B force\-reload |
| 103 |
Stop all running servers, reload config files and restart the service as if |
| 104 |
.I start |
| 105 |
was specified. |
| 106 |
|
| 107 |
.TP |
| 108 |
.B status |
| 109 |
Print information about running servers. Information about the specified |
| 110 |
server(s) will be printed. If no server is specified, information about all |
| 111 |
running servers will be printed. |
| 112 |
|
| 113 |
.SH OPTIONS |
| 114 |
The following options are used to provide additional configuration and |
| 115 |
to specify servers to be managed: |
| 116 |
|
| 117 |
.TP |
| 118 |
\fB\-c\fR \fIconfigfile\fR |
| 119 |
This option specifies a global configuration file in addition to the default |
| 120 |
global configuration file described |
| 121 |
below. This file will be processed after the default global |
| 122 |
configuration file. If the \fB\-c\fR option is specified more than once, the |
| 123 |
last |
| 124 |
configuration file specified will be used. |
| 125 |
|
| 126 |
.TP |
| 127 |
\fB\-a\fR \fIarchitecture\fR |
| 128 |
This option specifies the target architecture of the server and is |
| 129 |
analogous to the \fB\-a\fR option of \fIstap\fR. See the |
| 130 |
.IR stap (1) |
| 131 |
manual page for more details. |
| 132 |
The default architecture is the architecture of the host. |
| 133 |
|
| 134 |
.TP |
| 135 |
\fB\-r\fR \fIkernel\-release\fR |
| 136 |
This option specifies a target kernel release of the server and is |
| 137 |
analogous to the \fB\-r\fR option of \fIstap\fR. See the |
| 138 |
.IR stap (1) |
| 139 |
manual page for more details. |
| 140 |
The default release is that of the currently running kernel. |
| 141 |
A server can handle multiple releases by specifying multiple \fB\-r\fR flags. |
| 142 |
|
| 143 |
.TP |
| 144 |
\fB\-I\fR \fIpath\fR |
| 145 |
This option specifies an additional path to be searched by the server(s) for |
| 146 |
tapsets and is analogous to the \fB\-I\fR option of \fIstap\fR. |
| 147 |
See the |
| 148 |
.IR stap (1) |
| 149 |
manual page for more details. |
| 150 |
|
| 151 |
.TP |
| 152 |
\fB\-R\fR \fIpath\fR |
| 153 |
This option specifies the location of the systemtap runtime to be used by the |
| 154 |
server(s) and is analogous to the \fB\-R\fR option of \fIstap\fR. |
| 155 |
See the |
| 156 |
.IR stap (1) |
| 157 |
manual page for more details. |
| 158 |
|
| 159 |
.TP |
| 160 |
\fB\-B\fR \fIoptions\fR |
| 161 |
This option specifies options to be passed to \fImake\fR when building systemtap |
| 162 |
modules and is analogous to the \fB\-B\fR option of \fIstap\fR. |
| 163 |
See the |
| 164 |
.IR stap (1) |
| 165 |
manual page for more details. |
| 166 |
|
| 167 |
.TP |
| 168 |
\fB\-i\fR |
| 169 |
This option is a shortcut which specifies a server that handles every |
| 170 |
release installed in \fI/lib/modules/\fR. |
| 171 |
.TP |
| 172 |
\fB\-n\fR \fInickname\fR |
| 173 |
This option allows the specification of a server configuration by nickname. |
| 174 |
When \fB\-n\fR is specified, a currently running server with the given nickname |
| 175 |
will be searched for. If no currently running server with the given nickname is |
| 176 |
found, a server configuration with the given nickname will be searched for in |
| 177 |
the configuration files for default servers, |
| 178 |
or the path configured in the global configuration file or |
| 179 |
the configuration file specified by the |
| 180 |
\fB\-c\fR option. If a server configuration for the given |
| 181 |
nickname is found, the |
| 182 |
\fB\-a\fR, \fB\-r\fR, \fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options for |
| 183 |
that server will be used as if they were specified on the command line. If no |
| 184 |
configuration with the given nickname is found, and the action is |
| 185 |
.I start |
| 186 |
(or an action behaving like \fIstart\fR |
| 187 |
(see \fBARGUMENTS\fR), the server will be started with the given nickname. |
| 188 |
If no configuration with the given nickname is found, and the action is not |
| 189 |
.I start |
| 190 |
(or an action behaving like \fIstart\fR), it is an error. If a nickname is |
| 191 |
not specified for a server which is being started, its nickname will be its |
| 192 |
process id. |
| 193 |
|
| 194 |
.TP |
| 195 |
\fB\-p\fR \fIpid\fR |
| 196 |
This option allows the specification of a server configuration by process id. |
| 197 |
When \fB\-p\fR is specified, a currently running server with the given process |
| 198 |
id will be searched for. If no such server is found, it is an error. If a server |
| 199 |
with the given process id is found, the |
| 200 |
\fB\-a\fR, \fB\-r\fR, \fB\-I\fR, \fB\-R\fR, \fB\-B\fR and \fB\-u\fR options for |
| 201 |
that server will be used as if they were specified on the command line. |
| 202 |
|
| 203 |
.TP |
| 204 |
\fB\-u\fR \fIuser\-name\fR |
| 205 |
Each systemtap compile server is normally run by the user name |
| 206 |
\fIstap\-server\fR (for the initscript) or as the user invoking |
| 207 |
\fIstap\-server\fR, |
| 208 |
unless otherwise configured (see \fBFILES\fR). This option |
| 209 |
specifies the user name used to run the server(s). The user name specified |
| 210 |
must be a member of the group \fIstap\-server\fR. |
| 211 |
|
| 212 |
.TP |
| 213 |
\fB\-\-log\fR \fIlogfile\fR |
| 214 |
This option allows the specification of a separate log file for each server. |
| 215 |
Each \-\-log option is added to a list which will be applied, in turn, to each |
| 216 |
server specified. If more servers are specified than \-\-log options, the default |
| 217 |
log file (see \fBFILES\fR) will be used for subsequent servers. |
| 218 |
|
| 219 |
.TP |
| 220 |
\fB\-\-port\fR \fIport\-number\fR |
| 221 |
This option allows the specification of a specific network port for each |
| 222 |
server. Each \-\-port option is added to a list which will be applied, in turn, |
| 223 |
to each server specified. If more servers are specified than |
| 224 |
\-\-port options, a randomly selected port is used for subsequent servers. |
| 225 |
|
| 226 |
.TP |
| 227 |
\fB\-\-ssl\fR \fIcertificate\-db\-path\fR |
| 228 |
This option allows the specification of a separate NSS certificate database |
| 229 |
for each server. Each \-\-ssl option is added to a list which will be applied, |
| 230 |
in turn, to each server specified. If more servers are specified than \-\-ssl |
| 231 |
options, the default certificate database |
| 232 |
(see \fBFILES\fR) for subsequent servers. |
| 233 |
|
| 234 |
.TP |
| 235 |
\fB\-\-max\-threads\fR \fIthreads\fR |
| 236 |
This option allows the specification of the maximum number of worker threads |
| 237 |
to handle concurrent requests. If \fIthreads\fR == 0, each request will be |
| 238 |
handled on the main thread, serially. The default is the number of available |
| 239 |
processor cores. |
| 240 |
|
| 241 |
.TP |
| 242 |
\fB\-\-max\-request\-size\fR \fIsize\fR |
| 243 |
This options allows the specification of the maximum size of an uncompressed |
| 244 |
client request. The arguement \fIsize\fR is specified in bytes. The |
| 245 |
default is the 50000 bytes. |
| 246 |
|
| 247 |
.TP |
| 248 |
\fB\-\-max\-compressed\-request\fR \fIsize\fR |
| 249 |
This options allows the specification of the maximum size of a compressed |
| 250 |
client request. The arguement \fIsize\fR is specified in bytes. The |
| 251 |
default is the 5000 bytes. |
| 252 |
|
| 253 |
.SH CONFIGURATION |
| 254 |
|
| 255 |
Configuration files allow us to: |
| 256 |
.IP \(bu 4 |
| 257 |
specify global configuration of logging, server configuration files, status |
| 258 |
files and other global parameters. |
| 259 |
.IP \(bu 4 |
| 260 |
specify which servers are to be started by default. |
| 261 |
|
| 262 |
.SH Global Configuration |
| 263 |
|
| 264 |
The Global Configuration file contains |
| 265 |
variable assignments used to configure the overall operation of the service. |
| 266 |
Each line beginning with a '#' character is ignored. All other lines must be |
| 267 |
of the form \fIVARIABLE=VALUE\fR. This is not a shell script. The entire |
| 268 |
contents of the line after the = will be assigned as\-is to the variable. |
| 269 |
|
| 270 |
The following variables may be assigned: |
| 271 |
|
| 272 |
.TP |
| 273 |
.B CONFIG_PATH |
| 274 |
Specifies the absolute path of the directory containing the default server |
| 275 |
configurations. |
| 276 |
|
| 277 |
.TP |
| 278 |
.B STAT_PATH |
| 279 |
Specifies the absolute path of the running server status directory. |
| 280 |
|
| 281 |
.TP |
| 282 |
.B LOG_FILE |
| 283 |
Specifies the absolute path of the log file. |
| 284 |
|
| 285 |
.TP |
| 286 |
.B STAP_USER |
| 287 |
Specifies the userid which will be used to run the server(s) |
| 288 |
(default: for the initscript \fIstap\-server\fR, otherwise the user running |
| 289 |
\fIstap\-server\fR). |
| 290 |
|
| 291 |
.PP |
| 292 |
Here is an example of a Global Configuration file: |
| 293 |
.SAMPLE |
| 294 |
CONFIG_PATH=~<user>/my-stap-server-configs |
| 295 |
LOG_FILE=/tmp/stap-server/log |
| 296 |
.ESAMPLE |
| 297 |
|
| 298 |
.SH Individual Server Configuration |
| 299 |
|
| 300 |
Each server configuration file configures a server to be started when no |
| 301 |
server is specified for the \fIstart\fR action, or an action behaving like the |
| 302 |
\fIstart\fR action (see \fIARGUMENTS\fR). Each configuration file contains |
| 303 |
variable assignments used to configure an individual server. |
| 304 |
|
| 305 |
Each line beginning with a '#' character is ignored. All other lines must be |
| 306 |
of the form \fIVARIABLE=VALUE\fR. This is not a shell script. The entire |
| 307 |
contents of the line after the = will be assigned as\-is to the variable. |
| 308 |
|
| 309 |
Each configuration file must have a filename suffix of \fI.conf\fR. See |
| 310 |
\fIstappaths\fR(7) for the default location of these files. This default |
| 311 |
location can be overridden in the global configuration file using the \fB\-c\fR |
| 312 |
option (see \fIOPTIONS\fR). |
| 313 |
|
| 314 |
The following variables may be assigned: |
| 315 |
.TP |
| 316 |
.B ARCH |
| 317 |
Specifies the target architecture for this server and corresponds to the |
| 318 |
\fB\-a\fR option (see \fIOPTIONS\fR). If \fBARCH\fR is not set, the |
| 319 |
architecture of the host will be used. |
| 320 |
|
| 321 |
.TP |
| 322 |
.B RELEASE |
| 323 |
Specifies a kernel release for this server |
| 324 |
and corresponds to the |
| 325 |
\fB\-r\fR option (see \fIOPTIONS\fR). If \fBRELEASE\fR is not set, the |
| 326 |
release |
| 327 |
of the kernel running on the host will be used. |
| 328 |
|
| 329 |
.TP |
| 330 |
.B BUILD |
| 331 |
Specifies options to be passed to the \fImake\fR process used by |
| 332 |
\fIsystemtap\fR to build kernel modules. |
| 333 |
This an array variable with each element corresponding to a |
| 334 |
\fB\-B\fR option (see \fIOPTIONS\fR). Using the form \fBBUILD=STRING\fR clears |
| 335 |
the array and sets the first element to \fBSTRING\fR. Using the form |
| 336 |
\fBBUILD+=STRING\fR adds \fBSTRING\fR as an additional element to the array. |
| 337 |
|
| 338 |
.TP |
| 339 |
.B INCLUDE |
| 340 |
Specifies a list of directories to be searched by the server for tapsets. |
| 341 |
This is an array variable with each element corresponding to a |
| 342 |
\fB\-I\fR option (see \fIOPTIONS\fR). Using the form \fBINCLUDE=PATH\fR clears |
| 343 |
the array and sets the first element to \fBPATH\fR. Using the form |
| 344 |
\fBINCLUDE+=PATH\fR adds \fBPATH\fR as an additional element to the array. |
| 345 |
|
| 346 |
.TP |
| 347 |
.B RUNTIME |
| 348 |
Specifies the directory which contains the systemtap runtime code to be used |
| 349 |
by this server |
| 350 |
and corresponds to the |
| 351 |
\fB\-R\fR option (see \fIOPTIONS\fR). |
| 352 |
|
| 353 |
.TP |
| 354 |
.B USER |
| 355 |
Specifies the user name to be used to run this server |
| 356 |
and corresponds to the |
| 357 |
\fB\-u\fR option (see \fIOPTIONS\fR). |
| 358 |
|
| 359 |
.TP |
| 360 |
.B NICKNAME |
| 361 |
Specifies the nickname to be used to refer to this server |
| 362 |
and corresponds to the |
| 363 |
\fB\-n\fR option (see \fIOPTIONS\fR). |
| 364 |
|
| 365 |
.TP |
| 366 |
.B LOG |
| 367 |
Specifies the location of the log file to be used by this server and corresponds to the |
| 368 |
\fB\-\-log\fR option (see \fIOPTIONS\fR). |
| 369 |
|
| 370 |
.TP |
| 371 |
.B PORT |
| 372 |
Specifies the network port to be used by this server and corresponds to the |
| 373 |
\fB\-\-port\fR option (see \fIOPTIONS\fR). |
| 374 |
|
| 375 |
.TP |
| 376 |
.B SSL |
| 377 |
Specifies the location of the NSS certificate database to be used by this server and corresponds |
| 378 |
to the |
| 379 |
\fB\-\-ssl\fR option (see \fIOPTIONS\fR). |
| 380 |
|
| 381 |
.TP |
| 382 |
.B MAXTHREADS |
| 383 |
Specifies the maximum number of worker threads to handle concurrent requests to be used by this server |
| 384 |
and corresponds to the \fB\-\-max\-threads\fR option (see \fIOPTIONS\fR). |
| 385 |
|
| 386 |
.TP |
| 387 |
.B MAXREQSIZE |
| 388 |
Specifies the maximum size of an uncompressed client request, to be used by |
| 389 |
this server and correspnds to the \fB\-\-max\-request\-size\fR option (see \fIOPTIONS\fR). |
| 390 |
|
| 391 |
.TP |
| 392 |
.B MAXCOMPRESSEDREQ |
| 393 |
Specifies the maximum size of an compressed client request, to be used by |
| 394 |
this server and correspnds to the \fB\-\-max\-compressed\-request\fR option (see \fIOPTIONS\fR). |
| 395 |
|
| 396 |
.PP |
| 397 |
Here is an example of a server configuration file: |
| 398 |
.SAMPLE |
| 399 |
ARCH= |
| 400 |
USER= |
| 401 |
RELEASE= |
| 402 |
NICKNAME=native |
| 403 |
.ESAMPLE |
| 404 |
By keeping the ARCH, USER, and RELEASE fields blank, they will default to the |
| 405 |
current arch and release and use the default user. |
| 406 |
|
| 407 |
A more specific example: |
| 408 |
.SAMPLE |
| 409 |
ARCH=i386 |
| 410 |
RELEASE=2.6.18-128.el5 |
| 411 |
PORT=5001 |
| 412 |
LOG=/path/to/log/file |
| 413 |
.ESAMPLE |
| 414 |
|
| 415 |
And here is a more complicated example: |
| 416 |
.SAMPLE |
| 417 |
USER=serveruser |
| 418 |
RELEASE=/kernels/2.6.18-92.1.18.el5/build |
| 419 |
INCLUDE=/mytapsets |
| 420 |
INCLUDE+=/yourtapsets |
| 421 |
BUILD='VARIABLE1=VALUE1 VARIABLE2=VALUE2' |
| 422 |
DEFINE=STP_MAXMEMORY=1024 |
| 423 |
DEFINE+=DEBUG_TRANS |
| 424 |
RUNTIME=/myruntime |
| 425 |
NICKNAME=my-server |
| 426 |
SSL=/path/to/NSS/certificate/database |
| 427 |
.ESAMPLE |
| 428 |
|
| 429 |
.SH SERVER AUTHENTICATION |
| 430 |
The security of the SSL network connection between the client and server |
| 431 |
depends on the proper |
| 432 |
management of server certificates. |
| 433 |
|
| 434 |
.PP |
| 435 |
The trustworthiness of a given systemtap compile server can not be determined |
| 436 |
automatically without a trusted certificate authority issuing systemtap compile server |
| 437 |
certificates. This is |
| 438 |
not practical in everyday use and so, clients must authenticate servers |
| 439 |
against their own database of trusted server certificates. In this context, |
| 440 |
establishing a given server as trusted by a given client means adding |
| 441 |
that server\[aq]s certificate to the |
| 442 |
client\[aq]s database of trusted servers. |
| 443 |
|
| 444 |
.PP |
| 445 |
For the \fIstap\-server\fR initscript, on the local host, this is handled |
| 446 |
automatically. |
| 447 |
When the \fIsystemtap\-server\fR package is installed, the server\[aq]s |
| 448 |
certificate for the default user (\fIstap\-server\fR) is automatically |
| 449 |
generated and installed. This means that servers started by the |
| 450 |
\fIstap\-server\fR initscript, |
| 451 |
with the default user, are automatically trusted by clients on the local |
| 452 |
host, both as an SSL peer and as a systemtap module signer. |
| 453 |
.PP |
| 454 |
Furthermore, when stap is invoked by an unprivileged user |
| 455 |
(not root, not a member of the group stapdev, but a member of the group |
| 456 |
stapusr and possibly the group stapsys), the options \fI\-\-use\-server\fR |
| 457 |
and \fI\-\-privilege\fR |
| 458 |
are automatically added to the specified options. |
| 459 |
This means that unprivileged users |
| 460 |
on the local host can use a server on the local host |
| 461 |
in unprivileged mode with no further setup or options required. Normal users |
| 462 |
(those in none of the SystemTap groups) can also use compile-servers through the |
| 463 |
\fI\-\-use\-server\fR and \fI\-\-privilege\fR options. But they will of course |
| 464 |
be unable to load the module (the \fI\-p4\fR option can be used to stop short of |
| 465 |
loading). |
| 466 |
|
| 467 |
.PP |
| 468 |
In order to use a server running on another host, that server\[aq]s certificate |
| 469 |
must be installed on the client\[aq]s host. |
| 470 |
See the \fI\-\-trust\-servers\fR option in the |
| 471 |
.IR stap (1) |
| 472 |
manual page for more details and README.unprivileged in the systemtap sources |
| 473 |
for more details. |
| 474 |
|
| 475 |
.SH EXAMPLES |
| 476 |
See the |
| 477 |
.IR stapex (3stap) |
| 478 |
manual page for a collection of sample \fIsystemtap\fR scripts. |
| 479 |
.PP |
| 480 |
To start the configured servers, or the default server, if none are configured: |
| 481 |
.PP |
| 482 |
.B \& $ [ service ] stap\-server start |
| 483 |
.PP |
| 484 |
To start a server that handles all kernel versions installed in /lib/modules: |
| 485 |
.PP |
| 486 |
.B \& $ [ service ] stap\-server start \-i |
| 487 |
.PP |
| 488 |
To obtain information about the running server(s): |
| 489 |
.PP |
| 490 |
.B \& $ [ service ] stap\-server status |
| 491 |
.PP |
| 492 |
To start a server like another one, except targeting a different architecture, |
| 493 |
by referencing the first server\[aq]s nickname: |
| 494 |
.PP |
| 495 |
.B \& $ [ service ] stap\-server start \-n \fINICKNAME\fB \-a \fIARCH\fR |
| 496 |
.PP |
| 497 |
To start a server for a kernel release not installed (cross-compiling) |
| 498 |
.PP |
| 499 |
.B \& $ [ service ] stap\-server start \-a \fIARCH\fB \-r \fI/BUILDDIR\fR |
| 500 |
.PP |
| 501 |
To stop one of the servers by referencing its process id (obtained by running |
| 502 |
\fBstap\-server status\fR): |
| 503 |
.PP |
| 504 |
.B \& $ [ service ] stap\-server stop \-p \fIPID\fR |
| 505 |
.PP |
| 506 |
To run a script using a compile server: |
| 507 |
.PP |
| 508 |
.B \& $ stap SCRIPT \-\-use\-server |
| 509 |
.PP |
| 510 |
To run a script as an unprivileged user using a compile server: |
| 511 |
.PP |
| 512 |
.B \& $ stap SCRIPT |
| 513 |
.PP |
| 514 |
To stop all running servers: |
| 515 |
.PP |
| 516 |
.B \& $ [ service ] stap\-server stop |
| 517 |
.PP |
| 518 |
To restart servers after a global configuration change and/or when default |
| 519 |
servers have been added, changed, or removed: |
| 520 |
.PP |
| 521 |
.B \& $ [ service ] stap\-server force-reload |
| 522 |
|
| 523 |
.SH SAFETY AND SECURITY |
| 524 |
Systemtap is an administrative tool. It exposes kernel internal data |
| 525 |
structures and potentially private user information. See the |
| 526 |
.IR stap (1) |
| 527 |
manual page for additional information on safety and security. |
| 528 |
|
| 529 |
.PP |
| 530 |
As a network server, stap\-server should be activated with care in |
| 531 |
order to limit the potential effects of bugs or mischevious users. |
| 532 |
Consider the following prophylactic measures. |
| 533 |
.TP |
| 534 |
1 |
| 535 |
Run stap\-server as an unprivileged user, never as root. |
| 536 |
|
| 537 |
When invoked as a |
| 538 |
service (i.e. \fBservice stap\-server\fR ...), each server is run, |
| 539 |
by default, as the user \fIstap\-server\fR. |
| 540 |
When invoked directly (i.e. \fBstap\-server\fR ...), each server is run, |
| 541 |
by default, as the invoking user. In each case, another user may be selected by |
| 542 |
using the \fI\-u\fR option on invocation, by specifying |
| 543 |
\fISTAP_USER=\fRusername in the global configuration file or by specifying |
| 544 |
\fIUSER=\fRusername in an individual server configuration file. The invoking |
| 545 |
user must have authority to run processes as another user. |
| 546 |
See \fICONFIGURATION\fR. |
| 547 |
|
| 548 |
The selected user must have write access to the server log file. |
| 549 |
The location of the server log file may |
| 550 |
be changed by setting \fILOG_FILE=\fRpath in the global configuration file. |
| 551 |
See \fICONFIGURATION\fR. |
| 552 |
|
| 553 |
The selected user must have |
| 554 |
read/write access to the directory containing the server status files. |
| 555 |
The location of the server |
| 556 |
status files may be changed by setting \fISTAT_PATH=\fRpath in the global |
| 557 |
configuration file. |
| 558 |
See \fICONFIGURATION\fR. |
| 559 |
|
| 560 |
The selected user must have |
| 561 |
read/write access to the uprobes.ko build directory and its files. |
| 562 |
|
| 563 |
Neither form of stap\-server will run if the selected user is root. |
| 564 |
|
| 565 |
.TP |
| 566 |
2 |
| 567 |
Run stap\-server requests with resource limits that impose maximum |
| 568 |
cpu time, file size, memory consumption, in order to bound |
| 569 |
the effects of processing excessively large or bogus inputs. |
| 570 |
|
| 571 |
When the user running the server is \fIstap\-server\fR, |
| 572 |
each server request is run with limits specified in \fI~stap-server/.systemtap/rc\fR |
| 573 |
otherwise, no limits are imposed. |
| 574 |
|
| 575 |
.TP |
| 576 |
3 |
| 577 |
Run stap\-server with a TMPDIR environment variable that |
| 578 |
points to a separate and/or quota-enforced directory, in |
| 579 |
order to prevent filling up of important filesystems. |
| 580 |
|
| 581 |
The default TMPDIR is \fI/tmp/\fR. |
| 582 |
|
| 583 |
.TP |
| 584 |
4 |
| 585 |
Activate network firewalls to limit stap client connections |
| 586 |
to relatively trustworthy networks. |
| 587 |
|
| 588 |
For automatic selection of servers by clients, \fIavahi\fR must be installed |
| 589 |
on both the server and client hosts and \fImDNS\fR messages must be allowed through the firewall. |
| 590 |
|
| 591 |
.PP |
| 592 |
The systemtap compile server and its related utilities use the Secure Socket Layer |
| 593 |
(SSL) as implemented by Network Security Services (NSS) |
| 594 |
for network security. NSS is also used |
| 595 |
for the generation and management of certificates. The related |
| 596 |
certificate databases must be protected in order to maintain the security of |
| 597 |
the system. |
| 598 |
Use of the utilities provided will help to ensure that the proper protection |
| 599 |
is maintained. The systemtap client will check for proper |
| 600 |
access permissions before making use of any certificate database. |
| 601 |
|
| 602 |
.SH FILES |
| 603 |
.TP |
| 604 |
Important files and their corresponding paths can be located in the |
| 605 |
stappaths (7) manual page. |
| 606 |
|
| 607 |
.SH SEE ALSO |
| 608 |
.nh |
| 609 |
.nf |
| 610 |
.IR stap (1), |
| 611 |
.IR staprun (8), |
| 612 |
.IR stapprobes (3stap), |
| 613 |
.IR stappaths (7), |
| 614 |
.IR stapex (3stap), |
| 615 |
.IR avahi , |
| 616 |
.IR ulimit (1), |
| 617 |
.IR NSS |
| 618 |
|
| 619 |
.SH BUGS |
| 620 |
Use the Bugzilla link of the project web page or our mailing list. |
| 621 |
.nh |
| 622 |
.BR http://sourceware.org/systemtap/ ", " <[email protected]> . |
| 623 |
.hy |
| 624 |
|