krb5 commit: Update the kadm5.acl example

[Benjamin Kaduk]

https://github.com/krb5/krb5/commit/70b2ba4852913ceb2bdc9a57edd487da8230f813
commit 70b2ba4852913ceb2bdc9a57edd487da8230f813
Author: Ben Kaduk <kaduk at mit.edu>
Date:   Fri Jun 13 14:59:39 2014 -0400

    Update the kadm5.acl example
    
    Make the example and documentation a closer match to reality.
    In particular, the list permission is all-or-nothing; it is not
    restricted in scope by the target_principal field.  Change the
    table entry to try and indicate this fact, and do not put list
    permissions on any example line that is scoped by a target_principal
    pattern.
    
    While here, remove the nonsensical granting of global inquire
    permissions to */* (inaccurately described as "all principals"),
    and the granting of privileges to foreign-realm principals.
    It is not possible to obtain an initial ticket (as required by
    the kadmin service) for a principal in a different realm, and
    the current kadmind implementation can serve only a single realm
    at a time -- this permission literally has no effect.  Replace
    it with a (presumably automated) "Service Management System"
    example, where it might make sense to limit the principals which
    are automatically created.
    
    ticket: 7939

 doc/admin/conf_files/kadm5_acl.rst |   34 ++++++++++++++++++----------------
 1 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/doc/admin/conf_files/kadm5_acl.rst b/doc/admin/conf_files/kadm5_acl.rst
index 6a009d2..ca3cea6 100644
--- a/doc/admin/conf_files/kadm5_acl.rst
+++ b/doc/admin/conf_files/kadm5_acl.rst
@@ -50,7 +50,7 @@ ignored.  Lines containing ACL entries have the format:
     c  [Dis]allows the changing of passwords for principals
     d  [Dis]allows the deletion of principals or policies
     i  [Dis]allows inquiries about principals or policies
-    l  [Dis]allows the listing of principals or policies
+    l  [Dis]allows the listing of all principals or policies
     m  [Dis]allows the modification of principals or policies
     p  [Dis]allows the propagation of the principal database (used in :ref:`incr_db_prop`)
     s  [Dis]allows the explicit setting of the key for a principal
@@ -102,12 +102,12 @@ Here is an example of a kadm5.acl file.
 
  ::
 
-    */admin at ATHENA.MIT.EDU        *                           # line 1
+    */admin at ATHENA.MIT.EDU    *                               # line 1
     joeadmin at ATHENA.MIT.EDU   ADMCIL                          # line 2
-    joeadmin/*@ATHENA.MIT.EDU il  */root at ATHENA.MIT.EDU       # line 3
-    */root at ATHENA.MIT.EDU     cil *1 at ATHENA.MIT.EDU           # line 4
-    */*@ATHENA.MIT.EDU        i                               # line 5
-    */admin at EXAMPLE.COM       x   * -maxlife 9h -postdateable # line 6
+    joeadmin/*@ATHENA.MIT.EDU i   */root at ATHENA.MIT.EDU       # line 3
+    */root at ATHENA.MIT.EDU     ci  *1 at ATHENA.MIT.EDU           # line 4
+    */root at ATHENA.MIT.EDU     l   *                           # line 5
+    sms at ATHENA.MIT.EDU        x   * -maxlife 9h -postdateable # line 6
 
 (line 1) Any principal in the ``ATHENA.MIT.EDU`` realm with
 an ``admin`` instance has all administrative privileges.
@@ -117,22 +117,24 @@ an ``admin`` instance has all administrative privileges.
 1).  He has no permissions at all with his null instance,
 ``joeadmin at ATHENA.MIT.EDU`` (matches line 2).  His ``root`` and other
 non-``admin``, non-null instances (e.g., ``extra`` or ``dbadmin``) have
-inquire and list permissions with any principal that has the
-instance ``root`` (matches line 3).
+inquire permissions with any principal that has the instance ``root``
+(matches line 3).
 
-(line 4) Any ``root`` principal in ``ATHENA.MIT.EDU`` can inquire, list,
+(line 4) Any ``root`` principal in ``ATHENA.MIT.EDU`` can inquire
 or change the password of their null instance, but not any other
 null instance.  (Here, ``*1`` denotes a back-reference to the
 component matching the first wildcard in the actor principal.)
 
-(line 5) Any principal in the realm ``ATHENA.MIT.EDU`` (except for
-``joeadmin at ATHENA.MIT.EDU``, as mentioned above) has inquire
-privileges.
+(line 5) Any ``root`` principal in ``ATHENA.MIT.EDU`` can generate
+the list of principals in the database, and the list of policies
+in the database.  This line is separate from line 4, because list
+permission can only be granted globally, not to specific target
+principals.
 
-(line 6) Finally, any principal with an ``admin`` instance in ``EXAMPLE.COM``
-has all permissions, but any principal that they create or modify will
-not be able to get postdateable tickets or tickets with a life of
-longer than 9 hours.
+(line 6) Finally, the Service Management System principal
+``sms at ATHENA.MIT.EDU`` has all permissions, but any principal that it
+creates or modifies will not be able to get postdateable tickets or
+tickets with a life of longer than 9 hours.
 
 SEE ALSO
 --------