From: Zhanna Tsitkov Date: Fri, 29 Jul 2011 19:40:39 +0000 (+0000) Subject: Start building man pages from Sphinx documentation. X-Git-Tag: krb5-1.10-alpha1~313 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=5adcd3c9956c68edfd90623963585ed9bb39535e;p=krb5.git 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 --- 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) + +