1 files changed, 107 insertions, 0 deletions
diff --git a/stap-authorize-signing-cert.8.in b/stap-authorize-signing-cert.8.in
new file mode 100644
index 00000000..0813cc88
--- /dev/null
+++ b/stap-authorize-signing-cert.8.in
@@ -0,0 +1,107 @@
+.\" -*- nroff -*-
+.TH STAP-AUTHORIZE-SIGNING-CERT 8 @DATE@ "Red Hat"
+.SH NAME
+stap\-authorize\-signing\-cert \- systemtap signing authorization utility
+
+.SH SYNOPSIS
+
+.br
+.B stap\-authorize\-signing\-cert \fICERTFILE\fR [ \fIDIRNAME\fR ]
+
+.SH DESCRIPTION
+
+The \fIstaprun\fR program will load modules for members of the group
+\fIstapusr\fR if they are signed by a trusted signer. A trusted signer is
+usually a \fIsystemtap\fR compile server which signs modules when the client
+(\fIstap\-client\fR) specifies the \fB\-\-unprivileged\fR option.
+
+.PP
+The trustworthiness of a given signer can not be determined
+automatically without a trusted certificate authority issuing systemtap signing
+certificates. This is
+not practical in everyday use and so, \fIstaprun\fR must authenticate servers
+against its own database of trusted signers. In this context,
+establishing a given signer as trusted means adding
+that signer\[aq]s certificate to
+\fIstaprun\fR\[aq]s
+database of trusted signers.
+
+.PP
+The
+.I stap\-authorize\-signing\-cert
+program adds the given signing certificate to the given
+certificate database, making that signer a trusted server for
+\fIstaprun\fR when using
+that database.
+
+.SH ARGUMENTS
+The
+.I stap\-authorize\-signing\-cert
+program accepts two arguments:
+
+.TP
+.B CERTFILE
+This is the name of the file containing the certificate of the new trusted
+signer. 
+For systemtap compile servers, 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
+certificate database to which the certificate is to be added. If not specified,
+the
+default is
+.I @sysconfdir@/systemtap/staprun/\fP.
+That is, the default result
+is that all users on the local host will trust this signer. Note that this
+default directory is only writable by root.
+
+.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
+\fISystemtap\fR uses Network Security Services (NSS)
+for module signing and verification. 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. \fIstaprun\fR will check for proper
+access permissions before making use of any certificate database.
+
+.SH FILES
+.TP
+@sysconfdir@/staprun/
+\fIstaprun\fR\[aq]s trusted signer certificate database.
+
+.TP
+/var/lib/stap\-server/.systemtap/ssl/server/stap.cert
+Signing 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\-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