other versions
- wheezy 1.7-1+deb7u1
- jessie 2.6-0.2
- jessie-backports 3.0-6~bpo8+1
- testing 3.1-2
- unstable 3.1-2
STAP-SERVER(8) | System Manager's Manual | STAP-SERVER(8) |
NAME¶
stap-server - systemtap compile server managementSYNOPSIS¶
[ service ] stap-server { start | stop | restart | condrestart | try-restart | force-reload | status } [ options ]DESCRIPTION¶
A systemtap compile server listens for connections from stap clients on a secure SSL network port and accepts requests to run the stap front end. Each server advertises its presence and configuration on the local network using mDNS ( avahi) allowing for automatic detection by clients.- •
- management of systemtap compile servers as a service.
- •
- convenient control over configured servers and individual
(ad-hoc) servers.
ARGUMENTS¶
One of the actions below must be specified:- start
- Start servers. The specified servers are started. If no
server is specified, the configured servers are started. If no servers are
configured, a server for the kernel release and architecture of the host
is started. If a specified server is already started, this action will be
ignored for that server. If a server fails to start, this action fails.
- stop
- Stop server(s). The specified servers are stopped. If no
server is specified, all currently running servers are stopped. If a
specified server is not running, this action will be successful for that
server. If a server fails to stop, this action fails.
- restart
- Stop and restart servers. The specified servers are stopped
and restarted. If no server is specified, all currently running servers
are stopped and restarted. If no servers are running, this action behaves
like start.
- condrestart
- Stop and restart servers. The specified servers are stopped
and restarted. If a specified server is not running, it is not started. If
no server is specified, all currently running servers are stopped and
restarted. If no servers are running, none will be started.
- try-restart
- This action is identical to condrestart.
- force-reload
- Stop all running servers, reload config files and restart
the service as if start was specified.
- status
- Print information about running servers. Information about
the specified server(s) will be printed. If no server is specified,
information about all running servers will be printed.
OPTIONS¶
The following options are used to provide additional configuration and to specify servers to be managed:- -c configfile
- This option specifies a global configuration file in
addition to the default global configuration file described below. This
file will be processed after the default global configuration file. If the
-c option is specified more than once, the last configuration file
specified will be used.
- -a architecture
- This option specifies the target architecture of the server
and is analogous to the -a option of stap. See the
stap(1) manual page for more details. The default architecture is
the architecture of the host.
- -r kernel-release
- This option specifies the target kernel release of the
server and is analogous to the -r option of stap. See the
stap(1) manual page for more details. The default release is that
of the currently running kernel.
- -I path
- This option specifies an additional path to be searched by
the server(s) for tapsets and is analogous to the -I option of
stap. See the stap(1) manual page for more details.
- -R path
- This option specifies the location of the systemtap runtime
to be used by the server(s) and is analogous to the -R option of
stap. See the stap(1) manual page for more details.
- -B options
- This option specifies options to be passed to make
when building systemtap modules and is analogous to the -B option
of stap. See the stap(1) manual page for more details.
- -i
- This option is a shortcut which specifies one server for
each kernel release installed in /lib/modules/. Previous -I,
-R, -B and -u options will be applied to each server,
however previous -a options will be ignored and the default
architecture will be used.
- -n nickname
- This option allows the specification of a server
configuration by nickname. When -n is specified, a currently
running server with the given nickname will be searched for. If no
currently running server with the given nickname is found, a server
configuration with the given nickname will be searched for in the
configuration files for default servers, or the path configured in the
global configuration file or the configuration file specified by the
-c option. If a server configuration for the given nickname is
found, the -a, -r, -I, -R, -B and
-u options for that server will be used as if they were specified
on the command line. If no configuration with the given nickname is found,
and the action is start (or an action behaving like start
(see ARGUMENTS), the server will be started with the given
nickname. If no configuration with the given nickname is found, and the
action is not start (or an action behaving like start), it
is an error. If a nickname is not specified for a server which is being
started, its nickname will be its process id.
- -p pid
- This option allows the specification of a server
configuration by process id. When -p is specified, a currently
running server with the given process id will be searched for. If no such
server is found, it is an error. If a server with the given procss id is
found, the -a, -r, -I, -R, -B and
-u options for that server will be used as if they were specified
on the command line.
- -u user-name
- Each systemtap compile server is normally run by the user
name stap-server (for the initscript) or as the user invoking
stap-server, unless otherwise configured (see FILES). This
option specifies the user name used to run the server(s). The user name
specified must be a member of the group stap-server.
- --log logfile
- This option allows the specification of a separate log file
for each server. Each --log option is added to a list which will be
applied, in turn, to each server specified. If more servers are specified
than --log options, the default log file (see FILES) will be used
for subsequent servers.
- --port port-number
- This option allows the specification of a specific network
port for each server. Each --port option is added to a list which will be
applied, in turn, to each server specified. If more servers are specified
than --port options, a randomly selected port is used for subsequent
servers.
- --ssl certificate-db-path
- This option allows the specification of a separate NSS
certificate database for each server. Each --ssl option is added to a list
which will be applied, in turn, to each server specified. If more servers
are specified than --ssl options, the default certificate database (see
FILES) for subsequent servers.
CONFIGURATION¶
Configuration files allow us to:- •
- specify global configuration of logging, server configuration files, status files and other global parameters.
- •
- specify which servers are to be started by default.
Global Configuration¶
The Global Configuration file contains variable assignments used to configure the overall operation of the service. Each line beginning with a '#' character is ignored. All other lines must be of the form VARIABLE=VALUE. This is not a shell script. The entire contents of the line after the = will be assigned as-is to the variable.- CONFIG_PATH
- Specifies the absolute path of the directory containing the
default server configurations.
- STAT_PATH
- Specifies the absolute path of the running server status
directory.
- LOG_FILE
- Specifies the absolute path of the log file.
- STAP_USER
- Specifies the userid which will be used to run the
server(s) (default: for the initscript stap-server, otherwise the
user running stap-server).
Individual Server Configuration¶
Each server configuration file configures a server to be started when no server is specified for the start action, or an action behaving like the start action (see ARGUMENTS). Each configuration file contains variable assignments used to configure an individual server.- ARCH
- Specifies the target architecture for this server and
corresponds to the -a option (see OPTIONS). If ARCH
is not set, the architecture of the host will be used.
- RELEASE
- Specifies the kernel release for this server and
corresponds to the -r option (see OPTIONS). If
RELEASE is not set, the release of the kernel running on the host
will be used.
- BUILD
- Specifies options to be passed to the make process
used by systemtap to build kernel modules. This an array variable
with each element corresponding to a -B option (see
OPTIONS). Using the form BUILD=STRING clears the array and
sets the first element to STRING. Using the form
BUILD+=STRING adds STRING as an additional element to the
array.
- INCLUDE
- Specifies a list of directories to be searched by the
server for tapsets. This an array variable with each element corresponding
to an -I option (see OPTIONS). Using the form
INCLUDE=PATH clears the array and sets the first element to
PATH. Using the form INCLUDE+=PATH adds PATH as an
additional element to the array.
- RUNTIME
- Specifies the directory which contains the systemtap
runtime code to be used by this server and corresponds to the -R
option (see OPTIONS).
- USER
- Specifies the user name to be used to run this server and
corresponds to the -u option (see OPTIONS).
- NICKNAME
- Specifies the nickname to be used to refer to this server
and corresponds to the -n option (see OPTIONS).
- LOG
- Specifies the location of the log file to be used by this
server and corresponds to the --log option (see OPTIONS).
- PORT
- Specifies the network port to be used by this server and
corresponds to the --port option (see OPTIONS).
- SSL
- Specifies the location of the NSS certificate database to
be used by this server and corresponds to the --ssl option (see
OPTIONS).
SERVER AUTHENTICAION¶
The security of the SSL network connection between the client and server depends on the proper management of server certificates.EXAMPLES¶
See the stapex(3stap) manual page for a collection of sample systemtap scripts. To start the configured servers, or the default server, if none are configured: $ [ service ] stap-server start To start a server for each kernel installed in /lib/modules: $ [ service ] stap-server start -i To obtain information about the running server(s): $ [ service ] stap-server status To start a server like another one, except targeting a different architecture, by referencing the first server's nickname: $ [ service ] stap-server start -n NICKNAME -a ARCH To stop one of the servers by referencing its process id (obtained by running stap-server status): $ [ service ] stap-server stop -p PID To run a script using a compile server: $ stap SCRIPT --use-server To run a script as an unprivileged user using a compile server: $ stap SCRIPT To stop all running servers: $ [ service ] stap-server stopSAFETY AND SECURITY¶
Systemtap is an administrative tool. It exposes kernel internal data structures and potentially private user information. See the stap(1) manual page for additional information on safety and security.- 1
- Run stap-server as an unprivileged user, never as root.
- 2
- Run stap-server with resource limits that impose maximum
cpu time, file size, memory consumption, in order to bound the effects of
processing excessively large or bogus inputs.
ulimit -f 50000 -s 1000 -t 60 -u 20 -v 500000
- 3
- Run stap-server with a TMPDIR environment variable that
points to a separate and/or quota-enforced directory, in order to prevent
filling up of important filesystems.
- 4
- Activate network firewalls to limit stap client connections
to relatively trustworthy networks.
FILES¶
- Important files and their corresponding paths can be located in the
- stappaths (7) manual page.