path: root/stap-server.8.in

.\" -*- nroff -*-
.TH STAP-SERVER 8 @DATE@ "Red Hat"
.SH NAME
stap-server \- systemtap server and related utilities

.SH SYNOPSIS

.br
.B stap\-start\-server
.br
.B stap\-find\-servers
[
.B \-\-all
]
.br
.B stap\-find\-or\-start\-server
.br
.B stap\-stop\-server
.I PID
.br
.B stap\-authorize\-server\-cert \fICERTFILE\fR [ \fIDIRNAME\fR ]
.br
.B stap\-client
[
.B \-\-server=\fIHOSTNAME\fR|\fIIP_ADDRESS\fR[\fB:\fIPORT\fR]
]
[
.B \-\-ssl=\fIDIRNAME
]
[
.I ARGUMENTS
]

.SH DESCRIPTION

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

.PP
The
.I stap\-start\-server
program attempts to start a systemtap server (\fIstap-serverd\fP)
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
.I 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.

.PP
The
.I 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.

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

.PP
The
.I 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.
.I stap\-stop\-server
does not verify that the server actually shuts down.

.PP
The
.I 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.

.PP
The
.I stap\-client
program is analogous to the
.I 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
.IR staprun .
Upon successful completion, the exit code is 0. Otherwise the exit code
is 1.

.SH OPTIONS
The
.I stap\-find\-servers
program supports the following option.  Any other option
is ignored.
.TP
.B \-\-all
Instructs
.I 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.

.PP
In addition to the options accepted by the
.I stap
front end,
.I stap\-client
accepts the following:

.TP
.B \-\-server=\fIHOSTNAME\fR|\fIIP_ADDRESS\fR[\fB:\fIPORT\fR]
This option instructs
.I 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
.I 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
.I stap\-client
will attempt to connect to the named host on the specified port. This is useful
for connecting to non\-local servers. If
.B \-\-server
is specified,
.I stap\-client
will make no attempt to contact other servers. If more than one
.B \-\-server
option is specified,
.I stap\-client
will attempt to use the servers in the order specified.

.TP
.B \-\-ssl=\fIDIRNAME
.I stap\-client
uses certificate databases in default locations (see
.I SERVER MANAGEMENT
below) in order to authenticate each server which is contacted. The
.B \-\-ssl
option is used to specify additional databases to search. Databases specified
using
.B \-\-ssl
are searched before the default databases. If more than one
.B \-\-ssl
option is specified, then the databases are searched in the order specified on
the command line followed by the default locations.

.SH ARGUMENTS
The
.I stap\-stop\-server
program requires a process id argument which identifies the server to be stopped.

.PP
The
.I stap\-authorize\-server\-cert
program accepts two arguments:

.TP
.B CERTFILE
This is the name of the file containing the certificate of the new trusted
server. This is the file named \fIstap.cert\fR which can be found in the
server\[aq]s certificate database.

.TP
.B 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
.I $HOME/.systemtap/ssl/server\fP.
For root users (EUID=0), the default is
.I $sysconfdir/systemtap/ssl/server\fP.

.PP
The
.I stap\-client
program accepts the same arguments as
.I stap\fP.
See \fIstap\fP(1) for details.

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

.PP
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\[aq]s certificate to the
client\[aq]s database of trusted servers.

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

.IP \(bu 4
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
.I $HOME/.systemtap/ssl/server\fP.
For root users (EUID=0), it will be created in
.I $sysconfdir/systemtap/ssl/server\fP.

.IP \(bu 4
At this time, the
server will also create a local client\-side certificate database and add the
server\[aq]s certificate to it. For non\-root users,
this database will be created in
.I $HOME/.systemtap/ssl/client\fP.
For root users (EUID=0), it will be created in
.I $sysconfdir/systemtap/ssl/client\fP.

In this way, a server started by a given user is automatically trusted by
clients run by that user.

.IP \(bu 4
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.

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

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

.IP \(bu 4
A user may add the certificate of a new trusted server to his own local
client\-side certificate database using
\[aq]\fBstap\-authorize\-server\-cert \fICERTFILE\fR\[aq]
(see above), where \fICERTFILE\fP is the server\[aq]s certificate file
(\fIstap.cert\fP) from the server\[aq]s certificate database directory and
\fIDIRNAME\fP is the
directory containing the user\[aq]s client\-side certificate database.

The server will trusted by clients run by that user from then on.

.PP
When a root (EUID=0) user adds a server\[aq]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.

.SH EXAMPLES
See the 
.IR stapex (3stap)
manual page for a collection of sample scripts.
.PP
Here is a very basic example of how to use
.IR stap\-client .
.PP
To find out if a compatible systemtap server is running on your local network
.PP
.B \& $ stap\-find\-servers
.PP
If no servers are reported, you can start one using
.PP
.B \& $ stap\-start\-server
.PP
You could also have accomplished both of the previous two steps using
.PP
.B \& $ stap\-find\-or\-start\-server
.PP
To compile and execute a simple example using an automatically discovered
server on the local network
.PP
.B \& $ stap\-client \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& Hello World!
.PP
To compile and execute a simple example using a server on a specific host
on the local network
.PP
.B \& $ stap\-client \-\-server=\fIHOSTNAME\fP \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& Hello World!
.PP
To compile and execute a simple example using a specific server
.PP
.B \& $ stap\-client \-\-server=\fIHOSTNAME\fP:\fIPORT\fP \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& Hello World!
.PP
To search additional certificate databases in order to compile and execute a
simple example
.PP
.B \& $ stap\-client \-\-ssl=\fIDIRNAME\fP \-e \[aq]probe begin { printf("Hello World!\\n"); exit() }\[aq]
.br
\& Hello World!
.PP
To permanently trust a given server for your own use
.PP
.B \& $ stap\-authorize\-server\-cert \fICERTFILE\fP
.PP
As root, to permanently trust a given server for all users on your host
.PP
.B \& $ stap\-authorize\-server\-cert \fICERTFILE\fP
.PP
If a process id was echoed by
.I stap\-start\-server
or
.I stap\-find\-or\-start\-server
then you can stop the server using
.PP
.B \& $ stap\-stop\-server \fIPID\fP
.PP
where \fIPID\fR is the process id that was echoed.

.SH SAFETY AND SECURITY
Systemtap is an administrative tool.  It exposes kernel internal data
structures and potentially private user information.  See the 
.IR stap (1)
manual page for additional information on safety and security.

.PP
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
.I 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.

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

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