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 7188684)

ticket: 7480
version_fixed: 1.11
status: resolved

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

doc/admin/database.rst

@@ -184,6 +184,8 @@ To change a principal's password use the :ref:`kadmin(1)`
           :ref:`kpasswd(1)`.
 
 
+.. _policies:
+
 Policies
 --------
 

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