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!\n); 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!\n); 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!\n); 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!\n); 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.