Provided by: systemtap-server_2.9-2ubuntu2_amd64 bug

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.

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).

       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/, <systemtap@sourceware.org>.

                                                                                   STAP-SERVER(8)