svn rev #25069: trunk/doc/rst_source/ krb_admins/ krb_admins/admin_commands/ ...
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Wed Aug 3 13:50:23 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=25069
Commit By: tsitkova
Log Message:
Added kadmin_local and krb5kdc admin programs to Sphinx doc tree.
Changed the reference labels in krb5/kdc.conf files for them to appear properly in the man pages.
Changed Files:
U trunk/doc/rst_source/conf.py
A trunk/doc/rst_source/krb_admins/admin_commands/
A trunk/doc/rst_source/krb_admins/admin_commands/index.rst
A trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
A trunk/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst
U trunk/doc/rst_source/krb_admins/conf_files/kdc_conf.rst
U trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst
U trunk/doc/rst_source/krb_admins/conf_ldap.rst
U trunk/doc/rst_source/krb_admins/database/incr_db_prop.rst
U trunk/doc/rst_source/krb_admins/index.rst
U trunk/doc/rst_source/krb_admins/install_clients/cl_config.rst
U trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst
U trunk/doc/rst_source/krb_admins/realm_config/kdc_hn.rst
U trunk/doc/rst_source/krb_admins/realm_config/kdc_ports.rst
U trunk/doc/rst_source/krb_admins/realm_config/mapping_hn.rst
Modified: trunk/doc/rst_source/conf.py
===================================================================
--- trunk/doc/rst_source/conf.py 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/conf.py 2011-08-03 17:50:23 UTC (rev 25069)
@@ -224,4 +224,6 @@
('krb_users/user_commands/kpasswd', 'kpasswd', u'change a user\'s Kerberos password', [u'MIT'], 1),
('krb_users/user_commands/kvno', 'kvno', u'print key version numbers of Kerberos principals', [u'MIT'], 1),
('krb_users/user_commands/ksu', 'ksu', u'Kerberized super-user', [u'MIT'], 1),
+ ('krb_admins/admin_commands/krb5kdc', 'krb5kdc', u'Kerberos V5 KDC', [u'MIT'], 8),
+ ('krb_admins/admin_commands/kadmin_local', 'kadmin.local', u'Kerberos V5 database administration program', [u'MIT'], 8),
]
Added: trunk/doc/rst_source/krb_admins/admin_commands/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/index.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/admin_commands/index.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -0,0 +1,19 @@
+Administration programs
+============================
+
+.. note:: This document was copied from Kerberos man pages. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs at mit.edu. Your contribution is greatly appreciated.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ krb5kdc.rst
+ kadmin_local.rst
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___admin_commands
+
Added: trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -0,0 +1,710 @@
+kadmin - Kerberos V5 database administration program
+============================================================
+
+SYNOPSYS
+--------------
+
+**kadmin**
+ [ **-O** | **-N** ]
+ [**-r** *realm*]
+ [**-p** *principal*]
+ [**-q** *query*]
+ [[**-c** *cache_name*] | [**-k** [**-t** *keytab* ]] | **-n**]
+ [**-w** *password*]
+ [**-s** *admin_server* [:*port*]
+
+
+**kadmin.local**
+ [**-r** *realm*]
+ [**-p** *principal*]
+ [**-q** *query*]
+ [**-d** *dbname*]
+ [**-e** "enc:salt ..."]
+ [**-m**]
+ [**-x** *db_args*]
+
+
+DESCRIPTION
+------------
+
+*kadmin* and *kadmin.local* are command-line interfaces to the Kerberos V5 KADM5 administration system.
+Both *kadmin* and *kadmin.local* provide identical functionalities;
+the difference is that *kadmin.local* runs on the master KDC if the database is db2 and does not use Kerberos to authenticate to the database.
+Except as explicitly noted otherwise, this man page will use *kadmin* to refer to both versions.
+*kadmin* provides for the maintenance of Kerberos principals, KADM5 policies, and service key tables (keytabs).
+
+The remote version uses Kerberos authentication and an encrypted RPC, to operate securely from anywhere on the network.
+It authenticates to the KADM5 server using the service principal *kadmin/admin*.
+If the credentials cache contains a ticket for the *kadmin/admin* principal, and the *-c* credentials_cache option is specified,
+that ticket is used to authenticate to KADM5.
+Otherwise, the *-p* and *-k* options are used to specify the client Kerberos principal name used to authenticate.
+Once *kadmin* has determined the principal name, it requests a *kadmin/admin* Kerberos service ticket from the KDC,
+and uses that service ticket to authenticate to KADM5.
+
+If the database is db2, the local client *kadmin.local*, is intended to run directly on the master KDC without Kerberos authentication.
+The local version provides all of the functionality of the now obsolete kdb5_edit(8), except for database dump and load,
+which is now provided by the kdb5_util(8) utility.
+
+If the database is LDAP, *kadmin.local* need not be run on the KDC.
+
+*kadmin.local* can be configured to log updates for incremental database propagation.
+Incremental propagation allows slave KDC servers to receive principal and policy updates incrementally instead of receiving full dumps of the database.
+This facility can be enabled in the :ref:`kdc.conf` file with the *iprop_enable* option.
+See the :ref:`kdc.conf` documentation for other options for tuning incremental propagation parameters.
+
+
+OPTIONS
+------------
+
+ **-r** *realm*
+ Use realm as the default database realm.
+
+ **-p** *principal*
+ Use principal to authenticate. Otherwise, *kadmin* will append "/admin" to the primary principal name of the default ccache, the
+ value of the *USER* environment variable, or the username as obtained with *getpwuid*, in order of preference.
+
+ **-k**
+ Use a *keytab* to decrypt the KDC response instead of prompting for a password on the TTY. In this case, the default principal
+ will be *host/hostname*. If there is not a *keytab* specified with the **-t** option, then the default *keytab* will be used.
+
+ **-t** *keytab*
+ Use *keytab* to decrypt the KDC response. This can only be used with the **-k** option.
+
+ **-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 :ref:`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.
+
+ **-c** *credentials_cache*
+ Use *credentials_cache* as the credentials cache. The *credentials_cache* should contain a service ticket for the *kadmin/admin* service;
+ it can be acquired with the kinit(1) program. If this option is not specified, *kadmin* requests a new service ticket from
+ the KDC, and stores it in its own temporary ccache.
+
+ **-w** *password*
+ Use *password* instead of prompting for one on the TTY.
+
+ .. note:: Placing the password for a Kerberos principal with administration access into a shell script can be dangerous if
+ unauthorized users gain read access to the script.
+
+ **-q** *query*
+ pass query directly to kadmin, which will perform query and then exit. This can be useful for writing scripts.
+
+ **-d** *dbname*
+ Specifies the name of the Kerberos database. This option does not apply to the LDAP database.
+
+ **-s** *admin_server* [:port]
+ Specifies the admin server which *kadmin* should contact.
+
+ **-m** Do not authenticate using a *keytab*. This option will cause *kadmin* to prompt for the master database password.
+
+ **-e** enc:salt_list
+ Sets the list of encryption types and salt types to be used for any new keys created.
+
+ **-O** Force use of old AUTH_GSSAPI authentication flavor.
+
+ **-N** Prevent fallback to AUTH_GSSAPI authentication flavor.
+
+ **-x** *db_args*
+ Specifies the database specific arguments.
+
+ Options supported for LDAP database are:
+
+ **-x** host=<hostname>
+ specifies the LDAP server to connect to by a LDAP URI.
+
+ **-x** binddn=<bind_dn>
+ specifies the DN of the object used by the administration server to bind to the LDAP server. This object should have the
+ read and write rights on the realm container, principal container and the subtree that is referenced by the realm.
+
+ **-x** bindpwd=<bind_password>
+ specifies the password for the above mentioned binddn. It is recommended not to use this option.
+ Instead, the password can be stashed using the stashsrvpw command of *kdb5_ldap_util*.
+
+
+DATE FORMAT
+--------------
+
+Various commands in *kadmin* can take a variety of date formats, specifying durations or absolute times.
+Examples of valid formats are::
+
+ 1 month ago
+ 2 hours ago
+ 400000 seconds ago
+ last year
+ this Monday
+ next Monday
+ yesterday
+ tomorrow
+ now
+ second Monday
+ a fortnight ago
+ 3/31/92 10:00:07 PST
+ January 23, 1987 10:05pm
+ 22:00 GMT
+
+Dates which do not have the "ago" specifier default to being absolute dates, unless they appear in a field where a duration is expected.
+In that case the time specifier will be interpreted as relative.
+Specifying "ago" in a duration may result in unexpected behavior.
+
+
+COMMANDS
+-----------
+
+ **add_principal** [options] *newprinc*
+ creates the principal newprinc, prompting twice for a password. If no policy is specified with the *-policy* option,
+ and the policy named "default" exists, then that policy is assigned to the principal;
+ note that the assignment of the policy "default" only occurs automatically when a principal is first created,
+ so the policy "default" must already exist for the assignment to occur.
+ This assignment of "default" can be suppressed with the *-clearpolicy* option.
+
+ .. note:: This command requires the *add* privilege.
+
+ Aliases::
+
+ addprinc and ank.
+
+ The options are:
+
+ **-x** *db_princ_args*
+ Denotes the database specific options. The options for LDAP database are:
+
+ **-x** dn=<dn>
+ Specifies the LDAP object that will contain the Kerberos principal being created.
+
+ **-x** linkdn=<dn>
+ Specifies the LDAP object to which the newly created Kerberos principal object will point to.
+
+ **-x** containerdn=<container_dn>
+ Specifies the container object under which the Kerberos principal is to be created.
+
+ **-x** tktpolicy=<policy>
+ Associates a ticket policy to the Kerberos principal.
+
+ **-expire** *expdate*
+ expiration date of the principal
+
+ **-pwexpire** *pwexpdate*
+ password expiration date
+
+ **-maxlife** *maxlife*
+ maximum ticket life for the principal
+
+ **-maxrenewlife** *maxrenewlife*
+ maximum renewable life of tickets for the principal
+
+ **-kvno** *kvno*
+ explicity set the key version number.
+
+ **-policy** *policy*
+ policy used by this principal.
+ If no policy is supplied, then if the policy "default" exists and the *-clearpolicy* is not also specified,
+ then the policy "default" is used;
+ otherwise, the principal will have no policy, and a warning message will be printed.
+
+ **-clearpolicy**
+ *-clearpolicy* prevents the policy "default" from being assigned when *-policy* is not specified.
+ This option has no effect if the policy "default" does not exist.
+
+ {- | +} **allow_postdated**
+ *-allow_postdated* prohibits this principal from obtaining postdated tickets.
+ (Sets the KRB5_*KDB_DISALLOW_POSTDATED* flag.) *+allow_postdated* clears this flag.
+
+ {- | +} **allow_forwardable**
+ *-allow_forwardable* prohibits this principal from obtaining forwardable tickets.
+ (Sets the *KRB5_KDB_DISALLOW_FORWARDABLE* flag.)
+ *+allow_forwardable* clears this flag.
+
+ {- | +} **allow_renewable**
+ *-allow_renewable* prohibits this principal from obtaining renewable tickets.
+ (Sets the *KRB5_KDB_DISALLOW_RENEWABLE* flag.)
+ *+allow_renewable* clears this flag.
+
+ {- | +} **allow_proxiable**
+ *-allow_proxiable* prohibits this principal from obtaining proxiable tickets.
+ (Sets the *KRB5_KDB_DISALLOW_PROXIABLE* flag.)
+ *+allow_proxiable* clears this flag.
+
+ {- | +} **allow_dup_skey**
+ *-allow_dup_skey* disables user-to-user authentication for this principal by prohibiting this principal from obtaining a
+ session key for another user.
+ (Sets the *KRB5_KDB_DISALLOW_DUP_SKEY* flag.)
+ *+allow_dup_skey* clears this flag.
+
+ {- | +} **requires_preauth**
+ *+requires_preauth* requires this principal to preauthenticate before being allowed to kinit.
+ (Sets the *KRB5_KDB_REQUIRES_PRE_AUTH* flag.)
+ *-requires_preauth* clears this flag.
+
+ {- | +} **requires_hwauth**
+ *+requires_hwauth* requires this principal to preauthenticate using a hardware device before being allowed to kinit.
+ (Sets the *KRB5_KDB_REQUIRES_HW_AUTH* flag.)
+ *-requires_hwauth* clears this flag.
+
+ {- | +} **ok_as_delegate**
+ *+ok_as_delegate* sets the OK-AS-DELEGATE flag on tickets issued for use with this principal as the service,
+ which clients may use as a hint that credentials can and should be delegated when authenticating to the service.
+ (Sets the *KRB5_KDB_OK_AS_DELEGATE* flag.)
+ *-ok_as_delegate* clears this flag.
+
+ {- | +} **allow_svr**
+ *-allow_svr* prohibits the issuance of service tickets for this principal.
+ (Sets the *KRB5_KDB_DISALLOW_SVR* flag.)
+ *+allow_svr* clears this flag.
+
+ {- | +} **allow_tgs_req**
+ *-allow_tgs_req* specifies that a Ticket-Granting Service (TGS) request for a service ticket for this principal is not permitted.
+ This option is useless for most things.
+ *+allow_tgs_req* clears this flag.
+ The default is +allow_tgs_req.
+ In effect, *-allow_tgs_req sets* the *KRB5_KDB_DISALLOW_TGT_BASED* flag on the principal in the database.
+
+ {- | +} **allow_tix**
+ *-allow_tix* forbids the issuance of any tickets for this principal.
+ *+allow_tix* clears this flag.
+ The default is *+allow_tix*. In effect, *-allow_tix* sets the *KRB5_KDB_DISALLOW_ALL_TIX* flag on the principal in the database.
+
+ {- | +} **needchange**
+ *+needchange* sets a flag in attributes field to force a password change;
+ *-needchange* clears it.
+ The default is *-needchange*.
+ In effect, *+needchange* sets the *KRB5_KDB_REQUIRES_PWCHANGE* flag on the principal in the database.
+
+ {- | +} **password_changing_service**
+ *+password_changing_service* sets a flag in the attributes field marking this as a password change service principal
+ (useless for most things).
+ *-password_changing_service* clears the flag. This flag intentionally has a long name.
+ The default is *-password_changing_service*.
+ In effect, *+password_changing_service* sets the *KRB5_KDB_PWCHANGE_SERVICE* flag on the principal in the database.
+
+ **-randkey**
+ sets the key of the principal to a random value
+
+ **-pw** *password*
+ sets the key of the principal to the specified string and does not prompt for a password. Note: using this option in a
+ shell script can be dangerous if unauthorized users gain read access to the script.
+
+ **-e** "enc:salt ..."
+ uses the specified list of enctype-salttype pairs for setting the key of the principal. The quotes are necessary if
+ there are multiple enctype-salttype pairs. This will not function against *kadmin* daemons earlier than krb5-1.2.
+
+ EXAMPLE::
+
+ kadmin: addprinc tlyu/admin
+ WARNING: no policy specified for "tlyu/admin at BLEEP.COM";
+ defaulting to no policy.
+ Enter password for principal tlyu/admin at BLEEP.COM:
+ Re-enter password for principal tlyu/admin at BLEEP.COM:
+ Principal "tlyu/admin at BLEEP.COM" created.
+ kadmin:
+
+ kadmin: addprinc **-x** dn=cn=mwm_user,o=org mwm_user
+ WARNING: no policy specified for "mwm_user at BLEEP.COM";
+ defaulting to no policy.
+ Enter password for principal mwm_user at BLEEP.COM:
+ Re-enter password for principal mwm_user at BLEEP.COM:
+ Principal "mwm_user at BLEEP.COM" created.
+ kadmin:
+
+
+ ERRORS::
+
+ KADM5_AUTH_ADD (requires "add" privilege)
+ KADM5_BAD_MASK (shouldn't happen)
+ KADM5_DUP (principal exists already)
+ KADM5_UNK_POLICY (policy does not exist)
+ KADM5_PASS_Q_* (password quality violations)
+
+ **delete_principal** [ *-force* ] *principal*
+ Deletes the specified *principal* from the database. This command prompts for deletion, unless the *-force* option is given.
+
+ .. note:: This command requires the *delete* privilege.
+
+ Alias::
+
+ delprinc
+
+
+ EXAMPLE::
+
+ kadmin: delprinc mwm_user
+ Are you sure you want to delete the principal
+ "mwm_user at BLEEP.COM"? (yes/no): yes
+ Principal "mwm_user at BLEEP.COM" deleted.
+ Make sure that you have removed this principal from
+ all ACLs before reusing.
+ kadmin:
+
+ ERRORS::
+
+ KADM5_AUTH_DELETE (reequires "delete" privilege)
+ KADM5_UNK_PRINC (principal does not exist)
+
+ **modify_principal** [options] *principal*
+ Modifies the specified principal, changing the fields as specified. The options are as above for *add_principal*, except that
+ password changing and flags related to password changing are forbidden by this command.
+ In addition, the option *-clearpolicy* will clear the current policy of a principal.
+
+ .. note:: This command requires the *modify* privilege.
+
+ Alias::
+
+ modprinc
+
+ The options are:
+
+ **-x** *db_princ_args*
+ Denotes the database specific options. The options for LDAP database are:
+
+ **-x** tktpolicy=<policy>
+ Associates a ticket policy to the Kerberos principal.
+
+ **-x** linkdn=<dn>
+ Associates a Kerberos principal with a LDAP object. This option is honored only if the Kerberos principal is not
+ already associated with a LDAP object.
+
+ *-unlock*
+ Unlocks a locked principal (one which has received too many failed authentication attempts without enough time between
+ them according to its password policy) so that it can successfully authenticate.
+
+ ERRORS::
+
+ KADM5_AUTH_MODIFY (requires "modify" privilege)
+ KADM5_UNK_PRINC (principal does not exist)
+ KADM5_UNK_POLICY (policy does not exist)
+ KADM5_BAD_MASK (shouldn't happen)
+
+ **change_password** [options] *principal*
+ Changes the password of principal. Prompts for a new password if neither *-randkey* or *-pw* is specified.
+
+ .. note:: Requires the *changepw* privilege, or that the principal that is running the program to be the same as the one changed.
+
+ Alias::
+
+ cpw
+
+ The following options are available:
+
+ **-randkey**
+ Sets the key of the principal to a random value
+
+ **-pw** *password*
+ Set the password to the specified string. Not recommended.
+
+ **-e** "enc:salt ..."
+ Uses the specified list of enctype-salttype pairs for setting the key of the principal. The quotes are necessary if
+ there are multiple enctype-salttype pairs. This will not function against *kadmin* daemons earlier than krb5-1.2.
+
+ **-keepold**
+ Keeps the previous kvno's keys around. This flag is usually not necessary except perhaps for TGS keys. Don't use this
+ flag unless you know what you're doing. This option is not supported for the LDAP database.
+
+ EXAMPLE::
+
+ kadmin: cpw systest
+ Enter password for principal systest at BLEEP.COM:
+ Re-enter password for principal systest at BLEEP.COM:
+ Password for systest at BLEEP.COM changed.
+ kadmin:
+
+ ERRORS::
+
+ KADM5_AUTH_MODIFY (requires the modify privilege)
+ KADM5_UNK_PRINC (principal does not exist)
+ KADM5_PASS_Q_* (password policy violation errors)
+ KADM5_PADD_REUSE (password is in principal's password
+ history)
+ KADM5_PASS_TOOSOON (current password minimum life not
+ expired)
+
+ **purgekeys** [*-keepkvno oldest_kvno_to_keep* ] *principal*
+ Purges previously retained old keys (e.g., from *change_password -keepold*) from *principal*.
+ If *-keepkvno* is specified, then only purges keys with kvnos lower than oldest_kvno_to_keep.
+
+ **get_principal** [*-terse*] *principal*
+ Gets the attributes of principal.
+ With the *-terse* option, outputs fields as quoted tab-separated strings.
+
+ .. note:: Requires the *inquire* privilege, or that the principal that is running the the program to be the same as the one being listed.
+
+ Alias::
+
+ getprinc
+
+
+ EXAMPLES::
+
+ kadmin: getprinc tlyu/admin
+ Principal: tlyu/admin at BLEEP.COM
+ Expiration date: [never]
+ Last password change: Mon Aug 12 14:16:47 EDT 1996
+ Password expiration date: [none]
+ Maximum ticket life: 0 days 10:00:00
+ Maximum renewable life: 7 days 00:00:00
+ Last modified: Mon Aug 12 14:16:47 EDT 1996 (bjaspan/admin at BLEEP.COM)
+ Last successful authentication: [never]
+ Last failed authentication: [never]
+ Failed password attempts: 0
+ Number of keys: 2
+ Key: vno 1, DES cbc mode with CRC-32, no salt
+ Key: vno 1, DES cbc mode with CRC-32, Version 4
+ Attributes:
+ Policy: [none]
+ kadmin: getprinc -terse systest
+ systest at BLEEP.COM 3 86400 604800 1
+ 785926535 753241234 785900000
+ tlyu/admin at BLEEP.COM 786100034 0 0
+ kadmin:
+
+ ERRORS::
+
+ KADM5_AUTH_GET (requires the get (inquire) privilege)
+ KADM5_UNK_PRINC (principal does not exist)
+
+ **list_principals** [expression]
+ Retrieves all or some principal names.
+ Expression is a shell-style glob expression that can contain the wild-card characters ?, \*, and []'s.
+ All principal names matching the expression are printed.
+ If no expression is provided, all principal names are printed.
+ If the expression does not contain an "@" character, an "@" character followed by the local realm is appended to the expression.
+
+ .. note:: Requires the *list* priviledge.
+
+ Aliases::
+
+ listprincs get_principals get_princs
+
+ EXAMPLES::
+
+ kadmin: listprincs test*
+ test3 at SECURE-TEST.OV.COM
+ test2 at SECURE-TEST.OV.COM
+ test1 at SECURE-TEST.OV.COM
+ testuser at SECURE-TEST.OV.COM
+ kadmin:
+
+ **add_policy** [options] *policy*
+ Adds the named *policy* to the policy database.
+
+ .. note:: Requires the *add* privilege.
+
+ Alias::
+
+ addpol
+
+ The following options are available:
+
+ *-maxlife time*
+ sets the maximum lifetime of a password
+
+ *-minlife time*
+ sets the minimum lifetime of a password
+
+ *-minlength length*
+ sets the minimum length of a password
+
+ *-minclasses number*
+ sets the minimum number of character classes allowed in a password
+
+ *-history number*
+ sets the number of past keys kept for a principal. This option is not supported for LDAP database
+
+ *-maxfailure maxnumber*
+ sets the maximum number of authentication failures before the principal is locked.
+ Authentication failures are only tracked for principals which require preauthentication.
+
+ *-failurecountinterval failuretime*
+ sets the allowable time between authentication failures.
+ If an authentication failure happens after *failuretime* has elapsed since the previous failure,
+ the number of authentication failures is reset to 1.
+
+ *-lockoutduration lockouttime*
+ sets the duration for which the principal is locked from authenticating if too many authentication failures occur without
+ the specified failure count interval elapsing.
+
+
+ EXAMPLES::
+
+ kadmin: add_policy -maxlife "2 days" -minlength 5 guests
+ kadmin:
+
+ ERRORS::
+
+ KADM5_AUTH_ADD (requires the add privilege)
+ KADM5_DUP (policy already exists)
+
+ **delete_policy** [ *-force* ] *policy*
+ deletes the named *policy*. Prompts for confirmation before deletion.
+ The command will fail if the policy is in use by any principals.
+
+ ..note:: Requires the *delete* privilege.
+
+ Alias::
+
+ delpol
+
+
+ EXAMPLE::
+
+ kadmin: del_policy guests
+ Are you sure you want to delete the policy "guests"?
+ (yes/no): yes
+ kadmin:
+
+ ERRORS::
+
+ KADM5_AUTH_DELETE (requires the delete privilege)
+ KADM5_UNK_POLICY (policy does not exist)
+ KADM5_POLICY_REF (reference count on policy is not zero)
+
+ **modify_policy** [options] *policy*
+ modifies the named *policy*. Options are as above for *add_policy*.
+
+ .. note:: Requires the *modify* privilege.
+
+ Alias::
+
+ modpol
+
+
+ ERRORS::
+
+ KADM5_AUTH_MODIFY (requires the modify privilege)
+ KADM5_UNK_POLICY (policy does not exist)
+
+ **get_policy** [ *-terse* ] *policy*
+ displays the values of the named *policy*.
+ With the *-terse* flag, outputs the fields as quoted strings separated by tabs.
+
+ .. note:: Requires the *inquire* privilege.
+
+
+ Alias::
+
+ getpol
+
+
+ EXAMPLES::
+
+ kadmin: get_policy admin
+ Policy: admin
+ Maximum password life: 180 days 00:00:00
+ Minimum password life: 00:00:00
+ Minimum password length: 6
+ Minimum number of password character classes: 2
+ Number of old keys kept: 5
+ Reference count: 17
+ kadmin: get_policy -terse admin
+ admin 15552000 0 6 2 5 17
+ kadmin:
+
+ ERRORS::
+
+ KADM5_AUTH_GET (requires the get privilege)
+ KADM5_UNK_POLICY (policy does not exist)
+
+ **list_policies** [expression]
+ Retrieves all or some policy names. Expression is a shell-style glob expression that can contain the wild-card characters ?, \*, and []'s.
+ All policy names matching the expression are printed.
+ If no expression is provided, all existing policy names are printed.
+
+ .. note:: Requires the *list* priviledge.
+
+ Alias::
+
+ listpols, get_policies, getpols.
+
+
+ EXAMPLES::
+
+ kadmin: listpols
+ test-pol
+ dict-only
+ once-a-min
+ test-pol-nopw
+ kadmin: listpols t*
+ test-pol
+ test-pol-nopw
+ kadmin:
+
+ **ktadd** [**-k** *keytab*] [**-q**] [**-e** *keysaltlist*] [**-norandkey**] [[*principal* | **-glob** *princ-exp*] [...]
+ Adds a *principal* or all principals matching *princ-exp* to a *keytab*.
+ It randomizes each principal's key in the process, to prevent a compromised admin account from reading out all of the keys from the database.
+ However, *kadmin.local* has the *-norandkey* option, which leaves the keys and their version numbers unchanged,
+ similar to the Kerberos V4 ext_srvtab command. That allows users to continue to use the passwords they know to login normally,
+ while simultaneously allowing scripts to login to the same account using a *keytab*.
+ There is no significant security risk added since *kadmin.local* must be run by root on the KDC anyway.
+
+ .. note:: Requires the *inquire* and *changepw* privileges.
+
+ An entry for each of the principal's unique encryption types is added, ignoring
+ multiple keys with the same encryption type but different salt types. If the **-k** argument is not specified, the default *keytab*
+ */etc/krb5.keytab* is used. If the *-q* option is specified, less verbose status information is displayed.
+
+ The *-glob* option requires the *list* privilege. *princ-exp* follows the same rules described for the *list_principals* command.
+
+
+ EXAMPLE::
+
+ kadmin: ktadd -k /tmp/foo-new-keytab host/foo.mit.edu
+ Entry for principal host/foo.mit.edu at ATHENA.MIT.EDU with
+ kvno 3, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/tmp/foo-new-keytab
+ kadmin:
+
+ **ktremove** [**-k** *keytab*] [**-q**] *principal* [*kvno* | *all* | *old*]
+ Removes entries for the specified principal from a *keytab*. Requires no permissions, since this does not require database
+ access. If the string "all" is specified, all entries for that principal are removed; if the string "old" is specified, all
+ entries for that principal except those with the highest kvno are removed. Otherwise, the value specified is parsed as an integer,
+ and all entries whose kvno match that integer are removed. If the *-k* argument is not specifeid, the default *keytab*
+ */etc/krb5.keytab* is used. If the *-q* option is specified, less verbose status information is displayed.
+
+
+ EXAMPLE::
+
+ kadmin: ktremove -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin
+ Entry for principal kadmin/admin with kvno 3 removed
+ from keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
+ kadmin:
+
+
+FILES
+-----------
+
+====================== =================================================
+principal.db default name for Kerberos principal database
+<dbname>.kadm5 KADM5 administrative database. (This would be "principal.kadm5", if you use the default database name.) Contains policy information.
+<dbname>.kadm5.lock Lock file for the KADM5 administrative database. This file works backwards from most other lock files. I.e., *kadmin* will exit with an error if this file does not exist.
+====================== =================================================
+
+NOTE: The above three files are specific to db2 database.
+
+====================== =================================================
+kadm5.acl File containing list of principals and their *kadmin* administrative privileges. See kadmind(8) for a description.
+kadm5.keytab *keytab* file for *kadmin/admin* principal.
+kadm5.dict file containing dictionary of strings explicitly disallowed as passwords.
+====================== =================================================
+
+
+
+HISTORY
+-------------
+
+The *kadmin* prorgam was originally written by Tom Yu at MIT, as an interface to the OpenVision Kerberos administration program.
+
+
+SEE ALSO
+------------
+
+kerberos(1), kpasswd(1), kadmind(8)
+
+
+BUGS
+--------
+
+Command output needs to be cleaned up.
+
Added: trunk/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -0,0 +1,99 @@
+krb5kdc - Kerberos V5 KDC
+===========================
+
+SYNOPSIS
+----------
+
+**krb5kdc**
+ [ **-x** *db_args* ]
+ [ **-d** *dbname* ]
+ [ **-k** *keytype* ]
+ [ **-M** *mkeyname* ]
+ [ **-p** *portnum* ]
+ [ **-m** ]
+ [ **-r** *realm* ]
+ [ **-n** ]
+ [ **-w** *numworkers* ]
+ [ **-P** *pid_file* ]
+
+DESCRIPTION
+--------------
+
+*krb5kdc* is the Kerberos version 5 Authentication Service and Key Distribution Center (AS/KDC).
+
+OPTIONS
+----------
+
+The **-x** *db_args* option specifies the database specific arguments.
+
+ Options supported for LDAP database are:
+
+ **-x** nconns=<number_of_connections>
+ Specifies the number of connections to be maintained per LDAP server.
+
+ **-x** host=<ldapuri>
+ Specifies the LDAP server to connect to by a LDAP URI.
+
+ **-x** binddn=<binddn>
+ Specifies the DN of the object used by the KDC server to bind to the LDAP server. This object should have the rights to read
+ the realm container, principal container and the subtree that is referenced by the realm.
+
+ **-x** bindpwd=<bind_password>
+ Specifies the password for the above mentioned binddn. It is recommended not to use this option. Instead, the password can be
+ stashed using the stashsrvpw command of kdb5_ldap_util.
+
+The **-r** *realm* option specifies the realm for which the server should provide service;
+by default the realm returned by krb5_default_local_realm(3) is used.
+
+The **-d** *dbname* option specifies the name under which the principal database can be found;
+by default the database is in DEFAULT_DBM_FILE. This option does not apply to the LDAP database.
+
+The **-k** *keytype* option specifies the key type of the master key to be entered manually as a password when **-m** is given;
+the default is "des-cbc-crc".
+
+The **-M** *mkeyname* option specifies the principal name for the master key in the database;
+the default is KRB5_KDB_M_NAME (usually "K/M" in the KDC's realm).
+
+The **-p** *portnum* option specifies the default UDP port number which the KDC should listen on for Kerberos version 5 requests.
+This value is used when no port is specified in the KDC profile and when no port is specified in the Kerberos configuration file.
+If no value is available, then the value in */etc/services* for service "kerberos" is used.
+
+The **-m** option specifies that the master database password should be fetched from the keyboard rather than from a file on disk.
+
+The **-n** option specifies that the KDC does not put itself in the background and does not disassociate itself from the terminal.
+In normal operation, you should always allow the KDC to place itself in the background.
+
+The **-w** *numworkers* option tells the KDC to fork *numworkers* processes to listen to the KDC ports and process requests in parallel.
+The top level KDC process (whose pid is recorded in the pid file if the **-P** option is also given) acts as a supervisor.
+The supervisor will relay SIGHUP signals to the worker subprocesses, and will terminate the worker subprocess if the it is itself terminated or
+if any other worker process exits.
+
+.. note:: on operating systems which do not have *pktinfo* support, using worker processes will prevent the KDC from listening for UDP packets on network interfaces created after the KDC starts.
+
+The **-P** *pid_file* option tells the KDC to write its PID (followed by a newline) into *pid_file* after it starts up.
+This can be used to identify whether the KDC is still running and to allow init scripts to stop the correct process.
+
+The KDC may service requests for multiple realms (maximum 32 realms).
+The realms are listed on the command line. Per-realm options that can be specified on the command line pertain for each realm
+that follows it and are superceded by subsequent definitions of the same option.
+For example::
+
+ krb5kdc -p 2001 -r REALM1 -p 2002 -r REALM2 -r REALM3
+
+specifies that the KDC listen on port 2001 for REALM1 and on port 2002 for REALM2 and REALM3.
+Additionally, per-realm parameters may be specified in the :ref:`kdc.conf` file.
+The location of this file may be specified by the KRB5_KDC_PROFILE environment variable.
+Parameters specified in this file take precedence over options specified on the command line.
+See the kdc.conf(5) description for further details.
+
+SEE ALSO
+-----------
+
+krb5(3), kdb5_util(8), kdc.conf(5), kdb5_ldap_util(8)
+
+BUGS
+-----------
+
+It should fork and go into the background when it finishes reading the master password from the terminal.
+
+
Modified: trunk/doc/rst_source/krb_admins/conf_files/kdc_conf.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/conf_files/kdc_conf.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/conf_files/kdc_conf.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -1,4 +1,4 @@
-.. _kdc_conf_label:
+.. _kdc.conf:
kdc.conf
==============
@@ -8,7 +8,7 @@
Structure
--------------
-The kdc.conf file is set up in the same format as the :ref:`krb5_conf_label` file. The kdc.conf file may contain any or all of the following three sections:
+The kdc.conf file is set up in the same format as the :ref:`krb5.conf` file. The kdc.conf file may contain any or all of the following three sections:
==================== ================================
:ref:`kdcdefaults` Contains default values for overall behavior of the KDC.
@@ -124,7 +124,7 @@
**[logging]**
~~~~~~~~~~~~~~~~~~~~
-See :ref:`logging` section in :ref:`krb5_conf_label`
+See :ref:`logging` section in :ref:`krb5.conf`
PKINIT options
Modified: trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/conf_files/krb5_conf.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -1,4 +1,4 @@
-.. _krb5_conf_label:
+.. _krb5.conf:
krb5.conf
==========
Modified: trunk/doc/rst_source/krb_admins/conf_ldap.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/conf_ldap.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/conf_ldap.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -88,7 +88,7 @@
- For the sample krb5.conf file, refer to :ref:`krb5_conf_sample_label`. For more details, refer to :ref:`krb5_conf_label`
+ For the sample krb5.conf file, refer to :ref:`krb5_conf_sample_label`. For more details, refer to :ref:`krb5.conf`
8. Create the realm using *kdb5_ldap_util* (see :ref:`ldap_create_realm_label`)::
Modified: trunk/doc/rst_source/krb_admins/database/incr_db_prop.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database/incr_db_prop.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/database/incr_db_prop.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -14,14 +14,14 @@
With incremental propagation enabled, all programs on the master KDC that change the database also write information about the changes to an "update log" file, maintained as a circular buffer of a certain size. A process on each slave KDC connects to a service on the master KDC (currently implmented in the kadmind server) and periodically requests the changes that have been made since the last check. By default, this check is done every two minutes. If the database has just been modified in the previous several seconds (currently the threshold is hard-coded at 10 seconds), the slave will not retrieve updates, but instead will pause and try again soon after. This reduces the likelihood that incremental update queries will cause delays for an administrator trying to make a bunch of changes to the database at the same time.
-Incremental propagation uses the following entries in the per-realm data in the KDC config file (See :ref:`kdc_conf_label`):
+Incremental propagation uses the following entries in the per-realm data in the KDC config file (See :ref:`kdc.conf`):
====================== =============== ===========================================
iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*.
iprop_master_ulogsize *integer* Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500.
iprop_slave_poll *time interval* Indicates how often the slave should poll the master KDC for changes to the database. The default is two minutes.
iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and slave configuration files.
-iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc_conf_label`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.)
+iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc.conf`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.)
====================== =============== ===========================================
Both master and slave sides must have principals named *kiprop/hostname* (where *hostname* is, as usual, the lower-case, fully-qualified, canonical name for the host) registered and keys stored in the default keytab file (/etc/krb5.keytab).
Modified: trunk/doc/rst_source/krb_admins/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/index.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/index.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -22,6 +22,7 @@
.. toctree::
:maxdepth: 1
+ admin_commands/index.rst
troubleshoot.rst
advanced/index.rst
various_envs.rst
Modified: trunk/doc/rst_source/krb_admins/install_clients/cl_config.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_clients/cl_config.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/install_clients/cl_config.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -2,7 +2,7 @@
=====================================
-Each machine running Kerberos must have a */etc/krb5.conf* file. (See :ref:`krb5_conf_label`.)
+Each machine running Kerberos must have a */etc/krb5.conf* file. (See :ref:`krb5.conf`.)
Also, for most UNIX systems, you must add the appropriate Kerberos services to each client machine's */etc/services* file. If you are using the default configuration for Kerberos V5, you should be able to just insert the following code::
Modified: trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/install_kdc/mod_conf.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -3,7 +3,7 @@
Modify the configuration files, */etc/krb5.conf* and */usr/local/var/krb5kdc/kdc.conf* to reflect the correct information (such as the hostnames and realm name) for your realm. MIT recommends that you keep *krb5.conf* in */etc*.
-Most of the tags in the configuration have default values that will work well for most sites. There are some tags in the *krb5.conf* file whose values must be specified, and this section will explain those. For more information on Kerberos V5 configuration files see :ref:`krb5_conf_label` and :ref:`kdc_conf_label`.
+Most of the tags in the configuration have default values that will work well for most sites. There are some tags in the *krb5.conf* file whose values must be specified, and this section will explain those. For more information on Kerberos V5 configuration files see :ref:`krb5.conf` and :ref:`kdc.conf`.
*krb5.conf*
-------------
Modified: trunk/doc/rst_source/krb_admins/realm_config/kdc_hn.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/realm_config/kdc_hn.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/realm_config/kdc_hn.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -22,7 +22,7 @@
If you have only one KDC, or for whatever reason there is no accessible KDC that would get database changes faster than the others, you do not need to define this entry.
_kerberos-adm._tcp
- This should list port 749 on your master KDC. Support for it is not complete at this time, but it will eventually be used by the kadmin program and related utilities. For now, you will also need the admin_server entry in :ref:`krb5_conf_label`.
+ This should list port 749 on your master KDC. Support for it is not complete at this time, but it will eventually be used by the kadmin program and related utilities. For now, you will also need the admin_server entry in :ref:`krb5.conf`.
_kpasswd._udp
This should list port 464 on your master KDC. It is used when a user changes her password.
Modified: trunk/doc/rst_source/krb_admins/realm_config/kdc_ports.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/realm_config/kdc_ports.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/realm_config/kdc_ports.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -1,7 +1,7 @@
Ports for the KDC and admin services
======================================
-The default ports used by Kerberos are port **88** for the KDC1 and port **749** for the admin server. You can, however, choose to run on other ports, as long as they are specified in each host's */etc/services* and :ref:`krb5_conf_label` files, and the :ref:`kdc_conf_label` file on each KDC. For a more thorough treatment of port numbers used by the Kerberos V5 programs, refer to the :ref:`conf_firewall_label`
+The default ports used by Kerberos are port **88** for the KDC1 and port **749** for the admin server. You can, however, choose to run on other ports, as long as they are specified in each host's */etc/services* and :ref:`krb5.conf` files, and the :ref:`kdc.conf` file on each KDC. For a more thorough treatment of port numbers used by the Kerberos V5 programs, refer to the :ref:`conf_firewall_label`
------------
Modified: trunk/doc/rst_source/krb_admins/realm_config/mapping_hn.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/realm_config/mapping_hn.rst 2011-08-03 03:41:35 UTC (rev 25068)
+++ trunk/doc/rst_source/krb_admins/realm_config/mapping_hn.rst 2011-08-03 17:50:23 UTC (rev 25069)
@@ -8,7 +8,7 @@
Mapping hostnames onto Kerberos realms is done in one of two ways.
-The first mechanism, which has been in use for years in MIT-based Kerberos distributions, works through a set of rules in the :ref:`krb5_conf_label` configuration file. You can specify mappings for an entire domain or subdomain, and/or on a hostname-by-hostname basis. Since greater specificity takes precedence, you would do this by specifying the mappings for a given domain or subdomain and listing the exceptions.
+The first mechanism, which has been in use for years in MIT-based Kerberos distributions, works through a set of rules in the :ref:`krb5.conf` configuration file. You can specify mappings for an entire domain or subdomain, and/or on a hostname-by-hostname basis. Since greater specificity takes precedence, you would do this by specifying the mappings for a given domain or subdomain and listing the exceptions.
The second mechanism works by looking up the information in special TXT records in the Domain Name Service. This is currently not used by default because security holes could result if the DNS TXT records were spoofed. If this mechanism is enabled on the client, it will try to look up a TXT record for the DNS name formed by putting the prefix _kerberos in front of the hostname in question. If that record is not found, it will try using _kerberos and the host's domain name, then its parent domain, and so forth. So for the hostname *BOSTON.ENGINEERING.FOOBAR.COM*, the names looked up would be::
More information about the cvs-krb5
mailing list