svn rev #25770: trunk/doc/rst_source/krb_admins/ admin_commands/
ghudson@MIT.EDU
ghudson at MIT.EDU
Thu Mar 15 18:52:45 EDT 2012
http://src.mit.edu/fisheye/changelog/krb5/?cs=25770
Commit By: ghudson
Log Message:
Edit RST admin man pages for clarity and accuracy
Changed Files:
U trunk/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst
U trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
U trunk/doc/rst_source/krb_admins/admin_commands/kadmind.rst
U trunk/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst
U trunk/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst
U trunk/doc/rst_source/krb_admins/admin_commands/kprop.rst
U trunk/doc/rst_source/krb_admins/admin_commands/kpropd.rst
U trunk/doc/rst_source/krb_admins/admin_commands/kproplog.rst
U trunk/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst
U trunk/doc/rst_source/krb_admins/admin_commands/ktutil.rst
U trunk/doc/rst_source/krb_admins/admin_commands/sserver.rst
U trunk/doc/rst_source/krb_admins/database.rst
Modified: trunk/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -13,8 +13,8 @@
DESCRIPTION
-----------
-k5srvutil allows a system manager to list or change keys currently in
-his keytab or to add new keys to the keytab.
+k5srvutil allows an administrator to list or change keys currently in
+a keytab or to add new keys to the keytab.
*operation* must be one of the following:
@@ -23,32 +23,32 @@
name.
**change**
- Changes all the keys in the keytab to new randomly-generated keys,
- updating the keys in the Kerberos server's database to match by
- using the kadmin protocol. If a key's version number doesn't
- match the version number stored in the Kerberos server's database,
- then the operation will fail. The old keys are retained so that
+ Uses the kadmin protocol to update the keys in the Kerberos
+ database to new randomly-generated keys, and updates the keys in
+ the keytab to match. If a key's version number doesn't match the
+ version number stored in the Kerberos server's database, then the
+ operation will fail. Old keys are retained in the keytab so that
existing tickets continue to work. If the **-i** flag is given,
- k5srvutil will prompt for yes or no before changing each key. If
- the **-k** option is used, the old and new keys will be displayed.
+ k5srvutil will prompt for confirmation before changing each key.
+ If the **-k** option is given, the old and new keys will be
+ displayed.
**delold**
Deletes keys that are not the most recent version from the keytab.
This operation should be used some time after a change operation
- to remove old keys. If the **-i** flag is used, then the program
- prompts the user whether the old keys associated with each
- principal should be removed.
+ to remove old keys, after existing tickets issued for the service
+ have expired. If the **-i** flag is given, then k5srvutil will
+ prompt for confirmation for each principal.
**delete**
Deletes particular keys in the keytab, interactively prompting for
each key.
-In all cases, the default file used is ``/etc/krb5.keytab`` file
-unless this is overridden by the **-f** option.
+In all cases, the default keytab is used unless this is overridden by
+the **-f** option.
k5srvutil uses the :ref:`kadmin(1)` program to edit the keytab in
-place. However, old keys are retained, so they are available in case
-of failure.
+place.
SEE ALSO
Modified: trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -33,40 +33,31 @@
-----------
kadmin and kadmin.local are command-line interfaces to the Kerberos V5
-KADM5 administration system. Both kadmin and kadmin.local provide
-identical functionalities; the difference is that kadmin.local runs on
-the master KDC if the database is db2 and does not use Kerberos to
-authenticate to the database. Except as explicitly noted otherwise,
-this man page will use kadmin to refer to both versions. kadmin
-provides for the maintenance of Kerberos principals, KADM5 policies,
-and service key tables (keytabs).
+administration system. They provide nearly identical functionalities;
+the difference is that kadmin.local directly accesses the KDC
+database, while kadmin performs operations using :ref:`kadmind(8)`.
+Except as explicitly noted otherwise, this man page will use "kadmin"
+to refer to both versions. kadmin provides for the maintenance of
+Kerberos principals, password policies, and service key tables
+(keytabs).
-The remote version uses Kerberos authentication and an encrypted RPC,
-to operate securely from anywhere on the network. It authenticates to
-the KADM5 server using the service principal ``kadmin/admin``. If the
-credentials cache contains a ticket for the ``kadmin/admin``
-principal, and the **-c** credentials_cache option is specified, that
-ticket is used to authenticate to KADM5. Otherwise, the **-p** and
+The remote kadmin client uses Kerberos to authenticate to kadmind
+using the service principal ``kadmin/ADMINHOST`` (where *ADMINHOST* is
+the fully-qualified hostname of the admin server) or ``kadmin/admin``.
+If the credentials cache contains a ticket for one of these
+principals, and the **-c** credentials_cache option is specified, that
+ticket is used to authenticate to kadmind. Otherwise, the **-p** and
**-k** options are used to specify the client Kerberos principal name
used to authenticate. Once kadmin has determined the principal name,
-it requests a ``kadmin/admin`` Kerberos service ticket from the KDC,
-and uses that service ticket to authenticate to KADM5.
+it requests a service ticket from the KDC, and uses that service
+ticket to authenticate to kadmind.
-If the database is db2, the local client kadmin.local is intended to
-run directly on the master KDC without Kerberos authentication. The
-local version provides all of the functionality of the now obsolete
-kdb5_edit(8), except for database dump and load, which is now provided
-by the :ref:`kdb5_util(8)` utility.
+Since kadmin.local directly accesses the KDC database, it usually must
+be run directly on the master KDC with sufficient permissions to read
+the KDC database. If the KDC database uses the LDAP database module,
+kadmin.local can be run on any host which can access the LDAP server.
-If the database is LDAP, kadmin.local need not be run on the KDC.
-kadmin.local can be configured to log updates for incremental database
-propagation. Incremental propagation allows slave KDC servers to
-receive principal and policy updates incrementally instead of
-receiving full dumps of the database. This facility can be enabled in
-the :ref:`kdc.conf(5)` file with the **iprop_enable** option.
-
-
OPTIONS
-------
@@ -83,8 +74,8 @@
**-k**
Use a keytab to decrypt the KDC response instead of prompting for
- a password on the TTY. In this case, the default principal will
- be ``host/hostname``. If there is not a keytab specified with the
+ a password. In this case, the default principal will be
+ ``host/hostname``. If there is no keytab specified with the
**-t** option, then the default keytab will be used.
**-t** *keytab*
@@ -93,7 +84,7 @@
**-n**
Requests anonymous processing. Two types of anonymous principals
- are supported. For fully anonymous Kerberos, configure pkinit on
+ are supported. For fully anonymous Kerberos, configure PKINIT on
the KDC and configure **pkinit_anchors** in the client's
:ref:`krb5.conf(5)`. Then use the **-n** option with a principal
of the form ``@REALM`` (an empty principal name followed by the
@@ -108,34 +99,32 @@
**-c** *credentials_cache*
Use *credentials_cache* as the credentials cache. The
- *credentials_cache* should contain a service ticket for the
- ``kadmin/admin`` service; it can be acquired with the
+ cache should contain a service ticket for the ``kadmin/ADMINHOST``
+ (where *ADMINHOST* is the fully-qualified hostname of the admin
+ server) or ``kadmin/admin`` service; it can be acquired with the
:ref:`kinit(1)` program. If this option is not specified, kadmin
requests a new service ticket from the KDC, and stores it in its
own temporary ccache.
**-w** *password*
- Use *password* instead of prompting for one on the TTY.
+ Use *password* instead of prompting for one. Use this option with
+ care, as it may expose the password to other users on the system
+ via the process list.
- .. note:: Placing the password for a Kerberos principal with
- administration access into a shell script can be
- dangerous if unauthorized users gain read access to the
- script.
-
**-q** *query*
- Pass query directly to kadmin, which will perform query and then
- exit. This can be useful for writing scripts.
+ Perform the specified query and then exit. This can be useful for
+ writing scripts.
**-d** *dbname*
- Specifies the name of the Kerberos database. This option does not
- apply to the LDAP database.
+ Specifies the name of the KDC database. This option does not
+ apply to the LDAP database module.
**-s** *admin_server*\ [:*port*]
Specifies the admin server which kadmin should contact.
**-m**
- Do not authenticate using a keytab. This option will cause kadmin
- to prompt for the master database password.
+ If using kadmin.local, prompt for the database master password
+ instead of reading it from a stash file.
**-e** "*enc*:*salt* ..."
Sets the list of encryption types and salt types to be used for
@@ -149,7 +138,7 @@
**-x** *db_args*
Specifies the database specific arguments. Options supported for
- LDAP database are:
+ the LDAP database module are:
**-x host=**\ *hostname*
specifies the LDAP server to connect to by a LDAP URI.
@@ -157,22 +146,26 @@
**-x binddn=**\ *bind_dn*
specifies the DN of the object used by the administration
server to bind to the LDAP server. This object should have
- the read and write rights on the realm container, principal
- container and the subtree that is referenced by the realm.
+ the read and write privileges on the realm container, the
+ principal container, and the subtree that is referenced by the
+ realm.
**-x bindpwd=**\ *bind_password*
- specifies the password for the above mentioned binddn. It is
- recommended not to use this option. Instead, the password can
- be stashed using the *stashsrvpw* command of
- :ref:`kdb5_ldap_util(8)`
+ specifies the password for the above mentioned binddn. Using
+ this option may expose the password to other users on the
+ system via the process list; to avoid this, instead stash the
+ password using the **stashsrvpw** command of
+ :ref:`kdb5_ldap_util(8)`.
.. _kadmin_options_end:
+.. _date_format:
+
DATE FORMAT
-----------
-.. _date_format:
+.. _date_format_start:
Many of the kadmin commands take a duration or time as an
argument. The date can appear in a wide variety of formats, such as:
@@ -201,14 +194,22 @@
The following is a list of all of the allowable keywords.
-========================== ============================================
-Months january, jan, february, feb, march, mar, april, apr, may, june, jun, july, jul, august, aug, september, sep, sept, october, oct, november, nov, december, dec
-Days sunday, sun, monday, mon, tuesday, tues, tue, wednesday, wednes, wed, thursday, thurs, thur, thu, friday, fri, saturday, sat
-Units year, month, fortnight, week, day, hour, minute, min, second, sec
-Relative tomorrow, yesterday, today, now, last, this, next, first, second, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth, ago
-Time Zones kadmin recognizes abbreviations for most of the world's time zones. A complete listing appears in kadmin Time Zones.
-12-hour Time Delimiters am, pm
-========================== ============================================
+========== ==========================================================
+Months january, jan, february, feb, march, mar, april, apr, may,
+ june, jun, july, jul, august, aug, september, sep, sept,
+ october, oct, november, nov, december, dec
+Days sunday, sun, monday, mon, tuesday, tues, tue, wednesday,
+ wednes, wed, thursday, thurs, thur, thu, friday, fri,
+ saturday, sat
+Units year, month, fortnight, week, day, hour, minute, min,
+ second, sec
+Relative tomorrow, yesterday, today, now, last, this, next, first,
+ second, third, fourth, fifth, sixth, seventh, eighth,
+ ninth, tenth, eleventh, twelfth, ago
+Time Zones kadmin recognizes abbreviations for most of the world's
+ time zones.
+Meridians am, pm
+========== ==========================================================
.. _date_format_end:
@@ -216,8 +217,9 @@
COMMANDS
--------
-Note that the privileges are based on the kadm5.acl file on the master
-KDC.
+When using the remote client, available commands may be restricted
+according to the privileges specified in the kadm5.acl file on the
+admin server.
.. _add_principal:
@@ -227,49 +229,18 @@
**add_principal** [*options*] *newprinc*
Creates the principal *newprinc*, prompting twice for a password. If
-no policy is specified with the **-policy** option, and the policy
-named ``default`` exists, then that policy is assigned to the
-principal; note that the assignment of the policy ``default`` only
-occurs automatically when a principal is first created, so the policy
-``default`` must already exist for the assignment to occur. This
-assignment of ``default`` can be suppressed with the **-clearpolicy**
-option.
+no password policy is specified with the **-policy** option, and the
+policy named ``default`` is assigned to the principal if it exists.
+However, creating a policy named ``default`` will not automatically
+assign this policy to previously existing principals. This policy
+assignment can be suppressed with the **-clearpolicy** option.
-.. note:: This command requires the **add** privilege.
+This command requires the **add** privilege.
Aliases: **addprinc**, **ank**
-The options are:
+Options:
-**-x** *db_princ_args*
- Denotes the database specific options. The options for LDAP
- database are:
-
- **-x dn=**\ *dn*
- Specifies the LDAP object that will contain the Kerberos
- principal being created.
-
- **-x linkdn=**\ *dn*
- Specifies the LDAP object to which the newly created Kerberos
- principal object will point to.
-
- **-x containerdn=**\ *container_dn*
- Specifies the container object under which the Kerberos
- principal is to be created.
-
- **-x tktpolicy=**\ *policy*
- Associates a ticket policy to the Kerberos principal.
-
- .. note::
- - *containerdn* and *linkdn* options cannot be
- specified with *dn* option.
- - If *dn* or *containerdn* options are not specified
- while adding the principal, the principals are
- created under the prinicipal container configured in
- the realm or the realm container.
- - *dn* and *containerdn* should be within the subtrees
- or principal container configured in the realm.
-
**-expire** *expdate*
expiration date of the principal
@@ -283,137 +254,131 @@
maximum renewable life of tickets for the principal
**-kvno** *kvno*
- explicitly set the key version number.
+ initial key version number
**-policy** *policy*
- policy used by this principal. If no policy is supplied, then if
- the policy "default" exists and the **-clearpolicy** is not also
- specified, then the policy "default" is used; otherwise, the
- principal will have no policy, and a warning message will be
- printed.
+ password policy used by this principal. If not specified, the
+ policy ``default`` is used if it exists (unless **-clearpolicy**
+ is specified).
**-clearpolicy**
- prevents the policy "default" from being assigned when **-policy**
- is not specified. This option has no effect if the policy
- "default" does not exist.
+ prevents any policy from being assigned when **-policy** is not
+ specified.
{-\|+}\ **allow_postdated**
**-allow_postdated** prohibits this principal from obtaining
- postdated tickets. (Sets the **KRB5_KDB_DISALLOW_POSTDATED**
- flag.) **+allow_postdated** clears this flag.
+ postdated tickets. **+allow_postdated** clears this flag.
{-\|+}\ **allow_forwardable**
**-allow_forwardable** prohibits this principal from obtaining
- forwardable tickets. (Sets the **KRB5_KDB_DISALLOW_FORWARDABLE**
- flag.) **+allow_forwardable** clears this flag.
+ forwardable tickets. **+allow_forwardable** clears this flag.
{-\|+}\ **allow_renewable**
**-allow_renewable** prohibits this principal from obtaining
- renewable tickets. (Sets the **KRB5_KDB_DISALLOW_RENEWABLE**
- flag.) **+allow_renewable** clears this flag.
+ renewable tickets. **+allow_renewable** clears this flag.
{-\|+}\ **allow_proxiable**
**-allow_proxiable** prohibits this principal from obtaining
- proxiable tickets. (Sets the **KRB5_KDB_DISALLOW_PROXIABLE**
- flag.) **+allow_proxiable** clears this flag.
+ proxiable tickets. **+allow_proxiable** clears this flag.
{-\|+}\ **allow_dup_skey**
**-allow_dup_skey** disables user-to-user authentication for this
principal by prohibiting this principal from obtaining a session
- key for another user. (Sets the **KRB5_KDB_DISALLOW_DUP_SKEY**
- flag.) **+allow_dup_skey** clears this flag.
+ key for another user. **+allow_dup_skey** clears this flag.
{-\|+}\ **requires_preauth**
**+requires_preauth** requires this principal to preauthenticate
- before being allowed to kinit. (Sets the
- **KRB5_KDB_REQUIRES_PRE_AUTH** flag.) **-requires_preauth**
- clears this flag.
+ before being allowed to kinit. **-requires_preauth** clears this
+ flag.
{-\|+}\ **requires_hwauth**
**+requires_hwauth** requires this principal to preauthenticate
- using a hardware device before being allowed to kinit. (Sets the
- **KRB5_KDB_REQUIRES_HW_AUTH** flag.) **-requires_hwauth** clears
- this flag.
+ using a hardware device before being allowed to kinit.
+ **-requires_hwauth** clears this flag.
{-\|+}\ **ok_as_delegate**
- **+ok_as_delegate** sets the OK-AS-DELEGATE flag on tickets issued
- for use with this principal as the service, which clients may use
- as a hint that credentials can and should be delegated when
- authenticating to the service. (Sets the
- **KRB5_KDB_OK_AS_DELEGATE** flag.) **-ok_as_delegate** clears
- this flag.
+ **+ok_as_delegate** sets the **okay as delegate** flag on tickets
+ issued with this principal as the service. Clients may use this
+ flag as a hint that credentials should be delegated when
+ authenticating to the service. **-ok_as_delegate** clears this
+ flag.
{-\|+}\ **allow_svr**
**-allow_svr** prohibits the issuance of service tickets for this
- principal. (Sets the **KRB5_KDB_DISALLOW_SVR** flag.)
- **+allow_svr** clears this flag.
+ principal. **+allow_svr** clears this flag.
{-\|+}\ **allow_tgs_req**
**-allow_tgs_req** specifies that a Ticket-Granting Service (TGS)
request for a service ticket for this principal is not permitted.
- This option is useless for most things. **+allow_tgs_req** clears
- this flag. The default is +allow_tgs_req. In effect,
- **-allow_tgs_req sets** the **KRB5_KDB_DISALLOW_TGT_BASED** flag
- on the principal in the database.
+ **+allow_tgs_req** clears this flag.
{-\|+}\ **allow_tix**
**-allow_tix** forbids the issuance of any tickets for this
- principal. **+allow_tix** clears this flag. The default is
- **+allow_tix**. In effect, **-allow_tix** sets the
- **KRB5_KDB_DISALLOW_ALL_TIX** flag on the principal in the
- database.
+ principal. **+allow_tix** clears this flag.
{-\|+}\ **needchange**
- **+needchange** sets a flag in attributes field to force a
- password change; **-needchange** clears it. The default is
- **-needchange**. In effect, **+needchange** sets the
- **KRB5_KDB_REQUIRES_PWCHANGE** flag on the principal in the
- database.
+ **+needchange** forces a password change on the next initial
+ authentication to this principal. **-needchange** clears this
+ flag.
{-\|+}\ **password_changing_service**
- **+password_changing_service** sets a flag in the attributes field
- marking this as a password change service principal (useless for
- most things). **-password_changing_service** clears the flag.
- This flag intentionally has a long name. The default is
- **-password_changing_service**. In effect,
- **+password_changing_service** sets the
- *KRB5_KDB_PWCHANGE_SERVICE* flag on the principal in the database.
+ **+password_changing_service** marks this principal as a password
+ change service principal.
**-randkey**
sets the key of the principal to a random value
**-pw** *password*
- sets the key of the principal to the specified string and does not
- prompt for a password. Note: using this option in a shell script
- can be dangerous if unauthorized users gain read access to the
- script.
+ sets the password of the principal to the specified string and
+ does not prompt for a password. Note: using this option in a
+ shell script may expose the password to other users on the system
+ via the process list.
-**-e** "*enc*:*salt* ..."
+**-e** *enc*:*salt*,...
uses the specified list of enctype-salttype pairs for setting the
- key of the principal. The quotes are necessary if there are
- multiple enctype-salttype pairs. This will not function against
- kadmin daemons earlier than krb5-1.2.
+ key of the principal.
+**-x** *db_princ_args*
+ indicates database-specific options. The options for the LDAP
+ database module are:
+
+ **-x dn=**\ *dn*
+ specifies the LDAP object that will contain the Kerberos
+ principal being created.
+
+ **-x linkdn=**\ *dn*
+ specifies the LDAP object to which the newly created Kerberos
+ principal object will point.
+
+ **-x containerdn=**\ *container_dn*
+ specifies the container object under which the Kerberos
+ principal is to be created.
+
+ **-x tktpolicy=**\ *policy*
+ associates a ticket policy to the Kerberos principal.
+
+ .. note::
+ - The **containerdn** and **linkdn** options cannot be
+ specified with the **dn** option.
+ - If the *dn* or *containerdn* options are not specified while
+ adding the principal, the principals are created under the
+ principal container configured in the realm or the realm
+ container.
+ - *dn* and *containerdn* should be within the subtrees or
+ principal container configured in the realm.
+
Example:
+
::
kadmin: addprinc jennifer
WARNING: no policy specified for "jennifer at ATHENA.MIT.EDU";
defaulting to no policy.
- Enter password for principal jennifer at ATHENA.MIT.EDU: <= Type the password.
- Re-enter password for principal jennifer at ATHENA.MIT.EDU: <=Type it again.
+ Enter password for principal jennifer at ATHENA.MIT.EDU:
+ Re-enter password for principal jennifer at ATHENA.MIT.EDU:
Principal "jennifer at ATHENA.MIT.EDU" created.
kadmin:
-Errors:
- ::
-
- KADM5_AUTH_ADD (requires "add" privilege)
- KADM5_BAD_MASK (shouldn't happen)
- KADM5_DUP (principal exists already)
- KADM5_UNK_POLICY (policy does not exist)
- KADM5_PASS_Q_* (password quality violations)
-
.. _add_principal_end:
.. _modify_principal:
@@ -423,43 +388,22 @@
**modify_principal** [*options*] *principal*
-Modifies the specified principal, changing the fields as
-specified. The options are as above for **add_principal**, except that
-password changing and flags related to password changing are forbidden
-by this command. In addition, the option **-clearpolicy** will clear
-the current policy of a principal.
+Modifies the specified principal, changing the fields as specified.
+The options to **add_principal** also apply to this command, except
+for the **-randkey**, **-pw**, and **-e** options. In addition, the
+option **-clearpolicy** will clear the current policy of a principal.
-.. note:: This command requires the *modify* privilege.
+This command requires the *modify* privilege.
Alias: **modprinc**
-The options are:
+Options (in addition to the **addprinc** options):
-**-x** *db_princ_args*
- Denotes the database specific options. The options for LDAP
- database are:
-
- **-x tktpolicy=**\ *policy*
- Associates a ticket policy to the Kerberos principal.
-
- **-x linkdn=**\ *dn*
- Associates a Kerberos principal with a LDAP object. This
- option is honored only if the Kerberos principal is not
- already associated with a LDAP object.
-
**-unlock**
Unlocks a locked principal (one which has received too many failed
authentication attempts without enough time between them according
to its password policy) so that it can successfully authenticate.
-Errors:
- ::
-
- KADM5_AUTH_MODIFY (requires "modify" privilege)
- KADM5_UNK_PRINC (principal does not exist)
- KADM5_UNK_POLICY (policy does not exist)
- KADM5_BAD_MASK (shouldn't happen)
-
.. _modify_principal_end:
.. _rename_principal:
@@ -473,18 +417,10 @@
command prompts for confirmation, unless the **-force** option is
given.
-.. note:: This command requires the **add** and **delete** privileges.
+This command requires the **add** and **delete** privileges.
Alias: **renprinc**
-Errors:
- ::
-
- KADM5_AUTH_ADD (requires "add" privilege)
- KADM5_AUTH_DELETE (requires "delete" privilege)
- KADM5_UNK_PRINC (principal does not exist)
- KADM5_DUP (principal exists already)
-
.. _rename_principal_end:
.. _delete_principal:
@@ -497,16 +433,10 @@
Deletes the specified *principal* from the database. This command
prompts for deletion, unless the **-force** option is given.
-.. note:: This command requires the **delete** privilege.
+This command requires the **delete** privilege.
Alias: **delprinc**
-Errors:
- ::
-
- KADM5_AUTH_DELETE (requires "delete" privilege)
- KADM5_UNK_PRINC (principal does not exist)
-
.. _delete_principal_end:
.. _change_password:
@@ -519,9 +449,9 @@
Changes the password of *principal*. Prompts for a new password if
neither **-randkey** or **-pw** is specified.
-.. note:: Requires the **changepw** privilege, or that the principal
- that is running the program to be the same as the one
- changed.
+This command requires the **changepw** privilege, or that the
+principal running the program is the same as the principal being
+changed.
Alias: **cpw**
@@ -531,22 +461,20 @@
Sets the key of the principal to a random value
**-pw** *password*
- Set the password to the specified string. Not recommended.
+ Set the password to the specified string. Using this option in a
+ script may expose the password to other users on the system via
+ the process list.
-**-e** "*enc*:*salt* ..."
+**-e** *enc*:*salt*,...
Uses the specified list of enctype-salttype pairs for setting the
- key of the principal. The quotes are necessary if there are
- multiple enctype-salttype pairs. This will not function against
- kadmin daemons earlier than krb5-1.2. See
- :ref:`Supported_Encryption_Types_and_Salts` for possible values.
+ key of the principal.
**-keepold**
- Keeps the previous kvno's keys around. This flag is usually not
- necessary except perhaps for TGS keys. Don't use this flag unless
- you know what you're doing. This option is not supported for the
- LDAP database.
+ Keeps the existing keys in the database. This flag is usually not
+ necessary except perhaps for ``krbtgt`` principals.
Example:
+
::
kadmin: cpw systest
@@ -555,15 +483,6 @@
Password for systest at BLEEP.COM changed.
kadmin:
-Errors:
- ::
-
- KADM5_AUTH_MODIFY (requires the modify privilege)
- KADM5_UNK_PRINC (principal does not exist)
- KADM5_PASS_Q_* (password policy violation errors)
- KADM5_PADD_REUSE (password is in principal's password history)
- KADM5_PASS_TOOSOON (current password minimum life not expired)
-
.. _change_password_end:
.. _purgekeys:
@@ -577,7 +496,7 @@
-keepold**) from *principal*. If **-keepkvno** is specified, then
only purges keys with kvnos lower than *oldest_kvno_to_keep*.
-.. note:: This command requires the **modify** privilege.
+This command requires the **modify** privilege.
.. _purgekeys_end:
@@ -591,13 +510,13 @@
Gets the attributes of principal. With the **-terse** option, outputs
fields as quoted tab-separated strings.
-.. note:: Requires the **inquire** privilege, or that the principal
- that is running the the program to be the same as the one
- being listed.
+This command requires the **inquire** privilege, or that the principal
+running the the program to be the same as the one being listed.
Alias: **getprinc**
Examples:
+
::
kadmin: getprinc tlyu/admin
@@ -623,12 +542,6 @@
tlyu/admin at BLEEP.COM 786100034 0 0
kadmin:
-Errors:
- ::
-
- KADM5_AUTH_GET (requires the get (inquire) privilege)
- KADM5_UNK_PRINC (principal does not exist)
-
.. _get_principal_end:
.. _list_principals:
@@ -638,7 +551,7 @@
**list_principals** [*expression*]
-Retrieves all or some principal names. Expression is a shell-style
+Retrieves all or some principal names. *expression* is a shell-style
glob expression that can contain the wild-card characters ``?``,
``*``, and ``[]``. All principal names matching the expression are
printed. If no expression is provided, all principal names are
@@ -646,11 +559,12 @@
``@`` character followed by the local realm is appended to the
expression.
-.. note:: Requires the **list** privilege.
+This command requires the **list** privilege.
Alias: **listprincs**, **get_principals**, **get_princs**
Example:
+
::
kadmin: listprincs test*
@@ -672,7 +586,7 @@
Displays string attributes on *principal*. String attributes are used
to supply per-principal configuration to some KDC plugin modules.
-.. note:: Requires the **inquire** privilege.
+This command requires the **inquire** privilege.
Alias: **getstr**
@@ -687,7 +601,7 @@
Sets a string attribute on *principal*.
-.. note:: This command requires the **modify** privilege.
+This command requires the **modify** privilege.
Alias: **setstr**
@@ -702,7 +616,7 @@
Deletes a string attribute from *principal*.
-.. note:: This command requires the **delete** privilege.
+This command requires the **delete** privilege.
Alias: **delstr**
@@ -715,9 +629,9 @@
**add_policy** [*options*] *policy*
-Adds the named *policy* to the policy database.
+Adds a password policy named *policy* to the database.
-.. note:: Requires the **add** privilege.
+This command requires the **add** privilege.
Alias: **addpol**
@@ -736,8 +650,8 @@
sets the minimum number of character classes allowed in a password
**-history** *number*
- sets the number of past keys kept for a principal. This option is
- not supported for LDAP database
+ sets the number of past keys kept for a principal. This option is
+ not supported with the LDAP KDC database module.
**-maxfailure** *maxnumber*
sets the maximum number of authentication failures before the
@@ -752,22 +666,17 @@
**-lockoutduration** *lockouttime*
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.
+ authenticating if too many authentication failures occur without
+ the specified failure count interval elapsing. A duration of 0
+ means forever.
Example:
+
::
kadmin: add_policy -maxlife "2 days" -minlength 5 guests
kadmin:
-Errors:
- ::
-
- KADM5_AUTH_ADD (requires the add privilege)
- KADM5_DUP (policy already exists)
-
.. _add_policy_end:
.. _modify_policy:
@@ -777,18 +686,13 @@
**modify_policy** [*options*] *policy*
-Modifies the named *policy*. Options are as above for *add_policy*.
+Modifies the password policy named *policy*. Options are as described
+for **add_policy**.
-.. note:: Requires the **modify** privilege.
+This command requires the **modify** privilege.
Alias: **modpol**
-Errors:
- ::
-
- KADM5_AUTH_MODIFY (requires the modify privilege)
- KADM5_UNK_POLICY (policy does not exist)
-
.. _modify_policy_end:
.. _delete_policy:
@@ -798,14 +702,16 @@
**delete_policy** [**-force**] *policy*
-Deletes the named *policy*. Prompts for confirmation before deletion.
-The command will fail if the policy is in use by any principals.
+Deletes the password policy named *policy*. Prompts for confirmation
+before deletion. The command will fail if the policy is in use by any
+principals.
-.. note:: Requires the **delete** privilege.
+This command requires the **delete** privilege.
Alias: **delpol**
Example:
+
::
kadmin: del_policy guests
@@ -813,13 +719,6 @@
(yes/no): yes
kadmin:
-Errors:
- ::
-
- KADM5_AUTH_DELETE (requires the delete privilege)
- KADM5_UNK_POLICY (policy does not exist)
- KADM5_POLICY_REF (reference count on policy is not zero)
-
.. _delete_policy_end:
.. _get_policy:
@@ -829,14 +728,16 @@
**get_policy** [ **-terse** ] *policy*
-Displays the values of the named *policy*. With the **-terse** flag,
-outputs the fields as quoted strings separated by tabs.
+Displays the values of the password policy named *policy*. With the
+**-terse** flag, outputs the fields as quoted strings separated by
+tabs.
-.. note:: Requires the **inquire** privilege.
+This command requires the **inquire** privilege.
Alias: getpol
Examples:
+
::
kadmin: get_policy admin
@@ -853,13 +754,9 @@
kadmin:
The "Reference count" is the number of principals using that policy.
+With the LDAP KDC database module, the reference count field is not
+meaningful.
-Errors:
- ::
-
- KADM5_AUTH_GET (requires the get privilege)
- KADM5_UNK_POLICY (policy does not exist)
-
.. _get_policy_end:
.. _list_policies:
@@ -875,11 +772,12 @@
printed. If no expression is provided, all existing policy names are
printed.
-.. note:: Requires the **list** privilege.
+This command requires the **list** privilege.
Aliases: **listpols**, **get_policies**, **getpols**.
Examples:
+
::
kadmin: listpols
@@ -895,24 +793,6 @@
.. _list_policies_end:
-get_privs
-~~~~~~~~~
-
- **get_privs**
-
-Returns the Kerberos administrative privileges of the principal that
-is currently running kadmin.
-
-Alias: **getprivs**
-
-Example:
- ::
-
- kadmin: get_privs
- Principal joe/admin at ATHENA.MIT.EDU
- current privileges: GET, ADD, MODIFY, DELETE
- kadmin:
-
.. _ktadd:
ktadd
@@ -920,56 +800,44 @@
**ktadd** [[*principal*\|\ **-glob** *princ-exp*]
-Adds a *principal* or all principals matching *princ-exp* to a keytab
-file. It randomizes each principal's key in the process, to prevent a
-compromised admin account from reading out all of the keys from the
-database. The rules for principal expression are the same as for the
-*kadmin* :ref:`list_principals` command.
+Adds a *principal*, or all principals matching *princ-exp*, to a
+keytab file. Each principal's keys are randomized in the process.
+The rules for *princ-exp* are described in the **list_principals**
+command.
-.. note:: Requires the **inquire** and **changepw** privileges. If
- you use the **-glob** option, it also requires the **list**
- administrative privilege.
+This command requires the **inquire** and **changepw** privileges.
+With the **-glob** option, it also requires the **list** privilege.
The options are:
**-k[eytab]** *keytab*
- Use *keytab* as the keytab file. Otherwise, ktadd will use the
- default keytab file (``/etc/krb5.keytab``).
+ Use *keytab* as the keytab file. Otherwise, the default keytab is
+ used.
-**-e** "*enc*:*salt* ..."*
+**-e** *enc*:*salt*,...
Use the specified list of enctype-salttype pairs for setting the
- key of the principal. The enctype-salttype pairs may be delimited
- with commas or whitespace. The quotes are necessary for
- whitespace-delimited list. If this option is not specified, then
- **supported_enctypes** from :ref:`krb5.conf(5)` will be used. See
- :ref:`Supported_Encryption_Types_and_Salts` for all possible
- values.
+ new keys of the principal.
**-q**
- Run in quiet mode. This causes *ktadd* to display less verbose
- information.
+ Display less verbose information.
**-norandkey**
Do not randomize the keys. The keys and their version numbers stay
- unchanged. That allows users to continue to use the passwords
- they know to login normally, while simultaneously allowing scripts
- to login to the same account using a keytab. There is no
- significant security risk added since kadmin.local must be run by
- root on the KDC anyway. This option is only available in
- kadmin.local and cannot be specified in combination with **-e**
- option.
+ unchanged. This option is only available in kadmin.local, and
+ cannot be specified in combination with the **-e** option.
An entry for each of the principal's unique encryption types is added,
ignoring multiple keys with the same encryption type but different
salt types.
Example:
+
::
kadmin: ktadd -k /tmp/foo-new-keytab host/foo.mit.edu
- Entry for principal host/foo.mit.edu at ATHENA.MIT.EDU with
- kvno 3, encryption type DES-CBC-CRC added to keytab
- WRFILE:/tmp/foo-new-keytab
+ Entry for principal host/foo.mit.edu at ATHENA.MIT.EDU with kvno 3,
+ encryption type aes256-cts-hmac-sha1-96 added to keytab
+ FILE:/tmp/foo-new-keytab
kadmin:
.. _ktadd_end:
@@ -993,19 +861,19 @@
The options are:
**-k[eytab]** *keytab*
- Use keytab as the keytab file. Otherwise, ktremove will use the
- default keytab file (``/etc/krb5.keytab``).
+ Use *keytab* as the keytab file. Otherwise, the default keytab is
+ used.
**-q**
- Run in quiet mode. This causes ktremove to display less verbose
- information.
+ Display less verbose information.
Example:
+
::
- kadmin: ktremove -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin all
- Entry for principal kadmin/admin with kvno 3 removed
- from keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
+ kadmin: ktremove kadmin/admin all
+ Entry for principal kadmin/admin with kvno 3 removed from keytab
+ FILE:/etc/krb5.keytab
kadmin:
.. _ktremove_end:
@@ -1013,7 +881,7 @@
lock
~~~~
-Lock database exclusively. Use with extreme caution!
+Lock database exclusively. Use with extreme caution!
unlock
~~~~~~
@@ -1023,8 +891,7 @@
list_requests
~~~~~~~~~~~~~
-Lists available for kadmin requests. This is a generic, unrelated to
-Kerberos command.
+Lists available for kadmin requests.
Aliases: **lr**, **?**
@@ -1036,21 +903,6 @@
Aliases: **exit**, **q**
-FILES
------
-
-.. note:: The first three files are specific to db2 database.
-
-====================== =================================================
-principal.db default name for Kerberos principal database
-<dbname>.kadm5 KADM5 administrative database. (This would be "principal.kadm5", if you use the default database name.) Contains policy information.
-<dbname>.kadm5.lock Lock file for the KADM5 administrative database. This file works backwards from most other lock files. I.e., *kadmin* will exit with an error if this file does not exist.
-kadm5.acl File containing list of principals and their *kadmin* administrative privileges. See kadmind(8) for a description.
-kadm5.keytab *keytab* file for *kadmin/admin* principal.
-kadm5.dict file containing dictionary of strings explicitly disallowed as passwords.
-====================== =================================================
-
-
HISTORY
-------
@@ -1061,4 +913,4 @@
SEE ALSO
--------
-kerberos(1), :ref:`kpasswd(1)`, kadmind(8)
+:ref:`kpasswd(1)`, :ref:`kadmind(8)`
Modified: trunk/doc/rst_source/krb_admins/admin_commands/kadmind.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kadmind.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kadmind.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -17,33 +17,32 @@
DESCRIPTION
-----------
-This command starts the KADM5 administration server. If the database
-is db2, the administration server runs on the master Kerberos server,
-which stores the KDC principal database and the KADM5 policy database.
-If the database is LDAP, the administration server and the KDC server
-need not run on the same machine. kadmind accepts remote requests to
-administer the information in these databases. Remote requests are
-sent, for example, by kadmin(8) and the :ref:`kpasswd(1)` command,
-both of which are clients of kadmind.
+kadmind starts the Kerberos administration server. kadmind typically
+runs on the master Kerberos server, which stores the KDC database. If
+the KDC database uses the LDAP module, the administration server and
+the KDC server need not run on the same machine. kadmind accepts
+remote requests from programs such as :ref:`kadmin(1)` and
+:ref:`kpasswd(1)` to administer the information in these database.
kadmind requires a number of configuration files to be set up in order
for it to work:
:ref:`kdc.conf(5)`
The KDC configuration file contains configuration information for
- the KDC and the KADM5 system. kadmind understands a number of
- variable settings in this file, some of which are mandatory and
- some of which are optional. See the CONFIGURATION VALUES section
- below.
+ the KDC and admin servers. kadmind uses settings in this file to
+ locate the Kerberos database, and is also affected by the
+ **acl_file**, **dict_file**, **kadmind_port**, and iprop-related
+ settings.
ACL file
kadmind's ACL (access control list) tells it which principals are
- allowed to perform KADM5 administration actions. The path of the
- ACL file is specified via the **acl_file** configuration variable
- (see CONFIGURATION VALUES). The syntax of the ACL file is
- specified in the ACL FILE SYNTAX section below.
+ 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 ``/usr/local/var/krb5kdc/kadm5.acl``. The
+ syntax of the ACL file is specified in the ACL FILE SYNTAX section
+ below.
- If the kadmind's ACL file is modified, the kadmind daemon needs to
+ If the kadmind ACL file is modified, the kadmind daemon needs to
be restarted for changes to take effect.
After the server begins running, it puts itself in the background and
@@ -62,80 +61,57 @@
OPTIONS
-------
-**-x** *db_args*
- specifies the database specific arguments.
-
- Options supported for LDAP database are:
-
- **-x nconns=**\ *number_of_connections*
- specifies the number of connections to be maintained per
- LDAP server.
-
- **-x host=**\ *ldapuri*
- specifies the LDAP server to connect to by a LDAP URI.
-
- **-x binddn=**\ *binddn*
- specifies the DN of the object used by the administration
- server to bind to the LDAP server. This object should
- have the read and write rights on the realm container,
- principal container and the subtree that is referenced by
- the realm.
-
- **-x bindpwd=**\ *bind_password*
- specifies the password for the above mentioned binddn. It
- is recommended not to use this option. Instead, the
- password can be stashed using the stashsrvpw command of
- kdb5_ldap_util.
-
**-r** *realm*
- specifies the default realm that kadmind will serve; if it is not
- specified, the default realm of the host is used. kadmind will
- answer requests for any realm that exists in the local KDC
- database and for which the appropriate principals are in its
- keytab.
+ specifies the realm that kadmind will serve; if it is not
+ specified, the default realm of the host is used.
**-m**
- specifies that the master database password should be fetched from
- the keyboard rather than from a file on disk. Note that the
- server gets the password prior to putting itself in the
- background; in combination with the **-nofork** option, you must
- place it in the background by hand.
+ causes the master database password to be fetched from the
+ keyboard (before the server puts itself in the background, if not
+ invoked with the **-nofork** option) rather than from a file on
+ disk.
**-nofork**
- specifies that the server does not put itself in the background
- and does not disassociate itself from the terminal. In normal
- operation, you should always allow the server place itself in the
- background.
+ causes the server to remain in the foreground and remain
+ associated to the terminal. In normal operation, you should allow
+ the server to place itself in the background.
**-port** *port-number*
specifies the port on which the administration server listens for
- connections. The default is is controlled by the **kadmind_port**
- configuration variable (see below).
+ connections. The default port is determined by the
+ **kadmind_port** configuration variable in :ref:`kdc.conf(5)`.
**-P** *pid_file*
specifies the file to which the PID of kadmind process should be
- written to after it starts up. This can be used to identify
+ written after it starts up. This file can be used to identify
whether kadmind is still running and to allow init scripts to stop
the correct process.
+**-x** *db_args*
+ specifies database-specific arguments.
-CONFIGURATION VALUES
---------------------
+ Options supported for LDAP database are:
-In addition to the relations defined in :ref:`kdc.conf(5)`, kadmind
-understands the following relations, all of which should appear in the
-[realms] section:
+ **-x nconns=**\ *number_of_connections*
+ specifies the number of connections to be maintained per
+ LDAP server.
-**acl_file**
- The path of kadmind's ACL file. **Mandatory**. No default.
+ **-x host=**\ *ldapuri*
+ specifies the LDAP server to connect to by URI.
-**dict_file**
- The path of kadmind's password dictionary. A principal with any
- password policy will not be allowed to select any password in the
- dictionary. Optional. No default.
+ **-x binddn=**\ *binddn*
+ specifies the DN of the object used by the administration
+ server to bind to the LDAP server. This object should
+ have read and write privileges on the realm container, the
+ principal container, and the subtree that is referenced by
+ the realm.
-**kadmind_port**
- The TCP port on which kadmind will listen. The default is 749.
+ **-x bindpwd=**\ *bind_password*
+ specifies the password for the above mentioned binddn.
+ Using this option may expose the password to other users
+ on the system via the process list; to avoid this, instead
+ stash the password using the **stashsrvpw** command of
+ :ref:`kdb5_ldap_util(8)`.
ACL FILE SYNTAX
@@ -144,27 +120,27 @@
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. This file can contain comment lines, null lines or lines
-which contain ACL entries. Comment lines start with the sharp sign
-(#) and continue until the end of the line. Lines containing ACL
-entries have the format of principal whitespace *operation-mask*
-[whitespace *operation-target*]
+principals. Empty lines and lines starting with the sharp sign
+(``#``) are ignored. Lines containing ACL entries have the format:
-Ordering is important. The first matching entry is the one which will
-control access for a particular principal on a particular principal.
+ ::
-**principal**
+ 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**
-
+*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**
+*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
@@ -172,31 +148,31 @@
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.
+ == ======================================================
- a [Dis]allows the addition of principals or policies in the database.
- d [Dis]allows the deletion of principals or policies in the database.
- m [Dis]allows the modification of principals or policies in the database.
- c [Dis]allows the changing of passwords for principals in the database.
- i [Dis]allows inquiries to the database.
- l [Dis]allows the listing of principals or policies in the database.
- 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
+ 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
+ the target's password, request information about the target,
and modify it.
``user/*@realm ac``
@@ -212,21 +188,7 @@
principals whose second component is ``instance`` and realm is
``realm``.
-FILES
------
-Note: The first three files are specific to db2 database.
-
-==================== ===================================================================
-principal.db default name for Kerberos principal database
-<dbname>.kadm5 KADM5 administrative database. (This would be "principal.kadm5", if you use the default database name.) Contains policy information.
-<dbname>.kadm5.lock lock file for the KADM5 administrative database. This file works backwards from most other lock files. I.e., kadmin will exit with an error if this file does not exist.
-kadm5.acl file containing list of principals and their kadmin administrative privileges. See above for a description.
-kadm5.keytab keytab file for *kadmin/admin* principal.
-kadm5.dict file containing dictionary of strings explicitly disallowed as passwords.
-==================== ===================================================================
-
-
SEE ALSO
--------
Modified: trunk/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -16,12 +16,14 @@
.. _kdb5_ldap_util_synopsis_end:
+
DESCRIPTION
-----------
kdb5_ldap_util allows an administrator to manage realms, Kerberos
services and ticket policies.
+
COMMAND-LINE OPTIONS
--------------------
@@ -116,94 +118,16 @@
realm.
*ticket_flags*
- Specifies the ticket flags. If this option is not specified, by
- default, none of the flags are set. This means all the ticket
- options will be allowed and no restriction will be set.
+ Specifies global ticket flags for the realm. Allowable flags are
+ documented in the description of the **add_principal** command in
+ :ref:`kadmin(1)`.
- The various flags are:
+Example:
- {-\|+}\ **allow_postdated**
- **-allow_postdated** prohibits this principal from obtaining
- postdated tickets. (Sets the **KRB5_KDB_DISALLOW_POSTDATED**
- flag.) **+allow_postdated** clears this flag.
-
- {-\|+}\ **allow_forwardable**
- **-allow_forwardable** prohibits this principal from obtaining
- forwardable tickets. (Sets the
- **KRB5_KDB_DISALLOW_FORWARDABLE** flag.)
- **+allow_forwardable** clears this flag.
-
- {-\|+}\ **allow_renewable**
- **-allow_renewable** prohibits this principal from obtaining
- renewable tickets. (Sets the **KRB5_KDB_DISALLOW_RENEWABLE**
- flag.) **+allow_renewable** clears this flag.
-
- {-\|+}\ **allow_proxiable**
- **-allow_proxiable** prohibits this principal from obtaining
- proxiable tickets. (Sets the **KRB5_KDB_DISALLOW_PROXIABLE**
- flag.) **+allow_proxiable** clears this flag.
-
- {-\|+}\ **allow_dup_skey**
- **-allow_dup_skey** disables user-to-user authentication for
- this principal by prohibiting this principal from obtaining a
- session key for another user. (Sets the
- **KRB5_KDB_DISALLOW_DUP_SKEY** flag.) **+allow_dup_skey**
- clears this flag.
-
- {-\|+}\ **requires_preauth**
- **+requires_preauth** requires this principal to
- preauthenticate before being allowed to kinit. (Sets the
- **KRB5_KDB_REQUIRES_PRE_AUTH** flag.) **-requires_preauth**
- clears this flag.
-
- {-\|+}\ **requires_hwauth**
- **+requires_hwauth** requires this principal to
- preauthenticate using a hardware device before being allowed
- to kinit. (Sets the **KRB5_KDB_REQUIRES_HW_AUTH** flag.)
- **-requires_hwauth** clears this flag.
-
- {-\|+}\ **allow_svr**
- **-allow_svr** prohibits the issuance of service tickets for
- this principal. (Sets the **KRB5_KDB_DISALLOW_SVR** flag.)
- **+allow_svr** clears this flag.
-
- {-\|+}\ **allow_tgs_req**
- **-allow_tgs_req** specifies that a Ticket-Granting Service
- (TGS) request for a service ticket for this principal is not
- permitted. This option is useless for most things.
- **+allow_tgs_req** clears this flag. The default is
- +allow_tgs_req. In effect, **-allow_tgs_req sets** the
- **KRB5_KDB_DISALLOW_TGT_BASED** flag on the principal in the
- database.
-
- {-\|+}\ **allow_tix**
- **-allow_tix** forbids the issuance of any tickets for this
- principal. **+allow_tix** clears this flag. The default is
- **+allow_tix**. In effect, **-allow_tix** sets the
- **KRB5_KDB_DISALLOW_ALL_TIX** flag on the principal in the
- database.
-
- {-\|+}\ **needchange**
- **+needchange** sets a flag in attributes field to force a
- password change; **-needchange** clears it. The default is
- **-needchange**. In effect, **+needchange** sets the
- **KRB5_KDB_REQUIRES_PWCHANGE** flag on the principal in the
- database.
-
- {-\|+}\ **password_changing_service**
- **+password_changing_service** sets a flag in the attributes
- field marking this as a password change service principal
- (useless for most things). **-password_changing_service**
- clears the flag. This flag intentionally has a long name.
- The default is **-password_changing_service**. In effect,
- **+password_changing_service** sets the
- *KRB5_KDB_PWCHANGE_SERVICE* flag on the principal in the
- database.
-
-EXAMPLE:
::
- kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu create -subtrees o=org -sscope SUB -r ATHENA.MIT.EDU
+ kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
+ create -subtrees o=org -sscope SUB -r ATHENA.MIT.EDU
Password for "cn=admin,o=org":
Initializing database for realm 'ATHENA.MIT.EDU'
You will be prompted for the database Master Password.
@@ -232,7 +156,6 @@
Modifies the attributes of a realm. Options:
**-subtrees** *subtree_dn_list*
-
Specifies the list of subtrees containing the principals of a
realm. The list contains the DNs of the subtree objects separated
by colon (``:``). This list replaces the existing list.
@@ -257,94 +180,17 @@
realm.
*ticket_flags*
- Specifies the ticket flags. If this option is not specified, by
- default, none of the flags are set. This means all the ticket
- options will be allowed and no restriction will be set.
+ Specifies global ticket flags for the realm. Allowable flags are
+ documented in the description of the **add_principal** command in
+ :ref:`kadmin(1)`.
- The various flags are:
+Example:
- {-\|+}\ **allow_postdated**
- **-allow_postdated** prohibits this principal from obtaining
- postdated tickets. (Sets the **KRB5_KDB_DISALLOW_POSTDATED**
- flag.) **+allow_postdated** clears this flag.
-
- {-\|+}\ **allow_forwardable**
- **-allow_forwardable** prohibits this principal from obtaining
- forwardable tickets. (Sets the
- **KRB5_KDB_DISALLOW_FORWARDABLE** flag.)
- **+allow_forwardable** clears this flag.
-
- {-\|+}\ **allow_renewable**
- **-allow_renewable** prohibits this principal from obtaining
- renewable tickets. (Sets the **KRB5_KDB_DISALLOW_RENEWABLE**
- flag.) **+allow_renewable** clears this flag.
-
- {-\|+}\ **allow_proxiable**
- **-allow_proxiable** prohibits this principal from obtaining
- proxiable tickets. (Sets the **KRB5_KDB_DISALLOW_PROXIABLE**
- flag.) **+allow_proxiable** clears this flag.
-
- {-\|+}\ **allow_dup_skey**
- **-allow_dup_skey** disables user-to-user authentication for
- this principal by prohibiting this principal from obtaining a
- session key for another user. (Sets the
- **KRB5_KDB_DISALLOW_DUP_SKEY** flag.) **+allow_dup_skey**
- clears this flag.
-
- {-\|+}\ **requires_preauth**
- **+requires_preauth** requires this principal to
- preauthenticate before being allowed to kinit. (Sets the
- **KRB5_KDB_REQUIRES_PRE_AUTH** flag.) **-requires_preauth**
- clears this flag.
-
- {-\|+}\ **requires_hwauth**
- **+requires_hwauth** requires this principal to
- preauthenticate using a hardware device before being allowed
- to kinit. (Sets the **KRB5_KDB_REQUIRES_HW_AUTH** flag.)
- **-requires_hwauth** clears this flag.
-
- {-\|+}\ **allow_svr**
- **-allow_svr** prohibits the issuance of service tickets for
- this principal. (Sets the **KRB5_KDB_DISALLOW_SVR** flag.)
- **+allow_svr** clears this flag.
-
- {-\|+}\ **allow_tgs_req**
- **-allow_tgs_req** specifies that a Ticket-Granting Service
- (TGS) request for a service ticket for this principal is not
- permitted. This option is useless for most things.
- **+allow_tgs_req** clears this flag. The default is
- +allow_tgs_req. In effect, **-allow_tgs_req sets** the
- **KRB5_KDB_DISALLOW_TGT_BASED** flag on the principal in the
- database.
-
- {-\|+}\ **allow_tix**
- **-allow_tix** forbids the issuance of any tickets for this
- principal. **+allow_tix** clears this flag. The default is
- **+allow_tix**. In effect, **-allow_tix** sets the
- **KRB5_KDB_DISALLOW_ALL_TIX** flag on the principal in the
- database.
-
- {-\|+}\ **needchange**
- **+needchange** sets a flag in attributes field to force a
- password change; **-needchange** clears it. The default is
- **-needchange**. In effect, **+needchange** sets the
- **KRB5_KDB_REQUIRES_PWCHANGE** flag on the principal in the
- database.
-
- {-\|+}\ **password_changing_service**
- **+password_changing_service** sets a flag in the attributes
- field marking this as a password change service principal
- (useless for most things). **-password_changing_service**
- clears the flag. This flag intentionally has a long name.
- The default is **-password_changing_service**. In effect,
- **+password_changing_service** sets the
- *KRB5_KDB_PWCHANGE_SERVICE* flag on the principal in the
- database.
-
-EXAMPLE:
::
- shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu modify +requires_preauth -r ATHENA.MIT.EDU
+ shell% kdb5_ldap_util -D cn=admin,o=org -H
+ ldaps://ldap-server1.mit.edu modify +requires_preauth -r
+ ATHENA.MIT.EDU
Password for "cn=admin,o=org":
shell%
@@ -362,10 +208,12 @@
**-r** *realm*
Specifies the Kerberos realm of the database.
-EXAMPLE:
+Example:
+
::
- kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu view -r ATHENA.MIT.EDU
+ kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
+ view -r ATHENA.MIT.EDU
Password for "cn=admin,o=org":
Realm Name: ATHENA.MIT.EDU
Subtree: ou=users,o=org
@@ -392,10 +240,12 @@
**-r** *realm*
Specifies the Kerberos realm of the database.
-EXAMPLE:
+Example:
+
::
- shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu destroy -r ATHENA.MIT.EDU
+ shell% kdb5_ldap_util -D cn=admin,o=org -H
+ ldaps://ldap-server1.mit.edu destroy -r ATHENA.MIT.EDU
Password for "cn=admin,o=org":
Deleting KDC database of 'ATHENA.MIT.EDU', are you sure?
(type 'yes' to confirm)? yes
@@ -413,10 +263,12 @@
Lists the name of realms.
-EXAMPLE:
+Example:
+
::
- shell% kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu list
+ shell% kdb5_ldap_util -D cn=admin,o=org -H
+ ldaps://ldap-server1.mit.edu list
Password for "cn=admin,o=org":
ATHENA.MIT.EDU
OPENLDAP.MIT.EDU
@@ -446,10 +298,12 @@
Specifies Distinguished Name (DN) of the service object whose
password is to be stored in file.
-EXAMPLE:
+Example:
+
::
- kdb5_ldap_util stashsrvpw -f /home/andrew/conf_keyfile cn=service-kdc,o=org
+ kdb5_ldap_util stashsrvpw -f /home/andrew/conf_keyfile
+ cn=service-kdc,o=org
Password for "cn=service-kdc,o=org":
Re-enter password for "cn=service-kdc,o=org":
@@ -467,7 +321,7 @@
[*ticket_flags*]
*policy_name*
-Creates a ticket policy in directory. Options:
+Creates a ticket policy in the directory. Options:
**-r** *realm*
Specifies the Kerberos realm of the database.
@@ -479,97 +333,22 @@
Specifies maximum renewable life of tickets for principals.
*ticket_flags*
- Specifies the ticket flags. If this option is not specified, by
- default, none of the flags are set. This means all the ticket
- options will be allowed and no restriction will be set.
+ Specifies the ticket flags. If this option is not specified, by
+ default, no restriction will be set by the policy. Allowable
+ flags are documented in the description of the **add_principal**
+ command in :ref:`kadmin(1)`.
- The various flags are:
-
- {-\|+}\ **allow_postdated**
- **-allow_postdated** prohibits this principal from obtaining
- postdated tickets. (Sets the **KRB5_KDB_DISALLOW_POSTDATED**
- flag.) **+allow_postdated** clears this flag.
-
- {-\|+}\ **allow_forwardable**
- **-allow_forwardable** prohibits this principal from obtaining
- forwardable tickets. (Sets the
- **KRB5_KDB_DISALLOW_FORWARDABLE** flag.)
- **+allow_forwardable** clears this flag.
-
- {-\|+}\ **allow_renewable**
- **-allow_renewable** prohibits this principal from obtaining
- renewable tickets. (Sets the **KRB5_KDB_DISALLOW_RENEWABLE**
- flag.) **+allow_renewable** clears this flag.
-
- {-\|+}\ **allow_proxiable**
- **-allow_proxiable** prohibits this principal from obtaining
- proxiable tickets. (Sets the **KRB5_KDB_DISALLOW_PROXIABLE**
- flag.) **+allow_proxiable** clears this flag.
-
- {-\|+}\ **allow_dup_skey**
- **-allow_dup_skey** disables user-to-user authentication for
- this principal by prohibiting this principal from obtaining a
- session key for another user. (Sets the
- **KRB5_KDB_DISALLOW_DUP_SKEY** flag.) **+allow_dup_skey**
- clears this flag.
-
- {-\|+}\ **requires_preauth**
- **+requires_preauth** requires this principal to
- preauthenticate before being allowed to kinit. (Sets the
- **KRB5_KDB_REQUIRES_PRE_AUTH** flag.) **-requires_preauth**
- clears this flag.
-
- {-\|+}\ **requires_hwauth**
- **+requires_hwauth** requires this principal to
- preauthenticate using a hardware device before being allowed
- to kinit. (Sets the **KRB5_KDB_REQUIRES_HW_AUTH** flag.)
- **-requires_hwauth** clears this flag.
-
- {-\|+}\ **allow_svr**
- **-allow_svr** prohibits the issuance of service tickets for
- this principal. (Sets the **KRB5_KDB_DISALLOW_SVR** flag.)
- **+allow_svr** clears this flag.
-
- {-\|+}\ **allow_tgs_req**
- **-allow_tgs_req** specifies that a Ticket-Granting Service
- (TGS) request for a service ticket for this principal is not
- permitted. This option is useless for most things.
- **+allow_tgs_req** clears this flag. The default is
- +allow_tgs_req. In effect, **-allow_tgs_req sets** the
- **KRB5_KDB_DISALLOW_TGT_BASED** flag on the principal in the
- database.
-
- {-\|+}\ **allow_tix**
- **-allow_tix** forbids the issuance of any tickets for this
- principal. **+allow_tix** clears this flag. The default is
- **+allow_tix**. In effect, **-allow_tix** sets the
- **KRB5_KDB_DISALLOW_ALL_TIX** flag on the principal in the
- database.
-
- {-\|+}\ **needchange**
- **+needchange** sets a flag in attributes field to force a
- password change; **-needchange** clears it. The default is
- **-needchange**. In effect, **+needchange** sets the
- **KRB5_KDB_REQUIRES_PWCHANGE** flag on the principal in the
- database.
-
- {-\|+}\ **password_changing_service**
- **+password_changing_service** sets a flag in the attributes
- field marking this as a password change service principal
- (useless for most things). **-password_changing_service**
- clears the flag. This flag intentionally has a long name.
- The default is **-password_changing_service**. In effect,
- **+password_changing_service** sets the
- *KRB5_KDB_PWCHANGE_SERVICE* flag on the principal in the
- database.
-
*policy_name*
Specifies the name of the ticket policy.
-EXAMPLE:
+Example:
+
::
- kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu create_policy -r ATHENA.MIT.EDU -maxtktlife "1 day" -maxrenewlife "1 week" -allow_postdated +needchange -allow_forwardable tktpolicy
+ kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
+ create_policy -r ATHENA.MIT.EDU -maxtktlife "1 day"
+ -maxrenewlife "1 week" -allow_postdated +needchange
+ -allow_forwardable tktpolicy
Password for "cn=admin,o=org":
.. _kdb5_ldap_util_create_policy_end:
@@ -586,16 +365,20 @@
[*ticket_flags*]
*policy_name*
-Modifies the attributes of a ticket policy. Options are same as
-create_policy.
+Modifies the attributes of a ticket policy. Options are same as for
+**create_policy**.
**-r** *realm*
Specifies the Kerberos realm of the database.
-EXAMPLE:
+Example:
+
::
- kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu modify_policy -r ATHENA.MIT.EDU -maxtktlife "60 minutes" -maxrenewlife "10 hours" +allow_postdated -requires_preauth tktpolicy
+ kdb5_ldap_util -D cn=admin,o=org -H
+ ldaps://ldap-server1.mit.edu modify_policy -r ATHENA.MIT.EDU
+ -maxtktlife "60 minutes" -maxrenewlife "10 hours"
+ +allow_postdated -requires_preauth tktpolicy
Password for "cn=admin,o=org":
.. _kdb5_ldap_util_modify_policy_end:
@@ -609,15 +392,17 @@
[**-r** *realm*]
*policy_name*
-Displays the attributes of a ticket policy. Options:
+Displays the attributes of a ticket policy. Options:
*policy_name*
Specifies the name of the ticket policy.
-EXAMPLE:
+Example:
+
::
- kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu view_policy -r ATHENA.MIT.EDU tktpolicy
+ kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
+ view_policy -r ATHENA.MIT.EDU tktpolicy
Password for "cn=admin,o=org":
Ticket policy: tktpolicy
Maximum ticket life: 0 days 01:00:00
@@ -636,7 +421,7 @@
[**-force**]
*policy_name*
-Destroys an existing ticket policy. Options:
+Destroys an existing ticket policy. Options:
**-r** *realm*
Specifies the Kerberos realm of the database.
@@ -649,10 +434,12 @@
*policy_name*
Specifies the name of the ticket policy.
-EXAMPLE:
+Example:
+
::
- kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu destroy_policy -r ATHENA.MIT.EDU tktpolicy
+ kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
+ destroy_policy -r ATHENA.MIT.EDU tktpolicy
Password for "cn=admin,o=org":
This will delete the policy object 'tktpolicy', are you sure?
(type 'yes' to confirm)? yes
@@ -674,10 +461,12 @@
**-r** *realm*
Specifies the Kerberos realm of the database.
-EXAMPLE:
+Example:
+
::
- kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu list_policy -r ATHENA.MIT.EDU
+ kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
+ list_policy -r ATHENA.MIT.EDU
Password for "cn=admin,o=org":
tktpolicy
tmppolicy
Modified: trunk/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -23,21 +23,20 @@
DESCRIPTION
-----------
-kdb5_util allows an administrator to perform low-level maintenance
-procedures on the Kerberos and KADM5 database. Databases can be
-created, destroyed, and dumped to and loaded from ASCII files.
-Additionally, kdb5_util can create a Kerberos master key stash file.
-kdb5_util subsumes the functionality of and makes obsolete the
-previous database maintenance programs kdb5_create, kdb5_edit,
-kdb5_destroy, and kdb5_stash.
+kdb5_util allows an administrator to perform maintenance procedures on
+the KDC database. Databases can be created, destroyed, and dumped to
+or loaded from ASCII files. kdb5_util can create a Kerberos master
+key stash file or perform live rollover of the master key.
When kdb5_util is run, it attempts to acquire the master key and open
the database. However, execution continues regardless of whether or
not kdb5_util successfully opens the database, because the database
may not exist yet or the stash file may be corrupt.
-Note that some KDB plugins may not support all kdb5_util commands.
+Note that some KDC database modules may not support all kdb5_util
+commands.
+
COMMAND-LINE OPTIONS
--------------------
@@ -49,7 +48,7 @@
**-d** *dbname*
specifies the name under which the principal database is stored;
by default the database is that listed in :ref:`kdc.conf(5)`. The
- KADM5 policy database and lock file are also derived from this
+ password policy database and lock files are also derived from this
value.
**-k** *mkeytype*
@@ -61,22 +60,27 @@
the default is 1. Note that 0 is not allowed.
**-M** *mkeyname*
- principal name for the master key in the database; the default is
- that given in :ref:`kdc.conf(5)`.
+ principal name for the master key in the database. If not
+ specified, the name is determined by the **master_key_name**
+ variable in :ref:`kdc.conf(5)`.
**-m**
specifies that the master database password should be read from
- the TTY rather than fetched from a file on disk.
+ the keyboard rather than fetched from a file on disk.
**-sf** *stash_file*
- specifies the stash file of the master database password.
+ specifies the stash filename of the master database password. If
+ not specified, the filename is determined by the
+ **key_stash_file** variable in :ref:`kdc.conf(5)`.
**-P** *password*
- specifies the master database password. This option is not
- recommended.
+ specifies the master database password. Using this option may
+ expose the password to other users on the system via the process
+ list.
.. _kdb5_util_options_end:
+
COMMANDS
--------
@@ -147,7 +151,7 @@
releases prior to 1.2.2.
**-ov**
- causes the dump to be in *ovsec_adm_export* format.
+ causes the dump to be in "ovsec_adm_export" format.
**-r13**
causes the dump to be in the Kerberos 5 1.3 format ("kdb5_util
@@ -187,7 +191,7 @@
.. _kdb5_util_load:
**load** [**-old**\|\ **-b6**\|\ **-b7**\|\ **-ov**\|\ **-r13**]
- [**-hash**] [**-verbose**] [**-update**] *filename* *dbname*
+ [**-hash**] [**-verbose**] [**-update**] *filename* [*dbname*]
Loads a database dump from the named file into the named database.
Unless the **-old** or **-b6** option is given, the format of the dump
@@ -210,7 +214,7 @@
("kdb5_util load_dump version 4").
**-ov**
- requires the database to be in ovsec_adm_import format. Must be
+ requires the database to be in "ovsec_adm_import" format. Must be
used with the **-update** option.
**-hash**
@@ -232,7 +236,7 @@
what is in the dump file and the old one destroyed upon successful
completion.
-*dbname* is required and overrides the value specified on the command
+If specified, *dbname* overrides the value specified on the command
line or the default.
.. _kdb5_util_load_end:
@@ -240,65 +244,74 @@
ark
~~~
- **ark**
+ **ark** [**-e** *enc*:*salt*,...] *principal*
-Adds a random key.
+Adds new random keys to *principal* at the next available key version
+number. Keys for the current highest key version number will be
+preserved. The **-e** option specifies the list of encryption and
+salt types to be used for the new keys.
add_mkey
~~~~~~~~
**add_mkey** [**-e** *etype*] [**-s**]
-Adds a new master key to the ``K/M`` (master key) principal. Existing
-master keys will remain. The **-e** *etype* option allows
-specification of the enctype of the new master key. The **-s** option
-stashes the new master key in a local stash file which will be created
-if it doesn't already exist.
+Adds a new master key to the master key principal, but does not mark
+it as active. Existing master keys will remain. The **-e** option
+specifies of the encryption type of the new master key. The **-s**
+option stashes the new master key in the stash file, which will be
+created if it doesn't already exist.
+After a new master key is added, it should be propagated to slave
+servers via a manual or periodic invocation of :ref:`kprop(8)`. Then,
+the stash files on the slave servers should be updated with the
+kdb5_util **stash** command. Once those steps are complete, the key
+is ready to be marked active with the kdb5_util **use_mkey** command.
+
use_mkey
~~~~~~~~
**use_mkey** *mkeyVNO* [*time*]
Sets the activation time of the master key specified by *mkeyVNO*.
-Once a master key is active (i.e. its activation time has been
-reached) it will then be used to encrypt principal keys either when
-the principal keys change, are newly created or when the
-**update_princ_encryption** command is run. If the time argument is
-provided then that will be the activation time otherwise the current
-time is used by default. The format of the optional time argument is
-that specified in the *Time Formats* section of the :ref:`kadmin(1)`
-man page.
+Once a master key becomes active, it will be used to encrypt newly
+created principal keys. If no *time* argument is given, the current
+time is used, causing the specified master key version to become
+active immediately. The format of *time* is specified in the
+:ref:`date_format` section of the :ref:`kadmin(1)` man page.
+After a new master key becomes active, the kdb5_util
+**update_princ_encryption** command can be used to update all
+principal keys to be encrypted in the new master key.
+
list_mkeys
~~~~~~~~~~
**list_mkeys**
-List all master keys from most recent to earliest in ``K/M``
-principal. The output will show the kvno, enctype and salt for each
-mkey similar to :ref:`kadmin(1)` **getprinc** output. A ``*``
-following an mkey denotes the currently active master key.
+List all master keys, from most recent to earliest, in the master key
+principal. The output will show the kvno, enctype, and salt type for
+each mkey, similar to the output of :ref:`kadmin(1)` **getprinc**. A
+``*`` following an mkey denotes the currently active master key.
purge_mkeys
~~~~~~~~~~~
**purge_mkeys** [**-f**] [**-n**] [**-v**]
-Delete master keys from the ``K/M`` principal that are not used to
+Delete master keys from the master key principal that are not used to
protect any principals. This command can be used to remove old master
-keys from a ``K/M`` principal once all principal keys are protected by
-a newer master key.
+keys all principal keys are protected by a newer master key.
**-f**
- does not prompt user.
+ does not prompt for confirmation.
**-n**
- do a dry run, shows master keys that would be purged, does not
- actually purge any keys.
+ performs a dry run, showing master keys that would be purged, but
+ not actually purging any keys.
**-v**
- verbose output.
+ gives more verbose output.
update_princ_encryption
~~~~~~~~~~~~~~~~~~~~~~~
@@ -312,13 +325,11 @@
versions, and give a count at the end of the number of principals
updated. If the **-f** option is not given, ask for confirmation
before starting to make changes. The **-v** option causes each
-principal processed (each one matching the pattern) to be listed, and
-an indication given as to whether it needed updating or not. The
-**-n** option causes the actions not to be taken, only the normal or
-verbose status messages displayed; this implies **-f** since no
-database changes will be performed and thus there's little reason to
-seek confirmation.
+principal processed to be listed, with an indication as to whether it
+needed updating or not. The **-n** option performs a dry run, only
+showing the actions which would have been taken.
+
SEE ALSO
--------
Modified: trunk/doc/rst_source/krb_admins/admin_commands/kprop.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kprop.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kprop.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -18,12 +18,12 @@
DESCRIPTION
-----------
-kprop is used to propagate a Kerberos V5 database dump file from the
-master Kerberos server to a slave Kerberos server, which is specified
-by *slave_host*. This is done by transmitting the dumped database
-file to the slave server over an encrypted, secure channel. The dump
-file must be created by :ref:`kdb5_util(8)`.
+kprop is used to securely propagate a Kerberos V5 database dump file
+from the master Kerberos server to a slave Kerberos server, which is
+specified by *slave_host*. The dump file must be created by
+:ref:`kdb5_util(8)`.
+
OPTIONS
-------
Modified: trunk/doc/rst_source/krb_admins/admin_commands/kpropd.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kpropd.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kpropd.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -20,14 +20,15 @@
-----------
The *kpropd* command runs on the slave KDC server. It listens for
-update requests made by the :ref:`kprop(8)` program, and periodically
-requests incremental updates from the master KDC.
+update requests made by the :ref:`kprop(8)` program. If incremental
+propagation is enabled, it periodically requests incremental updates
+from the master KDC.
When the slave receives a kprop request from the master, kpropd
accepts the dumped KDC database and places it in a file, and then runs
:ref:`kdb5_util(8)` to load the dumped database into the active
-database which is used by :ref:`krb5kdc(8)`. Thus, the master
-Kerberos server can use :ref:`kprop(8)` to propagate its database to
+database which is used by :ref:`krb5kdc(8)`. This allows the master
+Kerberos server to use :ref:`kprop(8)` to propagate its database to
the slave servers. Upon a successful download of the KDC database
file, the slave Kerberos server will have an up-to-date KDC database.
@@ -36,22 +37,23 @@
::
- kprop stream tcp nowait root /usr/local/sbin/kpropd kpropd
+ kprop stream tcp nowait root /usr/local/sbin/kpropd kpropd
-However, kpropd can also run as a standalone daemon, if the **-S**
-option is turned on. This is done for debugging purposes, or if for
-some reason the system administrator just doesn't want to run it out
-of inetd(8).
+kpropd can also run as a standalone daemon by specifying the **-S**
+option. This is done for debugging purposes, or if for some reason
+the system administrator just doesn't want to run it out of inetd(8).
-When the slave periodically requests incremental updates, kpropd
-updates its principal.ulog file with any updates from the master.
-:ref:`kproplog(8)` can be used to view a summary of the update entry
-log on the slave KDC. Incremental propagation is not enabled by
-default; it can be enabled using the **iprop_enable** and
-**iprop_slave_poll** settings in :ref:`kdc.conf(5)`. The principal
-``kiprop/slavehostname at REALM`` (where *slavehostname* is the name of
-the slave KDC host, and *REALM* is the name of the Kerberos realm)
-must be present in the slave's keytab file.
+Incremental propagation may be enabled with the **iprop_enable**
+variable in :ref:`kdc.conf(5)`. If incremental propagation is
+enabled, the slave periodically polls the master KDC for updates, at
+an interval determined by the **iprop_slave_poll** variable. If the
+slave receives updates, kpropd updates its principal.ulog file with
+any updates from the master. :ref:`kproplog(8)` can be used to view a
+summary of the update entry log on the slave KDC. If incremental
+propagation is enabled, the principal ``kiprop/slavehostname at REALM``
+(where *slavehostname* is the name of the slave KDC host, and *REALM*
+is the name of the Kerberos realm) must be present in the slave's
+keytab file.
OPTIONS
@@ -62,19 +64,20 @@
**-f** *file*
Specifies the filename where the dumped principal database file is
- to be stored; by default the dumped database file
+ to be stored; by default the dumped database file is
``/usr/local/var/krb5kdc/from_master``.
**-p**
- Allows the user to specify the pathname to the :ref:`kdb5_util(8)` program;
- by default the pathname used is /usr/local/sbin/kdb5_util.
+ Allows the user to specify the pathname to the :ref:`kdb5_util(8)`
+ program; by default the pathname used is
+ ``/usr/local/sbin/kdb5_util``.
**-S**
Turn on standalone mode. Normally, kpropd is invoked out of
inetd(8) so it expects a network connection to be passed to it
from inetd(8). If the **-S** option is specified, kpropd will put
- itself into the background, and wait for connections to the
- ``krb5_prop`` port specified in ``/etc/services``.
+ itself into the background, and wait for connections on port 754
+ (or the port specified with the **-P** option if given).
**-d**
Turn on debug mode. In this mode, if the **-S** option is
@@ -84,12 +87,13 @@
**-P**
Allow for an alternate port number for kpropd to listen on. This
- is only useful if the program is run in standalone mode.
+ is only useful in combination with the **-S** option.
**-a** *acl_file*
Allows the user to specify the path to the kpropd.acl file; by
default the path used is ``/usr/local/var/krb5kdc/kpropd.acl``.
+
ENVIRONMENT
-----------
@@ -98,6 +102,7 @@
* **KRB5_CONFIG**
* **KRB5_KDC_PROFILE**
+
FILES
-----
@@ -107,6 +112,7 @@
containing the principal of a host from which the local machine
will allow Kerberos database propagation via :ref:`kprop(8)`.
+
SEE ALSO
--------
Modified: trunk/doc/rst_source/krb_admins/admin_commands/kproplog.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kproplog.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kproplog.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -8,29 +8,30 @@
**kproplog** [**-h**] [**-e** *num*] [-v]
+
DESCRIPTION
-----------
-The kproplog command displays the contents of the Kerberos principal
-update log to standard output. It can be used to keep track of the
-incremental updates to the principal database, when enabled. The
-update log file contains the update log maintained by the
-:ref:`kadmind(8)` process on the master KDC server and the kpropd
-process on the slave KDC servers. When updates occur, they are logged
-to this file. Subsequently any KDC slave configured for incremental
-updates will request the current data from the master KDC and update
-their principal.ulog file with any updates returned.
+The kproplog command displays the contents of the KDC database update
+log to standard output. It can be used to keep track of incremental
+updates to the principal database. The update log file contains the
+update log maintained by the :ref:`kadmind(8)` process on the master
+KDC server and the :ref:`kpropd(8)` process on the slave KDC servers.
+When updates occur, they are logged to this file. Subsequently any
+KDC slave configured for incremental updates will request the current
+data from the master KDC and update their principal.ulog file with any
+updates returned.
-The kproplog command can only be run on a KDC server by someone with
-privileges comparable to the superuser. It will display update
-entries for that server only.
+The kproplog command requires read access to the update log file. It
+will display update entries only for the KDC it runs on.
-If no options are specified, the summary of the update log is
-displayed. If invoked on the master, all of the update entries are
-also displayed. When invoked on a slave KDC server, only a summary of
-the updates are displayed, which includes the serial number of the
+If no options are specified, kproplog displays a summary of the update
+log. If invoked on the master, kproplog also displays all of the
+update entries. If invoked on a slave KDC server, kproplog displays
+only a summary of the updates, which includes the serial number of the
last update received and the associated time stamp of the last update.
+
OPTIONS
-------
@@ -65,6 +66,7 @@
Modification time
TL data
+
ENVIRONMENT
-----------
@@ -72,6 +74,7 @@
* **KRB5_KDC_PROFILE**
+
SEE ALSO
--------
Modified: trunk/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -29,28 +29,6 @@
OPTIONS
-------
-The **-x** *db_args* option specifies the database specific arguments.
-Options supported for LDAP database are:
-
- **-x** nconns=<number_of_connections>
- Specifies the number of connections to be maintained per
- LDAP server.
-
- **-x** host=<ldapuri>
- Specifies the LDAP server to connect to by a LDAP URI.
-
- **-x** binddn=<binddn>
- Specifies the DN of the object used by the KDC server to bind
- to the LDAP server. This object should have the rights to
- read the realm container, principal container and the subtree
- that is referenced by the realm.
-
- **-x** bindpwd=<bind_password>
- Specifies the password for the above mentioned binddn. It is
- recommended not to use this option. Instead, the password can
- be stashed using the **stashsrvpw** command of
- :ref:`kdb5_ldap_util(8)`
-
The **-r** *realm* option specifies the realm for which the server
should provide service.
@@ -62,28 +40,28 @@
to be entered manually as a password when **-m** is given; the default
is ``des-cbc-crc``.
-The **-M** *mkeyname* option specifies the principal name for the master key
-in the database (usually ``K/M`` in the KDC's realm).
+The **-M** *mkeyname* option specifies the principal name for the
+master key in the database (usually ``K/M`` in the KDC's realm).
The **-m** option specifies that the master database password should
-be fetched from the keyboard rather than from a file on disk.
+be fetched from the keyboard rather than from a stash file.
The **-n** option specifies that the KDC does not put itself in the
background and does not disassociate itself from the terminal. In
normal operation, you should always allow the KDC to place itself in
the background.
-The **-P** *pid_file* option tells the KDC to write its PID (followed
-by a newline) into *pid_file* after it starts up. This can be used to
-identify whether the KDC is still running and to allow init scripts to
-stop the correct process.
+The **-P** *pid_file* option tells the KDC to write its PID into
+*pid_file* after it starts up. This can be used to identify whether
+the KDC is still running and to allow init scripts to stop the correct
+process.
-The **-p** *portnum* option specifies the default UDP port number
-which the KDC should listen on for Kerberos version 5 requests. This
-value is used when no port is specified in the KDC profile and when no
-port is specified in the Kerberos configuration file. If no value is
-available, then the value in ``/etc/services`` for service
-``kerberos`` is used.
+The **-p** *portnum* option specifies the default UDP port numbers
+which the KDC should listen on for Kerberos version 5 requests, as a
+comma-separated list. This value overrides the UDP port numbers
+specified in the :ref:`kdcdefaults` section of :ref:`kdc.conf(5)`, but
+may be overridden by realm-specific values. If no value is given from
+any source, the default ports are 88 and 750.
The **-w** *numworkers* option tells the KDC to fork *numworkers*
processes to listen to the KDC ports and process requests in parallel.
@@ -98,7 +76,30 @@
for UDP packets on network interfaces created after the KDC
starts.
+The **-x** *db_args* option specifies database-specific arguments.
+Options supported for the LDAP database module are:
+ **-x** nconns=<number_of_connections>
+ Specifies the number of connections to be maintained per
+ LDAP server.
+
+ **-x** host=<ldapuri>
+ Specifies the LDAP server to connect to by URI.
+
+ **-x** binddn=<binddn>
+ Specifies the DN of the object used by the KDC server to bind
+ to the LDAP server. This object should have read and write
+ privileges to the realm container, the principal container,
+ and the subtree that is referenced by the realm.
+
+ **-x** bindpwd=<bind_password>
+ Specifies the password for the above mentioned binddn. Using
+ this option may expose the password to other users on the
+ system via the process list; to avoid this, instead stash the
+ password using the **stashsrvpw** command of
+ :ref:`kdb5_ldap_util(8)`.
+
+
EXAMPLE
-------
@@ -108,6 +109,7 @@
it and are superseded by subsequent definitions of the same option.
For example:
+
::
krb5kdc -p 2001 -r REALM1 -p 2002 -r REALM2 -r REALM3
@@ -116,9 +118,9 @@
for REALM2 and REALM3. Additionally, per-realm parameters may be
specified in the :ref:`kdc.conf(5)` file. The location of this file
may be specified by the **KRB5_KDC_PROFILE** environment variable.
-Parameters specified in this file take precedence over options
-specified on the command line. See the :ref:`kdc.conf(5)` description
-for further details.
+Per-realm parameters specified in this file take precedence over
+options specified on the command line. See the :ref:`kdc.conf(5)`
+description for further details.
ENVIRONMENT
Modified: trunk/doc/rst_source/krb_admins/admin_commands/ktutil.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/ktutil.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/ktutil.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -12,9 +12,9 @@
DESCRIPTION
-----------
-The ktutil command invokes a subshell from which an administrator can
-read, write, or edit entries in a Kerberos V5 keytab or V4 srvtab
-file.
+The ktutil command invokes a command interface from which an
+administrator can read, write, or edit entries in a keytab or Kerberos
+V4 srvtab file.
COMMANDS
@@ -117,13 +117,16 @@
::
- ktutil: add_entry -password -p alice at BLEEP.COM -k 1 -e aes128-cts-hmac-sha1-96
+ ktutil: add_entry -password -p alice at BLEEP.COM -k 1 -e
+ aes128-cts-hmac-sha1-96
Password for alice at BLEEP.COM:
- ktutil: add_entry -password -p alice at BLEEP.COM -k 1 -e aes256-cts-hmac-sha1-96
+ ktutil: add_entry -password -p alice at BLEEP.COM -k 1 -e
+ aes256-cts-hmac-sha1-96
Password for alice at BLEEP.COM:
ktutil: write_kt keytab
ktutil:
+
SEE ALSO
--------
Modified: trunk/doc/rst_source/krb_admins/admin_commands/sserver.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/sserver.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/admin_commands/sserver.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -34,7 +34,7 @@
::
- sample stream tcp nowait root /usr/local/sbin/sserver sserver
+ sample stream tcp nowait root /usr/local/sbin/sserver sserver
Since ``sample`` is normally not a port defined in ``/etc/services``,
you will usually have to add a line to ``/etc/services`` which looks
@@ -53,6 +53,7 @@
files.
When you run sclient you should see something like this:
+
::
sendauth succeeded, reply is:
@@ -64,14 +65,17 @@
---------------------
1) kinit returns the error:
+
::
- kinit: Client not found in Kerberos database while getting initial credentials
+ kinit: Client not found in Kerberos database while getting
+ initial credentials
This means that you didn't create an entry for your username in the
Kerberos database.
2) sclient returns the error:
+
::
unknown service sample/tcp; check /etc/services
@@ -80,6 +84,7 @@
sample tcp port.
3) sclient returns the error:
+
::
connect: Connection refused
@@ -88,9 +93,11 @@
you didn't restart inetd after editing inetd.conf.
4) sclient returns the error:
+
::
- sclient: Server not found in Kerberos database while using sendauth
+ sclient: Server not found in Kerberos database while using
+ sendauth
This means that the ``sample/hostname at LOCAL.REALM`` service was not
defined in the Kerberos database; it should be created using
@@ -98,10 +105,11 @@
the key for that service principal available for sclient.
5) sclient returns the error:
+
::
sendauth rejected, error reply is:
- " No such file or directory"
+ "No such file or directory"
This probably means sserver couldn't find the keytab file. It was
probably not installed in the proper directory.
Modified: trunk/doc/rst_source/krb_admins/database.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database.rst 2012-03-15 04:55:41 UTC (rev 25769)
+++ trunk/doc/rst_source/krb_admins/database.rst 2012-03-15 22:52:45 UTC (rev 25770)
@@ -66,7 +66,7 @@
-----------
.. include:: admin_commands/kadmin_local.rst
- :start-after: _date_format:
+ :start-after: _date_format_start:
:end-before: _date_format_end:
.. note:: If the date specification contains spaces, you must enclose
More information about the cvs-krb5
mailing list