STAP-SERVER(8)

NAME
stap-server - systemtap server and related utilities

SYNOPSIS
stap-start-server
stap-find-servers [ --all ]
stap-find-or-start-server
stap-stop-server PID
stap-authorize-server-cert CERTFILE [ DIRNAME ]
stap-client [ --server=HOSTNAME|IP_ADDRESS[:PORT] ] [ --ssl=DIRNAME ] [ ARGUMENTS ]

DESCRIPTION
The systemtap server listens for connections from stap-client on a secure SLL network port and accepts requests to run the stap front end.

The stap-start-server program attempts to start a systemtap server (stap-serverd) on the local host. Upon successful startup, the server listens for connections on a random port and advertises its presence on the local network using the avahi daemon. If the server is successfully started, its process id is echoed to stdout and the exit code is 0. Otherwise, nothing is echoed and the exit code is 1.

The stap-find-servers program attempts to find systemtap servers running on the local network. The details of any servers found are echoed to stdout. If servers are found, then the exit code is 0, otherwise it is 1.

The stap-find-or-start-server program attempts to find a compatible systemtap server running on the local network using stap-find-servers. If a compatible server is found, stap-find-or-start-server echoes '0' to stdout. Otherwise stap-find-or-start-server attempts to start a server on the local network using stap-start-server. If successful, the process id of the new server is echoed to stdout. If no server can be found or started, '-1' is echoed to stdout. The exit code is 0 in all cases.

The stap-stop-server program verifies that the given process id is that of a running systemtap server on the local host and, if so, attempts to shut down the server by sending it the SIGTERM signal. If a process id is provided and it is that of a running systemtap server, the exit code is 0. Otherwise the exit code is 1. stap-stop-server does not verify that the server actually shuts down.

The stap-authorize-server-cert program adds the given server certificate to the given client-side certificate database, making that server a trusted server for clients using that database.

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
The stap-find-servers program supports the following option. Any other option is ignored.

--all
    Instructs stap-find-servers to report all systemtap servers on the local network regardless of compatibility. The default behavior is to report only servers which are compatible with systemtap on the local host.

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 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 MANAGEMENT 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-stop-server program requires a process id argument which identifies the server to be stopped.

The stap-authorize-server-cert program accepts two arguments:

CERTFILE
    This is the name of the file containing the certificate of the new trusted server. This is the file named stap.cert which can be found in the server's certificate database.

DIRNAME
    This optional argument is the name of the directory containing the client-side certificate database to which the certificate is to be added. If not specified, the default, for non-root users, is $HOME/.systemtap/ssl/server. For root users (EUID=0), the default is $sysconfdir/systemtap/ssl/server.

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

SERVER MANAGEMENT
The security of the SSL network connection between the client and server and of the signing and verification of the server's response depend on the proper management of server certificates and the public and private key pairs with which they are signed and verified.

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

The implementation of the client and server have automated many of the tasks required. In particular:

•   When a user starts a server for the first time, the server will generate its own certificate and add it to a database local to that user. For non-root users, this database will be created in $HOME/.systemtap/ssl/server. For root users (EUID=0), it will be created in $sysconfdir/systemtap/ssl/server.

•   At this time, the server will also create a local client-side certificate database and add the server's certificate to it. For non-root users, this database will be created in $HOME/.systemtap/ssl/client. For root users (EUID=0), it will be created in $sysconfdir/systemtap/ssl/client. In this way, a server started by a given user is automatically trusted by clients run by that user.

•   The client-side certificate database created for root users is also the global client-side database for all clients on the host. In this way, a server started by root is automatically trusted by clients run by any user on that host.

The trustworthiness of other servers may be asserted in one of two ways:

•   Other existing client-side certificate databases may be searched by using the --ssl option one or more times when running the client (see OPTIONS above). Servers whose certificates are contained in the additional databases will be considered to be trusted for that invocation of the client.

•   A user may add the certificate of a new trusted server to his own local client-side certificate database using 'stap-authorize-server-cert CERTFILE' (see above), where CERTFILE is the server's certificate file (stap.cert) from the server's certificate database directory and DIRNAME is the directory containing the user's client-side certificate database. The server will trusted by clients run by that user from then on.

When a root (EUID=0) user adds a server's certificate to their client-side certificate database, which is also the global database for all users on that host, they assert the trustworthiness of that server for all users on that host.

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

Here is a very basic example of how to use stap-client.

To find out if a compatible systemtap server is running on your local network

$ stap-find-servers

If no servers are reported, you can start one using

$ stap-start-server

You could also have accomplished both of the previous two steps using

$ stap-find-or-start-server

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!

To permanently trust a given server for your own use

$ stap-authorize-server-cert CERTFILE

As root, to permanently trust a given server for all users on your host

$ stap-authorize-server-cert CERTFILE

If a process id was echoed by stap-start-server or stap-find-or-start-server then you can stop the server using

$ stap-stop-server PID

where PID is the process id that was echoed.

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 and server will both check for proper access permissions before making use of any certificate database.

SEE ALSO
stap(1), staprun(8), stapprobes(3stap), stapfuncs(3stap), stapex(3stap), NSS, certutil

BUGS
Use the Bugzilla link off of the project web page or our mailing list. http://sources.redhat.com/systemtap/, <systemtap@sources.redhat.com>.