Start building man pages from Sphinx documentation.

Added kinit document to Sphinx docs.

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

5 files changed, 216 insertions, 2 deletions

diff --git a/doc/rst_source/README b/doc/rst_source/README
index 63d13461f..1aacbbd2d 100644
--- a/doc/rst_source/README
+++ b/doc/rst_source/README
@@ -1,3 +1,6 @@
+HTML
+====
+
 To build the documentation as HTML pages run:
 
 sphinx-build source_dir  destination_dir
@@ -8,3 +11,13 @@ destination_dir is the directory for the built documentation.
 
 Once completed, the newly generated HTML documentation can be viewed from the browser by pointing to destination_dir/index.html
 
+
+MAN PAGES
+=========
+
+Similarly, to build the documentation as man pages run:
+
+sphinx-build -b man source_dir  destination_dir
+
+The list of manual pages to be built should be constructed under man_pages section on conf.py
+
diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py
index 4e6a1e0c8..f958907bb 100644
--- a/doc/rst_source/conf.py
+++ b/doc/rst_source/conf.py
@@ -215,6 +215,5 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'krbdoc', u'MIT Kerberos Documentation',
-     [u'MIT'], 1)
+    ('krb_users/user_commands/kinit', 'kinit', u'obtain and cache Kerberos ticket-granting ticket', [u'MIT'], 1)
 ]
diff --git a/doc/rst_source/krb_users/index.rst b/doc/rst_source/krb_users/index.rst
index 249b48b20..f8a0adefb 100644
--- a/doc/rst_source/krb_users/index.rst
+++ b/doc/rst_source/krb_users/index.rst
@@ -16,6 +16,7 @@ Contents:
    pwd_mgmt/index.rst
    tkt_mgmt/index.rst
    user_appl/index.rst
+   user_commands/index.rst
 
 ------------
 
diff --git a/doc/rst_source/krb_users/user_commands/index.rst b/doc/rst_source/krb_users/user_commands/index.rst
new file mode 100644
index 000000000..00ffedd82
--- /dev/null
+++ b/doc/rst_source/krb_users/user_commands/index.rst
@@ -0,0 +1,22 @@
+User commands
+====================================
+
+.. note:: This document was copied from Kerberos man pages. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   kinit.rst
+   klist.rst
+   kdestroy.rst
+   kpasswd.rst
+
+
+------------------
+
+Feedback:
+
+Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___user_commands
+
+
diff --git a/doc/rst_source/krb_users/user_commands/kinit.rst b/doc/rst_source/krb_users/user_commands/kinit.rst
new file mode 100644
index 000000000..afee487ee
--- /dev/null
+++ b/doc/rst_source/krb_users/user_commands/kinit.rst
@@ -0,0 +1,179 @@
+kinit - obtain and cache Kerberos ticket-granting ticket
+=========================================================
+
+SYNOPSIS
+~~~~~~~~
+
+kinit      
+          [**-V**]
+          [**-l** *lifetime*]
+          [**-s** *start_time*]
+          [**-r** *renewable_life*]
+          [**-p** | -**P**] 
+          [**-f** | -**F**]
+          [**-a**]
+          [**-A**]
+          [**-C**]
+          [**-E**]
+          [**-v**]
+          [**-R**]
+          [**-k** [-**t** *keytab_file*]]
+          [**-c** *cache_name*]
+          [**-n**]
+          [**-S** *service_name*]
+          [**-T** *armor_ccache*]
+          [**-X** *attribute[=value]*]
+          [*principal*]
+
+
+DESCRIPTION
+~~~~~~~~~~~~~
+
+*kinit* obtains and caches an initial  ticket-granting  ticket for principal.
+
+
+OPTIONS
+~~~~~~~
+
+     **-V**   display verbose output.
+
+     **-l** *lifetime*
+          requests a ticket  with  the  lifetime  lifetime.   The
+          value  for lifetime must be followed immediately by one
+          of the following delimiters::
+
+             s  seconds
+             m  minutes
+             h  hours
+             d  days
+
+          as in "kinit -l 90m".  You cannot mix units; a value of "3h30m" will result in an error.
+
+          If the **-l** option is not specified, the  default  ticket lifetime
+          (configured by each site) is used.  Specifying a ticket lifetime longer than the maximum
+          ticket  lifetime (configured by each site) results in a ticket with the maximum lifetime.
+
+     **-s** *start_time*
+          requests  a  postdated  ticket,   valid   starting   at
+          *start_time*.   Postdated  tickets  are  issued  with the
+          *invalid* flag set, and need to be fed back  to  the  kdc
+          before use.
+
+     **-r** *renewable_life*
+          requests renewable tickets, with a  total  lifetime  of
+          *renewable_life*.   The duration is in the same format as
+          the **-l** option, with the same delimiters.
+
+     **-f**   request forwardable tickets.
+
+     **-F**   do not request forwardable tickets.
+
+     **-p**   request proxiable tickets.
+
+     **-P**   do not request proxiable tickets.
+
+     **-a**   request tickets with the local address[es].
+
+     **-A**   request address-less tickets.
+
+     **-C**   requests canonicalization of the principal name.
+
+     **-E**   treats the principal name as an enterprise name.
+
+     **-v**    
+          requests that the ticket granting ticket in  the  cache
+          (with  the  *invalid*  flag set) be passed to the KDC for validation.
+          If the ticket is within its requested time range,
+          the cache is replaced with the validated ticket.
+
+     **-R**
+          requests renewal of the ticket-granting  ticket.
+          Note that  an  expired ticket cannot be renewed, even if the ticket
+          is still within its renewable life.
+
+     **-k** [**-t** *keytab_file*]
+          requests a ticket, obtained from a  key  in  the  local host's  *keytab* file.
+          The name and location of the key tab file may be specified with the 
+          **-t** *keytab_file* option; otherwise the default name and location will be used.
+          By default a host ticket is  requested  but any principal may be specified.
+          On a KDC, the special keytab location **KDB:** can be used to  indicate that kinit
+          should  open the KDC database and look  up the key directly.
+          This permits  an  administrator  to  obtain tickets  as  any principal that
+          supports password-based authentication.
+
+     **-n**
+          Requests anonymous processing.
+          Two types of  anonymous principals  are  supported.
+        
+          For  fully anonymous Kerberos,  configure  pkinit  on  the  KDC  and  configure
+          *pkinit_anchors* in the client's krb5.conf.  Then use the **-n** option with
+          a principal of the form *@REALM* (an empty principal  name  followed  by  the
+          at-sign and a realm name).  If permitted by the KDC,  an  anonymous  ticket will  be  returned.
+    
+          A second form of anonymous tickets is supported;  these  realm-exposed  tickets
+          hide the identity of the client but not the client's realm.
+          For this mode, use **kinit -n** with a normal  principal  name.
+          If  supported by the KDC, the principal (but not realm) will be replaced by the  anonymous  principal.
+
+          As  of release  1.8,  the MIT Kerberos KDC only supports fully anonymous operation.
+
+     **-T** *armor_ccache*
+          Specifies the name of a credential cache  that  already contains  a  ticket.   If  supported  by  the KDC, This
+          ccache will be used to armor the  request  so  that  an attacker  would  have to know both the key of the armor
+          ticket and the key of the principal used for  authentication  in  order  to attack the request. Armoring also
+          makes sure that the response from the KDC is not  modified in transit.
+
+     **-c** *cache_name*
+          use *cache_name* as the Kerberos 5  credentials  (ticket) cache  name  and  location;
+          if this option is not used, the default cache name and location are used.
+
+          The default credentials cache may vary between systems.  If  the  **KRB5CCNAME**  environment  variable  is set, its
+          value is used to name the default  ticket  cache.   Any existing contents of the cache are destroyed by kinit.
+
+     **-S** *service_name*
+          specify an alternate service name to use  when  getting initial tickets.
+
+     **-X** *attribute* [= *value* ]
+          specify a pre-authentication *attribute* and *value* to  be passed  to  pre-authentication plugins.
+          The acceptable attribute and value values vary from pre-authentication plugin  to plugin.
+          This option may be specified multiple times to specify multiple attributes.
+          If no  value is specified, it is assumed to be "yes".
+
+          The following attributes are recognized by the OpenSSL pkinit pre-authentication mechanism:
+
+              **X509_user_identity** = *value*
+
+                   specify where to find user's X509 identity information
+
+              **X509_anchors** = *value*
+
+                   specify where to find trusted X509 anchor information
+
+              **flag_RSA_PROTOCOL** [ = *yes* ]
+
+                   specify use of RSA, rather than the default Diffie-Hellman protocol
+
+
+
+ENVIRONMENT
+~~~~~~~~~~~~~
+
+*kinit* uses the following environment variables:
+
+       **KRB5CCNAME**  Location of the Kerberos 5 credentials (ticket) cache.
+
+
+FILES
+~~~~~~~~
+
+/tmp/krb5cc_[uid]  default location of Kerberos 5 credentials cache ([uid] is the decimal UID of the user).
+
+/etc/krb5.keytab   default location for the local host's keytab file.
+
+
+SEE ALSO
+~~~~~~~~~~~
+
+klist(1), kdestroy(1), kerberos(1)
+
+