.\" -*- 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.
For 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 of the project web page or our mailing list.
.nh
.BR http://sources.redhat.com/systemtap/ ", " <systemtap@sources.redhat.com> .
.hy