Man Linux: Main Page and Category List


       stap-client - systemtap client


       stap-client [ --server=HOSTNAME|IP_ADDRESS[:PORT] ] [ --ssl=DIRNAME ] [
       ARGUMENTS ]


       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-client program is analogous to the stap front end except  that
       it  attempts to find a compatible systemtap server on the local network
       and then attempts to use that server for actions related  to  passes  1
       through  4.  Pass  5  actions, if requested, are performed on the local
       host using staprun.  Upon successful completion, the exit  code  is  0.
       Otherwise the exit code is 1.


       In  addition to the options accepted by the stap front end, stap-client
       accepts the following:

              This option  instructs  stap-client  to  use  the  named  server
              instead  of  looking  for  one  automatically. The server may be
              specified using a valid host name or ip address. If no  port  is
              specified,  then  stap-client  searches for the server among the
              servers on  the  specified  host  which  are  advertising  their
              presence  on  the local network and uses the port which is being
              advertised. This is useful for connecting to a  specific  server
              on  the  local network. If a port is specified, then stap-client
              will attempt to connect to the named host on the specified port.
              This  is useful for connecting to non-local servers. If --server
              is specified, stap-client will make no attempt to contact  other
              servers.   If  more  than  one  --server  option  is  specified,
              stap-client will  attempt  to  use  the  servers  in  the  order

              stap-client uses certificate databases in default locations (see
              SERVER AUTHENTICATION  below)  in  order  to  authenticate  each
              server  which  is contacted. The --ssl option is used to specify
              additional databases to search. Databases specified using  --ssl
              are  searched  before  the  default  databases. If more than one
              --ssl option is specified, then the databases  are  searched  in
              the  order specified on the command line followed by the default


       The stap-client program  accepts  the  same  arguments  as  stap.   See
       stap(1) for details.


       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  service,  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 service, 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.

       The  trustworthiness  of  other  servers  may  also be asserted for the
       duration of one invocation of stap-client by using the --ssl option one
       or  more  times  (see  OPTIONS  above).  Servers whose certificates are
       contained in the additional databases will be considered to be  trusted
       for that invocation of the client.


       One  purpose  of the systemtap client and server is to provide a secure
       compilation environment and trusted signer  for  allowing  unprivileged
       users  (members  of  the  group  stapusr)  to  load  systemtap  modules
       generated from scripts which use only  a  safe  subset  of  systemtap's

       When the --unprivileged option is used on an invocation of stap-client,
       the server will pass it on to stap which will check to ensure that  the
       script  is  safe  to run for unprivileged users. If so, the server will
       also sign the resulting module, making it loadable by  an  unprivileged


       See the stapex(3stap) manual page for a collection of sample scripts.

       Here are some examples of how to use stap-client.

       To  compile  and  execute  a  simple  example  using  an  automatically
       discovered server on the local network

        $ stap-client -e 'probe begin { printf("Hello World!0); exit() }'
        Hello World!

       To compile and execute a simple example using a server  on  a  specific
       host on the local network

         $  stap-client  --server=HOSTNAME  -e  'probe  begin  { printf("Hello
       World!0); exit() }'
        Hello World!

       To compile and execute a simple example using a specific server

        $ stap-client --server=HOSTNAME:PORT -e 'probe begin  {  printf("Hello
       World!0); exit() }'
        Hello World!

       To  search  additional  certificate  databases  in order to compile and
       execute a simple example

        $ stap-client --ssl=DIRNAME -e 'probe begin { printf("Hello  World!0);
       exit() }'
        Hello World!


       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.

       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.


              Public (root's) client side certificate database.

              User's private client side certificate database.

              Server  certificate  for  servers  started  by  the  stap-server


       stap(1),   staprun(8),  stap-server(8),  stap-authorize-server-cert(8),
       stapprobes(3stap), stapfuncs(3stap), stapex(3stap), NSS, certutil


       Use the Bugzilla link of the project web  page  or  our  mailing  list., <>.