Nancy L. Gilman's changes for Beta 4

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@3778 dc483132-0cff-0310-8789-dd5450dbe970

1 files changed, 87 insertions, 10 deletions

diff --git a/src/appl/sample/sserver/sserver.M b/src/appl/sample/sserver/sserver.M
index 07901ee9b5..2c7070a4d9 100644
--- a/src/appl/sample/sserver/sserver.M
+++ b/src/appl/sample/sserver/sserver.M
@@ -30,16 +30,93 @@ sserver \- sample Kerberos version 5 server
 ]
 .br
 .SH DESCRIPTION
-.I sserver
-is usually executed from the internet daemon (\fIinetd\fR(8)) which
-listens on the \fBsample\fR TCP port when a connection from a sample
-client is established.  There is a compile-time option to allow it to
-run without intervention of the internet daemon.
+
+\fIsserver\fP and \fIsclient\fP are a simple demonstration
+client/server application.  When \fIsclient\fP connects to
+\fIsserver\fP, it performs a Kerberos authentication, and then
+\fIsserver\fP returns to \fIsclient\fP the Kerberos
+principal which was used for the Kerberos authentication.  It makes a
+good test that Kerberos has been successfully installed on a machine.
 .PP
-.I server_port
-is an optional argument; if specified, 
-.I sserver
-will listen on the specified port and wait for a connection.  It is used for
-debugging when it is inconvenient to run the sample server out of inetd.
+The service name used by \fIsserver\fP and \fIsclient\fP is
+\fBsample\fP.  Hence, \fIsserver\fP will require that there be a srvtab entry for the service
+"sample/hostname.mit.edu@REALM.NAME".  This srvtab is generated using
+the 
+.IR krb5_edit(8)
+program.  The srvtab file is installed in whatever
+directory is defined by V5Srvtabdir (usually /etc) as "v5srvtab".
+.PP
+\fIsserver\fP is normally invoked out of 
+.IR inetd(8), 
+using a line in
+/etc/inetd.conf that looks like this:
+.PP
+sample  stream  tcp     nowait  root /krb5/sbin/sserver	sserver
+.PP
+Since \fBsample\fP is normally not a port defined in /etc/services, you will
+usually have to add a line to /etc/services which looks like this:
+.PP
+sample          13135/tcp
+.PP
+When using \fIsclient,\fP you will first have to have an entry in the Kerberos
+database, by using 
+.IR kdb5_edit(8),
+and then you have to get Kerberos
+tickets, by using 
+.IR kinit(8).  
+Also, if you are running the \fIsclient\fP
+program on a different host than the \fIsserver\fP it will be
+connecting to, be
+sure that both hosts have an entry in /etc/services for the \fBsample\fP tcp
+port, and that the same port number is in both files.
+.PP
+When you run sclient you should see something like this:
+.PP
+sendauth succeeded, reply is:
+.br
+reply len 32, contents:
+.br
+You are nlgilman@JIMI.MIT.EDU
+.br
+.SH COMMON ERROR MESSAGES
+
+1)  \fIkinit\fP returns the error:
+.PP
+kinit: Client not found in Kerberos database while getting initial credentials
+.PP
+This means that you didn't create an entry for your username in the
+Kerberos database.
+.PP
+2)  \fIsclient\fP returns the error:
+.PP
+unknown service sample/tcp; check /etc/services
+.PP
+This means that you don't have an entry in /etc/services for the
+\fBsample\fP tcp port.
+.PP
+3)  \fIsclient\fP returns the error:
+.PP
+connect: Connection refused
+.PP
+This probably means you didn't edit /etc/inetd.conf correctly, or you
+didn't restart \fIinetd\fP after editing inetd.conf.
+.PP
+4)  \fIsclient\fP returns the error:
+.PP
+/krb5/bin/sclient: Server not found in Kerberos database while using sendauth
+.PP
+This means that the "sample/hostname@LOCAL.REALM" service was not
+defined in the Kerberos database; it should be created using \fIkdb5_edit,\fP
+and a srvtab file needs to be generated to make the key for that service
+principal available for \fIssclient\fP.
+.PP
+5)  \fIsclient\fP returns the error:
+.PP
+sendauth rejected, error reply is:
+        " No such file or directory"
+.PP
+This probably means \fIsserver\fP couldn't find the srvtab file.  It was
+probably not installed in the proper directory.
+.br
 .SH SEE ALSO
 sclient(1), services(5), inetd(8)