1 files changed, 118 insertions, 0 deletions
diff --git a/stap-authorize-server-cert.8.in b/stap-authorize-server-cert.8.in
new file mode 100644
index 00000000..5fae0237
--- /dev/null
+++ b/stap-authorize-server-cert.8.in
@@ -0,0 +1,118 @@
+.\" -*- nroff -*-
+.TH STAP-AUTHORIZE-SERVER-CERT 8 @DATE@ "Red Hat"
+.SH NAME
+stap\-authorize\-server\-cert \- systemtap server authorization utility
+
+.SH SYNOPSIS
+
+.br
+.B stap\-authorize\-server\-cert \fICERTFILE\fR [ \fIDIRNAME\fR ]
+
+.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 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
+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.
+
+.SH ARGUMENTS
+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.
+On the server host,
+for servers started by the \fIstap\-server\fR service, this database can be
+found in \fI/var/lib/stap\-server/.systemtap/ssl/server/\fR.
+Ror servers run by other non\-root users,
+this database can be found in
+.I $HOME/.systemtap/ssl/server/\fP.
+For root users (EUID=0), it can be found in
+.I @sysconfdir@/systemtap/ssl/server\fP.
+
+.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/client\fP.
+For root users (EUID=0), the default is
+.I @sysconfdir@/systemtap/ssl/client\fP, which is the global client\-side
+certificate database.
+That is, the default result
+is that all users on the client host will trust this server
+when \fIstap\-authorize\-server\-cert\fR is run by root and that only the user
+running \fIstap\-authorize\-server\-cert\fR will trust the server otherwise.
+
+.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 stap\-server (8),
+.IR stap\-client (8),
+.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