From: Zhanna Tsitkov Date: Mon, 9 Jan 2012 21:45:52 +0000 (+0000) Subject: Added documentation for sserver, sclient and krb5-send-pr in RST format X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=d60a71b2808ee07b276133bd246a50f042379ebd;p=krb5.git 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 --- diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py index 29fd607fe..3d479ed6f 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 10bf4e32f..2d2e4fbc1 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 000000000..05dffec09 --- /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 7f374fcd0..a2c14759b 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 000000000..301979d0e --- /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 000000000..757d0da85 --- /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. +