Added documentation for sserver, sclient and krb5-send-pr in RST format

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

6 files changed, 311 insertions, 0 deletions

diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py
index 29fd607fe7..3d479ed6f3 100644
--- a/doc/rst_source/conf.py
+++ b/doc/rst_source/conf.py
@@ -238,4 +238,7 @@ man_pages = [
     ('krb_admins/admin_commands/kdb5_ldap_util', 'kdb5_ldap_util', u'Kerberos configuration utility', [u'MIT'], 8),
     ('krb_admins/conf_files/krb5_conf', 'krb5.conf', u'Kerberos configuration file', [u'MIT'], 5),
     ('krb_admins/conf_files/kdc_conf', 'kdc.conf', u'Kerberos V5 KDC configuration file', [u'MIT'], 5),
+    ('krb_users/user_commands/send-pr', 'krb5-send-pr', u'send problem report (PR) to a central support site', [u'MIT'], 1),
+    ('krb_users/user_commands/sclient', 'sclient', u'sample Kerberos version 5 client', [u'MIT'], 1),
+    ('krb_admins/admin_commands/sserver', 'sserver', u'sample Kerberos version 5 server', [u'MIT'], 8),
 ]
diff --git a/doc/rst_source/krb_admins/admin_commands/index.rst b/doc/rst_source/krb_admins/admin_commands/index.rst
index 10bf4e32f5..2d2e4fbc17 100644
--- a/doc/rst_source/krb_admins/admin_commands/index.rst
+++ b/doc/rst_source/krb_admins/admin_commands/index.rst
@@ -17,6 +17,7 @@ Administration  programs
    k5srvutil.rst
    kadmind.rst
    kdb5_ldap_util.rst 
+   sserver.rst
 
 ------------
 
diff --git a/doc/rst_source/krb_admins/admin_commands/sserver.rst b/doc/rst_source/krb_admins/admin_commands/sserver.rst
new file mode 100644
index 0000000000..05dffec09f
--- /dev/null
+++ b/doc/rst_source/krb_admins/admin_commands/sserver.rst
@@ -0,0 +1,94 @@
+.. _sserver(8):
+
+sserver
+========
+
+SYNOPSIS
+------------
+
+**sserver**
+[ **-p** *port* ] 
+[ **-S** *keytab* ] 
+[ *server_port* ]
+
+DESCRIPTION
+---------------
+
+**sserver**  and :ref:`sclient(1)` are a simple demonstration client/server application.  
+When *sclient* connects to *sserver*, it performs a Kerberos authentication, 
+and then sserver returns to *sclient* the Kerberos principal which was used for 
+the Kerberos authentication.  It makes a good test that Kerberos
+has been successfully installed on a machine.
+
+The service name used by *sserver* and *sclient* is sample.  
+Hence, *sserver* will require that there be a keytab entry for the service 
+"sample/hostname.domain.name\@REALM.NAME".  
+This keytab is generated using the  :ref:`kadmin(1)`  program.   
+The keytab file is usually installed as "/etc/krb5.keytab".
+
+The **-S** option allows for a different keytab than the default.
+
+*sserver* is normally invoked out of inetd(8), using a line in /etc/inetd.conf that looks like this::
+
+       sample  stream  tcp     nowait  root /usr/local/sbin/sserver     sserver
+
+Since *sample* is normally not a port defined in /etc/services, 
+you will usually have to add a line to /etc/services which looks like this::
+
+       sample          13135/tcp
+
+When using *sclient*, you will first have to have an entry in the Kerberos database, 
+by using :ref:`kadmin(1)`, and then you have to get Kerberos tickets, by using kinit(1).  
+Also, if you are running the *sclient* program on a different host than the *sserver* 
+it will be connecting to, be sure that both hosts have an entry in /etc/services 
+for the sample tcp port, and that the same port number is in both files.
+
+When you run *sclient* you should see something like this::
+
+       sendauth succeeded, reply is:
+       reply len 32, contents:
+       You are nlgilman@JIMI.MIT.EDU
+
+COMMON ERROR MESSAGES
+-----------------------
+
+1)  *kinit* returns the error::
+
+       kinit: Client not found in Kerberos database while getting initial credentials
+
+    This means that you didn't create an entry for your username in the Kerberos database.
+
+2)  *sclient* returns the error::
+
+       unknown service sample/tcp; check /etc/services
+
+    This means that you don't have an entry in /etc/services for the sample tcp port.
+
+3)  *sclient* returns the error::
+
+       connect: Connection refused
+
+    This probably means you didn't edit /etc/inetd.conf correctly,
+    or you didn't restart inetd after editing inetd.conf.
+
+4)  *sclient* returns the error::
+
+       sclient: Server not found in Kerberos database while using sendauth
+
+    This means that the "sample/hostname\@LOCAL.REALM" service was not defined 
+    in the Kerberos database; it should be created using *kadmin*, and a keytab file
+    needs to be generated to make the key for that service principal available for *sclient*.
+
+5)  *sclient* returns the error::
+
+       sendauth rejected, error reply is:
+               " No such file or directory"
+
+    This probably means *sserver* couldn't find the keytab file.
+    It was probably not installed in the proper directory.
+
+SEE ALSO
+------------
+
+:ref:`sclient(1)`, services(5), inetd(8)
+
diff --git a/doc/rst_source/krb_users/user_commands/index.rst b/doc/rst_source/krb_users/user_commands/index.rst
index 7f374fcd00..a2c14759b9 100644
--- a/doc/rst_source/krb_users/user_commands/index.rst
+++ b/doc/rst_source/krb_users/user_commands/index.rst
@@ -19,6 +19,8 @@ User commands
    k5login.rst
    ../../krb_admins/admin_commands/kadmin_local.rst
    ../../krb_admins/admin_commands/k5srvutil.rst
+   sclient.rst
+   send-pr.rst
 
 
 ------------------
diff --git a/doc/rst_source/krb_users/user_commands/sclient.rst b/doc/rst_source/krb_users/user_commands/sclient.rst
new file mode 100644
index 0000000000..301979d0e1
--- /dev/null
+++ b/doc/rst_source/krb_users/user_commands/sclient.rst
@@ -0,0 +1,22 @@
+.. _sclient(1):
+
+
+sclient 
+=======
+
+SYNOPSIS
+-----------
+
+**sclient** *remotehost*
+
+DESCRIPTION
+-------------
+
+*sclient* will contact a sample server :ref:`sserver(8)` and authenticate 
+to it using Kerberos version 5 tickets, then display the server's response.
+
+SEE ALSO
+----------
+
+kinit(1), sserver(8)
+
diff --git a/doc/rst_source/krb_users/user_commands/send-pr.rst b/doc/rst_source/krb_users/user_commands/send-pr.rst
new file mode 100644
index 0000000000..757d0da85c
--- /dev/null
+++ b/doc/rst_source/krb_users/user_commands/send-pr.rst
@@ -0,0 +1,189 @@
+.. _krb5-send-pr(1):
+
+
+krb5-send-pr - send problem report (PR) to a central support site
+=======================================================================
+
+SYNOPSIS
+-----------
+
+**krb5-send-pr**
+[ *site* ] 
+[ **-f** *problem-report* ] 
+[ **-t** *mail-address* ]
+[ **-P** ] 
+[ **-L** ] 
+[ **-s** *severity* ] 
+[ **-c** *address* ]
+[ **--request-id** ] 
+[ **-V** ]
+
+DESCRIPTION
+--------------
+
+*krb5-send-pr* is a tool used to submit problem reports (PRs) to a central support site.  
+In most cases the correct *site* will be the default.  
+This argument indicates the support site which is responsible 
+for the category of problem involved.  
+Some sites may use a local address as a default.  
+*site* values are defined by using the aliases(5).
+
+*krb5-send-pr* invokes an editor on a problem report template 
+(after trying to fill in some fields with reasonable default values).  
+When you exit the editor, *krb5-send-pr* sends  the completed form 
+to the *Problem Report Management System* (**GNATS**) at a central support site.  
+At the support site, the PR is assigned a unique number and is stored 
+in the GNATS database according to its category and submitter-id.  
+GNATS automatically replies with an acknowledgement, 
+citing the category and the PR number.
+
+To ensure that a PR is handled promptly, it should contain your (unique) 
+*submitter-id* and one of the available *categories* to identify the problem area.
+(Use  `krb5-send-pr -L` to see a list of categories.)
+
+The *krb5-send-pr* template at your site should already be customized 
+with your *submitter-id* (running `install-sid submitter-id` to accomplish 
+this is part of the installation procedures for *krb5-send-pr*).  
+If this hasn't been done, see your system administrator for your *submitter-id*, 
+or request one from your support site by invoking  `krb5-send-pr --request-id`.  
+If your site does not distinguish between different user sites, 
+or if you are not affiliated with the support site, use `net` for this field.
+
+The more precise your problem description and the more complete your information, 
+the faster your support team can solve your problems.
+
+
+OPTIONS
+---------
+
+**-f** *problem-report*
+       Specify a file  *problem-report* which already contains a complete problem report.  
+       *krb5-send-pr sends* the contents of the file without invoking the editor.
+       If the value for problem-report is "-", then *krb5-send-pr* reads from standard input.
+
+**-s** *severity*
+       Give the problem report the severity *severity*.
+
+**-t** *mail-address*
+       Change mail address at the support site for problem reports.
+       The default mail-address is the address used for the default site.
+       Use the site argument rather than this option in nearly all cases.
+
+**-c** *address*
+       Put *address* in the *Cc:* header of the message.
+
+**-P**
+       Print the form specified by the environment variable *PR_FORM* on standard output.
+       If *PR_FORM* is not set, print the standard blank PR template.  No mail is sent.
+
+**-L**
+       Print the list of available categories.  No mail is sent.
+
+**--request-id**
+       Sends mail to the default support site, or site if specified,
+       with a request for your *submitter-id*.
+       If you are not affiliated with site, use a *submitter-id* of `net`.
+
+**-V**
+       Display the *krb5-send-pr* version number.
+
+
+.. note:: Use *krb5-send-pr* to submit problem reports rather than mailing them directly.
+          Using both the template and *krb5-send-pr* itself will help ensure all
+          necessary information will reach the support site.
+
+ENVIRONMENT
+------------
+
+The environment variable *EDITOR* specifies the editor to invoke on the template.
+Default: *vi*.
+
+If the environment variable *PR_FORM* is set, then its value is used as 
+the file name of the template for your problem-report editing session.  
+You can use this to start with a partially completed form 
+(for example, a form with the identification fields already completed).
+
+
+HOW TO FILL OUT A PROBLEM REPORT
+---------------------------------
+
+Problem reports have to be in a particular form so that a program can 
+easily manage them.  Please remember the following guidelines:
+
+    - Describe only one problem with each problem report.
+
+    - For follow-up mail, use the same subject line as the one 
+      in the automatic acknowledgent. 
+      It consists of category, PR number and the original synopsis line.  
+      This allows the support site to relate several mail messages 
+      to a particular PR and to record them automatically.
+
+    - Please try to be as accurate as possible in the subject and/or synopsis line.
+
+    - The subject and the synopsis line are not confidential.  
+      This is because open-bugs lists are compiled from them.  
+      Avoid confidential information there.
+
+See the GNU Info file *krb5-send-pr.info* or the document 
+Reporting Problems With *krb5-send-pr* for detailed information on reporting problems.
+
+HOW TO SUBMIT TEST CASES, CODE, ETC.
+---------------------------------------
+
+Submit small code samples with the PR.  
+Contact the support site for instructions on submitting larger test cases 
+and problematic source code.
+
+FILES
+----------
+
+/tmp/p$$     copy of PR used in editing session
+
+/tmp/pf$$    copy of empty PR form, for testing purposes
+
+/tmp/pbad$$  file for rejected PRs
+
+EMACS USER INTERFACE
+---------------------
+
+An Emacs user interface for *krb5-send-pr* with completion of field values 
+is part of the *krb5-send-pr* distribution (invoked with `M-x krb5-send-pr`).  
+See the file *krb5-send-pr.info* or the ASCII file INSTALL in the top level 
+directory of the distribution for configuration and installation information.  
+The Emacs LISP template file is *krb5-send-pr-el.in* and is installed as *krb5-send-pr.el*.
+
+
+INSTALLATION AND CONFIGURATION
+--------------------------------
+
+See *krb5-send-pr.info* or INSTALL for installation instructions.
+
+SEE ALSO
+-----------
+
+Reporting Problems Using *krb5-send-pr* (also installed as the GNU Info file *krb5-send-pr.info*).
+
+gnats(l), query-pr(1), edit-pr(1), gnats(8), queue-pr(8), at-pr(8), mkcat(8), mkdist(8).
+
+AUTHORS
+-----------
+
+Jeffrey Osier, Brendan Kehoe, Jason Merrill, Heinz G. Seidl (Cygnus Support)
+
+COPYING
+--------
+
+Copyright (c) 1992, 1993 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this manual 
+provided the copyright notice and this permission notice are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this manual 
+under the conditions for verbatim copying, provided that the entire resulting
+derived work is distributed under the terms of a permission notice identical to this one.
+
+Permission  is granted to copy and distribute translations of this manual 
+into another language, under the above conditions for modified versions, 
+except that this permission notice may be included in translations approved 
+by the Free Software Foundation instead of in the original English.
+