stap-server(8)
NAME
stap-server - systemtap compile 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 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.
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
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
process 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.
--max-threads threads
This option allows the specification of the maximum number of
worker threads to handle concurrent requests. If threads == 0,
each request will be handled on the main thread, serially. The
default is the number of available processor cores.
--max-request-size size
This options allows the specification of the maximum size of an
uncompressed client request. The arguement size is specified in
bytes. The default is the 50000 bytes.
--max-compressed-request size
This options allows the specification of the maximum size of a
compressed client request. The arguement size is specified in
bytes. The default is the 5000 bytes.
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.
The following variables may be assigned:
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).
Here is an example of a Global Configuration file:
CONFIG_PATH=~<user>/my-stap-server-configs
LOG_FILE=/tmp/stap-server/log
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. 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. Each configuration file must have a filename suffix of .conf. See stappaths(7) for the default location of these files. This default location can be overridden in the global configuration file using the -c option (see OPTIONS). The following variables may be assigned: 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 is an array variable with each element corresponding to a -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). MAXTHREADS Specifies the maximum number of worker threads to handle concurrent requests to be used by this server and corresponds to the --max-threads option (see OPTIONS). MAXREQSIZE Specifies the maximum size of an uncompressed client request, to be used by this server and correspnds to the --max-request-size option (see OPTIONS). MAXCOMPRESSEDREQ Specifies the maximum size of an compressed client request, to be used by this server and correspnds to the --max-compressed-request option (see OPTIONS). Here is an example of a server configuration file: ARCH= USER= RELEASE= NICKNAME=native By keeping the ARCH, USER, and RELEASE fields blank, they will default to the current arch and release and use the default user. A more specific example: ARCH=i386 RELEASE=2.6.18-128.el5 PORT=5001 LOG=/path/to/log/file And here is a more complicated example: USER=serveruser RELEASE=/kernels/2.6.18-92.1.18.el5/build INCLUDE=/mytapsets INCLUDE+=/yourtapsets BUILD='VARIABLE1=VALUE1 VARIABLE2=VALUE2' DEFINE=STP_MAXMEMORY=1024 DEFINE+=DEBUG_TRANS RUNTIME=/myruntime NICKNAME=my-server SSL=/path/to/NSS/certificate/database
SERVER AUTHENTICATION
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 compile server can not be determined automatically without a trusted certificate authority issuing systemtap compile 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, both as an SSL peer and as a systemtap module signer. Furthermore, when stap is invoked by an unprivileged user (not root, not a member of the group stapdev, but a member of the group stapusr and possibly the group stapsys), the options --use-server and --privilege are automatically added to the specified options. This means that unprivileged users on the local host can use a server on the local host in unprivileged mode with no further setup or options required. Normal users (those in none of the SystemTap groups) can also use compile-servers through the --use-server and --privilege options. But they will of course be unable to load the module (the -p4 option can be used to stop short of loading). In order to use a server running on another host, that server's certificate must be installed on the client's host. See the --trust-servers option in the stap(1) manual page for more details and README.unprivileged in the systemtap sources 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 start a server for a kernel release not installed (cross-compiling)
$ [ service ] stap-server start -a ARCH -r /BUILDDIR
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 stop
To restart servers after a global configuration change and/or when
default servers have been added, changed, or removed:
$ [ service ] stap-server force-reload
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. When invoked as a service (i.e. service stap-server ...), each server is run, by default, as the user stap-server. When invoked directly (i.e. stap-server ...), each server is run, by default, as the invoking user. In each case, another user may be selected by using the -u option on invocation, by specifying STAP_USER=username in the global configuration file or by specifying USER=username in an individual server configuration file. The invoking user must have authority to run processes as another user. See CONFIGURATION. The selected user must have write access to the server log file. The location of the server log file may be changed by setting LOG_FILE=path in the global configuration file. See CONFIGURATION. The selected user must have read/write access to the directory containing the server status files. The location of the server status files may be changed by setting STAT_PATH=path in the global configuration file. See CONFIGURATION. The selected user must have read/write access to the uprobes.ko build directory and its files. Neither form of stap-server will run if the selected user is root. 2 Run stap-server requests 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. When the user running the server is stap-server, each server request is run with limits specified in ~stap- server/.systemtap/rc otherwise, no limits are imposed. 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. The default TMPDIR is /tmp/. 4 Activate network firewalls to limit stap client connections to relatively trustworthy networks. For automatic selection of servers by clients, avahi must be installed on both the server and client hosts and mDNS messages must be allowed through the firewall. The systemtap compile server and its related utilities use the Secure Socket Layer (SSL) as implemented by Network Security Services (NSS) for network security. NSS is also used for the generation and management 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
Important files and their corresponding paths can be located in the
stappaths (7) manual page.
SEE ALSO
stap(1), staprun(8), stapprobes(3stap), stappaths(7), stapex(3stap), avahi, ulimit(1), NSS
BUGS
Use the Bugzilla link of the project web page or our mailing list. http://sourceware.org/systemtap/, <[email protected]>. STAP-SERVER(8)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
