krb5 commit [krb5-1.11]: Cross-reference account lockout documentation

[Tom Yu]

https://github.com/krb5/krb5/commit/35d11e2a1190453a6b3c2b403021fadad76d2455
commit 35d11e2a1190453a6b3c2b403021fadad76d2455
Author: Greg Hudson <ghudson at mit.edu>
Date:   Wed Dec 5 11:42:55 2012 -0500

    Cross-reference account lockout documentation
    
    Link to the database.rst description of policy objects when talking
    about them.  Briefly mention the "default" policy.  Link to the
    kadmin_local.rst description of policy fields when referencing them.
    Describe policy fields more briefly, and expand the kadmin_local.rst
    descriptions where appropriate.
    
    (cherry picked from commit 718868423c7a1e712e54c841b88521e23d374745)
    
    ticket: 7480
    version_fixed: 1.11
    status: resolved

 doc/admin/admin_commands/kadmin_local.rst |   21 +++++++++++++----
 doc/admin/database.rst                    |    2 +
 doc/admin/lockout.rst                     |   36 ++++++++++++-----------------
 3 files changed, 33 insertions(+), 26 deletions(-)

diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index 396e255..c15042b 100644
--- a/doc/admin/admin_commands/kadmin_local.rst
+++ b/doc/admin/admin_commands/kadmin_local.rst
@@ -610,22 +610,33 @@ The following options are available:
     Sets the number of past keys kept for a principal.  This option is
     not supported with the LDAP KDC database module.
 
+.. _policy_maxfailure:
+
 **-maxfailure** *maxnumber*
-    Sets the maximum number of authentication failures before the
-    principal is locked.  Authentication failures are only tracked for
-    principals which require preauthentication.
+    Sets the number of authentication failures before the principal is
+    locked.  Authentication failures are only tracked for principals
+    which require preauthentication.  The counter of failed attempts
+    resets to 0 after a successful attempt to authenticate.  A
+    *maxnumber* value of 0 (the default) disables lockout.
+
+.. _policy_failurecountinterval:
 
 **-failurecountinterval** *failuretime*
     (:ref:`getdate` string) 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.
+    the number of authentication failures is reset to 1.  A
+    *failuretime* value of 0 (the default) means forever.
+
+.. _policy_lockoutduration:
 
 **-lockoutduration** *lockouttime*
     (:ref:`getdate` string) Sets the duration for which the principal
     is locked from authenticating if too many authentication failures
     occur without the specified failure count interval elapsing.
-    A duration of 0 means forever.
+    A duration of 0 (the default) means the principal remains locked
+    out until it is administratively unlocked with ``modprinc
+    -unlock``.
 
 **-allowedkeysalts**
     Specifies the key/salt tuples supported for long-term keys when
diff --git a/doc/admin/database.rst b/doc/admin/database.rst
index d7d6aa9..e2acb94 100644
--- a/doc/admin/database.rst
+++ b/doc/admin/database.rst
@@ -184,6 +184,8 @@ To change a principal's password use the :ref:`kadmin(1)`
           :ref:`kpasswd(1)`.
 
 
+.. _policies:
+
 Policies
 --------
 
diff --git a/doc/admin/lockout.rst b/doc/admin/lockout.rst
index 8260cb2..e520921 100644
--- a/doc/admin/lockout.rst
+++ b/doc/admin/lockout.rst
@@ -21,27 +21,21 @@ through a TGS request.  You can set these flags on a principal with
 
     kadmin: modprinc +requires_preauth -allow_svr PRINCNAME
 
-Account lockout parameters are configured via password policies.  The
-policy parameters are:
-
-* **maxfailure**: the maximum number of failed attempts before the
-  principal is locked out.  For example, if **maxfailure** is set to
-  10, the principal would be locked out after ten failed attempts.
-  The counter of failed attempts resets to 0 after a successful
-  attempt to authenticate.  A **maxfailure** value of 0 (the default)
-  disables account lockout.
-
-* **failurecountinterval**: if this interval elapses between failed
-  attempts, the counter of failed attempts resets to 1 for the most
-  recent failure.  A **failurecountinterval** of 0 (the default) means
-  the counter only resets on a successful attempt to authenticate.
-
-* **lockoutduration**: if a principal is locked out, it remains locked
-  out for this amount of time.  A **lockoutduration** of 0 (the
-  default) means the principal remains locked out until it is
-  administratively unlocked.
-
-Here is an example of setting these attributes on a new policy and
+Account lockout parameters are configured via :ref:`policy objects
+<policies>`.  There may be an existing policy associated with user
+principals (such as the "default" policy), or you may need to create a
+new one and associate it with each user principal.
+
+The policy parameters related to account lockout are:
+
+* :ref:`maxfailure <policy_maxfailure>`: the number of failed attempts
+  before the principal is locked out
+* :ref:`failurecountinterval <policy_failurecountinterval>`: the
+  allowable interval between failed attempts
+* :ref:`lockoutduration <policy_lockoutduration>`: the amount of time
+  a principal is locked out for
+
+Here is an example of setting these parameters on a new policy and
 associating it with a principal::
 
     kadmin: addpol -maxfailure 10 -failurecountinterval 180