krb5 commit: Cross-reference to kadm5.acl in documentation
Zhanna A Tsitkova
tsitkova at MIT.EDU
Fri Aug 3 12:02:44 EDT 2012
https://github.com/krb5/krb5/commit/d68864d8d90349b8906a570a34c989ec7e0c9edb
commit d68864d8d90349b8906a570a34c989ec7e0c9edb
Author: Zhanna Tsitkov <tsitkova at mit.edu>
Date: Fri Aug 3 12:14:32 2012 -0400
Cross-reference to kadm5.acl in documentation
.../krb_admins/admin_commands/kadmin_local.rst | 4 +-
.../krb_admins/admin_commands/kadmind.rst | 88 +------------------
doc/rst_source/krb_admins/conf_files/kdc_conf.rst | 5 +-
doc/rst_source/krb_admins/database.rst | 93 +-------------------
doc/rst_source/krb_admins/install_kdc.rst | 92 +-------------------
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 fbb6038..39198b7 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 bb858f4..573e7a1 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 at 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 at realm cim service/instance at 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 at 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 2c41573..212742c 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 b92a99e..eae37c8 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 at 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 at ATHENA.MIT.EDU *
- joeadmin at ATHENA.MIT.EDU ADMCIL
- joeadmin/*@ATHENA.MIT.EDU il */root at ATHENA.MIT.EDU
- *@ATHENA.MIT.EDU cil *1/admin at ATHENA.MIT.EDU
- */*@ATHENA.MIT.EDU i
- */admin at 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 at ATHENA.MIT.EDU`` (matches the first line). He has no
-permissions at all with his null instance, ``joeadmin at 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 at 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 4fb62f9..c43e416 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 at 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 at ATHENA.MIT.EDU *
- joeadmin at ATHENA.MIT.EDU ADMCIL
- joeadmin/*@ATHENA.MIT.EDU il */root at ATHENA.MIT.EDU
- *@ATHENA.MIT.EDU cil *1/admin at ATHENA.MIT.EDU
- */*@ATHENA.MIT.EDU i
- */admin at 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 at ATHENA.MIT.EDU`` (matches the first line). He has no
-permissions at all with his null instance, ``joeadmin at 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 at 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:
More information about the cvs-krb5
mailing list