Cross-reference to kadm5.acl in documentation

5 files changed, 13 insertions, 269 deletions

diff --git a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
index fbb6038c33..39198b790e 100644
--- a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
+++ b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
@@ -165,8 +165,8 @@ COMMANDS
 --------
 
 When using the remote client, available commands may be restricted
-according to the privileges specified in the kadm5.acl file on the
-admin server.
+according to the privileges specified in the :ref:`kadm5.acl(5)` file
+on the admin server.
 
 .. _add_principal:
 
diff --git a/doc/rst_source/krb_admins/admin_commands/kadmind.rst b/doc/rst_source/krb_admins/admin_commands/kadmind.rst
index bb858f4ca9..573e7a1240 100644
--- a/doc/rst_source/krb_admins/admin_commands/kadmind.rst
+++ b/doc/rst_source/krb_admins/admin_commands/kadmind.rst
@@ -34,15 +34,11 @@ for it to work:
     **acl_file**, **dict_file**, **kadmind_port**, and iprop-related
     settings.
 
-ACL file
+:ref:`kadm5.acl(5)`
     kadmind's ACL (access control list) tells it which principals are
     allowed to perform administration actions.  The pathname to the
-    ACL file can be specified with the **acl_file** kdc.conf variable;
-    by default, it is |kdcdir|\ ``/kadm5.acl``.  The syntax of the ACL
-    file is specified in the ACL FILE SYNTAX section below.
-
-    If the kadmind ACL file is modified, the kadmind daemon needs to
-    be restarted for changes to take effect.
+    ACL file can be specified with the **acl_file** :ref:`kdc.conf(5)`
+    variable; by default, it is |kdcdir|\ ``/kadm5.acl``.
 
 After the server begins running, it puts itself in the background and
 disassociates itself from its controlling terminal.
@@ -112,84 +108,8 @@ OPTIONS
             stash the password using the **stashsrvpw** command of
             :ref:`kdb5_ldap_util(8)`.
 
-
-ACL FILE SYNTAX
----------------
-
-The ACL file controls which principals can or cannot perform which
-administrative functions.  For operations that affect principals, the
-ACL file also controls which principals can operate on which other
-principals.  Empty lines and lines starting with the sharp sign
-(``#``) are ignored.  Lines containing ACL entries have the format:
-
- ::
-
-    principal operation-mask [operation-target]
-
-Ordering is important.  The first matching entry will control access
-for an actor principal on a target principal.
-
-*principal*
-    may specify a partially or fully qualified Kerberos version 5
-    principal name.  Each component of the name may be wildcarded
-    using the ``*`` character.
-
-*operation-target*
-    [Optional] may specify a partially or fully qualified Kerberos
-    version 5 principal name.  Each component of the name may be
-    wildcarded using the ``*`` character.
-
-*operation-mask*
-    Specifies what operations may or may not be performed by a
-    principal matching a particular entry.  This is a string of one or
-    more of the following list of characters or their upper-case
-    counterparts.  If the character is upper-case, then the operation
-    is disallowed.  If the character is lower-case, then the operation
-    is permitted.
-
-    == ======================================================
-    a  [Dis]allows the addition of principals or policies
-    d  [Dis]allows the deletion of principals or policies
-    m  [Dis]allows the modification of principals or policies
-    c  [Dis]allows the changing of passwords for principals
-    i  [Dis]allows inquiries about principals or policies
-    l  [Dis]allows the listing of principals or policies
-    p  [Dis]allows the propagation of the principal database
-    x  Short for admcil.
-    \* Same as x.
-    == ======================================================
-
-    Some examples of valid entries here are:
-
-    ``user/instance@realm adm``
-        A standard fully qualified name.  The *operation-mask* only
-        applies to this principal and specifies that [s]he may add,
-        delete, or modify principals and policies, but not change
-        anybody else's password.
-
-    ``user/instance@realm cim service/instance@realm``
-        A standard fully qualified name and a standard fully qualified
-        target.  The *operation-mask* only applies to this principal
-        operating on this target and specifies that [s]he may change
-        the target's password, request information about the target,
-        and modify it.
-
-    ``user/*@realm ac``
-        A wildcarded name.  The *operation-mask* applies to all
-        principals in realm ``realm`` whose first component is
-        ``user`` and specifies that [s]he may add principals and
-        change anybody's password.
-
-    ``user/*@realm i */instance@realm``
-        A wildcarded name and target.  The *operation-mask* applies to
-        all principals in realm ``realm`` whose first component is
-        ``user`` and specifies that [s]he may perform inquiries on
-        principals whose second component is ``instance`` and realm is
-        ``realm``.
-
-
 SEE ALSO
 --------
 
 :ref:`kpasswd(1)`, :ref:`kadmin(1)`, :ref:`kdb5_util(8)`,
-:ref:`kdb5_ldap_util(8)`
+:ref:`kdb5_ldap_util(8)`, :ref:`kadm5.acl(5)`
diff --git a/doc/rst_source/krb_admins/conf_files/kdc_conf.rst b/doc/rst_source/krb_admins/conf_files/kdc_conf.rst
index 2c41573e2c..212742c887 100644
--- a/doc/rst_source/krb_admins/conf_files/kdc_conf.rst
+++ b/doc/rst_source/krb_admins/conf_files/kdc_conf.rst
@@ -72,7 +72,8 @@ For each realm, the following tags may be specified:
     (String.)  Location of the access control list file that
     :ref:`kadmind(8)` uses to determine which principals are allowed
     which permissions on the Kerberos database.  The default value is
-    |kdcdir|\ ``/kadm5.acl``.
+    |kdcdir|\ ``/kadm5.acl``.  For more information on Kerberos ACL
+    file see :ref:`kadm5.acl(5)`.
 
 **database_module**
     This relation indicates the name of the configuration section
@@ -698,4 +699,4 @@ FILES
 SEE ALSO
 ---------
 
-:ref:`krb5.conf(5)`, :ref:`krb5kdc(8)`
+:ref:`krb5.conf(5)`, :ref:`krb5kdc(8)`, :ref:`kadm5.acl(5)`
diff --git a/doc/rst_source/krb_admins/database.rst b/doc/rst_source/krb_admins/database.rst
index b92a99e2f8..eae37c8796 100644
--- a/doc/rst_source/krb_admins/database.rst
+++ b/doc/rst_source/krb_admins/database.rst
@@ -276,19 +276,7 @@ Privileges
 ----------
 
 Administrative privileges for the Kerberos database are stored in the
-file kadm5.acl.
-
-The format of the file is::
-
-     Kerberos_principal      permissions     [target_principal] [restrictions]
-
-The Kerberos principal (and optional target principal) can include the
-``*`` wildcard, so if you want any principal with the instance
-``admin`` to have full permissions on the database, you could use the
-principal ``*/admin@REALM`` where *REALM* is your Kerberos realm.
-*target_principal* can also include backreferences to
-*Kerberos_principal*, in which "number" matches the component number
-in the *Kerberos_principal*.
+file :ref:`kadm5.acl(5)`.
 
 .. note:: A common use of an admin instance is so you can grant
           separate permissions (such as administrator access to the
@@ -299,81 +287,6 @@ in the *Kerberos_principal*.
           only when he actually needs to use those permissions.
 
 
-Permissions
-~~~~~~~~~~~
-
-The permissions are represented by single letters; UPPER-CASE letters
-represent negative permissions.  The permissions are:
-
-=== =====================================
-a    allows the addition of principals or policies in the database.
-A    disallows the addition of principals or policies in the database.
-c    allows the changing of passwords for principals in the database.
-C    disallows the changing of passwords for principals in the database.
-d    allows the deletion of principals or policies in the database.
-D    disallows the deletion of principals or policies in the database.
-i    allows inquiries to the database.
-I    disallows inquiries to the database.
-l    allows the listing of principals or policies in the database.
-L    disallows the listing of principals or policies in the database.
-m    allows the modification of principals or policies in the database.
-M    disallows the modification of principals or policies in the database.
-p    allow the propagation of the principal database (used in :ref:`incr_db_prop`).
-P    disallow the propagation of the principal database (used in :ref:`incr_db_prop`).
-s    allows the explicit setting of the key for a principal
-S    disallows the explicit setting of the key for a principal
-\*   All privileges (admcil).
-x    All privileges (admcil); identical to "\*".
-=== =====================================
-
-
-Restrictions
-~~~~~~~~~~~~
-
-The restrictions are a string of flags.  Allowed restrictions are:
-
-======================== ============================
-[+\|-]flagname             flag is forced to indicated value. The permissible flags are the same as the + and - flags for the kadmin addprinc and modprinc commands.
--clearpolicy               policy is forced to clear
--policy *pol*              policy is forced to be *pol*
--expire time
--pwexpire time
--maxlife time
--maxrenewlife time        associated value will be forced to MIN(time, requested value)
-======================== ============================
-
-The above flags act as restrictions on any add or modify operation
-which is allowed due to that ACL line.
-
-Here is an example of a *kadm5.acl* file::
-
-    */admin@ATHENA.MIT.EDU  *
-    joeadmin@ATHENA.MIT.EDU  ADMCIL
-    joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU
-    *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU
-    */*@ATHENA.MIT.EDU  i
-    */admin@EXAMPLE.COM * -maxlife 9h -postdateable
-
-.. note:: The order is important; permissions are determined by the
-          first matching entry.
-
-In the above file, any principal in the ``ATHENA.MIT.EDU`` realm with
-an admin instance has all administrative privileges.  The user
-``joeadmin`` has all permissions with his admin instance,
-``joeadmin/admin@ATHENA.MIT.EDU`` (matches the first line).  He has no
-permissions at all with his null instance, ``joeadmin@ATHENA.MIT.EDU``
-(matches the second line).  His root instance has inquire and list
-permissions with any other principal that has the instance root.  Any
-principal in ``ATHENA.MIT.EDU`` can inquire, list, or change the
-password of their admin instance, but not any other admin instance.
-Any principal in the realm ``ATHENA.MIT.EDU`` (except for
-``joeadmin@ATHENA.MIT.EDU``, as mentioned above) has inquire
-privileges.  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.
-
-
 .. _db_operations:
 
 Operations on the Kerberos database
@@ -798,8 +711,8 @@ Kerberos database, and have keys for that principal stored in the
 default keytab file (|keytab|).
 
 On the master KDC side, the ``kiprop/hostname`` principal must be
-listed in the kadmind ACL file kadm5.acl, and given the **p**
-privilege (see :ref:`privileges`).
+listed in the kadmind ACL file :ref:`kadm5.acl(5)`, and given the
+**p** privilege (see :ref:`privileges`).
 
 On the slave KDC side, :ref:`kpropd(8)` should be run.  When
 incremental propagation is enabled, it will connect to the kadmind on
diff --git a/doc/rst_source/krb_admins/install_kdc.rst b/doc/rst_source/krb_admins/install_kdc.rst
index 4fb62f9afe..c43e4161f6 100644
--- a/doc/rst_source/krb_admins/install_kdc.rst
+++ b/doc/rst_source/krb_admins/install_kdc.rst
@@ -203,97 +203,7 @@ database files.  The ACL filename is determined by the **acl_file**
 variable in :ref:`kdc.conf(5)`; the default is |kdcdir|\
 ``/kadm5.acl``.
 
-The format of the file is::
-
-    client_principal      permissions     [target_principal]  [restrictions]
-
-The *client_principal* (and optional *target_principal*) can include
-the ``*`` wildcard, so if you want any principal with the instance
-``admin`` to have full permissions on the database, you could use the
-principal ``*/admin@REALM`` where *REALM* is your Kerberos realm.
-*target_principal* can also include backreferences to
-*client_principal*, in which ``*number`` matches the component number
-in *client_principal*.
-
-.. note:: A common use of an admin instance is so you can grant
-          separate permissions (such as administrator access to the
-          Kerberos database) to a separate kerberos principal.  For
-          example, the user ``joeadmin`` might have a principal for
-          his administrative use, called ``joeadmin/admin``.  This
-          way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets
-          only when he actually needs to use those permissions.
-
-The permissions are represented by single letters.  A lowercase
-character specifies that operation can be performed by the principal,
-while its uppercase counterpart indicates negative permission.  The
-permissions are:
-
-    ==== ==========================================================
-    a    [Dis]allows the addition of principals or policies in the database
-    c    [Dis]allows the changing of passwords for principals in the database
-    d    [Dis]allows the deletion of principals or policies in the database
-    i    [Dis]allows inquiries to the database
-    l    [Dis]allows the listing of principals or policies in the database
-    m    [Dis]allows the modification of principals or policies in the database
-    s    [Dis]allows the explicit setting of the key for a principal
-    \*   All privileges (admcil)
-    x    All privileges (admcil); identical to "\*"
-    ==== ==========================================================
-
-*Restrictions* are a string of flags. Allowed restrictions are:
-
-    ====================== ===============================
-    [+\|-]flagname          flag is forced to indicated value.  The permissible flags are the same as the + and - flags for the kadmin :ref:`add_principal` and :ref:`modify_principal` commands.
-    -clearpolicy            policy is forced to clear
-    -policy *pol*           policy is forced to be *pol*
-    expire *time*           associated value will be forced to MIN(*time*, requested value)
-    pwexpire *time*         associated value will be forced to MIN(*time*, requested value)
-    maxlife *time*          associated value will be forced to MIN(*time*, requested value)
-    maxrenewlife *time*     associated value will be forced to MIN(*time*, requested value)
-    ====================== ===============================
-
-The above flags act as restrictions on any add or modify operation
-which is allowed due to that ACL line.
-
-Here is an example of a kadm5.acl file.
-
-.. warning:: The order of lines is important; permissions are
-             determined by the first matching entry.
-
-::
-
-    */admin@ATHENA.MIT.EDU          *
-    joeadmin@ATHENA.MIT.EDU         ADMCIL
-    joeadmin/*@ATHENA.MIT.EDU  il   */root@ATHENA.MIT.EDU
-    *@ATHENA.MIT.EDU           cil  *1/admin@ATHENA.MIT.EDU
-    */*@ATHENA.MIT.EDU         i
-    */admin@EXAMPLE.COM        * -maxlife 9h -postdateable
-
-In the above file, any principal in the ``ATHENA.MIT.EDU`` realm with
-an ``admin`` instance has all administrative privileges.
-
-The user ``joeadmin`` has all permissions with his ``admin`` instance,
-``joeadmin/admin@ATHENA.MIT.EDU`` (matches the first line).  He has no
-permissions at all with his null instance, ``joeadmin@ATHENA.MIT.EDU``
-(matches the second line).  His root instance has inquire and list
-permissions with any other principal that has the instance root.
-
-Any principal in ``ATHENA.MIT.EDU`` can inquire, list, or change the
-password of their ``admin`` instance, but not any other admin
-instance.
-
-Any principal in the realm ``ATHENA.MIT.EDU`` (except for
-``joeadmin@ATHENA.MIT.EDU``, as mentioned above) has inquire
-privileges.
-
-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.
-
-.. warning:: If the kadmind ACL file is modified, the kadmind
-             daemon needs to be restarted for changes to take effect.
-
+For more information on Kerberos ACL file see :ref:`kadm5.acl(5)`.
 
 .. _addadmin_kdb: