-MIT Kerberos Documentation.
-===================================
+MIT Kerberos Documentation
+==========================
Contents
-=========
+--------
.. toctree::
:maxdepth: 1
Feedback
-========
+--------
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___main
-
-..
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___main
Version
-=======
+-------
.. _reference:
Administration programs
-============================
-
-.. note:: This document was copied from Kerberos man pages. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+========================
+.. note:: This document was copied from Kerberos man pages. Currently
+ it is under review. Please, send your feedback, corrections
+ and additions to krb5-bugs@mit.edu. Your contribution is
+ greatly appreciated.
.. toctree::
:maxdepth: 1
ktutil.rst
k5srvutil.rst
kadmind.rst
- kdb5_ldap_util.rst
+ kdb5_ldap_util.rst
sserver.rst
-------------
-
-Feedback:
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___admin_commands
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___admin_commands
.. _k5srvutil(1):
k5srvutil
-=============================================================
+=========
SYNOPSIS
-----------
+--------
-**k5srvutil** *operation* [ **-i** ] [ **-f** *filename* ]
+**k5srvutil** *operation*
+[**-i**]
+[**-f** *filename*]
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 a system manager to list or change keys currently in
+his keytab or to add new keys to the keytab.
-Operation must be one of the following:
+*operation* must be one of the following:
- **list**
- Lists the keys in a keytab showing version number and principal name.
+**list**
+ Lists the keys in a keytab showing version number and principal
+ 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 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.
+**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
+ 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.
- **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.
+**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.
- **delete**
- Deletes particular keys in the keytab, interactively prompting for each key.
+**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 file used is /etc/krb5.keytab file unless this is overridden by the **-f** option.
-
-
-*k5srvutil* uses the kadmin program to edit the keytab in place.
-However, old keys are retained, so they are available in case of failure.
+k5srvutil uses the kadmin program to edit the keytab in place.
+However, old keys are retained, so they are available in case of
+failure.
SEE ALSO
--------------
+--------
kadmin(8), ktutil(8)
-
-
.. _kadmin.local(1):
kadmin, kadmin.local
-===========================
-
+====================
SYNOPSIS
---------------
+--------
.. _kadmin_synopsys:
-
-**kadmin**
- [ **-O** | **-N** ]
- [**-r** *realm*]
- [**-p** *principal*]
- [**-q** *query*]
- [[**-c** *cache_name*] | [**-k** [**-t** *keytab* ]] | **-n**]
- [**-w** *password*]
- [**-s** *admin_server* [:*port*]]
+**kadmin**
+[**-O**\|\ **-N**]
+[**-r** *realm*]
+[**-p** *principal*]
+[**-q** *query*]
+[[**-c** *cache_name*]\|[**-k** [**-t** *keytab*]]\|\ **-n**]
+[**-w** *password*]
+[**-s** *admin_server*\ [:*port*]]
**kadmin.local**
- [**-r** *realm*]
- [**-p** *principal*]
- [**-q** *query*]
- [**-d** *dbname*]
- [**-e** "enc:salt ..."]
- [**-m**]
- [**-x** *db_args*]
-
+[**-r** *realm*]
+[**-p** *principal*]
+[**-q** *query*]
+[**-d** *dbname*]
+[**-e** *enc*:*salt* ...]
+[**-m**]
+[**-x** *db_args*]
.. _kadmin_synopsys_end:
-
+
+
DESCRIPTION
-------------
-
-*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).
-
-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 *-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,
+-----------
+
+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).
+
+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
+**-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.
-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.
+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.
-If the database is LDAP, *kadmin.local* need not be run on the KDC.
+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` file with the *iprop_enable* option.
-See the :ref:`kdc.conf` documentation for other options for tuning incremental propagation parameters.
+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` file with the **iprop_enable** option. See the
+:ref:`kdc.conf` documentation for other options for tuning incremental
+propagation parameters.
OPTIONS
-------------
+-------
.. _kadmin_options:
- **-r** *realm*
- Use *realm* as the default database realm.
-
- **-p** *principal*
- Use *principal* to authenticate. Otherwise, *kadmin* will append "/admin" to the primary principal name of the default ccache, the
- value of the *USER* environment variable, or the username as obtained with *getpwuid*, in order of preference.
-
- **-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 **-t** option, then the default *keytab* will be used.
-
- **-t** *keytab*
- Use *keytab* to decrypt the KDC response. This can only be used with the **-k** option.
-
- **-n**
- Requests anonymous processing. Two types of anonymous principals are supported.
- For fully anonymous Kerberos, configure pkinit on the KDC and configure *pkinit_anchors* in the client's :ref:`krb5.conf`.
- Then use the *-n* option with a principal of the form *@REALM* (an empty principal name followed by the at-sign and a realm name).
- If permitted by the KDC, an anonymous ticket will be returned.
- A second form of anonymous tickets is supported; these realm-exposed tickets hide the identity of the client but not the client's realm.
- For this mode, use *kinit -n* with a normal principal name.
- If supported by the KDC, the principal (but not realm) will be replaced by the anonymous principal.
- As of release 1.8, the MIT Kerberos KDC only supports fully anonymous operation.
-
- **-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 :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.
-
- .. 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.
-
- **-d** *dbname*
- Specifies the name of the Kerberos database. This option does not apply to the LDAP database.
-
- **-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.
-
- **-e** enc:salt_list
- Sets the list of encryption types and salt types to be used for any new keys created.
-
- **-O**
- Force use of old AUTH_GSSAPI authentication flavor.
-
- **-N**
- Prevent fallback to AUTH_GSSAPI authentication flavor.
-
- **-x** *db_args*
- Specifies the database specific arguments.
-
- Options supported for LDAP database are:
-
- **-x** host=<hostname>
- specifies the LDAP server to connect to by a LDAP URI.
-
- **-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.
-
- **-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)`
-
+**-r** *realm*
+ Use *realm* as the default database realm.
+
+**-p** *principal*
+ Use *principal* to authenticate. Otherwise, kadmin will append
+ ``/admin`` to the primary principal name of the default ccache,
+ the value of the **USER** environment variable, or the username as
+ obtained with getpwuid, in order of preference.
+
+**-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
+ **-t** option, then the default keytab will be used.
+
+**-t** *keytab*
+ Use *keytab* to decrypt the KDC response. This can only be used
+ with the **-k** option.
+
+**-n**
+ Requests anonymous processing. Two types of anonymous principals
+ are supported. For fully anonymous Kerberos, configure pkinit on
+ the KDC and configure **pkinit_anchors** in the client's
+ :ref:`krb5.conf`. Then use the **-n** option with a principal of
+ the form ``@REALM`` (an empty principal name followed by the
+ at-sign and a realm name). If permitted by the KDC, an anonymous
+ ticket will be returned. A second form of anonymous tickets is
+ supported; these realm-exposed tickets hide the identity of the
+ client but not the client's realm. For this mode, use ``kinit
+ -n`` with a normal principal name. If supported by the KDC, the
+ principal (but not realm) will be replaced by the anonymous
+ principal. As of release 1.8, the MIT Kerberos KDC only supports
+ fully anonymous operation.
+
+**-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
+ :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.
+
+ .. 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.
+
+**-d** *dbname*
+ Specifies the name of the Kerberos database. This option does not
+ apply to the LDAP database.
+
+**-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.
+
+**-e** "*enc*:*salt* ..."
+ Sets the list of encryption types and salt types to be used for
+ any new keys created.
+
+**-O**
+ Force use of old AUTH_GSSAPI authentication flavor.
+
+**-N**
+ Prevent fallback to AUTH_GSSAPI authentication flavor.
+
+**-x** *db_args*
+ Specifies the database specific arguments. Options supported for
+ LDAP database are:
+
+ **-x host=**\ *hostname*
+ specifies the LDAP server to connect to by a LDAP URI.
+
+ **-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.
+
+ **-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)`
.. _kadmin_options_end:
DATE FORMAT
---------------
+-----------
.. _date_format:
-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::
-
- 1 month ago
- 2 hours ago
- 400000 seconds ago
- last year
- this Monday
- next Monday
- yesterday
- tomorrow
- now
- second Monday
- fortnight ago
- 3/31/92 10:00:07 PST
- January 23, 1987 10:05pm
- 22:00 GMT
-
-Dates which do not have the "ago" specifier default to being absolute dates, unless they appear in a field where a duration is expected.
-In that case the time specifier will be interpreted as relative.
+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::
+
+ 1 month ago
+ 2 hours ago
+ 400000 seconds ago
+ last year
+ this Monday
+ next Monday
+ yesterday
+ tomorrow
+ now
+ second Monday
+ fortnight ago
+ 3/31/92 10:00:07 PST
+ January 23, 1987 10:05pm
+ 22:00 GMT
+
+Dates which do not have the "ago" specifier default to being absolute
+dates, unless they appear in a field where a duration is expected. In
+that case the time specifier will be interpreted as relative.
Specifying "ago" in a duration may result in unexpected behavior.
-
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.
+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
========================== ============================================
.. _date_format_end:
-
COMMANDS
------------
+--------
-Note that the privileges are based on the kadm5.acl file on the master KDC.
+Note that the privileges are based on the kadm5.acl file on the master
+KDC.
.. _add_principal:
add_principal
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- **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.
-
- .. note:: This command requires the *add* privilege.
-
- Aliases::
-
- addprinc ank
-
- The options are:
-
- **-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
-
- **-pwexpire** *pwexpdate*
- password expiration date
-
- **-maxlife** *maxlife*
- maximum ticket life for the principal
-
- **-maxrenewlife** *maxrenewlife*
- maximum renewable life of tickets for the principal
-
- **-kvno** *kvno*
- explicitly set the 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.
-
- **-clearpolicy**
- *-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.
-
- {- | +} **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.
-
- {- | +} **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.
-
- {- | +} **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.
-
- **-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.
-
- **-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.
-
- EXAMPLE::
-
- kadmin: addprinc jennifer
- WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU";
- defaulting to no policy.
- Enter password for principal jennifer@ATHENA.MIT.EDU: <= Type the password.
- Re-enter password for principal jennifer@ATHENA.MIT.EDU: <=Type it again.
- Principal "jennifer@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** [*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.
+
+.. note:: This command requires the **add** privilege.
+
+Aliases: **addprinc**, **ank**
+
+The options are:
+
+**-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
+
+**-pwexpire** *pwexpdate*
+ password expiration date
+
+**-maxlife** *maxlife*
+ maximum ticket life for the principal
+
+**-maxrenewlife** *maxrenewlife*
+ maximum renewable life of tickets for the principal
+
+**-kvno** *kvno*
+ explicitly set the 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.
+
+**-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.
+
+{-\|+}\ **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.
+
+{-\|+}\ **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.
+
+{-\|+}\ **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.
+
+**-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.
+
+**-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.
+
+Example::
+
+ kadmin: addprinc jennifer
+ WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU";
+ defaulting to no policy.
+ Enter password for principal jennifer@ATHENA.MIT.EDU: <= Type the password.
+ Re-enter password for principal jennifer@ATHENA.MIT.EDU: <=Type it again.
+ Principal "jennifer@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:
modify_principal
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~
- **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.
+ **modify_principal** [*options*] *principal*
- .. note:: This command requires the *modify* privilege.
+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.
- Alias::
+.. note:: This command requires the *modify* privilege.
- modprinc
+Alias: **modprinc**
- The options are:
+The options are:
- **-x** *db_princ_args*
- Denotes the database specific options.
+**-x** *db_princ_args*
+ Denotes the database specific options. The options for LDAP
+ database are:
- The options for LDAP database are:
+ **-x tktpolicy=**\ *policy*
+ Associates a ticket policy to the Kerberos principal.
- **-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.
- **-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.
- **-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::
- 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)
+ 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:
rename_principal
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- **rename_principal** [ *-force* ] *old_principal* *new_principal*
- Renames the specified *old_principal* to *new_principal*.
- This command prompts for confirmation, unless the *-force* option is given.
+~~~~~~~~~~~~~~~~
- .. note:: This command requires the *add* and *delete* privileges.
+ **rename_principal** [**-force**] *old_principal* *new_principal*
- Alias::
+Renames the specified *old_principal* to *new_principal*. This
+command prompts for confirmation, unless the **-force** option is
+given.
- renprinc
+.. note:: This command requires the **add** and **delete** privileges.
- ERRORS::
+Alias: **renprinc**
- KADM5_AUTH_ADD (requires "add" privilege)
- KADM5_AUTH_DELETE (requires "delete" privilege)
- KADM5_UNK_PRINC (principal does not exist)
- KADM5_DUP (principal exists already)
+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:
delete_principal
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~
- **delete_principal** [ *-force* ] *principal*
- Deletes the specified *principal* from the database. This command prompts for deletion, unless the *-force* option is given.
+ **delete_principal** [**-force**] *principal*
- .. note:: This command requires the *delete* privilege.
+Deletes the specified *principal* from the database. This command
+prompts for deletion, unless the **-force** option is given.
- Alias::
+.. note:: This command requires the **delete** privilege.
- delprinc
+Alias: **delprinc**
- ERRORS::
+Errors::
- KADM5_AUTH_DELETE (requires "delete" privilege)
- KADM5_UNK_PRINC (principal does not exist)
+ KADM5_AUTH_DELETE (requires "delete" privilege)
+ KADM5_UNK_PRINC (principal does not exist)
.. _delete_principal_end:
.. _change_password:
change_password
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- **change_password** [options] *principal*
- 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.
+ **change_password** [*options*] *principal*
- Alias::
+Changes the password of *principal*. Prompts for a new password if
+neither **-randkey** or **-pw** is specified.
- cpw
+.. note:: Requires the **changepw** privilege, or that the principal
+ that is running the program to be the same as the one
+ changed.
- The following options are available:
+Alias: **cpw**
- **-randkey**
- Sets the key of the principal to a random value
+The following options are available:
- **-pw** *password*
- Set the password to the specified string. Not recommended.
+**-randkey**
+ Sets the key of the principal to a random value
- **-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.
+**-pw** *password*
+ Set the password to the specified string. Not recommended.
- **-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.
+**-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.
- EXAMPLE::
+**-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.
- kadmin: cpw systest
- Enter password for principal systest@BLEEP.COM:
- Re-enter password for principal systest@BLEEP.COM:
- Password for systest@BLEEP.COM changed.
- kadmin:
+Example::
- ERRORS::
+ kadmin: cpw systest
+ Enter password for principal systest@BLEEP.COM:
+ Re-enter password for principal systest@BLEEP.COM:
+ Password for systest@BLEEP.COM changed.
+ kadmin:
- 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)
+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:
purgekeys
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~
+
+ **purgekeys** [**-keepkvno** *oldest_kvno_to_keep*] *principal*
- **purgekeys** [*-keepkvno oldest_kvno_to_keep* ] *principal*
- Purges previously retained old keys (e.g., from *change_password -keepold*) from *principal*.
- If **-keepkvno** is specified, then only purges keys with kvnos lower than *oldest_kvno_to_keep*.
+Purges previously retained old keys (e.g., from **change_password
+-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.
+.. note:: This command requires the **modify** privilege.
.. _purgekeys_end:
.. _get_principal:
get_principal
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
- **get_principal** [*-terse*] *principal*
- 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.
+ **get_principal** [**-terse**] *principal*
- Alias::
+Gets the attributes of principal. With the **-terse** option, outputs
+fields as quoted tab-separated strings.
- getprinc
+.. note:: Requires the **inquire** privilege, or that the principal
+ that is running the the program to be the same as the one
+ being listed.
+Alias: **getprinc**
- EXAMPLES::
+Examples::
- kadmin: getprinc tlyu/admin
- Principal: tlyu/admin@BLEEP.COM
- Expiration date: [never]
- Last password change: Mon Aug 12 14:16:47 EDT 1996
- Password expiration date: [none]
- Maximum ticket life: 0 days 10:00:00
- Maximum renewable life: 7 days 00:00:00
- Last modified: Mon Aug 12 14:16:47 EDT 1996 (bjaspan/admin@BLEEP.COM)
- Last successful authentication: [never]
- Last failed authentication: [never]
- Failed password attempts: 0
- Number of keys: 2
- Key: vno 1, DES cbc mode with CRC-32, no salt
- Key: vno 1, DES cbc mode with CRC-32, Version 4
- Attributes:
- Policy: [none]
+ kadmin: getprinc tlyu/admin
+ Principal: tlyu/admin@BLEEP.COM
+ Expiration date: [never]
+ Last password change: Mon Aug 12 14:16:47 EDT 1996
+ Password expiration date: [none]
+ Maximum ticket life: 0 days 10:00:00
+ Maximum renewable life: 7 days 00:00:00
+ Last modified: Mon Aug 12 14:16:47 EDT 1996 (bjaspan/admin@BLEEP.COM)
+ Last successful authentication: [never]
+ Last failed authentication: [never]
+ Failed password attempts: 0
+ Number of keys: 2
+ Key: vno 1, DES cbc mode with CRC-32, no salt
+ Key: vno 1, DES cbc mode with CRC-32, Version 4
+ Attributes:
+ Policy: [none]
+ kadmin: getprinc -terse systest
+ systest@BLEEP.COM 3 86400 604800 1
+ 785926535 753241234 785900000
+ tlyu/admin@BLEEP.COM 786100034 0 0
+ kadmin:
- kadmin: getprinc -terse systest
- systest@BLEEP.COM 3 86400 604800 1
- 785926535 753241234 785900000
- tlyu/admin@BLEEP.COM 786100034 0 0
- kadmin:
+Errors::
-
- ERRORS::
-
- KADM5_AUTH_GET (requires the get (inquire) privilege)
- KADM5_UNK_PRINC (principal does not exist)
+ KADM5_AUTH_GET (requires the get (inquire) privilege)
+ KADM5_UNK_PRINC (principal does not exist)
.. _get_principal_end:
.. _list_principals:
list_principals
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- **list_principals** [expression]
- Retrieves all or some principal names.
- Expression is a shell-style glob expression that can contain the wild-card characters ?, \*, and []'s.
- All principal names matching the expression are printed.
- If no expression is provided, all principal names are printed.
- If the expression does not contain an "@" character, an "@" character followed by the local realm is appended to the expression.
-
- .. note:: Requires the *list* privilege.
-
- Aliases::
-
- listprincs get_principals get_princs
-
- EXAMPLE::
-
- kadmin: listprincs test*
- test3@SECURE-TEST.OV.COM
- test2@SECURE-TEST.OV.COM
- test1@SECURE-TEST.OV.COM
- testuser@SECURE-TEST.OV.COM
- kadmin:
+~~~~~~~~~~~~~~~
+
+ **list_principals** [*expression*]
+
+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
+printed. If the expression does not contain an ``@`` character, an
+``@`` character followed by the local realm is appended to the
+expression.
+
+.. note:: Requires the **list** privilege.
+
+Alias: **listprincs**, **get_principals**, **get_princs**
+
+Example::
+
+ kadmin: listprincs test*
+ test3@SECURE-TEST.OV.COM
+ test2@SECURE-TEST.OV.COM
+ test1@SECURE-TEST.OV.COM
+ testuser@SECURE-TEST.OV.COM
+ kadmin:
.. _list_principals_end:
.. _get_strings:
get_strings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~
- **get_strings** *principal*
- Displays string attributes on *principal*.
- String attributes are used to supply per-principal configuration to some KDC plugin modules.
+ **get_strings** *principal*
- .. note:: Requires the *inquire* privilege.
+Displays string attributes on *principal*. String attributes are used
+to supply per-principal configuration to some KDC plugin modules.
- Alias::
+.. note:: Requires the **inquire** privilege.
- getstr
+Alias: **getstr**
.. _get_strings_end:
.. _set_string:
set_string
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~
- **set_string** *principal* *key* *value*
- Sets a string attribute on *principal*.
+ **set_string** *principal* *key* *value*
- .. note:: This command requires the *modify* privilege.
+Sets a string attribute on *principal*.
- Alias::
+.. note:: This command requires the **modify** privilege.
- setstr
+Alias: **setstr**
.. _set_string_end:
.. _del_string:
del_string
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~
- **del_string** *principal* *key*
- Deletes a string attribute from *principal*.
+ **del_string** *principal* *key*
- .. note:: This command requires the *delete* privilege.
+Deletes a string attribute from *principal*.
- Alias::
+.. note:: This command requires the **delete** privilege.
- delstr
+Alias: **delstr**
.. _del_string_end:
.. _add_policy:
add_policy
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- **add_policy** [options] *policy*
- Adds the named *policy* to the policy database.
+~~~~~~~~~~
- .. note:: Requires the *add* privilege.
+ **add_policy** [*options*] *policy*
- Alias::
+Adds the named *policy* to the policy database.
- addpol
+.. note:: Requires the **add** privilege.
- The following options are available:
+Alias: **addpol**
- **-maxlife** *time*
- sets the maximum lifetime of a password
+The following options are available:
- **-minlife** *time*
- sets the minimum lifetime of a password
+**-maxlife** *time*
+ sets the maximum lifetime of a password
- **-minlength** *length*
- sets the minimum length of a password
+**-minlife** *time*
+ sets the minimum lifetime of a password
- **-minclasses** *number*
- sets the minimum number of character classes allowed in a password
+**-minlength** *length*
+ sets the minimum length of a password
- **-history** *number*
- sets the number of past keys kept for a principal. This option is not supported for LDAP database
+**-minclasses** *number*
+ sets the minimum number of character classes allowed in a password
- **-maxfailure** *maxnumber*
- sets the maximum number of authentication failures before the principal is locked.
- Authentication failures are only tracked for principals which require preauthentication.
+**-history** *number*
+ sets the number of past keys kept for a principal. This option is
+ not supported for LDAP database
- **-failurecountinterval** *failuretime*
- sets the allowable time between authentication failures.
- If an authentication failure happens after *failuretime* has elapsed since the previous failure,
- the number of authentication failures is reset to 1.
+**-maxfailure** *maxnumber*
+ sets the maximum number of authentication failures before the
+ principal is locked. Authentication failures are only tracked for
+ principals which require preauthentication.
- **-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.
+**-failurecountinterval** *failuretime*
+ sets the allowable time between authentication failures. If an
+ authentication failure happens after *failuretime* has elapsed
+ since the previous failure, the number of authentication failures
+ is reset to 1.
+**-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.
- EXAMPLE::
+Example::
- kadmin: add_policy -maxlife "2 days" -minlength 5 guests
- kadmin:
+ kadmin: add_policy -maxlife "2 days" -minlength 5 guests
+ kadmin:
- ERRORS::
+Errors::
- KADM5_AUTH_ADD (requires the add privilege)
- KADM5_DUP (policy already exists)
+ KADM5_AUTH_ADD (requires the add privilege)
+ KADM5_DUP (policy already exists)
.. _add_policy_end:
.. _modify_policy:
modify_policy
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
- **modify_policy** [options] *policy*
- Modifies the named *policy*. Options are as above for *add_policy*.
+ **modify_policy** [*options*] *policy*
- .. note:: Requires the *modify* privilege.
+Modifies the named *policy*. Options are as above for *add_policy*.
- Alias::
+.. note:: Requires the **modify** privilege.
- modpol
+Alias: **modpol**
+Errors::
- ERRORS::
-
- KADM5_AUTH_MODIFY (requires the modify privilege)
- KADM5_UNK_POLICY (policy does not exist)
+ KADM5_AUTH_MODIFY (requires the modify privilege)
+ KADM5_UNK_POLICY (policy does not exist)
.. _modify_policy_end:
.. _delete_policy:
delete_policy
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- **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.
+~~~~~~~~~~~~~
- .. note:: Requires the *delete* privilege.
+ **delete_policy** [**-force**] *policy*
- Alias::
+Deletes the named *policy*. Prompts for confirmation before deletion.
+The command will fail if the policy is in use by any principals.
- delpol
+.. note:: Requires the **delete** privilege.
+Alias: **delpol**
- EXAMPLE::
+Example::
- kadmin: del_policy guests
- Are you sure you want to delete the policy "guests"?
- (yes/no): yes
- kadmin:
+ kadmin: del_policy guests
+ Are you sure you want to delete the policy "guests"?
+ (yes/no): yes
+ kadmin:
- ERRORS::
+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)
+ 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:
get_policy
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- **get_policy** [ **-terse** ] *policy*
- Displays the values of the named *policy*.
- With the **-terse** flag, outputs the fields as quoted strings separated by tabs.
+~~~~~~~~~~
- .. note:: Requires the *inquire* privilege.
+ **get_policy** [ **-terse** ] *policy*
- Alias::
+Displays the values of the named *policy*. With the **-terse** flag,
+outputs the fields as quoted strings separated by tabs.
- getpol
+.. note:: Requires the **inquire** privilege.
+Alias: getpol
- EXAMPLES::
+Examples::
- kadmin: get_policy admin
- Policy: admin
- Maximum password life: 180 days 00:00:00
- Minimum password life: 00:00:00
- Minimum password length: 6
- Minimum number of password character classes: 2
- Number of old keys kept: 5
- Reference count: 17
+ kadmin: get_policy admin
+ Policy: admin
+ Maximum password life: 180 days 00:00:00
+ Minimum password life: 00:00:00
+ Minimum password length: 6
+ Minimum number of password character classes: 2
+ Number of old keys kept: 5
+ Reference count: 17
- kadmin: get_policy -terse admin
- admin 15552000 0 6 2 5 17
- kadmin:
+ kadmin: get_policy -terse admin
+ admin 15552000 0 6 2 5 17
+ kadmin:
- The *Reference count* is the number of principals using that policy.
+The "Reference count" is the number of principals using that policy.
- ERRORS::
+Errors::
- KADM5_AUTH_GET (requires the get privilege)
- KADM5_UNK_POLICY (policy does not exist)
+ KADM5_AUTH_GET (requires the get privilege)
+ KADM5_UNK_POLICY (policy does not exist)
.. _get_policy_end:
.. _list_policies:
list_policies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
- **list_policies** [expression]
- Retrieves all or some policy names. Expression is a shell-style glob expression that can contain the wild-card characters ?, \*, and []'s.
- All policy names matching the expression are printed.
- If no expression is provided, all existing policy names are printed.
+ **list_policies** [*expression*]
- .. note:: Requires the *list* privilege.
+Retrieves all or some policy names. *expression* is a shell-style
+glob expression that can contain the wild-card characters ``?``,
+``*``, and ``[]'`. All policy names matching the expression are
+printed. If no expression is provided, all existing policy names are
+printed.
- Alias::
+.. note:: Requires the **list** privilege.
- listpols, get_policies, getpols.
+Aliases: **listpols**, **get_policies**, **getpols**.
+Examples::
- EXAMPLES::
+ kadmin: listpols
+ test-pol
+ dict-only
+ once-a-min
+ test-pol-nopw
- kadmin: listpols
- test-pol
- dict-only
- once-a-min
- test-pol-nopw
-
- kadmin: listpols t*
- test-pol
- test-pol-nopw
- kadmin:
+ kadmin: listpols t*
+ test-pol
+ test-pol-nopw
+ kadmin:
.. _list_policies_end:
get_privs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~
- **get_privs**
- Returns the Kerberos administrative privileges of the principal
- that is currently running kadmin.
+ **get_privs**
- Alias::
+Returns the Kerberos administrative privileges of the principal that
+is currently running kadmin.
- getprivs
+Alias: **getprivs**
- EXAMPLE::
+Example::
- kadmin: get_privs
- Principal joe/admin@ATHENA.MIT.EDU
- current privileges: GET, ADD, MODIFY, DELETE
- kadmin:
+ kadmin: get_privs
+ Principal joe/admin@ATHENA.MIT.EDU
+ current privileges: GET, ADD, MODIFY, DELETE
+ kadmin:
.. _ktadd:
ktadd
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- **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.
-
- .. note:: Requires the *inquire* and *changepw* privileges.
-
- If you use the *-glob* option, it also requires the *list* administrative privilege.
-
- The options are:
-
- **-k[eytab]** *keytab*
- Use *keytab* as the keytab file. Otherwise, *ktadd* will use the default keytab file (*/etc/krb5.keytab*).
-
- **-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` will be used.
- See :ref:`Supported_Encryption_Types_and_Salts` for all possible values.
-
- **-q**
- Run in quiet mode. This causes *ktadd* to 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.
-
-
- 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@ATHENA.MIT.EDU with
- kvno 3, encryption type DES-CBC-CRC added to keytab
- WRFILE:/tmp/foo-new-keytab
- kadmin:
+~~~~~
+
+ **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.
+
+.. note:: Requires the **inquire** and **changepw** privileges. If
+ you use the **-glob** option, it also requires the **list**
+ administrative privilege.
+
+The options are:
+
+**-k[eytab]** *keytab*
+ Use *keytab* as the keytab file. Otherwise, ktadd will use the
+ default keytab file (``/etc/krb5.keytab``).
+
+**-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` will be used. See
+ :ref:`Supported_Encryption_Types_and_Salts` for all possible
+ values.
+
+**-q**
+ Run in quiet mode. This causes *ktadd* to 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.
+
+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@ATHENA.MIT.EDU with
+ kvno 3, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/tmp/foo-new-keytab
+ kadmin:
.. _ktadd_end:
.. _ktremove:
ktremove
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~
- **ktremove** *principal* [*kvno* | *all* | *old*]
- Removes entries for the specified *principal* from a keytab. Requires no permissions, since this does not require database access.
+ **ktremove** *principal* [*kvno*\|\ *all*\| *old*]
+Removes entries for the specified *principal* from a keytab. Requires
+no permissions, since this does not require database access.
- If the string "all" is specified, all entries for that principal are removed;
- if the string "old" is specified, all entries for that principal except those with the highest kvno are removed.
- Otherwise, the value specified is parsed as an integer, and all entries whose *kvno* match that integer are removed.
+If the string "all" is specified, all entries for that principal are
+removed; if the string "old" is specified, all entries for that
+principal except those with the highest kvno are removed. Otherwise,
+the value specified is parsed as an integer, and all entries whose
+*kvno* match that integer are removed.
- The options are:
+The options are:
- **-k[eytab]** *keytab*
- Use keytab as the keytab file. Otherwise, *ktremove* will use the default keytab file (*/etc/krb5.keytab*).
+**-k[eytab]** *keytab*
+ Use keytab as the keytab file. Otherwise, ktremove will use the
+ default keytab file (``/etc/krb5.keytab``).
- **-q**
- Run in quiet mode. This causes *ktremove* to display less verbose information.
+**-q**
+ Run in quiet mode. This causes ktremove to display less verbose
+ information.
- EXAMPLE::
+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:
+ 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_end:
-
lock
-~~~~~~~
+~~~~
- Lock database exclusively. Use with extreme caution!
+Lock database exclusively. Use with extreme caution!
unlock
-~~~~~~~~
-
- Release the exclusive database lock.
+~~~~~~
+Release the exclusive database lock.
list_requests
-~~~~~~~~~~~~~~~
-
- Lists available for kadmin requests.
- This is a generic, unrelated to Kerberos command.
+~~~~~~~~~~~~~
- Alias::
+Lists available for kadmin requests. This is a generic, unrelated to
+Kerberos command.
- lr, "?".
+Aliases: **lr**, **?**
quit
-~~~~~~
-
- Exit program. If the database was locked, the lock is released.
+~~~~
- Alias::
+Exit program. If the database was locked, the lock is released.
- exit, q
+Aliases: **exit**, **q**
FILES
------------
+-----
-.. note:: The first three files are specific to db2 database.
+.. note:: The first three files are specific to db2 database.
====================== =================================================
principal.db default name for Kerberos principal database
====================== =================================================
-
HISTORY
--------------
+-------
-The *kadmin* program was originally written by Tom Yu at MIT, as an interface to the OpenVision Kerberos administration program.
+The kadmin program was originally written by Tom Yu at MIT, as an
+interface to the OpenVision Kerberos administration program.
SEE ALSO
-------------
+--------
kerberos(1), kpasswd(1), kadmind(8)
-
-
.. _kadmind(8):
kadmind
-==========
+=======
SYNOPSIS
------------
-
-**kadmind** [**-x** *db_args*] [**-r** *realm*] [**-m**] [**-nofork**] [**-port** *port-number*] [**-P** *pid_file*]
+--------
+
+**kadmind**
+[**-x** *db_args*]
+[**-r** *realm*]
+[**-m**]
+[**-nofork**]
+[**-port** *port-number*]
+[**-P** *pid_file*]
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 kpasswd(1) command, both of which are clients of *kadmind*.
-
-*kadmind* requires a number of configuration files to be set up in order for it to work:
-
-:ref:`kdc.conf`
- 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.
-
-*keytab*
- Kadmind requires a keytab containing correct entries for the kadmin/admin and kadmin/changepw principals for every realm that
- *kadmind* will answer requests for. The keytab can be created with the kadmin(8) client.
- The location of the keytab is determined by the *admin_keytab* configuration variable (see CONFIGURATION VALUES).
-
-*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.
-
- If the *kadmind*'s 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 disassociates itself from its controlling terminal.
-
-*kadmind* can be configured 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` file
-with the *iprop_enable* option. See the :ref:`kdc.conf` documentation for other options for tuning incremental propagation parameters.
-Incremental propagation requires the principal "kiprop/MASTER\@REALM"
-(where MASTER is the master KDC's canonical host name, and REALM the realm name) to be registered in the database.
+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 kpasswd(1) command, both of
+which are clients of kadmind.
+
+kadmind requires a number of configuration files to be set up in order
+for it to work:
+
+:ref:`kdc.conf`
+ 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.
+
+keytab
+ kadmind requires a keytab containing correct entries for the
+ kadmin/admin and kadmin/changepw principals for every realm that
+ kadmind will answer requests for. The keytab can be created with
+ the kadmin(8) client. The location of the keytab is determined by
+ the **admin_keytab** configuration variable (see CONFIGURATION
+ VALUES).
+
+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.
+
+ If the kadmind's 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
+disassociates itself from its controlling terminal.
+
+kadmind can be configured 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`
+file with the **iprop_enable** option. See the :ref:`kdc.conf`
+documentation for other options for tuning incremental propagation
+parameters. Incremental propagation requires the principal
+``kiprop/MASTER\@REALM`` (where MASTER is the master KDC's canonical
+host name, and REALM the realm name) to be registered in the database.
OPTIONS
------------
-
- **-x** *db_args*
- specifies the database specific arguments.
-
- Options supported for LDAP database are:
+-------
+
+**-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.
+
+**-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.
+
+**-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.
+
+**-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).
+
+**-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
+ whether kadmind is still running and to allow init scripts to stop
+ the correct process.
- **-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.
-
- **-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.
-
- **-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.
-
- **-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).
-
- **-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
- whether *kadmind* is still running and to allow init scripts to stop the correct process.
CONFIGURATION VALUES
----------------------------
-
-In addition to the relations defined in kdc.conf(5), *kadmind* understands the following relations,
-all of which should appear in the [realms] section:
-
- **acl_file**
- The path of *kadmind*'s *ACL* file. **Mandatory**. No default.
-
- **admin_keytab**
- The name of the keytab containing entries for the principals kadmin/admin and kadmin/changepw in each realm that *kadmind* will
- serve. The default is the value of the KRB5_KTNAME environment variable, if defined. **Mandatory**.
-
- **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.
-
- **kadmind_port**
- The TCP port on which *kadmind* will listen. The default is 749.
-
-*ACL* FILE SYNTAX
--------------------
-
-The *ACL* file controls which principals can or cannot perform which administrative functions. For operations that affect principals,
-the *ACL* file also controls which principals can operate on which other principals. 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*]
-
-Ordering is important. The first matching entry is the one which will control access for a particular principal on a particular principal.
-
- **principal**
- may specify a partially or fully qualified Kerberos version 5 principal name. Each component of the name may be wildcarded
- using the asterisk ( * ) character.
-
- **operation-target**
- [Optional] may specify a partially or fully qualified Kerberos version 5 principal name. Each component of the name may be
- wildcarded using the asterisk ( \* ) character.
-
- **operation-mask**
- Specifies what operations may or may not be performed by a principal matching a particular entry. This is a string of one or
- more of the following list of characters or their upper-case counterparts. If the character is upper-case, then the operation
- is disallowed. If the character is lower-case, then the operation is permitted.
-
- ::
-
- a [Dis]allows the addition of principals or policies 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@realm adm*
- A standard fully qualified name.
- The *operation-mask* only applies to this principal and specifies that [s]he may add,
- delete or modify principals and policies, but not change anybody else's password.
-
- *user/instance@realm cim service/instance@realm*
- A standard fully qualified name and a standard fully qualified target.
- The *operation-mask* only applies to this principal operating on this target and specifies
- that [s]he may change the target's password, request information about the target and modify it.
-
- *user/\*@realm ac*
- A wildcarded name. The *operation-mask* applies to all principals in realm "realm" whose first component is "user" and specifies
- that [s]he may add principals and change anybody's password.
-
- *user/\*@realm i \*/instance@realm*
- A wildcarded name and target. The *operation-mask* applies to all principals in realm "realm" whose first component is "user" and
- specifies that [s]he may perform inquiries on principals whose second component is "instance" and realm is "realm".
+--------------------
+
+In addition to the relations defined in kdc.conf(5), kadmind
+understands the following relations, all of which should appear in the
+[realms] section:
+
+**acl_file**
+ The path of kadmind's ACL file. **Mandatory**. No default.
+
+**admin_keytab**
+ The name of the keytab containing entries for the principals
+ kadmin/admin and kadmin/changepw in each realm that kadmind will
+ serve. The default is the value of the KRB5_KTNAME environment
+ variable, if defined. **Mandatory**.
+
+**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.
+
+**kadmind_port**
+ The TCP port on which kadmind will listen. The default is 749.
+
+
+ACL FILE SYNTAX
+---------------
+
+The ACL file controls which principals can or cannot perform which
+administrative functions. For operations that affect principals, the
+ACL file also controls which principals can operate on which other
+principals. 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*]
+
+Ordering is important. The first matching entry is the one which will
+control access for a particular principal on a particular principal.
+
+**principal**
+ may specify a partially or fully qualified Kerberos version 5
+ principal name. Each component of the name may be wildcarded
+ using the ``*`` character.
+
+**operation-target**
+
+ [Optional] may specify a partially or fully qualified Kerberos
+ version 5 principal name. Each component of the name may be
+ wildcarded using the ``*`` character.
+
+**operation-mask**
+ Specifies what operations may or may not be performed by a
+ principal matching a particular entry. This is a string of one or
+ more of the following list of characters or their upper-case
+ counterparts. If the character is upper-case, then the operation
+ is disallowed. If the character is lower-case, then the operation
+ is permitted.
+
+ ::
+
+ a [Dis]allows the addition of principals or policies 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@realm adm``
+ A standard fully qualified name. The *operation-mask* only
+ applies to this principal and specifies that [s]he may add,
+ delete or modify principals and policies, but not change
+ anybody else's password.
+
+ ``user/instance@realm cim service/instance@realm``
+ A standard fully qualified name and a standard fully qualified
+ target. The *operation-mask* only applies to this principal
+ operating on this target and specifies that [s]he may change
+ the target's password, request information about the target
+ and modify it.
+
+ ``user/*@realm ac``
+ A wildcarded name. The *operation-mask* applies to all
+ principals in realm ``realm`` whose first component is
+ ``user`` and specifies that [s]he may add principals and
+ change anybody's password.
+
+ ``user/*@realm i */instance@realm``
+ A wildcarded name and target. The *operation-mask* applies to
+ all principals in realm ``realm`` whose first component is
+ ``user`` and specifies that [s]he may perform inquiries on
+ principals whose second component is ``instance`` and realm is
+ ``realm``.
FILES
------------
+-----
Note: The first three files are specific to db2 database.
kadm5.dict file containing dictionary of strings explicitly disallowed as passwords.
==================== ===================================================================
-SEE ALSO
------------
-
-kpasswd(1), kadmin(8), kdb5_util(8), kadm5_export(8), kadm5_import(8), kdb5_ldap_util(8)
+SEE ALSO
+--------
+kpasswd(1), kadmin(8), kdb5_util(8), kadm5_export(8), kadm5_import(8),
+kdb5_ldap_util(8)
.. _kdb5_ldap_util(8):
-kdb5_ldap_util
-==================================================
+kdb5_ldap_util
+===============
SYNOPSIS
------------------------
+--------
.. _kdb5_ldap_util_synopsis:
-
-**kdb5_ldap_util** [**-D** *user_dn* [**-w** *passwd*]] [**-H** *ldapuri*] **command** [*command_options*]
+
+**kdb5_ldap_util**
+[**-D** *user_dn* [**-w** *passwd*]]
+[**-H** *ldapuri*]
+**command**
+[*command_options*]
.. _kdb5_ldap_util_synopsis_end:
DESCRIPTION
------------------------
-
-*kdb5_ldap_util* allows an administrator to manage realms, Kerberos services and ticket policies.
+-----------
+
+kdb5_ldap_util allows an administrator to manage realms, Kerberos
+services and ticket policies.
COMMAND-LINE OPTIONS
------------------------
-
+--------------------
+
.. _kdb5_ldap_util_options:
**-D** *user_dn*
- Specifies the Distinguished Name (DN) of the user who has sufficient rights to perform the operation on the LDAP server.
+ Specifies the Distinguished Name (DN) of the user who has
+ sufficient rights to perform the operation on the LDAP server.
**-w** *passwd*
- Specifies the password of *user_dn*. This option is not recommended.
+ Specifies the password of *user_dn*. This option is not
+ recommended.
**-H** *ldapuri*
- Specifies the URI of the LDAP server. It is recommended to use *ldapi://* or *ldaps://* to connect to the LDAP server.
+ Specifies the URI of the LDAP server. It is recommended to use
+ ``ldapi://`` or ``ldaps://`` to connect to the LDAP server.
.. _kdb5_ldap_util_options_end:
COMMANDS
------------------------
-
+--------
+
create
-~~~~~~~~~~~~~~~~~~~
+~~~~~~
.. _kdb5_ldap_util_create:
- **create**
- [**-subtrees** *subtree_dn_list*]
- [**-sscope** *search_scope*]
- [**-containerref** *container_reference_dn*]
- [**-k** *mkeytype*]
- [**-kv** *mkeyVNO*]
- [**-m|-P** *password*|**-sf** *stashfilename*]
- [**-s**]
- [**-r** *realm*]
- [**-kdcdn** *kdc_service_list*]
- [**-admindn** *admin_service_list*]
- [**-maxtktlife** *max_ticket_life*]
- [**-maxrenewlife** *max_renewable_ticket_life*]
- [*ticket_flags*]
-
- Creates realm in directory. 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(\:).
-
- **-sscope** *search_scope*
- Specifies the scope for searching the principals under the subtree.
- The possible values are 1 or one (one level), 2 or sub (subtrees).
-
- **-containerref** *container_reference_dn*
- Specifies the DN of the container object in which the principals of a realm will be created.
- If the container reference is not configured for a realm, the principals will be created in the realm container.
-
- **-k** *mkeytype*
- Specifies the key type of the master key in the database; the default is that given in kdc.conf.
-
- **-kv** *mkeyVNO*
- Specifies the version number of the master key in the database; the default is 1. Note that 0 is not allowed.
-
- **-m**
- Specifies that the master database password should be read from the TTY rather than fetched from a file on the disk.
-
- **-P** *password*
- Specifies the master database password. This option is not recommended.
-
- **-r** *realm*
- Specifies the Kerberos realm of the database.
-
- **-sf** *stashfilename*
- Specifies the stash file of the master database password.
-
- **-s**
- Specifies that the stash file is to be created.
-
- **-maxtktlife** *max_ticket_life*
- Specifies maximum ticket life for principals in this realm.
-
- **-maxrenewlife** *max_renewable_ticket_life*
- Specifies maximum renewable life of tickets for principals in this 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.
-
- The various flags are:
-
- {-\|+}allow_postdated
- *-allow_postdated* prohibits principals from obtaining postdated tickets.
- (Sets the KRB5_KDB_DISALLOW_POSTDATED flag.) *+allow_postdated* clears this flag.
-
- {-\|+}allow_forwardable
- *-allow_forwardable* prohibits principals from obtaining forwardable tickets.
- (Sets the KRB5_KDB_DISALLOW_FORWARDABLE flag.)
- *+allow_forwardable* clears this flag.
-
- {-\|+}allow_renewable
- *-allow_renewable* prohibits principals from obtaining renewable tickets.
- (Sets the KRB5_KDB_DISALLOW_RENEWABLE flag.)
- *+allow_renewable* clears this flag.
-
- {-\|+}allow_proxiable
- *-allow_proxiable* prohibits principals 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 principals by prohibiting principals
- from obtaining a session key for another user.
- (Sets the KRB5_KDB_DISALLOW_DUP_SKEY flag.)
- *+allow_dup_skey* 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.
-
- {-\|+}requires_preauth
- *+requires_preauth* requires principals 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 principals 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 principals. (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 principals 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 principals in the database.
-
- {-\|+}allow_tix
- *-allow_tix* forbids the issuance of any tickets for principals. *+allow_tix* clears this flag.
- The default is *+allow_tix*.
- In effect, *-allow_tix* sets the KRB5_KDB_DISALLOW_ALL_TIX flag on principals 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 principals in the database.
-
- {-\|+}password_changing_service
- *+password_changing_service* sets a flag in the attributes field marking principal 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 principals in the database.
-
- Command options specific to eDirectory
+ **create**
+ [**-subtrees** *subtree_dn_list*]
+ [**-sscope** *search_scope*]
+ [**-containerref** *container_reference_dn*]
+ [**-k** *mkeytype*]
+ [**-kv** *mkeyVNO*]
+ [**-m|-P** *password*\|\ **-sf** *stashfilename*]
+ [**-s**]
+ [**-r** *realm*]
+ [**-kdcdn** *kdc_service_list*]
+ [**-admindn** *admin_service_list*]
+ [**-maxtktlife** *max_ticket_life*]
+ [**-maxrenewlife** *max_renewable_ticket_life*]
+ [*ticket_flags*]
+
+Creates realm in directory. 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 (``:``).
+
+**-sscope** *search_scope*
+ Specifies the scope for searching the principals under the
+ subtree. The possible values are 1 or one (one level), 2 or sub
+ (subtrees).
+
+**-containerref** *container_reference_dn*
+ Specifies the DN of the container object in which the principals
+ of a realm will be created. If the container reference is not
+ configured for a realm, the principals will be created in the
+ realm container.
+
+**-k** *mkeytype*
+ Specifies the key type of the master key in the database; the
+ default is that given in kdc.conf.
+
+**-kv** *mkeyVNO*
+ Specifies the version number of the master key in the database;
+ the default is 1. Note that 0 is not allowed.
+
+**-m**
+ Specifies that the master database password should be read from
+ the TTY rather than fetched from a file on the disk.
+
+**-P** *password*
+ Specifies the master database password. This option is not
+ recommended.
+
+**-r** *realm*
+ Specifies the Kerberos realm of the database.
+
+**-sf** *stashfilename*
+ Specifies the stash file of the master database password.
+
+**-s**
+ Specifies that the stash file is to be created.
+
+**-maxtktlife** *max_ticket_life*
+ Specifies maximum ticket life for principals in this realm.
+
+**-maxrenewlife** *max_renewable_ticket_life*
+ Specifies maximum renewable life of tickets for principals in this
+ 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.
+
+ 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.
+
+Command options specific to eDirectory:
.. _kdb5_ldap_util_create_edir:
- **-kdcdn** *kdc_service_list*
- Specifies the list of KDC service objects serving the realm.
- The list contains the DNs of the KDC service objects separated by colon(\:).
+**-kdcdn** *kdc_service_list*
+ Specifies the list of KDC service objects serving the realm. The
+ list contains the DNs of the KDC service objects separated by
+ colon (``:``).
- **-admindn** *admin_service_list*
- Specifies the list of Administration service objects serving the realm.
- The list contains the DNs of the Administration service objects separated by colon(\:).
+**-admindn** *admin_service_list*
+ Specifies the list of Administration service objects serving the
+ realm. The list contains the DNs of the Administration service
+ objects separated by colon (``:``).
.. _kdb5_ldap_util_create_edir_end:
-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
- Password for "cn=admin,o=org":
- Initializing database for realm 'ATHENA.MIT.EDU'
- You will be prompted for the database Master Password.
- It is important that you NOT FORGET this password.
- Enter KDC database master key:
- Re-enter KDC database master key to verify:
+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
+ Password for "cn=admin,o=org":
+ Initializing database for realm 'ATHENA.MIT.EDU'
+ You will be prompted for the database Master Password.
+ It is important that you NOT FORGET this password.
+ Enter KDC database master key:
+ Re-enter KDC database master key to verify:
.. _kdb5_ldap_util_create_end:
modify
-~~~~~~~~~~~~~~~~~~~
+~~~~~~
.. _kdb5_ldap_util_modify:
-
- **modify**
- [**-subtrees** *subtree_dn_list*]
- [**-sscope** *search_scope*]
- [**-containerref** *container_reference_dn*]
- [**-r** *realm*]
- [**-kdcdn** *kdc_service_list* | [**-clearkdcdn** *kdc_service_list*] [**-addkdcdn** *kdc_service_list*]]
- [**-admindn** *admin_service_list* | [**-clearadmindn** *admin_service_list*] [**-addadmindn** *admin_service_list*]]
- [**-maxtktlife** *max_ticket_life*]
- [**-maxrenewlife** *max_renewable_ticket_life*]
- [*ticket_flags*]
-
- 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.
-
- **-sscope** *search_scope*
- Specifies the scope for searching the principals under the subtrees.
- The possible values are 1 or one (one level), 2 or sub (subtrees).
-
- **-containerref** *container_reference_dn*
- Specifies the DN of the container object in which the principals of a realm will be created.
-
- **-r** *realm*
- Specifies the Kerberos realm of the database.
-
- **-maxtktlife** *max_ticket_life*
- Specifies maximum ticket life for principals in this realm.
-
- **-maxrenewlife** *max_renewable_ticket_life*
- Specifies maximum renewable life of tickets for principals in this 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.
-
- The various flags are:
-
- {-\|+}allow_postdated
- *-allow_postdated* prohibits principals from obtaining postdated tickets. (Sets the KRB5_KDB_DISALLOW_POSTDATED flag.)
- *+allow_postdated* clears this flag.
-
- {-\|+}allow_forwardable
- *-allow_forwardable* prohibits principals from obtaining forwardable tickets.
- (Sets the KRB5_KDB_DISALLOW_FORWARDABLE flag.)
- *+allow_forwardable* clears this flag.
-
- {-\|+}allow_renewable
- *-allow_renewable* prohibits principals from obtaining renewable tickets. (Sets the KRB5_KDB_DISALLOW_RENEWABLE flag.)
- *+allow_renewable* clears this flag.
-
- {-\|+}allow_proxiable
- *-allow_proxiable* prohibits principals 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 principals by prohibiting principals 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 principals 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 principals 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 principals. (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 principals 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 principals in the database.
-
- {-\|+}allow_tix
- *-allow_tix* forbids the issuance of any tickets for principals.
- *+allow_tix* clears this flag. The default is *+allow_tix*.
- In effect, *-allow_tix* sets the KRB5_KDB_DISALLOW_ALL_TIX flag on principals 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 principals in the database.
-
- {-\|+}password_changing_service
- *+password_changing_service* sets a flag in the attributes field marking principal 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 principals in the database.
-
- Command options specific to eDirectory
+ **modify**
+ [**-subtrees** *subtree_dn_list*]
+ [**-sscope** *search_scope*]
+ [**-containerref** *container_reference_dn*]
+ [**-r** *realm*]
+ [**-kdcdn** *kdc_service_list* | [**-clearkdcdn** *kdc_service_list*] [**-addkdcdn** *kdc_service_list*]]
+ [**-admindn** *admin_service_list* | [**-clearadmindn** *admin_service_list*] [**-addadmindn** *admin_service_list*]]
+ [**-maxtktlife** *max_ticket_life*]
+ [**-maxrenewlife** *max_renewable_ticket_life*]
+ [*ticket_flags*]
+
+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.
+
+**-sscope** *search_scope*
+ Specifies the scope for searching the principals under the
+ subtrees. The possible values are 1 or one (one level), 2 or sub
+ (subtrees).
+
+**-containerref** *container_reference_dn* Specifies the DN of the
+ container object in which the principals of a realm will be
+ created.
+
+**-r** *realm*
+ Specifies the Kerberos realm of the database.
+
+**-maxtktlife** *max_ticket_life*
+ Specifies maximum ticket life for principals in this realm.
+
+**-maxrenewlife** *max_renewable_ticket_life*
+ Specifies maximum renewable life of tickets for principals in this
+ 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.
+
+ 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.
+
+Command options specific to eDirectory:
.. _kdb5_ldap_util_modify_edir:
- **-kdcdn** *kdc_service_list*
- Specifies the list of KDC service objects serving the realm.
- The list contains the DNs of the KDC service objects separated by a colon (\:).
- This list replaces the existing list.
-
- **-clearkdcdn** *kdc_service_list*
- Specifies the list of KDC service objects that need to be removed from the existing list.
- The list contains the DNs of the KDC service objects separated by a colon (\:).
-
- **-addkdcdn** *kdc_service_list*
- Specifies the list of KDC service objects that need to be added to the existing list.
- The list contains the DNs of the KDC service objects separated by a colon (\:).
-
- **-admindn** *admin_service_list*
- Specifies the list of Administration service objects serving the realm.
- The list contains the DNs of the Administration service objects separated by a colon (\:).
- This list replaces the existing list.
-
- **-clearadmindn** *admin_service_list*
- Specifies the list of Administration service objects that need to be removed from the existing list.
- The list contains the DNs of the Administration service objects separated by a colon (\:).
-
- **-addadmindn** *admin_service_list*
- Specifies the list of Administration service objects that need to be added to the existing list.
- The list contains the DNs of the Administration service objects separated by a colon (:).
+**-kdcdn** *kdc_service_list*
+ Specifies the list of KDC service objects serving the realm. The
+ list contains the DNs of the KDC service objects separated by a
+ colon (``:``). This list replaces the existing list.
+
+**-clearkdcdn** *kdc_service_list*
+ Specifies the list of KDC service objects that need to be removed
+ from the existing list. The list contains the DNs of the KDC
+ service objects separated by a colon (``:``).
+
+**-addkdcdn** *kdc_service_list*
+ Specifies the list of KDC service objects that need to be added to
+ the existing list. The list contains the DNs of the KDC service
+ objects separated by a colon (``:``).
+
+**-admindn** *admin_service_list*
+ Specifies the list of Administration service objects serving the
+ realm. The list contains the DNs of the Administration service
+ objects separated by a colon (``:``). This list replaces the
+ existing list.
+
+**-clearadmindn** *admin_service_list*
+ Specifies the list of Administration service objects that need to
+ be removed from the existing list. The list contains the DNs of
+ the Administration service objects separated by a colon (``:``).
+
+**-addadmindn** *admin_service_list*
+ Specifies the list of Administration service objects that need to
+ be added to the existing list. The list contains the DNs of the
+ Administration service objects separated by a colon (``:``).
.. _kdb5_ldap_util_modify_edir_end:
-EXAMPLE::
+Example::
- 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%
+ 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%
.. _kdb5_ldap_util_modify_end:
view
-~~~~~~~~~~~~~~~~~~~
+~~~~
.. _kdb5_ldap_util_view:
- **view** [**-r** *realm*]
- Displays the attributes of a realm. Options:
+ **view** [**-r** *realm*]
+
+Displays the attributes of a realm. Options:
- **-r** *realm*
- Specifies the Kerberos realm of the database.
+**-r** *realm*
+ Specifies the Kerberos realm of the database.
EXAMPLE::
- 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
- Subtree: ou=servers,o=org
- SearchScope: ONE
- Maximum ticket life: 0 days 01:00:00
- Maximum renewable life: 0 days 10:00:00
- Ticket flags: DISALLOW_FORWARDABLE REQUIRES_PWCHANGE
+ 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
+ Subtree: ou=servers,o=org
+ SearchScope: ONE
+ Maximum ticket life: 0 days 01:00:00
+ Maximum renewable life: 0 days 10:00:00
+ Ticket flags: DISALLOW_FORWARDABLE REQUIRES_PWCHANGE
.. _kdb5_ldap_util_view_end:
destroy
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~
.. _kdb5_ldap_util_destroy:
- **destroy** [**-f**] [**-r** *realm*]
- Destroys an existing realm. Options:
+ **destroy** [**-f**] [**-r** *realm*]
- **-f**
- If specified, will not prompt the user for confirmation.
+Destroys an existing realm. Options:
- **-r** *realm*
- Specifies the Kerberos realm of the database.
+**-f**
+ If specified, will not prompt the user for confirmation.
+
+**-r** *realm*
+ Specifies the Kerberos realm of the database.
EXAMPLE::
- 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
- OK, deleting database of 'ATHENA.MIT.EDU'...
- shell%
+ 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
+ OK, deleting database of 'ATHENA.MIT.EDU'...
+ shell%
.. _kdb5_ldap_util_destroy_end:
list
-~~~~~~~~~~~~~~~~~~~
+~~~~
.. _kdb5_ldap_util_list:
- **list**
- Lists the name of realms.
+ **list**
+
+Lists the name of realms.
EXAMPLE::
- 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
- MEDIA-LAB.MIT.EDU
- shell%
+ 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
+ MEDIA-LAB.MIT.EDU
+ shell%
.. _kdb5_ldap_util_list_end:
-
stashsrvpw
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~
.. _kdb5_ldap_util_stashsrvpw:
- **stashsrvpw** [**-f** *filename*] *servicedn*
- Allows an administrator to store the password for service object in a file so that KDC and Administration server
- can use it to authenticate to the LDAP server. Options:
+ **stashsrvpw**
+ [**-f** *filename*]
+ *servicedn*
+
+Allows an administrator to store the password for service object in a
+file so that KDC and Administration server can use it to authenticate
+to the LDAP server. Options:
- **-f** *filename*
- Specifies the complete path of the service password file. By default, */usr/local/var/service_passwd* is used.
+**-f** *filename*
+ Specifies the complete path of the service password file. By
+ default, ``/usr/local/var/service_passwd`` is used.
- *servicedn*
- Specifies Distinguished Name (DN) of the service object whose password is to be stored in file.
+*servicedn*
+ Specifies Distinguished Name (DN) of the service object whose
+ password is to be stored in file.
EXAMPLE::
- 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":
+ 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":
.. _kdb5_ldap_util_stashsrvpw_end:
create_policy
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
.. _kdb5_ldap_util_create_policy:
- **create_policy** [**-r** *realm*] [**-maxtktlife** *max_ticket_life*] [**-maxrenewlife** *max_renewable_ticket_life*] [*ticket_flags*] *policy_name*
- Creates a ticket policy in directory. Options:
-
- **-r** *realm*
- Specifies the Kerberos realm of the database.
-
- **-maxtktlife** *max_ticket_life*
- Specifies maximum ticket life for principals.
-
- **-maxrenewlife** *max_renewable_ticket_life*
- 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.
-
- The various flags are:
-
- {-\|+}allow_postdated
- *-allow_postdated* prohibits principals from obtaining postdated tickets.
- (Sets the KRB5_KDB_DISALLOW_POSTDATED flag.) *+allow_postdated* clears this flag.
-
- {-\|+}allow_forwardable
- *-allow_forwardable* prohibits principals from obtaining forwardable tickets.
- (Sets the KRB5_KDB_DISALLOW_FORWARDABLE flag.) *+allow_forwardable* clears this flag.
-
- {-\|+}allow_renewable
- *-allow_renewable* prohibits principals from obtaining renewable tickets.
- (Sets the KRB5_KDB_DISALLOW_RENEWABLE flag.) *+allow_renewable* clears this flag.
-
- {-\|+}allow_proxiable
- *-allow_proxiable* prohibits principals 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 principals by prohibiting principals
- 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 principals 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 principals 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 principals.
- (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 principals 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 principals in the database.
-
- {-\|+}allow_tix
- *-allow_tix* forbids the issuance of any tickets for principals.
- *+allow_tix* clears this flag.
- The default is *+allow_tix*. In effect, *-allow_tix sets* the KRB5_KDB_DISALLOW_ALL_TIX flag on principals 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 principals in the database.
-
- {-\|+}password_changing_service
- *+password_changing_service* sets a flag in the attributes field marking principal 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 principals in the database.
-
- *policy_name*
- Specifies the name of the ticket policy.
+ **create_policy**
+ [**-r** *realm*]
+ [**-maxtktlife** *max_ticket_life*]
+ [**-maxrenewlife** *max_renewable_ticket_life*]
+ [*ticket_flags*]
+ *policy_name*
+
+Creates a ticket policy in directory. Options:
+
+**-r** *realm*
+ Specifies the Kerberos realm of the database.
+
+**-maxtktlife** *max_ticket_life*
+ Specifies maximum ticket life for principals.
+
+**-maxrenewlife** *max_renewable_ticket_life*
+ 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.
+
+ 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::
- 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 -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:
modify_policy
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
.. _kdb5_ldap_util_modify_policy:
+ **modify_policy**
+ [**-r** *realm*]
+ [**-maxtktlife** *max_ticket_life*]
+ [**-maxrenewlife** *max_renewable_ticket_life*]
+ [*ticket_flags*]
+ *policy_name*
- **modify_policy**
- [**-r** *realm*]
- [**-maxtktlife** *max_ticket_life*]
- [**-maxrenewlife** *max_renewable_ticket_life*]
- [*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
+create_policy.
- **-r** *realm*
- Specifies the Kerberos realm of the database.
+**-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
- Password for "cn=admin,o=org":
+ 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:
view_policy
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~
.. _kdb5_ldap_util_view_policy:
- **view_policy** [**-r** *realm*] *policy_name*
- Displays the attributes of a ticket policy. Options:
+ **view_policy**
+ [**-r** *realm*]
+ *policy_name*
- *policy_name*
- Specifies the name of the ticket policy.
+Displays the attributes of a ticket policy. Options:
+
+*policy_name*
+ Specifies the name of the ticket policy.
EXAMPLE::
- 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
- Maximum renewable life: 0 days 10:00:00
- Ticket flags: DISALLOW_FORWARDABLE REQUIRES_PWCHANGE
+ 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
+ Maximum renewable life: 0 days 10:00:00
+ Ticket flags: DISALLOW_FORWARDABLE REQUIRES_PWCHANGE
.. _kdb5_ldap_util_view_policy_end:
destroy_policy
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
.. _kdb5_ldap_util_destroy_policy:
- **destroy_policy**
- [**-r** *realm*]
- [**-force**]
- *policy_name*
-
- Destroys an existing ticket policy. Options:
+ **destroy_policy**
+ [**-r** *realm*]
+ [**-force**]
+ *policy_name*
- **-r** *realm*
- Specifies the Kerberos realm of the database.
+Destroys an existing ticket policy. Options:
- **-force**
- Forces the deletion of the policy object. If not specified, will be prompted for confirmation while deleting the policy.
- Enter yes to confirm the deletion.
+**-r** *realm*
+ Specifies the Kerberos realm of the database.
- *policy_name*
- Specifies the name of the ticket policy.
+**-force**
+ Forces the deletion of the policy object. If not specified, will
+ be prompted for confirmation while deleting the policy. Enter yes
+ to confirm the deletion.
-EXAMPLE::
+*policy_name*
+ Specifies the name of the ticket policy.
- 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
- ** policy object 'tktpolicy' deleted.
+Example::
+
+ 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
+ ** policy object 'tktpolicy' deleted.
.. _kdb5_ldap_util_destroy_policy_end:
list_policy
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~
.. _kdb5_ldap_util_list_policy:
- **list_policy** [**-r** *realm*]
- Lists the ticket policies in realm if specified or in the default realm. Options:
+ **list_policy**
+ [**-r** *realm*]
- **-r** *realm*
- Specifies the Kerberos realm of the database.
+Lists the ticket policies in realm if specified or in the default
+realm. Options:
-EXAMPLE::
+**-r** *realm*
+ Specifies the Kerberos realm of the database.
- 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
- userpolicy
+Example::
+
+ 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
+ userpolicy
.. _kdb5_ldap_util_list_policy_end:
Commands specific to eDirectory
---------------------------------
+-------------------------------
setsrvpw
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~
+
.. _kdb5_ldap_util_setsrvpw:
- **setsrvpw**
- [**-randpw\|-fileonly**]
- [**-f** *filename*]
- *service_dn*
-
- Allows an administrator to set password for service objects such as KDC and Administration server in eDirectory and store them in a file.
- The *-fileonly* option stores the password in a file and not in the eDirectory object. Options:
+ **setsrvpw**
+ [**-randpw\|-fileonly**]
+ [**-f** *filename*]
+ *service_dn*
- **-randpw**
- Generates and sets a random password.
- This options can be specified to store the password both in eDirectory and a file.
- The *-fileonly* option can not be used if *-randpw* option is already specified.
+Allows an administrator to set password for service objects such as
+KDC and Administration server in eDirectory and store them in a file.
+The **-fileonly** option stores the password in a file and not in the
+eDirectory object. Options:
- **-fileonly**
- Stores the password only in a file and not in eDirectory.
- The *-randpw* option can not be used when *-fileonly* options is specified.
+**-randpw**
+ Generates and sets a random password. This options can be
+ specified to store the password both in eDirectory and a file.
+ The **-fileonly** option can not be used if **-randpw** option is
+ already specified.
- **-f** *filename*
- Specifies complete path of the service password file. By default, */usr/local/var/service_passwd* is used.
+**-fileonly**
+ Stores the password only in a file and not in eDirectory. The
+ **-randpw** option can not be used when **-fileonly** options is
+ specified.
- *service_dn*
- Specifies Distinguished Name (DN) of the service object whose password is to be set.
+**-f** *filename*
+ Specifies complete path of the service password file. By default,
+ ``/usr/local/var/service_passwd`` is used.
-EXAMPLE::
+*service_dn*
+ Specifies Distinguished Name (DN) of the service object whose
+ password is to be set.
- kdb5_ldap_util setsrvpw -D cn=admin,o=org setsrvpw -fileonly -f /home/andrew/conf_keyfile cn=service-kdc,o=org
- Password for "cn=admin,o=org":
- Password for "cn=service-kdc,o=org":
- Re-enter password for "cn=service-kdc,o=org":
+Example::
+
+ kdb5_ldap_util setsrvpw -D cn=admin,o=org setsrvpw -fileonly -f /home/andrew/conf_keyfile cn=service-kdc,o=org
+ Password for "cn=admin,o=org":
+ Password for "cn=service-kdc,o=org":
+ Re-enter password for "cn=service-kdc,o=org":
.. _kdb5_ldap_util_setsrvpw_end:
create_service
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
.. _kdb5_ldap_util_create_service:
- **create_service**
- {**-kdc\|-admin\|-pwd**}
- [**-servicehost** *service_host_list*]
- [**-realm** *realm_list*]
- [**-randpw\|-fileonly**]
- [**-f** *filename*] *service_dn*
-
- Creates a service in directory and assigns appropriate rights. Options:
+ **create_service**
+ {**-kdc**\|\ **-admin**\|\ **-pwd**}
+ [**-servicehost** *service_host_list*]
+ [**-realm** *realm_list*]
+ [**-randpw**\|\ **-fileonly**]
+ [**-f** *filename*]
+ *service_dn*
- **-kdc**
- Specifies the service is a KDC service
+Creates a service in directory and assigns appropriate rights. Options:
- **-admin**
- Specifies the service is a Administration service
+**-kdc**
+ Specifies the service is a KDC service
- **-pwd**
- Specifies the Password service
+**-admin**
+ Specifies the service is a Administration service
- **-servicehost** *service_host_list*
- Specifies the list of entries separated by a colon (\:).
- Each entry consists of the hostname or IP address of the server hosting the service,
- transport protocol, and the port number of the service separated by a pound sign (#).
- For example, server1#tcp#88:server2#udp#89.
+**-pwd**
+ Specifies the Password service
- **-realm** *realm_list*
- Specifies the list of realms that are to be associated with this service.
- The list contains the name of the realms separated by a colon (\:).
+**-servicehost** *service_host_list*
+ Specifies the list of entries separated by a colon (``:``). Each
+ entry consists of the hostname or IP address of the server hosting
+ the service, transport protocol, and the port number of the
+ service separated by a pound sign (``#``). For example,
+ ``server1#tcp#88:server2#udp#89``.
- **-randpw**
- Generates and sets a random password. This option is used to set the random password for
- the service object in directory and also to store it in the file.
- The *-fileonly* option can not be used if *-randpw* option is specified.
+**-realm** *realm_list*
+ Specifies the list of realms that are to be associated with this
+ service. The list contains the name of the realms separated by a
+ colon (``:``).
- **-fileonly**
- Stores the password only in a file and not in eDirectory.
- The *-randpw* option can not be used when *-fileonly* option is specified.
+**-randpw**
+ Generates and sets a random password. This option is used to set
+ the random password for the service object in directory and also
+ to store it in the file. The **-fileonly** option can not be used
+ if **-randpw** option is specified.
- **-f** *filename*
- Specifies the complete path of the file where the service object password is stashed.
+**-fileonly**
+ Stores the password only in a file and not in eDirectory. The
+ **-randpw** option can not be used when **-fileonly** option is
+ specified.
- *service_dn*
- Specifies Distinguished Name (DN) of the Kerberos service to be created.
+**-f** *filename*
+ Specifies the complete path of the file where the service object
+ password is stashed.
-EXAMPLE::
+*service_dn*
+ Specifies Distinguished Name (DN) of the Kerberos service to be
+ created.
+
+Example::
- shell% kdb5_ldap_util -D cn=admin,o=org create_service -kdc -randpw -f /home/andrew/conf_keyfile cn=service-kdc,o=org
- Password for "cn=admin,o=org":
- File does not exist. Creating the file /home/andrew/conf_keyfile...
- shell%
+ shell% kdb5_ldap_util -D cn=admin,o=org create_service -kdc -randpw -f /home/andrew/conf_keyfile cn=service-kdc,o=org
+ Password for "cn=admin,o=org":
+ File does not exist. Creating the file /home/andrew/conf_keyfile...
+ shell%
.. _kdb5_ldap_util_create_service_end:
modify_service
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
.. _kdb5_ldap_util_modify_service:
-
- **modify_service**
- [**-servicehost** *service_host_list* | [**-clearservicehost** *service_host_list*] [**-addservicehost** *service_host_list*]]
- [**-realm** *realm_list* | [**-clearrealm** *realm_list*] [**-addrealm** *realm_list*]]
- *service_dn*
-
- Modifies the attributes of a service and assigns appropriate rights. Options:
-
- **-servicehost** *service_host_list*
- Specifies the list of entries separated by a colon (\:).
- Each entry consists of a host name or IP Address of the Server hosting the service, transport protocol,
- and port number of the service separated by a pound sign (#). For example::
-
- server1#tcp#88:server2#udp#89
-
- **-clearservicehost** *service_host_list*
- Specifies the list of servicehost entries to be removed from the existing list separated by colon (\:).
- Each entry consists of a host name or IP Address of
- the server hosting the service, transport protocol, and port number of the service separated by a pound sign (#).
-
- **-addservicehost** *service_host_list*
- Specifies the list of servicehost entries to be added to the existing list separated by colon (\:).
- Each entry consists of a host name or IP Address of the
- server hosting the service, transport protocol, and port number of the service separated by a pound sign (#).
-
- **-realm** *realm_list*
- Specifies the list of realms that are to be associated with this service.
- The list contains the name of the realms separated by a colon (\:).
- This list replaces the existing list.
-
- **-clearrealm** *realm_list*
- Specifies the list of realms to be removed from the existing list.
- The list contains the name of the realms separated by a colon (\:).
-
- **-addrealm** *realm_list*
- Specifies the list of realms to be added to the existing list.
- The list contains the name of the realms separated by a colon (\:).
-
+ **modify_service**
+ [**-servicehost** *service_host_list* |
+ [**-clearservicehost** *service_host_list*]
+ [**-addservicehost** *service_host_list*]]
+ [**-realm** *realm_list* |
+ [**-clearrealm** *realm_list*]
+ [**-addrealm** *realm_list*]]
*service_dn*
- Specifies Distinguished Name (DN) of the Kerberos service to be modified.
-
-EXAMPLE::
- shell% kdb5_ldap_util -D cn=admin,o=org modify_service -realm ATHENA.MIT.EDU cn=service-kdc,o=org
- Password for "cn=admin,o=org":
- Changing rights for the service object. Please wait ... done
- shell%
+Modifies the attributes of a service and assigns appropriate
+rights. Options:
+
+**-servicehost** *service_host_list*
+ Specifies the list of entries separated by a colon (``:``). Each
+ entry consists of a host name or IP Address of the Server hosting
+ the service, transport protocol, and port number of the service
+ separated by a pound sign (``#``). For example,
+ ``server1#tcp#88:server2#udp#89``.
+
+**-clearservicehost** *service_host_list*
+ Specifies the list of servicehost entries to be removed from the
+ existing list separated by colon (``:``). Each entry consists of
+ a host name or IP Address of the server hosting the service,
+ transport protocol, and port number of the service separated by a
+ pound sign (``#``).
+
+**-addservicehost** *service_host_list*
+ Specifies the list of servicehost entries to be added to the
+ existing list separated by colon (``:``). Each entry consists of
+ a host name or IP Address of the server hosting the service,
+ transport protocol, and port number of the service separated by a
+ pound sign (``#``).
+
+**-realm** *realm_list*
+ Specifies the list of realms that are to be associated with this
+ service. The list contains the name of the realms separated by a
+ colon (``:``). This list replaces the existing list.
+
+**-clearrealm** *realm_list*
+ Specifies the list of realms to be removed from the existing list.
+ The list contains the name of the realms separated by a colon
+ (``:``).
+
+**-addrealm** *realm_list*
+ Specifies the list of realms to be added to the existing list.
+ The list contains the name of the realms separated by a colon
+ (``:``).
+
+*service_dn*
+ Specifies Distinguished Name (DN) of the Kerberos service to be
+ modified.
+
+Example::
+
+ shell% kdb5_ldap_util -D cn=admin,o=org modify_service -realm ATHENA.MIT.EDU cn=service-kdc,o=org
+ Password for "cn=admin,o=org":
+ Changing rights for the service object. Please wait ... done
+ shell%
.. _kdb5_ldap_util_modify_service_end:
view_service
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~
.. _kdb5_ldap_util_view_service:
- **view_service** *service_dn*
- Displays the attributes of a service. Options:
+ **view_service** *service_dn*
- *service_dn*
- Specifies Distinguished Name (DN) of the Kerberos service to be viewed.
+Displays the attributes of a service. Options:
-EXAMPLE::
+*service_dn*
+ Specifies Distinguished Name (DN) of the Kerberos service to be
+ viewed.
- shell% kdb5_ldap_util -D cn=admin,o=org view_service cn=service-kdc,o=org
- Password for "cn=admin,o=org":
- Service dn: cn=service-kdc,o=org
- Service type: kdc
- Service host list:
- Realm DN list: cn=ATHENA.MIT.EDU,cn=Kerberos,cn=Security
- shell%
+Example::
+
+ shell% kdb5_ldap_util -D cn=admin,o=org view_service cn=service-kdc,o=org
+ Password for "cn=admin,o=org":
+ Service dn: cn=service-kdc,o=org
+ Service type: kdc
+ Service host list:
+ Realm DN list: cn=ATHENA.MIT.EDU,cn=Kerberos,cn=Security
+ shell%
.. _kdb5_ldap_util_view_service_end:
destroy_service
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~
.. _kdb5_ldap_util_destroy_service:
- **destroy_service** [**-force**] [**-f** *stashfilename*] *service_dn*
- Destroys an existing service. Options:
+ **destroy_service**
+ [**-force**]
+ [**-f** *stashfilename*]
+ *service_dn*
- **-force**
- If specified, will not prompt for user's confirmation, instead will force destruction of the service.
+Destroys an existing service. Options:
- **-f** *stashfilename*
- Specifies the complete path of the service password file from where the entry corresponding
- to the service_dn needs to be removed.
+**-force**
+ If specified, will not prompt for user's confirmation, instead
+ will force destruction of the service.
- *service_dn*
- Specifies Distinguished Name (DN) of the Kerberos service to be destroyed.
+**-f** *stashfilename*
+ Specifies the complete path of the service password file from
+ where the entry corresponding to the service_dn needs to be
+ removed.
+
+*service_dn*
+ Specifies Distinguished Name (DN) of the Kerberos service to be
+ destroyed.
EXAMPLE::
- shell% kdb5_ldap_util -D cn=admin,o=org destroy_service cn=service-kdc,o=org
- Password for "cn=admin,o=org":
- This will delete the service object 'cn=service-kdc,o=org', are you sure?
- (type 'yes' to confirm)? yes
- ** service object 'cn=service-kdc,o=org' deleted.
- shell%
+ shell% kdb5_ldap_util -D cn=admin,o=org destroy_service cn=service-kdc,o=org
+ Password for "cn=admin,o=org":
+ This will delete the service object 'cn=service-kdc,o=org', are you sure?
+ (type 'yes' to confirm)? yes
+ ** service object 'cn=service-kdc,o=org' deleted.
+ shell%
.. _kdb5_ldap_util_destroy_service_end:
list_service
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~
.. _kdb5_ldap_util_list_service:
- **list_service** [**-basedn** *base_dn*]
- Lists the name of services under a given base in directory. Options:
+ **list_service** [**-basedn** *base_dn*]
+
+Lists the name of services under a given base in directory. Options:
- **-basedn** *base_dn*
- Specifies the base DN for searching the service objects, limiting the search to a particular subtree.
- If this option is not provided, LDAP Server specific search base will be used.
- For eg, in the case of OpenLDAP, value of defaultsearchbase from *slapd.conf* file will be used,
- where as in the case of eDirectory, the default value for the base DN is Root.
+**-basedn** *base_dn*
+ Specifies the base DN for searching the service objects, limiting
+ the search to a particular subtree. If this option is not
+ provided, LDAP Server specific search base will be used. For eg,
+ in the case of OpenLDAP, value of defaultsearchbase from
+ slapd.conf file will be used, where as in the case of eDirectory,
+ the default value for the base DN is Root.
EXAMPLE::
- shell% kdb5_ldap_util -D cn=admin,o=org list_service
- Password for "cn=admin,o=org":
- cn=service-kdc,o=org
- cn=service-adm,o=org
- cn=service-pwd,o=org
- shell%
+ shell% kdb5_ldap_util -D cn=admin,o=org list_service
+ Password for "cn=admin,o=org":
+ cn=service-kdc,o=org
+ cn=service-adm,o=org
+ cn=service-pwd,o=org
+ shell%
.. _kdb5_ldap_util_list_service_end:
SEE ALSO
------------------------
-
-kadmin(8)
+--------
+kadmin(8)
.. _kdb5_util(8):
kdb5_util
-==========
+=========
SYNOPSIS
----------------
+--------
.. _kdb5_util_synopsys:
-
-**kdb5_util**
- [**-r** *realm*]
- [**-d** *dbname*]
- [**-k** *mkeytype*]
- [**-M** *mkeyname*]
- [**-kv** *mkeyVNO*]
- [**-sf** *stashfilename*]
- [**-m**]
- *command* [*command_options*]
+
+**kdb5_util**
+[**-r** *realm*]
+[**-d** *dbname*]
+[**-k** *mkeytype*]
+[**-M** *mkeyname*]
+[**-kv** *mkeyVNO*]
+[**-sf** *stashfilename*]
+[**-m**]
+*command* [*command_options*]
.. _kdb5_util_synopsys_end:
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 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.
-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.
+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 KDB plugins may not support all kdb5_util commands.
COMMAND-LINE OPTIONS
-----------------------
-
+--------------------
+
.. _kdb5_util_options:
- **-r** *realm*
- specifies the Kerberos realm of the database.
+**-r** *realm*
+ specifies the Kerberos realm of the database.
- **-d** *dbname*
- specifies the name under which the principal database is stored; by default the database is that listed in :ref:`kdc.conf`.
- The KADM5 policy database and lock file are also derived from this value.
+**-d** *dbname*
+ specifies the name under which the principal database is stored;
+ by default the database is that listed in :ref:`kdc.conf`. The
+ KADM5 policy database and lock file are also derived from this
+ value.
- **-k** *mkeytype*
- specifies the key type of the master key in the database; the default is that given in :ref:`kdc.conf`.
+**-k** *mkeytype*
+ specifies the key type of the master key in the database; the
+ default is that given in :ref:`kdc.conf`.
- **-kv** *mkeyVNO*
- Specifies the version number of the master key in the database; the default is 1. Note that 0 is not allowed.
+**-kv** *mkeyVNO*
+ Specifies the version number of the master key in the database;
+ 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`.
+**-M** *mkeyname*
+ principal name for the master key in the database; the default is
+ that given in :ref:`kdc.conf`.
- **-m**
- specifies that the master database password should be read from the TTY rather than fetched from a file on disk.
+**-m**
+ specifies that the master database password should be read from
+ the TTY rather than fetched from a file on disk.
- **-sf** *stash_file*
- specifies the stash file of the master database password.
+**-sf** *stash_file*
+ specifies the stash file of the master database password.
- **-P** *password*
- specifies the master database password. This option is not recommended.
+**-P** *password*
+ specifies the master database password. This option is not
+ recommended.
.. _kdb5_util_options_end:
COMMANDS
----------------
-
+--------
+
+create
+~~~~~~
+
.. _kdb5_util_create:
- **create** [**-s**]
- Creates a new database. If the *-s* option is specified, the stash file is also created. This command fails if the database already exists.
- If the command is successful, the database is opened just as if it had already existed when the program was first run.
+ **create** [**-s**]
+
+Creates a new database. If the **-s** option is specified, the stash
+file is also created. This command fails if the database already
+exists. If the command is successful, the database is opened just as
+if it had already existed when the program was first run.
.. _kdb5_util_create_end:
+destroy
+~~~~~~~
+
.. _kdb5_util_destroy:
- **destroy** [**-f**]
- Destroys the database, first overwriting the disk sectors and then unlinking the files, after prompting the user for confirmation.
- With the *-f* argument, does not prompt the user.
+ **destroy** [**-f**]
+
+Destroys the database, first overwriting the disk sectors and then
+unlinking the files, after prompting the user for confirmation. With
+the **-f** argument, does not prompt the user.
.. _kdb5_util_destroy_end:
+stash
+~~~~~
+
.. _kdb5_util_stash:
- **stash** [**-f** *keyfile*]
- Stores the master principal's keys in a stash file. The *-f* argument can be used to override the *keyfile* specified at startup.
+ **stash** [**-f** *keyfile*]
+
+Stores the master principal's keys in a stash file. The **-f**
+argument can be used to override the *keyfile* specified at startup.
.. _kdb5_util_stash_end:
+dump
+~~~~
+
.. _kdb5_util_dump:
- **dump** [**-old|-b6|-b7|-ov|-r13**] [**-verbose**] [**-mkey_convert**] [**-new_mkey_file** *mkey_file*] [**-rev**] [**-recurse**] [*filename* [*principals*...]]
- Dumps the current Kerberos and KADM5 database into an ASCII file. By default, the database is dumped in current format, "*kdb5_util*
- load_dump version 6". If filename is not specified, or is the string "-", the dump is sent to standard output. Options:
+ **dump** [**-old**\|\ **-b6**\|\ **-b7**\|\ **-ov**\|\ **-r13**]
+ [**-verbose**] [**-mkey_convert**] [**-new_mkey_file** *mkey_file*]
+ [**-rev**] [**-recurse**] [*filename* [*principals*...]]
+
+Dumps the current Kerberos and KADM5 database into an ASCII file. By
+default, the database is dumped in current format, "kdb5_util
+load_dump version 6". If filename is not specified, or is the string
+"-", the dump is sent to standard output. Options:
+
+**-old**
+ causes the dump to be in the Kerberos 5 Beta 5 and earlier dump
+ format ("kdb5_edit load_dump version 2.0").
+
+**-b6**
+ causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit
+ load_dump version 3.0").
+
+**-b7**
+ causes the dump to be in the Kerberos 5 Beta 7 format ("kdb5_util
+ load_dump version 4"). This was the dump format produced on
+ releases prior to 1.2.2.
+
+**-ov**
+ 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
+ load_dump version 5"). This was the dump format produced on
+ releases prior to 1.8.
+
+**-verbose**
+ causes the name of each principal and policy to be printed as it
+ is dumped.
+
+**-mkey_convert**
+ prompts for a new master key. This new master key will be used to
+ re-encrypt the key data in the dumpfile. The key data in the
+ database will not be changed.
+
+**-new_mkey_file** *mkey_file*
+ the filename of a stash file. The master key in this stash file
+ will be used to re-encrypt the key data in the dumpfile. The key
+ data in the database will not be changed.
+
+**-rev**
+ dumps in reverse order. This may recover principals that do not
+ dump normally, in cases where database corruption has occurred.
+
+**-recurse**
+ causes the dump to walk the database recursively (btree only).
+ This may recover principals that do not dump normally, in cases
+ where database corruption has occurred. In cases of such
+ corruption, this option will probably retrieve more principals
+ than the **-rev** option will.
- **-old**
- causes the dump to be in the Kerberos 5 Beta 5 and earlier dump format ("kdb5_edit load_dump version 2.0").
+.. _kdb5_util_dump_end:
- **-b6**
- causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
+load
+~~~~
- **-b7**
- causes the dump to be in the Kerberos 5 Beta 7 format ("*kdb5_util* load_dump version 4").
- This was the dump format produced on releases prior to 1.2.2.
+.. _kdb5_util_load:
- **-ov**
- causes the dump to be in *ovsec_adm_export* format.
+ **load** [**-old**\|\ **-b6**\|\ **-b7**\|\ **-ov**\|\ **-r13**]
+ [**-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
+file is detected automatically and handled as appropriate. Unless the
+**-update** option is given, load creates a new database containing
+only the principals in the dump file, overwriting the contents of any
+previously existing database. Note that when using the LDAP KDB
+plugin the **-update** must be given. Options:
+
+**-old**
+ requires the database to be in the Kerberos 5 Beta 5 and earlier
+ format ("kdb5_edit load_dump version 2.0").
+
+**-b6**
+ requires the database to be in the Kerberos 5 Beta 6 format
+ ("kdb5_edit load_dump version 3.0").
+
+**-b7**
+ requires the database to be in the Kerberos 5 Beta 7 format
+ ("kdb5_util load_dump version 4").
+
+**-ov**
+ requires the database to be in ovsec_adm_import format. Must be
+ used with the **-update** option.
+
+**-hash**
+ requires the database to be stored as a hash. If this option is
+ not specified, the database will be stored as a btree. This
+ option is not recommended, as databases stored in hash format are
+ known to corrupt data and lose principals.
+
+**-verbose**
+ causes the name of each principal and policy to be printed as it
+ is dumped.
+
+**-update**
+ records from the dump file are added to or updated in the existing
+ database. (This is useful in conjunction with an ovsec_adm_export
+ format dump if you want to preserve per-principal policy
+ information, since the current default format does not contain
+ this data.) Otherwise, a new database is created containing only
+ 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
+line or the default.
- **-r13**
- causes the dump to be in the Kerberos 5 1.3 format ("*kdb5_util* load_dump version 5").
- This was the dump format produced on releases prior to 1.8.
+.. _kdb5_util_load_end:
- **-verbose**
- causes the name of each principal and policy to be printed as it is dumped.
+ark
+~~~
- **-mkey_convert**
- prompts for a new master key. This new master key will be used to re-encrypt the key data in the dumpfile.
- The key data in the database will not be changed.
+ **ark**
- **-new_mkey_file** *mkey_file*
- the filename of a stash file. The master key in this stash file will be used to re-encrypt the key data in the dumpfile.
- The key data in the database will not be changed.
+Adds a random key.
- **-rev**
- dumps in reverse order. This may recover principals that do not dump normally, in cases where database corruption has occurred.
+add_mkey
+~~~~~~~~
- **-recurse**
- causes the dump to walk the database recursively (btree only). This may recover principals that do not dump normally,
- in cases where database corruption has occurred.
- In cases of such corruption, this option will probably retrieve more principals than the *-rev* option will.
+ **add_mkey** [**-e** *etype*] [**-s**]
-.. _kdb5_util_dump_end:
+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.
-.. _kdb5_util_load:
+use_mkey
+~~~~~~~~
- **load** [**-old|-b6|-b7|-ov|-r13**] [**-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 file is detected automatically and handled as appropriate.
- Unless the *-update* option is given, load creates a new database containing only the principals in the dump file,
- overwriting the contents of any previously existing database.
- Note that when using the LDAP KDB plugin the *-update* must be given. Options:
+ **use_mkey** *mkeyVNO* [*time*]
- **-old**
- requires the database to be in the Kerberos 5 Beta 5 and earlier format ("kdb5_edit load_dump version 2.0").
+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 kadmin man page.
- **-b6**
- requires the database to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
+list_mkeys
+~~~~~~~~~~
- **-b7**
- requires the database to be in the Kerberos 5 Beta 7 format ("*kdb5_util* load_dump version 4").
+ **list_mkeys**
- **-ov**
- requires the database to be in ovsec_adm_import format. Must be used with the *-update* option.
+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 kadmin getprinc output. A ``*`` following an mkey
+denotes the currently active master key.
- **-hash**
- requires the database to be stored as a hash. If this option is not specified, the database will be stored as a btree.
- This option is not recommended, as databases stored in hash format are known to corrupt data and lose principals.
+purge_mkeys
+~~~~~~~~~~~
- **-verbose**
- causes the name of each principal and policy to be printed as it is dumped.
+ **purge_mkeys** [**-f**] [**-n**] [**-v**]
- **-update**
- records from the dump file are added to or updated in the existing database.
- (This is useful in conjunction with an *ovsec_adm_export* format dump if you want to preserve per-principal policy information,
- since the current default format does not contain this data.)
- Otherwise, a new database is created containing only what is in the dump file and the old one destroyed upon successful completion.
+Delete master keys from the ``K/M`` 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.
- *dbname* is required and overrides the value specified on the command line or the default.
+**-f**
+ does not prompt user.
-.. _kdb5_util_load_end:
+**-n**
+ do a dry run, shows master keys that would be purged, does not
+ actually purge any keys.
- **ark**
- Adds a random key.
-
- **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.
-
- **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 kadmin man page.
-
- **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 kadmin getprinc output.
- A \* following an mkey denotes the currently active master key.
-
- **purge_mkeys** [**-f**] [**-n**] [**-v**]
- Delete master keys from the *K/M* 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.
-
- **-f**
- does not prompt user.
-
- **-n**
- do a dry run, shows master keys that would be purged, does not actually purge any keys.
-
- **-v**
- verbose output.
-
- **update_princ_encryption** [**-f**] [**-n**] [**-v**] [*princ-pattern*]
- Update all principal records (or only those matching the princ-pattern glob pattern)
- to re-encrypt the key data using the active database master key, if they are encrypted using older 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.
+**-v**
+ verbose output.
-SEE ALSO
----------------
-
-kadmin(8)
+update_princ_encryption
+~~~~~~~~~~~~~~~~~~~~~~~
+
+ **update_princ_encryption** [**-f**] [**-n**] [**-v**]
+ [*princ-pattern*]
+Update all principal records (or only those matching the
+*princ-pattern* glob pattern) to re-encrypt the key data using the
+active database master key, if they are encrypted using older
+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.
+SEE ALSO
+--------
+
+kadmin(8)
.. _kprop(8):
kprop
-=========
-
+=====
SYNOPSIS
--------------
+--------
**kprop**
- [**-r** *realm*]
- [**-f** *file*]
- [**-d**]
- [**-P** *port*]
- [**-s** *keytab*]
- *slave_host*
+[**-r** *realm*]
+[**-f** *file*]
+[**-d**]
+[**-P** *port*]
+[**-s** *keytab*]
+*slave_host*
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 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)`.
OPTIONS
--------------
+-------
+
+**-r** *realm*
+ Specifies the realm of the master server.
- **-r** *realm*
- Specifies the realm of the master server.
+**-f** *file*
+ Specifies the filename where the dumped principal database file is
+ to be found; by default the dumped database file is normally
+ ``/usr/local/var/krb5kdc/slave_datatrans``.
- **-f** *file*
- Specifies the filename where the dumped principal database file is to be found;
- by default the dumped database file is normally
- */usr/local/var/krb5kdc/slave_datatrans*.
+**-P** *port*
+ Specifies the port to use to contact the :ref:`kpropd(8)` server
+ on the remote host.
- **-P** *port*
- Specifies the port to use to contact the :ref:`kpropd(8)` server on the remote host.
+**-d**
+ Prints debugging information.
- **-d**
- Prints debugging information.
+**-s** *keytab*
+ Specifies the location of the keytab file.
- **-s** *keytab*
- Specifies the location of the keytab file.
ENVIRONMENT
---------------
+-----------
*kprop* uses the following environment variable:
- - **KRB5_CONFIG**
+* **KRB5_CONFIG**
+
SEE ALSO
--------------
+--------
kpropd(8), kdb5_util(8), krb5kdc(8)
-
.. _kpropd(8):
kpropd
-===========
-
+======
SYNOPSIS
-----------
+--------
**kpropd**
- [ **-r** *realm* ]
- [ **-a** *acl_file* ]
- [ **-f** *slave_dumpfile* ]
- [ **-F** *principal_database* ]
- [ **-p** *kdb5_util_prog* ]
- [ **-P** *port* ]
- [ **-d** ]
- [ **-S** ]
+[**-r** *realm*]
+[**-a** *acl_file*]
+[**-f** *slave_dumpfile*]
+[**-F** *principal_database*]
+[**-p** *kdb5_util_prog*]
+[**-P** *port*]
+[**-d**]
+[**-S**]
DESCRIPTION
--------------
-
-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.
-
-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 the slave servers.
-Upon a successful download of the KDC database file,
-the slave Kerberos server will have an up-to-date KDC database.
-
-Normally, *kpropd* is invoked out of inetd(8).
-This is done by adding a line to the *inetd.conf* file which looks like this::
-
- 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).
-
-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`.
-The principal "kiprop/slavehostname\@REALM"
-(where "slavehostname" is the name of the slave KDC host,
-and "REALM" is the name of the Kerberos realm)
+-----------
+
+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.
+
+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
+the slave servers. Upon a successful download of the KDC database
+file, the slave Kerberos server will have an up-to-date KDC database.
+
+Normally, kpropd is invoked out of inetd(8). This is done by adding
+a line to the ``/etc/inetd.conf`` file which looks like this::
+
+ 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).
+
+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`. The principal
+``kiprop/slavehostname@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
--------
- **-r** *realm*
- Specifies the realm of the master server.
+**-r** *realm*
+ Specifies the realm of the master server.
- **-f** *file*
- Specifies the filename where the dumped principal database file is to be stored;
- by default the dumped database file */usr/local/var/krb5kdc/from_master*.
+**-f** *file*
+ Specifies the filename where the dumped principal database file is
+ to be stored; by default the dumped database file
+ ``/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.
+**-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.
- **-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.
+**-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``.
- **-d**
- Turn on debug mode. In this mode, if the *-S* option is selected,
- *kpropd* will not detach itself from the current job and run in the background.
- Instead, it will run in the foreground and print out debugging messages
- during the database propagation.
+**-d**
+ Turn on debug mode. In this mode, if the **-S** option is
+ selected, kpropd will not detach itself from the current job and
+ run in the background. Instead, it will run in the foreground and
+ print out debugging messages during the database propagation.
- **-P**
- Allow for an alternate port number for *kpropd* to listen on.
- This is only useful if the program is run in standalone mode.
+**-P**
+ Allow for an alternate port number for kpropd to listen on. This
+ is only useful if the program is run in standalone mode.
- **-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.
+**-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
---------------
+-----------
-*kpropd* uses the following environment variables:
+kpropd uses the following environment variables:
- - **KRB5_CONFIG**
- - **KRB5_KDC_PROFILE**
+* **KRB5_CONFIG**
+* **KRB5_KDC_PROFILE**
FILES
----------
+-----
-*kpropd.acl*
- Access file for *kpropd*; the default location is */usr/local/var/krb5kdc/kpropd.acl*.
- Each entry is a line containing the principal of a *host* from which the local machine
- will allow Kerberos database propagation via :ref:`kprop(8)`.
+kpropd.acl
+ Access file for kpropd; the default location is
+ ``/usr/local/var/krb5kdc/kpropd.acl``. Each entry is a line
+ containing the principal of a host from which the local machine
+ will allow Kerberos database propagation via :ref:`kprop(8)`.
SEE ALSO
-----------
+--------
kprop(8), kdb5_util(8), krb5kdc(8), inetd(8)
-
-
.. _kproplog(8):
kproplog
-===========
-
+========
SYNOPSIS
-------------
+--------
**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 *kadmind* 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 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.
-
-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 last update received and
-the associated time stamp of the last update.
+-----------
+
+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 kadmind
+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 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.
+
+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
+last update received and the associated time stamp of the last update.
OPTIONS
-------------
-
- **-h**
- Display a summary of the update log.
- This information includes the database version number, state of the database,
- the number of updates in the log, the time stamp of the first and last update,
- and the version number of the first and last update entry.
-
- **-e** *num*
- Display the last *num* update entries in the log.
- This is useful when debugging synchronization between KDC servers.
-
- **-v**
- Display individual attributes per update. An example of the output generated for one entry::
-
- Update Entry
- Update serial # : 4
- Update operation : Add
- Update principal : test@EXAMPLE.COM
- Update size : 424
- Update committed : True
- Update time stamp : Fri Feb 20 23:37:42 2004
- Attributes changed : 6
- Principal
- Key data
- Password last changed
- Modifying principal
- Modification time
- TL data
+-------
+
+**-h**
+ Display a summary of the update log. This information includes
+ the database version number, state of the database, the number of
+ updates in the log, the time stamp of the first and last update,
+ and the version number of the first and last update entry.
+
+**-e** *num*
+ Display the last *num* update entries in the log. This is useful
+ when debugging synchronization between KDC servers.
+
+**-v**
+ Display individual attributes per update. An example of the
+ output generated for one entry::
+
+ Update Entry
+ Update serial # : 4
+ Update operation : Add
+ Update principal : test@EXAMPLE.COM
+ Update size : 424
+ Update committed : True
+ Update time stamp : Fri Feb 20 23:37:42 2004
+ Attributes changed : 6
+ Principal
+ Key data
+ Password last changed
+ Modifying principal
+ Modification time
+ TL data
ENVIRONMENT
---------------
+-----------
-*kproplog* uses the following environment variables:
+kproplog uses the following environment variables:
- - **KRB5_KDC_PROFILE**
+* **KRB5_KDC_PROFILE**
SEE ALSO
-------------
+--------
kpropd(8)
-
.. _krb5kdc(8):
krb5kdc
-===========================
+=======
SYNOPSIS
-----------
+--------
**krb5kdc**
- [ **-x** *db_args* ]
- [ **-d** *dbname* ]
- [ **-k** *keytype* ]
- [ **-M** *mkeyname* ]
- [ **-p** *portnum* ]
- [ **-m** ]
- [ **-r** *realm* ]
- [ **-n** ]
- [ **-w** *numworkers* ]
- [ **-P** *pid_file* ]
+[**-x** *db_args*]
+[**-d** *dbname*]
+[**-k** *keytype*]
+[**-M** *mkeyname*]
+[**-p** *portnum*]
+[**-m**]
+[**-r** *realm*]
+[**-n**]
+[**-w** *numworkers*]
+[**-P** *pid_file*]
+
DESCRIPTION
---------------
+-----------
+
+krb5kdc is the Kerberos version 5 Authentication Service and Key
+Distribution Center (AS/KDC).
-*krb5kdc* is the Kerberos version 5 Authentication Service and Key Distribution Center (AS/KDC).
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.
-
-The **-d** *dbname* option specifies the name under which the principal database can be found.
-This option does not apply to the LDAP database.
-
-The **-k** *keytype* option specifies the key type of the master key 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** option specifies that the master database password should be fetched
-from the keyboard rather than from a file on disk.
-
-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** *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 **-w** *numworkers* option tells the KDC to fork *numworkers* processes
-to listen to the KDC ports and process requests in parallel.
-The top level KDC process (whose pid is recorded in the pid file
-if the **-P** option is also given) acts as a supervisor.
-The supervisor will relay SIGHUP signals to the worker subprocesses,
-and will terminate the worker subprocess if the it is itself terminated or
-if any other worker process exits.
+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.
+
+The **-d** *dbname* option specifies the name under which the
+principal database can be found. This option does not apply to the
+LDAP database.
+
+The **-k** *keytype* option specifies the key type of the master key
+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** option specifies that the master database password should
+be fetched from the keyboard rather than from a file on disk.
+
+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** *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 **-w** *numworkers* option tells the KDC to fork *numworkers*
+processes to listen to the KDC ports and process requests in parallel.
+The top level KDC process (whose pid is recorded in the pid file if
+the **-P** option is also given) acts as a supervisor. The supervisor
+will relay SIGHUP signals to the worker subprocesses, and will
+terminate the worker subprocess if the it is itself terminated or if
+any other worker process exits.
.. note:: On operating systems which do not have *pktinfo* support,
- using worker processes will prevent the KDC from listening
- for UDP packets on network interfaces created after the KDC starts.
-
+ using worker processes will prevent the KDC from listening
+ for UDP packets on network interfaces created after the KDC
+ starts.
EXAMPLE
-----------
+-------
-The KDC may service requests for multiple realms (maximum 32 realms).
-The realms are listed on the command line.
-Per-realm options that can be specified on the command line pertain for each realm
-that follows it and are superseded by subsequent definitions of the same option.
+The KDC may service requests for multiple realms (maximum 32 realms).
+The realms are listed on the command line. Per-realm options that can
+be specified on the command line pertain for each realm that follows
+it and are superseded by subsequent definitions of the same option.
For example::
- krb5kdc -p 2001 -r REALM1 -p 2002 -r REALM2 -r REALM3
+ krb5kdc -p 2001 -r REALM1 -p 2002 -r REALM2 -r REALM3
+
+specifies that the KDC listen on port 2001 for REALM1 and on port 2002
+for REALM2 and REALM3. Additionally, per-realm parameters may be
+specified in the :ref:`kdc.conf` 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` description
+for further details.
-specifies that the KDC listen on port 2001 for REALM1 and on port 2002 for REALM2 and REALM3.
-Additionally, per-realm parameters may be specified in the :ref:`kdc.conf` 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` description for further details.
ENVIRONMENT
---------------
+-----------
*krb5kdc* uses the following environment variables:
- - **KRB5_CONFIG**
- - **KRB5_KDC_PROFILE**
+* **KRB5_CONFIG**
+* **KRB5_KDC_PROFILE**
SEE ALSO
------------
+--------
kdb5_util(8), kdc.conf(5), krb5.conf(5), kdb5_ldap_util(8)
-
.. _ktutil(1):
ktutil
-=============
-
+======
SYNOPSIS
--------------
+--------
**ktutil**
+
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 subshell from which an administrator can read, write, or edit entries in a Kerberos V5 keytab or V4 srvtab file.
COMMANDS
--------------
+--------
+
+list
+~~~~
+
+ **list**
+
+Displays the current keylist.
+
+Alias: **l**
+
+read_kt
+~~~~~~~
+
+ **read_kt** *keytab*
+
+Read the Kerberos V5 keytab file *keytab* into the current keylist.
+
+Alias: **rkt**
+
+read_st
+~~~~~~~
+
+ **read_st** *srvtab*
- **list**
- Displays the current keylist.
+Read the Kerberos V4 srvtab file *srvtab* into the current keylist.
- Alias: **l**
+Alias: **rst**
- **read_kt** *keytab*
- Read the Kerberos V5 keytab file *keytab* into the current keylist.
+write_kt
+~~~~~~~~
- Alias: **rkt**
+ **write_kt** *keytab*
- **read_st** *srvtab*
- Read the Kerberos V4 srvtab file *srvtab* into the current keylist.
+Write the current keylist into the Kerberos V5 keytab file *keytab*.
- Alias: **rst**
+Alias: **wkt**
- **write_kt** *keytab*
- Write the current keylist into the Kerberos V5 keytab file *keytab*.
+write_st
+~~~~~~~~
- Alias: **wkt**
+ **write_st** *srvtab*
- **write_st** *srvtab*
- Write the current keylist into the Kerberos V4 srvtab file *srvtab*.
+Write the current keylist into the Kerberos V4 srvtab file *srvtab*.
- Alias: **wst**
+Alias: **wst**
+
+clear_list
+~~~~~~~~~~
**clear_list**
- Clear the current keylist.
- Alias: **clear**
+Clear the current keylist.
- **delete_entry** *slot*
- Delete the entry in slot number *slot* from the current keylist.
+Alias: **clear**
- Alias: *delent*
+delete_entry
+~~~~~~~~~~~~
- **add_entry** (**-key | -password)** **-p** *principal* **-k** *kvno* **-e** *enctype*
- Add *principal* to keylist using key or password.
+ **delete_entry** *slot*
- Alias: **addent**
+Delete the entry in slot number *slot* from the current keylist.
- **list_requests**
- Displays a listing of available commands.
+Alias: **delent**
- Aliases: **lr**, **?**
+add_entry
+~~~~~~~~~
- **quit**
- Quits ktutil.
+ **add_entry** {**-key**\|\ **-password**} **-p** *principal*
+ **-k** *kvno* **-e** *enctype*
- Aliases: **exit**, **q**
+Add *principal* to keylist using key or password.
+Alias: **addent**
-EXAMPLE::
+list_requests
+~~~~~~~~~~~~~
- ktutil: add_entry -password -p alice@BLEEP.COM -k 1 -e aes128-cts-hmac-sha1-96
- Password for alice@BLEEP.COM:
- ktutil: add_entry -password -p alice@BLEEP.COM -k 1 -e aes256-cts-hmac-sha1-96
- Password for alice@BLEEP.COM:
- ktutil: write_kt keytab
- ktutil:
+ **list_requests**
-SEE ALSO
--------------
+Displays a listing of available commands.
+
+Aliases: **lr**, **?**
+
+quit
+~~~~
+
+ **quit**
+
+Quits ktutil.
- kadmin(8), kdb5_util(8)
+Aliases: **exit**, **q**
+
+
+EXAMPLE
+-------
+
+::
+
+ ktutil: add_entry -password -p alice@BLEEP.COM -k 1 -e aes128-cts-hmac-sha1-96
+ Password for alice@BLEEP.COM:
+ ktutil: add_entry -password -p alice@BLEEP.COM -k 1 -e aes256-cts-hmac-sha1-96
+ Password for alice@BLEEP.COM:
+ ktutil: write_kt keytab
+ ktutil:
+
+SEE ALSO
+--------
+kadmin(8), kdb5_util(8)
.. _sserver(8):
sserver
-========
+=======
SYNOPSIS
-------------
+--------
**sserver**
-[ **-p** *port* ]
-[ **-S** *keytab* ]
+[ **-p** *port* ]
+[ **-S** *keytab* ]
[ *server_port* ]
+
DESCRIPTION
----------------
+-----------
-**sserver** and :ref:`sclient(1)` are a simple demonstration client/server application.
-When *sclient* connects to *sserver*, it performs a Kerberos authentication,
-and then sserver returns to *sclient* the Kerberos principal which was used for
-the Kerberos authentication. It makes a good test that Kerberos
-has been successfully installed on a machine.
+sserver and :ref:`sclient(1)` are a simple demonstration client/server
+application. When sclient connects to sserver, it performs a Kerberos
+authentication, and then sserver returns to sclient the Kerberos
+principal which was used for the Kerberos authentication. It makes a
+good test that Kerberos has been successfully installed on a machine.
-The service name used by *sserver* and *sclient* is sample.
-Hence, *sserver* will require that there be a keytab entry for the service
-"sample/hostname.domain.name\@REALM.NAME".
-This keytab is generated using the :ref:`kadmin(1)` program.
-The keytab file is usually installed as "/etc/krb5.keytab".
+The service name used by sserver and sclient is sample. Hence,
+sserver will require that there be a keytab entry for the service
+``sample/hostname.domain.name@REALM.NAME``. This keytab is generated
+using the :ref:`kadmin(1)` program. The keytab file is usually
+installed as ``/etc/krb5.keytab``.
The **-S** option allows for a different keytab than the default.
-*sserver* is normally invoked out of inetd(8), using a line in /etc/inetd.conf that looks like this::
+sserver is normally invoked out of inetd(8), using a line in
+``/etc/inetd.conf`` that looks like this::
+
+ 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
+like this::
-Since *sample* is normally not a port defined in /etc/services,
-you will usually have to add a line to /etc/services which looks like this::
+ sample 13135/tcp
- sample 13135/tcp
+When using sclient, you will first have to have an entry in the
+Kerberos database, by using :ref:`kadmin(1)`, and then you have to get
+Kerberos tickets, by using kinit(1). Also, if you are running the
+sclient program on a different host than the sserver it will be
+connecting to, be sure that both hosts have an entry in /etc/services
+for the sample tcp port, and that the same port number is in both
+files.
-When using *sclient*, you will first have to have an entry in the Kerberos database,
-by using :ref:`kadmin(1)`, and then you have to get Kerberos tickets, by using kinit(1).
-Also, if you are running the *sclient* program on a different host than the *sserver*
-it will be connecting to, be sure that both hosts have an entry in /etc/services
-for the sample tcp port, and that the same port number is in both files.
+When you run sclient you should see something like this::
-When you run *sclient* you should see something like this::
+ sendauth succeeded, reply is:
+ reply len 32, contents:
+ You are nlgilman@JIMI.MIT.EDU
- sendauth succeeded, reply is:
- reply len 32, contents:
- You are nlgilman@JIMI.MIT.EDU
COMMON ERROR MESSAGES
------------------------
+---------------------
-1) *kinit* returns the error::
+1) *kinit* returns the error::
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.
+ This means that you didn't create an entry for your username in the
+ Kerberos database.
-2) *sclient* returns the error::
+2) sclient returns the error::
unknown service sample/tcp; check /etc/services
- This means that you don't have an entry in /etc/services for the sample tcp port.
+ This means that you don't have an entry in /etc/services for the
+ sample tcp port.
-3) *sclient* returns the error::
+3) sclient returns the error::
connect: Connection refused
- This probably means you didn't edit /etc/inetd.conf correctly,
- or you didn't restart inetd after editing inetd.conf.
+ This probably means you didn't edit /etc/inetd.conf correctly, or
+ you didn't restart inetd after editing inetd.conf.
-4) *sclient* returns the error::
+4) sclient returns the error::
sclient: Server not found in Kerberos database while using sendauth
- This means that the "sample/hostname\@LOCAL.REALM" service was not defined
- in the Kerberos database; it should be created using *kadmin*, and a keytab file
- needs to be generated to make the key for that service principal available for *sclient*.
+ This means that the ``sample/hostname@LOCAL.REALM`` service was not
+ defined in the Kerberos database; it should be created using
+ kadmin, and a keytab file needs to be generated to make the key for
+ that service principal available for sclient.
-5) *sclient* returns the error::
+5) sclient returns the error::
sendauth rejected, error reply is:
" No such file or directory"
- This probably means *sserver* couldn't find the keytab file.
- It was probably not installed in the proper directory.
+ This probably means sserver couldn't find the keytab file. It was
+ probably not installed in the proper directory.
+
SEE ALSO
-------------
+--------
:ref:`sclient(1)`, services(5), inetd(8)
-
Advanced topics
-============================
-
+===============
Contents:
---------
plugins.rst
-
Topics in TODO list:
----------------------
+--------------------
-#. Choosing backend: LDAP vs DB2
-#. Validating Kerberos tickets
-#. Cross-realm interaction with AD
-#. Replication
-#. Performance tuning tips
-#. Logging error messages
+#. Choosing backend: LDAP vs DB2
+#. Validating Kerberos tickets
+#. Cross-realm interaction with AD
+#. Replication
+#. Performance tuning tips
+#. Logging error messages
-------------------
-Feedback:
+Feedback
+--------
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___admin_advanced
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___admin_advanced
.. _ldap_be_ubuntu:
LDAP backend on Ubuntu 10.4 (lucid)
-====================================
+===================================
Setting up Kerberos v1.9 with LDAP backend on Ubuntu 10.4 (lucid Lynx)
-Prerequisites:
---------------
+
+Prerequisites
+-------------
Install the following packages: *slapd, ldap-utils* and *libldap2-dev*
You can install the necessary packages with these commands::
- sudo apt-get install slapd
- sudo apt-get install ldap-utils
- sudo apt-get install libldap2-dev
+ sudo apt-get install slapd
+ sudo apt-get install ldap-utils
+ sudo apt-get install libldap2-dev
+
+Extend the user schema using schemas from standart OpenLDAP
+distribution: *cosine, mics, nis, inetcomperson* ::
-Extend the user schema using schemas from standart OpenLDAP distribution: *cosine, mics, nis, inetcomperson* ::
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/cosine.ldif
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/mics.ldif
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/nis.ldif
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/inetcomperson.ldif
- ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/cosine.ldif
- ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/mics.ldif
- ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/nis.ldif
- ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/inetcomperson.ldif
-
-Building Kerberos from source:
-------------------------------
+
+Building Kerberos from source
+-----------------------------
::
- util/reconf
- ./configure –with-ldap
- make
- sudo make install
+ util/reconf
+ ./configure –with-ldap
+ make
+ sudo make install
+
+.. note:: in some environments one may need to suppress rpath linker
+ option: ``./configure –with-ldap –disable-rpath``
-.. note:: in some environments one may need to suppress *rpath* linker option: *./configure –with-ldap –disable-rpath*
-Setting up Kerberos:
---------------------------------
+Setting up Kerberos
+-------------------
+
+Configuration
+~~~~~~~~~~~~~
-Configuration:
-~~~~~~~~~~~~~~
-
-Update Kerberos configuration files with the backend information:
+Update Kerberos configuration files with the backend information:
-krb5.conf::
+krb5.conf::
- [realms]
+ [realms]
EXAMPLE.COM = {
- database_module = LDAP
+ database_module = LDAP
}
- [dbdefaults]
+ [dbdefaults]
ldap_kerberos_container_dn = "cn=krbContainer,dc=example,dc=com"
- [dbmodules]
+ [dbmodules]
LDAP = {
- db_library = kldap
- ldap_kerberos_container_dn = "cn=krbContainer,dc=example,dc=com"
- ldap_kdc_dn = cn=admin,dc=example,dc=com
- ldap_kadmind_dn = cn=admin,dc=example,dc=com
- ldap_service_password_file = /tmp/krb5kdc/admin.stash
- ldap_servers = ldapi:///
+ db_library = kldap
+ ldap_kerberos_container_dn = "cn=krbContainer,dc=example,dc=com"
+ ldap_kdc_dn = cn=admin,dc=example,dc=com
+ ldap_kadmind_dn = cn=admin,dc=example,dc=com
+ ldap_service_password_file = /tmp/krb5kdc/admin.stash
+ ldap_servers = ldapi:///
}
-
kdc.conf::
- [realms]
+ [realms]
EXAMPLE.COM = {
- acl_file = /tmp/kadm5.acl
+ acl_file = /tmp/kadm5.acl
-
kadm5.acl::
- # See Kerberos V5 Installation Guide for detail of ACL setup and configuration
- */admin *
+ # See Kerberos V5 Installation Guide for detail of ACL setup and
+ # configuration
+ */admin *
-Setup run-time environment to point to the Kerberos configuration files::
+Setup run-time environment to point to the Kerberos configuration
+files::
- export KRB5_CONFIG=/tmp/krb5.conf
- export KRB5_KDC_PROFILE=/tmp/kdc.conf
+ export KRB5_CONFIG=/tmp/krb5.conf
+ export KRB5_KDC_PROFILE=/tmp/kdc.conf
-Schema:
-~~~~~~~
+Schema
+~~~~~~
-From the source tree copy *src/plugins/kdb/ldap/libkdb_ldap/kerberos.schema* into */etc/ldap/schema*
+From the source tree copy
+``src/plugins/kdb/ldap/libkdb_ldap/kerberos.schema`` into
+``/etc/ldap/schema``
-Warning:: it should be done after slapd is installed to avoid problems with slapd installation
+Warning: it should be done after slapd is installed to avoid problems
+with slapd installation
-To convert *kerberos.schema* to run-time configuration (cn=config) do the folowing:
+To convert kerberos.schema to run-time configuration (``cn=config``)
+do the folowing:
-#. create temporary file /tmp/schema_convert.conf with the following content::
+#. create temporary file ``/tmp/schema_convert.conf`` with the
+ following content::
- include /etc/ldap/schema/kerberos.schema
+ include /etc/ldap/schema/kerberos.schema
-#. Create temporary directory */tmp/krb5_ldif*
+#. Create temporary directory ``/tmp/krb5_ldif``
#. Run::
-
- slaptest -f /tmp/schema_convert.conf -F /tmp/krb5_ldif
- It should result into a new file */tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif*
+ slaptest -f /tmp/schema_convert.conf -F /tmp/krb5_ldif
+
+ It should result into a new file
+ ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif``
-#. Edit /tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif by replacing lines::
+#. Edit ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif`` by
+ replacing lines::
- dn: cn={0}kerberos
- cn: {0}kerberos
+ dn: cn={0}kerberos
+ cn: {0}kerberos
- with
+ with
- dn: cn=kerberos,cn=schema,cn=config
- cn: kerberos
+ dn: cn=kerberos,cn=schema,cn=config
+ cn: kerberos
Also, remove following attribute-value pairs::
-
- structuralObjectClass: olcSchemaConfig
- entryUUID: ...
- creatorsName: cn=config
- createTimestamp: ...
- entryCSN: ...
- modifiersName: cn=config
- modifyTimestamp: ...
+
+ structuralObjectClass: olcSchemaConfig
+ entryUUID: ...
+ creatorsName: cn=config
+ createTimestamp: ...
+ entryCSN: ...
+ modifiersName: cn=config
+ modifyTimestamp: ...
#. Load the new schema with ldapadd (with the proper authentication)::
- ldapadd -Y EXTERNAL -H ldapi:/// -f /tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif
+ ldapadd -Y EXTERNAL -H ldapi:/// -f /tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif
- which should result into *adding new entry "cn=kerberos,cn=schema,cn=config"* message
-
+ which should result into ``adding new entry
+ "cn=kerberos,cn=schema,cn=config"`` message
-Create Kerberos database:
--------------------------
-Using LDAP administrator credentials, create Kerberos database and stash::
+Create Kerberos database
+------------------------
- kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// create
+Using LDAP administrator credentials, create Kerberos database and
+stash::
-
-Stash the password::
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// create
- kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// stashsrvpw cn=admin,dc=example,dc=com
+Stash the password::
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// stashsrvpw cn=admin,dc=example,dc=com
-Start kdc::
+Start kdc::
- krb5kdc
-
+ krb5kdc
To destroy database run::
-
- kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// destroy -f
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// destroy -f
-Useful references:
--------------------
-* `Kerberos and LDAP <https://help.ubuntu.com/10.04/serverguide/C/kerberos-ldap.html>`_
-
-------------------
+Useful references
+-----------------
-Feedback:
+* `Kerberos and LDAP <https://help.ubuntu.com/10.04/serverguide/C/kerberos-ldap.html>`_
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___ldap_be_ubuntu
+Feedback
+--------
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___ldap_be_ubuntu
-How to create and add plugins
-===================================
+How to create and add plugins
+==============================
Initial reference: <http://k5wiki.kerberos.org/wiki/Projects/Plugin_support_improvements>_
-..
-------------------
+Feedback
+--------
-Feedback:
-
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___plugins
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___plugins
Clock Skew
-============
+==========
-In order to prevent intruders from resetting their system clocks in order to continue to use expired tickets, Kerberos V5 is set up to reject ticket requests from any host whose clock is not within the specified maximum clock skew of the KDC (as specified in the kdc.conf file). Similarly, hosts are configured to reject responses from any KDC whose clock is not within the specified maximum clock skew of the host (as specified in the krb5.conf file). The default value for maximum clock skew is 300 seconds, or five minutes. MIT suggests that you add a line to client machines' /etc/rc files to synchronize the machine's clock to your KDC at boot time. On UNIX hosts, assuming you had a kdc called kerberos in your realm, this would be::
+In order to prevent intruders from resetting their system clocks in
+order to continue to use expired tickets, Kerberos V5 is set up to
+reject ticket requests from any host whose clock is not within the
+specified maximum clock skew of the KDC (as specified in the kdc.conf
+file). Similarly, hosts are configured to reject responses from any
+KDC whose clock is not within the specified maximum clock skew of the
+host (as specified in the krb5.conf file). The default value for
+maximum clock skew is 300 seconds, or five minutes. MIT suggests that
+you add a line to client machines' ``/etc/rc`` files to synchronize
+the machine's clock to your KDC at boot time. On UNIX hosts, assuming
+you had a kdc called kerberos in your realm, this would be::
- gettime -s kerberos
-
+ gettime -s kerberos
-If the host is not likely to be rebooted frequently, you may also want to set up a cron job that adjusts the time on a regular basis.
+If the host is not likely to be rebooted frequently, you may also want
+to set up a cron job that adjusts the time on a regular basis.
-----------------------
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___appl_servers
.. _conf_firewall_label:
Configuring your firewall to work with Kerberos V5
-=====================================================
+==================================================
-If you need off-site users to be able to get Kerberos tickets in your realm, they must be able to get to your KDC. This requires either that you have a slave KDC outside your firewall, or you configure your firewall to allow UDP requests into at least one of your KDCs, on whichever port the KDC is running. (The default is port 88; other ports may be specified in the KDC's kdc.conf file.) Similarly, if you need off-site users to be able to change their passwords in your realm, they must be able to get to your Kerberos admin server. The default port for the admin server is 749.
+If you need off-site users to be able to get Kerberos tickets in your
+realm, they must be able to get to your KDC. This requires either
+that you have a slave KDC outside your firewall, or you configure your
+firewall to allow UDP requests into at least one of your KDCs, on
+whichever port the KDC is running. (The default is port 88; other
+ports may be specified in the KDC's kdc.conf file.) Similarly, if you
+need off-site users to be able to change their passwords in your
+realm, they must be able to get to your Kerberos admin server. The
+default port for the admin server is 749.
-If your on-site users inside your firewall will need to get to KDCs in other realms, you will also need to configure your firewall to allow outgoing TCP and UDP requests to port 88. Additionally, if they will need to get to any Kerberos V4 KDCs, you may also need to allow TCP and UDP requests to port 750. If your on-site users inside your firewall will need to get to Kerberos admin servers in other realms, you will also need to allow outgoing TCP and UDP requests to port 749.
+If your on-site users inside your firewall will need to get to KDCs in
+other realms, you will also need to configure your firewall to allow
+outgoing TCP and UDP requests to port 88. Additionally, if they will
+need to get to any Kerberos V4 KDCs, you may also need to allow TCP
+and UDP requests to port 750. If your on-site users inside your
+firewall will need to get to Kerberos admin servers in other realms,
+you will also need to allow outgoing TCP and UDP requests to port 749.
-If any of your KDCs are outside your firewall, you will need to allow *kprop* requests to get through to the remote KDC.
-*kprop* uses the *krb5_prop* service on port 754 (tcp).
+If any of your KDCs are outside your firewall, you will need to allow
+kprop requests to get through to the remote KDC. kprop uses the
+``krb5_prop`` service on port 754 (tcp).
-If you need your off-site users to have access to machines inside your firewall, you need to allow TCP connections from their off-site hosts on the appropriate ports for the programs they will be using. The following lines from */etc/services* show the default port numbers for the Kerberos V5 programs::
+If you need your off-site users to have access to machines inside your
+firewall, you need to allow TCP connections from their off-site hosts
+on the appropriate ports for the programs they will be using. The
+following lines from ``/etc/services`` show the default port numbers
+for the Kerberos V5 programs::
- ftp 21/tcp # Kerberos ftp and telnet use the
- telnet 23/tcp # default ports
- kerberos 88/udp kdc # Kerberos V5 KDC
- kerberos 88/tcp kdc # Kerberos V5 KDC
- klogin 543/tcp # Kerberos authenticated rlogin
- kshell 544/tcp cmd # and remote shell
- kerberos-adm 749/tcp # Kerberos 5 admin/changepw
- kerberos-adm 749/udp # Kerberos 5 admin/changepw
- krb5_prop 754/tcp # Kerberos slave propagation
- eklogin 2105/tcp # Kerberos auth. & encrypted rlogin
-
+ ftp 21/tcp # Kerberos ftp and telnet use the
+ telnet 23/tcp # default ports
+ kerberos 88/udp kdc # Kerberos V5 KDC
+ kerberos 88/tcp kdc # Kerberos V5 KDC
+ klogin 543/tcp # Kerberos authenticated rlogin
+ kshell 544/tcp cmd # and remote shell
+ kerberos-adm 749/tcp # Kerberos 5 admin/changepw
+ kerberos-adm 749/udp # Kerberos 5 admin/changepw
+ krb5_prop 754/tcp # Kerberos slave propagation
+ eklogin 2105/tcp # Kerberos auth. & encrypted rlogin
-By default, Kerberos V5 telnet and ftp use the same ports as the standard telnet and ftp programs, so if you already allow telnet and ftp connections through your firewall, the Kerberos V5 versions will get through as well. If you do not already allow telnet and ftp connections through your firewall, but need your users to be able to use Kerberos V5 telnet and ftp, you can either allow ftp and telnet connections on the standard ports, or switch these programs to non-default port numbers and allow ftp and telnet connections on those ports to get through. Kerberos V5 rlogin uses the *klogin* service, which by default uses port 543. Encrypted Kerberos V5 rlogin uses the *eklogin* service, which by default uses port 2105. Kerberos V5 rsh uses the kshell service, which by default uses port 544. However, the server must be able to make a TCP connection from the kshell port to an arbitrary port on the client, so if your users are to be able to use rsh from outside your firewall, the server they connect to must be able to send outgoing packets to arbitrary port numbers. Similarly, if your users need to run rsh from inside your firewall to hosts outside your firewall, the outside server needs to be able to connect to an arbitrary port on the machine inside your firewall. Because Kerberos V5 rcp uses rsh, the same issues apply. If you need to use rsh (or rcp) through your firewall and are concerned with the security implications of allowing connections to arbitrary ports, MIT suggests that you have rules that specifically name these applications and, if possible, list the allowed hosts.
+By default, Kerberos V5 telnet and ftp use the same ports as the
+standard telnet and ftp programs, so if you already allow telnet and
+ftp connections through your firewall, the Kerberos V5 versions will
+get through as well. If you do not already allow telnet and ftp
+connections through your firewall, but need your users to be able to
+use Kerberos V5 telnet and ftp, you can either allow ftp and telnet
+connections on the standard ports, or switch these programs to
+non-default port numbers and allow ftp and telnet connections on those
+ports to get through. Kerberos V5 rlogin uses the ``klogin`` service,
+which by default uses port 543. Encrypted Kerberos V5 rlogin uses the
+``eklogin`` service, which by default uses port 2105. Kerberos V5 rsh
+uses the kshell service, which by default uses port 544. However, the
+server must be able to make a TCP connection from the kshell port to
+an arbitrary port on the client, so if your users are to be able to
+use rsh from outside your firewall, the server they connect to must be
+able to send outgoing packets to arbitrary port numbers. Similarly,
+if your users need to run rsh from inside your firewall to hosts
+outside your firewall, the outside server needs to be able to connect
+to an arbitrary port on the machine inside your firewall. Because
+Kerberos V5 rcp uses rsh, the same issues apply. If you need to use
+rsh (or rcp) through your firewall and are concerned with the security
+implications of allowing connections to arbitrary ports, MIT suggests
+that you have rules that specifically name these applications and, if
+possible, list the allowed hosts.
-The book UNIX System Security, by David Curry, is a good starting point for learning to configure firewalls.
+The book UNIX System Security, by David Curry, is a good starting
+point for learning to configure firewalls.
-----------------------
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___appl_servers
Getting DNS information correct
-===================================
+===============================
-Several aspects of Kerberos rely on name service. In order for Kerberos to provide its high level of security, it is less forgiving of name service problems than some other parts of your network. It is important that your Domain Name System (DNS) entries and your hosts have the correct information.
+Several aspects of Kerberos rely on name service. In order for
+Kerberos to provide its high level of security, it is less forgiving
+of name service problems than some other parts of your network. It is
+important that your Domain Name System (DNS) entries and your hosts
+have the correct information.
-Each host's canonical name must be the fully-qualified host name (including the domain), and each host's IP address must reverse-resolve to the canonical name.
+Each host's canonical name must be the fully-qualified host name
+(including the domain), and each host's IP address must
+reverse-resolve to the canonical name.
-Other than the localhost entry, make all entries in each machine's /etc/hosts file in the following form::
+Other than the localhost entry, make all entries in each machine's
+/etc/hosts file in the following form::
- IP address fully-qualified hostname aliases
-
+ IP address fully-qualified hostname aliases
-Here is a sample */etc/hosts* file::
+Here is a sample ``/etc/hosts`` file::
- # this is a comment
- 127.0.0.1 localhost localhost@mit.edu
- 10.0.0.6 daffodil.mit.edu trillium wake-robin
-
+ # this is a comment
+ 127.0.0.1 localhost localhost@mit.edu
+ 10.0.0.6 daffodil.mit.edu trillium wake-robin
-Additionally, on Solaris machines, you need to be sure the "hosts" entry in the file */etc/nsswitch.conf* includes the source "dns" as well as "file".
+Additionally, on Solaris machines, you need to be sure the ``hosts``
+entry in the file ``/etc/nsswitch.conf`` includes the source ``dns``
+as well as ``file``.
-Finally, each host's keytab file must include a host/key pair for the host's canonical name. You can list the keys in a keytab file by issuing the command *klist -k*. For example::
+Finally, each host's keytab file must include a host/key pair for the
+host's canonical name. You can list the keys in a keytab file by
+issuing the command ``klist -k``. For example::
- viola# klist -k
- Keytab name: /etc/krb5.keytab
- KVNO Principal
- ---- ------------------------------------------------------------
- 1 host/daffodil.mit.edu@ATHENA.MIT.EDU
-
+ viola# klist -k
+ Keytab name: /etc/krb5.keytab
+ KVNO Principal
+ ---- ------------------------------------------------------------
+ 1 host/daffodil.mit.edu@ATHENA.MIT.EDU
-If you telnet to the host with a fresh credentials cache (ticket file), and then *klist*, the host's service principal should be::
+If you telnet to the host with a fresh credentials cache (ticket
+file), and then klist, the host's service principal should be::
- host/fully-qualified-hostname@REALM_NAME.
+ host/fully-qualified-hostname@REALM_NAME.
-----------------------
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___appl_servers
Application servers
-==========================
-
-If you need to install the Kerberos V5 programs on an application server, please refer to the Kerberos V5 Installation Guide. Once you have installed the software, you need to add that host to the Kerberos database (see :ref:`add_mod_del_princs_label`), and generate a keytab for that host, that contains the host's key. You also need to make sure the host's clock is within your maximum clock skew of the KDCs.
+===================
+If you need to install the Kerberos V5 programs on an application
+server, please refer to the Kerberos V5 Installation Guide. Once you
+have installed the software, you need to add that host to the Kerberos
+database (see :ref:`add_mod_del_princs_label`), and generate a keytab
+for that host, that contains the host's key. You also need to make
+sure the host's clock is within your maximum clock skew of the KDCs.
.. toctree::
:maxdepth: 2
dns_info.rst
conf_firewall.rst
-----------------------
-
-Feedback:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___appl_servers
Keytabs
-==============
+=======
-A keytab is a host's copy of its own keylist, which is analogous to a user's password. An application server that needs to authenticate itself to the KDC has to have a keytab that contains its own principal and key. Just as it is important for users to protect their passwords, it is equally important for hosts to protect their keytabs. You should always store keytab files on local disk, and make them readable only by root, and you should never send a keytab file over a network in the clear. Ideally, you should run the *kadmin* command to extract a keytab on the host on which the keytab is to reside.
+A keytab is a host's copy of its own keylist, which is analogous to a
+user's password. An application server that needs to authenticate
+itself to the KDC has to have a keytab that contains its own principal
+and key. Just as it is important for users to protect their
+passwords, it is equally important for hosts to protect their keytabs.
+You should always store keytab files on local disk, and make them
+readable only by root, and you should never send a keytab file over a
+network in the clear. Ideally, you should run the kadmin command to
+extract a keytab on the host on which the keytab is to reside.
.. _add_princ_kt:
Adding principals to keytabs
-----------------------------------
+----------------------------
-
-To generate a keytab, or to add a principal to an existing keytab, use the **ktadd** command from *kadmin*.
+To generate a keytab, or to add a principal to an existing keytab, use
+the **ktadd** command from kadmin.
.. include:: ../admin_commands/kadmin_local.rst
:start-after: _ktadd:
:end-before: _ktadd_end:
-
-.. note:: Alternatively, the keytab can be generated using :ref:`ktutil(1)` *add_entry -password* and *write_kt* commands.
+.. note:: Alternatively, the keytab can be generated using
+ :ref:`ktutil(1)` **add_entry -password** and **write_kt**
+ commands.
+Examples
+~~~~~~~~
-EXAMPLES:
+Here is a sample session, using configuration files that enable only
+*des-cbc-crc* encryption::
- Here is a sample session, using configuration files that enable only *des-cbc-crc* encryption::
+ kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU
+ kadmin: Entry for principal host/daffodil.mit.edu@ATHENA.MIT.EDU with kvno 2, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab.
+ kadmin:
- kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU
- kadmin: Entry for principal host/daffodil.mit.edu@ATHENA.MIT.EDU with kvno 2, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab.
- kadmin:
-
+ kadmin: ktadd -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin kadmin/changepw
+ kadmin: Entry for principal kadmin/admin@ATHENA.MIT.EDU with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
+ kadmin:
- kadmin: ktadd -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin kadmin/changepw
- kadmin: Entry for principal kadmin/admin@ATHENA.MIT.EDU with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
- kadmin:
-
Removing principals from keytabs
---------------------------------
-To remove a principal from an existing keytab, use the *kadmin* **ktremove** command.
+To remove a principal from an existing keytab, use the *kadmin*
+**ktremove** command.
.. include:: ../admin_commands/kadmin_local.rst
:start-after: _ktremove:
:end-before: _ktremove_end:
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___appl_servers
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___appl_servers
Backups of secure hosts
-===========================
+=======================
-.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+.. note:: This document was copied from **Kerberos V5 System
+ Administrator's Guide** with minor changes. Currently it is
+ under review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is
+ greatly appreciated.
-When you back up a secure host, you should exclude the host's keytab file from the backup. If someone obtained a copy of the keytab from a backup, that person could make any host masquerade as the host whose keytab was compromised. This could be particularly dangerous if the compromised keytab was from one of your KDCs. If the machine has a disk crash and the keytab file is lost, it is easy to generate another keytab file. (See :ref:`add_princ_kt`.) If you are unable to exclude particular files from backups, you should ensure that the backups are kept as secure as the host's root password.
+When you back up a secure host, you should exclude the host's keytab
+file from the backup. If someone obtained a copy of the keytab from a
+backup, that person could make any host masquerade as the host whose
+keytab was compromised. This could be particularly dangerous if the
+compromised keytab was from one of your KDCs. If the machine has a
+disk crash and the keytab file is lost, it is easy to generate another
+keytab file. (See :ref:`add_princ_kt`.) If you are unable to exclude
+particular files from backups, you should ensure that the backups are
+kept as secure as the host's root password.
Backing up the Kerberos database
---------------------------------------
-
-As with any file, it is possible that your Kerberos database could become corrupted. If this happens on one of the slave KDCs, you might never notice, since the next automatic propagation of the database would install a fresh copy. However, if it happens to the master KDC, the corrupted database would be propagated to all of the slaves during the next propagation. For this reason, MIT recommends that you back up your Kerberos database regularly. Because the master KDC is continuously dumping the database to a file in order to propagate it to the slave KDCs, it is a simple matter to have a cron job periodically copy the dump file to a secure machine elsewhere on your network. (Of course, it is important to make the host where these backups are stored as secure as your KDCs, and to encrypt its transmission across your network.) Then if your database becomes corrupted, you can load the most recent dump onto the master KDC. (See :ref:`restore_from_dump`.)
-
------------------------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___backup_secure_hosts
-
+--------------------------------
+
+As with any file, it is possible that your Kerberos database could
+become corrupted. If this happens on one of the slave KDCs, you might
+never notice, since the next automatic propagation of the database
+would install a fresh copy. However, if it happens to the master KDC,
+the corrupted database would be propagated to all of the slaves during
+the next propagation. For this reason, MIT recommends that you back
+up your Kerberos database regularly. Because the master KDC is
+continuously dumping the database to a file in order to propagate it
+to the slave KDCs, it is a simple matter to have a cron job
+periodically copy the dump file to a secure machine elsewhere on your
+network. (Of course, it is important to make the host where these
+backups are stored as secure as your KDCs, and to encrypt its
+transmission across your network.) Then if your database becomes
+corrupted, you can load the most recent dump onto the master KDC.
+(See :ref:`restore_from_dump`.)
+
+
+Feedback
+--------
+
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___backup_secure_hosts
.. _Supported_Encryption_Types_and_Salts:
Supported encryption types and salts
-======================================
+====================================
-Supported encryption types
--------------------------------------
+Supported encryption types
+--------------------------
-Any tag in the configuration files which requires a list of encryption types can be set to some combination of the following strings. Encryption types marked as "weak" are available for compatibility but not recommended for use.
+Any tag in the configuration files which requires a list of encryption
+types can be set to some combination of the following strings.
+Encryption types marked as "weak" are available for compatibility but
+not recommended for use.
==================================================== =========================================================
des-cbc-crc DES cbc mode with CRC-32 (weak)
des3-cbc-raw Triple DES cbc mode raw (weak)
des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd Triple DES cbc mode with HMAC/sha1
des-hmac-sha1 DES with HMAC/sha1 (weak)
-aes256-cts-hmac-sha1-96 aes256-cts AES-256 CTS mode with 96-bit SHA-1 HMAC
+aes256-cts-hmac-sha1-96 aes256-cts AES-256 CTS mode with 96-bit SHA-1 HMAC
aes128-cts-hmac-sha1-96 aes128-cts AES-128 CTS mode with 96-bit SHA-1 HMAC
arcfour-hmac rc4-hmac arcfour-hmac-md5 RC4 with HMAC/MD5
arcfour-hmac-exp rc4-hmac-exp arcfour-hmac-md5-exp Exportable RC4 with HMAC/MD5 (weak)
des The DES family: des-cbc-crc, des-cbc-md5, and des-cbc-md4 (weak)
des3 The triple DES family: des3-cbc-sha1
aes The AES family: aes256-cts-hmac-sha1-96 and aes128-cts-hmac-sha1-96
-rc4 The RC4 family: arcfour-hmac
+rc4 The RC4 family: arcfour-hmac
==================================================== =========================================================
-The string **DEFAULT** can be used to refer to the default set of types for the variable in question. Types or families can be removed from the current list by prefixing them with a minus sign ("-"). Types or families can be prefixed with a plus sign ("+") for symmetry; it has the same meaning as just listing the type or family. For example, **"DEFAULT -des"** would be the default set of encryption types with DES types removed, and **"des3 DEFAULT"** would be the default set of encryption types with triple DES types moved to the front.
+The string **DEFAULT** can be used to refer to the default set of
+types for the variable in question. Types or families can be removed
+from the current list by prefixing them with a minus sign ("-").
+Types or families can be prefixed with a plus sign ("+") for symmetry;
+it has the same meaning as just listing the type or family. For
+example, "``DEFAULT -des``" would be the default set of encryption
+types with DES types removed, and "``des3 DEFAULT``" would be the
+default set of encryption types with triple DES types moved to the
+front.
+
+While **aes128-cts** and **aes256-cts** are supported for all Kerberos
+operations, they are not supported by older versions of our GSSAPI
+implementation (krb5-1.3.1 and earlier).
+
+By default, AES is enabled in 1.9 release. Sites wishing to use AES
+encryption types on their KDCs need to be careful not to give GSSAPI
+services AES keys if the servers have not been updated. If older
+GSSAPI services are given AES keys, then services may fail when
+clients supporting AES for GSSAPI are used. Sites may wish to use AES
+for user keys and for the ticket granting ticket key, although doing
+so requires specifying what encryption types are used as each
+principal is created.
+
+If all GSSAPI-based services have been updated before or with the KDC,
+this is not an issue.
-While *aes128-cts* and *aes256-cts* are supported for all Kerberos operations, they are not supported by older versions of our GSSAPI implementation (krb5-1.3.1 and earlier).
-
-By default, AES is enabled in 1.9 release. Sites wishing to use AES encryption types on their KDCs need to be careful not to give GSSAPI services AES keys if the servers have not been updated. If older GSSAPI services are given AES keys, then services may fail when clients supporting AES for GSSAPI are used. Sites may wish to use AES for user keys and for the ticket granting ticket key, although doing so requires specifying what encryption types are used as each principal is created.
-
-If all GSSAPI-based services have been updated before or with the KDC, this is not an issue.
Salts
--------------
+-----
-Your Kerberos key is derived from your password. To ensure that people who happen to pick the same password do not have the same key, Kerberos 5 incorporates more information into the key using something called a salt. The supported values for salts are as follows.
+Your Kerberos key is derived from your password. To ensure that
+people who happen to pick the same password do not have the same key,
+Kerberos 5 incorporates more information into the key using something
+called a salt. The supported values for salts are as follows.
================= ============================================
normal default for Kerberos Version 5
================= ============================================
---------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_files
-
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___conf_files
Configuration Files
-=========================
-
-.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+===================
+.. note:: This document was copied from **Kerberos V5 System
+ Administrator's Guide** with minor changes. Currently it is
+ under review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is greatly
+ appreciated.
.. toctree::
:maxdepth: 2
krb5_conf.rst
kdc_conf.rst
---------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_files
-
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___conf_files
.. _kdc.conf:
kdc.conf
-==============
+========
+
+The kdc.conf file contains KDC configuration information, including
+defaults used when issuing Kerberos tickets. Normally, you should
+install your kdc.conf file in the directory
+``/usr/local/var/krb5kdc``. You can override the default location by
+setting the environment variable KRB5_KDC_PROFILE.
-The kdc.conf file contains KDC configuration information, including defaults
-used when issuing Kerberos tickets. Normally, you should install your kdc.conf
-file in the directory */usr/local/var/krb5kdc*.
-You can override the default location by setting the environment variable
-*KRB5_KDC_PROFILE*.
Structure
---------------
+---------
The kdc.conf file is set up in the same format as the :ref:`krb5.conf` file.
+
Sections
--------------
+---------
-The kdc.conf file may contain any or all of the following three sections:
+The kdc.conf file may contain any or all of the following three
+sections:
==================== ================================
:ref:`kdcdefaults` Contains default values for overall behavior of the KDC.
:ref:`kdc_realms` Contains subsections keyed by Kerberos realm names. Each subsection describes realm-specific information, including where to find the Kerberos servers for that realm.
-:ref:`kdc_logging` Contains relations which determine how Kerberos programs are to perform logging.
+:ref:`kdc_logging` Contains relations which determine how Kerberos programs are to perform logging.
==================== ================================
.. _kdcdefaults:
-**[kdcdefaults]**
-~~~~~~~~~~~~~~~~~~~~~~~
+[kdcdefaults]
+~~~~~~~~~~~~~
The following relation is defined in the [kdcdefaults] section:
**host_based_services**
- This relation lists the services that will get host-based referral processing
- even if the server principal is not marked as host-based by the client.
+ This relation lists the services that will get host-based referral
+ processing even if the server principal is not marked as
+ host-based by the client.
+
**kdc_max_dgram_reply_size**
- Specifies the maximum packet size that can be sent over UDP.
- The default value is 4096 bytes.
+ Specifies the maximum packet size that can be sent over UDP. The
+ default value is 4096 bytes.
+
**kdc_ports**
- This relation lists the ports on which the Kerberos server should listen
- for UDP requests by default. This list is a comma separated list of integers.
- If this relation is not specified, the compiled-in default is 88,750,
- the first being the assigned Kerberos port and the second which was used
- by Kerberos V4.
+ This relation lists the ports on which the Kerberos server should
+ listen for UDP requests by default. This list is a comma
+ separated list of integers. If this relation is not specified,
+ the compiled-in default is ``88,750``, the first being the
+ assigned Kerberos port and the second which was used by Kerberos
+ V4.
+
**kdc_tcp_ports**
- This relation lists the ports on which the Kerberos server should listen
- for TCP connections by default. This list is a comma separated list of integers.
- If this relation is not specified, the compiled-in default is not
- to listen for TCP connections at all.
-
- If you wish to change this (which we do not recommend, because the current
- implementation has little protection against denial-of-service attacks),
- the standard port number assigned for Kerberos TCP traffic is port 88.
+ This relation lists the ports on which the Kerberos server should
+ listen for TCP connections by default. This list is a comma
+ separated list of integers. If this relation is not specified,
+ the compiled-in default is not to listen for TCP connections at
+ all.
+
+ If you wish to change this (which we do not recommend, because the
+ current implementation has little protection against
+ denial-of-service attacks), the standard port number assigned for
+ Kerberos TCP traffic is port 88.
+
**no_host_referral**
- This relation blocks the specified services from host-based referral processing,
- even if the client marks the server principal as host-based or the service
- is also listed in *host_based_services*. *no_host_referral* = \* will disable
+ This relation blocks the specified services from host-based
+ referral processing, even if the client marks the server principal
+ as host-based or the service is also listed in
+ **host_based_services**. ``no_host_referral = *`` will disable
referral processing altogether.
+
**restrict_anonymous_to_tgt**
- This flag determines the default value of *restrict_anonymous_to_tgt for realms*.
- The default value is false.
+ This flag determines the default value of
+ **restrict_anonymous_to_tgt** for realms. The default value is
+ false.
.. _kdc_realms:
-**[realms]**
-~~~~~~~~~~~~~~~
+[realms]
+~~~~~~~~
-Each tag in the [realms] section of the file names a Kerberos realm.
-The value of the tag is a subsection where the relations in that subsection
-define KDC parameters for that particular realm.
+Each tag in the [realms] section of the file names a Kerberos realm.
+The value of the tag is a subsection where the relations in that
+subsection define KDC parameters for that particular realm.
-For each realm, the following tags may be specified in the [realms] subsection:
+For each realm, the following tags may be specified in the [realms]
+subsection:
**acl_file**
- (String.) Location of the access control list (acl) file that
- kadmin uses to determine which principals are allowed which permissions
- on the database. The default is */usr/local/var/krb5kdc/kadm5.acl*.
+ (String.) Location of the access control list (acl) file that
+ kadmin uses to determine which principals are allowed which
+ permissions on the database. The default is
+ ``/usr/local/var/krb5kdc/kadm5.acl``.
+
**admin_keytab**
- (String.) Location of the keytab file that the legacy administration
- daemons kadmind4 and v5passwdd use to authenticate to the database.
- The default is */usr/local/var/krb5kdc/kadm5.keytab*.
+ (String.) Location of the keytab file that the legacy
+ administration daemons kadmind4 and v5passwdd use to authenticate
+ to the database. The default is
+ ``/usr/local/var/krb5kdc/kadm5.keytab``.
+
**database_name**
- This string specifies the location of the Kerberos database for this realm.
+ This string specifies the location of the Kerberos database for
+ this realm.
+
**default_principal_expiration**
- (Absolute time string.) Specifies the default expiration date of principals
- created in this realm. The default value for this tag is 0.
+ (Absolute time string.) Specifies the default expiration date of
+ principals created in this realm. The default value for this tag
+ is 0.
+
**default_principal_flags**
- (Flag string.) Specifies the default attributes of principals created
- in this realm. The format for this string is a comma-separated list of flags,
- with '+' before each flag that should be enabled and '-' before each flag
- that should be disabled. The default is *postdateable, forwardable, tgt-based,
- renewable, proxiable, dup-skey, allow-tickets*, and *service enabled*.
+ (Flag string.) Specifies the default attributes of principals
+ created in this realm. The format for this string is a
+ comma-separated list of flags, with '+' before each flag that
+ should be enabled and '-' before each flag that should be
+ disabled. The default is ``postdateable, forwardable, tgt-based,
+ renewable, proxiable, dup-skey, allow-tickets, service enabled``.
There are a number of possible flags:
- *allow-tickets*
- Enabling this flag means that the KDC will issue tickets for this principal.
- Disabling this flag essentially deactivates the principal within this realm.
- *dup-skey*
- Enabling this flag allows the principal to obtain a session key for another user,
- permitting user-to-user authentication for this principal.
- *forwardable*
- Enabling this flag allows the principal to obtain forwardable tickets.
- *hwauth*
- If this flag is enabled, then the principal is required to preauthenticate
- using a hardware device before receiving any tickets.
- *no-auth-data-required*
- Enabling this flag prvents PAC data from being added to the service tickets.
- *ok-as-delegate*
- If this flag is enabled, it hints the client that credentials can and
- should be delegated when authenticating to the service.
- *ok-to-auth-as-delegate*
+ **allow-tickets**
+ Enabling this flag means that the KDC will issue tickets for
+ this principal. Disabling this flag essentially deactivates
+ the principal within this realm.
+
+ **dup-skey**
+ Enabling this flag allows the principal to obtain a session
+ key for another user, permitting user-to-user authentication
+ for this principal.
+
+ **forwardable**
+ Enabling this flag allows the principal to obtain forwardable
+ tickets.
+
+ **hwauth**
+ If this flag is enabled, then the principal is required to
+ preauthenticate using a hardware device before receiving any
+ tickets.
+
+ **no-auth-data-required**
+ Enabling this flag prvents PAC data from being added to the
+ service tickets.
+
+ **ok-as-delegate**
+ If this flag is enabled, it hints the client that credentials
+ can and should be delegated when authenticating to the
+ service.
+
+ **ok-to-auth-as-delegate**
Enabling this flag allows the principal to use S4USelf ticket.
- *postdateable*
- Enabling this flag allows the principal to obtain postdateable tickets.
- *preauth*
- If this flag is enabled on a client principal, then that principal
- is required to preauthenticate to the KDC before receiving any tickets.
- On a service principal, enabling this flag means that service tickets
- for this principal will only be issued to clients with a TGT that has
- the preauthenticated ticket set.
- *proxiable*
- Enabling this flag allows the principal to obtain proxy tickets.
- *pwchange*
- Enabling this flag forces a password change for this principal.
- *pwservice*
- If this flag is enabled, it marks this principal as a password change service.
- This should only be used in special cases, for example,
- if a user's password has expired, then the user has to get tickets
- for that principal without going through the normal password authentication
- in order to be able to change the password.
- *renewable*
- Enabling this flag allows the principal to obtain renewable tickets.
- *service*
- Enabling this flag allows the the KDC to issue service tickets for this principal.
- *tgt-based*
+
+ **postdateable**
+ Enabling this flag allows the principal to obtain postdateable
+ tickets.
+
+ **preauth**
+ If this flag is enabled on a client principal, then that
+ principal is required to preauthenticate to the KDC before
+ receiving any tickets. On a service principal, enabling this
+ flag means that service tickets for this principal will only
+ be issued to clients with a TGT that has the preauthenticated
+ ticket set.
+
+ **proxiable**
+ Enabling this flag allows the principal to obtain proxy
+ tickets.
+
+ **pwchange**
+ Enabling this flag forces a password change for this
+ principal.
+
+ **pwservice**
+ If this flag is enabled, it marks this principal as a password
+ change service. This should only be used in special cases,
+ for example, if a user's password has expired, then the user
+ has to get tickets for that principal without going through
+ the normal password authentication in order to be able to
+ change the password.
+
+ **renewable**
+ Enabling this flag allows the principal to obtain renewable
+ tickets.
+
+ **service**
+ Enabling this flag allows the the KDC to issue service tickets
+ for this principal.
+
+ **tgt-based**
Enabling this flag allows a principal to obtain tickets based
- on a ticket-granting-ticket, rather than repeating the authentication
- process that was used to obtain the TGT.
+ on a ticket-granting-ticket, rather than repeating the
+ authentication process that was used to obtain the TGT.
+
**dict_file**
- (String.) Location of the dictionary file containing strings that
- are not allowed as passwords. If none is specified or if there is
- no policy assigned to the principal, no dictionary checks of passwords
- will be performed.
+ (String.) Location of the dictionary file containing strings that
+ are not allowed as passwords. If none is specified or if there is
+ no policy assigned to the principal, no dictionary checks of
+ passwords will be performed.
+
**host_based_services**
- (Whitespace- or comma-separated list) This relation lists the services
- that will get host-based referral processing even if the server principal
- is not marked as host-based by the client.
+ (Whitespace- or comma-separated list.) This relation lists the
+ services that will get host-based referral processing even if the
+ server principal is not marked as host-based by the client.
+
**iprop_enable**
This boolean ("true" or "false") specifies whether incremental database
propagation is enabled. The default is "false".
+
**iprop_master_ulogsize**
- This numeric value specifies the maximum number of log entries to be
- retained for incremental propagation.
- The maximum value is 2500; default is 1000.
+ This numeric value specifies the maximum number of log entries to
+ be retained for incremental propagation. The maximum value is
+ 2500; default is 1000.
+
**iprop_slave_poll**
- This delta time string specfies how often the slave KDC polls for new
- updates from the master. Default is "2m" (that is, two minutes).
+ This delta time string specfies how often the slave KDC polls for
+ new updates from the master. Default is ``2m`` (that is, two
+ minutes).
+
**iprop_port**
- (Port number.) This specifies the port number to be used for incremental
- propagation. This is required in both master and slave configuration files.
+ (Port number.) This specifies the port number to be used for
+ incremental propagation. This is required in both master and
+ slave configuration files.
+
**iprop_logfile**
- (File name) This specifies where the update log file for the realm database
- is to be stored. The default is to use the *database_name* entry from the
- realms section of the krb5 config file, with *.ulog* appended.
- (NOTE: If *database_name* isn't specified in the realms section,
- perhaps because the LDAP database back end is being used, or the file name
- is specified in the *dbmodules* section, then the hard-coded default for
- *database_name* is used. Determination of the *iprop_logfile* default value
- will not use values from the *dbmodules* section.)
+ (File name.) This specifies where the update log file for the
+ realm database is to be stored. The default is to use the
+ **database_name** entry from the realms section of the krb5 config
+ file, with ``.ulog`` appended. (NOTE: If **database_name** isn't
+ specified in the realms section, perhaps because the LDAP database
+ back end is being used, or the file name is specified in the
+ [dbmodules] section, then the hard-coded default for
+ **database_name** is used. Determination of the **iprop_logfile**
+ default value will not use values from the [dbmodules] section.)
+
**kadmind_port**
- (Port number.) Specifies the port on which the kadmind daemon is to listen
- for this realm. The assigned port for kadmind is 749.
+ (Port number.) Specifies the port on which the kadmind daemon is
+ to listen for this realm. The assigned port for kadmind is 749.
+
**key_stash_file**
- (String.) Specifies the location where the master key has been stored
- (via kdb5_util stash). The default is /usr/local/var/krb5kdc/.k5.REALM,
- where REALM is the Kerberos realm.
+ (String.) Specifies the location where the master key has been
+ stored (via kdb5_util stash). The default is
+ /usr/local/var/krb5kdc/.k5.REALM, where REALM is the Kerberos
+ realm.
+
**kdc_ports**
- (String.) Specifies the list of ports that the KDC is to listen to for
- UDP requests for this realm. By default, the value of kdc_ports as specified
- in the [kdcdefaults] section is used.
+ (String.) Specifies the list of ports that the KDC is to listen
+ to for UDP requests for this realm. By default, the value of
+ **kdc_ports** as specified in the [kdcdefaults] section is used.
+
**kdc_tcp_ports**
- (String.) Specifies the list of ports that the KDC is to listen to for TCP
- requests for this realm. By default, the value of kdc_tcp_ports as specified
- in the [kdcdefaults] section is used.
+ (String.) Specifies the list of ports that the KDC is to listen
+ to for TCP requests for this realm. By default, the value of
+ **kdc_tcp_ports** as specified in the [kdcdefaults] section is
+ used.
+
**master_key_name**
- (String.) Specifies the name of the principal associated with the master key.
- The default is K/M.
+ (String.) Specifies the name of the principal associated with the
+ master key. The default is ``K/M``.
+
**master_key_type**
- (Key type string.) Specifies the master key's key type.
- The default value for this is des3-cbc-sha1. For a list of all possible values,
- see :ref:`Supported_Encryption_Types_and_Salts`.
+ (Key type string.) Specifies the master key's key type. The
+ default value for this is ``des3-cbc-sha1``. For a list of all
+ possible values, see :ref:`Supported_Encryption_Types_and_Salts`.
+
**max_life**
- (Delta time string.) Specifies the maximum time period for which a ticket
- may be valid in this realm. The default value is 24 hours.
+ (Delta time string.) Specifies the maximum time period for which
+ a ticket may be valid in this realm. The default value is 24
+ hours.
+
**max_renewable_life**
- (Delta time string.) Specifies the maximum time period during which a valid
- ticket may be renewed in this realm. The default value is 0.
+ (Delta time string.) Specifies the maximum time period during
+ which a valid ticket may be renewed in this realm. The default
+ value is 0.
+
**no_host_referral**
- (Whitespace- or comma-separated list) This relation blocks the specified
- services from host-based referral processing, even if the client marks
- the server principal as host-based or the service is also listed in
- *host_based_services*.
- *no_host_referral* = \* will disable referral processing altogether.
+ (Whitespace- or comma-separated list.) This relation blocks the
+ specified services from host-based referral processing, even if
+ the client marks the server principal as host-based or the service
+ is also listed in **host_based_services**. ``no_host_referral =
+ *`` will disable referral processing altogether.
+
**reject_bad_transit**
- A boolean value (true, false). If set to true, the KDC will check the list
- of transited realms for cross-realm tickets against the transit path
- computed from the realm names and the capaths section of its krb5.conf file;
- if the path in the ticket to be issued contains any realms not in the
- computed path, the ticket will not be issued, and an error will be returned
- to the client instead. If this value is set to false, such tickets will be
- issued anyways, and it will be left up to the application server to validate
- the realm transit path.
-
- If the disable-transited-check flag is set in the incoming request,
- this check is not performed at all. Having the reject_bad_transit option
- will cause such ticket requests to be rejected always.
-
- This transit path checking and config file option currently apply only to TGS requests.
-
- This is a per-realm option so that multiple-realm KDCs may control it
- separately for each realm, in case (for example) one realm has had the
- software on its application servers updated but another has not.
-
- This option defaults to true.
+ A boolean value (true, false). If set to true, the KDC will check
+ the list of transited realms for cross-realm tickets against the
+ transit path computed from the realm names and the capaths section
+ of its krb5.conf file; if the path in the ticket to be issued
+ contains any realms not in the computed path, the ticket will not
+ be issued, and an error will be returned to the client instead.
+ If this value is set to false, such tickets will be issued
+ anyways, and it will be left up to the application server to
+ validate the realm transit path.
+
+ If the disable-transited-check flag is set in the incoming
+ request, this check is not performed at all. Having the
+ **reject_bad_transit** option will cause such ticket requests to
+ be rejected always.
+
+ This transit path checking and config file option currently apply
+ only to TGS requests.
+
+ This is a per-realm option so that multiple-realm KDCs may control
+ it separately for each realm, in case (for example) one realm has
+ had the software on its application servers updated but another
+ has not.
+
+ This option defaults to true.
+
**restrict_anonymous_to_tgt**
- A boolean value (true, false). If set to true, the KDC will reject ticket
- requests from anonymous principals to service principals other than
- the realm's ticket-granting service. This option allows anonymous PKINIT
- to be enabled for use as FAST armor tickets without allowing anonymous
- authentication to services. By default, the value of restrict_anonymous_to_tgt
- as specified in the [kdcdefaults] section is used.
-**supported_enctypes**
- List of *key:salt* strings. Specifies the default key/salt combinations
- of principals for this realm. Any principals created through kadmin will
- have keys of these types.
- The default value for this tag is aes256-cts-hmac-sha1-96:normal
- aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal arcfour-hmac-md5:normal.
- For lists of possible values, see :ref:`Supported_Encryption_Types_and_Salts`
+ A boolean value (true, false). If set to true, the KDC will
+ reject ticket requests from anonymous principals to service
+ principals other than the realm's ticket-granting service. This
+ option allows anonymous PKINIT to be enabled for use as FAST armor
+ tickets without allowing anonymous authentication to services. By
+ default, the value of **restrict_anonymous_to_tgt** as specified
+ in the [kdcdefaults] section is used.
+**supported_enctypes**
+ List of *key*:*salt* strings. Specifies the default key/salt
+ combinations of principals for this realm. Any principals created
+ through kadmin will have keys of these types. The default value
+ for this tag is ``aes256-cts-hmac-sha1-96:normal
+ aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal
+ arcfour-hmac-md5:normal``. For lists of possible values, see
+ :ref:`Supported_Encryption_Types_and_Salts`
.. _kdc_logging:
-**[logging]**
-~~~~~~~~~~~~~~~~~~~~
+[logging]
+~~~~~~~~~
-See :ref:`logging` section in :ref:`krb5.conf`
+See :ref:`logging` section in :ref:`krb5.conf`
PKINIT options
----------------
-
-.. note:: The following are pkinit-specific options. Note that these values
- may be specified in [kdcdefaults] as global defaults, or within
- a realm-specific subsection of [realms]. Also note that
- a realm-specific value over-rides, does not add to, a generic
- [kdcdefaults] specification. The search order is:
-
- 1. realm-specific subsection of [realms]
+--------------
- [realms]
- EXAMPLE.COM = {
- pkinit_anchors = FILE\:/usr/local/example.com.crt
+.. note:: The following are pkinit-specific options. Note that these
+ values may be specified in [kdcdefaults] as global defaults,
+ or within a realm-specific subsection of [realms]. Also
+ note that a realm-specific value over-rides, does not add
+ to, a generic [kdcdefaults] specification. The search order
+ is:
- }
-
+1. realm-specific subsection of [realms], ::
- 2. generic value in the [kdcdefaults] section.
+ [realms]
+ EXAMPLE.COM = {
+ pkinit_anchors = FILE\:/usr/local/example.com.crt
+ }
- [kdcdefaults]
- pkinit_anchors = DIR\:/usr/local/generic_trusted_cas/
-
+2. generic value in the [kdcdefaults] section. ::
+ [kdcdefaults]
+ pkinit_anchors = DIR\:/usr/local/generic_trusted_cas/
-For information about the syntax of some of these options, see pkinit identity syntax.
+For information about the syntax of some of these options, see pkinit
+identity syntax.
**pkinit_anchors**
- Specifies the location of trusted anchor (root) certificates which the KDC
- trusts to sign client certificates. This option is required if pkinit is
- to be supported by the KDC. This option may be specified multiple times.
+ Specifies the location of trusted anchor (root) certificates which
+ the KDC trusts to sign client certificates. This option is
+ required if pkinit is to be supported by the KDC. This option may
+ be specified multiple times.
**pkinit_dh_min_bits**
- Specifies the minimum number of bits the KDC is willing to accept for
- a client's Diffie-Hellman key. The default is 2048.
+ Specifies the minimum number of bits the KDC is willing to accept
+ for a client's Diffie-Hellman key. The default is 2048.
**pkinit_allow_upn**
- Specifies that the KDC is willing to accept client certificates with
- the Microsoft UserPrincipalName (UPN) Subject Alternative Name (SAN).
- This means the KDC accepts the binding of the UPN in the certificate
- to the Kerberos principal name.
+ Specifies that the KDC is willing to accept client certificates
+ with the Microsoft UserPrincipalName (UPN) Subject Alternative
+ Name (SAN). This means the KDC accepts the binding of the UPN in
+ the certificate to the Kerberos principal name.
- The default is *false*.
+ The default is false.
- Without this option, the KDC will only accept certificates with the
- *id-pkinit-san* as defined in :rfc:`4556`. There is currently no option
- to disable SAN checking in the KDC.
+ Without this option, the KDC will only accept certificates with
+ the id-pkinit-san as defined in :rfc:`4556`. There is currently
+ no option to disable SAN checking in the KDC.
**pkinit_eku_checking**
- This option specifies what Extended Key Usage (EKU) values the KDC is
- willing to accept in client certificates. The values recognized in
- the kdc.conf file are:
-
- *kpClientAuth*
- This is the default value and specifies that client certificates
- must have the id-pkinit-KPClientAuth EKU as defined in :rfc:`4556`.
- *scLogin*
- If scLogin is specified, client certificates with
- the Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be accepted.
- *none*
- If none is specified, then client certificates will not be checked
- to verify they have an acceptable EKU. The use of this option
- is not recommended.
+ This option specifies what Extended Key Usage (EKU) values the KDC
+ is willing to accept in client certificates. The values
+ recognized in the kdc.conf file are:
+
+ **kpClientAuth**
+ This is the default value and specifies that client
+ certificates must have the id-pkinit-KPClientAuth EKU as
+ defined in :rfc:`4556`.
+
+ **scLogin**
+ If scLogin is specified, client certificates with the
+ Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be
+ accepted.
+
+ **none**
+ If none is specified, then client certificates will not be
+ checked to verify they have an acceptable EKU. The use of
+ this option is not recommended.
**pkinit_identity**
Specifies the location of the KDC's X.509 identity information.
Specifies the location of the KDC's OCSP.
**pkinit_mapping_file**
- Specifies the name of the ACL pkinit mapping file.
- This file maps principals to the certificates that they can use.
-
+ Specifies the name of the ACL pkinit mapping file. This file maps
+ principals to the certificates that they can use.
+
**pkinit_pool**
- Specifies the location of intermediate certificates which may be used by
- the KDC to complete the trust chain between a client's certificate and
- a trusted anchor. This option may be specified multiple times.
+ Specifies the location of intermediate certificates which may be
+ used by the KDC to complete the trust chain between a client's
+ certificate and a trusted anchor. This option may be specified
+ multiple times.
**pkinit_revoke**
- Specifies the location of Certificate Revocation List (CRL) information
- to be used by the KDC when verifying the validity of client certificates.
- This option may be specified multiple times.
+ Specifies the location of Certificate Revocation List (CRL)
+ information to be used by the KDC when verifying the validity of
+ client certificates. This option may be specified multiple times.
**pkinit_require_crl_checking**
- The default certificate verification process will always check the available
- revocation information to see if a certificate has been revoked.
- If a match is found for the certificate in a CRL, verification fails.
- If the certificate being verified is not listed in a CRL, or there is no
- CRL present for its issuing CA, and pkinit_require_crl_checking is false,
- then verification succeeds.
+ The default certificate verification process will always check the
+ available revocation information to see if a certificate has been
+ revoked. If a match is found for the certificate in a CRL,
+ verification fails. If the certificate being verified is not
+ listed in a CRL, or there is no CRL present for its issuing CA,
+ and **pkinit_require_crl_checking** is false, then verification
+ succeeds.
- However, if pkinit_require_crl_checking is true and there is no CRL
- information available for the issuing CA, then verification fails.
+ However, if **pkinit_require_crl_checking** is true and there is
+ no CRL information available for the issuing CA, then verification
+ fails.
- *pkinit_require_crl_checking* should be set to true if the policy is such
- that up-to-date CRLs must be present for every CA.
+ **pkinit_require_crl_checking** should be set to true if the
+ policy is such that up-to-date CRLs must be present for every CA.
Sample kdc.conf File
Here's an example of a kdc.conf file::
- [kdcdefaults]
- kdc_ports = 88
-
- [realms]
- ATHENA.MIT.EDU = {
- kadmind_port = 749
- max_life = 12h 0m 0s
- max_renewable_life = 7d 0h 0m 0s
- master_key_type = des3-hmac-sha1
- supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal des-cbc-crc:v4
- }
-
- [logging]
- kdc = FILE:/usr/local/var/krb5kdc/kdc.log
- admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log
-
+ [kdcdefaults]
+ kdc_ports = 88
+
+ [realms]
+ ATHENA.MIT.EDU = {
+ kadmind_port = 749
+ max_life = 12h 0m 0s
+ max_renewable_life = 7d 0h 0m 0s
+ master_key_type = des3-hmac-sha1
+ supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal des-cbc-crc:v4
+ }
+
+ [logging]
+ kdc = FILE:/usr/local/var/krb5kdc/kdc.log
+ admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log
+
FILES
------
-
-/usr/local/var/krb5kdc/kdc.conf
+
+``/usr/local/var/krb5kdc/kdc.conf``
+
SEE ALSO
---------
krb5.conf(5), krb5kdc(8)
-
-
.. _krb5.conf:
krb5.conf
-==========
+=========
+
+The krb5.conf file contains Kerberos configuration information,
+including the locations of KDCs and admin servers for the Kerberos
+realms of interest, defaults for the current realm and for Kerberos
+applications, and mappings of hostnames onto Kerberos realms.
+Normally, you should install your krb5.conf file in the directory
+``/etc``. You can override the default location by setting the
+environment variable KRB5_CONFIG.
-The *krb5.conf* file contains Kerberos configuration information, including
-the locations of KDCs and admin servers for the Kerberos realms of interest,
-defaults for the current realm and for Kerberos applications,
-and mappings of hostnames onto Kerberos realms.
-Normally, you should install your krb5.conf file in the directory /etc.
-You can override the default location by setting the environment variable KRB5_CONFIG.
Structure
---------
-The krb5.conf file is set up in the style of a Windows INI file.
-Sections are headed by the section name, in square brackets.
-Each section may contain zero or more relations, of the form::
+The krb5.conf file is set up in the style of a Windows INI file.
+Sections are headed by the section name, in square brackets. Each
+section may contain zero or more relations, of the form::
+
+ foo = bar
- foo = bar
-
-or ::
+or::
- fubar = {
- foo = bar
- baz = quux
- }
+ fubar = {
+ foo = bar
+ baz = quux
+ }
-Placing a '\*' at the end of a line indicates that this is the *final* value for the tag.
-This means that neither the remainder of this configuration file nor any other
-configuration file will be checked for any other values for this tag.
+Placing a '\*' at the end of a line indicates that this is the *final*
+value for the tag. This means that neither the remainder of this
+configuration file nor any other configuration file will be checked
+for any other values for this tag.
For example, if you have the following lines::
- foo = bar*
- foo = baz
-
+ foo = bar*
+ foo = baz
-then the second value of *foo* (baz) would never be read.
+then the second value of ``foo`` (``baz``) would never be read.
-The krb5.conf file can include other files using either of the following
-directives at the beginning of a line::
+The krb5.conf file can include other files using either of the
+following directives at the beginning of a line::
- include FILENAME
- includedir DIRNAME
-
+ include FILENAME
+ includedir DIRNAME
-*FILENAME* or *DIRNAME* should be an absolute path. The named file or directory
-must exist and be readable. Including a directory includes all files within
-the directory whose names consist solely of alphanumeric characters, dashes,
-or underscores. Included profile files are syntactically independent of their
-parents, so each included file must begin with a section header.
+*FILENAME* or *DIRNAME* should be an absolute path. The named file or
+directory must exist and be readable. Including a directory includes
+all files within the directory whose names consist solely of
+alphanumeric characters, dashes, or underscores. Included profile
+files are syntactically independent of their parents, so each included
+file must begin with a section header.
-The krb5.conf file can specify that configuration should be obtained from
-a loadable module, rather than the file itself, using the following directive
-at the beginning of a line before any section headers::
+The krb5.conf file can specify that configuration should be obtained
+from a loadable module, rather than the file itself, using the
+following directive at the beginning of a line before any section
+headers::
- module MODULEPATH:RESIDUAL
+ module MODULEPATH:RESIDUAL
+
+*MODULEPATH* may be relative to the library path of the krb5
+installation, or it may be an absolute path. *RESIDUAL* is provided
+to the module at initialization time. If krb5.conf uses a module
+directive, kdc.conf should also use one if it exists.
-*MODULEPATH* may be relative to the library path of the krb5 installation,
-or it may be an absolute path. *RESIDUAL* is provided to the module at
-initialization time.
-If krb5.conf uses a module directive, kdc.conf should also use one if it exists.
Sections
-----------
+--------
The krb5.conf file may contain any or all of the following sections:
============== =======================================================
-libdefaults_ Contains default values used by the Kerberos V5 library.
-realms_ Contains subsections keyed by Kerberos realm names. Each subsection describes realm-specific information, including where to find the Kerberos servers for that realm.
-domain_realm_ Contains relations which map domain names and subdomains onto Kerberos realm names. This is used by programs to determine what realm a host should be in, given its fully qualified domain name.
-logging_ Contains relations which determine how Kerberos programs are to perform logging.
-capaths_ Contains the authentication paths used with direct (nonhierarchical) cross-realm authentication. Entries in this section are used by the client to determine the intermediate realms which may be used in cross-realm authentication. It is also used by the end-service when checking the transited field for trusted intermediate realms.
-plugins_ Contains tags to register dynamic plugin modules and to turn modules on and off.
-appdefaults_ Contains default values that can be used by Kerberos V5 applications.
+libdefaults_ Contains default values used by the Kerberos V5 library.
+realms_ Contains subsections keyed by Kerberos realm names. Each subsection describes realm-specific information, including where to find the Kerberos servers for that realm.
+domain_realm_ Contains relations which map domain names and subdomains onto Kerberos realm names. This is used by programs to determine what realm a host should be in, given its fully qualified domain name.
+logging_ Contains relations which determine how Kerberos programs are to perform logging.
+capaths_ Contains the authentication paths used with direct (nonhierarchical) cross-realm authentication. Entries in this section are used by the client to determine the intermediate realms which may be used in cross-realm authentication. It is also used by the end-service when checking the transited field for trusted intermediate realms.
+plugins_ Contains tags to register dynamic plugin modules and to turn modules on and off.
+appdefaults_ Contains default values that can be used by Kerberos V5 applications.
============== =======================================================
.. _libdefaults:
-**[libdefaults]**
-~~~~~~~~~~~~~~~~~~~
+[libdefaults]
+~~~~~~~~~~~~~
The libdefaults section may contain any of the following relations:
**allow_weak_crypto**
- If this is set to 0 (for false), then weak encryption types will be
- filtered out of the previous three lists (as noted in
- :ref:`Supported_Encryption_Types_and_Salts`).
- The default value for this tag is false, which may cause authentication
- failures in existing Kerberos infrastructures that do not support strong crypto.
- Users in affected environments should set this tag to true until their
- infrastructure adopts stronger ciphers.
+ If this is set to 0 (for false), then weak encryption types will
+ be filtered out of the previous three lists (as noted in
+ :ref:`Supported_Encryption_Types_and_Salts`). The default value
+ for this tag is false, which may cause authentication failures in
+ existing Kerberos infrastructures that do not support strong
+ crypto. Users in affected environments should set this tag to
+ true until their infrastructure adopts stronger ciphers.
**ap_req_checksum_type**
- An integer which specifies the type of AP-REQ checksum to use in authenticators.
- This variable should be unset so the appropriate checksum for the encryption
- key in use will be used.
- This can be set if backward compatibility requires a specific checksum type.
- See the *kdc_req_checksum_type* configuration option for the possible values
- and their meanings.
+ An integer which specifies the type of AP-REQ checksum to use in
+ authenticators. This variable should be unset so the appropriate
+ checksum for the encryption key in use will be used. This can be
+ set if backward compatibility requires a specific checksum type.
+ See the **kdc_req_checksum_type** configuration option for the
+ possible values and their meanings.
**canonicalize**
- This flag indicates to the KDC that the client is prepared to receive
- a reply that contains a principal name other than the one requested.
- The client should expect, when sending names with the "canonicalize" KDC option,
- that names in the KDC's reply will be different than the name in the request.
- The default value for this flag is not set.
+ This flag indicates to the KDC that the client is prepared to
+ receive a reply that contains a principal name other than the one
+ requested. The client should expect, when sending names with the
+ "canonicalize" KDC option, that names in the KDC's reply will be
+ different than the name in the request. The default value for
+ this flag is not set.
**ccache_type**
- Use this parameter on systems which are DCE clients, to specify the type
- of cache to be created by kinit, or when forwarded tickets are received.
- DCE and Kerberos can share the cache, but some versions of DCE do not support
- the default cache as created by this version of Kerberos.
- Use a value of 1 on DCE 1.0.3a systems, and a value of 2 on DCE 1.1 systems.
- The default value is 4.
+ Use this parameter on systems which are DCE clients, to specify
+ the type of cache to be created by kinit, or when forwarded
+ tickets are received. DCE and Kerberos can share the cache, but
+ some versions of DCE do not support the default cache as created
+ by this version of Kerberos. Use a value of 1 on DCE 1.0.3a
+ systems, and a value of 2 on DCE 1.1 systems. The default value
+ is 4.
**clockskew**
- Sets the maximum allowable amount of clockskew in seconds that the library
- will tolerate before assuming that a Kerberos message is invalid.
- The default value is 300 seconds, or five minutes.
+ Sets the maximum allowable amount of clockskew in seconds that the
+ library will tolerate before assuming that a Kerberos message is
+ invalid. The default value is 300 seconds, or five minutes.
**default_keytab_name**
- This relation specifies the default keytab name to be used by application
- servers such as telnetd and rlogind. The default is */etc/krb5.keytab*.
+ This relation specifies the default keytab name to be used by
+ application servers such as telnetd and rlogind. The default is
+ ``/etc/krb5.keytab``.
**default_realm**
- Identifies the default Kerberos realm for the client.
- Set its value to your Kerberos realm.
- If this is not specified and the TXT record lookup is enabled
- (see :ref:`udns_label`), then that information will be used to determine
- the default realm. If this tag is not set in this configuration file and
- there is no DNS information found, then an error will be returned.
+ Identifies the default Kerberos realm for the client. Set its
+ value to your Kerberos realm. If this is not specified and the
+ TXT record lookup is enabled (see :ref:`udns_label`), then that
+ information will be used to determine the default realm. If this
+ tag is not set in this configuration file and there is no DNS
+ information found, then an error will be returned.
**default_tgs_enctypes**
- Identifies the supported list of session key encryption types that should be
- returned by the KDC. The list may be delimited with commas or whitespace.
- Kerberos supports many different encryption types, and support for more
- is planned in the future. (see :ref:`Supported_Encryption_Types_and_Salts`
- for a list of the accepted values for this tag).
- The default value is *aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
- des3-cbc-sha1 arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4*.
+ Identifies the supported list of session key encryption types that
+ should be returned by the KDC. The list may be delimited with
+ commas or whitespace. Kerberos supports many different encryption
+ types, and support for more is planned in the future. (see
+ :ref:`Supported_Encryption_Types_and_Salts` for a list of the
+ accepted values for this tag). The default value is
+ ``aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1
+ arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4``.
**default_tkt_enctypes**
- Identifies the supported list of session key encryption types that should be
- requested by the client. The format is the same as for default_tgs_enctypes.
- The default value for this tag is *aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
- des3-cbc-sha1 arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4*.
+ Identifies the supported list of session key encryption types that
+ should be requested by the client. The format is the same as for
+ default_tgs_enctypes. The default value for this tag is
+ ``aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1
+ arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4``.
**dns_fallback**
General flag controlling the use of DNS for Kerberos information.
- If both of the preceding options are specified, this option has no effect.
+ If both of the preceding options are specified, this option has no
+ effect.
**dns_lookup_kdc**
- Indicate whether DNS SRV records should be used to locate the KDCs and
- other servers for a realm, if they are not listed in the information for the realm.
- (Note that the admin_server entry must be in the file,
- because the DNS implementation for it is incomplete.)
-
- Enabling this option does open up a type of denial-of-service attack,
- if someone spoofs the DNS records and redirects you to another server.
- However, it's no worse than a denial of service, because that fake KDC
- will be unable to decode anything you send it
- (besides the initial ticket request, which has no encrypted data),
- and anything the fake KDC sends will not be trusted without verification
- using some secret that it won't know.
-
- If this option is not specified but dns_fallback is, that value will be used instead.
- If neither option is specified, the behavior depends on configure-time options;
- if none were given, the default is to enable this option.
- If the DNS support is not compiled in, this entry has no effect.
+ Indicate whether DNS SRV records should be used to locate the KDCs
+ and other servers for a realm, if they are not listed in the
+ information for the realm. (Note that the admin_server entry must
+ be in the file, because the DNS implementation for it is
+ incomplete.)
+
+ Enabling this option does open up a type of denial-of-service
+ attack, if someone spoofs the DNS records and redirects you to
+ another server. However, it's no worse than a denial of service,
+ because that fake KDC will be unable to decode anything you send
+ it (besides the initial ticket request, which has no encrypted
+ data), and anything the fake KDC sends will not be trusted without
+ verification using some secret that it won't know.
+
+ If this option is not specified but dns_fallback is, that value
+ will be used instead. If neither option is specified, the
+ behavior depends on configure-time options; if none were given,
+ the default is to enable this option. If the DNS support is not
+ compiled in, this entry has no effect.
**dns_lookup_realm**
- Indicate whether DNS TXT records should be used to determine
- the Kerberos realm of a host.
-
- Enabling this option may permit a redirection attack, where spoofed DNS
- replies persuade a client to authenticate to the wrong realm,
- when talking to the wrong host (either by spoofing yet more DNS records
- or by intercepting the net traffic). Depending on how the client software
- manages hostnames, however, it could already be vulnerable to such attacks.
- We are looking at possible ways to minimize or eliminate this exposure.
- For now, we encourage more adventurous sites to try using Secure DNS.
-
- If this option is not specified but dns_fallback is, that value will be used instead.
- If neither option is specified, the behavior depends on configure-time options;
- if none were given, the default is to disable this option.
- If the DNS support is not compiled in, this entry has no effect.
+ Indicate whether DNS TXT records should be used to determine the
+ Kerberos realm of a host.
+
+ Enabling this option may permit a redirection attack, where
+ spoofed DNS replies persuade a client to authenticate to the wrong
+ realm, when talking to the wrong host (either by spoofing yet more
+ DNS records or by intercepting the net traffic). Depending on how
+ the client software manages hostnames, however, it could already
+ be vulnerable to such attacks. We are looking at possible ways to
+ minimize or eliminate this exposure. For now, we encourage more
+ adventurous sites to try using Secure DNS.
+
+ If this option is not specified but dns_fallback is, that value
+ will be used instead. If neither option is specified, the
+ behavior depends on configure-time options; if none were given,
+ the default is to disable this option. If the DNS support is not
+ compiled in, this entry has no effect.
**extra_addresses**
- This allows a computer to use multiple local addresses, in order to allow
- Kerberos to work in a network that uses NATs.
- The addresses should be in a comma-separated list.
+ This allows a computer to use multiple local addresses, in order
+ to allow Kerberos to work in a network that uses NATs. The
+ addresses should be in a comma-separated list.
**forwardable**
- If this flag is set, initial tickets by default will be *forwardable*.
- The default value for this flag is not set.
+ If this flag is set, initial tickets by default will be
+ forwardable. The default value for this flag is not set.
**ignore_acceptor_hostname**
- When accepting GSSAPI or krb5 security contexts for host-based service
- principals, ignore any hostname passed by the calling application and
- allow any service principal present in the keytab which matches
- the service name and realm name (if given).
- This option can improve the administrative flexibility of server
- applications on multihomed hosts, but can compromise the security of
- virtual hosting environments. The default value is false.
+ When accepting GSSAPI or krb5 security contexts for host-based
+ service principals, ignore any hostname passed by the calling
+ application and allow any service principal present in the keytab
+ which matches the service name and realm name (if given). This
+ option can improve the administrative flexibility of server
+ applications on multihomed hosts, but can compromise the security
+ of virtual hosting environments. The default value is false.
**k5login_authoritative**
- If the value of this relation is true (the default), principals must be
- listed in a local user's k5login file to be granted login access,
- if a *.k5login* file exists. If the value of this relation is false,
- a principal may still be granted login access through other mechanisms
- even if a k5login file exists but does not list the principal.
+ If the value of this relation is true (the default), principals
+ must be listed in a local user's k5login file to be granted login
+ access, if a .k5login file exists. If the value of this relation
+ is false, a principal may still be granted login access through
+ other mechanisms even if a k5login file exists but does not list
+ the principal.
**k5login_directory**
- If set, the library will look for a local user's k5login file within
- the named directory, with a filename corresponding to the local username.
- If not set, the library will look for k5login files in the user's home
- directory, with the filename .k5login. For security reasons,
- *.k5login* files must be owned by the local user or by root.
+ If set, the library will look for a local user's k5login file
+ within the named directory, with a filename corresponding to the
+ local username. If not set, the library will look for k5login
+ files in the user's home directory, with the filename
+ .k5login. For security reasons, .k5login files must be owned by
+ the local user or by root.
**kdc_default_options**
- Default KDC options (Xored for multiple values) when requesting initial credentials.
- By default it is set to 0x00000010 (KDC_OPT_RENEWABLE_OK).
+ Default KDC options (Xored for multiple values) when requesting
+ initial credentials. By default it is set to 0x00000010
+ (KDC_OPT_RENEWABLE_OK).
**kdc_timesync**
If this is set to 1 (for true), then client machines will compute
the difference between their time and the time returned by the KDC
in the timestamps in the tickets and use this value to correct for
- an inaccurate system clock. This corrective factor is only used by
- the Kerberos library. The default is 1.
+ an inaccurate system clock. This corrective factor is only used
+ by the Kerberos library. The default is 1.
**kdc_req_checksum_type**
- An integer which specifies the type of checksum to use for
- the KDC requests for compatibility with DCE security servers
- which do not support the default RSA MD5 used by Kerberos V5.
- This applies to DCE 1.1 and earlier.
- Use a value of 2 to use the RSA MD4 instead.
- This value is only used for DES keys;
- other keys use the preferred checksum type for those keys.
+ An integer which specifies the type of checksum to use for the KDC
+ requests for compatibility with DCE security servers which do not
+ support the default RSA MD5 used by Kerberos V5. This applies to
+ DCE 1.1 and earlier. Use a value of 2 to use the RSA MD4 instead.
+ This value is only used for DES keys; other keys use the preferred
+ checksum type for those keys.
The possible values and their meanings are as follows.
8 RSA MD5 DES
9 NIST SHA
12 HMAC SHA1 DES3
- -138 Microsoft MD5 HMAC checksum type
+ -138 Microsoft MD5 HMAC checksum type
======== ===============================
-
**noaddresses**
- Setting this flag causes the initial Kerberos ticket to be addressless. The default for the flag is set.
+ Setting this flag causes the initial Kerberos ticket to be
+ addressless. The default for the flag is set.
**permitted_enctypes**
- Identifies all encryption types that are permitted for use in session key encryption.
- The default value for this tag is *aes256-cts-hmac-sha1-96
- aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5
- des-cbc-crc des-cbc-md5 des-cbc-md4*.
+ Identifies all encryption types that are permitted for use in
+ session key encryption. The default value for this tag is
+ ``aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1
+ arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4``.
**plugin_base_dir**
- If set, determines the base directory where krb5 plugins are located.
- The default value is the "krb5/plugins" subdirectory of the krb5 library directory.
-
+ If set, determines the base directory where krb5 plugins are
+ located. The default value is the ``krb5/plugins`` subdirectory
+ of the krb5 library directory.
**preferred_preauth_types**
This allows you to set the preferred preauthentication types which
- the client will attempt before others which may be advertised by a KDC.
- The default value for this setting is "17, 16, 15, 14",
+ the client will attempt before others which may be advertised by a
+ KDC. The default value for this setting is "17, 16, 15, 14",
which forces libkrb5 to attempt to use PKINIT if it is supported.
**proxiable**
If this flag is set, initial tickets by default will be proxiable.
- The default value for this flag is not set.
+ The default value for this flag is not set.
**rdns**
- If set to false, prevent the use of reverse DNS resolution when translating
- hostnames into service principal names. Defaults to true.
- Setting this flag to false is more secure, but may force users to exclusively
- use fully qualified domain names when authenticating to services.
+ If set to false, prevent the use of reverse DNS resolution when
+ translating hostnames into service principal names. Defaults to
+ true. Setting this flag to false is more secure, but may force
+ users to exclusively use fully qualified domain names when
+ authenticating to services.
**realm_try_domains**
- Indicate whether a host's domain components should be used to determine
- the Kerberos realm of the host. The value of this variable is
- an integer: -1 means not to search, 0 means to try the host's domain itself,
- 1 means to also try the domain's immediate parent, and so forth.
- The library's usual mechanism for locating Kerberos realms is used
- to determine whether a domain is a valid realm--which may involve consulting
- DNS if *dns_lookup_kdc* is set. The default is not to search domain components.
+ Indicate whether a host's domain components should be used to
+ determine the Kerberos realm of the host. The value of this
+ variable is an integer: -1 means not to search, 0 means to try the
+ host's domain itself, 1 means to also try the domain's immediate
+ parent, and so forth. The library's usual mechanism for locating
+ Kerberos realms is used to determine whether a domain is a valid
+ realm--which may involve consulting DNS if **dns_lookup_kdc** is
+ set. The default is not to search domain components.
**renew_lifetime**
- The value of this tag is the default renewable lifetime for initial tickets.
- The default value for the tag is 0.
+ The value of this tag is the default renewable lifetime for
+ initial tickets. The default value for the tag is 0.
**safe_checksum_type**
-
- An integer which specifies the type of checksum to use for the KRB-SAFE requests.
- By default it is set to 8 (RSA MD5 DES).
- For compatibility with applications linked against DCE version 1.1 or
- earlier Kerberos libraries, use a value of 3 to use the RSA MD4 DES instead.
- This field is ignored when its value is incompatible with the session key type.
- See the *kdc_req_checksum_type* configuration option for the possible values
- and their meanings.
+ An integer which specifies the type of checksum to use for the
+ KRB-SAFE requests. By default it is set to 8 (RSA MD5 DES). For
+ compatibility with applications linked against DCE version 1.1 or
+ earlier Kerberos libraries, use a value of 3 to use the RSA MD4
+ DES instead. This field is ignored when its value is incompatible
+ with the session key type. See the **kdc_req_checksum_type**
+ configuration option for the possible values and their meanings.
**ticket_lifetime**
The value of this tag is the default lifetime for initial tickets.
- The default value for the tag is 1 day.
+ The default value for the tag is 1 day.
**udp_preference_limit**
- When sending a message to the KDC, the library will try using TCP before UDP
- if the size of the message is above *udp_preference_list*.
- If the message is smaller than *udp_preference_list*,
- then UDP will be tried before TCP. Regardless of the size,
- both protocols will be tried if the first attempt fails.
+ When sending a message to the KDC, the library will try using TCP
+ before UDP if the size of the message is above
+ **udp_preference_list**. If the message is smaller than
+ **udp_preference_list**, then UDP will be tried before
+ TCP. Regardless of the size, both protocols will be tried if the
+ first attempt fails.
**verify_ap_req_nofail**
- If this flag is set, then an attempt to get initial credentials will fail
- if the client machine does not have a keytab.
- The default for the flag is not set.
+ If this flag is set, then an attempt to get initial credentials
+ will fail if the client machine does not have a keytab. The
+ default for the flag is not set.
+
.. _realms:
-**[realms]**
-~~~~~~~~~~~~~~~~~
+[realms]
+~~~~~~~~
-Each tag in the [realms] section of the file is the name of a Kerberos realm.
-The value of the tag is a subsection with relations that define the properties
-of that particular realm.
-For each realm, the following tags may be specified in the realm's subsection:
+Each tag in the [realms] section of the file is the name of a Kerberos
+realm. The value of the tag is a subsection with relations that
+define the properties of that particular realm. For each realm, the
+following tags may be specified in the realm's subsection:
**admin_server**
Identifies the host where the administration server is running.
- Typically, this is the master Kerberos server. This tag must be given
- a value in order to communicate with the kadmin server for the realm.
+ Typically, this is the master Kerberos server. This tag must be
+ given a value in order to communicate with the kadmin server for
+ the realm.
**auth_to_local**
- This tag allows you to set a general rule for mapping principal names
- to local user names. It will be used if there is not an explicit mapping
- for the principal name that is being translated. The possible values are:
+ This tag allows you to set a general rule for mapping principal
+ names to local user names. It will be used if there is not an
+ explicit mapping for the principal name that is being
+ translated. The possible values are:
- DB:filename
- The principal will be looked up in the database filename.
+ **DB:**\ *filename*
+ The principal will be looked up in the database *filename*.
Support for this is not currently compiled in by default.
- RULE:exp
- The local name will be formulated from exp.
-
- The format for exp is *[n:string](regexp)s/pattern/replacement/g*.
- The integer *n* indicates how many components the target principal should have.
- If this matches, then a string will be formed from string,
- substituting the realm of the principal for $0 and the n'th component
- of the principal for *$n*
- (e.g. if the principal was *johndoe/admin* then [2:$2$1foo] would
- result in the string "adminjohndoefoo"). If this string matches *regexp*,
- then the *s//[g]* substitution command will be run over the string.
- The optional *g* will cause the substitution to be global over the *string*,
- instead of replacing only the first match in the *string*.
-
- DEFAULT
- The principal name will be used as the local user name.
- If the principal has more than one component or is not in the default realm,
- this rule is not applicable and the conversion will fail.
+
+ **RULE:**\ *exp*
+ The local name will be formulated from *exp*.
+
+ The format for *exp* is **[**\ *n*\ **:**\ *string*\ **](**\
+ *regexp*\ **)s/**\ *pattern*\ **/**\ *replacement*\ **/g**.
+ The integer *n* indicates how many components the target
+ principal should have. If this matches, then a string will be
+ formed from *string*, substituting the realm of the principal
+ for ``$0`` and the *n*'th component of the principal for
+ ``$n`` (e.g. if the principal was ``johndoe/admin`` then
+ ``[2:$2$1foo]`` would result in the string
+ ``adminjohndoefoo``). If this string matches *regexp*, then
+ the ``s//[g]`` substitution command will be run over the
+ string. The optional **g** will cause the substitution to be
+ global over the *string*, instead of replacing only the first
+ match in the *string*.
+
+ **DEFAULT**
+ The principal name will be used as the local user name. If
+ the principal has more than one component or is not in the
+ default realm, this rule is not applicable and the conversion
+ will fail.
For example::
- [realms]
- ATHENA.MIT.EDU = {
- auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/
- auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$//
- auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/
- auto_to_local = DEFAULT
- }
-
-
- would result in any principal without *root* or *admin* as the second
- component to be translated with the default rule.
- A principal with a second component of *admin* will become its first component.
- *root* will be used as the local name for any principal with a second component of *root*.
- The exception to these two rules are any principals *johndoe*/\*,
- which will always get the local name *guest*.
+ [realms]
+ ATHENA.MIT.EDU = {
+ auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/
+ auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$//
+ auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/
+ auto_to_local = DEFAULT
+ }
+
+ would result in any principal without ``root`` or ``admin`` as the
+ second component to be translated with the default rule. A
+ principal with a second component of ``admin`` will become its
+ first component. ``root`` will be used as the local name for any
+ principal with a second component of ``root``. The exception to
+ these two rules are any principals ``johndoe/*``, which will
+ always get the local name ``guest``.
**auth_to_local_names**
- This subsection allows you to set explicit mappings from principal names
- to local user names. The tag is the mapping name, and the value
- is the corresponding local user name.
+ This subsection allows you to set explicit mappings from principal
+ names to local user names. The tag is the mapping name, and the
+ value is the corresponding local user name.
**database_module**
- This relation indicates the name of the configuration section under dbmodules_
- for database specific parameters used by the loadable database library.
+ This relation indicates the name of the configuration section
+ under dbmodules_ for database specific parameters used by the
+ loadable database library.
**default_domain**
- This tag is used for Kerberos 4 compatibility. Kerberos 4 does not require
- the entire hostname of a server to be in its principal like Kerberos 5 does.
- This tag provides the domain name needed to produce a full hostname when
- translating V4 principal names into V5 principal names. All servers in this
- realm are assumed to be in the domain given as the value of this tag.
+ This tag is used for Kerberos 4 compatibility. Kerberos 4 does not
+ require the entire hostname of a server to be in its principal
+ like Kerberos 5 does. This tag provides the domain name needed to
+ produce a full hostname when translating V4 principal names into
+ V5 principal names. All servers in this realm are assumed to be
+ in the domain given as the value of this tag.
**kdc**
- The name or address of a host running a KDC for that realm.
- An optional port number, separated from the hostname by a colon, may be included.
- If the name or address contains colons (for example, if it is an IPv6 address),
- enclose it in square brackets to distinguish the colon from a port separator.
- For your computer to be able to communicate with the KDC for each realm,
- this tag must be given a value in each realm subsection in the configuration file,
- or there must be DNS SRV records specifying the KDCs (see :ref:`udns_label`).
-
-**kpasswd_server**
+ The name or address of a host running a KDC for that realm. An
+ optional port number, separated from the hostname by a colon, may
+ be included. If the name or address contains colons (for example,
+ if it is an IPv6 address), enclose it in square brackets to
+ distinguish the colon from a port separator. For your computer to
+ be able to communicate with the KDC for each realm, this tag must
+ be given a value in each realm subsection in the configuration
+ file, or there must be DNS SRV records specifying the KDCs (see
+ :ref:`udns_label`).
+
+**kpasswd_server**
Points to the server where all the password changes are performed.
- If there is no such entry, the port 464 on the *admin_server* host will be tried.
-
-**krb524_server**
- Points to the server that does 524 conversions.
- If it is not mentioned, the krb524 port 4444 on the kdc will be tried.
+ If there is no such entry, the port 464 on the **admin_server**
+ host will be tried.
+
+**krb524_server**
+ Points to the server that does 524 conversions. If it is not
+ mentioned, the krb524 port 4444 on the kdc will be tried.
**master_kdc**
- Identifies the master KDC(s). Currently, this tag is used in only one case:
- If an attempt to get credentials fails because of an invalid password,
- the client software will attempt to contact the master KDC,
- in case the user's password has just been changed, and the updated database
- has not been propagated to the slave servers yet.
+ Identifies the master KDC(s). Currently, this tag is used in only
+ one case: If an attempt to get credentials fails because of an
+ invalid password, the client software will attempt to contact the
+ master KDC, in case the user's password has just been changed, and
+ the updated database has not been propagated to the slave servers
+ yet.
**v4_instance_convert**
- This subsection allows the administrator to configure exceptions to the
- *default_domain* mapping rule. It contains V4 instances (the tag name)
- which should be translated to some specific hostname (the tag value)
- as the second component in a Kerberos V5 principal name.
+ This subsection allows the administrator to configure exceptions
+ to the **default_domain** mapping rule. It contains V4 instances
+ (the tag name) which should be translated to some specific
+ hostname (the tag value) as the second component in a Kerberos V5
+ principal name.
**v4_realm**
- This relation is used by the krb524 library routines when converting
- a V5 principal name to a V4 principal name. It is used when the V4 realm name
- and the V5 realm name are not the same, but still share the same
- principal names and passwords. The tag value is the Kerberos V4 realm name.
+ This relation is used by the krb524 library routines when
+ converting a V5 principal name to a V4 principal name. It is used
+ when the V4 realm name and the V5 realm name are not the same, but
+ still share the same principal names and passwords. The tag value
+ is the Kerberos V4 realm name.
+
.. _domain_realm:
-**[domain_realm]**
-~~~~~~~~~~~~~~~~~~~~~
+[domain_realm]
+~~~~~~~~~~~~~~
-The [domain_realm] section provides a translation from a domain name or hostname
-to a Kerberos realm name. The tag name can be a host name, or a domain name,
-where domain names are indicated by a prefix of a period (.).
-The value of the relation is the Kerberos realm name for that particular
-host or domain. The Kerberos realm may be identified either in the realms_
-section or using DNS SRV records.
+The [domain_realm] section provides a translation from a domain name
+or hostname to a Kerberos realm name. The tag name can be a host
+name, or a domain name, where domain names are indicated by a prefix
+of a period (.). The value of the relation is the Kerberos realm name
+for that particular host or domain. The Kerberos realm may be
+identified either in the realms_ section or using DNS SRV records.
Host names and domain names should be in lower case.
-If no translation entry applies, the host's realm is considered to be the
-hostname's domain portion converted to upper case.
-For example, the following [domain_realm] section::
+If no translation entry applies, the host's realm is considered to be
+the hostname's domain portion converted to upper case. For example,
+the following [domain_realm] section::
- [domain_realm]
- crash.mit.edu = TEST.ATHENA.MIT.EDU
- .mit.edu = ATHENA.MIT.EDU
- mit.edu = ATHENA.MIT.EDU
- example.com = EXAMPLE.COM
-
+ [domain_realm]
+ crash.mit.edu = TEST.ATHENA.MIT.EDU
+ .mit.edu = ATHENA.MIT.EDU
+ mit.edu = ATHENA.MIT.EDU
+ example.com = EXAMPLE.COM
-maps the host with the *exact* name *crash.mit.edu* into the TEST.ATHENA.MIT.EDU realm.
-The period prefix in *.mit.edu* denotes that *all* systems in the *mit.edu*
-domain belong to ATHENA.MIT.EDU realm.
-Note the entries for the hosts *mit.edu* and *example.com*.
-Without these entries, these hosts would be mapped into the Kerberos realms
-EDU and COM, respectively.
+maps the host with the *exact* name ``crash.mit.edu`` into the
+TEST.ATHENA.MIT.EDU realm. The period prefix in ``.mit.edu`` denotes
+that *all* systems in the ``mit.edu`` domain belong to
+``ATHENA.MIT.EDU`` realm. Note the entries for the hosts ``mit.edu``
+and ``example.com``. Without these entries, these hosts would be
+mapped into the Kerberos realms EDU and COM, respectively.
.. _logging:
-**[logging]**
-~~~~~~~~~~~~~~~~~~~~~~~
+[logging]
+~~~~~~~~~
-The [logging] section indicates how a particular entity is to perform its logging.
-The relations in this section assign one or more values to the entity name.
-Currently, the following entities are used:
+The [logging] section indicates how a particular entity is to perform
+its logging. The relations in this section assign one or more values
+to the entity name. Currently, the following entities are used:
**admin_server**
- These entries specify how the administrative server is to perform its logging.
+ These entries specify how the administrative server is to perform
+ its logging.
+
**default**
- These entries specify how to perform logging in the absence of explicit
- specifications otherwise.
+ These entries specify how to perform logging in the absence of
+ explicit specifications otherwise.
+
**kdc**
- These entries specify how the KDC is to perform its logging.
+ These entries specify how the KDC is to perform its logging.
Values are of the following forms:
-| FILE=<filename>
-| FILE:<filename>
-
- This value causes the entity's logging messages to go to the specified file.
- If the = form is used, the file is overwritten.
- If the \: form is used, the file is appended to.
-
-STDERR
- This value causes the entity's logging messages to go to its standard error stream.
-CONSOLE
- This value causes the entity's logging messages to go to the console,
- if the system supports it.
-DEVICE=<devicename>
- This causes the entity's logging messages to go to the specified device.
-SYSLOG[:<severity>[:<facility>]]
+**FILE=**\ *filename* or **FILE:**\ *filename*
+ This value causes the entity's logging messages to go to the
+ *filename*. If the = form is used, the file is overwritten. If
+ the \: form is used, the file is appended to.
+
+**STDERR**
+ This value causes the entity's logging messages to go to its
+ standard error stream.
+
+**CONSOLE**
+ This value causes the entity's logging messages to go to the
+ console, if the system supports it.
+
+**DEVICE=**\ *<devicename>*
+ This causes the entity's logging messages to go to the specified
+ device.
+
+**SYSLOG**\ [\ **:**\ *severity*\ [\ **:**\ *facility*\ ]]
This causes the entity's logging messages to go to the system log.
- The severity argument specifies the default severity of system log messages.
- This may be any of the following severities supported by the syslog(3) call,
- minus the LOG\_ prefix: LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING,
- LOG_NOTICE, LOG_INFO, and LOG_DEBUG.
- For example, a value of CRIT would specify LOG_CRIT severity.
+ The severity argument specifies the default severity of system log
+ messages. This may be any of the following severities supported
+ by the syslog(3) call, minus the LOG\_ prefix: LOG_EMERG,
+ LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO,
+ and LOG_DEBUG. For example, a value of CRIT would specify
+ LOG_CRIT severity.
- The facility argument specifies the facility under which the messages are logged.
- This may be any of the following facilities supported by the syslog(3)
- call minus the LOG\_ prefix: LOG_KERN, LOG_USER, LOG_MAIL, LOG_DAEMON,
- LOG_AUTH, LOG_LPR, LOG_NEWS, LOG_UUCP, LOG_CRON, and LOG_LOCAL0 through LOG_LOCAL7.
+ The facility argument specifies the facility under which the
+ messages are logged. This may be any of the following facilities
+ supported by the syslog(3) call minus the LOG\_ prefix: LOG_KERN,
+ LOG_USER, LOG_MAIL, LOG_DAEMON, LOG_AUTH, LOG_LPR, LOG_NEWS,
+ LOG_UUCP, LOG_CRON, and LOG_LOCAL0 through LOG_LOCAL7.
- If no severity is specified, the default is ERR.
- If no facility is specified, the default is AUTH.
+ If no severity is specified, the default is ERR. If no facility
+ is specified, the default is AUTH.
-In the following example, the logging messages from the KDC will go to the console
-and to the system log under the facility LOG_DAEMON with default severity of LOG_INFO;
-and the logging messages from the administrative server will be appended
-to the file */var/adm/kadmin.log* and sent to the device */dev/tty04*.::
+In the following example, the logging messages from the KDC will go to
+the console and to the system log under the facility LOG_DAEMON with
+default severity of LOG_INFO; and the logging messages from the
+administrative server will be appended to the file
+``/var/adm/kadmin.log`` and sent to the device ``/dev/tty04``.::
+
+ [logging]
+ kdc = CONSOLE
+ kdc = SYSLOG:INFO:DAEMON
+ admin_server = FILE:/var/adm/kadmin.log
+ admin_server = DEVICE=/dev/tty04
- [logging]
- kdc = CONSOLE
- kdc = SYSLOG:INFO:DAEMON
- admin_server = FILE:/var/adm/kadmin.log
- admin_server = DEVICE=/dev/tty04
-
.. _capaths:
-**[capaths]**
-~~~~~~~~~~~~~~~~~~~~~~
-
-In order to perform direct (non-hierarchical) cross-realm authentication,
-a database is needed to construct the authentication paths between the realms.
-This section defines that database.
-
-A client will use this section to find the authentication path between
-its realm and the realm of the server. The server will use this section
-to verify the authentication path used by the client,
-by checking the transited field of the received ticket.
-
-There is a tag for each participating realm, and each tag has subtags
-for each of the realms. The value of the subtags is an intermediate realm
-which may participate in the cross-realm authentication.
-The subtags may be repeated if there is more then one intermediate realm.
-A value of "." means that the two realms share keys directly,
-and no intermediate realms should be allowed to participate.
-
-There are n**2 possible entries in this table, but only those entries which
-will be needed on the client or the server need to be present.
-The client needs a tag for its local realm, with subtags for all the realms
-of servers it will need to authenticate with.
-A server needs a tag for each realm of the clients it will serve.
-
-For example, *ANL.GOV, PNL.GOV*, and *NERSC.GOV* all wish to use the *ES.NET*
-realm as an intermediate realm. *ANL* has a sub realm of *TEST.ANL.GOV*
-which will authenticate with *NERSC.GOV* but not *PNL.GOV*.
-The [capaths] section for *ANL.GOV* systems would look like this::
-
- [capaths]
- ANL.GOV = {
- TEST.ANL.GOV = .
- PNL.GOV = ES.NET
- NERSC.GOV = ES.NET
- ES.NET = .
- }
- TEST.ANL.GOV = {
- ANL.GOV = .
- }
- PNL.GOV = {
- ANL.GOV = ES.NET
- }
- NERSC.GOV = {
- ANL.GOV = ES.NET
- }
- ES.NET = {
- ANL.GOV = .
- }
-
-
-The [capaths] section of the configuration file used on *NERSC.GOV* systems would look like this::
-
- [capaths]
- NERSC.GOV = {
- ANL.GOV = ES.NET
- TEST.ANL.GOV = ES.NET
- TEST.ANL.GOV = ANL.GOV
- PNL.GOV = ES.NET
- ES.NET = .
- }
- ANL.GOV = {
- NERSC.GOV = ES.NET
- }
- PNL.GOV = {
- NERSC.GOV = ES.NET
- }
- ES.NET = {
- NERSC.GOV = .
- }
- TEST.ANL.GOV = {
- NERSC.GOV = ANL.GOV
- NERSC.GOV = ES.NET
- }
-
-
-In the above examples, the ordering is not important, except when the same
-subtag name is used more then once.
-The client will use this to determine the path.
-(It is not important to the server, since the transited field is not sorted.)
-
-This feature is not currently supported by DCE.
-DCE security servers can be used with Kerberized clients and servers,
-but versions prior to DCE 1.1 did not fill in the transited field,
-and should be used with caution.
+[capaths]
+~~~~~~~~~
+
+In order to perform direct (non-hierarchical) cross-realm
+authentication, a database is needed to construct the authentication
+paths between the realms. This section defines that database.
+
+A client will use this section to find the authentication path between
+its realm and the realm of the server. The server will use this
+section to verify the authentication path used by the client, by
+checking the transited field of the received ticket.
+
+There is a tag for each participating realm, and each tag has subtags
+for each of the realms. The value of the subtags is an intermediate
+realm which may participate in the cross-realm authentication. The
+subtags may be repeated if there is more then one intermediate realm.
+A value of "." means that the two realms share keys directly, and no
+intermediate realms should be allowed to participate.
+
+There are n**2 possible entries in this table, but only those entries
+which will be needed on the client or the server need to be present.
+The client needs a tag for its local realm, with subtags for all the
+realms of servers it will need to authenticate with. A server needs a
+tag for each realm of the clients it will serve.
+
+For example, ``ANL.GOV``, ``PNL.GOV``, and ``NERSC.GOV`` all wish to
+use the ``ES.NET`` realm as an intermediate realm. ``ANL`` has a sub
+realm of ``TEST.ANL.GOV`` which will authenticate with ``NERSC.GOV``
+but not ``PNL.GOV``. The [capaths] section for ``ANL.GOV`` systems
+would look like this::
+
+ [capaths]
+ ANL.GOV = {
+ TEST.ANL.GOV = .
+ PNL.GOV = ES.NET
+ NERSC.GOV = ES.NET
+ ES.NET = .
+ }
+ TEST.ANL.GOV = {
+ ANL.GOV = .
+ }
+ PNL.GOV = {
+ ANL.GOV = ES.NET
+ }
+ NERSC.GOV = {
+ ANL.GOV = ES.NET
+ }
+ ES.NET = {
+ ANL.GOV = .
+ }
+
+The [capaths] section of the configuration file used on ``NERSC.GOV``
+systems would look like this::
+
+ [capaths]
+ NERSC.GOV = {
+ ANL.GOV = ES.NET
+ TEST.ANL.GOV = ES.NET
+ TEST.ANL.GOV = ANL.GOV
+ PNL.GOV = ES.NET
+ ES.NET = .
+ }
+ ANL.GOV = {
+ NERSC.GOV = ES.NET
+ }
+ PNL.GOV = {
+ NERSC.GOV = ES.NET
+ }
+ ES.NET = {
+ NERSC.GOV = .
+ }
+ TEST.ANL.GOV = {
+ NERSC.GOV = ANL.GOV
+ NERSC.GOV = ES.NET
+ }
+
+In the above examples, the ordering is not important, except when the
+same subtag name is used more then once. The client will use this to
+determine the path. (It is not important to the server, since the
+transited field is not sorted.)
+
+This feature is not currently supported by DCE. DCE security servers
+can be used with Kerberized clients and servers, but versions prior to
+DCE 1.1 did not fill in the transited field, and should be used with
+caution.
+
.. _dbdefaults:
-**[dbdefaults]**
-~~~~~~~~~~~~~~~~~~~~~~~~
+[dbdefaults]
+~~~~~~~~~~~~
-The [dbdefaults] section provides default values for the database specific parameters.
-It can also specify the configuration section under dbmodules_ section
-for database specific parameters used by the database library.
+The [dbdefaults] section provides default values for the database
+specific parameters. It can also specify the configuration section
+under dbmodules_ section for database specific parameters used by the
+database library.
The following tags are used in this section:
**database_module**
- This relation indicates the name of the configuration section under
- the dbmodules_ for database specific parameters used by the
- loadable database library.
+ This relation indicates the name of the configuration section
+ under the dbmodules_ for database specific parameters used by the
+ loadable database library.
**ldap_kerberos_container_dn**
- This LDAP specific tag indicates the DN of the container object where
- the realm objects will be located. This value is used if the container
- object is not mentioned in the configuration section under dbmodules_.
+ This LDAP specific tag indicates the DN of the container object
+ where the realm objects will be located. This value is used if
+ the container object is not mentioned in the configuration section
+ under dbmodules_.
**ldap_kdc_dn**
- This LDAP specific tag indicates the default bind DN for the KDC server.
- The KDC server does a login to the directory as this object.
- This object should have the rights to read the Kerberos data in the LDAP database.
- This value is used if the bind DN for the KDC is not mentioned in
- the configuration section under dbmodules_.
+ This LDAP specific tag indicates the default bind DN for the KDC
+ server. The KDC server does a login to the directory as this
+ object. This object should have the rights to read the Kerberos
+ data in the LDAP database. This value is used if the bind DN for
+ the KDC is not mentioned in the configuration section under
+ dbmodules_.
**ldap_kadmind_dn**
- This LDAP specific tag indicates the default bind DN for the Administration server.
- The administration server does a login to the directory as this object.
- This object should have the rights to read and write the Kerberos data
- in the LDAP database. This value is used if the bind DN for
- the Administration server is not mentioned in the configuration section under dbmodules_.
+ This LDAP specific tag indicates the default bind DN for the
+ Administration server. The administration server does a login to
+ the directory as this object. This object should have the rights
+ to read and write the Kerberos data in the LDAP database. This
+ value is used if the bind DN for the Administration server is not
+ mentioned in the configuration section under dbmodules_.
**ldap_service_password_file**
- This LDAP specific tag indicates the file containing the stashed passwords
- (created by kdb5_ldap_util stashsrvpw) for the objects used by the Kerberos
- servers to bind to the LDAP server. This file must be kept secure.
- This value is used if no service password file is mentioned
- in the configuration section under dbmodules_.
+ This LDAP specific tag indicates the file containing the stashed
+ passwords (created by kdb5_ldap_util stashsrvpw) for the objects
+ used by the Kerberos servers to bind to the LDAP server. This
+ file must be kept secure. This value is used if no service
+ password file is mentioned in the configuration section under
+ dbmodules_.
**ldap_servers**
- This LDAP specific tag indicates the list of LDAP servers that the Kerberos servers
- can connect to. The list of LDAP servers is whitespace-separated.
- The LDAP server is specified by a LDAP URI.
- This value is used if no LDAP servers are mentioned in the configuration section
- under dbmodules_. It is recommended to use the *ldapi://* or *ldaps://* interface
- and not to use *ldap://* interface.
+ This LDAP specific tag indicates the list of LDAP servers that the
+ Kerberos servers can connect to. The list of LDAP servers is
+ whitespace-separated. The LDAP server is specified by a LDAP URI.
+ This value is used if no LDAP servers are mentioned in the
+ configuration section under dbmodules_. It is recommended to use
+ the ``ldapi://`` or ``ldaps://`` interface and not to use
+ ``ldap://`` interface.
**ldap_conns_per_server**
- This LDAP specific tag indicates the number of connections to be maintained per LDAP server.
- This value is used if the number of connections per LDAP server are not mentioned
- in the configuration section under dbmodules_. The default value is 5.
+ This LDAP specific tag indicates the number of connections to be
+ maintained per LDAP server. This value is used if the number of
+ connections per LDAP server are not mentioned in the configuration
+ section under dbmodules_. The default value is 5.
+
.. _dbmodules:
-**[dbmodules]**
-~~~~~~~~~~~~~~~~~~
+[dbmodules]
+~~~~~~~~~~~
Contains database specific parameters used by the database library.
-Each tag in the [dbmodules] section of the file names a configuration section
-for database specific parameters that can be referred to by a realm.
-The value of the tag is a subsection where the relations in
+Each tag in the [dbmodules] section of the file names a configuration
+section for database specific parameters that can be referred to by a
+realm. The value of the tag is a subsection where the relations in
that subsection define the database specific parameters.
-For each section, the following tags may be specified in the subsection:
+For each section, the following tags may be specified in the
+subsection:
**database_name**
- This DB2-specific tag indicates the location of the database
- in the filesystem. The default is */usr/local/var/krb5kdc/principal*.
+ This DB2-specific tag indicates the location of the database in
+ the filesystem. The default is
+ ``/usr/local/var/krb5kdc/principal``.
**db_library**
- This tag indicates the name of the loadable database library.
- The value should be *db2* for DB2 database and *kldap* for LDAP database.
+ This tag indicates the name of the loadable database library. The
+ value should be ``db2`` for DB2 database and ``kldap`` for LDAP
+ database.
**db_module_dir**
- This tag controls where the plugin system looks for modules.
- The value should be an absolute path.
+ This tag controls where the plugin system looks for modules. The
+ value should be an absolute path.
**disable_last_success**
- If set to *true*, suppresses KDC updates to the
- *"Last successful authentication"* field of principal entries requiring
+ If set to ``true``, suppresses KDC updates to the "Last successful
+ authentication" field of principal entries requiring
preauthentication. Setting this flag may improve performance.
- (Principal entries which do not require preauthentication
- never update the "Last successful authentication" field.).
-
+ (Principal entries which do not require preauthentication never
+ update the "Last successful authentication" field.).
+
**disable_lockout**
- If set to *true*, suppresses KDC updates to the
- *"Last failed authentication"* and *"Failed password attempts"* fields
- of principal entries requiring preauthentication.
- Setting this flag may improve performance, but also disables account lockout.
+ If set to ``true``, suppresses KDC updates to the "Last failed
+ authentication" and "Failed password attempts" fields of principal
+ entries requiring preauthentication. Setting this flag may
+ improve performance, but also disables account lockout.
**ldap_conns_per_server**
- This LDAP specific tags indicates the number of connections
- to be maintained per LDAP server.
+ This LDAP specific tags indicates the number of connections to be
+ maintained per LDAP server.
**ldap_kadmind_dn**
- This LDAP specific tag indicates the default bind DN for the Administration server.
- The administration server does a login to the directory as this object.
- This object should have the rights to read and write the Kerberos data
- in the LDAP database.
+ This LDAP specific tag indicates the default bind DN for the
+ Administration server. The administration server does a login to
+ the directory as this object. This object should have the rights
+ to read and write the Kerberos data in the LDAP database.
**ldap_kdc_dn**
- This LDAP specific tag indicates the default bind DN for the KDC server.
- The KDC server does a login to the directory as this object.
- This object should have the rights to read the Kerberos data in the LDAP database.
+ This LDAP specific tag indicates the default bind DN for the KDC
+ server. The KDC server does a login to the directory as this
+ object. This object should have the rights to read the Kerberos
+ data in the LDAP database.
**ldap_kerberos_container_dn**
- This LDAP specific tag indicates the DN of the container object where
- the realm objects will be located.
+ This LDAP specific tag indicates the DN of the container object
+ where the realm objects will be located.
**ldap_servers**
- This LDAP specific tag indicates the list of LDAP servers that the
- Kerberos servers can connect to. The list of LDAP servers is whitespace-separated.
- The LDAP server is specified by a LDAP URI.
- It is recommended to use *ldapi://* or *ldaps://* interface
- to connect to the LDAP server.
+ This LDAP specific tag indicates the list of LDAP servers that the
+ Kerberos servers can connect to. The list of LDAP servers is
+ whitespace-separated. The LDAP server is specified by a LDAP URI.
+ It is recommended to use ``ldapi://`` or ``ldaps://`` interface to
+ connect to the LDAP server.
**ldap_service_password_file**
- This LDAP specific tag indicates the file containing the stashed passwords
- (created by *kdb5_ldap_util stashsrvpw*) for the objects used by
- the Kerberos servers to bind to the LDAP server. This file must be kept secure.
+ This LDAP specific tag indicates the file containing the stashed
+ passwords (created by "kdb5_ldap_util stashsrvpw") for the objects
+ used by the Kerberos servers to bind to the LDAP server. This
+ file must be kept secure.
.. _appdefaults:
-**[appdefaults]**
-~~~~~~~~~~~~~~~~~~~~~~~~~
+[appdefaults]
+~~~~~~~~~~~~~
Each tag in the [appdefaults] section names a Kerberos V5 application
-or an option that is used by some Kerberos V5 application[s].
-The value of the tag defines the default behaviors for that application.
+or an option that is used by some Kerberos V5 application[s]. The
+value of the tag defines the default behaviors for that application.
For example::
- [appdefaults]
- telnet = {
- ATHENA.MIT.EDU = {
- option1 = false
- }
- }
- telnet = {
- option1 = true
- option2 = true
- }
- ATHENA.MIT.EDU = {
- option2 = false
- }
- option2 = true
-
-
-The above four ways of specifying the value of an option are shown in order
-of decreasing precedence. In this example, if telnet is running in the
-realm EXAMPLE.COM, it should, by default, have option1 and option2 set to true.
-However, a telnet program in the realm ATHENA.MIT.EDU should have *option1*
-set to false and *option2* set to true.
-Any other programs in ATHENA.MIT.EDU should have *option2* set to false by default.
-Any programs running in other realms should have *option2* set to true.
-
-The list of specifiable options for each application may be found in that
-application's man pages. The application defaults specified here
+ [appdefaults]
+ telnet = {
+ ATHENA.MIT.EDU = {
+ option1 = false
+ }
+ }
+ telnet = {
+ option1 = true
+ option2 = true
+ }
+ ATHENA.MIT.EDU = {
+ option2 = false
+ }
+ option2 = true
+
+The above four ways of specifying the value of an option are shown in
+order of decreasing precedence. In this example, if telnet is running
+in the realm EXAMPLE.COM, it should, by default, have option1 and
+option2 set to true. However, a telnet program in the realm
+``ATHENA.MIT.EDU`` should have ``option1`` set to false and
+``option2`` set to true. Any other programs in ATHENA.MIT.EDU should
+have ``option2`` set to false by default. Any programs running in
+other realms should have ``option2`` set to true.
+
+The list of specifiable options for each application may be found in
+that application's man pages. The application defaults specified here
are overridden by those specified in the realms_ section.
+
.. _plugins:
-Plugins
---------
+[plugins]
+~~~~~~~~~
* pwqual_ interface
* kadm5_hook_ interface
* clpreauth_ and kdcpreauth_ interfaces
-Tags in the **[plugins]** section can be used to register *dynamic plugin modules*
-and to turn modules on and off.
-Not every krb5 pluggable interface uses the [plugins] section;
-the ones that do are documented here.
+Tags in the [plugins] section can be used to register dynamic plugin
+modules and to turn modules on and off. Not every krb5 pluggable
+interface uses the [plugins] section; the ones that do are documented
+here.
-Each pluggable interface corresponds to a subsection of [plugins].
+Each pluggable interface corresponds to a subsection of [plugins].
All subsections support the same tags:
**disable**
- This tag may have multiple values. If there are values for this tag,
- then the named modules will be disabled for the pluggable interface.
+ This tag may have multiple values. If there are values for this
+ tag, then the named modules will be disabled for the pluggable
+ interface.
**enable_only**
- This tag may have multiple values. If there are values for this tag,
- then only the named modules will be enabled for the pluggable interface.
+ This tag may have multiple values. If there are values for this
+ tag, then only the named modules will be enabled for the pluggable
+ interface.
**module**
- This tag may have multiple values.
- Each value is a string of the form "modulename:pathname",
- which causes the shared object located at *pathname* to be registered as
- a dynamic module named *modulename* for the pluggable interface.
- If *pathname* is not an absolute path, it will be treated as relative
- to the "krb5/plugins" subdirectory of the krb5 library directory.
+ This tag may have multiple values. Each value is a string of the
+ form ``modulename:pathname``, which causes the shared object
+ located at *pathname* to be registered as a dynamic module named
+ *modulename* for the pluggable interface. If *pathname* is not an
+ absolute path, it will be treated as relative to the
+ ``krb5/plugins`` subdirectory of the krb5 library directory.
-The following subsections are currently supported within the [plugins] section:
+The following subsections are currently supported within the [plugins]
+section:
.. _pwqual:
pwqual interface
-~~~~~~~~~~~~~~~~~~~~~~~
+################
-The **pwqual** subsection controls modules for the password quality interface,
-which is used to reject weak passwords when passwords are changed.
-In addition to any registered dynamic modules, the following built-in modules
-exist (and may be disabled with the disable tag):
+The pwqual subsection controls modules for the password quality
+interface, which is used to reject weak passwords when passwords are
+changed. In addition to any registered dynamic modules, the following
+built-in modules exist (and may be disabled with the disable tag):
**dict**
- Checks against the realm dictionary file
+ Checks against the realm dictionary file
**empty**
- Rejects empty passwords
+ Rejects empty passwords
**hesiod**
- Checks against user information stored in Hesiod
- (only if Kerberos was built with Hesiod support)
+ Checks against user information stored in Hesiod (only if Kerberos
+ was built with Hesiod support)
**princ**
- Checks against components of the principal name
+ Checks against components of the principal name
.. _kadm5_hook:
kadm5_hook interface
-~~~~~~~~~~~~~~~~~~~~~~~~
+####################
-The **kadm5_hook** interface provides plugins with information on principal
-creation, modification, password changes and deletion.
-This interface can be used to write a plugin to synchronize MIT Kerberos
-with another database such as Active Directory.
-No plugins are built in for this interface.
+The kadm5_hook interface provides plugins with information on
+principal creation, modification, password changes and deletion. This
+interface can be used to write a plugin to synchronize MIT Kerberos
+with another database such as Active Directory. No plugins are built
+in for this interface.
.. _clpreauth:
.. _kdcpreauth:
clpreauth and kdcpreauth interfaces
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+###################################
-The **clpreauth** and **kdcpreauth** interfaces allow plugin modules to provide
-client and KDC preauthentication mechanisms.
-The following built-in modules exist for these interfaces:
+The clpreauth and kdcpreauth interfaces allow plugin modules to
+provide client and KDC preauthentication mechanisms. The following
+built-in modules exist for these interfaces:
**pkinit**
This module implements the PKINIT preauthentication mechanism.
**encrypted_timestamp**
This module implements the encrypted timestamp mechanism.
-PKINIT options
------------------
- * pkinit identity syntax
- * pkinit krb5.conf options
-
-.. note:: The following are pkinit-specific options.
- Note that these values may be specified in *[libdefaults]* as
- global defaults, or within a realm-specific subsection of
- *[libdefaults]*, or may be specified as realm-specific values
- in the *[realms]* section. Also note that a realm-specific value
- over-rides, does not add to, a generic *[libdefaults]* specification.
- The search order is:
+PKINIT options
+--------------
- 1. realm-specific subsection of [libdefaults]
+* pkinit identity syntax
+* pkinit krb5.conf options
- [libdefaults]
- EXAMPLE.COM = {
- pkinit_anchors = FILE\:/usr/local/example.com.crt
+.. note:: The following are pkinit-specific options. Note that these
+ values may be specified in [libdefaults] as global defaults,
+ or within a realm-specific subsection of [libdefaults], or
+ may be specified as realm-specific values in the [realms]
+ section. Also note that a realm-specific value over-rides,
+ does not add to, a generic [libdefaults] specification. The
+ search order is:
- }
-
+1. realm-specific subsection of [libdefaults] ::
- 2. realm-specific value in the [realms] section,
+ [libdefaults]
+ EXAMPLE.COM = {
+ pkinit_anchors = FILE\:/usr/local/example.com.crt
+ }
- [realms]
- OTHERREALM.ORG = {
- pkinit_anchors = FILE\:/usr/local/otherrealm.org.crt
+2. realm-specific value in the [realms] section, ::
- }
-
+ [realms]
+ OTHERREALM.ORG = {
+ pkinit_anchors = FILE\:/usr/local/otherrealm.org.crt
+ }
- 3. generic value in the [libdefaults] section.
+3. generic value in the [libdefaults] section. ::
- [libdefaults]
- pkinit_anchors = DIR\:/usr/local/generic_trusted_cas/
-
+ [libdefaults]
+ pkinit_anchors = DIR\:/usr/local/generic_trusted_cas/
Specifying pkinit identity information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The syntax for specifying Public Key identity, trust, and revocation information
-for pkinit is as follows:
-
+The syntax for specifying Public Key identity, trust, and revocation
+information for pkinit is as follows:
-FILE\:file-name\[,key-file-name]
+**FILE:**\ *filename*\ [**,**\ *keyfilename*]
This option has context-specific behavior.
- | pkinit_identity
- | pkinit_identities
+ In **pkinit_identity** or **pkinit_identities**, *filename*
+ specifies the name of a PEM-format file containing the user's
+ certificate. If *keyfilename* is not specified, the user's
+ private key is expected to be in file-name as well. Otherwise,
+ *keyfilename* is the name of the file containing the private key.
- *file-name* specifies the name of a PEM-format file containing
- the user's certificate. If *key-file-name* is not specified,
- the user's private key is expected to be in file-name as well.
- Otherwise, *key-file-name* is the name of the file containing the private key.
+ In **pkinit_anchors** or **pkinit_pool**, *filename* is assumed to
+ be the name of an OpenSSL-style ca-bundle file.
- | pkinit_anchors
- | pkinit_pool
-
- *file-name* is assumed to be the name of an OpenSSL-style ca-bundle file.
-
-
-DIR:directory-name
+**DIR:**\ *dirname*
This option has context-specific behavior.
- | pkinit_identity
- | pkinit_identities
-
- *directory-name* specifies a directory with files named \*.crt and \*.key,
- where the first part of the file name is the same for matching pairs
- of certificate and private key files. When a file with a name ending
- with .crt is found, a matching file ending with .key is assumed
- to contain the private key.
- If no such file is found, then the certificate in the .crt is not used.
-
- | pkinit_anchors
- | pkinit_pool
-
- *directory-name* is assumed to be an OpenSSL-style hashed CA directory
- where each CA cert is stored in a file named *hash-of-ca-cert.#*.
- This infrastructure is encouraged, but all files in the directory
- will be examined and if they contain certificates (in PEM format), they will be used.
-
- pkinit_revoke
- *directory-name* is assumed to be an OpenSSL-style hashed CA directory
- where each revocation list is stored in a file named *hash-of-ca-cert.r#*.
- This infrastructure is encouraged, but all files in the directory
- will be examined and if they contain a revocation list (in PEM format),
- they will be used.
-
-
-PKCS12:pkcs12-file-name
- *pkcs12-file-name* is the name of a PKCS #12 format file,
+ In **pkinit_identity** or **pkinit_identities**, *directory-name*
+ specifies a directory with files named ``*.crt`` and ``*.key``
+ where the first part of the file name is the same for matching
+ pairs of certificate and private key files. When a file with a
+ name ending with ``.crt`` is found, a matching file ending with
+ ``.key`` is assumed to contain the private key. If no such file
+ is found, then the certificate in the ``.crt`` is not used.
+
+ In **pkinit_anchors** or **pkinit_pool**, *directory-name* is
+ assumed to be an OpenSSL-style hashed CA directory where each CA
+ cert is stored in a file named ``hash-of-ca-cert.#``. This
+ infrastructure is encouraged, but all files in the directory will
+ be examined and if they contain certificates (in PEM format), they
+ will be used.
+
+ In **pkinit_revoke**, *directory-name* is assumed to be an
+ OpenSSL-style hashed CA directory where each revocation list is
+ stored in a file named ``hash-of-ca-cert.r#``. This
+ infrastructure is encouraged, but all files in the directory will
+ be examined and if they contain a revocation list (in PEM format),
+ they will be used.
+
+**PKCS12:**\ *pkcs12-file-name*
+ *pkcs12-file-name* is the name of a PKCS #12 format file,
containing the user's certificate and private key.
-PKCS11:[module_name=]module-name[:slotid=slot-id][:token=token-label][:certid=cert-id][:certlabel=cert-label]
- All keyword/values are optional. *module-name* specifies the location
- of a library implementing PKCS #11. If a value is encountered with no keyword,
- it is assumed to be the *module-name*. If no module-name is specified,
- the default is *opensc-pkcs11.so*. *slotid=* and/or *token=* may be
- specified to force the use of a particular smard card reader or token
- if there is more than one available. *certid=* and/or *certlabel=* may be
- specified to force the selection of a particular certificate on the device.
- See the *pkinit_cert_match* configuration option for more ways to select
+**PKCS11:**\ [**module_name=**]\ *module-name*\ [**:slotid=**\ *slot-id*][**:token=**\ *token-label*][**:certid=**\ *cert-id*][**:certlabel=**\ *cert-label*]
+ All keyword/values are optional. *module-name* specifies the
+ location of a library implementing PKCS #11. If a value is
+ encountered with no keyword, it is assumed to be the
+ *module-name*. If no module-name is specified, the default is
+ ``opensc-pkcs11.so``. ``slotid=`` and/or ``token=`` may be
+ specified to force the use of a particular smard card reader or
+ token if there is more than one available. ``certid=`` and/or
+ ``certlabel=`` may be specified to force the selection of a
+ particular certificate on the device. See the
+ **pkinit_cert_match** configuration option for more ways to select
a particular certificate to use for pkinit.
-ENV:environment-variable-name
- *environment-variable-name* specifies the name of an environment variable
- which has been set to a value conforming to one of the previous values.
- For example, *ENV:X509_PROXY*, where environment variable *X509_PROXY*
- has been set to *FILE:/tmp/my_proxy.pem*.
-
+**ENV:**\ *envvar*
+ *envvar* specifies the name of an environment variable which has
+ been set to a value conforming to one of the previous values. For
+ example, ``ENV:X509_PROXY``, where environment variable
+ ``X509_PROXY`` has been set to ``FILE:/tmp/my_proxy.pem``.
PKINIT krb5.conf options
~~~~~~~~~~~~~~~~~~~~~~~~
-
**pkinit_anchors**
Specifies the location of trusted anchor (root) certificates which
- the client trusts to sign KDC certificates.
- This option may be specified multiple times.
- These values from the config file are not used if the user specifies
- X509_anchors on the command line.
+ the client trusts to sign KDC certificates. This option may be
+ specified multiple times. These values from the config file are
+ not used if the user specifies X509_anchors on the command line.
**pkinit_cert_match**
- Specifies matching rules that the client certificate must match before
- it is used to attempt pkinit authentication.
- If a user has multiple certificates available
- (on a smart card, or via other media), there must be exactly one certificate
- chosen before attempting pkinit authentication.
- This option may be specified multiple times.
- All the available certificates are checked against each rule in order
- until there is a match of exactly one certificate.
+ Specifies matching rules that the client certificate must match
+ before it is used to attempt pkinit authentication. If a user has
+ multiple certificates available (on a smart card, or via other
+ media), there must be exactly one certificate chosen before
+ attempting pkinit authentication. This option may be specified
+ multiple times. All the available certificates are checked
+ against each rule in order until there is a match of exactly one
+ certificate.
- The Subject and Issuer comparison strings are the :rfc:`2253` string
- representations from the certificate Subject DN and Issuer DN values.
+ The Subject and Issuer comparison strings are the :rfc:`2253`
+ string representations from the certificate Subject DN and Issuer
+ DN values.
- The syntax of the matching rules is::
+ The syntax of the matching rules is:
- [relation-operator]component-rule ...
-
+ [*relation-operator*\ ]\ *component-rule* ...
- where
+ where:
*relation-operator*
- can be either **&&**, meaning all component rules must match,
- or **||**, meaning only one component rule must match. The default is &&.
+ can be either ``&&``, meaning all component rules must match,
+ or ``||``, meaning only one component rule must match. The
+ default is ``&&``.
*component-rule*
- can be one of the following.
- Note that there is no punctuation or whitespace between component rules.
-
- *<SUBJECT>regular-expression*
-
- *<ISSUER>regular-expression*
-
- *<SAN>regular-expression*
+ can be one of the following. Note that there is no
+ punctuation or whitespace between component rules.
- *<EKU>extended-key-usage-list*
- where *extended-key-usage-list* is a comma-separated list of required
- Extended Key Usage values. All values in the list must be present in the certificate.
+ | **<SUBJECT>**\ *regular-expression*
+ | **<ISSUER>**\ *regular-expression*
+ | **<SAN>**\ *regular-expression*
+ | **<EKU>**\ *extended-key-usage-list*
+ | **<KU>**\ *key-usage-list*
- - pkinit
- - msScLogin
- - clientAuth
- - emailProtection
-
+ *extended-key-usage-list* is a comma-separated list of
+ required Extended Key Usage values. All values in the list
+ must be present in the certificate. Extended Key Usage values
+ can be:
+ * pkinit
+ * msScLogin
+ * clientAuth
+ * emailProtection
- *<KU>key-usage-list*
- where *key-usage-list* is a comma-separated list of required Key Usage values.
- All values in the list must be present in the certificate.
+ *key-usage-list* is a comma-separated list of required Key
+ Usage values. All values in the list must be present in the
+ certificate. Key Usage values can be:
- - digitalSignature
- - keyEncipherment
-
+ * digitalSignature
+ * keyEncipherment
Examples::
- pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM
- pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.*
- pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
-
-**pkinit_eku_checking**
- This option specifies what Extended Key Usage value the KDC certificate
- presented to the client must contain. (Note that if the KDC certificate
- has the pkinit SubjectAlternativeName encoded as the Kerberos TGS name,
- EKU checking is not necessary since the issuing CA has certified this
- as a KDC certificate.) The values recognized in the krb5.conf file are:
+ pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM
+ pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.*
+ pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
- *kpKDC*
+**pkinit_eku_checking**
+ This option specifies what Extended Key Usage value the KDC
+ certificate presented to the client must contain. (Note that if
+ the KDC certificate has the pkinit SubjectAlternativeName encoded
+ as the Kerberos TGS name, EKU checking is not necessary since the
+ issuing CA has certified this as a KDC certificate.) The values
+ recognized in the krb5.conf file are:
+
+ **kpKDC**
This is the default value and specifies that the KDC must have
- the *id-pkinit-KPKdc* EKU as defined in :rfc:`4556`.
- *kpServerAuth*
- If kpServerAuth is specified, a KDC certificate with
- the *id-kp-serverAuth* EKU as used by Microsoft will be accepted.
- *none*
- If none is specified, then the KDC certificate will not be checked to
- verify it has an acceptable EKU. The use of this option is not recommended.
+ the id-pkinit-KPKdc EKU as defined in :rfc:`4556`.
+
+ **kpServerAuth**
+ If **kpServerAuth** is specified, a KDC certificate with the
+ id-kp-serverAuth EKU as used by Microsoft will be accepted.
+
+ **none**
+ If **none** is specified, then the KDC certificate will not be
+ checked to verify it has an acceptable EKU. The use of this
+ option is not recommended.
**pkinit_dh_min_bits**
- Specifies the size of the Diffie-Hellman key the client will attempt to use.
- The acceptable values are currently 1024, 2048, and 4096. The default is 2048.
+ Specifies the size of the Diffie-Hellman key the client will
+ attempt to use. The acceptable values are currently 1024, 2048,
+ and 4096. The default is 2048.
**pkinit_identities**
- Specifies the location(s) to be used to find the user's X.509 identity
- information. This option may be specified multiple times.
- Each value is attempted in order until identity information is found and
- authentication is attempted. Note that these values are not used
- if the user specifies X509_user_identity on the command line.
+ Specifies the location(s) to be used to find the user's X.509
+ identity information. This option may be specified multiple
+ times. Each value is attempted in order until identity
+ information is found and authentication is attempted. Note that
+ these values are not used if the user specifies
+ **X509_user_identity** on the command line.
**pkinit_kdc_hostname**
- The presense of this option indicates that the client is willing to accept
- a KDC certificate with a dNSName SAN (Subject Alternative Name)
- rather than requiring the id-pkinit-san as defined in :rfc:`4556`.
- This option may be specified multiple times.
- Its value should contain the acceptable hostname for the KDC
- (as contained in its certificate).
+ The presense of this option indicates that the client is willing
+ to accept a KDC certificate with a dNSName SAN (Subject
+ Alternative Name) rather than requiring the id-pkinit-san as
+ defined in :rfc:`4556`. This option may be specified multiple
+ times. Its value should contain the acceptable hostname for the
+ KDC (as contained in its certificate).
**pkinit_longhorn**
If this flag is set to true, we are talking to the Longhorn KDC.
**pkinit_pool**
- Specifies the location of intermediate certificates which may be used
- by the client to complete the trust chain between a KDC certificate
- and a trusted anchor. This option may be specified multiple times.
+ Specifies the location of intermediate certificates which may be
+ used by the client to complete the trust chain between a KDC
+ certificate and a trusted anchor. This option may be specified
+ multiple times.
**pkinit_require_crl_checking**
- The default certificate verification process will always check the
- available revocation information to see if a certificate has been revoked.
- If a match is found for the certificate in a CRL, verification fails.
- If the certificate being verified is not listed in a CRL,
- or there is no CRL present for its issuing CA, and
- *pkinit_require_crl_checking* is false, then verification succeeds.
+ The default certificate verification process will always check the
+ available revocation information to see if a certificate has been
+ revoked. If a match is found for the certificate in a CRL,
+ verification fails. If the certificate being verified is not
+ listed in a CRL, or there is no CRL present for its issuing CA,
+ and **pkinit_require_crl_checking** is false, then verification
+ succeeds.
- However, if *pkinit_require_crl_checking* is true and there is no
- CRL information available for the issuing CA, then verification fails.
+ However, if **pkinit_require_crl_checking** is true and there is
+ no CRL information available for the issuing CA, then verification
+ fails.
- *pkinit_require_crl_checking* should be set to true if the policy
- is such that up-to-date CRLs must be present for every CA.
+ **pkinit_require_crl_checking** should be set to true if the
+ policy is such that up-to-date CRLs must be present for every CA.
**pkinit_revoke**
- Specifies the location of Certificate Revocation List (CRL) information
- to be used by the client when verifying the validity of the KDC certificate
- presented. This option may be specified multiple times.
+ Specifies the location of Certificate Revocation List (CRL)
+ information to be used by the client when verifying the validity
+ of the KDC certificate presented. This option may be specified
+ multiple times.
**pkinit_win2k**
- This flag specifies whether the target realm is assumed to support only
- the old, pre-RFC version of the protocol. The default is false.
+ This flag specifies whether the target realm is assumed to support
+ only the old, pre-RFC version of the protocol. The default is
+ false.
**pkinit_win2k_require_binding**
- If this flag is set to true, it expects that the target KDC is patched
- to return a reply with a checksum rather than a nonce. The default is false.
-
+ If this flag is set to true, it expects that the target KDC is
+ patched to return a reply with a checksum rather than a nonce.
+ The default is false.
.. _krb5_conf_sample_label:
Sample krb5.conf file
--------------------------
+---------------------
Here is an example of a generic krb5.conf file::
- [libdefaults]
- default_realm = ATHENA.MIT.EDU
- default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc
- default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc
- dns_lookup_kdc = true
- dns_lookup_realm = false
-
- [realms]
- ATHENA.MIT.EDU = {
- kdc = kerberos.mit.edu
- kdc = kerberos-1.mit.edu
- kdc = kerberos-2.mit.edu:750
- admin_server = kerberos.mit.edu
- master_kdc = kerberos.mit.edu
- default_domain = mit.edu
- }
- EXAMPLE.COM = {
- kdc = kerberos.example.com
- kdc = kerberos-1.example.com
- admin_server = kerberos.example.com
- }
- OPENLDAP.MIT.EDU = {
- kdc = kerberos.mit.edu
- admin_server = kerberos.mit.edu
- database_module = openldap_ldapconf
- }
-
- [domain_realm]
- .mit.edu = ATHENA.MIT.EDU
- mit.edu = ATHENA.MIT.EDU
-
- [capaths]
- ATHENA.MIT.EDU = {
- EXAMPLE.COM = .
- }
- EXAMPLE.COM = {
- ATHENA.MIT.EDU = .
- }
-
- [logging]
- kdc = SYSLOG:INFO
- admin_server = FILE=/var/kadm5.log
- [dbdefaults]
- ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
- [dbmodules]
- openldap_ldapconf = {
- db_library = kldap
- disable_last_success = true
- ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
- ldap_kdc_dn = "cn=krbadmin,dc=example,dc=com"
- # this object needs to have read rights on
- # the realm container and principal subtrees
- ldap_kadmind_dn = "cn=krbadmin,dc=example,dc=com"
- # this object needs to have read and write rights on
- # the realm container and principal subtrees
- ldap_service_password_file = /etc/kerberos/service.keyfile
- ldap_servers = ldaps://kerberos.mit.edu
- ldap_conns_per_server = 5
- }
-
-FILES
---------
-
-/etc/krb5.conf
+ [libdefaults]
+ default_realm = ATHENA.MIT.EDU
+ default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc
+ default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc
+ dns_lookup_kdc = true
+ dns_lookup_realm = false
+
+ [realms]
+ ATHENA.MIT.EDU = {
+ kdc = kerberos.mit.edu
+ kdc = kerberos-1.mit.edu
+ kdc = kerberos-2.mit.edu:750
+ admin_server = kerberos.mit.edu
+ master_kdc = kerberos.mit.edu
+ default_domain = mit.edu
+ }
+ EXAMPLE.COM = {
+ kdc = kerberos.example.com
+ kdc = kerberos-1.example.com
+ admin_server = kerberos.example.com
+ }
+ OPENLDAP.MIT.EDU = {
+ kdc = kerberos.mit.edu
+ admin_server = kerberos.mit.edu
+ database_module = openldap_ldapconf
+ }
+
+ [domain_realm]
+ .mit.edu = ATHENA.MIT.EDU
+ mit.edu = ATHENA.MIT.EDU
+
+ [capaths]
+ ATHENA.MIT.EDU = {
+ EXAMPLE.COM = .
+ }
+ EXAMPLE.COM = {
+ ATHENA.MIT.EDU = .
+ }
+
+ [logging]
+ kdc = SYSLOG:INFO
+ admin_server = FILE=/var/kadm5.log
+ [dbdefaults]
+ ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
+ [dbmodules]
+ openldap_ldapconf = {
+ db_library = kldap
+ disable_last_success = true
+ ldap_kerberos_container_dn = cn=krbcontainer,dc=example,dc=com
+ ldap_kdc_dn = "cn=krbadmin,dc=example,dc=com"
+ # this object needs to have read rights on
+ # the realm container and principal subtrees
+ ldap_kadmind_dn = "cn=krbadmin,dc=example,dc=com"
+ # this object needs to have read and write rights on
+ # the realm container and principal subtrees
+ ldap_service_password_file = /etc/kerberos/service.keyfile
+ ldap_servers = ldaps://kerberos.mit.edu
+ ldap_conns_per_server = 5
+ }
-SEE ALSO
------------
-syslog(3)
+FILES
+-----
+``/etc/krb5.conf``
+SEE ALSO
+--------
+syslog(3)
Configuring Kerberos with OpenLDAP back-end
-=================================================
+===========================================
-.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+.. note:: This document was copied from **Kerberos V5 System
+ Administrator's Guide** with minor changes. Currently it is
+ under review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is
+ greatly appreciated.
.. seealso:: :ref:`ldap_be_ubuntu`
-1. Set up SSL on the OpenLDAP server and client to ensure secure communication when the KDC service and LDAP server are on different machines. *ldapi\://* can be used if the LDAP server and KDC service are running on the same machine.
- \A. Setting up SSL on the OpenLDAP server:
- a) Get a CA certificate using OpenSSL tools
- b) Configure OpenLDAP server for using SSL/TLS
+1. Set up SSL on the OpenLDAP server and client to ensure secure
+ communication when the KDC service and LDAP server are on different
+ machines. ``ldapi\://`` can be used if the LDAP server and KDC
+ service are running on the same machine.
- For the latter, you need to specify the location of CA certificate location in *slapd.conf* file.
+ A. Setting up SSL on the OpenLDAP server:
- Refer to the following link for more information: http://www.openldap.org/doc/admin23/tls.html
+ i) Get a CA certificate using OpenSSL tools
+ ii) Configure OpenLDAP server for using SSL/TLS
- \B. Setting up SSL on OpenLDAP Client:
- a) For the KDC and Admin Server, you need to do the client-side configuration in *ldap.conf*.
+ For the latter, you need to specify the location of CA
+ certificate location in *slapd.conf* file.
- For example::
+ Refer to the following link for more information:
+ http://www.openldap.org/doc/admin23/tls.html
- TLS_CACERT /etc/openldap/certs/cacert.pem
-
+ B. Setting up SSL on OpenLDAP Client:
-2. Include the Kerberos schema file (*kerberos.schema*) in the configuration file (*slapd.conf*) on the LDAP Server, by providing the location where it is stored.
+ i) For the KDC and Admin Server, you need to do the client-side
+ configuration in ldap.conf. For example::
- include /etc/openldap/schema/kerberos.schema
-
+ TLS_CACERT /etc/openldap/certs/cacert.pem
-3. Choose DNs for the KDC and kadmin servers to bind to the LDAP server, and create them if necessary. These DNs will be specified with the *ldap_kdc_dn* and *ldap_kadmind_dn* directives in *krb5.conf*; their passwords can be stashed with *kdb5_ldap_util stashsrvpw* and the resulting file specified with the *ldap_service_password_file* directive.
+2. Include the Kerberos schema file (kerberos.schema) in the
+ configuration file (slapd.conf) on the LDAP Server, by providing
+ the location where it is stored::
-4. Choose a DN for the global Kerberos container entry (but do not create the entry at this time). This DN will be specified with the *ldap_kerberos_container_dn* directive in *krb5.conf*. Realm container entries will be created underneath this DN. Principal entries may exist either underneath the realm container (the default) or in separate trees referenced from the realm container.
+ include /etc/openldap/schema/kerberos.schema
-5. Configure the LDAP server ACLs to enable the KDC and kadmin server DNs to read and write the Kerberos data.
+3. Choose DNs for the KDC and kadmin servers to bind to the LDAP
+ server, and create them if necessary. These DNs will be specified
+ with the **ldap_kdc_dn** and **ldap_kadmind_dn** directives in
+ krb5.conf; their passwords can be stashed with "``kdb5_ldap_util
+ stashsrvpw``" and the resulting file specified with the
+ **ldap_service_password_file** directive.
- Sample access control information::
+4. Choose a DN for the global Kerberos container entry (but do not
+ create the entry at this time). This DN will be specified with the
+ **ldap_kerberos_container_dn** directive in krb5.conf. Realm
+ container entries will be created underneath this DN. Principal
+ entries may exist either underneath the realm container (the
+ default) or in separate trees referenced from the realm container.
- access to dn.base=""
- by * read
-
- access to dn.base="cn=Subschema"
- by * read
-
- access to attrs=userPassword,userPKCS12
- by self write
- by * auth
-
- access to attrs=shadowLastChange
- by self write
- by * read
-
- # Providing access to realm container
- access to dn.subtree= "cn=EXAMPLE.COM,cn=krbcontainer,dc=example,dc=com"
- by dn.exact="cn=kdc-service,dc=example,dc=com" read
- by dn.exact="cn=adm-service,dc=example,dc=com" write
- by * none
-
- # Providing access to principals, if not underneath realm container
- access to dn.subtree= "ou=users,dc=example,dc=com"
- by dn.exact="cn=kdc-service,dc=example,dc=com" read
- by dn.exact="cn=adm-service,dc=example,dc=com" write
- by * none
-
- access to *
- by * read
-
+5. Configure the LDAP server ACLs to enable the KDC and kadmin server
+ DNs to read and write the Kerberos data.
- If the locations of the container and principals or the DNs of the service objects for a realm are changed then this information should be updated.
+ Sample access control information::
-6. Start the LDAP server as follows::
-
- slapd -h "ldapi:/// ldaps:///"
-
-
-7. Modify the *krb5.conf* file to include LDAP specific items listed below::
-
- realms
- database_module
-
- dbmodules
- db_library
- db_module_dir
- ldap_kdc_dn
- ldap_kadmind_dn
- ldap_service_password_file
- ldap_servers
- ldap_conns_per_server
-
-
-
- For the sample krb5.conf file, refer to :ref:`krb5_conf_sample_label`. For more details, refer to :ref:`krb5.conf`
-
-8. Create the realm using *kdb5_ldap_util* (see :ref:`ldap_create_realm_label`)::
+ access to dn.base=""
+ by * read
- kdb5_ldap_util -D cn=admin,dc=example,dc=com create -subtrees ou=users,dc=example,dc=com -r EXAMPLE.COM -s
-
+ access to dn.base="cn=Subschema"
+ by * read
+ access to attrs=userPassword,userPKCS12
+ by self write
+ by * auth
- Use the *-subtrees* option if the principals are to exist in a separate subtree from the realm container. Before executing the command, make sure that the subtree mentioned above *(ou=users,dc=example,dc=com)* exists. If the principals will exist underneath the realm container, omit the *-subtrees* option and do not worry about creating the principal subtree.
+ access to attrs=shadowLastChange
+ by self write
+ by * read
- For more information, refer to the section :ref:`ops_on_ldap_label`
+ # Providing access to realm container
+ access to dn.subtree= "cn=EXAMPLE.COM,cn=krbcontainer,dc=example,dc=com"
+ by dn.exact="cn=kdc-service,dc=example,dc=com" read
+ by dn.exact="cn=adm-service,dc=example,dc=com" write
+ by * none
- The realm object is created under the *ldap_kerberos_container_dn* specified in the configuration file. This operation will also create the Kerberos container, if not present already. This will be used to store information related to all realms.
+ # Providing access to principals, if not underneath realm container
+ access to dn.subtree= "ou=users,dc=example,dc=com"
+ by dn.exact="cn=kdc-service,dc=example,dc=com" read
+ by dn.exact="cn=adm-service,dc=example,dc=com" write
+ by * none
-9. Stash the password of the service object used by the KDC and Administration service to bind to the LDAP server using the *stashsrvpw* command of *kdb5_ldap_util* (see :ref:`stash_ldap_label`). The object DN should be the same as *ldap_kdc_dn* and *ldap_kadmind_dn* values specified in the *krb5.conf* file::
+ access to *
+ by * read
- kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/kerberos/service.keyfile cn=krbadmin,dc=example,dc=com
-
+ If the locations of the container and principals or the DNs of
+ the service objects for a realm are changed then this
+ information should be updated.
-10. Add *krb5principalname* to the indexes in *slapd.conf* to speed up the access.
-
-With the LDAP back end it is possible to provide aliases for principal entries. Currently we provide no mechanism provided for creating aliases, so it must be done by direct manipulation of the LDAP entries.
-
-An entry with aliases contains multiple values of the *krbPrincipalName* attribute. Since LDAP attribute values are not ordered, it is necessary to specify which principal name is canonical, by using the *krbCanonicalName* attribute. Therefore, to create aliases for an entry, first set the *krbCanonicalName* attribute of the entry to the canonical principal name (which should be identical to the pre-existing *krbPrincipalName* value), and then add additional *krbPrincipalName* attributes for the aliases.
-
-Principal aliases are only returned by the KDC when the client requests canonicalization. Canonicalization is normally requested for service principals; for client principals, an explicit flag is often required (e.g. *kinit -C*) and canonicalization is only performed for initial ticket requests.
-
-----------------------------------
-
-Feedback:
+6. Start the LDAP server as follows::
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___conf_ldap
+ slapd -h "ldapi:/// ldaps:///"
+
+7. Modify the krb5.conf file to include LDAP specific items listed
+ below::
+
+ realms
+ database_module
+
+ dbmodules
+ db_library
+ db_module_dir
+ ldap_kdc_dn
+ ldap_kadmind_dn
+ ldap_service_password_file
+ ldap_servers
+ ldap_conns_per_server
+
+ For the sample krb5.conf file, refer to
+ :ref:`krb5_conf_sample_label`. For more details, refer to
+ :ref:`krb5.conf`
+
+8. Create the realm using kdb5_ldap_util (see
+ :ref:`ldap_create_realm_label`)::
+
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com create -subtrees ou=users,dc=example,dc=com -r EXAMPLE.COM -s
+
+ Use the **-subtrees** option if the principals are to exist in a
+ separate subtree from the realm container. Before executing the
+ command, make sure that the subtree mentioned above
+ ``(ou=users,dc=example,dc=com)`` exists. If the principals will
+ exist underneath the realm container, omit the **-subtrees** option
+ and do not worry about creating the principal subtree.
+
+ For more information, refer to the section
+ :ref:`ops_on_ldap_label`.
+
+ The realm object is created under the
+ **ldap_kerberos_container_dn** specified in the configuration file.
+ This operation will also create the Kerberos container, if not
+ present already. This will be used to store information related to
+ all realms.
+
+9. Stash the password of the service object used by the KDC and
+ Administration service to bind to the LDAP server using the
+ **stashsrvpw** command of kdb5_ldap_util (see
+ :ref:`stash_ldap_label`). The object DN should be the same as
+ **ldap_kdc*_dn* and **ldap_kadmind_dn** values specified in the
+ krb5.conf file::
+
+ kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/kerberos/service.keyfile cn=krbadmin,dc=example,dc=com
+
+10. Add ``krb5principalname`` to the indexes in slapd.conf to speed up
+ the access.
+
+With the LDAP back end it is possible to provide aliases for principal
+entries. Currently we provide no mechanism provided for creating
+aliases, so it must be done by direct manipulation of the LDAP
+entries.
+
+An entry with aliases contains multiple values of the
+*krbPrincipalName* attribute. Since LDAP attribute values are not
+ordered, it is necessary to specify which principal name is canonical,
+by using the *krbCanonicalName* attribute. Therefore, to create
+aliases for an entry, first set the *krbCanonicalName* attribute of
+the entry to the canonical principal name (which should be identical
+to the pre-existing *krbPrincipalName* value), and then add additional
+*krbPrincipalName* attributes for the aliases.
+
+Principal aliases are only returned by the KDC when the client
+requests canonicalization. Canonicalization is normally requested for
+service principals; for client principals, an explicit flag is often
+required (e.g. ``kinit -C``) and canonicalization is only performed
+for initial ticket requests.
+
+
+Feedback
+--------
+
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___conf_ldap
-Changing the *krbtgt* key
-=============================
+Changing the krbtgt key
+=======================
-A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the principal *krbtgt\/REALM*. The key for this principal is created when the Kerberos database is initialized and need not be changed. However, it will only have the encryption types supported by the KDC at the time of the initial database creation. To allow use of newer encryption types for the TGT, this key has to be changed.
+A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the
+principal ``krbtgt/REALM``. The key for this principal is created
+when the Kerberos database is initialized and need not be changed.
+However, it will only have the encryption types supported by the KDC
+at the time of the initial database creation. To allow use of newer
+encryption types for the TGT, this key has to be changed.
+Changing this key using the normal kadmin **change_password** command
+would invalidate any previously issued TGTs. Therefore, when changing
+this key, normally one should use the **-keepold** flag to
+change_password to retain the previous key in the database as well as
+the new key. For example::
-Changing this key using the normal kadmin *change_password* command would invalidate any previously issued TGTs. Therefore, when changing this key, normally one should use the *-keepold* flag to change_password to retain the previous key in the database as well as the new key. For example::
+ kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
- kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
-
+.. warning:: After issuing this command, the old key is still valid
+ and is still vulnerable to (for instance) brute force
+ attacks. To completely retire an old key or encryption
+ type, run the kadmin **purgekeys** command to delete keys
+ with older kvnos, ideally first making sure that all
+ tickets issued with the old keys have expired.
-.. warning:: After issuing this command, the old key is still valid and is still vulnerable to (for instance) brute force attacks. To completely retire an old key or encryption type, run the *purgekeys* command to delete keys with older kvnos, ideally first making sure that all tickets issued with the old keys have expired.
+Feedback
+--------
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
-
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db
Date Format
-===============
+===========
.. include:: ../admin_commands/kadmin_local.rst
:start-after: _date_format:
:end-before: _date_format_end:
-.. note:: If the date specification contains spaces, you must enclose it in double quotes.
- Note also that you cannot use a number without a unit.
- (I.e., ""60 seconds"" is correct, but "60" is incorrect.) All keywords are case-insensitive.
-
-
-
+.. note:: If the date specification contains spaces, you must enclose
+ it in double quotes. Note also that you cannot use a number
+ without a unit. (I.e., ""60 seconds"" is correct, but "60"
+ is incorrect.) All keywords are case-insensitive.
Creating and destroying a Kerberos database
-===================================================
+===========================================
-If you need to create a new Kerberos database, use the :ref:`kdb5_util(8)` **create** command.
+If you need to create a new Kerberos database, use the
+:ref:`kdb5_util(8)` **create** command.
.. include:: ../../admin_commands/kdb5_util.rst
- :start-after: _kdb5_util_create:
+ :start-after: _kdb5_util_create:
:end-before: _kdb5_util_create_end:
-
-If you need to destroy the current Kerberos database, use the :ref:`kdb5_util(8)` **destroy** command.
+If you need to destroy the current Kerberos database, use the
+:ref:`kdb5_util(8)` **destroy** command.
.. include:: ../../admin_commands/kdb5_util.rst
- :start-after: _kdb5_util_destroy:
+ :start-after: _kdb5_util_destroy:
:end-before: _kdb5_util_destroy_end:
-EXAMPLES::
- shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU create -s
- kdb5_util: No such file or directory while setting active database to'/usr/local/var/krb5kdc/principal'
- Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
- master key name 'K/M@ATHENA.MIT.EDU'
- You will be prompted for the database Master Password.
- It is important that you NOT FORGET this password.
- Enter KDC database master key: <= Type the master password.
- Re-enter KDC database master key to verify: <= Type it again.
- shell%
-
+Examples
+--------
+
+::
+
+ shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU create -s
+ kdb5_util: No such file or directory while setting active database to'/usr/local/var/krb5kdc/principal'
+ Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
+ master key name 'K/M@ATHENA.MIT.EDU'
+ You will be prompted for the database Master Password.
+ It is important that you NOT FORGET this password.
+ Enter KDC database master key: <= Type the master password.
+ Re-enter KDC database master key to verify: <= Type it again.
+ shell%
- shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU destroy
- kdb5_util: Deleting KDC database stored in /usr/local/var/krb5kdc/principal, are you sure (type yes to confirm)? <== yes
- OK, deleting database '/usr/local/var/krb5kdc/principal'...
- shell%
-
-------------
+ shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU destroy
+ kdb5_util: Deleting KDC database stored in /usr/local/var/krb5kdc/principal, are you sure (type yes to confirm)? <== yes
+ OK, deleting database '/usr/local/var/krb5kdc/principal'...
+ shell%
-Feedback:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_operations
.. _create_stash:
Creating a stash file
-============================
+=====================
-A stash file allows a KDC to authenticate itself to the database utilities, such as *kadmin, kadmind, krb5kdc*, and *kdb5_util*.
+A stash file allows a KDC to authenticate itself to the database
+utilities, such as kadmin, kadmind, krb5kdc, and kdb5_util.
-To create a stash file, use the :ref:`kdb5_util(8)` *stash* command.
+To create a stash file, use the :ref:`kdb5_util(8)` **stash** command.
.. include:: ../../admin_commands/kdb5_util.rst
- :start-after: _kdb5_util_stash:
+ :start-after: _kdb5_util_stash:
:end-before: _kdb5_util_stash_end:
+Example
+-------
-EXAMPLE::
+ shell% kdb5_util stash
+ kdb5_util: Cannot find/read stored master key while reading master key
+ kdb5_util: Warning: proceeding without master key
+ Enter KDC database master key: <= Type the KDC database master password.
+ shell%
- shell% kdb5_util stash
- kdb5_util: Cannot find/read stored master key while reading master key
- kdb5_util: Warning: proceeding without master key
- Enter KDC database master key: <= Type the KDC database master password.
- shell%
-
+If you do not specify a stash file, kdb5_util will stash the key in
+the file specified in your :ref:`kdc.conf` file.
-If you do not specify a stash file, *kdb5_util* will stash the key in the file specified in your :ref:`kdc.conf` file.
+Feedback
+--------
-
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
-
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_operations
Dumping a Kerberos database to a file
-=============================================
-
-To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)` **dump** command on one of the KDCs.
+=====================================
+To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)`
+**dump** command on one of the KDCs.
.. include:: ../../admin_commands/kdb5_util.rst
:start-after: _kdb5_util_dump:
:end-before: _kdb5_util_dump_end:
+Examples
+--------
-
-EXAMPLES::
+::
- shell% kdb5_util dump dumpfile
- shell%
+ shell% kdb5_util dump dumpfile
+ shell%
- shell% kbd5_util dump -verbose dumpfile
- kadmin/admin@ATHENA.MIT.EDU
- krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
- kadmin/history@ATHENA.MIT.EDU
- K/M@ATHENA.MIT.EDU
- kadmin/changepw@ATHENA.MIT.EDU
- shell%
-
+ shell% kbd5_util dump -verbose dumpfile
+ kadmin/admin@ATHENA.MIT.EDU
+ krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ kadmin/history@ATHENA.MIT.EDU
+ K/M@ATHENA.MIT.EDU
+ kadmin/changepw@ATHENA.MIT.EDU
+ shell%
-If you specify which principals to dump, you must use the full principal, as in the following example::
+If you specify which principals to dump, you must use the full
+principal, as in the following example::
- shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU
- kadmin/admin@ATHENA.MIT.EDU
- K/M@ATHENA.MIT.EDU
- shell%
-
+ shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU
+ kadmin/admin@ATHENA.MIT.EDU
+ K/M@ATHENA.MIT.EDU
+ shell%
-Otherwise, the principals will not match those in the database and will not be dumped::
+Otherwise, the principals will not match those in the database and
+will not be dumped::
shell% kdb5_util dump -verbose dumpfile K/M kadmin/admin
shell%
-
-
-If you do not specify a dump file, *kdb5_util* will dump the database to the standard output.
-
-There is currently a bug where the default dump format omits the per-principal policy information. In order to dump all the data contained in the Kerberos database, you must perform a normal dump (with no option flags) and an additional dump using the "-ov" flag to a different file.
+If you do not specify a dump file, kdb5_util will dump the database to
+the standard output.
-
-------------
+There is currently a bug where the default dump format omits the
+per-principal policy information. In order to dump all the data
+contained in the Kerberos database, you must perform a normal dump
+(with no option flags) and an additional dump using the "-ov" flag to
+a different file.
-Feedback:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_operations
.. _restore_from_dump:
-
Restoring a Kerberos database from a dump file
-================================================
+==============================================
-To restore a Kerberos database dump from a file, use the :ref:`kdb5_util(8)` **load** command on one of the KDCs.
+To restore a Kerberos database dump from a file, use the
+:ref:`kdb5_util(8)` **load** command on one of the KDCs.
.. include:: ../../admin_commands/kdb5_util.rst
:start-after: _kdb5_util_load:
:end-before: _kdb5_util_load_end:
-EXAMPLES::
+Examples
+--------
+
+::
shell% kdb5_util load dumpfile principal
shell%
-
shell% kdb5_util load -update dumpfile principal
shell%
-
-.. note:: If the database file exists, and the *-update* flag was not given, *kdb5_util* will overwrite the existing database.
-
-------------
+.. note:: If the database file exists, and the *-update* flag was not
+ given, *kdb5_util* will overwrite the existing database.
-Feedback:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_operations
.. _db_operations_label:
Operations on the Kerberos database
-=============================================
+===================================
-The :ref:`kdb5_util(8)` command is the primary tool for administrating the Kerberos database.
+The :ref:`kdb5_util(8)` command is the primary tool for administrating
+the Kerberos database.
.. include:: ../../admin_commands/kdb5_util.rst
:start-after: _kdb5_util_synopsys:
create_stash.rst
create_destroy_db.rst
-------------
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_operations
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_operations
-*kadmin* options
-=================
+kadmin options
+==============
-
-You can invoke **kadmin** or **kadmin.local** with any of the following options:
+You can invoke kadmin or kadmin.local with any of the following
+options:
.. include:: ../admin_commands/kadmin_local.rst
:start-after: kadmin_synopsys:
:end-before: _kadmin_options_end:
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db
.. _db_policies_label:
Policies
-=========================
-
-A policy is a set of rules governing passwords. Policies can dictate minimum and maximum password lifetimes, minimum number of characters and character classes a password must contain, and the number of old passwords kept in the database.
+========
+A policy is a set of rules governing passwords. Policies can dictate
+minimum and maximum password lifetimes, minimum number of characters
+and character classes a password must contain, and the number of old
+passwords kept in the database.
.. toctree::
:maxdepth: 1
update_histkey.rst
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
-
-
-
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_policies
Adding, modifying and deleting policies
-===================================================
+=======================================
-To add a new policy, use the *kadmin* **add_policy** command.
+To add a new policy, use the kadmin **add_policy** command.
-To modify attributes of a principal, use the *kadmin* **modify_policy** command.
+To modify attributes of a principal, use the kadmin **modify_policy**
+command.
+
+To delete a policy, use the kadmin **delete_policy** command.
-To delete a policy, use the *kadmin* **delete_policy** command.
-
.. include:: ../../admin_commands/kadmin_local.rst
:start-after: _add_policy:
:end-before: _add_policy_end:
-.. note:: The policies are created under *realm* container in the LDAP database.
+.. note:: The policies are created under **realm** container in the
+ LDAP database.
.. include:: ../../admin_commands/kadmin_local.rst
:start-after: _modify_policy:
:start-after: _delete_policy:
:end-before: _delete_policy_end:
-.. note:: You must cancel the policy from *all* principals before deleting it. The *delete_policy* command will fail if it is in use by any principals.
-
-
-
-
-------------
-
-Feedback:
+.. note:: You must cancel the policy from *all* principals before
+ deleting it. The *delete_policy* command will fail if it is
+ in use by any principals.
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_policies
Retrieving policies
-========================
+===================
-To retrieve a policy, use the *kadmin* **get_policy** command.
+To retrieve a policy, use the kadmin **get_policy** command.
-You can retrieve the list of policies with the *kadmin* **list_policies** command.
+You can retrieve the list of policies with the kadmin
+**list_policies** command.
.. include:: ../../admin_commands/kadmin_local.rst
:start-after: _get_policy:
:end-before: _get_policy_end:
-
.. include:: ../../admin_commands/kadmin_local.rst
:start-after: _list_policies:
:end-before: _list_policies_end:
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
-
-
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_policies
Updating the history key
-==================================
+========================
The following text is for release < 1.8.
-If a policy specifies a number of old keys kept of two or more, the stored old keys are encrypted in a history key, which is found in the key data of the *kadmin/history* principal.
+If a policy specifies a number of old keys kept of two or more, the
+stored old keys are encrypted in a history key, which is found in the
+key data of the *kadmin/history* principal.
-Currently there is no support for proper rollover of the history key, but you can change the history key (for example, to use a better encryption type) at the cost of invalidating currently stored old keys. To change the history key, run::
+Currently there is no support for proper rollover of the history key,
+but you can change the history key (for example, to use a better
+encryption type) at the cost of invalidating currently stored old
+keys. To change the history key, run::
kadmin: change_password -randkey kadmin/history
-
-This command will fail if you specify the *-keepold* flag. Only one new history key will be created, even if you specify multiple key/salt combinations.
+This command will fail if you specify the **-keepold** flag. Only one
+new history key will be created, even if you specify multiple key/salt
+combinations.
-In the future, we plan to migrate towards encrypting old keys in the master key instead of the history key, and implementing proper rollover support for stored old keys. - implemented in 1.8+
+In the future, we plan to migrate towards encrypting old keys in the
+master key instead of the history key, and implementing proper
+rollover support for stored old keys. - implemented in 1.8+
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_policies
Principals
-===============
+==========
-Each entry in the Kerberos database contains a Kerberos principal and the attributes and policies associated with that principal.
+Each entry in the Kerberos database contains a Kerberos principal and
+the attributes and policies associated with that principal.
.. toctree::
:maxdepth: 2
-
modify_princ.rst
info_princ.rst
priv_princ.rst
pass_princ.rst
-
Retrieving information about a principal
-=============================================
+========================================
-To retrieve a listing of the attributes and/or policies associated with a principal, use the *kadmin* **get_principal** command.
+To retrieve a listing of the attributes and/or policies associated
+with a principal, use the kadmin **get_principal** command.
-To generate a listing of principals, use the *kadmin* **list_principals** command.
+To generate a listing of principals, use the kadmin
+**list_principals** command.
.. include:: ../../admin_commands/kadmin_local.rst
:start-after: _get_principal:
.. include:: ../../admin_commands/kadmin_local.rst
:start-after: _list_principals:
:end-before: _list_principals_end:
-
-
-
Adding, modifying and deleting principals
============================================
-To add a principal to the database, use the *kadmin* **add_principal** command.
+To add a principal to the database, use the kadmin **add_principal**
+command.
-To modify attributes of a principal, use the *kadmin* **modify_principal** command.
-
-To delete a principal, use the *kadmin* **delete_principal** command.
+To modify attributes of a principal, use the kadmin
+**modify_principal** command.
+To delete a principal, use the kadmin **delete_principal** command.
.. include:: ../../admin_commands/kadmin_local.rst
:start-after: _add_principal:
:end-before: _delete_principal_end:
-EXAMPLES
-
-If you want to create a principal which is contained by a LDAP object, all you need to do is::
-
- kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com jennifer
- WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU";
- defaulting to no policy.
- Enter password for principal jennifer@ATHENA.MIT.EDU: <= Type the password.
- Re-enter password for principal jennifer@ATHENA.MIT.EDU: <=Type it again.
- Principal "jennifer@ATHENA.MIT.EDU" created.
- kadmin:
-
-If you want to create a principal under a specific LDAP container and link to an existing LDAP object, all you need to do is::
-
- kadmin: addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=david,dc=example,dc=com david
- WARNING: no policy specified for "david@ATHENA.MIT.EDU";
- defaulting to no policy.
- Enter password for principal david@ATHENA.MIT.EDU: <= Type the password.
- Re-enter password for principal david@ATHENA.MIT.EDU: <=Type it again.
- Principal "david@ATHENA.MIT.EDU" created.
- kadmin:
-
-If you want to associate a ticket policy to a principal, all you need to do is::
-
- kadmin: modprinc -x tktpolicy=userpolicy david
- Principal "david@ATHENA.MIT.EDU" modified.
- kadmin:
-
-If, on the other hand, you want to set up an account that expires on January 1, 2000, that uses a policy called "stduser", with a temporary password (which you want the user to change immediately), you would type the following::
-
-
- kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser +needchange
- Enter password for principal david@ATHENA.MIT.EDU: <= Type the password.
- Re-enter password for principal
- david@ATHENA.MIT.EDU: <= Type it again.
- Principal "david@ATHENA.MIT.EDU" created.
- kadmin:
-
-If you need cross-realm authentication, you will need to add principals for the other realm's TGT to each realm. For example, if you need to do cross-realm authentication between the realms *ATHENA.MIT.EDU* and *EXAMPLE.COM*, you would need to add the principals *krbtgt\/EXAMPLE.COM\@ATHENA.MIT.EDU* and *krbtgt\/ATHENA.MIT.EDU\@EXAMPLE.COM* to both databases. You need to be sure the passwords and the key version numbers (*kvno*) are the same in both databases. This may require explicitly setting the *kvno* with the *-kvno* option. See :ref:`xrealm_authn_label` for more details.
+Examples
+--------
+
+If you want to create a principal which is contained by a LDAP object,
+all you need to do is::
+
+ kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com jennifer
+ WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU";
+ defaulting to no policy.
+ Enter password for principal jennifer@ATHENA.MIT.EDU: <= Type the password.
+ Re-enter password for principal jennifer@ATHENA.MIT.EDU: <=Type it again.
+ Principal "jennifer@ATHENA.MIT.EDU" created.
+ kadmin:
+
+If you want to create a principal under a specific LDAP container and
+link to an existing LDAP object, all you need to do is::
+
+ kadmin: addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=david,dc=example,dc=com david
+ WARNING: no policy specified for "david@ATHENA.MIT.EDU";
+ defaulting to no policy.
+ Enter password for principal david@ATHENA.MIT.EDU: <= Type the password.
+ Re-enter password for principal david@ATHENA.MIT.EDU: <=Type it again.
+ Principal "david@ATHENA.MIT.EDU" created.
+ kadmin:
+
+If you want to associate a ticket policy to a principal, all you need
+to do is::
+
+ kadmin: modprinc -x tktpolicy=userpolicy david
+ Principal "david@ATHENA.MIT.EDU" modified.
+ kadmin:
+
+If, on the other hand, you want to set up an account that expires on
+January 1, 2000, that uses a policy called "stduser", with a temporary
+password (which you want the user to change immediately), you would
+type the following::
+
+ kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser +needchange
+ Enter password for principal david@ATHENA.MIT.EDU: <= Type the password.
+ Re-enter password for principal
+ david@ATHENA.MIT.EDU: <= Type it again.
+ Principal "david@ATHENA.MIT.EDU" created.
+ kadmin:
+
+If you need cross-realm authentication, you will need to add
+principals for the other realm's TGT to each realm. For example, if
+you need to do cross-realm authentication between the realms
+``ATHENA.MIT.EDU`` and ``EXAMPLE.COM``, you would need to add the
+principals ``krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU`` and
+``krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM`` to both databases. You need to
+be sure the passwords and the key version numbers (kvno) are the same
+in both databases. This may require explicitly setting the kvno with
+the **-kvno** option. See :ref:`xrealm_authn_label` for more details.
If you want to delete a principal ::
- kadmin: delprinc jennifer
- Are you sure you want to delete the principal
- "jennifer@ATHENA.MIT.EDU"? (yes/no): yes
- Principal "jennifer@ATHENA.MIT.EDU" deleted.
- Make sure that you have removed this principal from
- all ACLs before reusing.
- kadmin:
-
-
-------------
-
-Feedback:
+ kadmin: delprinc jennifer
+ Are you sure you want to delete the principal
+ "jennifer@ATHENA.MIT.EDU"? (yes/no): yes
+ Principal "jennifer@ATHENA.MIT.EDU" deleted.
+ Make sure that you have removed this principal from
+ all ACLs before reusing.
+ kadmin:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_princs
Changing passwords
-============================
+==================
+
+To change a principal's password use the kadmin **change_password**
+command.
-To change a principal's password use the *kadmin* **change_password** command.
-
.. include:: ../../admin_commands/kadmin_local.rst
:start-after: _change_password:
:end-before: _change_password_end:
-.. note:: *change_password* will not let you change the password to one that is in the principal's password history.
-
-
-
-
-
-
+.. note:: *change_password* will not let you change the password to
+ one that is in the principal's password history.
.. _privileges_label:
Privileges
-===============
+==========
-Administrative privileges for the Kerberos database are stored in the file **kadm5.acl**.
+Administrative privileges for the Kerberos database are stored in the
+file kadm5.acl.
The format of the file is::
- Kerberos_principal permissions [target_principal] [restrictions]
-
-The Kerberos principal (and optional target principal) can include the "\*" wildcard, so if you want any principal with the instance "admin" to have full permissions on the database, you could use the principal "\*\/admin\@REALM" where "REALM" is your Kerberos realm. *target_principal* can also include backreferences to *Kerberos_principal*, in which "number" matches the component number in the *Kerberos_principal*.
+ Kerberos_principal permissions [target_principal] [restrictions]
-.. note:: A common use of an admin instance is so you can grant separate permissions (such as administrator access to the Kerberos database) to a separate Kerberos principal. For example, the user *joeadmin* might have a principal for his administrative use, called *joeadmin/admin*. This way, *joeadmin* would obtain *joeadmin/admin* tickets only when he actually needs to use those permissions.
+The Kerberos principal (and optional target principal) can include the
+``*`` wildcard, so if you want any principal with the instance
+``admin`` to have full permissions on the database, you could use the
+principal ``*/admin@REALM`` where *REALM* is your Kerberos realm.
+*target_principal* can also include backreferences to
+*Kerberos_principal*, in which "number" matches the component number
+in the *Kerberos_principal*.
-|
+.. note:: A common use of an admin instance is so you can grant
+ separate permissions (such as administrator access to the
+ Kerberos database) to a separate Kerberos principal. For
+ example, the user ``joeadmin`` might have a principal for
+ his administrative use, called ``joeadmin/admin``. This
+ way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets
+ only when he actually needs to use those permissions.
-The permissions are represented by single letters; UPPER-CASE letters represent negative permissions. The permissions are:
+
+Permissions
+-----------
+
+The permissions are represented by single letters; UPPER-CASE letters
+represent negative permissions. The permissions are:
=== =====================================
a allows the addition of principals or policies in the database.
x All privileges (admcil); identical to "\*".
=== =====================================
-|
-The restrictions are a string of flags. Allowed restrictions are:
+Restrictions
+------------
+
+The restrictions are a string of flags. Allowed restrictions are:
======================== ============================
[+\|-]flagname flag is forced to indicated value. The permissible flags are the same as the + and - flags for the kadmin addprinc and modprinc commands.
-maxrenewlife time associated value will be forced to MIN(time, requested value)
======================== ============================
-The above flags act as restrictions on any add or modify operation which is allowed due to that ACL line.
-
-|
+The above flags act as restrictions on any add or modify operation
+which is allowed due to that ACL line.
Here is an example of a *kadm5.acl* file::
- */admin@ATHENA.MIT.EDU *
- joeadmin@ATHENA.MIT.EDU ADMCIL
- joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU
- *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU
- */*@ATHENA.MIT.EDU i
- */admin@EXAMPLE.COM * -maxlife 9h -postdateable
-
-.. note:: The order is important; permissions are determined by the first matching entry.
-
-In the above file, any principal in the *ATHENA.MIT.EDU* realm with an admin instance has all administrative privileges. The user *joeadmin* has all permissions with his admin instance, *joeadmin/admin@ATHENA.MIT.EDU* (matches the first line). He has no permissions at all with his null instance, *joeadmin@ATHENA.MIT.EDU* (matches the second line). His root instance has inquire and list permissions with any other principal that has the instance root. Any principal in *ATHENA.MIT.EDU* can inquire, list, or change the password of their admin instance, but not any other admin instance. Any principal in the realm *ATHENA.MIT.EDU* (except for *joeadmin@ATHENA.MIT.EDU*, as mentioned above) has inquire privileges. Finally, any principal with an admin instance in EXAMPLE.COM has all permissions, but any principal that they create or modify will not be able to get postdateable tickets or tickets with a life of longer than 9 hours.
-
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
-
-
+ */admin@ATHENA.MIT.EDU *
+ joeadmin@ATHENA.MIT.EDU ADMCIL
+ joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU
+ *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU
+ */*@ATHENA.MIT.EDU i
+ */admin@EXAMPLE.COM * -maxlife 9h -postdateable
+
+.. note:: The order is important; permissions are determined by the
+ first matching entry.
+
+In the above file, any principal in the ``ATHENA.MIT.EDU`` realm with
+an admin instance has all administrative privileges. The user
+``joeadmin`` has all permissions with his admin instance,
+``joeadmin/admin@ATHENA.MIT.EDU`` (matches the first line). He has no
+permissions at all with his null instance, ``joeadmin@ATHENA.MIT.EDU``
+(matches the second line). His root instance has inquire and list
+permissions with any other principal that has the instance root. Any
+principal in ``ATHENA.MIT.EDU`` can inquire, list, or change the
+password of their admin instance, but not any other admin instance.
+Any principal in the realm ``ATHENA.MIT.EDU`` (except for
+``joeadmin@ATHENA.MIT.EDU``, as mentioned above) has inquire
+privileges. Finally, any principal with an admin instance in
+EXAMPLE.COM has all permissions, but any principal that they create or
+modify will not be able to get postdateable tickets or tickets with a
+life of longer than 9 hours.
+
+
+Feedback
+--------
+
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_princs
.. _incr_db_prop_label:
-
-
Incremental database propagation
-====================================
+================================
-.. note:: This document was copied from **Kerberos V5 Installation Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+.. note:: This document was copied from **Kerberos V5 Installation
+ Guide** with minor changes. Currently it is under review.
+ Please, send your feedback, corrections and additions to
+ krb5-bugs@mit.edu. Your contribution is greatly
+ appreciated.
Overview
-----------
-
-At some very large sites, dumping and transmitting the database can take more time than is desirable for changes to propagate from the master KDC to the slave KDCs. The incremental propagation support added in the 1.7 release is intended to address this.
-
-With incremental propagation enabled, all programs on the master KDC that change the database also write information about the changes to an "update log" file, maintained as a circular buffer of a certain size. A process on each slave KDC connects to a service on the master KDC (currently implmented in the kadmind server) and periodically requests the changes that have been made since the last check. By default, this check is done every two minutes. If the database has just been modified in the previous several seconds (currently the threshold is hard-coded at 10 seconds), the slave will not retrieve updates, but instead will pause and try again soon after. This reduces the likelihood that incremental update queries will cause delays for an administrator trying to make a bunch of changes to the database at the same time.
-
-Incremental propagation uses the following entries in the per-realm data in the KDC config file (See :ref:`kdc.conf`):
+--------
+
+At some very large sites, dumping and transmitting the database can
+take more time than is desirable for changes to propagate from the
+master KDC to the slave KDCs. The incremental propagation support
+added in the 1.7 release is intended to address this.
+
+With incremental propagation enabled, all programs on the master KDC
+that change the database also write information about the changes to
+an "update log" file, maintained as a circular buffer of a certain
+size. A process on each slave KDC connects to a service on the master
+KDC (currently implmented in the kadmind server) and periodically
+requests the changes that have been made since the last check. By
+default, this check is done every two minutes. If the database has
+just been modified in the previous several seconds (currently the
+threshold is hard-coded at 10 seconds), the slave will not retrieve
+updates, but instead will pause and try again soon after. This
+reduces the likelihood that incremental update queries will cause
+delays for an administrator trying to make a bunch of changes to the
+database at the same time.
+
+Incremental propagation uses the following entries in the per-realm
+data in the KDC config file (See :ref:`kdc.conf`):
====================== =============== ===========================================
iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*.
iprop_master_ulogsize *integer* Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500.
iprop_slave_poll *time interval* Indicates how often the slave should poll the master KDC for changes to the database. The default is two minutes.
iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and slave configuration files.
-iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc.conf`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.)
+iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc.conf`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.)
====================== =============== ===========================================
-Both master and slave sides must have principals named *kiprop/hostname* (where *hostname* is, as usual, the lower-case, fully-qualified, canonical name for the host) registered and keys stored in the default keytab file (/etc/krb5.keytab).
-
-On the master KDC side, the *kiprop/hostname* principal must be listed in the *kadmind* ACL file *kadm5.acl*, and given the *p* privilege (See :ref:`privileges_label`)
-
-On the slave KDC side, *kpropd* should be run. When incremental propagation is enabled, it will connect to the *kadmind* on the master KDC and start requesting updates.
+Both master and slave sides must have principals named
+``kiprop/hostname`` (where *hostname* is, as usual, the lower-case,
+fully-qualified, canonical name for the host) registered and keys
+stored in the default keytab file (``/etc/krb5.keytab``).
+
+On the master KDC side, the ``kiprop/hostname`` principal must be
+listed in the kadmind ACL file kadm5.acl, and given the **p**
+privilege (See :ref:`privileges_label`)
+
+On the slave KDC side, kpropd should be run. When incremental
+propagation is enabled, it will connect to the kadmind on the master
+KDC and start requesting updates.
+
+The normal kprop mechanism is disabled by the incremental propagation
+support. However, if the slave has been unable to fetch changes from
+the master KDC for too long (network problems, perhaps), the log on
+the master may wrap around and overwrite some of the updates that the
+slave has not yet retrieved. In this case, the slave will instruct
+the master KDC to dump the current database out to a file and invoke a
+one-time kprop propagation, with special options to also convey the
+point in the update log at which the slave should resume fetching
+incremental updates. Thus, all the keytab and ACL setup previously
+described for kprop propagation is still needed.
+
+There are several known bugs and restrictions in the current
+implementation:
+
+- The "call out to kprop" mechanism is a bit fragile; if the kprop
+ propagation fails to connect for some reason, the process on the
+ slave may hang waiting for it, and will need to be restarted.
+- The master and slave must be able to initiate TCP connections in
+ both directions, without an intervening NAT. They must also be able
+ to communicate over IPv4, since MIT's kprop and RPC code does not
+ currently support IPv6.
-The normal *kprop* mechanism is disabled by the incremental propagation support. However, if the slave has been unable to fetch changes from the master KDC for too long (network problems, perhaps), the log on the master may wrap around and overwrite some of the updates that the slave has not yet retrieved. In this case, the slave will instruct the master KDC to dump the current database out to a file and invoke a one-time kprop propagation, with special options to also convey the point in the update log at which the slave should resume fetching incremental updates. Thus, all the keytab and ACL setup previously described for kprop propagation is still needed.
-
-There are several known bugs and restrictions in the current implementation:
-
-- The "call out to kprop" mechanism is a bit fragile; if the kprop propagation fails to connect for some reason, the process on the slave may hang waiting for it, and will need to be restarted.
-- The master and slave must be able to initiate TCP connections in both directions, without an intervening NAT. They must also be able to communicate over IPv4, since MIT's kprop and RPC code does not currently support IPv6.
-- Sun/MIT Incremental Propagation Differences:
Sun/MIT incremental propagation differences
-----------------------------------------------
-
-Sun donated the original code for supporting incremental database propagation to MIT. Some changes have been made in the MIT source tree that will be visible to administrators. (These notes are based on Sun's patches. Changes to Sun's implementation since then may not be reflected here.)
-
-The Sun config file support looks for *sunw_dbprop_enable, sunw_dbprop_master_ulogsize,* and *sunw_dbprop_slave_poll*.
-
-The incremental propagation service is implemented as an ONC RPC service. In the Sun implementation, the service is registered with *rpcbind* (also known as portmapper) and the client looks up the port number to contact. In the MIT implementation, where interaction with some modern versions of *rpcbind* doesn't always work well, the port number must be specified in the config file on both the master and slave sides.
-
-The Sun implementation hard-codes pathnames in */var/krb5* for the update log and the per-slave kprop dump files. In the MIT implementation, the pathname for the update log is specified in the config file, and the per-slave dump files are stored in */usr/local/var/krb5kdc/slave_datatrans_hostname*.
+-------------------------------------------
+
+Sun donated the original code for supporting incremental database
+propagation to MIT. Some changes have been made in the MIT source
+tree that will be visible to administrators. (These notes are based
+on Sun's patches. Changes to Sun's implementation since then may not
+be reflected here.)
+
+The Sun config file support looks for ``sunw_dbprop_enable``,
+``sunw_dbprop_master_ulogsize``, and ``sunw_dbprop_slave_poll``.
+
+The incremental propagation service is implemented as an ONC RPC
+service. In the Sun implementation, the service is registered with
+rpcbind (also known as portmapper) and the client looks up the port
+number to contact. In the MIT implementation, where interaction with
+some modern versions of rpcbind doesn't always work well, the port
+number must be specified in the config file on both the master and
+slave sides.
+
+The Sun implementation hard-codes pathnames in ``/var/krb5`` for the
+update log and the per-slave kprop dump files. In the MIT
+implementation, the pathname for the update log is specified in the
+config file, and the per-slave dump files are stored in
+``/usr/local/var/krb5kdc/slave_datatrans_hostname``.
Database administration
-======================================
+=======================
-.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+.. note:: This document was copied from **Kerberos V5 System
+ Administrator's Guide** with minor changes. Currently it is
+ under review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is
+ greatly appreciated.
-Your Kerberos database contains all of your realm's Kerberos principals, their passwords, and other administrative information about each principal. For the most part, you will use the :ref:`kdb5_util(8)` program to manipulate the Kerberos database as a whole, and the kadmin program to make changes to the entries in the database. (One notable exception is that users will use the :ref:`kpasswd(1)` program to change their own passwords.) The kadmin program has its own command-line interface, to which you type the database administrating commands.
+Your Kerberos database contains all of your realm's Kerberos
+principals, their passwords, and other administrative information
+about each principal. For the most part, you will use the
+:ref:`kdb5_util(8)` program to manipulate the Kerberos database as a
+whole, and the kadmin program to make changes to the entries in the
+database. (One notable exception is that users will use the
+:ref:`kpasswd(1)` program to change their own passwords.) The kadmin
+program has its own command-line interface, to which you type the
+database administrating commands.
-:ref:`kdb5_util(8)` provides a means to create, delete, load, or dump a Kerberos database. It also includes a command to stash a copy of the master database key in a file on a KDC, so that the KDC can authenticate itself to the *kadmind* and *krb5kdc* daemons at boot time.
+:ref:`kdb5_util(8)` provides a means to create, delete, load, or dump
+a Kerberos database. It also includes a command to stash a copy of
+the master database key in a file on a KDC, so that the KDC can
+authenticate itself to the kadmind and krb5kdc daemons at boot time.
-*kadmin* provides for the maintenance of Kerberos principals, KADM5 policies, and service key tables (*keytabs*). It exists as both a Kerberos client, *kadmin*, using Kerberos authentication and an RPC, to operate securely from anywhere on the network, and as a local client, *kadmin.local*, intended to run directly on the KDC without Kerberos authentication. *kadmin.local* need not run on the kdc if the database is LDAP. Other than the fact that the remote client uses Kerberos to authenticate the person using it, the functionalities of the two versions are identical. The local version is necessary to enable you to set up enough of the database to be able to use the remote version. It replaces the now obsolete kdb5_edit (except for database dump and load, which are provided by *kdb5_util*).
+kadmin provides for the maintenance of Kerberos principals, KADM5
+policies, and service key tables (keytabs). It exists as both a
+Kerberos client, kadmin, using Kerberos authentication and an RPC, to
+operate securely from anywhere on the network, and as a local client,
+kadmin.local, intended to run directly on the KDC without Kerberos
+authentication. kadmin.local need not run on the kdc if the database
+is LDAP. Other than the fact that the remote client uses Kerberos to
+authenticate the person using it, the functionalities of the two
+versions are identical. The local version is necessary to enable you
+to set up enough of the database to be able to use the remote version.
+It replaces the now obsolete kdb5_edit (except for database dump and
+load, which are provided by kdb5_util).
-The remote version 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* ccache option is specified, that ticket is used to authenticate to KADM5. 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.
+The remote version 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** ccache option is
+specified, that ticket is used to authenticate to KADM5. 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.
-See :ref:`kadmin(1)` for the available *kadmin* and *kadmin.local* commands and options.
+See :ref:`kadmin(1)` for the available kadmin and kadmin.local
+commands and options.
.. toctree::
:maxdepth: 2
change_tgtkey.rst
incr_db_prop.rst
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db
.. _edir_create_realm_label:
-
eDir: Creating a Kerberos realm
-=================================
+===============================
See :ref:`ldap_create_realm_label`
-The following are the eDirectory specific options
+The following are the eDirectory specific options:
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_create_edir:
:end-before: _kdb5_ldap_util_create_edir_end:
-
EXAMPLE::
- shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create -sscope 2
- -subtree ou=users,dc=example,dc=com -kdcdn cn=krbkdc,dc=example,dc=com -admindn cn=krbadmin,dc=example,dc=com -r ATHENA.MIT.EDU
+ shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create -sscope 2
+ -subtree ou=users,dc=example,dc=com -kdcdn cn=krbkdc,dc=example,dc=com -admindn cn=krbadmin,dc=example,dc=com -r ATHENA.MIT.EDU
- Password for "cn=admin,dc=example,dc=com":
- Initializing database for realm 'ATHENA.MIT.EDU'
- You will be prompted for the database Master Password.
- It is important that you NOT FORGET this password.
- Enter KDC database master key:
- Re-enter KDC database master key to verify:
- shell%
-
+ Password for "cn=admin,dc=example,dc=com":
+ Initializing database for realm 'ATHENA.MIT.EDU'
+ You will be prompted for the database Master Password.
+ It is important that you NOT FORGET this password.
+ Enter KDC database master key:
+ Re-enter KDC database master key to verify:
+ shell%
.. _edir_mod_realm_label:
eDir: Modifying a Kerberos realm
-=================================
+================================
See :ref:`ldap_mod_realm_label`
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_modify_edir:
:end-before: _kdb5_ldap_util_modify_edir_end:
-
-
-------------
-
-Feedback:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___edir
eDir: Creating a Service Object
-========================================
+===============================
-To create a service object in eDirectory and assign appropriate rights on the container holding kerberos data, use the :ref:`kdb5_ldap_util(8)` **create_service** command.
+To create a service object in eDirectory and assign appropriate rights
+on the container holding kerberos data, use the
+:ref:`kdb5_ldap_util(8)` **create_service** command.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_create_service:
:end-before: _kdb5_ldap_util_create_service_end:
-eDir: Modifying a Service Object
-=================================
+eDir: Modifying a Service Object
+================================
-To modify the attributes of a service and assign appropriate rights, if realm associations are changed, use the :ref:`kdb5_ldap_util(8)` **modify_service** command.
+To modify the attributes of a service and assign appropriate rights,
+if realm associations are changed, use the :ref:`kdb5_ldap_util(8)`
+**modify_service** command.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_modify_service:
eDir: Retrieving Service Object Information
-==============================================================
+===========================================
-To display the attributes of a service, use the :ref:`kdb5_ldap_util(8)` **view_service** command.
+To display the attributes of a service, use the
+:ref:`kdb5_ldap_util(8)` **view_service** command.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_view_service:
eDir: Destroying a Service Object
-===================================
-
+=================================
-The :ref:`kdb5_ldap_util(8)` **destroy_service** command is used to destroy an existing service.
+The :ref:`kdb5_ldap_util(8)` **destroy_service** command is used to
+destroy an existing service.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_destroy_service:
:end-before: _kdb5_ldap_util_destroy_service_end:
-eDir: Listing Available Service Objects
-===========================================
+eDir: Listing Available Service Objects
+=======================================
-The :ref:`kdb5_ldap_util(8)` **list_service** command lists the name of services under a given base in eDirectory.
+The :ref:`kdb5_ldap_util(8)` **list_service** command lists the name
+of services under a given base in eDirectory.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_list_service:
eDir: Passwords for Service Objects
-============================================
+===================================
-The command :ref:`kdb5_ldap_util(8)` **setsrvpw** allows an administrator to set password for service objects such as KDC and Administration server in eDirectory and store them in a file.
+The command :ref:`kdb5_ldap_util(8)` **setsrvpw** allows an
+administrator to set password for service objects such as KDC and
+Administration server in eDirectory and store them in a file.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_setsrvpw:
:end-before: _kdb5_ldap_util_setsrvpw_end:
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___edir
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___edir
.. _ops_on_ldap_label:
Operations on the LDAP database
-===================================================
+===============================
-The *kdb5_ldap_util* is the primary tool for administrating the Kerberos LDAP database. It allows an administrator to manage realms, Kerberos services ( KDC and Admin Server) and ticket policies.
+The kdb5_ldap_util is the primary tool for administrating the Kerberos
+LDAP database. It allows an administrator to manage realms, Kerberos
+services (KDC and Admin Server) and ticket policies.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_synopsis:
:end-before: _kdb5_ldap_util_options_end:
-
-
LDAP
-----------
+----
.. toctree::
:maxdepth: 2
eDirectory
------------
+----------
.. toctree::
:maxdepth: 1
edir_create_realm.rst
edir_create_so.rst
-
-
.. _ldap_create_realm_label:
Creating a Kerberos realm
-================================
+=========================
-If you need to create a new realm, use the :ref:`kdb5_ldap_util(8)` **create** command as follows.
+If you need to create a new realm, use the :ref:`kdb5_ldap_util(8)`
+**create** command as follows.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_create:
:end-before: _kdb5_ldap_util_create_end:
-
.. seealso:: :ref:`edir_create_realm_label`
-------------
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_ldap
Destroying a Kerberos realm
-===============================================
+===========================
-
-If you need to destroy a Kerberos realm, use the :ref:`kdb5_ldap_util(8)` **destroy** command as follows.
+If you need to destroy a Kerberos realm, use the
+:ref:`kdb5_ldap_util(8)` **destroy** command as follows.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_destroy:
:end-before: _kdb5_ldap_util_destroy_end:
-
-
-
-------------
-
-Feedback:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_ldap
.. _ldap_mod_realm_label:
Modifying a Kerberos realm
-==================================
+==========================
-If you need to modify a realm, use the :ref:`kdb5_ldap_util(8)` **modify** command as follows.
+If you need to modify a realm, use the :ref:`kdb5_ldap_util(8)`
+**modify** command as follows.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_modify:
:end-before: _kdb5_ldap_util_modify_end:
-
.. seealso:: :ref:`edir_mod_realm_label`
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
-
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_ldap
Retrieving information about a Kerberos realm
-===============================================
+=============================================
-If you need to display the attributes of a realm, use the :ref:`kdb5_ldap_util(8)` **view** command as follows.
+If you need to display the attributes of a realm, use the
+:ref:`kdb5_ldap_util(8)` **view** command as follows.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_view:
:end-before: _kdb5_ldap_util_view_end:
-
+Feedback
+--------
-
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
-
-
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_ldap
Listing available Kerberos realms
-===============================================
+=================================
-If you need to display the list of the realms, use the :ref:`kdb5_ldap_util(8)` **list** command as follows.
+If you need to display the list of the realms, use the
+:ref:`kdb5_ldap_util(8)` **list** command as follows.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_list:
:end-before: _kdb5_ldap_util_list_end:
-
-
-
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_ldap
.. _stash_ldap_label:
Stashing service object's password
-========================================
+==================================
-
-The :ref:`kdb5_ldap_util(8)` **stashsrvpw** command allows an administrator to store the password of service object in a file.
-The KDC and Administration server uses this password to authenticate to the LDAP server.
+The :ref:`kdb5_ldap_util(8)` **stashsrvpw** command allows an
+administrator to store the password of service object in a file. The
+KDC and Administration server uses this password to authenticate to
+the LDAP server.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_list:
:end-before: _kdb5_ldap_util_list_end:
-
-------------
-
-Feedback:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_ldap
Ticket Policy operations
-===========================
+========================
Creating a Ticket Policy
-------------------------------------------
+------------------------
-To create a new ticket policy in directory , use the :ref:`kdb5_ldap_util(8)` **create_policy** command.
-Ticket policy objects are created under the realm container.
+To create a new ticket policy in directory , use the
+:ref:`kdb5_ldap_util(8)` **create_policy** command. Ticket policy
+objects are created under the realm container.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_create_policy:
Modifying a Ticket Policy
-------------------------------------------
+-------------------------
+
+To modify a ticket policy in directory, use the
+:ref:`kdb5_ldap_util(8)` **modify_policy** command.
-To modify a ticket policy in directory , use the :ref:`kdb5_ldap_util(8)` **modify_policy** command.
-
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_modify_policy:
:end-before: _kdb5_ldap_util_modify_policy_end:
Retrieving Information About a Ticket Policy
----------------------------------------------
-
+--------------------------------------------
-To display the attributes of a ticket policy, use the :ref:`kdb5_ldap_util(8)` **view_policy** command.
+To display the attributes of a ticket policy, use the
+:ref:`kdb5_ldap_util(8)` **view_policy** command.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_view_policy:
:end-before: _kdb5_ldap_util_view_policy_end:
-
Destroying a Ticket Policy
---------------------------------
+--------------------------
-To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)` **destroy_policy** command.
+To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)`
+**destroy_policy** command.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_destroy_policy:
Listing available Ticket Policies
------------------------------------
+---------------------------------
-To list the name of ticket policies in a realm, use the :ref:`kdb5_ldap_util(8)` **list_policy** command.
+To list the name of ticket policies in a realm, use the
+:ref:`kdb5_ldap_util(8)` **list_policy** command.
.. include:: ../../admin_commands/kdb5_ldap_util.rst
:start-after: _kdb5_ldap_util_destroy_policy:
:end-before: _kdb5_ldap_util_destroy_policy_end:
+Feedback
+--------
-
-
-
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_ldap
-
-
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db_ldap
.. _xrealm_authn_label:
Cross-realm authentication
-============================
-
-In order for a KDC in one realm to authenticate Kerberos users in a different realm, it must share a key with the KDC in the other realm. In both databases, there must be krbtgt service principals for realms. These principals should all have the same passwords, key version numbers, and encryption types.
-
-For example, if the administrators of ATHENA.MIT.EDU and EXAMPLE.COM wanted to authenticate across the realms, they would run the following commands on the KDCs in both realms::
-
- shell%: kadmin.local -e "des3-hmac-sha1:normal des-cbc-crc:v4"
- kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM
- Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
- Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
- kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
- Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
- Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
- kadmin:
-
-.. note:: Even if most principals in a realm are generally created with the *requires_preauth* flag enabled, this flag is not desirable on cross-realm authentication keys because doing so makes it impossible to disable preauthentication on a service-by-service basis. Disabling it as in the example above is recommended.
-
-
-.. note:: It is very important that these principals have good passwords. MIT recommends that TGT principal passwords be at least 26 characters of random ASCII textck:
-
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
-
-
+==========================
+
+In order for a KDC in one realm to authenticate Kerberos users in a
+different realm, it must share a key with the KDC in the other realm.
+In both databases, there must be krbtgt service principals for realms.
+These principals should all have the same passwords, key version
+numbers, and encryption types.
+
+For example, if the administrators of ATHENA.MIT.EDU and EXAMPLE.COM
+wanted to authenticate across the realms, they would run the following
+commands on the KDCs in both realms::
+
+ shell%: kadmin.local -e "des3-hmac-sha1:normal des-cbc-crc:v4"
+ kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM
+ Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
+ Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
+ kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
+ Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
+ Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
+ kadmin:
+
+.. note:: Even if most principals in a realm are generally created
+ with the **requires_preauth** flag enabled, this flag is not
+ desirable on cross-realm authentication keys because doing
+ so makes it impossible to disable preauthentication on a
+ service-by-service basis. Disabling it as in the example
+ above is recommended.
+
+.. note:: It is very important that these principals have good
+ passwords. MIT recommends that TGT principal passwords be
+ at least 26 characters of random ASCII text.
+
+
+Feedback
+--------
+
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___db
.. _udns_label:
Using DNS
-=========================
-
-.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+=========
+.. note:: This document was copied from **Kerberos V5 System
+ Administrator's Guide** with minor changes. Currently it is
+ under review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is
+ greatly appreciated.
See :ref:`mapping_hn_label`
See :ref:`kdc_hn_label`
-------------------
-
Feedback
+--------
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___admin_dns
-
-
-
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___admin_dns
Environment variables
-==========================
+=====================
The following environment variables can be used during runtime:
+**KRB5_CONFIG**
+ Main Kerberos configuration file. (See :ref:`mitK5defaults` for
+ the default name)
-**KRB5_CONFIG**
- Main Kerberos configuration file.
- (See :ref:`mitK5defaults` for the default name)
+**KRB5_KDC_PROFILE**
+ KDC configuration file. (See :ref:`mitK5defaults` for the default
+ name)
-**KRB5_KDC_PROFILE**
- KDC configuration file.
- (See :ref:`mitK5defaults` for the default name)
+**KRB5_KTNAME**
+ Default *keytab* file name. (See :ref:`mitK5defaults` for the
+ default name)
-**KRB5_KTNAME**
- Default *keytab* file name.
- (See :ref:`mitK5defaults` for the default name)
-
-**KRB5CCNAME**
- Default name for the credentials cache file, in the form *type:residual*.
- The type of the default cache may determine the availability of a cache collection.
- For instance, a default cache of type DIR causes caches within the directory
- to be present in the global cache collection.
+**KRB5CCNAME**
+ Default name for the credentials cache file, in the form *type*\:\
+ *residual*. The type of the default cache may determine the
+ availability of a cache collection. For instance, a default cache
+ of type DIR causes caches within the directory to be present in
+ the global cache collection.
**KRB5RCACHETYPE**
- Default replay cache type. Defaults to "dfl".
+ Default replay cache type. Defaults to "dfl".
- E.g. *KRB5RCACHETYPE="none"*
+ E.g. ``KRB5RCACHETYPE=none``
-**KRB5RCACHENAME**
- Default replay cache name.
- (See :ref:`mitK5defaults` for the default name)
+**KRB5RCACHENAME**
+ Default replay cache name. (See :ref:`mitK5defaults` for the
+ default name)
-**KRB5RCACHEDIR**
- Default replay cache directory.
- (See :ref:`mitK5defaults` for the default location)
+**KRB5RCACHEDIR**
+ Default replay cache directory. (See :ref:`mitK5defaults` for the
+ default location)
-**KPROP_PORT**
- *kprop* port to use. Defaults to 754.
+**KPROP_PORT**
+ *kprop* port to use. Defaults to 754.
-**KRB5_TRACE**
- Debugging and tracing. (Introduced in release 1.9)
+**KRB5_TRACE**
+ Debugging and tracing. (Introduced in release 1.9)
- E.g. *KRB5_TRACE=/dev/stdout kinit*
+ E.g. *KRB5_TRACE=/dev/stdout kinit*
- The setting of this environment variable can be overridden by
- the tracing behavior set by the application using either of the following API:
+ The setting of this environment variable can be overridden by
+ the tracing behavior set by the application using either of the following API:
- - :c:func:`krb5_set_trace_callback()` or
- - :c:func:`krb5_set_trace_filename()`
+ * :c:func:`krb5_set_trace_callback()` or
+ * :c:func:`krb5_set_trace_filename()`
-------------------
Feedback
+--------
-
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___env
-
-
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___env
For administrators
-============================
-
+==================
Contents:
---------
-
.. toctree::
:maxdepth: 1
appl_servers/index.rst
backup_host.rst
-
.. toctree::
:maxdepth: 1
various_envs.rst
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___admin
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___admin
Installation guide
-===================
-
-.. note:: This document was copied from **Kerberos V5 Installation Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+==================
+.. note:: This document was copied from **Kerberos V5 Installation
+ Guide** with minor changes. Currently it is under
+ review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is greatly
+ appreciated.
Contents
----------
+--------
.. toctree::
:maxdepth: 2
install_appl_srv.rst
-
Additional references
-----------------------
-
+---------------------
-#. Debian Setting up of Kerberos <http://techpubs.spinlocksolutions.com/dklar/kerberos.html>_
-#. Solaris Configuring the Kerberos Service <http://download.oracle.com/docs/cd/E19253-01/816-4557/6maosrjv2/index.html >_
+#. Debian: `Setting up MIT Kerberos 5
+ <http://techpubs.spinlocksolutions.com/dklar/kerberos.html>`_
+#. Solaris: `Configuring the Kerberos Service
+ <http://download.oracle.com/docs/cd/E19253-01/816-4557/6maosrjv2/index.html>`_
-------------------
Feedback
+--------
-
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___install_guide
-
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___install_guide
UNIX Application Servers
-================================
+========================
-An application server is a host that provides one or more services over the network. Application servers can be "secure" or "insecure." A "secure" host is set up to require authentication from every client connecting to it. An "insecure" host will still provide Kerberos authentication, but will also allow unauthenticated clients to connect.
+An application server is a host that provides one or more services
+over the network. Application servers can be "secure" or "insecure."
+A "secure" host is set up to require authentication from every client
+connecting to it. An "insecure" host will still provide Kerberos
+authentication, but will also allow unauthenticated clients to
+connect.
-If you have Kerberos V5 installed on all of your client machines, MIT recommends that you make your hosts secure, to take advantage of the security that Kerberos authentication affords. However, if you have some clients that do not have Kerberos V5 installed, you can run an insecure server, and still take advantage of Kerberos V5's single sign-on capability.
+If you have Kerberos V5 installed on all of your client machines, MIT
+recommends that you make your hosts secure, to take advantage of the
+security that Kerberos authentication affords. However, if you have
+some clients that do not have Kerberos V5 installed, you can run an
+insecure server, and still take advantage of Kerberos V5's single
+sign-on capability.
-.. _kt_file_label:
+.. _kt_file_label:
The keytab file
-----------------------
-
-All Kerberos server machines need a *keytab* file to authenticate to the KDC. By default on UNIX-like systems this file is named */etc/krb5.keytab*. The keytab file is an encrypted, local, on-disk copy of the host's key. The keytab file, like the stash file (See :ref:`create_db_label`) is a potential point-of-entry for a break-in, and if compromised, would allow unrestricted access to its host. The *keytab* file should be readable only by root, and should exist only on the machine's local disk. The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the machine's root password itself.
-
-
-In order to generate a *keytab* for a host, the host must have a principal in the Kerberos database. The procedure for adding hosts to the database is described fully in :ref:`add_mod_del_princs_label`. (See :ref:`slave_host_key_label` for a brief description.) The *keytab* is generated by running *kadmin* and issuing the :ref:`ktadd` command.
-
-For example, to generate a *keytab* file to allow the host *trillium.mit.edu* to authenticate for the services host, ftp, and pop, the administrator *joeadmin* would issue the command (on *trillium.mit.edu*)::
-
- trillium% /usr/local/sbin/kadmin
- kadmin5: ktadd host/trillium.mit.edu ftp/trillium.mit.edu pop/trillium.mit.edu
- kadmin: Entry for principal host/trillium.mit.edu@ATHENA.MIT.EDU with
- kvno 3, encryption type DES-CBC-CRC added to keytab
- WRFILE:/etc/krb5.keytab.
- kadmin: Entry for principal ftp/trillium.mit.edu@ATHENA.MIT.EDU with
- kvno 3, encryption type DES-CBC-CRC added to keytab
- WRFILE:/etc/krb5.keytab.
- kadmin: Entry for principal pop/trillium.mit.edu@ATHENA.MIT.EDU with
- kvno 3, encryption type DES-CBC-CRC added to keytab
- WRFILE:/etc/krb5.keytab.
- kadmin5: quit
- trillium%
-
+---------------
+
+All Kerberos server machines need a keytab file to authenticate to the
+KDC. By default on UNIX-like systems this file is named
+``/etc/krb5.keytab``. The keytab file is an encrypted, local, on-disk
+copy of the host's key. The keytab file, like the stash file (See
+:ref:`create_db_label`) is a potential point-of-entry for a break-in,
+and if compromised, would allow unrestricted access to its host. The
+keytab file should be readable only by root, and should exist only on
+the machine's local disk. The file should not be part of any backup
+of the machine, unless access to the backup data is secured as tightly
+as access to the machine's root password itself.
+
+In order to generate a keytab for a host, the host must have a
+principal in the Kerberos database. The procedure for adding hosts to
+the database is described fully in :ref:`add_mod_del_princs_label`.
+(See :ref:`slave_host_key_label` for a brief description.) The keytab
+is generated by running kadmin and issuing the :ref:`ktadd` command.
+
+For example, to generate a keytab file to allow the host
+``trillium.mit.edu`` to authenticate for the services host, ftp, and
+pop, the administrator ``joeadmin`` would issue the command (on
+``trillium.mit.edu``)::
+
+ trillium% /usr/local/sbin/kadmin
+ kadmin5: ktadd host/trillium.mit.edu ftp/trillium.mit.edu pop/trillium.mit.edu
+ kadmin: Entry for principal host/trillium.mit.edu@ATHENA.MIT.EDU with
+ kvno 3, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/etc/krb5.keytab.
+ kadmin: Entry for principal ftp/trillium.mit.edu@ATHENA.MIT.EDU with
+ kvno 3, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/etc/krb5.keytab.
+ kadmin: Entry for principal pop/trillium.mit.edu@ATHENA.MIT.EDU with
+ kvno 3, encryption type DES-CBC-CRC added to keytab
+ WRFILE:/etc/krb5.keytab.
+ kadmin5: quit
+ trillium%
+
+If you generate the keytab file on another host, you need to get a
+copy of the keytab file onto the destination host (``trillium``, in
+the above example) without sending it unencrypted over the network.
-If you generate the *keytab* file on another host, you need to get a copy of the *keytab* file onto the destination host (*trillium*, in the above example) without sending it unencrypted over the network.
Some advice about secure hosts
---------------------------------------
-
-Kerberos V5 can protect your host from certain types of break-ins, but it is possible to install Kerberos V5 and still leave your host vulnerable to attack. Obviously an installation guide is not the place to try to include an exhaustive list of countermeasures for every possible attack, but it is worth noting some of the larger holes and how to close them.
-
-We recommend that backups of secure machines exclude the *keytab* file (/etc/krb5.keytab). If this is not possible, the backups should at least be done locally, rather than over a network, and the backup tapes should be physically secured.
-
-The *keytab* file and any programs run by root, including the Kerberos V5 binaries, should be kept on local disk. The *keytab* file should be readable only by root.
-
-
-
+------------------------------
+
+Kerberos V5 can protect your host from certain types of break-ins, but
+it is possible to install Kerberos V5 and still leave your host
+vulnerable to attack. Obviously an installation guide is not the
+place to try to include an exhaustive list of countermeasures for
+every possible attack, but it is worth noting some of the larger holes
+and how to close them.
+
+We recommend that backups of secure machines exclude the keytab file
+(``/etc/krb5.keytab``). If this is not possible, the backups should
+at least be done locally, rather than over a network, and the backup
+tapes should be physically secured.
+
+The keytab file and any programs run by root, including the Kerberos
+V5 binaries, should be kept on local disk. The keytab file should be
+readable only by root.
Client machine configuration files
-=====================================
+==================================
+Each machine running Kerberos must have a ``/etc/krb5.conf`` file.
+(See :ref:`krb5.conf`.)
-Each machine running Kerberos must have a */etc/krb5.conf* file. (See :ref:`krb5.conf`.)
+Also, for most UNIX systems, you must add the appropriate Kerberos
+services to each client machine's ``/etc/services`` file. If you are
+using the default configuration for Kerberos V5, you should be able to
+just insert the following code::
-Also, for most UNIX systems, you must add the appropriate Kerberos services to each client machine's */etc/services* file. If you are using the default configuration for Kerberos V5, you should be able to just insert the following code::
-
- kerberos 88/udp kdc # Kerberos V5 KDC
- kerberos 88/tcp kdc # Kerberos V5 KDC
- kerberos-adm 749/tcp # Kerberos 5 admin/changepw
- kerberos-adm 749/udp # Kerberos 5 admin/changepw
- krb5_prop 754/tcp # Kerberos slave propagation
- krb524 4444/tcp # Kerberos 5 to 4 ticket translator
-
-
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___cl_install
+ kerberos 88/udp kdc # Kerberos V5 KDC
+ kerberos 88/tcp kdc # Kerberos V5 KDC
+ kerberos-adm 749/tcp # Kerberos 5 admin/changepw
+ kerberos-adm 749/udp # Kerberos 5 admin/changepw
+ krb5_prop 754/tcp # Kerberos slave propagation
+ krb524 4444/tcp # Kerberos 5 to 4 ticket translator
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___cl_install
Installing and configuring UNIX client machines
-=====================================================
+===============================================
-The Kerberized client programs are *kinit, klist, kdestroy, kpasswd,* and *ksu*. All of these programs are in the directory */usr/local/bin*. MIT recommends that you use login.krb5 in place of /bin/login to give your users a single-sign-on system. You will need to make sure your users know to use their Kerberos passwords when they log in.
+The Kerberized client programs are kinit, klist, kdestroy, kpasswd,
+and ksu. All of these programs are in the directory
+``/usr/local/bin``. MIT recommends that you use login.krb5 in place
+of ``/bin/login`` to give your users a single-sign-on system. You will
+need to make sure your users know to use their Kerberos passwords when
+they log in.
-You will also need to educate your users to use the ticket management programs *kinit, klist, kdestroy,* and to use the Kerberos programs *ksu* and *kpasswd* in place of their non-Kerberos counterparts *su* and *passwd*.
+You will also need to educate your users to use the ticket management
+programs kinit, klist, kdestroy, and to use the Kerberos programs ksu
+and kpasswd in place of their non-Kerberos counterparts su and passwd.
.. toctree::
:maxdepth: 1
cl_config.rst
mac_osX_config.rst
-------------
-Feedback:
+Feedback
+--------
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___cl_install
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___cl_install
Mac OS X configuration
-=======================
-
-To install Kerberos V5 on Mac OS X and Mac OS X Server, follow the directions for generic Unix-based OS's, except for the */etc/services* updates described above.
-
-Mac OS X and Mac OS X Server use a database called NetInfo to store the contents of files normally found in */etc*. Instead of modifying */etc/services*, you should run the following commands to add the Kerberos service entries to NetInfo::
-
- $ niutil -create . /services/kerberos
- $ niutil -createprop . /services/kerberos name kerberos kdc
- $ niutil -createprop . /services/kerberos port 750
- $ niutil -createprop . /services/kerberos protocol tcp udp
- $ niutil -create . /services/krbupdate
- $ niutil -createprop . /services/krbupdate name krbupdate kreg
- $ niutil -createprop . /services/krbupdate port 760
- $ niutil -createprop . /services/krbupdate protocol tcp
- $ niutil -create . /services/kpasswd
- $ niutil -createprop . /services/kpasswd name kpasswd kpwd
- $ niutil -createprop . /services/kpasswd port 761
- $ niutil -createprop . /services/kpasswd protocol tcp
- $ niutil -create . /services/klogin
- $ niutil -createprop . /services/klogin port 543
- $ niutil -createprop . /services/klogin protocol tcp
- $ niutil -create . /services/eklogin
- $ niutil -createprop . /services/eklogin port 2105
- $ niutil -createprop . /services/eklogin protocol tcp
- $ niutil -create . /services/kshell
- $ niutil -createprop . /services/kshell name kshell krcmd
- $ niutil -createprop . /services/kshell port 544
- $ niutil -createprop . /services/kshell protocol tcp
-
-
-In addition to adding services to NetInfo, you must also modify the resolver configuration in NetInfo so that the machine resolves its own hostname as a FQDN (fully qualified domain name). By default, Mac OS X and Mac OS X Server machines query NetInfo to resolve hostnames before falling back to DNS. Because NetInfo has an unqualified name for all the machines in the NetInfo database, the machine's own hostname will resolve to an unqualified name. Kerberos needs a FQDN to look up keys in the machine's keytab file.
-
-Fortunately, you can change the lookupd caching order to query DNS first. Run the following NetInfo commands and reboot the machine::
-
- $ niutil -create . /locations/lookupd/hosts
- $ niutil -createprop . /locations/lookupd/hosts LookupOrder CacheAgent DNSAgent
- NIAgent NILAgent
-
-
-Once you have rebooted, you can verify that the resolver now behaves correctly. Compile the Kerberos 5 distribution and run::
-
- $ cd .../src/tests/resolve
- $ ./resolve
-
-
-This will tell you whether or not your machine returns FQDNs on name lookups. If the test still fails, you can also try turning off DNS caching. Run the following commands and reboot::
-
- $ niutil -create . /locations/lookupd/hosts
- $ niutil -createprop . /locations/lookupd/hosts LookupOrder DNSAgent
- CacheAgent NIAgent NILAgent
-
-
-The remainder of the setup of a Mac OS X client machine or application server should be the same as for other UNIX-based systems.
-
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___cl_install
-
-
-
+======================
+
+To install Kerberos V5 on Mac OS X and Mac OS X Server, follow the
+directions for generic Unix-based OS's, except for the
+``/etc/services`` updates described above.
+
+Mac OS X and Mac OS X Server use a database called NetInfo to store
+the contents of files normally found in ``/etc``. Instead of
+modifying ``/etc/services``, you should run the following commands to
+add the Kerberos service entries to NetInfo::
+
+ $ niutil -create . /services/kerberos
+ $ niutil -createprop . /services/kerberos name kerberos kdc
+ $ niutil -createprop . /services/kerberos port 750
+ $ niutil -createprop . /services/kerberos protocol tcp udp
+ $ niutil -create . /services/krbupdate
+ $ niutil -createprop . /services/krbupdate name krbupdate kreg
+ $ niutil -createprop . /services/krbupdate port 760
+ $ niutil -createprop . /services/krbupdate protocol tcp
+ $ niutil -create . /services/kpasswd
+ $ niutil -createprop . /services/kpasswd name kpasswd kpwd
+ $ niutil -createprop . /services/kpasswd port 761
+ $ niutil -createprop . /services/kpasswd protocol tcp
+ $ niutil -create . /services/klogin
+ $ niutil -createprop . /services/klogin port 543
+ $ niutil -createprop . /services/klogin protocol tcp
+ $ niutil -create . /services/eklogin
+ $ niutil -createprop . /services/eklogin port 2105
+ $ niutil -createprop . /services/eklogin protocol tcp
+ $ niutil -create . /services/kshell
+ $ niutil -createprop . /services/kshell name kshell krcmd
+ $ niutil -createprop . /services/kshell port 544
+ $ niutil -createprop . /services/kshell protocol tcp
+
+In addition to adding services to NetInfo, you must also modify the
+resolver configuration in NetInfo so that the machine resolves its own
+hostname as a FQDN (fully qualified domain name). By default, Mac OS
+X and Mac OS X Server machines query NetInfo to resolve hostnames
+before falling back to DNS. Because NetInfo has an unqualified name
+for all the machines in the NetInfo database, the machine's own
+hostname will resolve to an unqualified name. Kerberos needs a FQDN
+to look up keys in the machine's keytab file.
+
+Fortunately, you can change the lookupd caching order to query DNS
+first. Run the following NetInfo commands and reboot the machine::
+
+ $ niutil -create . /locations/lookupd/hosts
+ $ niutil -createprop . /locations/lookupd/hosts LookupOrder CacheAgent DNSAgent NIAgent NILAgent
+
+Once you have rebooted, you can verify that the resolver now behaves
+correctly. Compile the Kerberos 5 distribution and run::
+
+ $ cd .../src/tests/resolve
+ $ ./resolve
+
+This will tell you whether or not your machine returns FQDNs on name
+lookups. If the test still fails, you can also try turning off DNS
+caching. Run the following commands and reboot::
+
+ $ niutil -create . /locations/lookupd/hosts
+ $ niutil -createprop . /locations/lookupd/hosts LookupOrder DNSAgent CacheAgent NIAgent NILAgent
+
+The remainder of the setup of a Mac OS X client machine or application
+server should be the same as for other UNIX-based systems.
+
+
+Feedback
+--------
+
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___cl_install
.. _admin_acl_label:
Add administrators to the ACL file
-======================================
+==================================
-Next, you need create an Access Control List (ACL) file, and put the Kerberos principal of at least one of the administrators into it.
-This file is used by the *kadmind* daemon to control which principals may view and make privileged modifications to the Kerberos database files.
-The filename should match the value you have set for "acl_file" (see :ref:`kdc_realms`) in your *kdc.conf* file.
-The default file name is /usr/local/var/krb5kdc/kadm5.acl (See :ref:`mitK5defaults`).
+Next, you need create an Access Control List (ACL) file, and put the
+Kerberos principal of at least one of the administrators into it.
+This file is used by the kadmind daemon to control which principals
+may view and make privileged modifications to the Kerberos database
+files. The filename should match the value you have set for
+**acl_file** (see :ref:`kdc_realms`) in your kdc.conf file. The
+default file name is ``/usr/local/var/krb5kdc/kadm5.acl`` (See
+:ref:`mitK5defaults`).
The format of the file is::
- kerberos_principal permissions [target_principal] [restrictions]
-
-
-The *kerberos_principal* (and optional *target_principal*) can include the "*" wildcard,
-so if you want any principal with the instance "admin" to have full permissions on the database,
-you could use the principal "\*\/admin\@REALM" where "REALM" is your Kerberos realm.
-*target_principal* can also include backreferences to *kerberos_principal*, in which "\*number" matches the component number in the *kerberos_principal*.
-
-.. note:: A common use of an admin instance is so you can grant separate permissions
- (such as administrator access to the Kerberos database) to a separate *kerberos principal*.
- For example, the user *joeadmin* might have a principal for his administrative use, called *joeadmin/admin*.
- This way, *joeadmin* would obtain *joeadmin/admin* tickets only when he actually needs to use those permissions.
-
-The permissions are represented by single letters. The lower-case charecter specifies that operation can be performed by the principal, while its UPPER-CASE counterparts represent negative permissions. The permissions are:
-
- ==== ==========================================================
- a [Dis]allows the addition of principals or policies in the database.
- c [Dis]allows the changing of passwords for principals in the database.
- d [Dis]allows the deletion of principals or policies in the database.
- i [Dis]allows inquiries to the database.
- l [Dis]allows the listing of principals or policies in the database.
- m [Dis]allows the modification of principals or policies in the database.
- s [Dis]allows the explicit setting of the key for a principal
- \* All privileges (admcil).
- x All privileges (admcil); identical to "\*".
- ==== ==========================================================
+ kerberos_principal permissions [target_principal] [restrictions]
+
+The *kerberos_principal* (and optional *target_principal*) can include
+the "*" wildcard, so if you want any principal with the instance
+"admin" to have full permissions on the database, you could use the
+principal "\*\/admin\@REALM" where "REALM" is your Kerberos realm.
+*target_principal* can also include backreferences to
+*kerberos_principal*, in which "\*number" matches the component number
+in the *kerberos_principal*.
+
+.. note:: A common use of an admin instance is so you can grant
+ separate permissions (such as administrator access to the
+ Kerberos database) to a separate kerberos principal. For
+ example, the user ``joeadmin`` might have a principal for
+ his administrative use, called ``joeadmin/admin``. This
+ way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets
+ only when he actually needs to use those permissions.
+
+The permissions are represented by single letters. The lower-case
+charecter specifies that operation can be performed by the principal,
+while its UPPER-CASE counterparts represent negative permissions. The
+permissions are:
+
+ ==== ==========================================================
+ a [Dis]allows the addition of principals or policies in the database
+ c [Dis]allows the changing of passwords for principals in the database
+ d [Dis]allows the deletion of principals or policies in the database
+ i [Dis]allows inquiries to the database
+ l [Dis]allows the listing of principals or policies in the database
+ m [Dis]allows the modification of principals or policies in the database
+ s [Dis]allows the explicit setting of the key for a principal
+ \* All privileges (admcil)
+ x All privileges (admcil); identical to "\*"
+ ==== ==========================================================
The restrictions are a string of flags. Allowed restrictions are:
- ====================== ===============================
- [+\|-]flagname flag is forced to indicated value. The permissible flags are the same as the + and - flags for the kadmin :ref:`add_principal` and :ref:`modify_principal` commands.
- -clearpolicy policy is forced to clear
- -policy *pol* policy is forced to be *pol*
- expire *time* associated value will be forced to MIN(*time*, requested value)
- pwexpire *time* associated value will be forced to MIN(*time*, requested value)
- maxlife *time* associated value will be forced to MIN(*time*, requested value)
- maxrenewlife *time* associated value will be forced to MIN(*time*, requested value)
- ====================== ===============================
+ ====================== ===============================
+ [+\|-]flagname flag is forced to indicated value. The permissible flags are the same as the + and - flags for the kadmin :ref:`add_principal` and :ref:`modify_principal` commands.
+ -clearpolicy policy is forced to clear
+ -policy *pol* policy is forced to be *pol*
+ expire *time* associated value will be forced to MIN(*time*, requested value)
+ pwexpire *time* associated value will be forced to MIN(*time*, requested value)
+ maxlife *time* associated value will be forced to MIN(*time*, requested value)
+ maxrenewlife *time* associated value will be forced to MIN(*time*, requested value)
+ ====================== ===============================
-The above flags act as restrictions on any add or modify operation which is allowed due to that ACL line.
+The above flags act as restrictions on any add or modify operation
+which is allowed due to that ACL line.
-Here is an example of a *kadm5.acl* file.
+Here is an example of a kadm5.acl file.
-.. warning:: The order is important; permissions are determined by the first matching entry.
+.. warning:: The order is important; permissions are determined by the
+ first matching entry.
::
- */admin@ATHENA.MIT.EDU *
- joeadmin@ATHENA.MIT.EDU ADMCIL
- joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU
- *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU
- */*@ATHENA.MIT.EDU i
- */admin@EXAMPLE.COM * -maxlife 9h -postdateable
-
+ */admin@ATHENA.MIT.EDU *
+ joeadmin@ATHENA.MIT.EDU ADMCIL
+ joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU
+ *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU
+ */*@ATHENA.MIT.EDU i
+ */admin@EXAMPLE.COM * -maxlife 9h -postdateable
-In the above file, any principal in the *ATHENA.MIT.EDU* realm with an *admin* instance has *all* administrative privileges.
+In the above file, any principal in the ``ATHENA.MIT.EDU`` realm with
+an ``admin`` instance has all administrative privileges.
-The user *joeadmin* has *all* permissions with his *admin* instance, *joeadmin\/admin\@ATHENA.MIT.EDU* (matches the first line).
-He has no permissions at all with his *null* instance, *joeadmin\@ATHENA.MIT.EDU* (matches the second line).
-His root instance has *inquire* and *list* permissions with any other principal that has the instance root.
+The user ``joeadmin`` has all permissions with his ``admin`` instance,
+``joeadmin/admin@ATHENA.MIT.EDU`` (matches the first line). He has no
+permissions at all with his null instance, ``joeadmin@ATHENA.MIT.EDU``
+(matches the second line). His root instance has inquire and list
+permissions with any other principal that has the instance root.
-Any principal in *ATHENA.MIT.EDU* can *inquire, list*, or *change the password* of their *admin* instance, but not any other admin instance.
+Any principal in ``ATHENA.MIT.EDU`` can inquire, list, or change the
+password of their ``admin`` instance, but not any other admin
+instance.
-Any principal in the realm *ATHENA.MIT.EDU* (except for *joeadmin\@ATHENA.MIT.EDU*, as mentioned above) has *inquire* privileges.
+Any principal in the realm ``ATHENA.MIT.EDU`` (except for
+``joeadmin@ATHENA.MIT.EDU``, as mentioned above) has inquire
+privileges.
-Finally, any principal with an *admin* instance in *EXAMPLE.COM* has *all* permissions,
-but any principal that they create or modify will not be able to get *postdateable* tickets or tickets with a life of longer than 9 hours.
+Finally, any principal with an ``admin`` instance in ``EXAMPLE.COM``
+has all permissions, but any principal that they create or modify will
+not be able to get postdateable tickets or tickets with a life of
+longer than 9 hours.
-.. warning:: If the *kadmind*'s ACL file is modified, the *kadmind* daemon needs to be restarted for changes to take effect.
+.. warning:: If the kadmind ACL file is modified, the kadmind
+ daemon needs to be restarted for changes to take effect.
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
.. _addadmin_kdb:
Add administrators to the Kerberos database
-===============================================
+===========================================
-Next you need to add administrative principals
-(i.e. principals who are allowed to administer Kerberos database) to the Kerberos database.
-You *must* add at least one principal now to allow communication between
-Kerberos administration daemon *kadmind* and *kadmin* program over the network
-for the further Kerberos administration.
-To do this, use *kadmin.local* utility on the master KDC.
-Note, that *kadmin.local* is designed to be ran on the same host as the primary KDC
-without using the Kerberos authentication to its database.
-(However, one needs administrative privileges on the local filesystem to access database files for this command to succeed.)
+Next you need to add administrative principals (i.e. principals who
+are allowed to administer Kerberos database) to the Kerberos database.
+You *must* add at least one principal now to allow communication
+between Kerberos administration daemon kadmind and kadmin program over
+the network for the further Kerberos administration. To do this, use
+kadmin.local utility on the master KDC. Note, that kadmin.local is
+designed to be ran on the same host as the primary KDC without using
+the Kerberos authentication to its database. (However, one needs
+administrative privileges on the local filesystem to access database
+files for this command to succeed.)
-The administrative principals you create should be the ones you added to the ACL file. (See :ref:`admin_acl_label`.)
+The administrative principals you create should be the ones you added
+to the ACL file. (See :ref:`admin_acl_label`.)
-In the following example, the administrative principal *admin/admin* is created::
+In the following example, the administrative principal ``admin/admin``
+is created::
- shell% /usr/local/sbin/kadmin.local
+ shell% /usr/local/sbin/kadmin.local
- kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU
+ kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU
- WARNING: no policy specified for "admin/admin@ATHENA.MIT.EDU";
- assigning "default".
- Enter password for principal admin/admin@ATHENA.MIT.EDU: <= Enter a password.
- Re-enter password for principal admin/admin@ATHENA.MIT.EDU: <= Type it again.
- Principal "admin/admin@ATHENA.MIT.EDU" created.
- kadmin.local:
-
-------------
+ WARNING: no policy specified for "admin/admin@ATHENA.MIT.EDU";
+ assigning "default".
+ Enter password for principal admin/admin@ATHENA.MIT.EDU: <= Enter a password.
+ Re-enter password for principal admin/admin@ATHENA.MIT.EDU: <= Type it again.
+ Principal "admin/admin@ATHENA.MIT.EDU" created.
+ kadmin.local:
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
.. _create_db_label:
Create the database
-=========================
-
-You will use the :ref:`kdb5_util(8)` command on the master KDC to create the Kerberos database and the optional :ref:`stash_definition`.
-
-.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up.
- This means that the KDC will not be able to start automatically, such as after a system reboot.
-
-Note that *kdb5_util* will prompt you for the master key for the Kerberos database. This key can be any string.
-A good key is one you can remember, but that no one else can guess.
-Examples of bad keys are words that can be found in a dictionary, any common or popular name,
-especially a famous person (or cartoon character),
-your username in any form (e.g., forward, backward, repeated twice, etc.), and any of the sample keys that appear in this manual.
-One example of a key which might be good if it did not appear in this manual is "MITiys4K5!",
-which represents the sentence "MIT is your source for Kerberos 5!"
-(It's the first letter of each word, substituting the numeral "4" for the word "for", and includes the punctuation mark at the end.)
-
-The following is an example of how to create a Kerberos database and stash file on the master KDC,
-using the :ref:`kdb5_util(8)` command. Replace *ATHENA.MIT.EDU* with the name of your Kerberos realm::
-
- shell% /usr/local/sbin/kdb5_util create -r ATHENA.MIT.EDU -s
-
- Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
- master key name 'K/M@ATHENA.MIT.EDU'
- You will be prompted for the database Master Password.
- It is important that you NOT FORGET this password.
- Enter KDC database master key: <= Type the master password.
- Re-enter KDC database master key to verify: <= Type it again.
- shell%
-
-
-This will create five files in the directory specified in your *kdc.conf* file
-(The default location is */usr/local/var/krb5kdc* directory. See :ref:`mitK5defaults`):
-
-- two Kerberos database files, *principal*, and *principal.ok*;
-- the Kerberos administrative database file, *principal.kadm5*;
-- the administrative database lock file, *principal.kadm5.lock*;
-- the stash file, in this example - *.k5.ATHENA.MIT.EDU*
- ( by default it is *.k5.* prefix followed by the realm name of the database). If you do not want a stash file, run the above command without the *-s* option.
-
-For more information on administrating Kerberos database see :ref:`db_operations_label`.
-
-
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
-
-
+===================
+
+You will use the :ref:`kdb5_util(8)` command on the master KDC to
+create the Kerberos database and the optional :ref:`stash_definition`.
+
+.. note:: If you choose not to install a stash file, the KDC will
+ prompt you for the master key each time it starts up. This
+ means that the KDC will not be able to start automatically,
+ such as after a system reboot.
+
+Note that **kdb5_util** will prompt you for the master key for the
+Kerberos database. This key can be any string. A good key is one you
+can remember, but that no one else can guess. Examples of bad keys
+are words that can be found in a dictionary, any common or popular
+name, especially a famous person (or cartoon character), your username
+in any form (e.g., forward, backward, repeated twice, etc.), and any
+of the sample keys that appear in this manual. One example of a key
+which might be good if it did not appear in this manual is
+"MITiys4K5!", which represents the sentence "MIT is your source for
+Kerberos 5!" (It's the first letter of each word, substituting the
+numeral "4" for the word "for", and includes the punctuation mark at
+the end.)
+
+The following is an example of how to create a Kerberos database and
+stash file on the master KDC, using the :ref:`kdb5_util(8)`
+command. Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos
+realm::
+
+ shell% /usr/local/sbin/kdb5_util create -r ATHENA.MIT.EDU -s
+
+ Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
+ master key name 'K/M@ATHENA.MIT.EDU'
+ You will be prompted for the database Master Password.
+ It is important that you NOT FORGET this password.
+ Enter KDC database master key: <= Type the master password.
+ Re-enter KDC database master key to verify: <= Type it again.
+ shell%
+
+This will create five files in the directory specified in your
+**kdc.conf** file (The default location is ``/usr/local/var/krb5kdc``
+directory. See :ref:`mitK5defaults`):
+
+- two Kerberos database files, ``principal``, and ``principal.ok``;
+- the Kerberos administrative database file, ``principal.kadm5``;
+- the administrative database lock file, ``principal.kadm5.lock``;
+- the stash file, in this example ``.k5.ATHENA.MIT.EDU`` (by default
+ it is ``.k5.`` prefix followed by the realm name of the database).
+ If you do not want a stash file, run the above command without the
+ **-s** option.
+
+For more information on administrating Kerberos database see
+:ref:`db_operations_label`.
+
+
+Feedback
+--------
+
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
-.. note:: This document was copied from **Kerberos V5 Installation Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+.. note:: This document was copied from **Kerberos V5 Installation
+ Guide** with minor changes. Currently it is under
+ review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is greatly
+ appreciated.
Installing KDCs
-======================
-
-When setting up Kerberos in a production environment it is recommended to have multiple secondary (slave) KDCs
-alongside with a primary (master) KDC to ensure the continued availability of the Kerberized services.
-Each KDC contains a copy of the Kerberos database.
-The master KDC contains the writable copy of the realm database, which it replicates to the slave KDCs at regular intervals.
-All database changes (such as password changes) are made on the master KDC.
-Slave KDCs provide Kerberos ticket-granting services, but not database administration.
-This allows clients to continue to obtain tickets when the master KDC is unavailable.
-MIT recommends that you install all of your KDCs to be able to function as either the master or one of the slaves.
-This will enable you to easily switch your master KDC with one of the slaves if necessary. (See :ref:`switch_master_slave`.)
-This installation procedure is based on that recommendation.
-
-.. warning::
- - The Kerberos system heavily relies on the timestamps, so all Kerberos exchange participants should be rather well synchronized.
-
- - It is recomended to install and run KDCs on the secured and dedicated solely to KDC hardware with limited access.
- If your KDC is also a file server, FTP server, Web server, or even just a client machine,
- someone who obtained root access through a security hole in any of those areas could gain access to the Kerberos database.
-
+===============
+
+When setting up Kerberos in a production environment it is recommended
+to have multiple secondary (slave) KDCs alongside with a primary
+(master) KDC to ensure the continued availability of the Kerberized
+services. Each KDC contains a copy of the Kerberos database. The
+master KDC contains the writable copy of the realm database, which it
+replicates to the slave KDCs at regular intervals. All database
+changes (such as password changes) are made on the master KDC. Slave
+KDCs provide Kerberos ticket-granting services, but not database
+administration. This allows clients to continue to obtain tickets
+when the master KDC is unavailable. MIT recommends that you install
+all of your KDCs to be able to function as either the master or one of
+the slaves. This will enable you to easily switch your master KDC
+with one of the slaves if necessary. (See :ref:`switch_master_slave`.)
+This installation procedure is based on that recommendation.
+
+.. warning::
+ - The Kerberos system heavily relies on the timestamps, so all
+ Kerberos exchange participants should be rather well
+ synchronized.
+
+ - It is recomended to install and run KDCs on the secured and
+ dedicated solely to KDC hardware with limited access. If your
+ KDC is also a file server, FTP server, Web server, or even just
+ a client machine, someone who obtained root access through a
+ security hole in any of those areas could gain access to the
+ Kerberos database.
Install and configure the master KDC
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
-Install Kerberos either from the OS-provided packages or from the source (See :ref:`do_build`).
+Install Kerberos either from the OS-provided packages or from the
+source (See :ref:`do_build`).
-.. note:: For the purpose of this document we will use the following names
- ::
-
- - kerberos.mit.edu - master KDC
- - kerberos-1.mit.edu - slave KDC
- - mit.edu - domain name
- - ATHENA.MIT.EDU - realm name
- - .k5.ATHENA.MIT.EDU - stash file
- - admin/admin - admin principal
-
- See :ref:`mitK5defaults` for the default names and locations of the relevant to this topic files.
- Adjust the names and paths to your system environment.
+.. note:: For the purpose of this document we will use the following
+ names::
+ kerberos.mit.edu - master KDC
+ kerberos-1.mit.edu - slave KDC
+ mit.edu - domain name
+ ATHENA.MIT.EDU - realm name
+ .k5.ATHENA.MIT.EDU - stash file
+ admin/admin - admin principal
+ See :ref:`mitK5defaults` for the default names and locations
+ of the relevant to this topic files. Adjust the names and
+ paths to your system environment.
.. toctree::
:maxdepth: 1
Install the Slave KDCs
-~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------
.. toctree::
:maxdepth: 1
slave_install.rst
kdc_prop_slave.rst
-Once your KDCs are set up and running, you are ready to use kadmin to load principals for your users,
-hosts, and other services into the Kerberos database.
-This procedure is described fully in the :ref:`add_mod_del_princs_label`.
-The keytab is generated by running kadmin and issuing the :ref:`ktadd` command.
+Once your KDCs are set up and running, you are ready to use kadmin to
+load principals for your users, hosts, and other services into the
+Kerberos database. This procedure is described fully in the
+:ref:`add_mod_del_princs_label`. The keytab is generated by running
+kadmin and issuing the :ref:`ktadd` command.
+You may occasionally want to use one of your slave KDCs as the master.
+This might happen if you are upgrading the master KDC, or if your
+master KDC has a disk crash. See the following section for the
+instructions.
-You may occasionally want to use one of your slave KDCs as the master.
-This might happen if you are upgrading the master KDC, or if your master KDC has a disk crash.
-See the following section for the instructions.
Switching Master and Slave KDCs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
.. toctree::
:maxdepth: 2
switch_master_slave.rst
+
Incremental database propagation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
.. toctree::
:maxdepth: 1
../database/incr_db_prop.rst
-------------
-
-Feedback:
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
-Create a kadmind keytab
-=================================
+Create a kadmind keytab
+=======================
.. note:: This operation is optional.
-
-The *kadmind keytab* is the key that the legacy admininstration daemons *kadmind4* and *v5passwdd*
-will use to decrypt administrators' or clients' Kerberos tickets to determine whether or not
-they should have access to the database.
-You need to create the kadmin keytab with entries for the principals *kadmin/admin* and *kadmin/changepw*.
-(These principals are placed in the Kerberos database automatically when you create it.)
-To create the *kadmin* keytab, run *kadmin.local* and use the :ref:`ktadd` command, as in the following example::
-
- shell% /usr/local/sbin/kadmin.local
-
- kadmin.local: ktadd -k /usr/local/var/krb5kdc/kadm5.keytab kadmin/admin kadmin/changepw
- Entry for principal kadmin/admin with kvno 5, encryption
- type Triple DES cbc mode with HMAC/sha1 added to keytab
- WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
- Entry for principal kadmin/admin with kvno 5, encryption type DES cbc mode
- with CRC-32 added to keytab
- WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
- Entry for principal kadmin/changepw with kvno 5, encryption
- type Triple DES cbc mode with HMAC/sha1 added to keytab
- WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
- Entry for principal kadmin/changepw with kvno 5,
- encryption type DES cbc mode with CRC-32 added to keytab
- WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
- kadmin.local: quit
-
-
-As specified in the *-k* argument, :ref:`ktadd` will save the extracted keytab as */usr/local/var/krb5kdc/kadm5.keytab*
-(This is also the default location for the admin keytab). The filename you use must be the one specified in your *kdc.conf* file.
-
-
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
-
-
+The kadmind keytab is the key that the legacy admininstration daemons
+kadmind4 and v5passwdd will use to decrypt administrators' or clients'
+Kerberos tickets to determine whether or not they should have access
+to the database. You need to create the kadmin keytab with entries
+for the principals ``kadmin/admin`` and ``kadmin/changepw``. (These
+principals are placed in the Kerberos database automatically when you
+create it.) To create the kadmin keytab, run kadmin.local and use the
+:ref:`ktadd` command, as in the following example::
+
+ shell% /usr/local/sbin/kadmin.local
+
+ kadmin.local: ktadd -k /usr/local/var/krb5kdc/kadm5.keytab kadmin/admin kadmin/changepw
+ Entry for principal kadmin/admin with kvno 5, encryption
+ type Triple DES cbc mode with HMAC/sha1 added to keytab
+ WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+ Entry for principal kadmin/admin with kvno 5, encryption type DES cbc mode
+ with CRC-32 added to keytab
+ WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+ Entry for principal kadmin/changepw with kvno 5, encryption
+ type Triple DES cbc mode with HMAC/sha1 added to keytab
+ WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+ Entry for principal kadmin/changepw with kvno 5,
+ encryption type DES cbc mode with CRC-32 added to keytab
+ WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+ kadmin.local: quit
+
+As specified in the **-k** argument, :ref:`ktadd` will save the
+extracted keytab as ``/usr/local/var/krb5kdc/kadm5.keytab`` (This is
+also the default location for the admin keytab). The filename you use
+must be the one specified in your kdc.conf file.
+
+
+Feedback
+--------
+
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
Propagate the database to each slave KDC
===========================================
-First, stop the *kadmin* service.
+First, stop the kadmin service.
-Next, create a dump file of the database on the master KDC, as follows::
+Next, create a dump file of the database on the master KDC, as
+follows::
- shell% /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans
-
-Finally, manually propagate the database to each slave KDC, as in the following example::
+ shell% /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans
- shell% /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu
+Finally, manually propagate the database to each slave KDC, as in the
+following example::
- Database propagation to kerberos-1.mit.edu: SUCCEEDED
+ shell% /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu
-Just in case you need an additional confirmation of the successful propagation,
-do the following on the slave:
+ Database propagation to kerberos-1.mit.edu: SUCCEEDED
- - make sure that only this slave's *kdc* is listed in the *krb5.conf* file, then
- - start *krb5kdc* on the slave server and
- - run "kinit admin/admin\@ATHENA.MIT.EDU" which should succeed once the correct password
- (i.e. password that was entered on the master server for this principal) is provided.
- - now *klist* should display the message similar to "Default principal: admin/admin\@ATHENA.MIT.EDU"
+Just in case you need an additional confirmation of the successful
+propagation, do the following on the slave:
+* make sure that only this slave's kdc is listed in the krb5.conf
+ file, then
+* start krb5kdc on the slave server and
+* run ``kinit admin/admin@ATHENA.MIT.EDU`` which should succeed once
+ the correct password (i.e. password that was entered on the master
+ server for this principal) is provided.
+* now klist should display the message similar to ``Default principal:
+ admin/admin@ATHENA.MIT.EDU``
-You will need a script to dump and propagate the database. The following is an example of a bourne shell script that will do this.
+You will need a script to dump and propagate the database. The
+following is an example of a bourne shell script that will do this.
-.. note:: Remember that you need to replace */usr/local/var* with the name of the directory in which you installed Kerberos V5.
+.. note:: Remember that you need to replace ``/usr/local/var`` with
+ the name of the directory in which you installed Kerberos
+ V5.
::
- #!/bin/sh
-
- kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu"
-
- /usr/local/sbin/kdb5_util "dump /usr/local/var/krb5kdc/slave_datatrans"
-
- for kdc in $kdclist
- do
- /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc
- done
-
-
-You will need to set up a cron job to run this script at the intervals you decided on earlier (See :ref:`db_prop_label` and :ref:`incr_db_prop_label`.)
-The dump can also be used as a save file.
-Once the operation succeeded, connect to slaves and start thier KDCs.
-
-Now that the slave KDC has a copy of the Kerberos database, you can start the *krb5kdc* daemon::
-
- shell% usr/local/sbin/krb5kdc
-
-
-As with the master KDC, you will probably want to add this command to the KDCs' */etc/rc* or */etc/inittab* files,
-so they will start the *krb5kdc* daemon automatically at boot time.
+ #!/bin/sh
-Once your KDCs are set up and running, you are ready to use kadmin to load principals for your users,
-hosts, and other services into the Kerberos database.
-This procedure is described fully in the :ref:`add_mod_del_princs_label`.
-The keytab is generated by running kadmin and issuing the ktadd command.
+ kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu"
+ /usr/local/sbin/kdb5_util "dump /usr/local/var/krb5kdc/slave_datatrans"
-Propagation failed?
-------------------------
+ for kdc in $kdclist
+ do
+ /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc
+ done
-.. _prop_failed_start:
+You will need to set up a cron job to run this script at the intervals
+you decided on earlier (See :ref:`db_prop_label` and
+:ref:`incr_db_prop_label`.) The dump can also be used as a save file.
+Once the operation succeeded, connect to slaves and start thier KDCs.
-.. error:: kprop: No route to host in call to connect while opening connection
+Now that the slave KDC has a copy of the Kerberos database, you can
+start the krb5kdc daemon::
- kprop: Connection refused in call to connect while opening connection
+ shell% usr/local/sbin/krb5kdc
- kprop: Server rejected authentication (during sendauth exchange) while authenticating to server
+As with the master KDC, you will probably want to add this command to
+the KDCs' ``/etc/rc`` or ``/etc/inittab`` files, so they will start
+the krb5kdc daemon automatically at boot time.
-Make sure that
+Once your KDCs are set up and running, you are ready to use kadmin to
+load principals for your users, hosts, and other services into the
+Kerberos database. This procedure is described fully in the
+:ref:`add_mod_del_princs_label`. The keytab is generated by running
+kadmin and issuing the ktadd command.
-#. the time is syncronized between the master-slaves participants;
-#. master stash and keytab files (e.g. *.k5.ATHENA.MIT.EDU* and *host/kerberos-1.mit.edu\@ATHENA.MIT.EDU*) are copied from the master to the expected location on the slaves;
-#. Kerberos database was created on the slaves prior the propagation from the master.
-#. if *kpropd* is invoked from *inetd* (or its equivalent *xinetd*),
- the *inetd* daemon was restarted after the configuration files
- */etc/inetd.conf* and */etc/services* were updated;
-#. *kpropd* is running on the slave server;
-#. if the locations of the configuration/keytab files differ from the default ones, provide the proper environment variables and/or options to the programs;
-.. _prop_failed_end:
+Propagation failed?
+-------------------
+.. _prop_failed_start:
+.. error:: kprop: No route to host in call to connect while opening
+ connection
-------------
+ kprop: Connection refused in call to connect while opening
+ connection
-Feedback:
+ kprop: Server rejected authentication (during sendauth
+ exchange) while authenticating to server
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
+Make sure that:
+#. the time is syncronized between the master-slaves participants;
+#. master stash and keytab files (e.g. ``.k5.ATHENA.MIT.EDU`` and
+ ``host/kerberos-1.mit.edu@ATHENA.MIT.EDU``) are copied from the
+ master to the expected location on the slaves;
+#. Kerberos database was created on the slaves prior the propagation
+ from the master.
+#. if kpropd is invoked from inetd (or its equivalent xinetd), the
+ inetd daemon was restarted after the configuration files
+ ``/etc/inetd.conf`` and ``/etc/services`` were updated;
+#. kpropd is running on the slave server;
+#. if the locations of the configuration/keytab files differ from the
+ default ones, provide the proper environment variables and/or
+ options to the programs;
+
+.. _prop_failed_end:
+
+Feedback
+--------
+
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
Start the Kerberos daemons on the master KDC
===============================================
-At this point, you are ready to start the Kerberos KDC (:ref:`krb5kdc(8)`) and
-administrative daemons on the Master KDC. To do so, type::
+At this point, you are ready to start the Kerberos KDC
+(:ref:`krb5kdc(8)`) and administrative daemons on the Master KDC. To
+do so, type::
- shell% /usr/local/sbin/krb5kdc
- shell% /usr/local/sbin/kadmind
-
+ shell% /usr/local/sbin/krb5kdc
+ shell% /usr/local/sbin/kadmind
-Each server daemon will fork and run in the background.
+Each server daemon will fork and run in the background.
-.. note:: Assuming you want these daemons to start up automatically at boot time,
- you can add them to the KDC's */etc/rc* or */etc/inittab* file.
- You need to have a :ref:`stash_definition` in order to do this.
+.. note:: Assuming you want these daemons to start up automatically at
+ boot time, you can add them to the KDC's ``/etc/rc`` or
+ ``/etc/inittab`` file. You need to have a
+ :ref:`stash_definition` in order to do this.
+You can verify that they started properly by checking for their
+startup messages in the logging locations you defined in
+krb5.conf. (See :ref:`logging`). For example::
+ shell% tail /var/log/krb5kdc.log
+ Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
+ shell% tail /var/log/kadmin.log
+ Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
-You can verify that they started properly by checking for their startup messages in the logging locations
-you defined in */etc/krb5.conf*. (See :ref:`logging`).
-For example::
+Any errors the daemons encounter while starting will also be listed in
+the logging output.
- shell% tail /var/log/krb5kdc.log
- Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
- shell% tail /var/log/kadmin.log
- Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
-
+As an additional verification, check if kinit succeeds against the
+principals that you have created on the previous step
+(:ref:`addadmin_kdb`). Run::
-Any errors the daemons encounter while starting will also be listed in the logging output.
+ shell% /usr/local/bin/kinit admin/admin@ATHENA.MIT.EDU
-As an additional verification, check if *kinit* succeeds against the principals that
-you have created on the previous step (:ref:`addadmin_kdb`). Run::
+You are now ready to start configuring the slave KDCs.
- shell% /usr/local/bin/kinit admin/admin@ATHENA.MIT.EDU
+.. note:: Assuming you are setting the KDCs up so that you can easily
+ switch the master KDC with one of the slaves, you should
+ perform each of these steps on the master KDC as well as the
+ slave KDCs, unless these instructions specify otherwise.
-You are now ready to start configuring the slave KDCs.
-
-.. note:: Assuming you are setting the KDCs up so that you can easily switch the master KDC with one of the slaves,
- you should perform each of these steps on the master KDC as well as the slave KDCs,
- unless these instructions specify otherwise.
-
-
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
-
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
Edit the configuration files
-==================================
-
-Modify the configuration files, *krb5.conf* and *kdc.conf* to reflect the correct information
-(such as domain-realm mappings and Kerberos servers names) for your realm.
-(See :ref:`mitK5defaults` for the recommended default locations for these files).
-
-Most of the tags in the configuration have default values that will work well for most sites.
-There are some tags in the *krb5.conf* file whose values must be specified,
-and this section will explain those.
-For more information on Kerberos V5 configuration files see :ref:`krb5.conf` and :ref:`kdc.conf`.
-
-If the locations for these configuration files differs from the default ones,
-set *KRB5_CONFIG* and *KRB5_KDC_PROFILE* environment variables to point to the
-*krb5.conf* and *kdc.conf* respectively.
-For example::
-
- export KRB5_CONFIG=/yourdir/krb5.conf
- export KRB5_KDC_PROFILE=/yourdir/kdc.conf
-
-*krb5.conf*
--------------
-
-If you are not using DNS TXT records (see :ref:`mapping_hn_label`), you must specify the *default_realm* in the :ref:`libdefaults` section.
-If you are not using DNS SRV records (see :ref:`kdc_hn_label`), you must include the *kdc* tag for each *realm* in the :ref:`realms` section.
-To communicate with the kadmin server in each realm, the *admin_server* tag must be set in the :ref:`realms` section.
-If your domain name and realm name are not the same, you must provide a translation in :ref:`domain_realm`.
-It is also higly recommeneded that you create a :ref:`logging` stanza if the computer will be functioning as a KDC
-so that the KDC and *kadmind* will generate logging output.
-
+============================
+
+Modify the configuration files, krb5.conf and kdc.conf, to reflect the
+correct information (such as domain-realm mappings and Kerberos
+servers names) for your realm. (See :ref:`mitK5defaults` for the
+recommended default locations for these files).
+
+Most of the tags in the configuration have default values that will
+work well for most sites. There are some tags in the krb5.conf file
+whose values must be specified, and this section will explain those.
+For more information on Kerberos V5 configuration files see
+:ref:`krb5.conf` and :ref:`kdc.conf`.
+
+If the locations for these configuration files differs from the
+default ones, set **KRB5_CONFIG** and **KRB5_KDC_PROFILE** environment
+variables to point to the krb5.conf and kdc.conf respectively. For
+example::
+
+ export KRB5_CONFIG=/yourdir/krb5.conf
+ export KRB5_KDC_PROFILE=/yourdir/kdc.conf
+
+
+krb5.conf
+---------
+
+If you are not using DNS TXT records (see :ref:`mapping_hn_label`),
+you must specify the **default_realm** in the :ref:`libdefaults`
+section. If you are not using DNS SRV records (see
+:ref:`kdc_hn_label`), you must include the **kdc** tag for each
+*realm* in the :ref:`realms` section. To communicate with the kadmin
+server in each realm, the **admin_server** tag must be set in the
+:ref:`realms` section. If your domain name and realm name are not the
+same, you must provide a translation in :ref:`domain_realm`. It is
+also higly recommeneded that you create a :ref:`logging` stanza if the
+computer will be functioning as a KDC so that the KDC and kadmind will
+generate logging output.
An example krb5.conf file::
-
- [libdefaults]
- default_realm = ATHENA.MIT.EDU
- # if the default location does not suit your setup,
- # explicitly configure the keytab location:
- # default_keytab_name = FILE:/var/krb5kdc/krb5.keytab
-
- [realms]
- ATHENA.MIT.EDU = {
- kdc = kerberos.mit.edu
- kdc = kerberos-1.mit.edu
- kdc = kerberos-2.mit.edu
- admin_server = kerberos.mit.edu
- }
-
- [logging]
- kdc = FILE:/var/log/krb5kdc.log
- admin_server = FILE:/var/log/kadmin.log
- default = FILE:/var/log/krb5lib.log
-
+ [libdefaults]
+ default_realm = ATHENA.MIT.EDU
+ # if the default location does not suit your setup,
+ # explicitly configure the keytab location:
+ # default_keytab_name = FILE:/var/krb5kdc/krb5.keytab
+
+ [realms]
+ ATHENA.MIT.EDU = {
+ kdc = kerberos.mit.edu
+ kdc = kerberos-1.mit.edu
+ kdc = kerberos-2.mit.edu
+ admin_server = kerberos.mit.edu
+ }
+
+ [logging]
+ kdc = FILE:/var/log/krb5kdc.log
+ admin_server = FILE:/var/log/kadmin.log
+ default = FILE:/var/log/krb5lib.log
An example kdc.conf file::
- [kdcdefaults]
- kdc_ports = 88,750
-
- [realms]
- ATHENA.MIT.EDU = {
- kadmind_port = 749
- max_life = 12h 0m 0s
- max_renewable_life = 7d 0h 0m 0s
- master_key_type = des3-hmac-sha1
- supported_enctypes = des3-hmac-sha1:normal aes128-cts-hmac-sha1-96:normal
- # if the default location does not suit your setup,
- # explicitly configure the following four values:
- # database_name = /var/krb5kdc/principal
- # key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU
- # admin_keytab = FILE:/var/krb5kdc/kadm5.keytab
- # acl_file = /var/krb5kdc/kadm5.acl
- }
-
-
-Replace *ATHENA.MIT.EDU* and *kerberos.mit.edu* with the name of your Kerberos *realm* and *server* respectively.
-
-.. note:: You have to have write permission on the target directories
- (these directories must exist) used by
- *database_name, key_stash_file, admin_keytab* and *acl_file*
-
-
-
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
-
+ [kdcdefaults]
+ kdc_ports = 88,750
+
+ [realms]
+ ATHENA.MIT.EDU = {
+ kadmind_port = 749
+ max_life = 12h 0m 0s
+ max_renewable_life = 7d 0h 0m 0s
+ master_key_type = des3-hmac-sha1
+ supported_enctypes = des3-hmac-sha1:normal aes128-cts-hmac-sha1-96:normal
+ # if the default location does not suit your setup,
+ # explicitly configure the following four values:
+ # database_name = /var/krb5kdc/principal
+ # key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU
+ # admin_keytab = FILE:/var/krb5kdc/kadm5.keytab
+ # acl_file = /var/krb5kdc/kadm5.acl
+ }
+
+Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of
+your Kerberos realm and server respectively.
+
+.. note:: You have to have write permission on the target directories
+ (these directories must exist) used by **database_name**,
+ **key_stash_file**, **admin_keytab**, and **acl_file**.
+
+
+Feedback
+--------
+
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
.. _slave_host_key_label:
Setting up slave KDCs
-========================================
+=====================
-Prep work on the master side.
--------------------------------------------
+Prep work on the master side
+----------------------------
-Each KDC needs a *host* keys in the Kerberos database.
-These keys are used for mutual authentication when propagating the database
-*dump* file from the master KDC to the secondary KDC servers.
+Each KDC needs a ``host`` keys in the Kerberos database. These keys
+are used for mutual authentication when propagating the database dump
+file from the master KDC to the secondary KDC servers.
-On the master KDC connect to administrative interface and create
-the new principals for each of the KDCs *host* service.
-For example, if the master KDC were called *kerberos.mit.edu*, and you had
-slave KDC named *kerberos-1.mit.edu*, you would type the following::
+On the master KDC connect to administrative interface and create the
+new principals for each of the KDCs ``host`` service. For example, if
+the master KDC were called ``kerberos.mit.edu``, and you had slave KDC
+named ``kerberos-1.mit.edu``, you would type the following::
- shell% /usr/local/bin/kadmin
- kadmin: addprinc -randkey host/kerberos.mit.edu
- NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default"
- Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created.
+ shell% /usr/local/bin/kadmin
+ kadmin: addprinc -randkey host/kerberos.mit.edu
+ NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default"
+ Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created.
- kadmin: addprinc -randkey host/kerberos-1.mit.edu
- NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default"
- Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created.
+ kadmin: addprinc -randkey host/kerberos-1.mit.edu
+ NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default"
+ Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created.
+It is not actually necessary to have the master KDC server in the
+Kerberos database, but it can be handy if:
-It is not actually necessary to have the master KDC server in the Kerberos
-database, but it can be handy if:
+ - anyone will be logging into the machine as something other than
+ root
+ - you want to be able to swap the master KDC with one of the slaves
+ if necessary.
- - anyone will be logging into the machine as something other than *root*
- - you want to be able to swap the master KDC with one of the slaves if necessary.
+Next, extract ``host`` random keys for all participating KDCs and
+store them in the default keytab file which is needed to decrypt
+tickets. Ideally, you should extract each keytab locally on its own
+KDC. If this is not feasible, you should use an encrypted session to
+send them across the network. To extract a keytab on a KDC called
+``kerberos.mit.edu``, you would execute the following command::
-Next, extract *host* random keys for all participating KDCs and store them
-in the default keytab file which is needed to decrypt tickets.
-Ideally, you should extract each keytab locally on its own KDC.
-If this is not feasible, you should use an encrypted session to send them across the network.
-To extract a keytab on a KDC called *kerberos.mit.edu*, you would execute the following command::
+ kadmin: ktadd host/kerberos.mit.edu
+ kadmin: Entry for principal host/kerberos.mit.edu@ATHENA.MIT.EDU with
+ kvno 1, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab.
- kadmin: ktadd host/kerberos.mit.edu
- kadmin: Entry for principal host/kerberos.mit.edu@ATHENA.MIT.EDU with
- kvno 1, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab.
+ kadmin: ktadd -k /tmp/krb5.keytab host/kerberos-1.mit.edu
+ kadmin: Entry for principal host/kerberos-1.mit.edu@ATHENA.MIT.EDU with
+ kvno 1, encryption type DES-CBC-CRC added to keytab WRFILE:/tmp/krb5.keytab.
- kadmin: ktadd -k /tmp/krb5.keytab host/kerberos-1.mit.edu
- kadmin: Entry for principal host/kerberos-1.mit.edu@ATHENA.MIT.EDU with
- kvno 1, encryption type DES-CBC-CRC added to keytab WRFILE:/tmp/krb5.keytab.
+ kadmin:
- kadmin:
-
-Move the file /tmp/krb5.keytab (via scp) onto the slave KDC (*kerberos-1.mit.edu*)
-into exactly the same location as on the master (default is */etc/krb5.keytab*).
-Remove the temporary copy /tmp/krb5.keytab from the master.
+Move the file /tmp/krb5.keytab (via scp) onto the slave KDC
+(``kerberos-1.mit.edu``) into exactly the same location as on the
+master (default is ``/etc/krb5.keytab``). Remove the temporary copy
+``/tmp/krb5.keytab`` from the master.
Configuring the slave
--------------------------
-
-By default, the propagation is done on the entire content of the master's database.
-That is, even special principals (like *K/M\@FOOBAR.COM*) will be dumped and
-copied to the slave KDCs.
-Pay attention there: it means that configuration files, as also specific files
-(like ACLs and :ref:`stash_definition`) must be copied to the slave hosts too.
-Copying only a part of it will result in a bulky situation.
-If you forget to copy the stash file for example,
-the KDC daemon on the slave host will not be able to access the propagated
-database because of missing master key.
-Before connecting to the slave, you will copy all minimum required files
-from the master for the slave system to work. Initially, it concerns
-(See :ref:`mitK5defaults` for the recommended default locations for these files):
-
- • krb5.conf
- • kdc.conf
- • kadm5.acl
- • master key stash file
-
-Connect to the slave, *kerberos-1.mit.edu*. Move the copied files into their
-appropriate directories (exactly like on the master KDC).
+---------------------
+
+By default, the propagation is done on the entire content of the
+master's database. That is, even special principals (like
+``K/M@FOOBAR.COM``) will be dumped and copied to the slave KDCs. Pay
+attention there: it means that configuration files, as also specific
+files (like ACLs and :ref:`stash_definition`) must be copied to the
+slave hosts too. Copying only a part of it will result in a bulky
+situation. If you forget to copy the stash file for example, the KDC
+daemon on the slave host will not be able to access the propagated
+database because of missing master key. Before connecting to the
+slave, you will copy all minimum required files from the master for
+the slave system to work. Initially, it concerns (See
+:ref:`mitK5defaults` for the recommended default locations for these
+files):
+
+ • krb5.conf
+ • kdc.conf
+ • kadm5.acl
+ • master key stash file
+
+Connect to the slave, *kerberos-1.mit.edu*. Move the copied files into
+their appropriate directories (exactly like on the master KDC).
You will now initialize the slave database::
- shell% /usr/local/sbin/kdb5_util create
+ shell% /usr/local/sbin/kdb5_util create
-.. caution:: You will use :ref:`kdb5_util(8)` but without exporting the stash file (-s argument), i
- thus avoiding the obliteration of the one you just copied from the master.
+.. caution:: You will use :ref:`kdb5_util(8)` but without exporting
+ the stash file (-s argument), thus avoiding the
+ obliteration of the one you just copied from the master.
-When asking for the database Master Password, type in anything you want.
-The whole dummy database will be erased upon the first propagation from master.
+When asking for the database Master Password, type in anything you
+want. The whole dummy database will be erased upon the first
+propagation from master.
The database is propagated from the master KDC to the slave KDCs via
-the :ref:`kpropd(8)` daemon.
-You must explicitly specify the clients that are allowed to provide Kerberos
-dump updates on the slave machine with a new database.
-The *kpropd.acl* file serves as the access control list for the *kpropd* service.
-This file is typically resides in *krb5kdc* local directory.
-Since in our case the updates should only come from *kerberos.mit.edu* server,
-then the file's contents would be::
+the :ref:`kpropd(8)` daemon. You must explicitly specify the clients
+that are allowed to provide Kerberos dump updates on the slave machine
+with a new database. The kpropd.acl file serves as the access control
+list for the kpropd service. This file is typically resides in
+krb5kdc local directory. Since in our case the updates should only
+come from ``kerberos.mit.edu`` server, then the file's contents would
+be::
host/kerberos.mit.edu@ATHENA.MIT.EDU
-.. note:: If you expect that the primary and secondary KDCs will be switched at some point of time,
- it is recommended to list the host principals from *all* participating KDC servers in
- *kpropd.acl* files on *all* of these servers.
+.. note:: If you expect that the primary and secondary KDCs will be
+ switched at some point of time, it is recommended to list
+ the host principals from *all* participating KDC servers in
+ kpropd.acl files on *all* of these servers.
+Then, add the following line to ``/etc/inetd.conf`` file on each KDC
+(Adjust the path to kpropd)::
-Then, add the following line to */etc/inetd.conf* file on each KDC
-(Adjust the path to *kpropd*)::
+ krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
+ eklogin stream tcp nowait root /usr/local/sbin/klogind klogind -5 -c -e
- krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
- eklogin stream tcp nowait root /usr/local/sbin/klogind klogind -5 -c -e
+You also need to add the following lines to ``/etc/services`` on each
+KDC (assuming that default ports are used)::
-You also need to add the following lines to */etc/services* on each KDC
-(assuming that default ports are used)::
+ kerberos 88/udp kdc # Kerberos authentication (udp)
+ kerberos 88/tcp kdc # Kerberos authentication (tcp)
+ krb5_prop 754/tcp # Kerberos slave propagation
+ kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp)
+ kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp)
- kerberos 88/udp kdc # Kerberos authentication (udp)
- kerberos 88/tcp kdc # Kerberos authentication (tcp)
- krb5_prop 754/tcp # Kerberos slave propagation
- kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp)
- kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp)
+Restart inetd daemon.
-Restart *inetd* daemon.
-
-
-Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon "kpropd -S" or,
-if the default locations must be overridden,::
+Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon "kpropd
+-S" or, if the default locations must be overridden::
shell% /usr/local/sbin/kpropd -S -a path-to-kpropd.acl -r ATHENA.MIT.EDU -f /var/krb5kdc/from_master
waiting for a kprop connection
-Now that the slave KDC is able to accept database propagation,
-you’ll need to propagate the database from the master server.
-
-NOTE: Do not start slave KDC - you still do not have a copy of the master's database.
+Now that the slave KDC is able to accept database propagation, you’ll
+need to propagate the database from the master server.
-------------
+NOTE: Do not start slave KDC - you still do not have a copy of the
+master's database.
-Feedback:
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
.. _switch_master_slave:
Switching Master and Slave KDCs
-=========================================
+===============================
-You may occasionally want to use one of your slave KDCs as the master. This might happen if you are upgrading the master KDC, or if your master KDC has a disk crash.
+You may occasionally want to use one of your slave KDCs as the master.
+This might happen if you are upgrading the master KDC, or if your
+master KDC has a disk crash.
-Assuming you have configured all of your KDCs to be able to function as either the master KDC or a slave KDC (as this document recommends), all you need to do to make the changeover is:
+Assuming you have configured all of your KDCs to be able to function
+as either the master KDC or a slave KDC (as this document recommends),
+all you need to do to make the changeover is:
-If the master KDC is still running, do the following on the *old* master KDC:
+If the master KDC is still running, do the following on the *old*
+master KDC:
#. Kill the kadmind process.
#. Disable the cron job that propagates the database.
-#. Run your database propagation script manually, to ensure that the slaves all have the latest copy of the database. (See Propagate the Database to Each Slave KDC.) If there is a need to preserve per-principal policy information from the database, you should do a "kdb5_util dump -ov" in order to preserve that information and propogate that dump file securely by some means to the slave so that its database has the correct state of the per-principal policy information.
+#. Run your database propagation script manually, to ensure that the
+ slaves all have the latest copy of the database. (See Propagate
+ the Database to Each Slave KDC.) If there is a need to preserve
+ per-principal policy information from the database, you should do a
+ "kdb5_util dump -ov" in order to preserve that information and
+ propogate that dump file securely by some means to the slave so
+ that its database has the correct state of the per-principal policy
+ information.
On the *new* master KDC:
-#. Create a database keytab. (See Create a kadmind Keytab (optional).)
-#. Start the kadmind daemon. (See Start the Kerberos Daemons.)
-#. Set up the cron job to propagate the database. (See Propagate the Database to Each Slave KDC.)
-#. Switch the CNAMEs of the old and new master KDCs. (If you don't do this, you'll need to change the krb5.conf file on every client machine in your Kerberos realm.)
+#. Create a database keytab. (See Create a kadmind Keytab (optional).)
+#. Start the kadmind daemon. (See Start the Kerberos Daemons.)
+#. Set up the cron job to propagate the database. (See Propagate the
+ Database to Each Slave KDC.)
+#. Switch the CNAMEs of the old and new master KDCs. (If you don't do
+ this, you'll need to change the krb5.conf file on every client
+ machine in your Kerberos realm.)
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___install_kdc
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___install_kdc
.. _db_prop_label:
Database propagation
-=========================
-
-The Kerberos database resides on the master KDC, and must be propagated regularly (usually by a cron job) to the slave KDCs. In deciding how frequently the propagation should happen, you will need to balance the amount of time the propagation takes against the maximum reasonable amount of time a user should have to wait for a password change to take effect.
-
-If the propagation time is longer than this maximum reasonable time (e.g., you have a particularly large database, you have a lot of slaves, or you experience frequent network delays), you may wish to cut down on your propagation delay by performing the propagation in parallel. To do this, have the master KDC propagate the database to one set of slaves, and then have each of these slaves propagate the database to additional slaves.
+====================
+
+The Kerberos database resides on the master KDC, and must be
+propagated regularly (usually by a cron job) to the slave KDCs. In
+deciding how frequently the propagation should happen, you will need
+to balance the amount of time the propagation takes against the
+maximum reasonable amount of time a user should have to wait for a
+password change to take effect.
+
+If the propagation time is longer than this maximum reasonable time
+(e.g., you have a particularly large database, you have a lot of
+slaves, or you experience frequent network delays), you may wish to
+cut down on your propagation delay by performing the propagation in
+parallel. To do this, have the master KDC propagate the database to
+one set of slaves, and then have each of these slaves propagate the
+database to additional slaves.
See also :ref:`incr_db_prop_label`
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___realm_config
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___realm_config
Realm configuration decisions
-===============================
+=============================
-.. note:: This document was copied from **Kerberos V5 Installation Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+.. note:: This document was copied from **Kerberos V5 Installation
+ Guide** with minor changes. Currently it is under review.
+ Please, send your feedback, corrections and additions to
+ krb5-bugs@mit.edu. Your contribution is greatly
+ appreciated.
+Before installing Kerberos V5, it is necessary to consider the
+following issues:
+* The name of your Kerberos realm (or the name of each realm, if you
+ need more than one).
+* How you will map your hostnames onto Kerberos realms.
+* Which ports your KDC and and kadmin (database access) services will
+ use.
+* How many slave KDCs you need and where they should be located.
+* The hostnames of your master and slave KDCs.
+* How frequently you will propagate the database from the master KDC
+ to the slave KDCs.
-Before installing Kerberos V5, it is necessary to consider the following issues:
-- The name of your Kerberos realm (or the name of each realm, if you need more than one).
-- How you will map your hostnames onto Kerberos realms.
-- Which ports your KDC and and kadmin (database access) services will use.
-- How many slave KDCs you need and where they should be located.
-- The hostnames of your master and slave KDCs.
-- How frequently you will propagate the database from the master KDC to the slave KDCs.
-
-
-Contents:
+Contents
+--------
.. toctree::
:maxdepth: 2
db_prop.rst
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___realm_config
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___realm_config
.. _kdc_hn_label:
-
-
Hostnames for KDCs
-==========================
-
-.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
-
-MIT recommends that your KDCs have a predefined set of CNAME records (DNS hostname aliases), such as *kerberos* for the master KDC and *kerberos-1, kerberos-2, ...* for the slave KDCs. This way, if you need to swap a machine, you only need to change a DNS entry, rather than having to change hostnames.
-
-A new mechanism for locating KDCs of a realm through DNS has been added to the MIT Kerberos V5 distribution. A relatively new record type called SRV has been added to DNS. Looked up by a service name and a domain name, these records indicate the hostname and port number to contact for that service, optionally with weighting and prioritization. (See :rfc:`2782` if you want more information. You can follow the example below for straightforward cases.)
-
-The use with Kerberos is fairly straightforward. The domain name used in the SRV record name is the domain-style Kerberos realm name. (It is possible to have Kerberos realm names that are not DNS-style names, but we don't recommend it for Internet use, and our code does not support it well.) Several different Kerberos-related service names are used:
+==================
+
+.. note:: This document was copied from **Kerberos V5 System
+ Administrator's Guide** with minor changes. Currently it is
+ under review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is
+ greatly appreciated.
+
+MIT recommends that your KDCs have a predefined set of CNAME records
+(DNS hostname aliases), such as ``kerberos`` for the master KDC and
+``kerberos-1``, ``kerberos-2``, ... for the slave KDCs. This way, if
+you need to swap a machine, you only need to change a DNS entry,
+rather than having to change hostnames.
+
+A new mechanism for locating KDCs of a realm through DNS has been
+added to the MIT Kerberos V5 distribution. A relatively new record
+type called SRV has been added to DNS. Looked up by a service name
+and a domain name, these records indicate the hostname and port number
+to contact for that service, optionally with weighting and
+prioritization. (See :rfc:`2782` if you want more information. You
+can follow the example below for straightforward cases.)
+
+The use with Kerberos is fairly straightforward. The domain name used
+in the SRV record name is the domain-style Kerberos realm name. (It
+is possible to have Kerberos realm names that are not DNS-style names,
+but we don't recommend it for Internet use, and our code does not
+support it well.) Several different Kerberos-related service names
+are used:
_kerberos._udp
- This is for contacting any KDC by UDP. This entry will be used the most often. Normally you should list port 88 on each of your KDCs.
+ This is for contacting any KDC by UDP. This entry will be used
+ the most often. Normally you should list port 88 on each of your
+ KDCs.
_kerberos._tcp
- This is for contacting any KDC by TCP. The MIT KDC by default will not listen on any TCP ports, so unless you've changed the configuration or you're running another KDC implementation, you should leave this unspecified. If you do enable TCP support, normally you should use port 88.
+ This is for contacting any KDC by TCP. The MIT KDC by default
+ will not listen on any TCP ports, so unless you've changed the
+ configuration or you're running another KDC implementation, you
+ should leave this unspecified. If you do enable TCP support,
+ normally you should use port 88.
_kerberos-master._udp
- This entry should refer to those KDCs, if any, that will immediately see password changes to the Kerberos database. This entry is used only in one case, when the user is logging in and the password appears to be incorrect; the master KDC is then contacted, and the same password used to try to decrypt the response, in case the user's password had recently been changed and the first KDC contacted hadn't been updated. Only if that fails is an "incorrect password" error given.
-
- If you have only one KDC, or for whatever reason there is no accessible KDC that would get database changes faster than the others, you do not need to define this entry.
+ This entry should refer to those KDCs, if any, that will
+ immediately see password changes to the Kerberos database. This
+ entry is used only in one case, when the user is logging in and
+ the password appears to be incorrect; the master KDC is then
+ contacted, and the same password used to try to decrypt the
+ response, in case the user's password had recently been changed
+ and the first KDC contacted hadn't been updated. Only if that
+ fails is an "incorrect password" error given.
+
+ If you have only one KDC, or for whatever reason there is no
+ accessible KDC that would get database changes faster than the
+ others, you do not need to define this entry.
_kerberos-adm._tcp
- This should list port 749 on your master KDC. Support for it is not complete at this time, but it will eventually be used by the kadmin program and related utilities. For now, you will also need the admin_server entry in :ref:`krb5.conf`.
+ This should list port 749 on your master KDC. Support for it is
+ not complete at this time, but it will eventually be used by the
+ kadmin program and related utilities. For now, you will also need
+ the admin_server entry in :ref:`krb5.conf`.
_kpasswd._udp
- This should list port 464 on your master KDC. It is used when a user changes her password.
+ This should list port 464 on your master KDC. It is used when a
+ user changes her password.
+
+Be aware, however, that the DNS SRV specification requires that the
+hostnames listed be the canonical names, not aliases. So, for
+example, you might include the following records in your (BIND-style)
+zone file::
+
+ $ORIGIN foobar.com.
+ _kerberos TXT "FOOBAR.COM"
+ kerberos CNAME daisy
+ kerberos-1 CNAME use-the-force-luke
+ kerberos-2 CNAME bunny-rabbit
+ _kerberos._udp SRV 0 0 88 daisy
+ SRV 0 0 88 use-the-force-luke
+ SRV 0 0 88 bunny-rabbit
+ _kerberos-master._udp SRV 0 0 88 daisy
+ _kerberos-adm._tcp SRV 0 0 749 daisy
+ _kpasswd._udp SRV 0 0 464 daisy
+
+As with the DNS-based mechanism for determining the Kerberos realm of
+a host, we recommend distributing the information this way for use by
+other sites that may want to interact with yours using Kerberos, even
+if you don't immediately make use of it within your own site. If you
+anticipate installing a very large number of machines on which it will
+be hard to update the Kerberos configuration files, you may wish to do
+all of your Kerberos service lookups via DNS and not put the
+information (except for **admin_server** as noted above) in future
+versions of your krb5.conf files at all. Eventually, we hope to phase
+out the listing of server hostnames in the client-side configuration
+files; making preparations now will make the transition easier in the
+future.
-Be aware, however, that the DNS SRV specification requires that the hostnames listed be the canonical names, not aliases. So, for example, you might include the following records in your (BIND-style) zone file::
-
- $ORIGIN foobar.com.
- _kerberos TXT "FOOBAR.COM"
- kerberos CNAME daisy
- kerberos-1 CNAME use-the-force-luke
- kerberos-2 CNAME bunny-rabbit
- _kerberos._udp SRV 0 0 88 daisy
- SRV 0 0 88 use-the-force-luke
- SRV 0 0 88 bunny-rabbit
- _kerberos-master._udp SRV 0 0 88 daisy
- _kerberos-adm._tcp SRV 0 0 749 daisy
- _kpasswd._udp SRV 0 0 464 daisy
-
-
-As with the DNS-based mechanism for determining the Kerberos realm of a host, we recommend distributing the information this way for use by other sites that may want to interact with yours using Kerberos, even if you don't immediately make use of it within your own site. If you anticipate installing a very large number of machines on which it will be hard to update the Kerberos configuration files, you may wish to do all of your Kerberos service lookups via DNS and not put the information (except for *admin_server* as noted above) in future versions of your krb5.conf files at all. Eventually, we hope to phase out the listing of server hostnames in the client-side configuration files; making preparations now will make the transition easier in the future.
-
---------------
Feedback
+--------
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___hostnames
-
-
-
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___hostnames
Ports for the KDC and admin services
-======================================
+====================================
-The default ports used by Kerberos are port **88** for the KDC1 and port **749** for the admin server. You can, however, choose to run on other ports, as long as they are specified in each host's */etc/services* and :ref:`krb5.conf` files, and the :ref:`kdc.conf` file on each KDC. For a more thorough treatment of port numbers used by the Kerberos V5 programs, refer to the :ref:`conf_firewall_label`
+The default ports used by Kerberos are port 88 for the KDC1 and port
+749 for the admin server. You can, however, choose to run on other
+ports, as long as they are specified in each host's ``/etc/services``
+and :ref:`krb5.conf` files, and the :ref:`kdc.conf` file on each KDC.
+For a more thorough treatment of port numbers used by the Kerberos V5
+programs, refer to the :ref:`conf_firewall_label`.
-------------
+Feedback
+--------
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___realm_config
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___realm_config
Mapping hostnames onto Kerberos realms
-=============================================
+======================================
-.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+.. note:: This document was copied from **Kerberos V5 System
+ Administrator's Guide** with minor changes. Currently it is
+ under review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is
+ greatly appreciated.
Mapping hostnames onto Kerberos realms is done in one of two ways.
-The first mechanism, which has been in use for years in MIT-based Kerberos distributions, works through a set of rules in the :ref:`krb5.conf` configuration file. You can specify mappings for an entire domain or subdomain, and/or on a hostname-by-hostname basis. Since greater specificity takes precedence, you would do this by specifying the mappings for a given domain or subdomain and listing the exceptions.
-
-The second mechanism works by looking up the information in special TXT records in the Domain Name Service. This is currently not used by default because security holes could result if the DNS TXT records were spoofed. If this mechanism is enabled on the client, it will try to look up a TXT record for the DNS name formed by putting the prefix _kerberos in front of the hostname in question. If that record is not found, it will try using _kerberos and the host's domain name, then its parent domain, and so forth. So for the hostname *BOSTON.ENGINEERING.FOOBAR.COM*, the names looked up would be::
-
- _kerberos.boston.engineering.foobar.com
- _kerberos.engineering.foobar.com
- _kerberos.foobar.com
- _kerberos.com
-
-
-The value of the first TXT record found is taken as the realm name. (Obviously, this doesn't work all that well if a host and a subdomain have the same name, and different realms. For example, if all the hosts in the *ENGINEERING.FOOBAR.COM* domain are in the *ENGINEERING.FOOBAR.COM* realm, but a host named *ENGINEERING.FOOBAR.COM* is for some reason in another realm. In that case, you would set up TXT records for all hosts, rather than relying on the fallback to the domain name.)
-
-Even if you do not choose to use this mechanism within your site, you may wish to set it up anyway, for use when interacting with other sites.
-
-
---------------
+The first mechanism, which has been in use for years in MIT-based
+Kerberos distributions, works through a set of rules in the
+:ref:`krb5.conf` configuration file. You can specify mappings for an
+entire domain or subdomain, and/or on a hostname-by-hostname basis.
+Since greater specificity takes precedence, you would do this by
+specifying the mappings for a given domain or subdomain and listing
+the exceptions.
+
+The second mechanism works by looking up the information in special
+TXT records in the Domain Name Service. This is currently not used by
+default because security holes could result if the DNS TXT records
+were spoofed. If this mechanism is enabled on the client, it will try
+to look up a TXT record for the DNS name formed by putting the prefix
+``_kerberos`` in front of the hostname in question. If that record is
+not found, it will try using ``_kerberos`` and the host's domain name,
+then its parent domain, and so forth. So for the hostname
+``BOSTON.ENGINEERING.FOOBAR.COM``, the names looked up would be::
+
+ _kerberos.boston.engineering.foobar.com
+ _kerberos.engineering.foobar.com
+ _kerberos.foobar.com
+ _kerberos.com
+
+The value of the first TXT record found is taken as the realm name.
+(Obviously, this doesn't work all that well if a host and a subdomain
+have the same name, and different realms. For example, if all the
+hosts in the ``ENGINEERING.FOOBAR.COM`` domain are in the
+``ENGINEERING.FOOBAR.COM`` realm, but a host named
+``ENGINEERING.FOOBAR.COM`` is for some reason in another realm. In
+that case, you would set up TXT records for all hosts, rather than
+relying on the fallback to the domain name.)
+
+Even if you do not choose to use this mechanism within your site, you
+may wish to set it up anyway, for use when interacting with other
+sites.
Feedback
+--------
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___hostnames
-
-
-
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___hostnames
Kerberos realms
-==================
+===============
-Although your Kerberos realm can be any ASCII string, convention is to make it the same as your domain name, in **upper-case** letters.
+Although your Kerberos realm can be any ASCII string, convention is to
+make it the same as your domain name, in upper-case letters.
-For example, hosts in the domain *example.com* would be in the Kerberos realm::
-
- EXAMPLE.COM
+For example, hosts in the domain ``example.com`` would be in the
+Kerberos realm::
-If you need multiple Kerberos realms, MIT recommends that you use descriptive names which end with your domain name, such as::
+ EXAMPLE.COM
- BOSTON.EXAMPLE.COM
- HOUSTON.EXAMPLE.COM
+If you need multiple Kerberos realms, MIT recommends that you use
+descriptive names which end with your domain name, such as::
-------------
+ BOSTON.EXAMPLE.COM
+ HOUSTON.EXAMPLE.COM
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___realm_config
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___realm_config
Slave KDCs
-===============
+==========
-Slave KDCs provide an additional source of Kerberos ticket-granting services in the event of inaccessibility of the master KDC. The number of slave KDCs you need and the decision of where to place them, both physically and logically, depends on the specifics of your network.
+Slave KDCs provide an additional source of Kerberos ticket-granting
+services in the event of inaccessibility of the master KDC. The
+number of slave KDCs you need and the decision of where to place them,
+both physically and logically, depends on the specifics of your
+network.
-All of the Kerberos authentication on your network requires that each client be able to contact a KDC. Therefore, you need to anticipate any likely reason a KDC might be unavailable and have a slave KDC to take up the slack.
+All of the Kerberos authentication on your network requires that each
+client be able to contact a KDC. Therefore, you need to anticipate
+any likely reason a KDC might be unavailable and have a slave KDC to
+take up the slack.
Some considerations include:
-- Have at least one slave KDC as a backup, for when the master KDC is down, is being upgraded, or is otherwise unavailable.
-- If your network is split such that a network outage is likely to cause a network partition (some segment or segments of the network to become cut off or isolated from other segments), have a slave KDC accessible to each segment.
-- If possible, have at least one slave KDC in a different building from the master, in case of power outages, fires, or other localized disasters.
+* Have at least one slave KDC as a backup, for when the master KDC is
+ down, is being upgraded, or is otherwise unavailable.
+* If your network is split such that a network outage is likely to
+ cause a network partition (some segment or segments of the network
+ to become cut off or isolated from other segments), have a slave KDC
+ accessible to each segment.
+* If possible, have at least one slave KDC in a different building
+ from the master, in case of power outages, fires, or other localized
+ disasters.
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___realm_config
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___realm_config
Troubleshooting
-================
+===============
List
----
+.. error:: KDC has no support for encryption type while getting
+ initial credentials
-.. error:: KDC has no support for encryption type while getting initial credentials
+.. error:: credential verification failed: KDC has no support for
+ encryption type
-.. error:: credential verification failed: KDC has no support for encryption type
-
-
-
-Add **allow_weak_crypto = true** to the [libdefaults] section of krb5.conf
+Add ``allow_weak_crypto = true`` to the [libdefaults] section of
+krb5.conf.
Version 1.7+
-Seen in: clients
+Seen in: clients
---------------------------------------------------------------------------------------------
+----
.. error:: Hostname cannot be canonicalized
The problem is that ssh is attempting to authenticate to the
canonicalization of inside-host in DNS, but since that's inside your
internal network, there is no DNS available to do the
-canonicalization, so one needs to tell GSSAPI what the hostname is separately.
+canonicalization, so one needs to tell GSSAPI what the hostname is
+separately.
| Host inside-host
| GSSAPITrustDns no
| HostName inside-host.inside.domain
| ProxyCommand ssh -t jump-box.example.com "nc -w2 %h %p"
-
-GSSAPITrustDns yes is setting the exact opposite of rdns = false. It's the equivalent of rdns = true.
+``GSSAPITrustDns yes`` is setting the exact opposite of ``rdns =
+false``. It's the equivalent of ``rdns = true``.
External links: [http://www.mail-archive.com/kerberos@mit.edu/msg17101.html]
-Seen in: ssh
+Seen in: ssh
-
---------------------------------------------------------------------------------------------
+----
.. error:: Wrong principal in request
-
-If referrals are being used, specifying the host to realm mapping in the krb5 profile results
-in the referrals logic being disabled and may solve the problem.
+If referrals are being used, specifying the host to realm mapping in
+the krb5 profile results in the referrals logic being disabled and may
+solve the problem.
External links: [http://www.mail-archive.com/kerberos@mit.edu/msg16257.html]
-Seen in: ssh
-
---------------------------------------------------------------------------------------------
+Seen in: ssh
+----
.. include:: ./install_kdc/kdc_prop_slave.rst
:start-after: _prop_failed_start:
:end-before: _prop_failed_end:
+----
---------------------------------------------------------------------------------------------
-
-
-.. error:: Unable to find requested database type - while initializing database for realm X.Y
+.. error:: Unable to find requested database type - while initializing
+ database for realm X.Y
-Set *db_module_dir* in :ref:`dbmodules` to the absolute path to the location of the database plugin
+Set **db_module_dir** in :ref:`dbmodules` to the absolute path to the
+location of the database plugin
---------------------------------------------------------------------------------------------
-..
+----
-------------------
Feedback
+--------
-
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___errors
-
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___errors
-Various links
-==============================================================
+Various links
+=============
-Whitepapers:
-------------
+Whitepapers
+-----------
#. http://kerberos.org/software/whitepapers.html
-Tutorials:
------------
+Tutorials
+---------
#. Fulvio Ricciardi <http://www.kerberos.org/software/tutorial.html>_
-Troubleshooting:
-----------------
+Troubleshooting
+---------------
#. http://www.ncsa.illinois.edu/UserInfo/Resources/Software/kerberos/troubleshooting.html
#. http://h71000.www7.hp.com/doc/83final/ba548_90007/ch06s05.html
-..
-
-------------------
Feedback
+--------
-
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___various_envs
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___various_envs
Differences between Heimdal and MIT Kerberos API
-==================================================================================
+================================================
.. note:: :c:func:`krb5_auth_con_getaddrs()`
-Heimdal: If either of the pointers to local_addr and remote_addr is not NULL,
- it is freed first and then reallocated before being populated with
- the content of corresponding address from authentication context.
+Heimdal: If either of the pointers to local_addr and remote_addr is
+not NULL, it is freed first and then reallocated before being
+populated with the content of corresponding address from
+authentication context.
.. note:: :c:func:`krb5_auth_con_setaddrs()`
-Heimdal: If either address is NULL, the previous address remains in place
+Heimdal: If either address is NULL, the previous address remains in
+place
.. note:: :c:func:`krb5_auth_con_setports()`
.. note:: :c:func:`krb5_auth_con_setrecvsubkey()`
-Heimdal: If either port is NULL, the previous port remains in place
+Heimdal: If either port is NULL, the previous port remains in place
.. note:: :c:func:`krb5_auth_con_setsendsubkey()`
.. note:: :c:func:`krb5_cc_set_config()`
-MIT: Before version 1.10 it was assumed that the last arguments *data* is ALWAYS non-zero.
+MIT: Before version 1.10 it was assumed that the last arguments *data*
+is ALWAYS non-zero.
-.. note:: :c:func:`krb5_cccol_last_change_time ()`
+.. note:: :c:func:`krb5_cccol_last_change_time()`
Prototype difference.
Heimdal takes three arguments:
| krb5_context context,
- | const char type,
- | krb5_timestamp \* change_time
+ | const char \*type,
+ | krb5_timestamp \*change_time
-MIT takes two arguments:
+MIT takes two arguments:
- | krb5_context context,
- | krb5_timestamp * change_time
+ | krb5_context context,
+ | krb5_timestamp \*change_time
.. note:: :c:func:`krb5_set_default_realm()`
-Heimdal: Caches the computed default realm context field.
- If the second argument is NULL, it tries to retrieve it from libdefaults or DNS.
-
-MIT: Computes the default realm each time if it wasn't explicitly set in the context
+Heimdal: Caches the computed default realm context field. If the
+second argument is NULL, it tries to retrieve it from libdefaults or
+DNS.
-..
+MIT: Computes the default realm each time if it wasn't explicitly set
+in the context
-------------------
Feedback
+--------
-
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___h5lMITdiff
-
-
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___h5lMITdiff
For application developers
-===================================
-
-Contents:
----------
+==========================
+Contents
+--------
.. toctree::
:maxdepth: 1
princ_handle.rst
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___appdev
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___appdev
Principal manipulation and parsing
-============================================
+==================================
Kerberos principal structure
..
-------------------
Feedback
+--------
-
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___princ_handle
-
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___princ_handle
Organization of the source directory
-============================================
+====================================
-Below is a brief overview of the organization of the complete source directory. More detailed descriptions follow.
+Below is a brief overview of the organization of the complete source
+directory. More detailed descriptions follow.
=============== ==============================================
-*appl* Kerberos application client and server programs
-*ccapi* Credential cache services
-*clients* Kerberos V5 user programs (See :ref:`user_commands`)
-*config* Configure scripts
-*config-files* Sample Kerberos configuration files
-*gen-manpages* *manpages* for Kerberos V5 and the Kerberos V5 login program
-*include* *include* files needed to build the Kerberos system
-*kadmin* Administrative interface to the Kerberos master database: :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, :ref:`ktutil(1)`.
-*kdc* Kerberos V5 Authentication Service and Key Distribution Center
-*kim* Kerberos Identiry Management API
-lib_ Libraries for use with/by Kerberos V5
-*plugins* Kerberos plugins directory
-*po* Localization infrastructure
-*prototype* Templates files containing the MIT copyright message and a placeholder for the title and description of the file.
-*slave* Utilities for propagating the database to slave KDCs :ref:`kprop(8)` and :ref:`kpropd(8)`
-*tests* Test suite
-util_ Various utilities for building/configuring the code, sending bug reports, etc.
-*windows* Source code for building Kerberos V5 on Windows (see windows/README)
+appl Kerberos application client and server programs
+ccapi Credential cache services
+clients Kerberos V5 user programs (See :ref:`user_commands`)
+config Configure scripts
+config-files Sample Kerberos configuration files
+gen-manpages manpages for Kerberos V5 and the Kerberos V5 login program
+include include files needed to build the Kerberos system
+kadmin Administrative interface to the Kerberos master database: :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, :ref:`ktutil(1)`.
+kdc Kerberos V5 Authentication Service and Key Distribution Center
+kim Kerberos Identiry Management API
+lib_ Libraries for use with/by Kerberos V5
+plugins Kerberos plugins directory
+po Localization infrastructure
+prototype Templates files containing the MIT copyright message and a placeholder for the title and description of the file.
+slave Utilities for propagating the database to slave KDCs :ref:`kprop(8)` and :ref:`kpropd(8)`
+tests Test suite
+util_ Various utilities for building/configuring the code, sending bug reports, etc.
+windows Source code for building Kerberos V5 on Windows (see windows/README)
=============== ==============================================
.. _lib:
-**lib**
-------------------
+lib
+---
-The *lib* directory contain several subdirectories as well as some definition and glue files.
+The lib directory contain several subdirectories as well as some
+definition and glue files.
- - The *apputils* directory contains the code for the generic network servicing.
- - The *crypto* subdirectory contains the Kerberos V5 encryption library.
- - The *gssapi* library contains the Generic Security Services API, which is a library of commands to be used in secure client-server communication.
- - The *kadm5* directory contains the libraries for the KADM5 administration utilities.
- - The Kerberos 5 database libraries are contained in *kdb*.
- - The *krb5* directory contains Kerberos 5 API.
- - The *rpc* directory contains the API for the Kerberos Remote Procedure Call protocol.
+ - The apputils directory contains the code for the generic network
+ servicing.
+ - The crypto subdirectory contains the Kerberos V5 encryption
+ library.
+ - The gssapi library contains the Generic Security Services API,
+ which is a library of commands to be used in secure client-server
+ communication.
+ - The kadm5 directory contains the libraries for the KADM5
+ administration utilities.
+ - The Kerberos 5 database libraries are contained in kdb.
+ - The krb5 directory contains Kerberos 5 API.
+ - The rpc directory contains the API for the Kerberos Remote
+ Procedure Call protocol.
.. _util:
-**util**
------------------------------------
-
-
-The *util* directory contains several utility programs and libraries.
- - the programs used to configure and build the code, such as *autoconf, lndir, kbuild, reconf*, and *makedepend*, are in this directory.
- - the *profile* directory contains most of the functions which parse the Kerberos configuration files (*krb5.conf* and *kdc.conf*).
- - the Kerberos error table library and utilities (*et*);
- - the Sub-system library and utilities (*ss*);
- - database utilities (*db2*);
- - pseudo-terminal utilities (*pty*);
- - bug-reporting program *send-pr*;
- - a generic support library *support* used by several of our other libraries;
- - the build infrastructure for building lightweight Kerberos client (*collected-client-lib*)
- - the tool for validating Kerberos configuration files (*confvalidator*);
- - the toolkit for kernel integrators for building krb5 code subsets (*gss-kernel-lib*);
- - source code for building Kerberos V5 on MacOS (*mac*)
- - Windows *getopt* operations (*windows*)
+util
+----
+The util directory contains several utility programs and libraries.
+ - the programs used to configure and build the code, such as
+ autoconf, lndir, kbuild, reconf, and makedepend, are in this
+ directory.
+ - the profile directory contains most of the functions which parse
+ the Kerberos configuration files (krb5.conf and kdc.conf).
+ - the Kerberos error table library and utilities (et);
+ - the Sub-system library and utilities (ss);
+ - database utilities (db2);
+ - pseudo-terminal utilities (pty);
+ - bug-reporting program send-pr;
+ - a generic support library support used by several of our other
+ libraries;
+ - the build infrastructure for building lightweight Kerberos client
+ (collected-client-lib)
+ - the tool for validating Kerberos configuration files
+ (confvalidator);
+ - the toolkit for kernel integrators for building krb5 code subsets
+ (gss-kernel-lib);
+ - source code for building Kerberos V5 on MacOS (mac)
+ - Windows getopt operations (windows)
Doing the build
-======================
+===============
-Using *autoconf*
--------------------
+Using autoconf
+--------------
(If you are not a developer, you can skip this section.)
-In most of the Kerberos V5 source directories, there is a *configure* script which automatically determines
-the compilation environment and creates the proper Makefiles for a particular platform.
-These configure files are generated using *autoconf*, which can be found in the *src/util/autoconf* directory in the distribution.
+In most of the Kerberos V5 source directories, there is a configure
+script which automatically determines the compilation environment and
+creates the proper Makefiles for a particular platform. These
+configure files are generated using autoconf, which can be found in
+the ``src/util/autoconf`` directory in the distribution.
-Normal users will not need to worry about running *autoconf*; the distribution comes with the configure files already prebuilt.
+Normal users will not need to worry about running autoconf; the
+distribution comes with the configure files already prebuilt.
-Note that in order to run *autoconf*, you must have GNU m4 in your path.
-Before you use the *autoconf* in the Kerberos V5 source tree, you may also need to run configure,
-and then run make in the *src/util/autoconf* directory in order to properly set up *autoconf*.
+Note that in order to run autoconf, you must have GNU m4 in your path.
+Before you use the autoconf in the Kerberos V5 source tree, you may
+also need to run configure, and then run make in the
+``src/util/autoconf`` directory in order to properly set up autoconf.
-One tool which is provided for the convenience of developers can be found in *src/util/reconf*.
-This program should be run while the current directory is the top source directory.
-It will automatically rebuild any configure files which need rebuilding.
-If you know that you have made a change that will require that all the configure files need to be rebuilt from scratch, specify the *--force* option::
+One tool which is provided for the convenience of developers can be
+found in ``src/util/reconf``. This program should be run while the
+current directory is the top source directory. It will automatically
+rebuild any configure files which need rebuilding. If you know that
+you have made a change that will require that all the configure files
+need to be rebuilt from scratch, specify the **--force** option::
- cd /u1/krb5-1.9/src
- ./util/reconf --force
-
-Then follow the instructions for building packaged source trees (below).
-To install the binaries into a binary tree, do::
+ cd /u1/krb5-1.9/src
+ ./util/reconf --force
- cd /u1/krb5-1.9/src
- make all
- make install DESTDIR=somewhere-else
-
-You have a number of different options in how to build Kerberos.
+Then follow the instructions for building packaged source trees
+(below). To install the binaries into a binary tree, do::
+
+ cd /u1/krb5-1.9/src
+ make all
+ make install DESTDIR=somewhere-else
+
+You have a number of different options in how to build Kerberos.
.. _do_build:
Building within a single tree
--------------------------------
+-----------------------------
-If you only need to build Kerberos for one platform, using a single directory tree
-which contains both the source files and the object files is the simplest.
-However, if you need to maintain Kerberos for a large number of platforms,
-you will probably want to use separate build trees for each platform.
-We recommend that you look at OS Incompatibilities, for notes that we have on particular operating systems.
+If you only need to build Kerberos for one platform, using a single
+directory tree which contains both the source files and the object
+files is the simplest. However, if you need to maintain Kerberos for
+a large number of platforms, you will probably want to use separate
+build trees for each platform. We recommend that you look at OS
+Incompatibilities, for notes that we have on particular operating
+systems.
-If you don't want separate build trees for each architecture, then use the following abbreviated procedure::
+If you don't want separate build trees for each architecture, then use
+the following abbreviated procedure::
- 1. cd /u1/krb5-1.9/src
- 2. ./configure
- 3. make
+ cd /u1/krb5-1.9/src
+ ./configure
+ make
That's it!
Building with separate build directories
---------------------------------------------
+----------------------------------------
-If you wish to keep separate build directories for each platform, you can do so using the following procedure.
-(Note, this requires that your make program support *VPATH*. GNU's make will provide this functionality, for example.)
-If your make program does not support this, see the next section.
+If you wish to keep separate build directories for each platform, you
+can do so using the following procedure. (Note, this requires that
+your make program support VPATH. GNU's make will provide this
+functionality, for example.) If your make program does not support
+this, see the next section.
-For example, if you wish to store the binaries in *tmpbuild* build directory you might use the following procedure::
+For example, if you wish to store the binaries in ``tmpbuild`` build
+directory you might use the following procedure::
- 1. mkdir /u1/tmpbuild
- 2. cd /u1/tmpbuild
- 3. /u1/krb5-1.9/src/configure
- 4. make
+ mkdir /u1/tmpbuild
+ cd /u1/tmpbuild
+ /u1/krb5-1.9/src/configure
+ make
-Building using *lndir*
------------------------
-If you wish to keep separate build directories for each platform,
-and you do not have access to a make program which supports VPATH, all is not lost.
-You can use the lndir program to create symbolic link trees in your build directory.
+Building using lndir
+--------------------
-For example, if you wish to create a build directory for solaris binaries you might use the following procedure::
+If you wish to keep separate build directories for each platform, and
+you do not have access to a make program which supports VPATH, all is
+not lost. You can use the lndir program to create symbolic link trees
+in your build directory.
- 1. mkdir /u1/krb5-1.9/solaris
- 2. cd /u1/krb5-1.9/solaris
- 3. /u1/krb5-1.9/src/util/lndir `pwd`/../src
- 4. ./configure
- 5. make
+For example, if you wish to create a build directory for solaris
+binaries you might use the following procedure:
-You must give an absolute pathname to *lndir* because it has a bug that makes it fail for relative pathnames.
-Note that this version differs from the latest version as distributed and installed by the XConsortium with X11R6.
-Either version should be acceptable.
+ mkdir /u1/krb5-1.9/solaris
+ cd /u1/krb5-1.9/solaris
+ /u1/krb5-1.9/src/util/lndir `pwd`/../src
+ ./configure
+ make
+
+You must give an absolute pathname to lndir because it has a bug that
+makes it fail for relative pathnames. Note that this version differs
+from the latest version as distributed and installed by the
+XConsortium with X11R6. Either version should be acceptable.
Installing the binaries
--------------------------
+-----------------------
+
+Once you have built Kerberos, you should install the binaries. You can
+do this by running::
-Once you have built Kerberos, you should install the binaries. You can do this by running::
+ make install
- make install
-
+If you want to install the binaries into a destination directory that
+is not their final destination, which may be convenient if you want to
+build a binary distribution to be deployed on multiple hosts, you may
+use::
-If you want to install the binaries into a destination directory that is not their final destination,
-which may be convenient if you want to build a binary distribution to be deployed on multiple hosts, you may use::
+ make install DESTDIR=/path/to/destdir
- make install DESTDIR=/path/to/destdir
-
+This will install the binaries under *DESTDIR/PREFIX*, e.g., the user
+programs will install into *DESTDIR/PREFIX/bin*, the libraries into
+*DESTDIR/PREFIX/lib*, etc.
-This will install the binaries under *DESTDIR/PREFIX*, e.g., the user programs will install into *DESTDIR/PREFIX/bin*,
-the libraries into *DESTDIR/PREFIX/lib*, etc.
+Some implementations of make allow multiple commands to be run in
+parallel, for faster builds. We test our Makefiles in parallel builds
+with GNU make only; they may not be compatible with other parallel
+build implementations.
-Some implementations of make allow multiple commands to be run in parallel, for faster builds.
-We test our Makefiles in parallel builds with GNU make only; they may not be compatible with other parallel build implementations.
Testing the build
---------------------
+-----------------
-The Kerberos V5 distribution comes with built-in regression tests.
-To run them, simply type the following command while in the top-level build directory
-(i.e., the directory where you sent typed make to start building Kerberos; see :ref:`do_build`)::
+The Kerberos V5 distribution comes with built-in regression tests. To
+run them, simply type the following command while in the top-level
+build directory (i.e., the directory where you sent typed make to
+start building Kerberos; see :ref:`do_build`)::
- make check
-
+ make check
However, there are several prerequisites that must be satisfied first:
- * Configure and build Kerberos with Tcl support. Tcl is used to drive the test suite.
- This often means passing *--with-tcl* to configure to tell it the location of the Tcl configuration script. (See :ref:`options2configure`.)
- * On some operating systems, you have to run *make install* before
- running *make check*, or the test suite will pick up installed
- versions of Kerberos libraries rather than the newly built ones.
- You can install into a prefix that isn't in the system library
- search path, though. Alternatively, you can configure with
- *--disable-rpath*, which renders the build tree less suitable
- for installation, but allows testing without interference from
- previously installed libraries.
- * In order to test the RPC layer, the local system has to be running the *portmap* daemon and
- it has to be listening to the regular network interface (not just localhost).
-
-
-Cleaning up the build
--------------------------
-
- - Use *make clean* to remove all files generated by running *make* command.
- - Use *make distclean* to remove all files generated by running *./configure* script.
- After running *make distclean* your source tree (ideally) should look like the raw (just un-tarred) source tree with executed *util/reconf* command.
-
-
-
-
+* Configure and build Kerberos with Tcl support. Tcl is used to drive
+ the test suite. This often means passing **--with-tcl** to
+ configure to tell it the location of the Tcl configuration
+ script. (See :ref:`options2configure`.)
+* On some operating systems, you have to run ``make install`` before
+ running ``make check``, or the test suite will pick up installed
+ versions of Kerberos libraries rather than the newly built ones.
+ You can install into a prefix that isn't in the system library
+ search path, though. Alternatively, you can configure with
+ **--disable-rpath**, which renders the build tree less suitable for
+ installation, but allows testing without interference from
+ previously installed libraries.
+* In order to test the RPC layer, the local system has to be running
+ the portmap daemon and it has to be listening to the regular network
+ interface (not just localhost).
+
+
+Cleaning up the build
+---------------------
+
+* Use ``make clean`` to remove all files generated by running make
+ command.
+* Use ``make distclean`` to remove all files generated by running
+ ./configure script. After running ``make distclean`` your source
+ tree (ideally) should look like the raw (just un-tarred) source tree
+ with executed ``util/reconf`` command.
.. _build_V5:
Building Kerberos V5
-===================================
-
-.. note:: This document was copied from **Kerberos V5 Installation Guide** with minor changes.
- Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu.
- Your contribution is greatly appreciated.
-
+====================
+.. note:: This document was copied from **Kerberos V5 Installation
+ Guide** with minor changes. Currently it is under
+ review. Please, send your feedback, corrections and
+ additions to krb5-bugs@mit.edu. Your contribution is
+ greatly appreciated.
Build Requirements
-----------------------
-
-In order to build Kerberos V5, you will need approximately 60-70 megabytes of disk space.
-The exact amount will vary depending on the platform and whether the distribution is compiled with debugging symbol tables or not.
-
-Your C compiler must conform to ANSI C (ISO/IEC 9899:1990, "c89").
-Some operating systems do not have an ANSI C compiler, or their default compiler requires extra command-line options to enable ANSI C conformance.
-
-If you wish to keep a separate build tree, which contains the compiled \*.o file and executables,
-separate from your source tree, you will need a make program which supports *VPATH*,
-or you will need to use a tool such as lndir to produce a symbolic link tree for your build tree.
-
-The first step in each of these build procedures is to unpack the source distribution.
-The Kerberos V5 distribution comes in a tar file, generally named krb5-1.9.tar
-(for version 1.9. We will assume that version is 1.9. Please, adjust this number accordingly),
-which contains a compressed tar file consisting of the sources for all of Kerberos (generally krb5-1.9.tar.gz)
-and a PGP signature for this source tree (generally krb5-1.9.tar.gz.asc).
-MIT highly recommends that you verify the integrity of the source code using this signature.
-
-Unpack the compressed tar file in some directory, such as /u1/krb5-1.9.
-(In the rest of this document, we will assume that you have chosen to unpack the Kerberos V5 source distribution in this directory.
-Note that the tarfiles will by default all unpack into the ./krb5-1.9 directory,
-so that if your current directory is /u1 when you unpack the tarfiles, you will get /u1/krb5-1.9/src, etc.)
-
-Contents:
----------
-
+------------------
+
+In order to build Kerberos V5, you will need approximately 60-70
+megabytes of disk space. The exact amount will vary depending on the
+platform and whether the distribution is compiled with debugging
+symbol tables or not.
+
+Your C compiler must conform to ANSI C (ISO/IEC 9899:1990, "c89").
+Some operating systems do not have an ANSI C compiler, or their
+default compiler requires extra command-line options to enable ANSI C
+conformance.
+
+If you wish to keep a separate build tree, which contains the compiled
+\*.o file and executables, separate from your source tree, you will
+need a make program which supports **VPATH**, or you will need to use
+a tool such as lndir to produce a symbolic link tree for your build
+tree.
+
+The first step in each of these build procedures is to unpack the
+source distribution. The Kerberos V5 distribution comes in a tar
+file, generally named krb5-1.9.tar (for version 1.9. We will assume
+that version is 1.9. Please, adjust this number accordingly), which
+contains a compressed tar file consisting of the sources for all of
+Kerberos (generally krb5-1.9.tar.gz) and a PGP signature for this
+source tree (generally krb5-1.9.tar.gz.asc). MIT highly recommends
+that you verify the integrity of the source code using this signature.
+
+Unpack the compressed tar file in some directory, such as
+``/u1/krb5-1.9``. (In the rest of this document, we will assume that
+you have chosen to unpack the Kerberos V5 source distribution in this
+directory. Note that the tarfiles will by default all unpack into the
+``./krb5-1.9`` directory, so that if your current directory is ``/u1``
+when you unpack the tarfiles, you will get ``/u1/krb5-1.9/src``, etc.)
+
+
+Contents
+--------
.. toctree::
:maxdepth: 1
test_cov.rst
+Feedback
+--------
-------------
-
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___build
-
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___build
.. _options2configure:\r
\r
Options to *configure*\r
-=========================\r
+======================\r
\r
-There are a number of options to configure which you can use to control \r
-how the Kerberos distribution is built. \r
+There are a number of options to configure which you can use to\r
+control how the Kerberos distribution is built.\r
\r
Most commonly used options\r
------------------------------\r
-\r
- ---help\r
-\r
- Provides help to configure. \r
- This will list the set of commonly used options for building Kerberos.\r
-\r
- --prefix=PREFIX\r
-\r
- By default, Kerberos will install the package's files rooted at '/usr/local'.\r
- If you desire to place the binaries into the directory *PREFIX*, use this option.\r
-\r
- --exec-prefix=EXECPREFIX\r
-\r
- This option allows one to separate the architecture independent programs\r
- from the host-dependent files (configuration files, manual pages).\r
- Use this option to install architecture-dependent programs in *EXECPREFIX*.\r
- The default location is the value of specified by *prefix* option.\r
-\r
- --localstatedir=LOCALSTATEDIR\r
- \r
- This option sets the directory for locally modifiable single-machine data. \r
- In Kerberos, this mostly is useful for setting a location for the KDC data files, \r
- as they will be installed in *LOCALSTATEDIR/krb5kdc*, \r
- which is by default *PREFIX/var/krb5kdc*.\r
-\r
- --with-netlib[=libs]\r
-\r
- Allows for suppression of or replacement of network libraries. \r
- By default, Kerberos V5 configuration will look for *-lnsl* and *-lsocket*. \r
- If your operating system has a broken resolver library \r
- or fails to pass the tests in 'src/tests/resolv', you will need to use this option.\r
-\r
- --with-tcl=TCLPATH\r
-\r
- Some of the unit-tests in the build tree rely upon using a program in Tcl. \r
- The directory specified by *TCLPATH* specifies where the Tcl header file \r
- (TCLPATH/include/tcl.h) \r
- as well as where the Tcl library (TCLPATH/lib) should be found.\r
-\r
- --enable-dns-for-realm\r
-\r
- Enable the use of DNS to look up a host's Kerberos realm, or a realm's KDCs, \r
- if the information is not provided in :ref:`krb5.conf`. \r
- See :ref:`kdc_hn_label` for information about using DNS to locate the KDCs, \r
- and :ref:`mapping_hn_label` for information about using DNS to determine the default realm. \r
- By default, DNS lookups are enabled for the former but not for the latter.\r
-\r
- --with-system-et\r
- \r
- Use an installed version of the error-table (et) support software, \r
- the *compile_et* program, the com_err.h header file and the *com_err* library. \r
- If these are not in the default locations, you may wish to specify \r
- *CPPFLAGS=-I/some/dir* and *LDFLAGS=-L/some/other/dir* options at configuration time as well.\r
-\r
- If this option is not given, a version supplied with the Kerberos sources \r
- will be built and installed along with the rest of the Kerberos tree, \r
- for Kerberos applications to link against.\r
-\r
- --with-system-ss\r
-\r
- Use an installed version of the subsystem command-line interface software, \r
- the *mk_cmds* program, the ss/ss.h header file and the *ss* library. \r
- If these are not in the default locations, you may wish to specify \r
- *CPPFLAGS=-I/some/dir* and *LDFLAGS=-L/some/other/dir* options \r
- at configuration time as well. See also the *SS_LIB* option.\r
-\r
- If this option is not given, the *ss* library supplied with the Kerberos sources \r
- will be compiled and linked into those programs that need it; \r
- it will not be installed separately.\r
-\r
- --with-system-db\r
-\r
- Use an installed version of the Berkeley DB package, \r
- which must provide an API compatible with version 1.85. \r
- This option is unsupported and untested. \r
- In particular, we do not know if the database-rename code used \r
- in the dumpfile load operation will behave properly.\r
-\r
- If this option is not given, a version supplied with the Kerberos sources \r
- will be built and installed. \r
- (We are not updating this version at this time because of licensing issues \r
- with newer versions that we haven't investigated sufficiently yet.)\r
+--------------------------\r
+\r
+**--help**\r
+ Provides help to configure. This will list the set of commonly\r
+ used options for building Kerberos.\r
+\r
+**--prefix=**\ *PREFIX*\r
+ By default, Kerberos will install the package's files rooted at\r
+ ``/usr/local``. If you desire to place the binaries into the\r
+ directory *PREFIX*, use this option.\r
+\r
+**--exec-prefix=**\ *EXECPREFIX*\r
+ This option allows one to separate the architecture independent\r
+ programs from the host-dependent files (configuration files,\r
+ manual pages). Use this option to install architecture-dependent\r
+ programs in *EXECPREFIX*. The default location is the value of\r
+ specified by **--prefix** option.\r
+\r
+**--localstatedir=**\ *LOCALSTATEDIR*\r
+ This option sets the directory for locally modifiable\r
+ single-machine data. In Kerberos, this mostly is useful for\r
+ setting a location for the KDC data files, as they will be\r
+ installed in ``LOCALSTATEDIR/krb5kdc``, which is by default\r
+ ``PREFIX/var/krb5kdc``.\r
+\r
+**--with-netlib**\ [=\ *libs*]\r
+ Allows for suppression of or replacement of network libraries. By\r
+ default, Kerberos V5 configuration will look for ``-lnsl`` and\r
+ ``-lsocket``. If your operating system has a broken resolver\r
+ library or fails to pass the tests in ``src/tests/resolv``, you\r
+ will need to use this option.\r
+\r
+**--with-tcl=**\ *TCLPATH*\r
+ Some of the unit-tests in the build tree rely upon using a program\r
+ in Tcl. The directory specified by *TCLPATH* specifies where the\r
+ Tcl header file (TCLPATH/include/tcl.h) as well as where the Tcl\r
+ library (TCLPATH/lib) should be found.\r
+\r
+**--enable-dns-for-realm**\r
+ Enable the use of DNS to look up a host's Kerberos realm, or a\r
+ realm's KDCs, if the information is not provided in\r
+ :ref:`krb5.conf`. See :ref:`kdc_hn_label` for information about\r
+ using DNS to locate the KDCs, and :ref:`mapping_hn_label` for\r
+ information about using DNS to determine the default realm. By\r
+ default, DNS lookups are enabled for the former but not for the\r
+ latter.\r
+\r
+**--with-system-et**\r
+ Use an installed version of the error-table (et) support software,\r
+ the compile_et program, the com_err.h header file and the com_err\r
+ library. If these are not in the default locations, you may wish\r
+ to specify ``CPPFLAGS=-I/some/dir`` and\r
+ ``LDFLAGS=-L/some/other/dir`` options at configuration time as\r
+ well.\r
+\r
+ If this option is not given, a version supplied with the Kerberos\r
+ sources will be built and installed along with the rest of the\r
+ Kerberos tree, for Kerberos applications to link against.\r
+\r
+**--with-system-ss**\r
+ Use an installed version of the subsystem command-line interface\r
+ software, the mk_cmds program, the ``ss/ss.h`` header file and the\r
+ ss library. If these are not in the default locations, you may\r
+ wish to specify ``CPPFLAGS=-I/some/dir`` and\r
+ ``LDFLAGS=-L/some/other/dir`` options at configuration time as\r
+ well. See also the **SS_LIB** option.\r
+\r
+ If this option is not given, the ss library supplied with the\r
+ Kerberos sources will be compiled and linked into those programs\r
+ that need it; it will not be installed separately.\r
+\r
+**--with-system-db**\r
+ Use an installed version of the Berkeley DB package, which must\r
+ provide an API compatible with version 1.85. This option is\r
+ unsupported and untested. In particular, we do not know if the\r
+ database-rename code used in the dumpfile load operation will\r
+ behave properly.\r
+\r
+ If this option is not given, a version supplied with the Kerberos\r
+ sources will be built and installed. (We are not updating this\r
+ version at this time because of licensing issues with newer\r
+ versions that we haven't investigated sufficiently yet.)\r
\r
\r
Environment variables\r
-----------------------------------------\r
+---------------------\r
\r
-CC=COMPILER\r
+**CC=**\ *COMPILER*\r
Use *COMPILER* as the C compiler.\r
\r
-CFLAGS=FLAGS\r
+**CFLAGS=**\ *FLAGS*\r
Use *FLAGS* as the default set of C compiler flags.\r
\r
-CPPFLAGS=CPPOPTS\r
- Use *CPPOPTS* as the default set of C preprocessor flags. \r
- The most common use of this option is to select certain #define's \r
- for use with the operating system's include files.\r
+**CPPFLAGS=**\ *CPPOPTS*\r
+ Use *CPPOPTS* as the default set of C preprocessor flags. The\r
+ most common use of this option is to select certain #define's for\r
+ use with the operating system's include files.\r
\r
-CPP=CPP \r
- C preprocessor to use. (e.g. CPP='gcc -E')\r
+**CPP=**\ *CPP*\r
+ C preprocessor to use. (e.g. ``CPP='gcc -E'``)\r
\r
-DB_HEADER=headername\r
- If db.h is not the correct header file to include to compile against the Berkeley DB 1.85 API, \r
- specify the correct header file name with this option. For example, DB_HEADER=db3/db_185.h.\r
+**DB_HEADER=**\ *headername*\r
+ If db.h is not the correct header file to include to compile\r
+ against the Berkeley DB 1.85 API, specify the correct header file\r
+ name with this option. For example, ``DB_HEADER=db3/db_185.h``.\r
\r
-DB_LIB=libs...\r
- If *-ldb* is not the correct library specification for the Berkeley DB library version to be used, \r
- override it with this option. For example, DB_LIB=-ldb-3.3. \r
+**DB_LIB=**\ *libs*...\r
+ If ``-ldb`` is not the correct library specification for the\r
+ Berkeley DB library version to be used, override it with this\r
+ option. For example, ``DB_LIB=-ldb-3.3``.\r
\r
-LD=LINKER\r
- Use *LINKER* as the default loader if it should be different from C compiler as specified above.\r
+**LD=**\ *LINKER*\r
+ Use *LINKER* as the default loader if it should be different from\r
+ C compiler as specified above.\r
\r
-LDFLAGS=LDOPTS\r
- This option informs the linker where to get additional libraries (e.g. -L<lib dir>).\r
+**LDFLAGS=**\ *LDOPTS*\r
+ This option informs the linker where to get additional libraries\r
+ (e.g. ``-L<lib dir>``).\r
\r
-LIBS=LDNAME\r
- This option allows one to specify libraries to be passed to the linker ( e.g. -l<library>)\r
+**LIBS=**\ *LDNAME*\r
+ This option allows one to specify libraries to be passed to the\r
+ linker (e.g. ``-l<library>``)\r
\r
-SS_LIB=libs...\r
- If *-lss* is not the correct way to link in your installed *ss* library, \r
- for example if additional support libraries are needed, \r
- specify the correct link options here. \r
- Some variants of this library are around which allow for Emacs-like line editing, \r
- but different versions require different support libraries to be explicitly specified.\r
+**SS_LIB=**\ *libs*...\r
+ If ``-lss`` is not the correct way to link in your installed ss\r
+ library, for example if additional support libraries are needed,\r
+ specify the correct link options here. Some variants of this\r
+ library are around which allow for Emacs-like line editing, but\r
+ different versions require different support libraries to be\r
+ explicitly specified.\r
\r
- This option is ignored if "with-system-ss" is not specified.\r
+ This option is ignored if **--with-system-ss** is not specified.\r
\r
-CXX \r
+**CXX**\r
C++ compiler command\r
\r
-CXXFLAGS\r
+**CXXFLAGS**\r
C++ compiler flags\r
\r
-YACC \r
+**YACC**\r
The 'Yet Another C Compiler' implementation to use. Defaults to\r
- the first program found out of: 'bison -y', 'byacc', 'yacc'.\r
+ the first program found out of: '`bison -y`', '`byacc`',\r
+ '`yacc`'.\r
\r
-YFLAGS \r
+**YFLAGS**\r
The list of arguments that will be passed by default to $YACC.\r
This script will default YFLAGS to the empty string to avoid a\r
- default value of '-d' given by some make applications.\r
-\r
-Fine tuning of the installation directories\r
-----------------------------------------------\r
-\r
- ---bindir=DIR \r
-\r
- User executables. \r
- Defaults to *EXECPREFIX/bin*, where *EXECPREFIX* is the path specified by "exec-prefix" configuration option.\r
-\r
- --sbindir=DIR \r
-\r
- System admin executables.\r
- Defaults to *EXECPREFIX/sbin*, where *EXECPREFIX* is the path specified by "exec-prefix" configuration option.\r
-\r
- --libexecdir=DIR \r
-\r
- Program executables.\r
- Defaults to *EXECPREFIX/libexec*, where *EXECPREFIX* is the path specified by "exec-prefix" configuration option.\r
-\r
- --sysconfdir=DIR \r
-\r
- Read-only single-machine data.\r
- Defaults to *PREFIX/etc*, where *PREFIX* is the path specified by "prefix" configuration option.\r
+ default value of ``-d`` given by some make applications.\r
\r
- --sharedstatedir=DIR\r
\r
- Modifiable architecture-independent data.\r
- Defaults to *PREFIX/com*, where *PREFIX* is the path specified by "prefix" configuration option.\r
-\r
- --libdir=DIR \r
-\r
- Object code libraries.\r
- Defaults to *EXECPREFIX/lib*, where *EXECPREFIX* is the path specified by "exec-prefix" configuration option.\r
-\r
- --includedir=DIR \r
-\r
- C header files.\r
- Defaults to *PREFIX/include*, where *PREFIX* is the path specified by "prefix" configuration option.\r
-\r
- --oldincludedir=DIR \r
-\r
- C header files for non-gcc. Default to '/usr/include'.\r
- \r
- --datarootdir=DATAROOTDIR \r
-\r
- Read-only architecture-independent data root.\r
- Defaults to *PREFIX/share*, where *PREFIX* is the path specified by "prefix" configuration option.\r
- \r
-\r
- --datadir=DIR \r
-\r
- Read-only architecture-independent data. \r
- Defaults to *DATAROOTDIR* by "datarootdir" configuration option.\r
- \r
- --infodir=DIR \r
-\r
- Info documentation.\r
- Defaults to *DATAROOTDIR/info*, where *DATAROOTDIR* is the path specified by "datarootdir" configuration option.\r
-\r
- --localedir=DIR \r
-\r
- Locale-dependent data.\r
- Defaults to *DATAROOTDIR/locale*, where *DATAROOTDIR* is the path specified by "datarootdir" configuration option.\r
- \r
- --mandir=DIR \r
-\r
- Man documentation.\r
- Defaults to *DATAROOTDIR/man*, where *DATAROOTDIR* is the path specified by "datarootdir" configuration option.\r
- \r
- --docdir=DOCDIR \r
-\r
- Documentation root.\r
- Defaults to *DATAROOTDIR/doc/krb5*, where *DATAROOTDIR* is the path specified by "datarootdir" configuration option.\r
- \r
- --htmldir=DIR \r
-\r
- *html* documentation.\r
- Defaults to *DOCDIR* path specified by "docdir" configuration option.\r
- \r
- --dvidir=DIR \r
-\r
- *dvi* documentation.\r
- Defaults to *DOCDIR* path specified by "docdir" configuration option.\r
- \r
- --pdfdir=DIR \r
-\r
- *pdf* documentation.\r
- Defaults to *DOCDIR* path specified by "docdir" configuration option.\r
- \r
- --psdir=DIR \r
-\r
- *ps* documentation.\r
- Defaults to *DOCDIR* path specified by "docdir" configuration option.\r
+Fine tuning of the installation directories\r
+-------------------------------------------\r
+\r
+**--bindir=**\ *DIR*\r
+ User executables. Defaults to ``EXECPREFIX/bin``, where\r
+ *EXECPREFIX* is the path specified by **--exec-prefix**\r
+ configuration option.\r
+\r
+**--sbindir=**\ *DIR*\r
+ System admin executables. Defaults to ``EXECPREFIX/sbin``, where\r
+ *EXECPREFIX* is the path specified by **--exec-prefix**\r
+ configuration option.\r
+\r
+**--libexecdir=**\ *DIR*\r
+ Program executables. Defaults to ``EXECPREFIX/libexec``, where\r
+ *EXECPREFIX* is the path specified by **--exec-prefix**\r
+ configuration option.\r
+\r
+**--sysconfdir=**\ *DIR*\r
+ Read-only single-machine data. Defaults to ``PREFIX/etc``, where\r
+ *PREFIX* is the path specified by **--prefix** configuration\r
+ option.\r
+\r
+**--sharedstatedir=**\ *DIR*\r
+ Modifiable architecture-independent data. Defaults to\r
+ ``PREFIX/com``, where *PREFIX* is the path specified by\r
+ **--prefix** configuration option.\r
+\r
+**--libdir=**\ *DIR*\r
+ Object code libraries. Defaults to ``EXECPREFIX/lib``, where\r
+ *EXECPREFIX* is the path specified by **--exec-prefix**\r
+ configuration option.\r
+\r
+**--includedir=**\ *DIR*\r
+ C header files. Defaults to ``PREFIX/include``, where *PREFIX* is\r
+ the path specified by **--prefix** configuration option.\r
+\r
+**--oldincludedir=**\ *DIR*\r
+ C header files for non-gcc. Default to ``/usr/include``.\r
+\r
+**--datarootdir=**\ *DATAROOTDIR*\r
+ Read-only architecture-independent data root. Defaults to\r
+ ``PREFIX/share``, where *PREFIX* is the path specified by\r
+ **--prefix** configuration option.\r
+\r
+**--datadir=**\ *DIR*\r
+ Read-only architecture-independent data. Defaults to path\r
+ specified by **--datarootdir** configuration option.\r
+\r
+**--infodir=**\ *DIR*\r
+ Info documentation. Defaults to ``DATAROOTDIR/info``, where\r
+ *DATAROOTDIR* is the path specified by **--datarootdir**\r
+ configuration option.\r
+\r
+**--localedir=**\ *DIR*\r
+ Locale-dependent data. Defaults to ``DATAROOTDIR/locale``, where\r
+ *DATAROOTDIR* is the path specified by **--datarootdir**\r
+ configuration option.\r
+\r
+**--mandir=**\ *DIR*\r
+ Man documentation. Defaults to ``DATAROOTDIR/man``, where\r
+ *DATAROOTDIR* is the path specified by **--datarootdir**\r
+ configuration option.\r
+\r
+**--docdir=**\ *DOCDIR*\r
+ Documentation root. Defaults to ``DATAROOTDIR/doc/krb5``, where\r
+ *DATAROOTDIR* is the path specified by **--datarootdir**\r
+ configuration option.\r
+\r
+**--htmldir=**\ *DIR*\r
+ HTML documentation. Defaults to path specified by **--docdir**\r
+ configuration option.\r
+\r
+**--dvidir=**\ *DIR*\r
+ DVI documentation. Defaults to path specified by **--docdir**\r
+ configuration option.\r
+\r
+**--pdfdir=**\ *DIR*\r
+ PDF documentation. Defaults to path specified by **--docdir**\r
+ configuration option.\r
+\r
+**--psdir=**\ *DIR*\r
+ PostScript documentation. Defaults to path specified by\r
+ **--docdir** configuration option.\r
\r
\r
Program names\r
-----------------------------------------------\r
- \r
- ---program-prefix=PREFIX \r
+-------------\r
\r
- Prepend *PREFIX* to the names of the programs when installing them. For example, specifying \r
- --program-prefix=mit- at the configure time will cause the program named *abc* to be installed \r
- as *mit-abc*.\r
- \r
- --program-suffix=SUFFIX \r
+**--program-prefix=**\ *PREFIX*\r
+ Prepend *PREFIX* to the names of the programs when installing\r
+ them. For example, specifying ``--program-prefix=mit-`` at the\r
+ configure time will cause the program named ``abc`` to be\r
+ installed as ``mit-abc``.\r
\r
- Append *SUFFIX* to the names of the programs when installing them. For example, specifying \r
- --program-suffix=-mit at the configure time will cause the program named *abc* to be installed \r
- as *abc-mit*.\r
- \r
- --program-transform-name=PROGRAM\r
+**--program-suffix=**\ *SUFFIX*\r
+ Append *SUFFIX* to the names of the programs when installing them.\r
+ For example, specifying ``--program-suffix=-mit`` at the configure\r
+ time will cause the program named ``abc`` to be installed as\r
+ ``abc-mit``.\r
\r
- Run *sed -e PROGRAM* on installed program names. (*PROGRAM* is a *sed* script).\r
+**--program-transform-name=**\ *PROGRAM*\r
+ Run ``sed -e PROGRAM`` on installed program names. (*PROGRAM* is a\r
+ sed script).\r
\r
\r
System types\r
-----------------------------------------------\r
-\r
- ---build=BUILD \r
+------------\r
\r
- Configure for building on *BUILD* (e.g. --build=x86_64-linux-gnu).\r
- \r
- --host=HOST \r
+**--build=**\ *BUILD*\r
+ Configure for building on *BUILD*\r
+ (e.g. ``--build=x86_64-linux-gnu``).\r
\r
- Cross-compile to build programs to run on *HOST* (e.g. --host=x86_64-linux-gnu). \r
- By default, Kerberos V5 configuration will look for "build" option.\r
+**--host=**\ *HOST*\r
+ Cross-compile to build programs to run on *HOST*\r
+ (e.g. ``--host=x86_64-linux-gnu``). By default, Kerberos V5\r
+ configuration will look for "build" option.\r
\r
\r
Optional features\r
-----------------------------------------------\r
-\r
- ---disable-FEATURE \r
-\r
- Do not include FEATURE (same as --enable-FEATURE=no).\r
- \r
- --disable-option-checking\r
-\r
- Ignore unrecognized --enable/--with options.\r
- \r
- --enable-FEATURE[=ARG] \r
+-----------------\r
\r
- Include FEATURE [ARG=yes].\r
- \r
- --enable-dns-for-realm\r
+**--disable-**\ *FEATURE*\r
+ Do not include *FEATURE* (same as --enable-FEATURE=no).\r
\r
- Enable DNS lookups of Kerberos realm names.\r
- \r
- --enable-maintainer-mode\r
+**--disable-option-checking**\r
+ Ignore unrecognized --enable/--with options.\r
\r
- Enable rebuilding of source files, Makefiles, etc.\r
- \r
- --disable-delayed-initialization\r
+**--enable-**\ *FEATURE*\ [=\ *ARG*]\r
+ Include *FEATURE* [ARG=yes].\r
\r
- Initialize library code when loaded.\r
- Defaults to delay until first use.\r
- \r
- --disable-thread-support\r
+**--enable-dns-for-realm**\r
+ Enable DNS lookups of Kerberos realm names.\r
\r
- Don't enable thread support. Defaults to enabled.\r
+**--enable-maintainer-mode**\r
+ Enable rebuilding of source files, Makefiles, etc.\r
\r
- --disable-rpath \r
+**--disable-delayed-initialization**\r
+ Initialize library code when loaded. Defaults to delay until\r
+ first use.\r
\r
- Suppress run path flags in link lines.\r
- \r
- --enable-athena \r
+**--disable-thread-support**\r
+ Don't enable thread support. Defaults to enabled.\r
\r
- Build with MIT Project Athena configuration.\r
- \r
- --enable-fortuna-test\r
+**--disable-rpath**\r
+ Suppress run path flags in link lines.\r
\r
- Build to test Fortuna PRNG.\r
- \r
- --disable-kdc-lookaside-cache\r
+**--enable-athena**\r
+ Build with MIT Project Athena configuration.\r
\r
- Disable the cache which detects client retransmits.\r
+**--enable-fortuna-test**\r
+ Build to test Fortuna PRNG.\r
\r
- --disable-pkinit \r
+**--disable-kdc-lookaside-cache**\r
+ Disable the cache which detects client retransmits.\r
\r
- Disable PKINIT plugin support.\r
+**--disable-pkinit**\r
+ Disable PKINIT plugin support.\r
\r
\r
Optional packages\r
-----------------\r
\r
+**--with-**\ *PACKAGE*\ [=ARG\]\r
+ Use *PACKAGE* (e.g. ``--with-imap``). The default value of *ARG*\r
+ is ``yes``.\r
\r
+**--without-**\ *PACKAGE*\r
+ Do not use *PACKAGE* (same as ``--with-PACKAGE=no``)\r
+ (e.g. ``--without-libedit``).\r
\r
- ---with-*PACKAGE* \[=ARG\]\r
- \r
- Use *PACKAGE* (e.g. --with-imap). The default value of *ARG* is 'yes'.\r
+**--with-size-optimizations**\r
+ Enable a few optimizations to reduce code size possibly at some\r
+ run-time cost.\r
\r
- --without-*PACKAGE* \r
+**--with-hesiod=**\ *path*\r
+ Compile with Hesiod support. The *path* points to the Hesiod\r
+ directory. By default Hesiod is unsupported.\r
\r
- Do not use *PACKAGE* (same as \-\-with-PACKAGE=no) (e.g. --without-libedit).\r
+**--with-ldap**\r
+ Compile OpenLDAP database backend module.\r
\r
- --with-size-optimizations\r
+**--with-edirectory**\r
+ Compile eDirectory database backend module.\r
\r
- Enable a few optimizations to reduce code size possibly at some run-time cost.\r
- \r
- --with-hesiod=path\r
+**--with-vague-errors**\r
+ Do not send helpful errors to client. For example, if the KDC\r
+ should return only vague error codes to clients.\r
\r
- Compile with Hesiod support. The *path* points to the Hesiod directory. \r
- By default Hesiod is unsupported.\r
- \r
- --with-ldap \r
+**--with-crypto-impl=**\ *IMPL*\r
+ Use specified crypto implementation (e.g. **--with-crypto=**\\r
+ *openssl*). Default is a native MIT Kerberos implementation\r
+ ``builtin``. The other currently implemented crypto backends are\r
+ ``openssl`` and ``nss``. (See :ref:`mitK5features`)\r
\r
- Compile OpenLDAP database backend module.\r
- \r
- --with-edirectory \r
+**--with-prng-alg=**\ *ALG*\r
+ Use specified PRNG algorithm. For example, to use the OS native\r
+ prng specify ``--with-prng-alg=os``.\r
\r
- Compile eDirectory database backend module.\r
- \r
- --with-vague-errors \r
+ Default is the ``fortuna`` PRNG algorithm. For the ``nss`` crypto\r
+ backend use one must explicitly specify ``--with-prng-alg=nss``.\r
+ (See :ref:`mitK5features`)\r
\r
- Do not send helpful errors to client. \r
- For example, if the KDC should return only vague error codes to clients.\r
- \r
- --with-crypto-impl=IMPL\r
+**--with-kdc-kdb-update**\r
+ Update the KDC database with the information about\r
\r
- Use specified crypto implementation (e.g. *--with-crypto=openssl*). \r
- Default is a native MIT Kerberos implementation *builtin*.\r
- The other currently implemented crypto backends are *openssl* and *nss*.\r
- (See :ref:`mitK5features`)\r
+ * the last successful authentication;\r
+ * the last failed authentication attempt;\r
+ * the number of the failed authentication attempts.\r
\r
- --with-prng-alg=ALG\r
+ By default the kdb is not updated with this information.\r
\r
- Use specified PRNG algorithm. \r
- For example, to use the OS native prng specify *--with-prng-alg=os*.\r
+**--with-system-verto**\r
+ Use an installed version of libverto. If the libverto header and\r
+ library are not in default locations, you may wish to specify\r
+ ``CPPFLAGS=-I/some/dir`` and ``LDFLAGS=-L/some/other/dir`` options\r
+ at configuration time as well.\r
\r
- Default is the *fortuna* PRNG algorithm. \r
- For the *nss* crypto backend use one must explicitly specify *--with-prng-alg=nss*. \r
- (See :ref:`mitK5features`)\r
-\r
- --with-kdc-kdb-update \r
-\r
- Update the KDC database with the information about \r
- \r
- - the last successful authentication;\r
- - the last failed authentication attempt;\r
- - the number of the failed authentication attempts.\r
-\r
- By default the kdb is not updated with this information.\r
- \r
- --with-system-verto\r
-\r
- Use an installed version of libverto. If the libverto header and\r
- library are not in default locations, you may wish to specify\r
- *CPPFLAGS=-I/some/dir* and *LDFLAGS=-L/some/other/dir* options at\r
- configuration time as well.\r
-\r
- If this option is not given, the build system will try to detect\r
- an installed version of libverto and use it if it is found.\r
- Otherwise, a version supplied with the Kerberos sources will be\r
- built and installed. The built-in version does not contain the\r
- full set of back-end modules and is not a suitable general\r
- replacement for the upstream version, but will work for the\r
- purposes of Kerberos.\r
-\r
- Specifying *--without-system-verto* will cause the built-in\r
- version of libverto to be used unconditionally.\r
+ If this option is not given, the build system will try to detect\r
+ an installed version of libverto and use it if it is found.\r
+ Otherwise, a version supplied with the Kerberos sources will be\r
+ built and installed. The built-in version does not contain the\r
+ full set of back-end modules and is not a suitable general\r
+ replacement for the upstream version, but will work for the\r
+ purposes of Kerberos.\r
\r
+ Specifying **--without-system-verto** will cause the built-in\r
+ version of libverto to be used unconditionally.\r
\r
\r
Examples\r
-----------\r
-\r
-For example, in order to configure Kerberos on a Solaris machine \r
-using the *suncc* compiler with the optimizer *turned on*, \r
-run the configure script with the following options::\r
+--------\r
\r
- % ./configure CC=suncc CFLAGS=-O\r
- \r
+For example, in order to configure Kerberos on a Solaris machine using\r
+the suncc compiler with the optimizer turned on, run the configure\r
+script with the following options::\r
\r
-For a slightly more complicated example, consider a system \r
-where several packages to be used by Kerberos are installed in /usr/foobar,\r
-including Berkeley DB 3.3, and an ss library that needs to link against the curses library. \r
-The configuration of Kerberos might be done thus::\r
+ % ./configure CC=suncc CFLAGS=-O\r
\r
- ./configure CPPFLAGS=-I/usr/foobar/include LDFLAGS=-L/usr/foobar/lib --with-system-et --with-system-ss --with-system-db SS_LIB='-lss -lcurses' DB_HEADER=db3/db_185.h DB_LIB=-ldb-3.3\r
- \r
+For a slightly more complicated example, consider a system where\r
+several packages to be used by Kerberos are installed in\r
+``/usr/foobar``, including Berkeley DB 3.3, and an ss library that\r
+needs to link against the curses library. The configuration of\r
+Kerberos might be done thus::\r
\r
+ ./configure CPPFLAGS=-I/usr/foobar/include LDFLAGS=-L/usr/foobar/lib --with-system-et --with-system-ss --with-system-db SS_LIB='-lss -lcurses' DB_HEADER=db3/db_185.h DB_LIB=-ldb-3.3\r
osconf.hin
-==============
+==========
-There is one configuration file which you may wish to edit to control various compile-time parameters in the Kerberos distribution::
+There is one configuration file which you may wish to edit to control
+various compile-time parameters in the Kerberos distribution::
- include/osconf.hin
-
-The list that follows is by no means complete, just some of the more interesting variables.
+ include/osconf.hin
+The list that follows is by no means complete, just some of the more
+interesting variables.
**DEFAULT_PROFILE_PATH**
- The pathname to the file which contains the profiles for the known realms, their KDCs, etc. The default value is /etc/krb5.conf.
+ The pathname to the file which contains the profiles for the known
+ realms, their KDCs, etc. The default value is ``/etc/krb5.conf``.
**DEFAULT_KEYTAB_NAME**
- The type and pathname to the default server keytab file. The default is /etc/krb5.keytab.
+ The type and pathname to the default server keytab file. The
+ default is ``/etc/krb5.keytab``.
**DEFAULT_KDC_ENCTYPE**
- The default encryption type for the KDC. The default value is aes256-cts-hmac-sha1-96.
+ The default encryption type for the KDC. The default value is
+ ``aes256-cts-hmac-sha1-96``.
**KDCRCACHE**
- The name of the replay cache used by the KDC. The default value is krb5kdc_rcache.
+ The name of the replay cache used by the KDC. The default value
+ is ``krb5kdc_rcache``.
**RCTMPDIR**
- The directory which stores replay caches. The default is /var/tmp.
+ The directory which stores replay caches. The default is
+ ``/var/tmp``.
**DEFAULT_KDB_FILE**
- The location of the default database. The default value is /usr/local/var/krb5kdc/principal.
+ The location of the default database. The default value is
+ ``/usr/local/var/krb5kdc/principal``.
-
Test coverage
-=================
+=============
-It is considered good practice to develop and maintain the test suite with high level
-of test coverage, i.e. the tests that execute every single statement, every line of the code and
-then validate the result.
+It is considered good practice to develop and maintain the test suite
+with high level of test coverage, i.e. the tests that execute every
+single statement, every line of the code and then validate the result.
-The GNU's *gcov* is a tool that analyses the frequency of execution of each line of the code.
-For more details see GNU documentation http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
+The GNU's gcov is a tool that analyses the frequency of execution of
+each line of the code. For more details see GNU documentation
+http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
-To invoke *gcov* on *krb5* tree, do *configure* with the following options and run the tests::
+To invoke gcov on krb5 tree, do configure with the following options
+and run the tests::
- ./configure CFLAGS="-fprofile-arcs -ftest-coverage -O0" LIBS=-lgcov
+ ./configure CFLAGS="-fprofile-arcs -ftest-coverage -O0" LIBS=-lgcov
make
make check
-It will result into creation of the new helper files with the extentions *gcno* and *gcda*.
-
-To validate the test coverage of the specific file, change the directory to
-its location and run ::
-
- gcov -o filename.so.gcno filename.c
-
-To see the test coverage of the *filename.c* open a newly created file *filename.c.gcov* in the editor.
-
-Some recent test coverage result can be found at the http://k5wiki.kerberos.org/wiki/Test_coverage
-
-
+It will result into creation of the new helper files with the
+extentions gcno and gcda.
+To validate the test coverage of the specific file, change the
+directory to its location and run ::
+ gcov -o filename.so.gcno filename.c
+To see the test coverage of the filename.c open a newly created file
+filename.c.gcov in the editor.
+Some recent test coverage result can be found at the
+http://k5wiki.kerberos.org/wiki/Test_coverage
For users
-===========
+=========
-::
+A collection of documents for Kerberos users
- A collection of documents for Kerberos users
+.. note:: This document was copied from **Kerberos V5 UNIX User's
+ Guide**. Currently it is under review. Please, send your
+ feedback, corrections and additions to krb5-bugs@mit.edu.
+ Your contribution is greatly appreciated.
-.. note:: This document was copied from **Kerberos V5 UNIX User's Guide**. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
-Contents:
----------
+Contents
+--------
.. toctree::
:maxdepth: 2
user_appl/index.rst
user_commands/index.rst
-------------
-Feedback:
-
-Please, provide your feedback or suggest a new topic at krb5-bugs@mit.edu?subject=Documentation___users
+Feedback
+--------
+Please, provide your feedback or suggest a new topic at
+krb5-bugs@mit.edu?subject=Documentation___users
.. _gatya_label:
Granting access to your account
-======================================
+===============================
-If you need to give someone access to log into your account, you can do so through Kerberos, without telling the person your password. Simply create a file called .k5login in your home directory. This file should contain the Kerberos principal of each person to whom you wish to give access. Each principal must be on a separate line. Here is a sample *.k5login* file::
+If you need to give someone access to log into your account, you can
+do so through Kerberos, without telling the person your password.
+Simply create a file called .k5login in your home directory. This
+file should contain the Kerberos principal of each person to whom you
+wish to give access. Each principal must be on a separate line. Here
+is a sample .k5login file::
- jennifer@ATHENA.MIT.EDU
- david@EXAMPLE.COM
+ jennifer@ATHENA.MIT.EDU
+ david@EXAMPLE.COM
-This file would allow the users *jennifer* and *david* to use your user ID, provided that they had Kerberos tickets in their respective realms. If you will be logging into other hosts across a network, you will want to include your own Kerberos principal in your *.k5login* file on each of these hosts.
+This file would allow the users ``jennifer`` and ``david`` to use your
+user ID, provided that they had Kerberos tickets in their respective
+realms. If you will be logging into other hosts across a network, you
+will want to include your own Kerberos principal in your .k5login file
+on each of these hosts.
-Using a *.k5login* file is much safer than giving out your password, because:
+Using a .k5login file is much safer than giving out your password,
+because:
-- You can take access away any time simply by removing the principal from your *.k5login* file.
-- Although the user has full access to your account on one particular host (or set of hosts if your *.k5login* file is shared, e.g., over NFS), that user does not inherit your network privileges.
-- Kerberos keeps a log of who obtains tickets, so a system administrator could find out, if necessary, who was capable of using your user ID at a particular time.
+* You can take access away any time simply by removing the principal
+ from your .k5login file.
-One common application is to have a *.k5login* file in root's home directory, giving root access to that machine to the Kerberos principals listed. This allows system administrators to allow users to become root locally, or to log in remotely as root, without their having to give out the root password, and without anyone having to type the root password over the network.
+* Although the user has full access to your account on one particular
+ host (or set of hosts if your .k5login file is shared, e.g., over
+ NFS), that user does not inherit your network privileges.
-------------------
+* Kerberos keeps a log of who obtains tickets, so a system
+ administrator could find out, if necessary, who was capable of using
+ your user ID at a particular time.
-Feedback:
+One common application is to have a .k5login file in root's home
+directory, giving root access to that machine to the Kerberos
+principals listed. This allows system administrators to allow users
+to become root locally, or to log in remotely as root, without their
+having to give out the root password, and without anyone having to
+type the root password over the network.
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
Password management
-============================
-
-.. note:: This document was copied from **Kerberos V5 UNIX User's Guide**. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
-
-
-
-Your password is the only way Kerberos has of verifying your identity. If someone finds out your password, that person can masquerade as you—send email that comes from you, read, edit, or delete your files, or log into other hosts as you—and no one will be able to tell the difference. For this reason, it is important that you choose a good password, and keep it secret. If you need to give access to your account to someone else, you can do so through Kerberos. (See :ref:`gatya_label`.) You should never tell your password to anyone, including your system administrator, for any reason. You should change your password frequently, particularly any time you think someone may have found out what it is.
-
-
+===================
+
+.. note:: This document was copied from **Kerberos V5 UNIX User's
+ Guide**. Currently it is under review. Please, send your
+ feedback, corrections and additions to krb5-bugs@mit.edu.
+ Your contribution is greatly appreciated.
+
+Your password is the only way Kerberos has of verifying your identity.
+If someone finds out your password, that person can masquerade as
+you--send email that comes from you, read, edit, or delete your files,
+or log into other hosts as you--and no one will be able to tell the
+difference. For this reason, it is important that you choose a good
+password, and keep it secret. If you need to give access to your
+account to someone else, you can do so through Kerberos. (See
+:ref:`gatya_label`.) You should never tell your password to anyone,
+including your system administrator, for any reason. You should
+change your password frequently, particularly any time you think
+someone may have found out what it is.
.. toctree::
:maxdepth: 1
grant_access.rst
pwd_quality.rst
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
Changing your password
-==========================
-
-To change your Kerberos password, use the *kpasswd* command. It will ask you for your old password (to prevent someone else from walking up to your computer when you're not there and changing your password), and then prompt you for the new one twice. (The reason you have to type it twice is to make sure you have typed it correctly.) For example, user *david* would do the following::
-
- shell% kpasswd
- Password for david: <- Type your old password.
- Enter new password: <- Type your new password.
- Enter it again: <- Type the new password again.
- Password changed.
- shell%
-
-If *david* typed the incorrect old password, he would get the following message::
-
- shell% kpasswd
- Password for david: <- Type the incorrect old password.
- kpasswd: Password incorrect while getting initial ticket
- shell%
-
-If you make a mistake and don't type the new password the same way twice, *kpasswd* will ask you to try again::
-
- shell% kpasswd
- Password for david: <- Type the old password.
- Enter new password: <- Type the new password.
- Enter it again: <- Type a different new password.
- kpasswd: Password mismatch while reading password
- shell%
-
-Once you change your password, it takes some time for the change to propagate through the system. Depending on how your system is set up, this might be anywhere from a few minutes to an hour or more. If you need to get new Kerberos tickets shortly after changing your password, try the new password. If the new password doesn't work, try again using the old one.
-
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
-
-
+======================
+
+To change your Kerberos password, use the kpasswd command. It will ask
+you for your old password (to prevent someone else from walking up to
+your computer when you're not there and changing your password), and
+then prompt you for the new one twice. (The reason you have to type
+it twice is to make sure you have typed it correctly.) For example,
+user ``david`` would do the following::
+
+ shell% kpasswd
+ Password for david: <- Type your old password.
+ Enter new password: <- Type your new password.
+ Enter it again: <- Type the new password again.
+ Password changed.
+ shell%
+
+If ``david`` typed the incorrect old password, he would get the
+following message::
+
+ shell% kpasswd
+ Password for david: <- Type the incorrect old password.
+ kpasswd: Password incorrect while getting initial ticket
+ shell%
+
+If you make a mistake and don't type the new password the same way
+twice, kpasswd will ask you to try again::
+
+ shell% kpasswd
+ Password for david: <- Type the old password.
+ Enter new password: <- Type the new password.
+ Enter it again: <- Type a different new password.
+ kpasswd: Password mismatch while reading password
+ shell%
+
+Once you change your password, it takes some time for the change to
+propagate through the system. Depending on how your system is set up,
+this might be anywhere from a few minutes to an hour or more. If you
+need to get new Kerberos tickets shortly after changing your password,
+try the new password. If the new password doesn't work, try again
+using the old one.
+
+
+Feedback
+--------
+
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
Password quality verification
-==============================
+=============================
TODO
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_pwd_mgmt
-Destroying tickets with *kdestroy*
-=====================================
+Destroying tickets with kdestroy
+================================
-Your Kerberos tickets are proof that you are indeed yourself, and tickets can be stolen. If this happens, the person who has them can masquerade as you until they expire. For this reason, you should destroy your Kerberos tickets when you are away from your computer.
+Your Kerberos tickets are proof that you are indeed yourself, and
+tickets can be stolen. If this happens, the person who has them can
+masquerade as you until they expire. For this reason, you should
+destroy your Kerberos tickets when you are away from your computer.
-Destroying your tickets is easy. Simply type *kdestroy*::
+Destroying your tickets is easy. Simply type kdestroy::
- shell% kdestroy
- shell%
+ shell% kdestroy
+ shell%
-If *kdestroy* fails to destroy your tickets, it will beep and give an error message. For example, if *kdestroy* can't find any tickets to destroy, it will give the following message::
+If kdestroy fails to destroy your tickets, it will beep and give an
+error message. For example, if kdestroy can't find any tickets to
+destroy, it will give the following message::
- shell% kdestroy
- kdestroy: No credentials cache file found while destroying cache
- shell%
-
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
+ shell% kdestroy
+ kdestroy: No credentials cache file found while destroying cache
+ shell%
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
Ticket management
-============================
-
-.. note:: This document was copied from **Kerberos V5 UNIX User's Guide**. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
-
-
-
-On many systems, Kerberos is built into the login program, and you get tickets automatically when you log in. Other programs, such as *rsh, rcp, telnet*, and *rlogin*, can forward copies of your tickets to the remote host. Most of these programs also automatically destroy your tickets when they exit. However, MIT recommends that you explicitly destroy your Kerberos tickets when you are through with them, just to be sure. One way to help ensure that this happens is to add the *kdestroy* command to your *.logout* file. Additionally, if you are going to be away from your machine and are concerned about an intruder using your permissions, it is safest to either destroy all copies of your tickets, or use a screensaver that locks the screen.
+=================
+
+.. note:: This document was copied from **Kerberos V5 UNIX User's
+ Guide**. Currently it is under review. Please, send your
+ feedback, corrections and additions to krb5-bugs@mit.edu.
+ Your contribution is greatly appreciated.
+
+On many systems, Kerberos is built into the login program, and you get
+tickets automatically when you log in. Other programs, such as rsh,
+rcp, telnet, and rlogin, can forward copies of your tickets to the
+remote host. Most of these programs also automatically destroy your
+tickets when they exit. However, MIT recommends that you explicitly
+destroy your Kerberos tickets when you are through with them, just to
+be sure. One way to help ensure that this happens is to add the
+kdestroy command to your .logout file. Additionally, if you are going
+to be away from your machine and are concerned about an intruder using
+your permissions, it is safest to either destroy all copies of your
+tickets, or use a screensaver that locks the screen.
.. toctree::
:maxdepth: 1
view_klist.rst
destroy_tkt.rst
-------------------
-
-Feedback:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
.. _otwk_labal:
Obtaining tickets with *kinit*
-==================================
+==============================
-If your site is using the Kerberos V5 login program, you will get Kerberos tickets automatically when you log in. If your site uses a different login program, you may need to explicitly obtain your Kerberos tickets, using the *kinit* program. Similarly, if your Kerberos tickets expire, use the *kinit* program to obtain new ones.
+If your site is using the Kerberos V5 login program, you will get
+Kerberos tickets automatically when you log in. If your site uses a
+different login program, you may need to explicitly obtain your
+Kerberos tickets, using the kinit program. Similarly, if your
+Kerberos tickets expire, use the kinit program to obtain new ones.
-To use the *kinit* program, simply type *kinit* and then type your password at the prompt. For example, Jennifer (whose username is *jennifer*) works for Bleep, Inc. (a fictitious company with the domain name mit.edu and the Kerberos realm ATHENA.MIT.EDU). She would type::
+To use the kinit program, simply type kinit and then type your
+password at the prompt. For example, Jennifer (whose username is
+``jennifer``) works for Bleep, Inc. (a fictitious company with the
+domain name mit.edu and the Kerberos realm ATHENA.MIT.EDU). She would
+type::
- shell% kinit
- Password for jennifer@ATHENA.MIT.EDU: <-- [Type jennifer's password here.]
- shell%
+ shell% kinit
+ Password for jennifer@ATHENA.MIT.EDU: <-- [Type jennifer's password here.]
+ shell%
-If you type your password incorrectly, *kinit* will give you the following error message::
+If you type your password incorrectly, kinit will give you the
+following error message::
- shell% kinit
- Password for jennifer@ATHENA.MIT.EDU: <-- [Type the wrong password here.]
- kinit: Password incorrect
- shell%
+ shell% kinit
+ Password for jennifer@ATHENA.MIT.EDU: <-- [Type the wrong password here.]
+ kinit: Password incorrect
+ shell%
and you won't get Kerberos tickets.
-Notice that *kinit* assumes you want tickets for your own username in your default realm. Suppose Jennifer's friend David is visiting, and he wants to borrow a window to check his mail. David needs to get tickets for himself in his own realm, EXAMPLE.COM [1]_. He would type::
+Notice that kinit assumes you want tickets for your own username in
+your default realm. Suppose Jennifer's friend David is visiting, and
+he wants to borrow a window to check his mail. David needs to get
+tickets for himself in his own realm, EXAMPLE.COM [1]_. He would
+type::
- shell% kinit david@EXAMPLE.COM
- Password for david@EXAMPLE.COM: <-- [Type david's password here.]
- shell%
+ shell% kinit david@EXAMPLE.COM
+ Password for david@EXAMPLE.COM: <-- [Type david's password here.]
+ shell%
-David would then have tickets which he could use to log onto his own machine. Note that he typed his password locally on Jennifer's machine, but it never went over the network. Kerberos on the local host performed the authentication to the KDC in the other realm.
+David would then have tickets which he could use to log onto his own
+machine. Note that he typed his password locally on Jennifer's
+machine, but it never went over the network. Kerberos on the local
+host performed the authentication to the KDC in the other realm.
-If you want to be able to forward your tickets to another host, you need to request forwardable tickets. You do this by specifying the **-f** option::
+If you want to be able to forward your tickets to another host, you
+need to request forwardable tickets. You do this by specifying the
+**-f** option::
- shell% kinit -f
- Password for jennifer@ATHENA.MIT.EDU: <-- [Type your password here.]
- shell%
+ shell% kinit -f
+ Password for jennifer@ATHENA.MIT.EDU: <-- [Type your password here.]
+ shell%
-Note that *kinit* does not tell you that it obtained forwardable tickets; you can verify this using the *klist* command (see :ref:`vytwk_label`).
+Note that kinit does not tell you that it obtained forwardable
+tickets; you can verify this using the *klist* command (see
+:ref:`vytwk_label`).
-Normally, your tickets are good for your system's default ticket lifetime, which is ten hours on many systems. You can specify a different ticket lifetime with the **-l** option. Add the letter **s** to the value for seconds, **m** for minutes, **h** for hours, or **d** for days. For example, to obtain forwardable tickets for *david@EXAMPLE.COM* that would be good for *three hours*, you would type::
+Normally, your tickets are good for your system's default ticket
+lifetime, which is ten hours on many systems. You can specify a
+different ticket lifetime with the **-l** option. Add the letter
+**s** to the value for seconds, **m** for minutes, **h** for hours, or
+**d** for days. For example, to obtain forwardable tickets for
+``david@EXAMPLE.COM`` that would be good for three hours, you would
+type::
- shell% kinit -f -l 3h david@EXAMPLE.COM
- Password for david@EXAMPLE.COM: <-- [Type david's password here.]
- shell%
+ shell% kinit -f -l 3h david@EXAMPLE.COM
+ Password for david@EXAMPLE.COM: <-- [Type david's password here.]
+ shell%
-.. note::You cannot mix units; specifying a lifetime of 3h30m would result in an error. Note also that most systems specify a maximum ticket lifetime. If you request a longer ticket lifetime, it will be automatically truncated to the maximum lifetime.
+.. note:: You cannot mix units; specifying a lifetime of 3h30m would
+ result in an error. Note also that most systems specify a
+ maximum ticket lifetime. If you request a longer ticket
+ lifetime, it will be automatically truncated to the maximum
+ lifetime.
+.. [1] Note: the realm EXAMPLE.COM must be listed in your computer's
+ Kerberos configuration file, */etc/krb5.conf*.
-.. [1] Note: the realm EXAMPLE.COM must be listed in your computer's Kerberos configuration file, */etc/krb5.conf*.
-
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
Kerberos ticket properties
-===========================
+==========================
There are various properties that Kerberos tickets can have:
-If a ticket is **forwardable**, then the KDC can issue a new ticket with a different network address based on the forwardable ticket. This allows for authentication forwarding without requiring a password to be typed in again. For example, if a user with a forwardable TGT logs into a remote system, the KDC could issue a new TGT for that user with the netword address of the remote system, allowing authentication on that host to work as though the user were logged in locally.
-
-When the KDC creates a new ticket based on a forwardable ticket, it sets the **forwarded** flag on that new ticket. Any tickets that are created based on a ticket with the forwarded flag set will also have their forwarded flags set.
-
-A **proxiable** ticket is similar to a forwardable ticket in that it allows a service to take on the identity of the client. Unlike a forwardable ticket, however, a proxiable ticket is only issued for specific services. In other words, a ticket-granting ticket cannot be issued based on a ticket that is proxiable but not forwardable.
+If a ticket is **forwardable**, then the KDC can issue a new ticket
+with a different network address based on the forwardable ticket.
+This allows for authentication forwarding without requiring a password
+to be typed in again. For example, if a user with a forwardable TGT
+logs into a remote system, the KDC could issue a new TGT for that user
+with the netword address of the remote system, allowing authentication
+on that host to work as though the user were logged in locally.
+
+When the KDC creates a new ticket based on a forwardable ticket, it
+sets the **forwarded** flag on that new ticket. Any tickets that are
+created based on a ticket with the forwarded flag set will also have
+their forwarded flags set.
+
+A **proxiable** ticket is similar to a forwardable ticket in that it
+allows a service to take on the identity of the client. Unlike a
+forwardable ticket, however, a proxiable ticket is only issued for
+specific services. In other words, a ticket-granting ticket cannot be
+issued based on a ticket that is proxiable but not forwardable.
A **proxy** ticket is one that was issued based on a proxiable ticket.
-A **postdated** ticket is issued with the invalid flag set. After the starting time listed on the ticket, it can be presented to the KDC to obtain valid tickets.
-
-Tickets with the **postdateable** flag set can be used to issue postdated tickets.
-
-**Renewable** tickets can be used to obtain new session keys without the user entering their password again. A renewable ticket has two expiration times. The first is the time at which this particular ticket expires. The second is the latest possible expiration time for any ticket issued based on this renewable ticket.
-
-A ticket with the **initial flag** set was issued based on the authentication protocol, and not on a ticket-granting ticket. Clients that wish to ensure that the user's key has been recently presented for verification could specify that this flag must be set to accept the ticket.
-
-An **invalid** ticket must be rejected by application servers. Postdated tickets are usually issued with this flag set, and must be validated by the KDC before they can be used.
-
-A **preauthenticated** ticket is one that was only issued after the client requesting the ticket had authenticated itself to the KDC.
-
-The **hardware authentication** flag is set on a ticket which required the use of hardware for authentication. The hardware is expected to be possessed only by the client which requested the tickets.
-
-If a ticket has the **transit policy** checked flag set, then the KDC that issued this ticket implements the transited-realm check policy and checked the transited-realms list on the ticket. The transited-realms list contains a list of all intermediate realms between the realm of the KDC that issued the first ticket and that of the one that issued the current ticket. If this flag is not set, then the application server must check the transited realms itself or else reject the ticket.
-
-The okay as **delegate** flag indicates that the server specified in the ticket is suitable as a delegate as determined by the policy of that realm. A server that is acting as a delegate has been granted a proxy or a forwarded TGT. This flag is a new addition to the Kerberos V5 protocol and is not yet implemented on MIT servers.
-
-An **anonymous** ticket is one in which the named principal is a generic principal for that realm; it does not actually specify the individual that will be using the ticket. This ticket is meant only to securely distribute a session key. This is a new addition to the Kerberos V5 protocol and is not yet implemented on MIT servers.
-
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
-
-
+A **postdated** ticket is issued with the invalid flag set. After the
+starting time listed on the ticket, it can be presented to the KDC to
+obtain valid tickets.
+
+Tickets with the **postdateable** flag set can be used to issue
+postdated tickets.
+
+**Renewable** tickets can be used to obtain new session keys without
+the user entering their password again. A renewable ticket has two
+expiration times. The first is the time at which this particular
+ticket expires. The second is the latest possible expiration time for
+any ticket issued based on this renewable ticket.
+
+A ticket with the **initial flag** set was issued based on the
+authentication protocol, and not on a ticket-granting ticket. Clients
+that wish to ensure that the user's key has been recently presented
+for verification could specify that this flag must be set to accept
+the ticket.
+
+An **invalid** ticket must be rejected by application servers.
+Postdated tickets are usually issued with this flag set, and must be
+validated by the KDC before they can be used.
+
+A **preauthenticated** ticket is one that was only issued after the
+client requesting the ticket had authenticated itself to the KDC.
+
+The **hardware authentication** flag is set on a ticket which required
+the use of hardware for authentication. The hardware is expected to
+be possessed only by the client which requested the tickets.
+
+If a ticket has the **transit policy** checked flag set, then the KDC
+that issued this ticket implements the transited-realm check policy
+and checked the transited-realms list on the ticket. The
+transited-realms list contains a list of all intermediate realms
+between the realm of the KDC that issued the first ticket and that of
+the one that issued the current ticket. If this flag is not set, then
+the application server must check the transited realms itself or else
+reject the ticket.
+
+The okay as **delegate** flag indicates that the server specified in
+the ticket is suitable as a delegate as determined by the policy of
+that realm. A server that is acting as a delegate has been granted a
+proxy or a forwarded TGT. This flag is a new addition to the Kerberos
+V5 protocol and is not yet implemented on MIT servers.
+
+An **anonymous** ticket is one in which the named principal is a
+generic principal for that realm; it does not actually specify the
+individual that will be using the ticket. This ticket is meant only
+to securely distribute a session key. This is a new addition to the
+Kerberos V5 protocol and is not yet implemented on MIT servers.
+
+
+Feedback
+--------
+
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
.. _vytwk_label:
-Viewing tickets with *klist*
-================================
-
-
-The klist command shows your tickets. When you first obtain tickets, you will have only the ticket-granting ticket. The listing would look like this::
-
- shell% klist
- Ticket cache: /tmp/krb5cc_ttypa
- Default principal: jennifer@ATHENA.MIT.EDU
-
- Valid starting Expires Service principal
- 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
- shell%
-
-The ticket cache is the location of your ticket file. In the above example, this file is named */tmp/krb5cc_ttypa*. The default principal is your kerberos principal.
-
-The *valid starting* and *expires* fields describe the period of time during which the ticket is valid. The service principal describes each ticket. The ticket-granting ticket has the primary *krbtgt*, and the instance is the realm name.
-
-Now, if *jennifer* connected to the machine *daffodil.mit.edu*, and then typed *klist* again, she would have gotten the following result::
-
- shell% klist
- Ticket cache: /tmp/krb5cc_ttypa
- Default principal: jennifer@ATHENA.MIT.EDU
-
- Valid starting Expires Service principal
- 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
- 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU
- shell%
-
-Here's what happened: when *jennifer* used telnet to connect to the host *daffodil.mit.edu*, the telnet program presented her ticket-granting ticket to the KDC and requested a host ticket for the host *daffodil.mit.edu*. The KDC sent the host ticket, which telnet then presented to the host *daffodil.mit.edu*, and she was allowed to log in without typing her password.
-
-Suppose your Kerberos tickets allow you to log into a host in another domain, such as *trillium.example.com*, which is also in another Kerberos realm, *EXAMPLE.COM*. If you telnet to this host, you will receive a ticket-granting ticket for the realm *EXAMPLE.COM*, plus the new host ticket for *trillium.example.com*. *klist* will now show::
-
- shell% klist
- Ticket cache: /tmp/krb5cc_ttypa
- Default principal: jennifer@ATHENA.MIT.EDU
-
- Valid starting Expires Service principal
- 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
- 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU
- 06/07/04 20:24:18 06/08/04 05:49:19 krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
- 06/07/04 20:24:18 06/08/04 05:49:19 host/trillium.example.com@EXAMPLE.COM
- shell%
-
-You can use the **-f** option to view the flags that apply to your tickets. The flags are:
+Viewing tickets with klist
+==========================
+
+The klist command shows your tickets. When you first obtain tickets,
+you will have only the ticket-granting ticket. The listing would look
+like this::
+
+ shell% klist
+ Ticket cache: /tmp/krb5cc_ttypa
+ Default principal: jennifer@ATHENA.MIT.EDU
+
+ Valid starting Expires Service principal
+ 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ shell%
+
+The ticket cache is the location of your ticket file. In the above
+example, this file is named ``/tmp/krb5cc_ttypa``. The default
+principal is your Kerberos principal.
+
+The "valid starting" and "expires" fields describe the period of time
+during which the ticket is valid. The "service principal" describes
+each ticket. The ticket-granting ticket has the primary ``krbtgt``,
+and the instance is the realm name.
+
+Now, if ``jennifer`` connected to the machine ``daffodil.mit.edu``,
+and then typed "klist" again, she would have gotten the following
+result::
+
+ shell% klist
+ Ticket cache: /tmp/krb5cc_ttypa
+ Default principal: jennifer@ATHENA.MIT.EDU
+
+ Valid starting Expires Service principal
+ 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU
+ shell%
+
+Here's what happened: when ``jennifer`` used telnet to connect to the
+host ``daffodil.mit.edu``, the telnet program presented her
+ticket-granting ticket to the KDC and requested a host ticket for the
+host ``daffodil.mit.edu``. The KDC sent the host ticket, which telnet
+then presented to the host ``daffodil.mit.edu``, and she was allowed
+to log in without typing her password.
+
+Suppose your Kerberos tickets allow you to log into a host in another
+domain, such as ``trillium.example.com``, which is also in another
+Kerberos realm, ``EXAMPLE.COM``. If you telnet to this host, you will
+receive a ticket-granting ticket for the realm ``EXAMPLE.COM``, plus
+the new host ticket for ``trillium.example.com``. klist will now
+show::
+
+ shell% klist
+ Ticket cache: /tmp/krb5cc_ttypa
+ Default principal: jennifer@ATHENA.MIT.EDU
+
+ Valid starting Expires Service principal
+ 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU
+ 06/07/04 20:24:18 06/08/04 05:49:19 krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
+ 06/07/04 20:24:18 06/08/04 05:49:19 host/trillium.example.com@EXAMPLE.COM
+ shell%
+
+You can use the **-f** option to view the flags that apply to your
+tickets. The flags are:
===== =========================
F Forwardable
a anonymous
===== =========================
-Here is a sample listing. In this example, the user *jennifer* obtained her initial tickets (**I**), which are forwardable (**F**) and postdated (**d**) but not yet validated (**i**)::
-
- shell% klist -f
- Ticket cache: /tmp/krb5cc_320
- Default principal: jennifer@ATHENA.MIT.EDU
-
- Valid starting Expires Service principal
- 31/07/05 19:06:25 31/07/05 19:16:25 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
- Flags: FdiI
- shell%
+Here is a sample listing. In this example, the user *jennifer*
+obtained her initial tickets (**I**), which are forwardable (**F**)
+and postdated (**d**) but not yet validated (**i**)::
+ shell% klist -f
+ Ticket cache: /tmp/krb5cc_320
+ Default principal: jennifer@ATHENA.MIT.EDU
-In the following example, the user *david*'s tickets were forwarded (**f**) to this host from another host. The tickets are reforwardable (**F**)::
+ Valid starting Expires Service principal
+ 31/07/05 19:06:25 31/07/05 19:16:25 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ Flags: FdiI
+ shell%
- shell% klist -f
- Ticket cache: /tmp/krb5cc_p11795
- Default principal: david@EXAMPLE.COM
-
- Valid starting Expires Service principal
- 07/31/05 11:52:29 07/31/05 21:11:23 krbtgt/EXAMPLE.COM@EXAMPLE.COM
- Flags: Ff
- 07/31/05 12:03:48 07/31/05 21:11:23 host/trillium.example.com@EXAMPLE.COM
- Flags: Ff
- shell%
+In the following example, the user *david*'s tickets were forwarded
+(**f**) to this host from another host. The tickets are reforwardable
+(**F**)::
-------------------
+ shell% klist -f
+ Ticket cache: /tmp/krb5cc_p11795
+ Default principal: david@EXAMPLE.COM
-Feedback:
+ Valid starting Expires Service principal
+ 07/31/05 11:52:29 07/31/05 21:11:23 krbtgt/EXAMPLE.COM@EXAMPLE.COM
+ Flags: Ff
+ 07/31/05 12:03:48 07/31/05 21:11:23 host/trillium.example.com@EXAMPLE.COM
+ Flags: Ff
+ shell%
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_tkt_mgmt
ftp
-=============
+===
-The Kerberos V5 FTP program works exactly like the standard UNIX FTP program, with the following Kerberos features added:
+The Kerberos V5 FTP program works exactly like the standard UNIX FTP
+program, with the following Kerberos features added:
=========================== ===================================================================================================
-k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself.
protect *level* (issued at the ftp> prompt) sets the protection level. **clear** is no protection; **safe** ensures data integrity by verifying the checksum, and **private** encrypts the data. Encryption also ensures data integrity.
=========================== ===================================================================================================
-For example, suppose *jennifer* wants to get her RMAIL file from the directory *~jennifer/Mail*, on the host *daffodil.mit.edu*. She wants to encrypt the file transfer. The exchange would look like the following::
-
- shell% ftp daffodil.mit.edu
- Connected to daffodil.mit.edu.
- 220 daffodil.mit.edu FTP server (Version 5.60) ready.
- 334 Using authentication type GSSAPI; ADAT must follow
- GSSAPI accepted as authentication type
- GSSAPI authentication succeeded
- 200 Data channel protection level set to private.
- Name (daffodil.mit.edu:jennifer):
- 232 GSSAPI user jennifer@ATHENA.MIT.EDU is authorized as jennifer
- 230 User jennifer logged in.
- Remote system type is UNIX.
- Using binary mode to transfer files.
- ftp> protect private
- 200 Protection level set to Private.
- ftp> cd ~jennifer/MAIL
- 250 CWD command successful.
- ftp> get RMAIL
- 227 Entering Passive Mode (128,0,0,5,16,49)
- 150 Opening BINARY mode data connection for RMAIL (361662 bytes).
- 226 Transfer complete.
- 361662 bytes received in 2.5 seconds (1.4e+02 Kbytes/s)
- ftp> quit
- shell%
-
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
-
+For example, suppose ``jennifer`` wants to get her RMAIL file from the
+directory ``~jennifer/Mail``, on the host ``daffodil.mit.edu``. She
+wants to encrypt the file transfer. The exchange would look like the
+following::
+
+ shell% ftp daffodil.mit.edu
+ Connected to daffodil.mit.edu.
+ 220 daffodil.mit.edu FTP server (Version 5.60) ready.
+ 334 Using authentication type GSSAPI; ADAT must follow
+ GSSAPI accepted as authentication type
+ GSSAPI authentication succeeded
+ 200 Data channel protection level set to private.
+ Name (daffodil.mit.edu:jennifer):
+ 232 GSSAPI user jennifer@ATHENA.MIT.EDU is authorized as jennifer
+ 230 User jennifer logged in.
+ Remote system type is UNIX.
+ Using binary mode to transfer files.
+ ftp> protect private
+ 200 Protection level set to Private.
+ ftp> cd ~jennifer/MAIL
+ 250 CWD command successful.
+ ftp> get RMAIL
+ 227 Entering Passive Mode (128,0,0,5,16,49)
+ 150 Opening BINARY mode data connection for RMAIL (361662 bytes).
+ 226 Transfer complete.
+ 361662 bytes received in 2.5 seconds (1.4e+02 Kbytes/s)
+ ftp> quit
+ shell%
+
+
+Feedback
+--------
+
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_appl
Kerberized LINUX/UNIX applications
-====================================
-
-.. note:: This document was copied from **Kerberos V5 UNIX User's Guide**. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
-
-
-
-Kerberos V5 is a single-sign-on system. This means that you only have to type your password once, and the Kerberos V5 programs do the authenticating (and optionally encrypting) for you. The way this works is that Kerberos has been built into each of a suite of network programs. For example, when you use a Kerberos V5 program to connect to a remote host, the program, the KDC, and the remote host perform a set of rapid negotiations. When these negotiations are completed, your program has proven your identity on your behalf to the remote host, and the remote host has granted you access, all in the space of a few seconds.o
-
-The Kerberos V5 network programs are those programs that connect to another host somewhere on the internet. These programs include rlogin, telnet, ftp, rsh, rcp, and ksu. These programs have all of the original features of the corresponding non-Kerberos rlogin, telnet, ftp, rsh, rcp, and su programs, plus additional features that transparently use your Kerberos tickets for negotiating authentication and optional encryption with the remote host. In most cases, all you'll notice is that you no longer have to type your password, because Kerberos has already proven your identity.
-
-The Kerberos V5 network programs allow you the options of forwarding your tickets to the remote host (if you obtained forwardable tickets with the *kinit* program; see :ref:`otwk_labal`), and encrypting data transmitted between you and the remote host.
-
-The Kerberos V5 applications are versions of existing UNIX network programs with the Kerberos features added.
+==================================
+
+.. note:: This document was copied from **Kerberos V5 UNIX User's
+ Guide**. Currently it is under review. Please, send your
+ feedback, corrections and additions to krb5-bugs@mit.edu.
+ Your contribution is greatly appreciated.
+
+Kerberos V5 is a single-sign-on system. This means that you only have
+to type your password once, and the Kerberos V5 programs do the
+authenticating (and optionally encrypting) for you. The way this
+works is that Kerberos has been built into each of a suite of network
+programs. For example, when you use a Kerberos V5 program to connect
+to a remote host, the program, the KDC, and the remote host perform a
+set of rapid negotiations. When these negotiations are completed,
+your program has proven your identity on your behalf to the remote
+host, and the remote host has granted you access, all in the space of
+a few seconds.
+
+The Kerberos V5 network programs are those programs that connect to
+another host somewhere on the internet. These programs include
+rlogin, telnet, ftp, rsh, rcp, and ksu. These programs have all of
+the original features of the corresponding non-Kerberos rlogin,
+telnet, ftp, rsh, rcp, and su programs, plus additional features that
+transparently use your Kerberos tickets for negotiating authentication
+and optional encryption with the remote host. In most cases, all
+you'll notice is that you no longer have to type your password,
+because Kerberos has already proven your identity.
+
+The Kerberos V5 network programs allow you the options of forwarding
+your tickets to the remote host (if you obtained forwardable tickets
+with the kinit program; see :ref:`otwk_labal`), and encrypting data
+transmitted between you and the remote host.
+
+The Kerberos V5 applications are versions of existing UNIX network
+programs with the Kerberos features added.
.. toctree::
:maxdepth: 1
ssh.rst
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
-
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_appl
ksu
-=============
-
-The Kerberos V5 *ksu* program replaces the standard UNIX *su* program (See ksu_vs_su_).
-*ksu* first authenticates you to Kerberos.
-Depending on the configuration of your system, *ksu* may ask for your Kerberos password if authentication fails.
-Note that you should never type your password if you are remotely logged in using an unencrypted connection.
-
-Once *ksu* has authenticated you, if your Kerberos principal appears in the target's *.k5login* file
-(see Granting Access to Your Account) or in the target's *.k5users* file (see below),
-it switches your user ID to the target user ID.
-
-For example, *david* has put *jennifer*'s Kerberos principal in his *.k5login* file.
-If *jennifer* uses *ksu* to become *david*, the exchange would look like this.
-(To differentiate between the two shells, *jennifer*'s prompt is represented as
-*jennifer* and *david*'s prompt is represented as *david*.)::
-
- jennifer% ksu david
- Account david: authorization for jennifer@ATHENA.MIT.EDU successful
- Changing uid to david (3382)
- david%
-
-Note that the new shell has a copy of *jennifer*'s tickets.
-The ticket filename contains *david*'s UID with .1 appended to it::
-
- david% klist
- Ticket cache: /tmp/krb5cc_3382.1
- Default principal: jennifer@ATHENA.MIT.EDU
-
- Valid starting Expires Service principal
- 07/31/04 21:53:01 08/01/04 07:52:53 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
- 07/31/04 21:53:39 08/01/04 07:52:53 host/daffodil.mit.edu@ATHENA.MIT.EDU
- david%
-
-If *jennifer* had not appeared in *david*'s *.k5login* file (and the system was configured to ask for a password),
-the exchange would have looked like this
-(assuming *david* has taken appropriate precautions in protecting his password)::
-
- jennifer% ksu david
- WARNING: Your password may be exposed if you enter it here and are logged in remotely using an unsecure (non-encrypted) channel.
- Kerberos password for david@ATHENA.MIT.EDU: <- jennifer types the wrong password here.
- ksu: Password incorrect
- Authentication failed.
- jennifer%
-
-Now, suppose *david* did not want to give *jennifer* full access to his account,
-but wanted to give her permission to list his files and use the "more" command to view them.
-He could create a *.k5users* file giving her permission to run only those specific commands.
-
-The *.k5users* file is like the *.k5login* file, except that each principal is optionally followed by a list of commands.
-*ksu* will let those principals execute only the commands listed, using the -e option.
-*david*'s *.k5users* file might look like the following::
-
- jennifer@ATHENA.MIT.EDU /bin/ls /usr/bin/more
- joeadmin@ATHENA.MIT.EDU /bin/ls
- joeadmin/admin@ATHENA.MIT.EDU *
- david@EXAMPLE.COM
-
-The above *.k5users* file would let *jennifer* run only the commands /bin/ls and /usr/bin/more.
-It would let *joeadmin* run only the command /bin/ls if he had regular tickets,
-but if he had tickets for his admin instance, joeadmin/admini\@ATHENA.MIT.EDU,
-he would be able to execute any command.
-The last line gives *david* in the realm EXAMPLE.COM permission to execute any command.
-(I.e., having only a Kerberos principal on a line is equivalent to giving
-that principal permission to execute \*.)
-This is so that *david* can allow himself to execute commands when he logs in,
-using Kerberos, from a machine in the realm EXAMPLE.COM.
-
-Then, when *jennifer* wanted to list his home directory, she would type::
-
- jennifer% ksu david -e ls ~david
- Authenticated jennifer@ATHENA.MIT.EDU
- Account david: authorization for jennifer@ATHENA.MIT.EDU for execution of /bin/ls successful
- Changing uid to david (3382)
- Mail News Personal misc bin
- jennifer%
-
-If *jennifer* had tried to give a different command to *ksu*,
-it would have prompted for a password as with the previous example.
-
-Note that unless the *.k5users* file gives the target permission to run any command,
-the user must use *ksu* with the -e command option.
-
-The *ksu* options you are most likely to use are:
+===
+
+The Kerberos V5 ksu program replaces the standard UNIX su program (See
+ksu_vs_su_). ksu first authenticates you to Kerberos. Depending on
+the configuration of your system, ksu may ask for your Kerberos
+password if authentication fails. Note that you should never type
+your password if you are remotely logged in using an unencrypted
+connection.
+
+Once ksu has authenticated you, if your Kerberos principal appears in
+the target's .k5login file (see Granting Access to Your Account) or in
+the target's .k5users file (see below), it switches your user ID to
+the target user ID.
+
+For example, ``david`` has put ``jennifer``'s Kerberos principal in
+his .k5login file. If ``jennifer`` uses ksu to become ``david``, the
+exchange would look like this. (To differentiate between the two
+shells, ``jennifer``'s prompt is represented as ``jennifer`` and
+``david``'s prompt is represented as ``david``.)::
+
+ jennifer% ksu david
+ Account david: authorization for jennifer@ATHENA.MIT.EDU successful
+ Changing uid to david (3382)
+ david%
+
+Note that the new shell has a copy of ``jennifer``'s tickets. The
+ticket filename contains ``david``'s UID with .1 appended to it::
+
+ david% klist
+ Ticket cache: /tmp/krb5cc_3382.1
+ Default principal: jennifer@ATHENA.MIT.EDU
+
+ Valid starting Expires Service principal
+ 07/31/04 21:53:01 08/01/04 07:52:53 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
+ 07/31/04 21:53:39 08/01/04 07:52:53 host/daffodil.mit.edu@ATHENA.MIT.EDU
+ david%
+
+If ``jennifer`` had not appeared in ``david``'s .k5login file (and the
+system was configured to ask for a password), the exchange would have
+looked like this (assuming ``david`` has taken appropriate precautions
+in protecting his password)::
+
+ jennifer% ksu david
+ WARNING: Your password may be exposed if you enter it here and are logged in remotely using an unsecure (non-encrypted) channel.
+ Kerberos password for david@ATHENA.MIT.EDU: <- jennifer types the wrong password here.
+ ksu: Password incorrect
+ Authentication failed.
+ jennifer%
+
+Now, suppose ``david`` did not want to give ``jennifer`` full access
+to his account, but wanted to give her permission to list his files
+and use the "more" command to view them. He could create a .k5users
+file giving her permission to run only those specific commands.
+
+The .k5users file is like the .k5login file, except that each
+principal is optionally followed by a list of commands. ksu will let
+those principals execute only the commands listed, using the -e
+option. ``david``'s .k5users file might look like the following::
+
+ jennifer@ATHENA.MIT.EDU /bin/ls /usr/bin/more
+ joeadmin@ATHENA.MIT.EDU /bin/ls
+ joeadmin/admin@ATHENA.MIT.EDU *
+ david@EXAMPLE.COM
+
+The above .k5users file would let ``jennifer`` run only the commands
+``/bin/ls`` and ``/usr/bin/more``. It would let ``joeadmin`` run only
+the command ``/bin/ls`` if he had regular tickets, but if he had
+tickets for his admin instance, ``joeadmin/admini@ATHENA.MIT.EDU``, he
+would be able to execute any command. The last line gives ``david``
+in the realm ``EXAMPLE.COM`` permission to execute any command.
+(I.e., having only a Kerberos principal on a line is equivalent to
+giving that principal permission to execute ``*``.) This is so that
+``david`` can allow himself to execute commands when he logs in, using
+Kerberos, from a machine in the realm EXAMPLE.COM.
+
+Then, when ``jennifer`` wanted to list his home directory, she would type::
+
+ jennifer% ksu david -e ls ~david
+ Authenticated jennifer@ATHENA.MIT.EDU
+ Account david: authorization for jennifer@ATHENA.MIT.EDU for execution of /bin/ls successful
+ Changing uid to david (3382)
+ Mail News Personal misc bin
+ jennifer%
+
+If ``jennifer`` had tried to give a different command to ksu, it would
+have prompted for a password as with the previous example.
+
+Note that unless the .k5users file gives the target permission to run
+any command, the user must use ksu with the -e command option.
+
+The ksu options you are most likely to use are:
=================== ====================================
--n *principal* specifies which Kerberos principal you want to use for *ksu*.
+-n *principal* specifies which Kerberos principal you want to use for ksu.
(e.g., the user *joeadmin* might want to use his admin instance.)
-c specifies the location of your Kerberos credentials cache (ticket file).
--k tells *ksu* not to destroy your Kerberos tickets when *ksu* is finished.
--f requests forwardable tickets. (See :ref:`otwk_labal`.)
- This is only applicable if *ksu* needs to obtain tickets.
+-k tells ksu not to destroy your Kerberos tickets when ksu is finished.
+-f requests forwardable tickets. (See :ref:`otwk_labal`.)
+ This is only applicable if ksu needs to obtain tickets.
-l *lifetime* sets the ticket lifetime. (See :ref:`otwk_labal`.) i
- This is only applicable if *ksu* needs to obtain tickets.
--z tells *ksu* to copy your Kerberos tickets only if the UID you are switching
- is the same as the Kerberos primary
+ This is only applicable if ksu needs to obtain tickets.
+-z tells ksu to copy your Kerberos tickets only if the UID you are switching
+ is the same as the Kerberos primary
(either yours or the one specified by the **-n** option).
--Z tells *ksu* not to copy any Kerberos tickets to the new UID.
--e *command* tells *ksu* to execute command and then exit.
- See the description of the *.k5users* file above.
--a *text* (at the end of the command line) tells *ksu* to pass everything
+-Z tells ksu not to copy any Kerberos tickets to the new UID.
+-e *command* tells ksu to execute command and then exit.
+ See the description of the .k5users file above.
+-a *text* (at the end of the command line) tells ksu to pass everything
after **-a** to the target shell.
=================== ====================================
.. _ksu_vs_su:
-*ksu* vs *su*
------------------------
+ksu vs su
+---------
-From from the discussion at [http://mailman.mit.edu/pipermail/kerberos/2011-January/016886.html]:
+From from the discussion at
+[http://mailman.mit.edu/pipermail/kerberos/2011-January/016886.html]:
-The main reason why we use *ksu* instead of *su* is because every person who
-can *su* to root has their own separate */root* principal with a separate
-password and we want them to use those passwords instead. In many cases,
-the set of people who know the actual root password is more limited than
-the people who can *ksu* (perhaps because the formula for it is shared with
-other systems those people should not be root on, for instance).
+The main reason why we use ksu instead of su is because every person
+who can su to root has their own separate ``/root`` principal with a
+separate password and we want them to use those passwords instead. In
+many cases, the set of people who know the actual root password is
+more limited than the people who can ksu (perhaps because the formula
+for it is shared with other systems those people should not be root
+on, for instance).
-You can do this with *su* and an appropriate PAM configuration, or with *sudo*
-and an appropriate PAM configuration, but it's fiddly and annoying and
-it's often easier to just use *ksu*. Plus, you'd probably have to use my
-pam-krb5 module rather than whatever came with your system, since it would
-be extremely difficult to set this up without the aid of the *alt_auth_map*
-configuration option.
+You can do this with su and an appropriate PAM configuration, or with
+sudo and an appropriate PAM configuration, but it's fiddly and
+annoying and it's often easier to just use ksu. Plus, you'd probably
+have to use my pam-krb5 module rather than whatever came with your
+system, since it would be extremely difficult to set this up without
+the aid of the **alt_auth_map** configuration option.
Don't need to leak my root password to client users
-Client users shall use *ksu* under local machine, not remote machines:
+Client users shall use ksu under local machine, not remote machines:
Ideally in Kerberos you never enter your password into any remote
system, but always authenticate locally and then use Kerberos to
authenticate to remote systems. We're moving in that way (by allowing
-root logins only via *GSSAPI*), but the tradeoff is that you have to allow
-remote direct root logins, which makes some a bit uncomfortable.
+root logins only via GSSAPI), but the tradeoff is that you have to
+allow remote direct root logins, which makes some a bit uncomfortable.
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_appl
rcp
-=============
+===
-The Kerberos V5 *rcp* program works exactly like the standard UNIX *rcp* program, with the following Kerberos features added:
+The Kerberos V5 rcp program works exactly like the standard UNIX rcp
+program, with the following Kerberos features added:
============= ================
-k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself.
-x turns on encryption.
============= ================
-For example, if you wanted to copy the file */etc/motd* from the host *daffodil.mit.edu* into the current directory, via an encrypted connection, you would simply type::
+For example, if you wanted to copy the file ``/etc/motd`` from the
+host ``daffodil.mit.edu`` into the current directory, via an encrypted
+connection, you would simply type::
- shell% rcp -x daffodil.mit.edu:/etc/motd .
+ shell% rcp -x daffodil.mit.edu:/etc/motd .
-The *rcp* program negotiates authentication and encryption transparently.
+The rcp program negotiates authentication and encryption transparently.
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_appl
rlogin
-=================
+======
-The Kerberos V5 *rlogin* command works exactly like the standard UNIX *rlogin* program, with the following Kerberos options added:
+The Kerberos V5 *rlogin* command works exactly like the standard UNIX
+*rlogin* program, with the following Kerberos options added:
============= ================================================================================================================
-f forwards a copy of your tickets to the remote host.
-x encrypts the input and output data streams (the username is sent unencrypted)
============= ================================================================================================================
-For example, if *david* wanted to use the standard UNIX *rlogin* to connect to the machine daffodil.example.com, he would type::
+For example, if ``david`` wanted to use the standard UNIX ``rlogin``
+to connect to the machine daffodil.example.com, he would type::
- shell% rlogin daffodil.example.com -l david
- Password: <- david types his password here
- Last login: Fri Jun 21 10:36:32 from :0.0
- Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
- The Regents of the University of California. All rights reserved.
-
- NetBSD 1.1: Tue May 21 00:31:42 EDT 1996
-
- Welcome to NetBSD!
- shell%
+ shell% rlogin daffodil.example.com -l david
+ Password: <- david types his password here
+ Last login: Fri Jun 21 10:36:32 from :0.0
+ Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
+ The Regents of the University of California. All rights reserved.
-Note that the machine daffodil.example.com asked for *david*'s password. When he typed it, his password was sent over the network unencrypted. If an intruder were watching network traffic at the time, that intruder would know *david*'s password.
+ NetBSD 1.1: Tue May 21 00:31:42 EDT 1996
-If, on the other hand, *jennifer* wanted to use Kerberos V5 *rlogin* to connect to the machine *trillium.mit.edu*, she could forward a copy of her tickets, mark them as not forwardable from the remote host, and request an encrypted session as follows::
+ Welcome to NetBSD!
+ shell%
- shell% rlogin trillium.mit.edu -f -x
- This rlogin session is using DES encryption for all data transmissions.
- Last login: Thu Jun 20 16:20:50 from daffodil
- Athena Server (sun4) Version 9.1.11 Tue Jul 30 14:40:08 EDT 2002
- shell%
+Note that the machine ``daffodil.example.com`` asked for *david*'s
+password. When he typed it, his password was sent over the network
+unencrypted. If an intruder were watching network traffic at the
+time, that intruder would know ``david``'s password.
-Note that *jennifer*'s machine used Kerberos to authenticate her to *trillium.mit.edu*, and logged her in automatically as herself. She had an encrypted session, a copy of her tickets were waiting for her, and she never typed her password.
+If, on the other hand, ``jennifer`` wanted to use Kerberos V5 rlogin
+to connect to the machine ``trillium.mit.edu``, she could forward a
+copy of her tickets, mark them as not forwardable from the remote
+host, and request an encrypted session as follows::
-If you forwarded your Kerberos tickets, *rlogin* automatically destroys them when it exits.
+ shell% rlogin trillium.mit.edu -f -x
+ This rlogin session is using DES encryption for all data transmissions.
+ Last login: Thu Jun 20 16:20:50 from daffodil
+ Athena Server (sun4) Version 9.1.11 Tue Jul 30 14:40:08 EDT 2002
+ shell%
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+Note that ``jennifer``'s machine used Kerberos to authenticate her to
+``trillium.mit.edu``, and logged her in automatically as herself. She
+had an encrypted session, a copy of her tickets were waiting for her,
+and she never typed her password.
+If you forwarded your Kerberos tickets, rlogin automatically destroys
+them when it exits.
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_appl
rsh
-================
-The Kerberos V5 rsh program works exactly like the standard UNIX rlogin program, with the following Kerberos features added:
+===
+
+The Kerberos V5 rsh program works exactly like the standard UNIX
+rlogin program, with the following Kerberos features added:
========== ======================
-f forwards a copy of your tickets to the remote host.
-x encrypts the input and output data streams (the command line is not encrypted)
========== ======================
-For example, if your Kerberos tickets allowed you to run programs on the host *trillium@example.com* as root, you could run the date program as follows::
-
- shell% rsh trillium.example.com -l root -x date
- This rsh session is using DES encryption for all data transmissions.
- Tue Jul 30 19:34:21 EDT 2002
- shell%
-
-If you forwarded your Kerberos tickets, *rsh* automatically destroys them when it exits.
+For example, if your Kerberos tickets allowed you to run programs on
+the host ``trillium@example.com`` as root, you could run the date
+program as follows::
-------------------
+ shell% rsh trillium.example.com -l root -x date
+ This rsh session is using DES encryption for all data transmissions.
+ Tue Jul 30 19:34:21 EDT 2002
+ shell%
-Feedback:
+If you forwarded your Kerberos tickets, rsh automatically destroys
+them when it exits.
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_appl
ssh
-=======================
-
+===
TODO
#. Cross realm and *ssh*
-#.
+#.
.. seealso:: man pages ssh_config and sshd_config
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_appl
telnet
-=================
+======
-The Kerberos V5 telnet command works exactly like the standard UNIX telnet program, with the following Kerberos options added:
+The Kerberos V5 telnet command works exactly like the standard UNIX
+telnet program, with the following Kerberos options added:
============== ==========================================================================================================================
-f forwards a copy of your tickets to the remote host.
-x turns on encryption.
============== ==========================================================================================================================
-For example, if david wanted to use the standard UNIX telnet to connect to the machine daffodil.mit.edu, he would type::
+For example, if david wanted to use the standard UNIX telnet to
+connect to the machine daffodil.mit.edu, he would type::
- shell% telnet daffodil.example.com
- Trying 128.0.0.5 ...
- Connected to daffodil.example.com.
- Escape character is '^]'.
-
- NetBSD/i386 (daffodil) (ttyp3)
-
- login: david
- Password: <- david types his password here
- Last login: Fri Jun 21 17:13:11 from trillium.mit.edu
- Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
- The Regents of the University of California. All rights reserved.
-
- NetBSD 1.1: Tue May 21 00:31:42 EDT 1996
-
- Welcome to NetBSD!
- shell%
+ shell% telnet daffodil.example.com
+ Trying 128.0.0.5 ...
+ Connected to daffodil.example.com.
+ Escape character is '^]'.
-Note that the machine *daffodil.example.com* asked for *david*'s password. When he typed it, his password was sent over the network unencrypted. If an intruder were watching network traffic at the time, that intruder would know david's password.
+ NetBSD/i386 (daffodil) (ttyp3)
-If, on the other hand, *jennifer* wanted to use the Kerberos V5 telnet to connect to the machine *trillium.mit.edu*, she could forward a copy of her tickets, request an encrypted session, and log on as herself as follows::
+ login: david
+ Password: <- david types his password here
+ Last login: Fri Jun 21 17:13:11 from trillium.mit.edu
+ Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
+ The Regents of the University of California. All rights reserved.
- shell% telnet -a -f -x trillium.mit.edu
- Trying 128.0.0.5...
- Connected to trillium.mit.edu.
- Escape character is '^]'.
- [ Kerberos V5 accepts you as ``jennifer@mit.edu'' ]
- [ Kerberos V5 accepted forwarded credentials ]
- What you type is protected by encryption.
- Last login: Tue Jul 30 18:47:44 from daffodil.example.com
- Athena Server (sun4) Version 9.1.11 Tue Jul 30 14:40:08 EDT 2002
-
- shell%
+ NetBSD 1.1: Tue May 21 00:31:42 EDT 1996
-Note that *jennifer*'s machine used Kerberos to authenticate her to *trillium.mit.edu*, and logged her in automatically as herself. She had an encrypted session, a copy of her tickets already waiting for her, and she never typed her password.
+ Welcome to NetBSD!
+ shell%
-If you forwarded your Kerberos tickets, *telnet* automatically destroys them when it exits.
+Note that the machine ``daffodil.example.com`` asked for *david*'s
+password. When he typed it, his password was sent over the network
+unencrypted. If an intruder were watching network traffic at the
+time, that intruder would know david's password.
-------------------
+If, on the other hand, ``jennifer`` wanted to use the Kerberos V5
+telnet to connect to the machine ``trillium.mit.edu``, she could
+forward a copy of her tickets, request an encrypted session, and log
+on as herself as follows::
-Feedback:
+ shell% telnet -a -f -x trillium.mit.edu
+ Trying 128.0.0.5...
+ Connected to trillium.mit.edu.
+ Escape character is '^]'.
+ [ Kerberos V5 accepts you as ``jennifer@mit.edu'' ]
+ [ Kerberos V5 accepted forwarded credentials ]
+ What you type is protected by encryption.
+ Last login: Tue Jul 30 18:47:44 from daffodil.example.com
+ Athena Server (sun4) Version 9.1.11 Tue Jul 30 14:40:08 EDT 2002
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___users_appl
+ shell%
+Note that ``jennifer``'s machine used Kerberos to authenticate her to
+``trillium.mit.edu``, and logged her in automatically as herself. She
+had an encrypted session, a copy of her tickets already waiting for
+her, and she never typed her password.
+If you forwarded your Kerberos tickets, telnet automatically destroys
+them when it exits.
+
+
+Feedback
+--------
+
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___users_appl
.. _user_commands:
User commands
-====================================
-
-.. note:: This document was copied from Kerberos man pages. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
+=============
+.. note:: This document was copied from Kerberos man pages. Currently
+ it is under review. Please, send your feedback, corrections
+ and additions to krb5-bugs@mit.edu. Your contribution is
+ greatly appreciated.
.. toctree::
:maxdepth: 1
send-pr.rst
-------------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___user_commands
-
+Feedback
+--------
+Please, provide your feedback at
+krb5-bugs@mit.edu?subject=Documentation___user_commands
SYNOPSIS
--------
+
**~/.k5identity**
DESCRIPTION
--------------
+-----------
-The *.k5identity* file, which resides in a user's home directory,
+The .k5identity file, which resides in a user's home directory,
contains a list of rules for selecting a client principals based on
-the server being accessed. These rules are used to choose a credential
-cache within the cache collection when possible.
+the server being accessed. These rules are used to choose a
+credential cache within the cache collection when possible.
-Blank lines and lines beginning with '#' are ignored. Each line has the form:
+Blank lines and lines beginning with ``#`` are ignored. Each line has
+the form:
- principal field=value ...
+ *principal* *field*\=\ *value* ...
-If the server principal meets all of the field constraints, then principal
-is chosen as the client principal. The following fields are recognized:
+If the server principal meets all of the field constraints, then
+principal is chosen as the client principal. The following fields are
+recognized:
-**realm**
- If the realm of the server principal is known, it is matched
- against *value*, which may be a pattern using shell wildcards.
- For host-based server principals, the realm will generally only
- be known if there is a :ref:`domain_realm` section
- in :ref:`krb5.conf` with a mapping for the hostname.
+**realm**
+ If the realm of the server principal is known, it is matched
+ against *value*, which may be a pattern using shell wildcards.
+ For host-based server principals, the realm will generally only be
+ known if there is a :ref:`domain_realm` section in
+ :ref:`krb5.conf` with a mapping for the hostname.
**service**
- If the server principal is a host-based principal,
- its service component is matched against *value*, which may be
- a pattern using shell wildcards.
+ If the server principal is a host-based principal, its service
+ component is matched against *value*, which may be a pattern using
+ shell wildcards.
-**host**
- If the server principal is a host-based principal,
- its hostname component is converted to lower case and matched
- against *value*, which may be a pattern using shell wildcards.
+**host**
+ If the server principal is a host-based principal, its hostname
+ component is converted to lower case and matched against *value*,
+ which may be a pattern using shell wildcards.
+
+ If the server principal matches the constraints of multiple lines
+ in the .k5identity file, the principal from the first matching
+ line is used. If no line matches, credentials will be selected
+ some other way, such as the realm heuristic or the current primary
+ cache.
- If the server principal matches the constraints of multiple lines
- in the .k5identity file, the principal from the first matching line is used.
- If no line matches, credentials will be selected some other way,
- such as the realm heuristic or the current primary cache.
EXAMPLE
------------
+-------
The following example .k5identity file selects the client principal
-alice\@KRBTEST.COM if the server principal is within that realm,
-the principal alice/root\@EXAMPLE.COM if the server host is within
-a servers subdomain, and the principal alice/mail\@EXAMPLE.COM
-when accessing the IMAP service on mail.example.com::
+``alice@KRBTEST.COM`` if the server principal is within that realm,
+the principal ``alice/root@EXAMPLE.COM`` if the server host is within
+a servers subdomain, and the principal ``alice/mail@EXAMPLE.COM`` when
+accessing the IMAP service on ``mail.example.com``::
+
+ alice@KRBTEST.COM realm=KRBTEST.COM
+ alice/root@EXAMPLE.COM host=*.servers.example.com
+ alice/mail@EXAMPLE.COM host=mail.example.com service=imap
- alice@KRBTEST.COM realm=KRBTEST.COM
- alice/root@EXAMPLE.COM host=*.servers.example.com
- alice/mail@EXAMPLE.COM host=mail.example.com service=imap
SEE ALSO
-----------
+--------
kerberos(1), krb5.conf(5)
-
-
--------
**~/.k5login**
+
DESCRIPTION
---------------
+-----------
+
+The .k5login file, which resides in a user's home directory, contains
+a list of the Kerberos principals. Anyone with valid tickets for a
+principal in the file is allowed host access with the UID of the user
+in whose home directory the file resides. One common use is to place
+a .k5login file in root's home directory, thereby granting system
+administrators remote root access to the host via Kerberos.
-The *.k5login* file, which resides in a user's home directory,
-contains a list of the Kerberos principals.
-Anyone with valid tickets for a principal in the file is allowed host access
-with the UID of the user in whose home directory the file resides.
-One common use is to place a *.k5login* file in root's home directory,
-thereby granting system administrators remote root access to the host via Kerberos.
EXAMPLES
------------
+--------
-Suppose the user *alice* had a *.k5login* file in her home directory containing the following line:
+Suppose the user ``alice`` had a .k5login file in her home directory
+containing the following line::
- bob\@FOOBAR.ORG
+ bob@FOOBAR.ORG
-This would allow *bob* to use any of the Kerberos network applications,
-such as telnet(1), rlogin(1), rsh(1), and rcp(1),
-to access *alice*'s account, using *bob*'s Kerberos tickets.
+This would allow ``bob`` to use any of the Kerberos network
+applications, such as telnet(1), rlogin(1), rsh(1), and rcp(1), to
+access ``alice``'s account, using ``bob``'s Kerberos tickets.
-Let us further suppose that *alice* is a system administrator.
+Let us further suppose that ``alice`` is a system administrator.
Alice and the other system administrators would have their principals
-in root's *.k5login* file on each host:
+in root's .k5login file on each host::
- alice\@BLEEP.COM
+ alice@BLEEP.COM
- joeadmin/root\@BLEEP.COM
+ joeadmin/root@BLEEP.COM
+
+This would allow either system administrator to log in to these hosts
+using their Kerberos tickets instead of having to type the root
+password. Note that because ``bob`` retains the Kerberos tickets for
+his own principal, ``bob@FOOBAR.ORG``, he would not have any of the
+privileges that require ``alice``'s tickets, such as root access to
+any of the site's hosts, or the ability to change ``alice``'s
+password.
-This would allow either system administrator to log in to these hosts
-using their Kerberos tickets instead of having to type the root password.
-Note that because *bob* retains the Kerberos tickets for his own principal,
-"bob\@FOOBAR.ORG", he would not have any of the privileges that require *alice*'s tickets,
-such as root access to any of the site's hosts,
-or the ability to change *alice*'s password.
SEE ALSO
------------
+--------
telnet(1), rlogin(1), rsh(1), rcp(1), ksu(1), telnetd(8), klogind(8)
-
kdestroy - destroy Kerberos tickets
-=======================================
+===================================
SYNOPSIS
-~~~~~~~~~~~~~
+--------
-*kdestroy*
- [**-A**]
- [**-q**]
- [**-c** *cache_name*]
+**kdestroy**
+[**-A**]
+[**-q**]
+[**-c** *cache_name*]
DESCRIPTION
-~~~~~~~~~~~~~
+-----------
-The *kdestroy* utility destroys the user's active Kerberos
+The kdestroy utility destroys the user's active Kerberos
authorization tickets by writing zeros to the specified
credentials cache that contains them. If the credentials
cache is not specified, the default credentials cache is destroyed.
OPTIONS
-~~~~~~~~~~~~~
+-------
- **-A**
- Destroys all caches in the collection, if a cache collection is
- available.
+**-A**
+ Destroys all caches in the collection, if a cache collection is
+ available.
- **-q**
- Run quietly. Normally *kdestroy* beeps if it fails to destroy the user's tickets.
- The *-q* flag suppresses this behavior.
+**-q**
+ Run quietly. Normally kdestroy beeps if it fails to destroy the
+ user's tickets. The **-q** flag suppresses this behavior.
- **-c** *cache_name*
- Use *cache_name* as the credentials (ticket) cache name and location;
- if this option is not used, the default cache name and location are used.
+**-c** *cache_name*
+ Use *cache_name* as the credentials (ticket) cache name and
+ location; if this option is not used, the default cache name and
+ location are used.
- The default credentials cache may vary between systems.
- If the **KRB5CCNAME** environment variable is set, its
- value is used to name the default ticket cache.
+ The default credentials cache may vary between systems. If the
+ **KRB5CCNAME** environment variable is set, its value is used to
+ name the default ticket cache.
NOTE
-~~~~~
+----
-Most installations recommend that you place the *kdestroy* command in your *.logout* file,
-so that your tickets are destroyed automatically when you log out.
+Most installations recommend that you place the kdestroy command in
+your .logout file, so that your tickets are destroyed automatically
+when you log out.
ENVIRONMENT
-~~~~~~~~~~~~~
+-----------
-*kdestroy* uses the following environment variable:
+kdestroy uses the following environment variable:
- **KRB5CCNAME**
- Location of the default Kerberos 5 credentials (ticket)
- cache, in the form *type*:*residual*. If no type prefix is
- present, the **FILE** type is assumed. The type of the
- default cache may determine the availability of a cache
- collection; for instance, a default cache of type **DIR**
- causes caches within the directory to be present in the
- collection.
+**KRB5CCNAME**
+ Location of the default Kerberos 5 credentials (ticket) cache, in
+ the form *type*:*residual*. If no type prefix is present, the
+ **FILE** type is assumed. The type of the default cache may
+ determine the availability of a cache collection; for instance, a
+ default cache of type **DIR** causes caches within the directory
+ to be present in the collection.
FILES
-~~~~~~~~~~~~~
+-----
-/tmp/krb5cc_[uid] - Default location of Kerberos 5 credentials cache ([*uid*] is the decimal UID of the user).
+``/tmp/krb5cc_[uid]``
+ Default location of Kerberos 5 credentials cache ([*uid*] is the
+ decimal UID of the user).
SEE ALSO
-~~~~~~~~~
+--------
kinit(1), klist(1)
BUGS
-~~~~~
-
-Only the tickets in the specified credentials cache are destroyed.
-Separate ticket caches are used to hold root instance and password changing tickets.
-These should probably be destroyed too, or all of a user's tickets kept in a single credentials cache.
+----
+Only the tickets in the specified credentials cache are destroyed.
+Separate ticket caches are used to hold root instance and password
+changing tickets. These should probably be destroyed too, or all of a
+user's tickets kept in a single credentials cache.
.. _kinit(1):
kinit - obtain and cache Kerberos ticket-granting ticket
-=========================================================
+========================================================
SYNOPSIS
-~~~~~~~~
-
-**kinit**
- [**-V**]
- [**-l** *lifetime*]
- [**-s** *start_time*]
- [**-r** *renewable_life*]
- [**-p** | -**P**]
- [**-f** | -**F**]
- [**-a**]
- [**-A**]
- [**-C**]
- [**-E**]
- [**-v**]
- [**-R**]
- [**-k** [-**t** *keytab_file*]]
- [**-c** *cache_name*]
- [**-n**]
- [**-S** *service_name*]
- [**-T** *armor_ccache*]
- [**-X** *attribute[=value]*]
- [*principal*]
+--------
+
+**kinit**
+[**-V**]
+[**-l** *lifetime*]
+[**-s** *start_time*]
+[**-r** *renewable_life*]
+[**-p** | -**P**]
+[**-f** | -**F**]
+[**-a**]
+[**-A**]
+[**-C**]
+[**-E**]
+[**-v**]
+[**-R**]
+[**-k** [-**t** *keytab_file*]]
+[**-c** *cache_name*]
+[**-n**]
+[**-S** *service_name*]
+[**-T** *armor_ccache*]
+[**-X** *attribute*\ [=\ *value*]]
+[*principal*]
DESCRIPTION
-~~~~~~~~~~~~~
+-----------
-*kinit* obtains and caches an initial ticket-granting ticket for principal.
+kinit obtains and caches an initial ticket-granting ticket for
+*principal*.
OPTIONS
-~~~~~~~
-
- **-V** display verbose output.
-
- **-l** *lifetime*
- requests a ticket with the lifetime lifetime. The
- value for lifetime must be followed immediately by one
- of the following delimiters::
-
- s seconds
- m minutes
- h hours
- d days
-
- as in "kinit -l 90m". You cannot mix units; a value of "3h30m" will result in an error.
-
- If the **-l** option is not specified, the default ticket lifetime
- (configured by each site) is used. Specifying a ticket lifetime longer than the maximum
- ticket lifetime (configured by each site) results in a ticket with the maximum lifetime.
-
- **-s** *start_time*
- requests a postdated ticket, valid starting at
- *start_time*. Postdated tickets are issued with the
- *invalid* flag set, and need to be fed back to the kdc
- before use.
-
- **-r** *renewable_life*
- requests renewable tickets, with a total lifetime of
- *renewable_life*. The duration is in the same format as
- the **-l** option, with the same delimiters.
-
- **-f** request forwardable tickets.
-
- **-F** do not request forwardable tickets.
-
- **-p** request proxiable tickets.
-
- **-P** do not request proxiable tickets.
-
- **-a** request tickets with the local address[es].
-
- **-A** request address-less tickets.
-
- **-C** requests canonicalization of the principal name.
-
- **-E** treats the principal name as an enterprise name.
-
- **-v**
- requests that the ticket granting ticket in the cache
- (with the *invalid* flag set) be passed to the KDC for validation.
- If the ticket is within its requested time range,
- the cache is replaced with the validated ticket.
-
- **-R**
- requests renewal of the ticket-granting ticket.
- Note that an expired ticket cannot be renewed, even if the ticket
- is still within its renewable life.
-
- **-k** [**-t** *keytab_file*]
- requests a ticket, obtained from a key in the local host's *keytab* file.
- The name and location of the key tab file may be specified with the
- **-t** *keytab_file* option; otherwise the default name and location will be used.
- By default a host ticket is requested but any principal may be specified.
- On a KDC, the special keytab location **KDB:** can be used to indicate that kinit
- should open the KDC database and look up the key directly.
- This permits an administrator to obtain tickets as any principal that
- supports password-based authentication.
-
- **-n**
- Requests anonymous processing.
- Two types of anonymous principals are supported.
-
- For fully anonymous Kerberos, configure pkinit on the KDC and configure
- *pkinit_anchors* in the client's krb5.conf. Then use the **-n** option with
- a principal of the form *@REALM* (an empty principal name followed by the
- at-sign and a realm name). If permitted by the KDC, an anonymous ticket will be returned.
-
- A second form of anonymous tickets is supported; these realm-exposed tickets
- hide the identity of the client but not the client's realm.
- For this mode, use **kinit -n** with a normal principal name.
- If supported by the KDC, the principal (but not realm) will be replaced by the anonymous principal.
-
- As of release 1.8, the MIT Kerberos KDC only supports fully anonymous operation.
-
- **-T** *armor_ccache*
- Specifies the name of a credential cache that already contains a ticket. If supported by the KDC, This
- ccache will be used to armor the request so that an attacker would have to know both the key of the armor
- ticket and the key of the principal used for authentication in order to attack the request. Armoring also
- makes sure that the response from the KDC is not modified in transit.
-
- **-c** *cache_name*
- use *cache_name* as the Kerberos 5 credentials (ticket) cache name and location;
- if this option is not used, the default cache name and location are used.
-
- The default credentials cache may vary between systems. If
- the **KRB5CCNAME** environment variable is set, its value is
- used to name the default ticket cache. If a principal name
- is specified and the type of the default credentials cache
- supports a collection (such as the DIR type), an existing
- cache containing credentials for the principal is selected
- or a new one is created and becomes the new primary cache.
- Otherwise, any existing contents of the default cache are
- destroyed by kinit.
-
- **-S** *service_name*
- specify an alternate service name to use when getting initial tickets.
-
- **-X** *attribute* [= *value* ]
- specify a pre-authentication *attribute* and *value* to be passed to pre-authentication plugins.
- The acceptable attribute and value values vary from pre-authentication plugin to plugin.
- This option may be specified multiple times to specify multiple attributes.
- If no value is specified, it is assumed to be "yes".
-
- The following attributes are recognized by the OpenSSL pkinit pre-authentication mechanism:
-
- **X509_user_identity** = *value*
-
- specify where to find user's X509 identity information
-
- **X509_anchors** = *value*
-
- specify where to find trusted X509 anchor information
-
- **flag_RSA_PROTOCOL** [ = *yes* ]
-
- specify use of RSA, rather than the default Diffie-Hellman protocol
-
+-------
+
+**-V**
+ display verbose output.
+
+**-l** *lifetime*
+ requests a ticket with the lifetime lifetime. The
+ value for lifetime must be followed immediately by one
+ of the following delimiters::
+
+ s seconds
+ m minutes
+ h hours
+ d days
+
+ as in ``kinit -l 90m``. You cannot mix units; a value of
+ ``3h30m`` will result in an error.
+
+ If the **-l** option is not specified, the default ticket lifetime
+ (configured by each site) is used. Specifying a ticket lifetime
+ longer than the maximum ticket lifetime (configured by each site)
+ results in a ticket with the maximum lifetime.
+
+**-s** *start_time*
+ requests a postdated ticket, valid starting at *start_time*.
+ Postdated tickets are issued with the **invalid** flag set, and
+ need to be fed back to the kdc before use.
+
+**-r** *renewable_life*
+ requests renewable tickets, with a total lifetime of
+ *renewable_life*. The duration is in the same format as the
+ **-l** option, with the same delimiters.
+
+**-f**
+ request forwardable tickets.
+
+**-F**
+ do not request forwardable tickets.
+
+**-p**
+ request proxiable tickets.
+
+**-P**
+ do not request proxiable tickets.
+
+**-a**
+ request tickets with the local address[es].
+
+**-A**
+ request address-less tickets.
+
+**-C**
+ requests canonicalization of the principal name.
+
+**-E**
+ treats the principal name as an enterprise name.
+
+**-v**
+ requests that the ticket granting ticket in the cache (with the
+ **invalid** flag set) be passed to the KDC for validation. If the
+ ticket is within its requested time range, the cache is replaced
+ with the validated ticket.
+
+**-R**
+ requests renewal of the ticket-granting ticket. Note that an
+ expired ticket cannot be renewed, even if the ticket is still
+ within its renewable life.
+
+**-k** [**-t** *keytab_file*]
+ requests a ticket, obtained from a key in the local host's keytab
+ file. The name and location of the key tab file may be specified
+ with the **-t** *keytab_file* option; otherwise the default name
+ and location will be used. By default a host ticket is requested
+ but any principal may be specified. On a KDC, the special keytab
+ location ``KDB:`` can be used to indicate that kinit should open
+ the KDC database and look up the key directly. This permits an
+ administrator to obtain tickets as any principal that supports
+ password-based authentication.
+
+**-n**
+ Requests anonymous processing. Two types of anonymous principals
+ are supported.
+
+ For fully anonymous Kerberos, configure pkinit on the KDC and
+ configure **pkinit_anchors** in the client's krb5.conf. Then use
+ the **-n** option with a principal of the form ``@REALM`` (an
+ empty principal name followed by the at-sign and a realm name).
+ If permitted by the KDC, an anonymous ticket will be returned.
+
+ A second form of anonymous tickets is supported; these
+ realm-exposed tickets hide the identity of the client but not the
+ client's realm. For this mode, use ``kinit -n`` with a normal
+ principal name. If supported by the KDC, the principal (but not
+ realm) will be replaced by the anonymous principal.
+
+ As of release 1.8, the MIT Kerberos KDC only supports fully
+ anonymous operation.
+
+**-T** *armor_ccache*
+ Specifies the name of a credential cache that already contains a
+ ticket. If supported by the KDC, this ccache will be used to
+ armor the request so that an attacker would have to know both the
+ key of the armor ticket and the key of the principal used for
+ authentication in order to attack the request. Armoring also
+ makes sure that the response from the KDC is not modified in
+ transit.
+
+**-c** *cache_name*
+ use *cache_name* as the Kerberos 5 credentials (ticket) cache name
+ and location; if this option is not used, the default cache name
+ and location are used.
+
+ The default credentials cache may vary between systems. If the
+ **KRB5CCNAME** environment variable is set, its value is used to
+ name the default ticket cache. If a principal name is specified
+ and the type of the default credentials cache supports a
+ collection (such as the DIR type), an existing cache containing
+ credentials for the principal is selected or a new one is created
+ and becomes the new primary cache. Otherwise, any existing
+ contents of the default cache are destroyed by kinit.
+
+**-S** *service_name*
+ specify an alternate service name to use when getting initial
+ tickets.
+
+**-X** *attribute*\ [=\ *value*]
+ specify a pre-authentication *attribute* and *value* to be passed
+ to pre-authentication plugins. The acceptable attribute and value
+ values vary from pre-authentication plugin to plugin. This option
+ may be specified multiple times to specify multiple attributes.
+ If no value is specified, it is assumed to be "yes".
+
+ The following attributes are recognized by the OpenSSL pkinit
+ pre-authentication mechanism:
+
+ **X509_user_identity**\ =\ *value*
+ specify where to find user's X509 identity information
+
+ **X509_anchors**\ =\ *value*
+ specify where to find trusted X509 anchor information
+
+ **flag_RSA_PROTOCOL**\ [**=yes**]
+ specify use of RSA, rather than the default Diffie-Hellman
+ protocol
ENVIRONMENT
-~~~~~~~~~~~~~
+-----------
-*kinit* uses the following environment variables:
+kinit uses the following environment variables:
- **KRB5CCNAME**
- Location of the default Kerberos 5 credentials (ticket)
- cache, in the form *type*:*residual*. If no type prefix is
- present, the **FILE** type is assumed. The type of the
- default cache may determine the availability of a cache
- collection; for instance, a default cache of type **DIR**
- causes caches within the directory to be present in the
- collection.
+**KRB5CCNAME**
+ Location of the default Kerberos 5 credentials (ticket) cache, in
+ the form *type*:*residual*. If no type prefix is present, the
+ **FILE** type is assumed. The type of the default cache may
+ determine the availability of a cache collection; for instance, a
+ default cache of type **DIR** causes caches within the directory
+ to be present in the collection.
FILES
-~~~~~~~~
+-----
-/tmp/krb5cc_[uid] default location of Kerberos 5 credentials cache ([uid] is the decimal UID of the user).
+``/tmp/krb5cc_[uid]``
+ default location of Kerberos 5 credentials cache ([*uid*] is the
+ decimal UID of the user).
-/etc/krb5.keytab default location for the local host's keytab file.
+``/etc/krb5.keytab``
+ default location for the local host's keytab file.
SEE ALSO
-~~~~~~~~~~~
+--------
klist(1), kdestroy(1), kerberos(1)
-
-
klist - list cached Kerberos tickets
-======================================
-
+====================================
SYNOPSIS
-~~~~~~~~
+--------
**klist**
- [**-e**]
- [[**-c**] [**-l**] [**-A**] [**-f**] [**-s**] [**-a** [**-n**]]]
- [**-k** [**-t**] [**-K**]]
- [**-V**]
- [*cache_name* | *keytab_name*]
+[**-e**]
+[[**-c**] [**-l**] [**-A**] [**-f**] [**-s**] [**-a** [**-n**]]]
+[**-k** [**-t**] [**-K**]]
+[**-V**]
+[*cache_name*\|\ *keytab_name*]
DESCRIPTION
-~~~~~~~~~~~~
+-----------
-*klist* lists the Kerberos principal and Kerberos tickets held in a credentials cache, or the keys held in a *keytab* file.
+klist lists the Kerberos principal and Kerberos tickets held in a
+credentials cache, or the keys held in a keytab file.
OPTIONS
-~~~~~~~~
-
- **-e**
- Displays the encryption types of the session key and the ticket for each credential in the credential cache,
- or each key in the keytab file.
-
- **-l**
- If a cache collection is available, displays a table
- summarizing the caches present in the collection.
-
- **-A**
- If a cache collection is available, displays the contents of
- all of the caches in the collection.
-
- **-c**
- List tickets held in a credentials cache. This is the default if neither *-c* nor *-k* is specified.
-
- **-f**
- Shows the flags present in the credentials, using the following abbreviations::
-
- F Forwardable
- f forwarded
- P Proxiable
- p proxy
- D postDateable
- d postdated
- R Renewable
- I Initial
- i invalid
- H Hardware authenticated
- A preAuthenticated
- T Transit policy checked
- O Okay as delegate
- a anonymous
-
- **-s**
- Causes *klist* to run silently (produce no output), but to still set the exit status according to whether it
- finds the credentials cache. The exit status is '0' if *klist* finds a credentials cache, and '1' if it does not
- or if the tickets are expired.
-
- **-a**
- Display list of addresses in credentials.
-
- **-n**
- Show numeric addresses instead of reverse-resolving addresses.
-
- **-k**
- List keys held in a keytab file.
-
- **-t**
- Display the time entry timestamps for each keytab entry in the keytab file.
-
- **-K**
- Display the value of the encryption key in each *keytab* entry in the *keytab* file.
-
- **-V**
- Display the Kerberos version number and exit.
-
- If **cache_name** or **keytab_name** is not specified, *klist* will display the credentials in the default credentials cache or
- *keytab* file as appropriate. If the *KRB5CCNAME* environment variable is set, its value is used to name the default ticket cache.
+-------
+
+**-e**
+ Displays the encryption types of the session key and the ticket
+ for each credential in the credential cache, or each key in the
+ keytab file.
+
+**-l**
+ If a cache collection is available, displays a table summarizing
+ the caches present in the collection.
+
+**-A**
+ If a cache collection is available, displays the contents of all
+ of the caches in the collection.
+
+**-c**
+ List tickets held in a credentials cache. This is the default if
+ neither **-c** nor **-k** is specified.
+
+**-f**
+ Shows the flags present in the credentials, using the following
+ abbreviations::
+
+ F Forwardable
+ f forwarded
+ P Proxiable
+ p proxy
+ D postDateable
+ d postdated
+ R Renewable
+ I Initial
+ i invalid
+ H Hardware authenticated
+ A preAuthenticated
+ T Transit policy checked
+ O Okay as delegate
+ a anonymous
+
+**-s**
+ Causes klist to run silently (produce no output), but to still set
+ the exit status according to whether it finds the credentials
+ cache. The exit status is '0' if klist finds a credentials cache,
+ and '1' if it does not or if the tickets are expired.
+
+**-a**
+ Display list of addresses in credentials.
+
+**-n**
+ Show numeric addresses instead of reverse-resolving addresses.
+
+**-k**
+ List keys held in a keytab file.
+
+**-t**
+ Display the time entry timestamps for each keytab entry in the
+ keytab file.
+
+**-K**
+ Display the value of the encryption key in each keytab entry in
+ the keytab file.
+
+**-V**
+ Display the Kerberos version number and exit.
+
+If *cache_name* or *keytab_name* is not specified, klist will display
+the credentials in the default credentials cache or keytab file as
+appropriate. If the **KRB5CCNAME** environment variable is set, its
+value is used to name the default ticket cache.
ENVIRONMENT
-~~~~~~~~~~~~~
+-----------
-*klist* uses the following environment variable:
+klist uses the following environment variable:
- **KRB5CCNAME**
- Location of the default Kerberos 5 credentials (ticket)
- cache, in the form *type*:*residual*. If no type prefix is
- present, the **FILE** type is assumed. The type of the
- default cache may determine the availability of a cache
- collection; for instance, a default cache of type **DIR**
- causes caches within the directory to be present in the
- collection.
+**KRB5CCNAME**
+ Location of the default Kerberos 5 credentials (ticket) cache, in
+ the form *type*:*residual*. If no type prefix is present, the
+ **FILE** type is assumed. The type of the default cache may
+ determine the availability of a cache collection; for instance, a
+ default cache of type **DIR** causes caches within the directory
+ to be present in the collection.
FILES
-~~~~~~~~~
+-----
-/tmp/krb5cc_[uid] - Default location of Kerberos 5 credentials cache ([uid] is the decimal UID of the user).
+``/tmp/krb5cc_[uid]``
+ Default location of Kerberos 5 credentials cache ([uid] is the
+ decimal UID of the user).
-/etc/krb5.keytab - Default location for the local host's keytab file.
+``/etc/krb5.keytab``
+ Default location for the local host's keytab file.
SEE ALSO
-~~~~~~~~~
+--------
kinit(1), kdestroy(1)
-
-
.. _kpasswd(1):
kpasswd
-===============================================
-
+=======
SYNOPSIS
-~~~~~~~~~~~~~
+--------
-*kpasswd* [ *principal* ]
+**kpasswd** [*principal*]
DESCRIPTION
-~~~~~~~~~~~~~
+-----------
-The *kpasswd* command is used to change a Kerberos principal's password.
-*kpasswd* prompts for the current Kerberos password, which is used to obtain a
-*changepw* ticket from the KDC for the user's Kerberos realm.
-If *kpasswd* successfully obtains the *changepw* ticket, the user is prompted twice for
-the new password, and the password is changed.
+The kpasswd command is used to change a Kerberos principal's password.
+kpasswd prompts for the current Kerberos password, which is used to
+obtain a ``changepw`` ticket from the KDC for the user's Kerberos
+realm. If kpasswd successfully obtains the ``changepw`` ticket, the
+user is prompted twice for the new password, and the password is
+changed.
-If the principal is governed by a policy that specifies the length and/or number of
-character classes required in the new password, the new password must conform to the policy.
-(The five character classes are lower case, upper case, numbers, punctuation, and all other characters.)
+If the principal is governed by a policy that specifies the length
+and/or number of character classes required in the new password, the
+new password must conform to the policy. (The five character classes
+are lower case, upper case, numbers, punctuation, and all other
+characters.)
OPTIONS
-~~~~~~~~~~~~~
+-------
*principal*
- Change the password for the Kerberos principal principal.
- Otherwise, *kpasswd* uses the principal name from an existing ccache if there is one;
- if not, the principal is derived from the identity of the user invoking the *kpasswd* command.
+ Change the password for the Kerberos principal principal.
+ Otherwise, kpasswd uses the principal name from an existing ccache
+ if there is one; if not, the principal is derived from the
+ identity of the user invoking the kpasswd command.
PORTS
-~~~~~~~~~~~~~
+-----
-*kpasswd* looks first for::
+kpasswd looks first for::
- kpasswd_server = host:port
+ kpasswd_server = host:port
-in the [*realms*] section of the *krb5.conf* file under the current realm.
-If that is missing, *kpasswd* looks for the *admin_server* entry, but substitutes 464 for the port.
+in the [realms] section of the krb5.conf file under the current realm.
+If that is missing, kpasswd looks for the **admin_server** entry, but
+substitutes 464 for the port.
SEE ALSO
-~~~~~~~~~~~~~
+--------
kadmin(8), kadmind(8)
BUGS
-~~~~~
-
-*kpasswd* may not work with multi-homed hosts running on the Solaris platform.
+----
+kpasswd may not work with multi-homed hosts running on the Solaris
+platform.
ksu - Kerberized super-user
-=================================
+===========================
SYNOPSIS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-**ksu**
- [ *target_user* ]
- [ **-n** *target_principal_name* ]
- [ **-c** *source_cache_name* ]
- [ **-k** ]
- [ **-D** ]
- [ **-r** time ]
- [ **-pf** ]
- [ **-l** *lifetime* ]
- [ **-z | Z** ]
- [ **-q** ]
- [ **-e** *command* [ args ... ] ] [ **-a** [ args ... ] ]
+--------
+
+**ksu**
+[ *target_user* ]
+[ **-n** *target_principal_name* ]
+[ **-c** *source_cache_name* ]
+[ **-k** ]
+[ **-D** ]
+[ **-r** time ]
+[ **-pf** ]
+[ **-l** *lifetime* ]
+[ **-z | Z** ]
+[ **-q** ]
+[ **-e** *command* [ args ... ] ] [ **-a** [ args ... ] ]
REQUIREMENTS
-~~~~~~~~~~~~~~~~~
+------------
+
+Must have Kerberos version 5 installed to compile ksu. Must have a
+Kerberos version 5 server running to use ksu.
-Must have Kerberos version 5 installed to compile *ksu*. Must have a Kerberos version 5 server running to use *ksu*.
DESCRIPTION
-~~~~~~~~~~~~~~~
+-----------
+
+ksu is a Kerberized version of the su program that has two missions:
+one is to securely change the real and effective user ID to that of
+the target user, and the other is to create a new security context.
-*ksu* is a Kerberized version of the *su* program that has two missions:
-one is to securely change the real and effective user ID to that of the target user,
-and the other is to create a new security context.
+.. note:: For the sake of clarity, all references to and attributes of
+ the user invoking the program will start with "source"
+ (e.g. "source user", "source cache", etc.).
-.. note::
- For the sake of clarity, all references to and attributes of the user invoking the program
- will start with 'source' (e.g. *source user, source cache*, etc.).
-
- Likewise, all references to and attributes of the target account will start with 'target'.
+ Likewise, all references to and attributes of the target
+ account will start with "target".
AUTHENTICATION
-~~~~~~~~~~~~~~~~~~~~~
-
-To fulfill the first mission, *ksu* operates in two phases: authentication and authorization.
-Resolving the target principal name is the first step in authentication.
-The user can either specify his principal name with the *-n* option (e.g. *-n jqpublic\@USC.EDU* ) or
-a default principal name will be assigned using a heuristic described in the *OPTIONS* section (see *-n* option).
-The target user name must be the first argument to *ksu*; if not specified root is the default.
-If '.' is specified then the target user will be the source user (e.g. *ksu* .).
-If the source user is root or the target user is the source user, no authentication or authorization takes place.
-Otherwise, *ksu* looks for an appropriate Kerberos ticket in the source cache.
-
-The ticket can either be for the end-server or a ticket granting ticket (TGT) for the target principal's realm.
-If the ticket for the end-server is already in the cache, it's decrypted and verified.
-If it's not in the cache but the TGT is, the TGT is used to obtain the ticket for the end-server.
-The end-server ticket is then verified.
-If neither ticket is in the cache, but *ksu* is compiled with the *GET_TGT_VIA_PASSWD* define,
-the user will be prompted for a Kerberos password which will then be used to get a TGT.
-If the user is logged in remotely and does not have a secure channel, the password may be exposed.
-If neither ticket is in the cache and *GET_TGT_VIA_PASSWD* is not defined, authentication fails.
+--------------
+
+To fulfill the first mission, ksu operates in two phases:
+authentication and authorization. Resolving the target principal name
+is the first step in authentication. The user can either specify his
+principal name with the **-n** option (e.g. ``-n jqpublic@USC.EDU``)
+or a default principal name will be assigned using a heuristic
+described in the OPTIONS section (see **-n** option). The target user
+name must be the first argument to ksu; if not specified root is the
+default. If ``.`` is specified then the target user will be the
+source user (e.g. ``ksu .``). If the source user is root or the
+target user is the source user, no authentication or authorization
+takes place. Otherwise, ksu looks for an appropriate Kerberos ticket
+in the source cache.
+
+The ticket can either be for the end-server or a ticket granting
+ticket (TGT) for the target principal's realm. If the ticket for the
+end-server is already in the cache, it's decrypted and verified. If
+it's not in the cache but the TGT is, the TGT is used to obtain the
+ticket for the end-server. The end-server ticket is then verified.
+If neither ticket is in the cache, but ksu is compiled with the
+**GET_TGT_VIA_PASSWD** define, the user will be prompted for a
+Kerberos password which will then be used to get a TGT. If the user
+is logged in remotely and does not have a secure channel, the password
+may be exposed. If neither ticket is in the cache and
+**GET_TGT_VIA_PASSWD** is not defined, authentication fails.
+
AUTHORIZATION
-~~~~~~~~~~~~~~~~~~
+-------------
-This section describes authorization of the source user when *ksu* is invoked without the *-e* option.
-For a description of the -e option, see the OPTIONS section.
+This section describes authorization of the source user when ksu is
+invoked without the **-e** option. For a description of the **-e**
+option, see the OPTIONS section.
-Upon successful authentication, *ksu* checks whether the target principal is authorized to access the target account.
-In the target user's home directory, *ksu* attempts to access two authorization files: *.k5login* and *.k5users*.
-In the *.k5login* file each line contains the name of a principal that is authorized to access the account.
+Upon successful authentication, ksu checks whether the target
+principal is authorized to access the target account. In the target
+user's home directory, ksu attempts to access two authorization files:
+.k5login and .k5users. In the .k5login file each line contains the
+name of a principal that is authorized to access the account.
For example::
- jqpublic@USC.EDU
- jqpublic/secure@USC.EDU
- jqpublic/admin@USC.EDU
+ jqpublic@USC.EDU
+ jqpublic/secure@USC.EDU
+ jqpublic/admin@USC.EDU
-The format of *.k5users* is the same, except the principal name may be followed by a list of commands
-that the principal is authorized to execute. (see the *-e* option in the *OPTIONS* section for details).
+The format of .k5users is the same, except the principal name may be
+followed by a list of commands that the principal is authorized to
+execute (see the **-e** option in the OPTIONS section for details).
+
+Thus if the target principal name is found in the .k5login file the
+source user is authorized to access the target account. Otherwise ksu
+looks in the .k5users file. If the target principal name is found
+without any trailing commands or followed only by ``*`` then the
+source user is authorized. If either .k5login or .k5users exist but
+an appropriate entry for the target principal does not exist then
+access is denied. If neither file exists then the principal will be
+granted access to the account according to the aname->lname mapping
+rules. Otherwise, authorization fails.
-Thus if the target principal name is found in the *.k5login* file the source user is authorized to access the target account.
-Otherwise *ksu* looks in the *.k5users* file.
-If the target principal name is found without any trailing commands or followed only by '\*' then the source user is authorized.
-If either *.k5login* or *.k5users* exist but an appropriate entry for the target principal does not exist then access is denied.
-If neither file exists then the principal will be granted access to the account according to the aname->lname mapping rules.
-Otherwise, authorization fails.
EXECUTION OF THE TARGET SHELL
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Upon successful authentication and authorization, *ksu* proceeds in a similar fashion to *su*.
-The environment is unmodified with the exception of USER, HOME and SHELL variables.
-If the target user is not root, USER gets set to the target user name.
-Otherwise USER remains unchanged.
-Both HOME and SHELL are set to the target login's default values.
-In addition, the environment variable *KRB5CCNAME* gets set to the name of the target cache.
-The real and effective user ID are changed to that of the target user.
-The target user's shell is then invoked (the shell name is specified in the password file).
-Upon termination of the shell, *ksu* deletes the target cache (unless *ksu* is invoked with the *-k* option).
-This is implemented by first doing a fork and then an exec, instead of just exec, as done by *su*.
+-----------------------------
+
+Upon successful authentication and authorization, ksu proceeds in a
+similar fashion to su. The environment is unmodified with the
+exception of USER, HOME and SHELL variables. If the target user is
+not root, USER gets set to the target user name. Otherwise USER
+remains unchanged. Both HOME and SHELL are set to the target login's
+default values. In addition, the environment variable **KRB5CCNAME**
+gets set to the name of the target cache. The real and effective user
+ID are changed to that of the target user. The target user's shell is
+then invoked (the shell name is specified in the password file). Upon
+termination of the shell, ksu deletes the target cache (unless ksu is
+invoked with the **-k** option). This is implemented by first doing a
+fork and then an exec, instead of just exec, as done by su.
+
CREATING A NEW SECURITY CONTEXT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*ksu* can be used to create a new security context for the target program
-(either the target shell, or command specified via the *-e* option).
-The target program inherits a set of credentials from the source user.
-By default, this set includes all of the credentials in the source cache
-plus any additional credentials obtained during authentication.
-The source user is able to limit the credentials in this set by using *-z* or *-Z* option.
-*-z* restricts the copy of tickets from the source cache to the target cache
-to only the tickets where client == the target principal name.
-The *-Z* option provides the target user with a fresh target cache (no creds in the cache).
-Note that for security reasons, when the source user is root and target user is non-root,
-*-z* option is the default mode of operation.
-
-While no authentication takes place if the source user is root or is the same as the target user,
-additional tickets can still be obtained for the target cache.
-If *-n* is specified and no credentials can be copied to the target cache,
-the source user is prompted for a Kerberos password (unless *-Z* specified or *GET_TGT_VIA_PASSWD* is undefined).
-If successful, a TGT is obtained from the Kerberos server and stored in the target cache.
-Otherwise, if a password is not provided (user hit return) *ksu* continues in a normal mode
-of operation (the target cache will not contain the desired TGT).
-If the wrong password is typed in, *ksu* fails.
-
-*Side Note*: during authentication, only the tickets that could be obtained without
-providing a password are cached in in the source cache.
+-------------------------------
+
+ksu can be used to create a new security context for the target
+program (either the target shell, or command specified via the **-e**
+option). The target program inherits a set of credentials from the
+source user. By default, this set includes all of the credentials in
+the source cache plus any additional credentials obtained during
+authentication. The source user is able to limit the credentials in
+this set by using **-z** or **-Z** option. **-z** restricts the copy
+of tickets from the source cache to the target cache to only the
+tickets where client == the target principal name. The **-Z** option
+provides the target user with a fresh target cache (no creds in the
+cache). Note that for security reasons, when the source user is root
+and target user is non-root, **-z** option is the default mode of
+operation.
+
+While no authentication takes place if the source user is root or is
+the same as the target user, additional tickets can still be obtained
+for the target cache. If **-n** is specified and no credentials can
+be copied to the target cache, the source user is prompted for a
+Kerberos password (unless **-Z** specified or **GET_TGT_VIA_PASSWD**
+is undefined). If successful, a TGT is obtained from the Kerberos
+server and stored in the target cache. Otherwise, if a password is
+not provided (user hit return) ksu continues in a normal mode of
+operation (the target cache will not contain the desired TGT). If the
+wrong password is typed in, ksu fails.
+
+.. note:: During authentication, only the tickets that could be
+ obtained without providing a password are cached in in the
+ source cache.
OPTIONS
-~~~~~~~~~~~~~~~
-
- **-n** *target_principal_name*
- Specify a Kerberos target principal name. Used in authentication and authorization phases of *ksu*.
-
- If *ksu* is invoked without *-n*, a default principal name is assigned via the following heuristic:
-
- *Case 1: source user is non-root.*
- If the target user is the source user the default principal name is set to the default principal of the source cache.
- If the cache does not exist then the default principal name is set to target_user\@local_realm.
- If the source and target users are different and neither ~target_user/*.k5users* nor ~target_user/*.k5login* exist
- then the default principal name is *target_user_login_name\@local_realm*.
- Otherwise, starting with the first principal listed below, *ksu* checks if the principal is authorized to access the target account
- and whether there is a legitimate ticket for that principal in the source cache.
- If both conditions are met that principal becomes the default target principal,
- otherwise go to the next principal.
-
- a) default principal of the source cache
- b) target_user\@local_realm
- c) source_user\@local_realm
-
- If a-c fails try any principal for which there is a ticket in the source cache and that is authorized to access the target account.
- If that fails select the first principal that is authorized to access the target account from the above list.
- If none are authorized and *ksu* is configured with *PRINC_LOOK_AHEAD* turned on, select the default principal as follows:
-
- For each candidate in the above list, select an authorized principal that has the same realm name and
- first part of the principal name equal to the prefix of the candidate.
- For example if candidate a) is *jqpublic\@ISI.EDU* and *jqpublic/secure\@ISI.EDU* is authorized to access the target account
- then the default principal is set to *jqpublic/secure\@ISI.EDU*.
-
- *Case 2: source user is root.*
- If the target user is non-root then the default principal name is *target_user\@local_realm*.
- Else, if the source cache exists the default principal name is set to the default principal of the source cache.
- If the source cache does not exist, default principal name is set to *root\@local_realm*.
-
- **-c** *source_cache_name*
- Specify source cache name (e.g. -c FILE\:/tmp/my_cache).
- If *-c* option is not used then the name is obtained from *KRB5CCNAME* environment variable.
- If *KRB5CCNAME* is not defined the source cache name is set to krb5cc_<source uid>.
- The target cache name is automatically set to krb5cc_<target uid>.(gen_sym()),
- where gen_sym generates a new number such that the resulting cache does not already exist.
- For example::
-
- krb5cc_1984.2
-
- **-k**
- Do not delete the target cache upon termination of the target shell or a command ( *-e* command).
- Without *-k*, *ksu* deletes the target cache.
-
- **-D**
- Turn on debug mode.
-
- **-z**
- Restrict the copy of tickets from the source cache to the target cache to only the tickets where client == the target principal name.
- Use the *-n* option if you want the tickets for other then the default principal.
- Note that the *-z* option is mutually exclusive with the *-Z* option.
-
- **-Z**
- Don't copy any tickets from the source cache to the target cache.
- Just create a fresh target cache, where the default principal name of the cache is initialized to the target principal name.
- Note that the *-Z* option is mutually exclusive with the *-z* option.
-
- **-q**
- Suppress the printing of status messages.
-
-Ticket granting ticket options
-
- **-l** *lifetime* **-r** *time* **-pf**
- The ticket granting ticket options only apply to the case where there are no appropriate tickets in the cache to authenticate
- the source user. In this case if *ksu* is configured to prompt users for a Kerberos password (GET_TGT_VIA_PASSWD is defined),
- the ticket granting ticket options that are specified will be used when getting a ticket granting ticket from the Kerberos
- server.
+-------
+
+**-n** *target_principal_name*
+ Specify a Kerberos target principal name. Used in authentication
+ and authorization phases of ksu.
+
+ If ksu is invoked without **-n**, a default principal name is
+ assigned via the following heuristic:
+
+ * Case 1: source user is non-root.
+
+ If the target user is the source user the default principal name
+ is set to the default principal of the source cache. If the
+ cache does not exist then the default principal name is set to
+ ``target_user@local_realm``. If the source and target users are
+ different and neither ``~target_user/.k5users`` nor
+ ``~target_user/.k5login`` exist then the default principal name
+ is ``target_user_login_name@local_realm``. Otherwise, starting
+ with the first principal listed below, ksu checks if the
+ principal is authorized to access the target account and whether
+ there is a legitimate ticket for that principal in the source
+ cache. If both conditions are met that principal becomes the
+ default target principal, otherwise go to the next principal.
+
+ a) default principal of the source cache
+ b) target_user\@local_realm
+ c) source_user\@local_realm
+
+ If a-c fails try any principal for which there is a ticket in
+ the source cache and that is authorized to access the target
+ account. If that fails select the first principal that is
+ authorized to access the target account from the above list. If
+ none are authorized and ksu is configured with
+ **PRINC_LOOK_AHEAD** turned on, select the default principal as
+ follows:
+
+ For each candidate in the above list, select an authorized
+ principal that has the same realm name and first part of the
+ principal name equal to the prefix of the candidate. For
+ example if candidate a) is ``jqpublic@ISI.EDU`` and
+ ``jqpublic/secure@ISI.EDU`` is authorized to access the target
+ account then the default principal is set to
+ ``jqpublic/secure@ISI.EDU``.
+
+ * Case 2: source user is root.
+
+ If the target user is non-root then the default principal name
+ is ``target_user@local_realm``. Else, if the source cache
+ exists the default principal name is set to the default
+ principal of the source cache. If the source cache does not
+ exist, default principal name is set to ``root\@local_realm``.
+
+**-c** *source_cache_name*
+
+ Specify source cache name (e.g. ``-c FILE:/tmp/my_cache``). If
+ **-c** option is not used then the name is obtained from
+ **KRB5CCNAME** environment variable. If **KRB5CCNAME** is not
+ defined the source cache name is set to ``krb5cc_<source uid>``.
+ The target cache name is automatically set to ``krb5cc_<target
+ uid>.(gen_sym())``, where gen_sym generates a new number such that
+ the resulting cache does not already exist. For example::
+
+ krb5cc_1984.2
+
+**-k**
+ Do not delete the target cache upon termination of the target
+ shell or a command (**-e** command). Without **-k**, ksu deletes
+ the target cache.
+
+**-D**
+ Turn on debug mode.
+
+**-z**
+ Restrict the copy of tickets from the source cache to the target
+ cache to only the tickets where client == the target principal
+ name. Use the **-n** option if you want the tickets for other then
+ the default principal. Note that the **-z** option is mutually
+ exclusive with the **-Z** option.
+
+**-Z**
+ Don't copy any tickets from the source cache to the target cache.
+ Just create a fresh target cache, where the default principal name
+ of the cache is initialized to the target principal name. Note
+ that the **-Z** option is mutually exclusive with the **-z**
+ option.
+
+**-q**
+ Suppress the printing of status messages.
+
+Ticket granting ticket options:
+
+**-l** *lifetime* **-r** *time* **-pf**
+ The ticket granting ticket options only apply to the case where
+ there are no appropriate tickets in the cache to authenticate the
+ source user. In this case if ksu is configured to prompt users
+ for a Kerberos password (**GET_TGT_VIA_PASSWD** is defined), the
+ ticket granting ticket options that are specified will be used
+ when getting a ticket granting ticket from the Kerberos server.
+
+**-l** *lifetime*
+ specifies the lifetime to be requested for the ticket; if this
+ option is not specified, the default ticket lifetime (configured
+ by each site) is used instead.
+
+**-r** *time*
+ specifies that the **renewable** option should be requested for
+ the ticket, and specifies the desired total lifetime of the
+ ticket.
+
+**-p**
+ specifies that the **proxiable** option should be requested for
+ the ticket.
+
+**-f**
+ option specifies that the **forwardable** option should be
+ requested for the ticket.
+
+**-e** *command* [*args* ...]
+ ksu proceeds exactly the same as if it was invoked without the
+ **-e** option, except instead of executing the target shell, ksu
+ executes the specified command Example of usage::
+
+ ksu bob -e ls -lag
+
+ The authorization algorithm for **-e** is as follows:
+
+ If the source user is root or source user == target user, no
+ authorization takes place and the command is executed. If source
+ user id != 0, and ``~target_user/.k5users`` file does not exist,
+ authorization fails. Otherwise, ``~target_user/.k5users`` file
+ must have an appropriate entry for target principal to get
+ authorized.
+
+ The .k5users file format:
+
+ A single principal entry on each line that may be followed by a
+ list of commands that the principal is authorized to execute. A
+ principal name followed by a ``*`` means that the user is
+ authorized to execute any command. Thus, in the following
+ example::
+
+ jqpublic@USC.EDU ls mail /local/kerberos/klist
+ jqpublic/secure@USC.EDU *
+ jqpublic/admin@USC.EDU
+
+ ``jqpublic@USC.EDU`` is only authorized to execute ``ls``,
+ ``mail`` and ``klist`` commands. ``jqpublic/secure@USC.EDU`` is
+ authorized to execute any command. ``jqpublic/admin@USC.EDU`` is
+ not authorized to execute any command. Note, that
+ ``jqpublic/admin@USC.EDU`` is authorized to execute the target
+ shell (regular ksu, without the **-e** option) but
+ ``jqpublic@USC.EDU`` is not.
+
+ The commands listed after the principal name must be either a full
+ path names or just the program name. In the second case,
+ **CMD_PATH** specifying the location of authorized programs must
+ be defined at the compilation time of ksu. Which command gets
+ executed?
+
+ If the source user is root or the target user is the source user
+ or the user is authorized to execute any command (``*`` entry)
+ then command can be either a full or a relative path leading to
+ the target program. Otherwise, the user must specify either a
+ full path or just the program name.
+
+**-a** *args*
+ Specify arguments to be passed to the target shell. Note that all
+ flags and parameters following -a will be passed to the shell,
+ thus all options intended for ksu must precede **-a**.
+
+ The **-a** option can be used to simulate the **-e** option if
+ used as follows::
+
+ -a -c [command [arguments]].
+
+ **-c** is interpreted by the c-shell to execute the command.
- **-l** *lifetime*
- option specifies the lifetime to be requested for the ticket; if this option is not specified, the default ticket lifetime
- (configured by each site) is used instead.
- **-r** *time*
- option specifies that the *RENEWABLE* option should be requested for the ticket, and specifies the desired total lifetime of the ticket.
-
- **-p**
- option specifies that the PROXIABLE option should be requested for the ticket.
-
- **-f**
- option specifies that the FORWARDABLE option should be requested for the ticket.
-
- **-e** *command* [args ...]
- *ksu* proceeds exactly the same as if it was invoked without the *-e* option,
- except instead of executing the target shell, *ksu* executes the specified command
- Example of usage::
-
- ksu bob -e ls -lag
-
- The authorization algorithm for *-e* is as follows:
-
- If the source user is root or source user == target user, no authorization takes place and the command is executed.
- If source user id != 0, and ~target_user/*.k5users* file does not exist, authorization fails.
- Otherwise, ~target_user/*.k5users* file must have an appropriate entry for target principal to get authorized.
-
- The *.k5users* file format:
-
- A single principal entry on each line that may be followed by a list of commands that the principal is authorized to execute.
- A principal name followed by a '\*' means that the user is authorized to execute any command. Thus, in the following example::
-
- jqpublic@USC.EDU ls mail /local/kerberos/klist
- jqpublic/secure@USC.EDU *
- jqpublic/admin@USC.EDU
-
- *jqpublic\@USC.EDU* is only authorized to execute *ls*, *mail* and *klist* commands.
- *jqpublic/secure\@USC.EDU* is authorized to execute any command.
- *jqpublic/admin\@USC.EDU* is not authorized to execute any command.
- Note, that *jqpublic/admin\@USC.EDU* is authorized to execute the target shell (regular *ksu*, without the *-e* option)
- but *jqpublic\@USC.EDU* is not.
-
- The commands listed after the principal name must be either a full path names or just the program name.
- In the second case, CMD_PATH specifying the location of authorized programs must be defined at the compilation time of *ksu*.
- Which command gets executed ?
-
- If the source user is *root* or the target user is the source user or the user is authorized to execute any command ('\*' entry)
- then command can be either a full or a relative path leading to the target program.
- Otherwise, the user must specify either a full path or just the program name.
-
- **-a** *args*
- Specify arguments to be passed to the target shell.
- Note: that all flags and parameters following -a will be passed to the shell,
- thus all options intended for *ksu* must precede *-a*.
+INSTALLATION INSTRUCTIONS
+-------------------------
- The *-a* option can be used to simulate the *-e* option if used as follows::
-
- -a -c [command [arguments]].
-
- *-c* is interpreted by the c-shell to execute the command.
+ksu can be compiled with the following four flags:
+**GET_TGT_VIA_PASSWD**
+ In case no appropriate tickets are found in the source cache, the
+ user will be prompted for a Kerberos password. The password is
+ then used to get a ticket granting ticket from the Kerberos
+ server. The danger of configuring ksu with this macro is if the
+ source user is logged in remotely and does not have a secure
+ channel, the password may get exposed.
-INSTALLATION INSTRUCTIONS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**PRINC_LOOK_AHEAD**
-*ksu* can be compiled with the following four flags:
+ During the resolution of the default principal name,
+ **PRINC_LOOK_AHEAD** enables ksu to find principal names in the
+ .k5users file as described in the OPTIONS section (see **-n**
+ option).
- **GET_TGT_VIA_PASSWD**
- In case no appropriate tickets are found in the source cache,
- the user will be prompted for a Kerberos password.
- The password is then used to get a ticket granting ticket from the Kerberos server.
- The danger of configuring *ksu* with this macro is if the source user is logged in remotely
- and does not have a secure channel, the password may get exposed.
+**CMD_PATH**
+ Specifies a list of directories containing programs that users are
+ authorized to execute (via .k5users file).
- **PRINC_LOOK_AHEAD**
- During the resolution of the default principal name, *PRINC_LOOK_AHEAD* enables *ksu* to find
- principal names in the *.k5users* file as described in the *OPTIONS* section (see *-n* option).
+**HAVE_GETUSERSHELL**
+ If the source user is non-root, ksu insists that the target user's
+ shell to be invoked is a "legal shell". *getusershell(3)* is
+ called to obtain the names of "legal shells". Note that the
+ target user's shell is obtained from the passwd file.
- **CMD_PATH**
- Specifies a list of directories containing programs that users are authorized to execute (via *.k5users* file).
+Sample configuration::
- **HAVE_GETUSERSHELL**
- If the source user is non-root, *ksu* insists that the target user's shell to be invoked is a "legal shell".
- *getusershell(3)* is called to obtain the names of "legal shells".
- Note that the target user's shell is obtained from the passwd file.
+ KSU_OPTS = -DGET_TGT_VIA_PASSWD -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin"
-SAMPLE CONFIGURATION
+ksu should be owned by root and have the set user id bit turned on.
- KSU_OPTS = -DGET_TGT_VIA_PASSWD -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin"
+ksu attempts to get a ticket for the end server just as Kerberized
+telnet and rlogin. Thus, there must be an entry for the server in the
+Kerberos database (e.g. ``host/nii.isi.edu@ISI.EDU``). The keytab
+file must be in an appropriate location.
-PERMISSIONS FOR KSU
- *ksu* should be owned by root and have the *set user id* bit turned on.
-END-SERVER ENTRY
- *ksu* attempts to get a ticket for the end server just as Kerberized telnet and rlogin.
- Thus, there must be an entry for the server in the Kerberos database (e.g. *host/nii.isi.edu\@ISI.EDU*).
- The keytab file must be in an appropriate location.
-
SIDE EFFECTS
-~~~~~~~~~~~~~~~
+------------
-*ksu* deletes all expired tickets from the source cache.
+ksu deletes all expired tickets from the source cache.
-AUTHOR OF KSU:
-~~~~~~~~~~~~~~~
-GENNADY (ARI) MEDVINSKY
+AUTHOR OF KSU
+-------------
+GENNADY (ARI) MEDVINSKY
kswitch - switch primary credential cache
=========================================
-
SYNOPSIS
~~~~~~~~
-**kswitch** {**-c** *cachename* | **-p** *principal*}
+**kswitch**
+{**-c** *cachename*\|\ **-p** *principal*}
+
DESCRIPTION
-~~~~~~~~~~~
+-----------
-*kswitch* makes the specified credential cache the primary cache for
-the collection, if a cache collection is available.
+kswitch makes the specified credential cache the primary cache for the
+collection, if a cache collection is available.
OPTIONS
-~~~~~~~
+-------
- **-c** *cachename*
- Directly specifies the credential cache to be made primary.
+**-c** *cachename*
+ Directly specifies the credential cache to be made primary.
- **-p** *principal*
- Causes the cache collection to be searched for a cache
- containing credentials for *principal*. If one is found,
- that collection is made primary.
+**-p** *principal*
+ Causes the cache collection to be searched for a cache containing
+ credentials for *principal*. If one is found, that collection is
+ made primary.
ENVIRONMENT
-~~~~~~~~~~~
+-----------
-*kswitch* uses the following environment variables:
+kswitch uses the following environment variables:
- **KRB5CCNAME**
- Location of the default Kerberos 5 credentials (ticket)
- cache, in the form *type*:*residual*. If no type prefix is
- present, the **FILE** type is assumed. The type of the
- default cache may determine the availability of a cache
- collection; for instance, a default cache of type **DIR**
- causes caches within the directory to be present in the
- collection.
+**KRB5CCNAME**
+ Location of the default Kerberos 5 credentials (ticket) cache, in
+ the form *type*:*residual*. If no type prefix is present, the
+ **FILE** type is assumed. The type of the default cache may
+ determine the availability of a cache collection; for instance, a
+ default cache of type **DIR** causes caches within the directory
+ to be present in the collection.
FILES
-~~~~~
+-----
-/tmp/krb5cc_[uid] - Default location of Kerberos 5 credentials cache ([*uid*] is the decimal UID of the user).
+``/tmp/krb5cc_[uid]``
+ Default location of Kerberos 5 credentials cache ([*uid*] is the
+ decimal UID of the user).
SEE ALSO
-~~~~~~~~
+--------
kinit(1), kdestroy(1), klist(1), kerberos(1)
kvno - print key version numbers of Kerberos principals
-===========================================================
+=======================================================
SYNOPSIS
-~~~~~~~~~~~~~~~
+--------
**kvno**
- [**-c** *ccache*]
- [**-e** *etype*]
- [**-q**]
- [**-h**]
- [**-P**]
- [**-S** *sname*]
- [**-U** *for_user*]
- *service1 service2* ...
+[**-c** *ccache*]
+[**-e** *etype*]
+[**-q**]
+[**-h**]
+[**-P**]
+[**-S** *sname*]
+[**-U** *for_user*]
+*service1 service2* ...
+
DESCRIPTION
-~~~~~~~~~~~~~~~
+-----------
+
+kvno acquires a service ticket for the specified Kerberos principals
+and prints out the key version numbers of each.
-*kvno* acquires a service ticket for the specified Kerberos principals and
-prints out the key version numbers of each.
OPTIONS
-~~~~~~~~~~~~~~~
+-------
- **-c** *ccache*
- Specifies the name of a credentials cache to use (if not the default)
+**-c** *ccache*
+ Specifies the name of a credentials cache to use (if not the
+ default)
- **-e** *etype*
- Specifies the enctype which will be requested for the session key of all
- the services named on the command line.
- This is useful in certain backward compatibility situations.
+**-e** *etype*
+ Specifies the enctype which will be requested for the session key
+ of all the services named on the command line. This is useful in
+ certain backward compatibility situations.
- **-q**
- Suppress printing
+**-q**
+ Suppress printing
- **-h**
- Prints a usage statement and exits
+**-h**
+ Prints a usage statement and exits
- **-P**
- Specifies that the *service1 service2* ... arguments are to be treated as
- services for which credentials should be acquired using constrained delegation.
- This option is only valid when used in conjunction with protocol transition.
+**-P**
+ Specifies that the *service1 service2* ... arguments are to be
+ treated as services for which credentials should be acquired using
+ constrained delegation. This option is only valid when used in
+ conjunction with protocol transition.
- **-S** *sname*
- Specifies that *krb5_sname_to_principal()* will be used to build principal names.
- If this flag is specified, the *service1 service2* ... arguments are interpreted as
- *hostnames* (rather than principal names),
- and *sname* is interpreted as the service name.
+**-S** *sname*
+ Specifies that *krb5_sname_to_principal()* will be used to build
+ principal names. If this flag is specified, the *service1
+ service2* ... arguments are interpreted as hostnames (rather than
+ principal names), and *sname* is interpreted as the service name.
+
+**-U** *for_user*
+ Specifies that protocol transition (S4U2Self) is to be used to
+ acquire a ticket on behalf of *for_user*. If constrained
+ delegation is not requested, the service name must match the
+ credentials cache client principal.
- **-U** *for_user*
- Specifies that protocol transition (S4U2Self) is to be used
- to acquire a ticket on behalf of *for_user*.
- If constrained delegation is not requested,
- the service name must match the credentials cache client principal.
ENVIRONMENT
-~~~~~~~~~~~~~~~
+-----------
+
+kvno uses the following environment variable:
-*kvno* uses the following environment variable:
+**KRB5CCNAME**
+ Location of the credentials (ticket) cache.
- **KRB5CCNAME** - Location of the credentials (ticket) cache.
FILES
-~~~~~~~~~~~~~~~
+-----
+
+``/tmp/krb5cc_[uid]``
+ Default location of the credentials cache ([*uid*] is the decimal
+ UID of the user).
-/tmp/krb5cc_[uid] - Default location of the credentials cache ([uid] is the decimal UID of the user).
SEE ALSO
-~~~~~~~~~~~~~~~
+--------
kinit(1), kdestroy(1)
-
-
.. _sclient(1):
-
-sclient
+sclient
=======
SYNOPSIS
------------
+--------
**sclient** *remotehost*
+
DESCRIPTION
--------------
+-----------
+
+sclient will contact a sample server :ref:`sserver(8)` and
+authenticate to it using Kerberos version 5 tickets, then display the
+server's response.
-*sclient* will contact a sample server :ref:`sserver(8)` and authenticate
-to it using Kerberos version 5 tickets, then display the server's response.
SEE ALSO
-----------
+--------
kinit(1), sserver(8)
-
.. _krb5-send-pr(1):
-
krb5-send-pr - send problem report (PR) to a central support site
-=======================================================================
+=================================================================
SYNOPSIS
------------
+--------
**krb5-send-pr**
-[ *site* ]
-[ **-f** *problem-report* ]
-[ **-t** *mail-address* ]
-[ **-P** ]
-[ **-L** ]
-[ **-s** *severity* ]
-[ **-c** *address* ]
-[ **--request-id** ]
-[ **-V** ]
+[*site*]
+[**-f** *problem-report*]
+[**-t** *mail-address*]
+[**-P**]
+[**-L**]
+[**-s** *severity*]
+[**-c** *address*]
+[**--request-id**]
+[**-V**]
DESCRIPTION
---------------
-
-*krb5-send-pr* is a tool used to submit problem reports (PRs) to a central support site.
-In most cases the correct *site* will be the default.
-This argument indicates the support site which is responsible
-for the category of problem involved.
-Some sites may use a local address as a default.
-*site* values are defined by using the aliases(5).
-
-*krb5-send-pr* invokes an editor on a problem report template
-(after trying to fill in some fields with reasonable default values).
-When you exit the editor, *krb5-send-pr* sends the completed form
-to the *Problem Report Management System* (**GNATS**) at a central support site.
-At the support site, the PR is assigned a unique number and is stored
-in the GNATS database according to its category and submitter-id.
-GNATS automatically replies with an acknowledgement,
+-----------
+
+krb5-send-pr is a tool used to submit problem reports (PRs) to a
+central support site. In most cases the correct site will be the
+default. This argument indicates the support site which is
+responsible for the category of problem involved. Some sites may use
+a local address as a default. *site* values are defined by using the
+aliases(5).
+
+krb5-send-pr invokes an editor on a problem report template (after
+trying to fill in some fields with reasonable default values). When
+you exit the editor, krb5-send-pr sends the completed form to the
+Problem Report Management System (**GNATS**) at a central support
+site. At the support site, the PR is assigned a unique number and is
+stored in the GNATS database according to its category and
+submitter-id. GNATS automatically replies with an acknowledgement,
citing the category and the PR number.
-To ensure that a PR is handled promptly, it should contain your (unique)
+To ensure that a PR is handled promptly, it should contain your (unique)
*submitter-id* and one of the available *categories* to identify the problem area.
(Use `krb5-send-pr -L` to see a list of categories.)
-The *krb5-send-pr* template at your site should already be customized
-with your *submitter-id* (running `install-sid submitter-id` to accomplish
-this is part of the installation procedures for *krb5-send-pr*).
-If this hasn't been done, see your system administrator for your *submitter-id*,
-or request one from your support site by invoking `krb5-send-pr --request-id`.
-If your site does not distinguish between different user sites,
-or if you are not affiliated with the support site, use `net` for this field.
+The krb5-send-pr template at your site should already be customized
+with your submitter-id (running ``install-sid submitter-id`` to
+accomplish this is part of the installation procedures for
+krb5-send-pr). If this hasn't been done, see your system
+administrator for your submitter-id, or request one from your support
+site by invoking ``krb5-send-pr --request-id``. If your site does not
+distinguish between different user sites, or if you are not affiliated
+with the support site, use ``net`` for this field.
-The more precise your problem description and the more complete your information,
-the faster your support team can solve your problems.
+The more precise your problem description and the more complete your
+information, the faster your support team can solve your problems.
OPTIONS
----------
+-------
**-f** *problem-report*
- Specify a file *problem-report* which already contains a complete problem report.
- *krb5-send-pr sends* the contents of the file without invoking the editor.
- If the value for problem-report is "-", then *krb5-send-pr* reads from standard input.
+ Specify a file *problem-report* which already contains a complete
+ problem report. krb5-send-pr sends the contents of the file
+ without invoking the editor. If the value for problem-report is
+ ``-``, then krb5-send-pr reads from standard input.
**-s** *severity*
- Give the problem report the severity *severity*.
+ Give the problem report the severity *severity*.
**-t** *mail-address*
- Change mail address at the support site for problem reports.
- The default mail-address is the address used for the default site.
- Use the site argument rather than this option in nearly all cases.
+ Change mail address at the support site for problem reports. The
+ default mail address is the address used for the default site.
+ Use the site argument rather than this option in nearly all cases.
**-c** *address*
- Put *address* in the *Cc:* header of the message.
+ Put *address* in the *Cc:* header of the message.
**-P**
- Print the form specified by the environment variable *PR_FORM* on standard output.
- If *PR_FORM* is not set, print the standard blank PR template. No mail is sent.
+ Print the form specified by the environment variable **PR_FORM**
+ on standard output. If **PR_FORM** is not set, print the standard
+ blank PR template. No mail is sent.
**-L**
- Print the list of available categories. No mail is sent.
+ Print the list of available categories. No mail is sent.
**--request-id**
- Sends mail to the default support site, or site if specified,
- with a request for your *submitter-id*.
- If you are not affiliated with site, use a *submitter-id* of `net`.
+ Sends mail to the default support site, or site if specified, with
+ a request for your submitter-id. If you are not affiliated with
+ site, use a submitter-id of ``net``.
**-V**
- Display the *krb5-send-pr* version number.
+ Display the krb5-send-pr version number.
+.. note:: Use krb5-send-pr to submit problem reports rather than
+ mailing them directly. Using both the template and
+ krb5-send-pr itself will help ensure all necessary
+ information will reach the support site.
-.. note:: Use *krb5-send-pr* to submit problem reports rather than mailing them directly.
- Using both the template and *krb5-send-pr* itself will help ensure all
- necessary information will reach the support site.
ENVIRONMENT
-------------
+-----------
-The environment variable *EDITOR* specifies the editor to invoke on the template.
-Default: *vi*.
+The environment variable **EDITOR** specifies the editor to invoke on
+the template. Default: ``vi``.
-If the environment variable *PR_FORM* is set, then its value is used as
-the file name of the template for your problem-report editing session.
-You can use this to start with a partially completed form
-(for example, a form with the identification fields already completed).
+If the environment variable **PR_FORM** is set, then its value is used
+as the file name of the template for your problem-report editing
+session. You can use this to start with a partially completed form
+(for example, a form with the identification fields already
+completed).
HOW TO FILL OUT A PROBLEM REPORT
----------------------------------
+--------------------------------
-Problem reports have to be in a particular form so that a program can
+Problem reports have to be in a particular form so that a program can
easily manage them. Please remember the following guidelines:
- - Describe only one problem with each problem report.
+* Describe only one problem with each problem report.
+
+* For follow-up mail, use the same subject line as the one in the
+ automatic acknowledgent. It consists of category, PR number and the
+ original synopsis line. This allows the support site to relate
+ several mail messages to a particular PR and to record them
+ automatically.
- - For follow-up mail, use the same subject line as the one
- in the automatic acknowledgent.
- It consists of category, PR number and the original synopsis line.
- This allows the support site to relate several mail messages
- to a particular PR and to record them automatically.
+* Please try to be as accurate as possible in the subject and/or
+ synopsis line.
- - Please try to be as accurate as possible in the subject and/or synopsis line.
+* The subject and the synopsis line are not confidential. This is
+ because open-bugs lists are compiled from them. Avoid confidential
+ information there.
- - The subject and the synopsis line are not confidential.
- This is because open-bugs lists are compiled from them.
- Avoid confidential information there.
+See the GNU Info file *krb5-send-pr.info* or the document
+Reporting Problems With krb5-send-pr for detailed information on reporting problems.
-See the GNU Info file *krb5-send-pr.info* or the document
-Reporting Problems With *krb5-send-pr* for detailed information on reporting problems.
HOW TO SUBMIT TEST CASES, CODE, ETC.
----------------------------------------
+------------------------------------
+
+Submit small code samples with the PR. Contact the support site for
+instructions on submitting larger test cases and problematic source
+code.
-Submit small code samples with the PR.
-Contact the support site for instructions on submitting larger test cases
-and problematic source code.
FILES
-----------
+-----
+
+``/tmp/p$$``
+ copy of PR used in editing session
-/tmp/p$$ copy of PR used in editing session
+``/tmp/pf$$``
+ copy of empty PR form, for testing purposes
-/tmp/pf$$ copy of empty PR form, for testing purposes
+``/tmp/pbad$$``
+ file for rejected PRs
-/tmp/pbad$$ file for rejected PRs
EMACS USER INTERFACE
----------------------
+--------------------
-An Emacs user interface for *krb5-send-pr* with completion of field values
-is part of the *krb5-send-pr* distribution (invoked with `M-x krb5-send-pr`).
-See the file *krb5-send-pr.info* or the ASCII file INSTALL in the top level
-directory of the distribution for configuration and installation information.
-The Emacs LISP template file is *krb5-send-pr-el.in* and is installed as *krb5-send-pr.el*.
+An Emacs user interface for krb5-send-pr with completion of field
+values is part of the krb5-send-pr distribution (invoked with ``M-x
+krb5-send-pr``). See the file krb5-send-pr.info or the ASCII file
+INSTALL in the top level directory of the distribution for
+configuration and installation information. The Emacs LISP template
+file is krb5-send-pr-el.in and is installed as krb5-send-pr.el.
INSTALLATION AND CONFIGURATION
---------------------------------
+------------------------------
+
+See krb5-send-pr.info or INSTALL for installation instructions.
-See *krb5-send-pr.info* or INSTALL for installation instructions.
SEE ALSO
------------
+--------
+
+Reporting Problems Using krb5-send-pr (also installed as the GNU Info
+file krb5-send-pr.info).
-Reporting Problems Using *krb5-send-pr* (also installed as the GNU Info file *krb5-send-pr.info*).
+gnats(l), query-pr(1), edit-pr(1), gnats(8), queue-pr(8), at-pr(8),
+mkcat(8), mkdist(8).
-gnats(l), query-pr(1), edit-pr(1), gnats(8), queue-pr(8), at-pr(8), mkcat(8), mkdist(8).
AUTHORS
------------
+-------
Jeffrey Osier, Brendan Kehoe, Jason Merrill, Heinz G. Seidl (Cygnus Support)
+
COPYING
---------
+-------
Copyright (c) 1992, 1993 Free Software Foundation, Inc.
-Permission is granted to make and distribute verbatim copies of this manual
-provided the copyright notice and this permission notice are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this manual
-under the conditions for verbatim copying, provided that the entire resulting
-derived work is distributed under the terms of a permission notice identical to this one.
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be included in translations approved
-by the Free Software Foundation instead of in the original English.
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be included in
+translations approved by the Free Software Foundation instead of in
+the original English.
.. _mitK5defaults:
MIT Kerberos defaults
-============================
-
+=====================
The list of the site- and OS- dependent configuration
--------------------------------------------------------
-
+-----------------------------------------------------
================================================== ============================================== =====================================
\ Default Environment
Path to Kerberos configuration file /etc/krb5.conf:SYSCONFDIR/krb5.conf KRB5_CONFIG
KDC configuration file LOCALSTATEDIR/krb5kdc/kdc.conf KRB5_KDC_PROFILE
The location of the default database LOCALSTATEDIR/krb5kdc/principal
- Master key stash file location and prefix LOCALSTATEDIR/krb5kdc/.k5.
+ Master key stash file location and prefix LOCALSTATEDIR/krb5kdc/.k5.
(e.g., /usr/local/var/krb5kdc/.k5.YOURREALM)
Admin Access Control List (ACL) file LOCALSTATEDIR/krb5kdc/krb5_adm.acl
Admin ACL file used by old admin server LOCALSTATEDIR/krb5kdc/kadm_old.acl
Base directory where plugins are located LIBDIR/krb5/plugins
Master key default enctype ENCTYPE_AES256_CTS_HMAC_SHA1_96
The name of the replay cache used by KDC dfl:krb5kdc_rcache KRB5RCACHETYPE, KRB5RCACHENAME
- KDC portname used for /etc/services or equiv. "kerberos"
+ KDC portname used for /etc/services or equiv. "kerberos"
KDC secondary portname for backward compatibility "kerberos-sec"
KDC default port 88
KDC default port for authentication 750
MAC OS specific
------------------
+---------------
============================================================ ================================
Path to Kerberos config file ~/Library/Preferences/edu.mit.Kerberos:/etc/krb5.conf:SYSCONFDIR/krb5.conf
Windows specific
-----------------------
+----------------
======================================= ====================================================
Kerberos config file name krb5.ini
Defaults for the KADM5 admin system
----------------------------------------
+-----------------------------------
====================================================================== ====================================== ==============================
\ Default Environment
====================================================================== ====================================== ==============================
Admin keytab file LOCALSTATEDIR/krb5kdc/kadm5.keytab KRB5_KTNAME
Admin ACL file that defines access rights to the Kerberos database LOCALSTATEDIR/krb5kdc/kadm5.acl
- Admin server default port 749
- Default supported enctype/salttype matrix aes256-cts-hmac-sha1-96:normal
- aes128-cts-hmac-sha1-96:normal
- des3-cbc-sha1:normal
+ Admin server default port 749
+ Default supported enctype/salttype matrix aes256-cts-hmac-sha1-96:normal
+ aes128-cts-hmac-sha1-96:normal
+ des3-cbc-sha1:normal
arcfour-hmac-md5:normal
Max datagram size 4096
Directory to store replay caches KRB5RCTMPDIR KRB5RCACHEDIR
krb5 *slave* support
------------------------------
+--------------------
============================================================ ======================================= ===============================
\ Default Environment
Site- and system-wide initialization for the code compiled on Linux or Solaris
------------------------------------------------------------------------------------
-
+------------------------------------------------------------------------------
+
===================== ============================== =================
BINDIR /usr/local/bin/
KRB5RCTMPDIR /var/tmp
SYSCONFDIR /usr/local/etc/
===================== ============================== =================
+
Report the problem
------------------
-
-Please, provide your feedback on this document at krb5-bugsmit.edu?subject=Documentation___krb5_implementation_features
-
+Please, provide your feedback on this document at
+krb5-bugsmit.edu?subject=Documentation___krb5_implementation_features
.. _mitK5features:
-MIT Kerberos features
-=======================================
-
+MIT Kerberos Features
+=====================
http://web.mit.edu/kerberos
-Quick facts
------------------------
+Quick facts
+-----------
====================================================== ======================================= =============================================================================
- Latest stable version 1.9.2
+ Latest stable version 1.9.2
Supported versions 1.7.3, 1.8.5, 1.9.2
- Release cycle 9 - 12 months
- Supported platforms/OS distributions Solaris
- - SPARC
- - x86_64/x86
- GNU/Linux
- - Debian x86_64/x86
- - Ubuntu x86_64/x86
- - RedHat x86_64/x86
- BSD
- - NetBSD x86_64/x86
- Crypto backends - OpenSSL 1.0\+ - http://www.openssl.org
- - builtin - MIT Kerberos native crypto library
- - NSS 3.12.9\+ - Mozilla's Network Security Services.
+ Release cycle 9 - 12 months
+ Supported platforms/OS distributions Solaris
+ - SPARC
+ - x86_64/x86
+ GNU/Linux
+ - Debian x86_64/x86
+ - Ubuntu x86_64/x86
+ - RedHat x86_64/x86
+ BSD
+ - NetBSD x86_64/x86
+ Crypto backends - OpenSSL 1.0\+ - http://www.openssl.org
+ - builtin - MIT Kerberos native crypto library
+ - NSS 3.12.9\+ - Mozilla's Network Security Services.
http://www.mozilla.org/projects/security/pki/nss
- Database backends - LDAP
- - DB2
- krb4 support < 1.8
+ Database backends - LDAP
+ - DB2
+ krb4 support < 1.8
DES support configurable http://k5wiki.kerberos.org/wiki/Projects/Disable_DES
GSS-API S4U extensions 1.8+ http://msdn.microsoft.com/en-us/library/cc246071
- - S4U2Proxy
- - S4U2Proxy
+ - S4U2Proxy
+ - S4U2Proxy
GSS-API naming extensions 1.8+ http://tools.ietf.org/html/draft-ietf-kitten-gssapi-naming-exts-11
-
+
GSS-API extensions for storing delegated credentials 1.8+ :rfc:`5588`
License :ref:`mitK5license`
====================================================== ======================================= =============================================================================
-
-
Interoperabiity
---------------
Microsoft
-~~~~~~~~~~
+~~~~~~~~~
Starting from version 1.7:
-* Follow client principal referrals in the client library when obtaining initial tickets.
+* Follow client principal referrals in the client library when
+ obtaining initial tickets.
* KDC can issue realm referrals for service principals based on domain names.
-* Extensions supporting DCE RPC, including three-leg GSS context setup and unencapsulated GSS tokens inside SPNEGO.
+* Extensions supporting DCE RPC, including three-leg GSS context setup
+ and unencapsulated GSS tokens inside SPNEGO.
-* Microsoft GSS_WrapEX, implemented using the gss_iov API, which is similar to the equivalent SSPI functionality. This is needed to support some instances of DCE RPC.
+* Microsoft GSS_WrapEX, implemented using the gss_iov API, which is
+ similar to the equivalent SSPI functionality. This is needed to
+ support some instances of DCE RPC.
-* NTLM recognition support in GSS-API, to facilitate dropping in an NTLM implementation for improved compatibility with older releases of Microsoft Windows.
+* NTLM recognition support in GSS-API, to facilitate dropping in an
+ NTLM implementation for improved compatibility with older releases
+ of Microsoft Windows.
-* KDC support for principal aliases, if the back end supports them. Currently, only the LDAP back end supports aliases.
+* KDC support for principal aliases, if the back end supports them.
+ Currently, only the LDAP back end supports aliases.
-* Support Microsoft set/change password (RFC 3244) protocol in kadmind.
+* Support Microsoft set/change password (RFC 3244) protocol in
+ kadmind.
-* Implement client and KDC support for GSS_C_DELEG_POLICY_FLAG, which allows a GSS application to request credential delegation only if permitted by KDC policy.
+* Implement client and KDC support for GSS_C_DELEG_POLICY_FLAG, which
+ allows a GSS application to request credential delegation only if
+ permitted by KDC policy.
Starting from version 1.8:
* Microsoft Services for User (S4U) compatibility`
+
Heimdal
-~~~~~~~~~~
+~~~~~~~
-* Support for reading Heimdal database starting from version 1.8
+* Support for reading Heimdal database starting from version 1.8
-Feature list
-~~~~~~~~~~~~~~~
+Feature list
+~~~~~~~~~~~~
=============================================== =========== ============================================
- \ Available Additional information
+ \ Available Additional information
=============================================== =========== ============================================
- Credentials delegation 1.7 :rfc:`5896`
+ Credentials delegation 1.7 :rfc:`5896`
Cross-realm authentication and referrals 1.7 http://tools.ietf.org/html/draft-ietf-krb-wg-kerberos-referrals-12
Master key migration 1.7 http://k5wiki.kerberos.org/wiki/Projects/Master_Key_Migration
- PKINIT 1.7 :rfc:`4556`
+ PKINIT 1.7 :rfc:`4556`
Anonymous PKINIT 1.8 :rfc:`6112` http://k5wiki.kerberos.org/wiki/Projects/Anonymous_pkinit
- Constrained delegation 1.8 http://k5wiki.kerberos.org/wiki/Projects/ConstrainedDelegation
- IAKERB 1.8 http://tools.ietf.org/html/draft-ietf-krb-wg-iakerb-02
- Heimdal bridge plugin for KDC backend 1.8
- Advance warning on password expiry 1.9
- Camellia encryption (CTS-CMAC mode) 1.9 experimental http://tools.ietf.org/html/draft-ietf-krb-wg-camellia-cts-00
+ Constrained delegation 1.8 http://k5wiki.kerberos.org/wiki/Projects/ConstrainedDelegation
+ IAKERB 1.8 http://tools.ietf.org/html/draft-ietf-krb-wg-iakerb-02
+ Heimdal bridge plugin for KDC backend 1.8
+ Advance warning on password expiry 1.9
+ Camellia encryption (CTS-CMAC mode) 1.9 experimental http://tools.ietf.org/html/draft-ietf-krb-wg-camellia-cts-00
KDC support for SecurID preauthentication 1.9 http://k5wiki.kerberos.org/wiki/Projects/SecurID_SAM_support
- kadmin over IPv6 1.9
- Trace logging 1.9 http://k5wiki.kerberos.org/wiki/Projects/Trace_logging
- GSSAPI/KRB5 multi-realm support
+ kadmin over IPv6 1.9
+ Trace logging 1.9 http://k5wiki.kerberos.org/wiki/Projects/Trace_logging
+ GSSAPI/KRB5 multi-realm support
Plugins to test password quality 1.9 http://k5wiki.kerberos.org/wiki/Projects/Password_quality_pluggable_interface
- Plugins to synchronize password changes 1.9
+ Plugins to synchronize password changes 1.9
Parallel KDC 1.9
- GS2 1.9 :rfc:`5801` :rfc:`5587` http://k5wiki.kerberos.org/wiki/Projects/GS2
- Purging old keys 1.9
- Naming extensions for delegation chain 1.9
- Password expiration API 1.9
- Windows client support (build-only) 1.9
- pre-auth mechanisms:
- - PW-SALT :rfc:`4120#section-5.2.7.3`
+ GS2 1.9 :rfc:`5801` :rfc:`5587` http://k5wiki.kerberos.org/wiki/Projects/GS2
+ Purging old keys 1.9
+ Naming extensions for delegation chain 1.9
+ Password expiration API 1.9
+ Windows client support (build-only) 1.9
+ pre-auth mechanisms:
+ - PW-SALT :rfc:`4120#section-5.2.7.3`
- ENC-TIMESTAMP :rfc:`4120#section-5.2.7.2`
- - SAM-2
- - FAST negotiation framework 1.8 :rfc:`6113`
- - PKINIT :rfc:`4556`
- - FX-COOKIE :rfc:`6113#section-5.2`
- - S4U-X509-USER 1.8 http://msdn.microsoft.com/en-us/library/cc246091
-
- PRNG
- - modularity: 1.9
- - Yarrow PRNG < 1.10
+ - SAM-2
+ - FAST negotiation framework 1.8 :rfc:`6113`
+ - PKINIT :rfc:`4556`
+ - FX-COOKIE :rfc:`6113#section-5.2`
+ - S4U-X509-USER 1.8 http://msdn.microsoft.com/en-us/library/cc246091
+
+ PRNG
+ - modularity: 1.9
+ - Yarrow PRNG < 1.10
- Fortuna PRNG 1.9 http://www.schneier.com/book-practical.html
- OS PRNG 1.10 OS's native PRNG
- Zero configuration
- IPv6 support in iprop
+ Zero configuration
+ IPv6 support in iprop
=============================================== =========== ============================================
+Feedback
+--------
-
-Report the problem
-------------------
-
-
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___krb5_implementation_features
-
-
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___krb5_implementation_features
.. _mitK5license:
MIT Kerberos License information
-===================================
-
+================================
.. include:: ../../NOTICE
:literal:
How to build this documentation from the source
-==================================================
+===============================================
Pre-requisites:
- - Sphinx 1.0.4 or higher (See http://sphinx.pocoo.org) with “autodoc” extension installed.
+* Sphinx 1.0.4 or higher (See http://sphinx.pocoo.org) with “autodoc”
+ extension installed.
How to build the Sphinx based documentation without references to API documentation
----------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------------
-To generate documentation in the *html* format, from the *trunk/doc/rst_source* run::
+To generate documentation in HTML format, from the
+``trunk/doc/rst_source`` run::
- sphinx-build . output_dir
+ sphinx-build . output_dir
To produce manpages run::
- sphinx-build -b man . output_dir
+ sphinx-build -b man . output_dir
-.. note:: The manpages output is controled by *man_pages* tag in the Sphinx configuration file
- *trunk/doc/rst_source/conf.py*.
+.. note:: The manpages output is controled by **man_pages** tag in the
+ Sphinx configuration file *trunk/doc/rst_source/conf.py*.
-How to deploy the Doxygen output in Sphinx project.
-----------------------------------------------------
+How to deploy the Doxygen output in Sphinx project
+--------------------------------------------------
-The text below is meant to give the instructions on how to incorporate MIT Kerberos API reference
-documentation into Sphinx document hierarchy.
-The Sphinx API documentation can be constructed without (:ref:`Part_A`) or with (:ref:`Part_B`) the bridge
-to the original Doxygen HTML output.
+The text below is meant to give the instructions on how to incorporate
+MIT Kerberos API reference documentation into Sphinx document
+hierarchy. The Sphinx API documentation can be constructed without
+(:ref:`Part_A`) or with (:ref:`Part_B`) the bridge to the original
+Doxygen HTML output.
Pre-requisites:
- - python 2.5+ with *Cheetah, lxml* and *xml* extension modules installed;
- - Doxygen documentation generator (http://www.doxygen.org) installed;
- - For "Part B" only:
- - Sphinx “doxylink” extension;
- - Doxygen HTML output
+* python 2.5+ with *Cheetah, lxml* and *xml* extension modules
+ installed;
+* Doxygen documentation generator (http://www.doxygen.org) installed;
+* For "Part B" only:
+ - Sphinx “doxylink” extension;
+ - Doxygen HTML output
.. _Part_A:
-Part A: Transforming Doxygen XML output into reStructuredText (rst) without the bridge to Doxygen HTML output.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Part A: Transforming Doxygen XML output into reStructuredText (rst) without the bridge to Doxygen HTML output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1. Delete lines containing text "Doxygen reference" from the template
+ files func_document.tmpl and type_document.tmpl located in
+ trunk/doc/rst_tools directory;
-1. Delete lines containing text "Doxygen reference" from the template files
- *func_document.tmpl* and *type_document.tmpl* located in trunk/doc/rst_tools directory;
+2. In the Doxygen configuration file (``trunk/src/Doxyfile``) set
+ **GENERATE_XML** flag to ``YES``. Generate Doxygen XML output. To
+ do so from the command line from the source directory
+ (``trunk/src``) run::
-2. In the Doxygen configuration file (trunk/src/Doxyfile) set *GENERATE_XML* flag to YES.
- Generate Doxygen XML output.
- To do so from the command line from the source directory (trunk/src) run::
+ doxygen
- doxygen
+ The **XML_OUTPUT** tag specifies the location of the Doxygen XML
+ output. The default location for this setup is ``trunk/out/xml``.
- The *XML_OUTPUT* tag specifies the location of the Doxygen XML output.
- The default location for this setup is *trunk/out/xml*.
+3. Suppose the Doxygen XML output is located in ``trunk/out/xml``
+ directory and the desired name for the reStructuredText output
+ directory is ``rst_dir``. From ``trunk/doc/rst_tools`` run::
-3. Suppose the Doxygen XML output is located in *trunk/out/xml* directory and
- the desired name for the reStructuredText output directory is *rst_dir*.
- From *trunk/doc/rst_tools* run::
+ python doxy.py –i ../../out/xml –o rst_dir –t func
- python doxy.py –i ../../out/xml –o rst_dir –t func
+ This will result in the storing the API function documentation
+ files in rst format in ``rst_dir``.
- This will result in the storing the API function documentation files in *rst* format in the *rst_dir*.
+ .. note:: The file names are constructed based on the function
+ name. For example, the file for krb5_build_principal()
+ will be krb5_build_principal.rst
- .. note:: The file names are constructed based on the function name.
- For example, the file for krb5_build_principal() will be krb5_build_principal.rst
+ Run::
- Run::
+ python doxy.py –i ../../out/xml –o rst_dir –t typedef
- python doxy.py –i ../../out/xml –o rst_dir –t typedef
+ It is similar to the API function conversion, but for data types.
+ The result will be stored under ``rst_dir/types`` directory
- It is similar to the API function conversion, but for data types. The result will be stored under *rst_dir/types* directory
+ Alternatively, running::
- Alternatively, running::
+ python doxy.py –i ../../out/xml –o rst_dir
- python doxy.py –i ../../out/xml –o rst_dir
+ or
- or
-
- python doxy.py –i ../../out/xml –o rst_dir -t all
+ python doxy.py –i ../../out/xml –o rst_dir -t all
- converts Doxygen XML output into reStructuredText format files both for API functions and data types;
+ converts Doxygen XML output into reStructuredText format files both
+ for API functions and data types;
-4. In *trunk/doc/krb_appldev/index.rst* add the following section to point to the API references::
+4. In ``trunk/doc/krb_appldev/index.rst`` add the following section to
+ point to the API references::
- .. toctree::
- :maxdepth: 1
+ .. toctree::
+ :maxdepth: 1
- refs/index.rst
+ refs/index.rst
-5. Copy the content of
+5. Copy the content of
- - *rst_dir* into *krb_appldev/refs/api* directory, and
-
- - *rst_dir/types* into *krb_appldev/refs/types* directory;
+ * ``rst_dir`` into ``krb_appldev/refs/api`` directory, and
+ * ``rst_dir/types`` into ``krb_appldev/refs/types`` directory;
-6. Rebuild Sphinx source. From the *trunk/doc/rst_source* run::
+6. Rebuild Sphinx source. From the ``trunk/doc/rst_source`` run::
- sphinx-build . output_dir
+ sphinx-build . output_dir
.. _Part_B:
-
-Part B: Bridge to Doxygen HTML output.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Part B: Bridge to Doxygen HTML output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Transform Doxygen XML output into reStructuredText.
- In src/Doxygen configuration file request generation of the tag file and XML output::
+ In src/Doxygen configuration file request generation of the tag
+ file and XML output::
GENERATE_TAGFILE = krb5doxy.tag
GENERATE_XML = YES
-2. Modify Sphinx conf.py file to point to the “doxylink” extension and Doxygen tag file::
+2. Modify Sphinx conf.py file to point to the “doxylink” extension and
+ Doxygen tag file::
- extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink']
- doxylink = { ' krb5doxy' : ('/tmp/krb5doxy.tag, ' doxy_html_dir ') }
+ extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink']
+ doxylink = { ' krb5doxy' : ('/tmp/krb5doxy.tag, ' doxy_html_dir ') }
where *doxy_html_dir* is the location of the Doxygen HTML output
-3. Continue with steps 3 - 6 of Part A.
-
-
-
+3. Continue with steps 3 - 6 of Part A.
About this project
-======================
+==================
.. toctree::
:maxdepth: 1
philosophy.rst
build_this.rst
-
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___relay_feedback
-
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___relay_feedback
Kerberos Documentation Relay
-=======================================
+============================
-
-Philosophy.
------------
+Philosophy
+----------
#. The documentation must be useful;
#. The documentation should be easy to maintain;
-#. The documentation should be examined to identify the approaches that do not work;
-
+#. The documentation should be examined to identify the approaches
+ that do not work;
-Process.
-------------
+Process
+-------
-#. The Work-To-Do list is created and updated based on the input from the community.
+#. The Work-To-Do list is created and updated based on the input from
+ the community.
#. Administrator supports the Work-To-Do list.
-#. Writer picks up the item from this list (such as specific API) and writes the documentation
-#. Committee reviews the documentation and recommends it to be accepted as-is or to be revised
-#. If the documentation needs revision, it is sent to the initial writer or someone else for completion
-#. Once Committee approves the document, it is proofread by the designated engineer
+#. Writer picks up the item from this list (such as specific API) and
+ writes the documentation
+#. Committee reviews the documentation and recommends it to be
+ accepted as-is or to be revised
+#. If the documentation needs revision, it is sent to the initial
+ writer or someone else for completion
+#. Once Committee approves the document, it is proofread by the
+ designated engineer
#. Documented is posted on the web
-Feedback and Comments.
-------------------------
-At the moment the comments should be sent via email to krb5-bugs@mit.edu. Normally, every document has an email link with the pre-constructed subject line similar to the following:
+Feedback and Comments
+---------------------
-Please, provide your feedback on this document at krb5-bugs@mit.edu?subject=Documentation___relay_feedback
+At the moment the comments should be sent via email to
+krb5-bugs@mit.edu. Normally, every document has an email link with
+the pre-constructed subject line similar to the following:
+Please, provide your feedback on this document at
+krb5-bugs@mit.edu?subject=Documentation___relay_feedback
projects / krb5.git / commitdiff