NAME
stap-client - systemtap client
SYNOPSIS
stap-client [ --server=HOSTNAME|IP_ADDRESS[:PORT] ] [ --ssl=DIRNAME ] [
ARGUMENTS ]
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-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.
OPTIONS
In addition to the options accepted by the stap front end, stap-client
accepts the following:
--server=HOSTNAME|IP_ADDRESS[:PORT]
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
specified.
--ssl=DIRNAME
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
locations.
ARGUMENTS
The stap-client program accepts the same arguments as stap. See
stap(1) for details.
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 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.
UNPRIVILEGED USERS
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
capabilities.
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
user.
EXAMPLES
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!
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.
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/systemtap/ssl/client/
Public (root's) client side certificate database.
~/.systemtap/ssl/client/
User's private client side certificate database.
/var/lib/stap-server/.systemtap/ssl/server/stap.cert
Server certificate for servers started by the stap-server
service.
SEE ALSO
stap(1), staprun(8), stap-server(8), stap-authorize-server-cert(8),
stapprobes(3stap), stapfuncs(3stap), stapex(3stap), 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>.