NAME
stap-server - systemtap server management
SYNOPSIS
[ service ] stap-server { start | stop | restart | condrestart |
try-restart | force-reload | status } [ options ]
DESCRIPTION
A systemtap compile server listens for connections from clients
(stap-client) 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.
The stap-server script aims to provide:
· 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
/etc/stap-server/conf.d/*.conf, or the path configured in
/etc/sysconfig/stap-server or the config 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.
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 (/etc/sysconfig/stap-server) is a shell
script fragment which may contain settings for the following variables:
CONFIG_PATH
Specifies the absolute path of the directory containing the
default server configurations (default:
/etc/stap-server/conf.d).
STAT_PATH
Specifies the absolute path of the running server status
directory (default: /var/run/stap-server).
LOG_FILE
Specifies the absolute path of the log file (default:
/var/log/stap-server.log).
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 is a shell
script fragment with a filename suffix of .conf. The default location
of these files is /etc/stap-server/conf.d/, but this can be overridden
using the -c option (see OPTIONS).
The following variables may be set:
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 and corresponds to one or more
-B options (see OPTIONS).
INCLUDE
Specifies a list of directories to be searched by the server for
tapsets and corresponds to one or more -I options (see OPTIONS).
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).
SERVER AUTHENTICAION
The security of the SSL network connection between the client and
server depends on the proper management of server certificates.
The trustworthiness of a given systemtap server can not be determined
automatically without a trusted certificate authority issuing systemtap
server certificates. This is not practical in everyday use and so,
clients must authenticate servers against their own database of trusted
server certificates. In this context, establishing a given server as
trusted by a given client means adding that server's certificate to the
client's database of trusted servers.
For the stap-server initscript, on the local host, this is handled
automatically. When the systemtap-server package is installed, the
server's certificate for the default user (stap-server) is
automatically generated and installed. This means that servers started
by the stap-server initscript, with the default user, are automatically
trusted by clients on the local host.
In order to use a server running on another host, that server's
certificate must be installed on the client's host. See the
stap-authorize-server-cert(8) manual page for more details.
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 stop all running servers:
$ [ service ] stap-server stop
SAFETY 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.
As a network server, stap-server should be activated with care in order
to limit the potential effects of bugs or mischevious users. Consider
the following prophylactic measures.
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.
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.
The systemtap server and its related utilities use the Secure Socket
Layer (SSL) as implemented by Network Security Services (NSS) for
network security. The NSS tool certutil is used for the generation of
certificates. The related certificate databases must be protected in
order to maintain the security of the system. Use of the utilities
provided will help to ensure that the proper protection is maintained.
The systemtap client will check for proper access permissions before
making use of any certificate database.
FILES
/etc/sysconfig/stap-server/
Global configuration file.
/etc/stap-server/conf.d/*.conf
Configuration files for default servers.
/var/run/stap-server/
Default location of status files for running servers.
/var/log/stap-server.log
Default log file.
/lib/modules/
Location of installed kernels.
SEE ALSO
stap(1), staprun(8), stap-client(8), stap-authorize-server-cert(8),
stapprobes(3stap), stapfuncs(3stap), stapex(3stap), ulimit(1), NSS,
certutil
BUGS
Use the Bugzilla link of the project web page or our mailing list.
http://sources.redhat.com/systemtap/, <systemtap@sources.redhat.com>.