PR 10889: Reorganize client/server man pages. Document --unprivileged.

1 files changed, 232 insertions, 0 deletions

diff --git a/stap-client.8.in b/stap-client.8.in
new file mode 100644
index 00000000..c8db45ee
--- /dev/null
+++ b/stap-client.8.in
@@ -0,0 +1,232 @@
+.\" -*- nroff -*-
+.TH STAP-CLIENT 8 @DATE@ "Red Hat"
+.SH NAME
+stap\-client \- systemtap client
+
+.SH SYNOPSIS
+
+.br
+.B stap\-client
+[
+.B \-\-server=\fIHOSTNAME\fR|\fIIP_ADDRESS\fR[\fB:\fIPORT\fR]
+]
+[
+.B \-\-ssl=\fIDIRNAME
+]
+[
+.I ARGUMENTS
+]
+
+.SH DESCRIPTION
+
+A systemtap compile server listens for connections from clients
+(\fIstap\-client\fR)
+on a secure SSL network port and accepts requests to run the
+.I stap
+front end. Each server advertises its presence and configuration on the local
+network using mDNS (\fIavahi\fR) allowing for automatic detection by clients.
+
+.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
+.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 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
+.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 AUTHENTICATION
+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\-client
+program accepts the same arguments as
+.I stap\fP.
+See \fIstap\fP(1) for details.
+
+.SH SERVER AUTHENTICAION
+The security of the SSL network connection between the client and server
+depends on the proper
+management of server certificates.
+
+.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 database 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
+For the \fIstap\-server\fR service, on the local host, this is handled
+automatically.
+When the \fIsystemtap\-server\fR package is installed, the server\[aq]s
+certificate for the default user (\fIstap\-server\fR) is automatically
+generated and installed. This means that servers started by the
+\fIstap\-server\fR service,
+with the default user, are automatically trusted by clients on the local
+host.
+
+.PP
+In order to use a server running on another host, that server\[aq]s certificate
+must be installed on the client\[aq]s host.
+See the
+.IR stap\-authorize\-server\-cert (8)
+manual page for more details.
+
+.PP
+The trustworthiness of other servers may also be asserted
+for the duration of one invocation of \fIstap\-client\fR
+by using the.B \-\-ssl
+option one or more times (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.
+
+.SH 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 \fIstapusr\fR) to load systemtap modules generated from
+scripts which use only a safe subset of systemtap\[aq]s capabilities.
+
+.PP
+When the \fB\-\-unprivileged\fR option is used on an invocation of
+\fIstap\-client\fR, the server will pass it on to \fIstap\fR 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.
+
+.SH EXAMPLES
+See the 
+.IR stapex (3stap)
+manual page for a collection of sample scripts.
+.PP
+Here are some examples of how to use
+.IR stap\-client .
+.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!
+
+.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 will check for proper
+access permissions before making use of any certificate database.
+
+.SH FILES
+.TP
+@sysconfdir@/systemtap/ssl/client/
+Public (root\[aq]s) client side certificate database.
+
+.TP
+~/.systemtap/ssl/client/
+User\[aq]s private client side certificate database.
+
+.TP
+/var/lib/stap\-server/.systemtap/ssl/server/stap.cert
+Server certificate for servers started by the \fIstap\-server\fR service.
+
+.SH SEE ALSO
+.IR stap (1),
+.IR staprun (8),
+.IR stap\-server (8),
+.IR stap\-authorize\-server\-cert (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