svn rev #25632: trunk/doc/rst_source/ krb_admins/admin_commands/ krb_users/user_commands/
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Mon Jan 9 16:45:52 EST 2012
http://src.mit.edu/fisheye/changelog/krb5/?cs=25632
Commit By: tsitkova
Log Message:
Added documentation for sserver, sclient and krb5-send-pr in RST format
Changed Files:
U trunk/doc/rst_source/conf.py
U trunk/doc/rst_source/krb_admins/admin_commands/index.rst
A trunk/doc/rst_source/krb_admins/admin_commands/sserver.rst
U trunk/doc/rst_source/krb_users/user_commands/index.rst
A trunk/doc/rst_source/krb_users/user_commands/sclient.rst
A trunk/doc/rst_source/krb_users/user_commands/send-pr.rst
Modified: trunk/doc/rst_source/conf.py
===================================================================
--- trunk/doc/rst_source/conf.py 2012-01-09 21:35:30 UTC (rev 25631)
+++ trunk/doc/rst_source/conf.py 2012-01-09 21:45:52 UTC (rev 25632)
@@ -238,4 +238,7 @@
('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),
]
Modified: trunk/doc/rst_source/krb_admins/admin_commands/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/index.rst 2012-01-09 21:35:30 UTC (rev 25631)
+++ trunk/doc/rst_source/krb_admins/admin_commands/index.rst 2012-01-09 21:45:52 UTC (rev 25632)
@@ -17,6 +17,7 @@
k5srvutil.rst
kadmind.rst
kdb5_ldap_util.rst
+ sserver.rst
------------
Added: trunk/doc/rst_source/krb_admins/admin_commands/sserver.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/sserver.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/admin_commands/sserver.rst 2012-01-09 21:45:52 UTC (rev 25632)
@@ -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 at 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)
+
Modified: trunk/doc/rst_source/krb_users/user_commands/index.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/index.rst 2012-01-09 21:35:30 UTC (rev 25631)
+++ trunk/doc/rst_source/krb_users/user_commands/index.rst 2012-01-09 21:45:52 UTC (rev 25632)
@@ -19,6 +19,8 @@
k5login.rst
../../krb_admins/admin_commands/kadmin_local.rst
../../krb_admins/admin_commands/k5srvutil.rst
+ sclient.rst
+ send-pr.rst
------------------
Added: trunk/doc/rst_source/krb_users/user_commands/sclient.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/sclient.rst (rev 0)
+++ trunk/doc/rst_source/krb_users/user_commands/sclient.rst 2012-01-09 21:45:52 UTC (rev 25632)
@@ -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)
+
Added: trunk/doc/rst_source/krb_users/user_commands/send-pr.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/send-pr.rst (rev 0)
+++ trunk/doc/rst_source/krb_users/user_commands/send-pr.rst 2012-01-09 21:45:52 UTC (rev 25632)
@@ -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.
+
More information about the cvs-krb5
mailing list