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:
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.
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.
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!
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.