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
]
The systemtap server listens for connections from stap-client on a secure SSL 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.
In addition to the options accepted by the stap front end, stap-client accepts the following:
The stap-authorize-server-cert program accepts two arguments:
The stap-client program accepts the same arguments as stap. See stap(1) for details.
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:
In this way, a server started by a given user is automatically trusted by clients run by that user.
The trustworthiness of other servers may be asserted in one of two ways:
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.
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.
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.