Provided by: systemtap-server_1.6-1ubuntu1_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  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 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).

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.  The  default  location  of
       these  files  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 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).

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  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),  the  options  --use-server  and  --unprivileged  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.

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

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  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 servers is stap-server, each server is run with limits
              equivalent to

                ulimit -f 50000 -s 1000 -t 60 -u 20 -v 500000

              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),  stapfuncs(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)