1 Database administration
2 =======================
4 A Kerberos database contains all of a realm's Kerberos principals,
5 their passwords, and other administrative information about each
6 principal. For the most part, you will use the :ref:`kdb5_util(8)`
7 program to manipulate the Kerberos database as a whole, and the
8 :ref:`kadmin(1)` program to make changes to the entries in the
9 database. (One notable exception is that users will use the
10 :ref:`kpasswd(1)` program to change their own passwords.) The kadmin
11 program has its own command-line interface, to which you type the
12 database administrating commands.
14 :ref:`kdb5_util(8)` provides a means to create, delete, load, or dump
15 a Kerberos database. It also contains commands to roll over the
16 database master key, and to stash a copy of the key so that the
17 :ref:`kadmind(8)` and :ref:`krb5kdc(8)` daemons can use the database
20 :ref:`kadmin(1)` provides for the maintenance of Kerberos principals,
21 password policies, and service key tables (keytabs). Normally it
22 operates as a network client using Kerberos authentication to
23 communicate with :ref:`kadmind(8)`, but there is also a variant, named
24 kadmin.local, which directly accesses the Kerberos database on the
25 local filesystem (or through LDAP). kadmin.local is necessary to set
26 up enough of the database to be able to use the remote version.
28 kadmin can authenticate to the admin server using the service
29 principal ``kadmin/admin`` or ``kadmin/HOST`` (where *HOST* is the
30 hostname of the admin server). If the credentials cache contains a
31 ticket for either service principal and the **-c** ccache option is
32 specified, that ticket is used to authenticate to KADM5. Otherwise,
33 the **-p** and **-k** options are used to specify the client Kerberos
34 principal name used to authenticate. Once kadmin has determined the
35 principal name, it requests a ``kadmin/admin`` Kerberos service ticket
36 from the KDC, and uses that service ticket to authenticate to KADM5.
38 See :ref:`kadmin(1)` for the available kadmin and kadmin.local
45 You can invoke :ref:`kadmin(1)` or kadmin.local with any of the
48 .. include:: admin_commands/kadmin_local.rst
49 :start-after: kadmin_synopsis:
50 :end-before: kadmin_synopsis_end:
54 .. include:: admin_commands/kadmin_local.rst
55 :start-after: _kadmin_options:
56 :end-before: _kadmin_options_end:
62 For the supported date-time formats see :ref:`getdate` section
69 Each entry in the Kerberos database contains a Kerberos principal and
70 the attributes and policies associated with that principal.
73 .. _add_mod_del_princs:
75 Adding, modifying and deleting principals
76 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
78 To add a principal to the database, use the :ref:`kadmin(1)`
79 **add_principal** command.
81 To modify attributes of a principal, use the kadmin
82 **modify_principal** command.
84 To delete a principal, use the kadmin **delete_principal** command.
86 .. include:: admin_commands/kadmin_local.rst
87 :start-after: _add_principal:
88 :end-before: _add_principal_end:
90 .. include:: admin_commands/kadmin_local.rst
91 :start-after: _modify_principal:
92 :end-before: _modify_principal_end:
94 .. include:: admin_commands/kadmin_local.rst
95 :start-after: _delete_principal:
96 :end-before: _delete_principal_end:
102 If you want to create a principal which is contained by a LDAP object,
103 all you need to do is::
105 kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com jennifer
106 No policy specified for "jennifer@ATHENA.MIT.EDU";
107 defaulting to no policy.
108 Enter password for principal jennifer@ATHENA.MIT.EDU: <= Type the password.
109 Re-enter password for principal jennifer@ATHENA.MIT.EDU: <=Type it again.
110 Principal "jennifer@ATHENA.MIT.EDU" created.
113 If you want to create a principal under a specific LDAP container and
114 link to an existing LDAP object, all you need to do is::
116 kadmin: addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=david,dc=example,dc=com david
117 No policy specified for "david@ATHENA.MIT.EDU";
118 defaulting to no policy.
119 Enter password for principal david@ATHENA.MIT.EDU: <= Type the password.
120 Re-enter password for principal david@ATHENA.MIT.EDU: <=Type it again.
121 Principal "david@ATHENA.MIT.EDU" created.
124 If you want to associate a ticket policy to a principal, all you need
127 kadmin: modprinc -x tktpolicy=userpolicy david
128 Principal "david@ATHENA.MIT.EDU" modified.
131 If, on the other hand, you want to set up an account that expires on
132 January 1, 2000, that uses a policy called "stduser", with a temporary
133 password (which you want the user to change immediately), you would
136 kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser +needchange
137 Enter password for principal david@ATHENA.MIT.EDU: <= Type the password.
138 Re-enter password for principal
139 david@ATHENA.MIT.EDU: <= Type it again.
140 Principal "david@ATHENA.MIT.EDU" created.
143 If you want to delete a principal::
145 kadmin: delprinc jennifer
146 Are you sure you want to delete the principal
147 "jennifer@ATHENA.MIT.EDU"? (yes/no): yes
148 Principal "jennifer@ATHENA.MIT.EDU" deleted.
149 Make sure that you have removed this principal from
150 all ACLs before reusing.
154 Retrieving information about a principal
155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157 To retrieve a listing of the attributes and/or policies associated
158 with a principal, use the :ref:`kadmin(1)` **get_principal** command.
160 To generate a listing of principals, use the kadmin
161 **list_principals** command.
163 .. include:: admin_commands/kadmin_local.rst
164 :start-after: _get_principal:
165 :end-before: _get_principal_end:
167 .. include:: admin_commands/kadmin_local.rst
168 :start-after: _list_principals:
169 :end-before: _list_principals_end:
175 To change a principal's password use the :ref:`kadmin(1)`
176 **change_password** command.
178 .. include:: admin_commands/kadmin_local.rst
179 :start-after: _change_password:
180 :end-before: _change_password_end:
184 Password changes through kadmin are subject to the same
185 password policies as would apply to password changes through
194 A policy is a set of rules governing passwords. Policies can dictate
195 minimum and maximum password lifetimes, minimum number of characters
196 and character classes a password must contain, and the number of old
197 passwords kept in the database.
200 Adding, modifying and deleting policies
201 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
203 To add a new policy, use the :ref:`kadmin(1)` **add_policy** command.
205 To modify attributes of a principal, use the kadmin **modify_policy**
208 To delete a policy, use the kadmin **delete_policy** command.
210 .. include:: admin_commands/kadmin_local.rst
211 :start-after: _add_policy:
212 :end-before: _add_policy_end:
214 .. include:: admin_commands/kadmin_local.rst
215 :start-after: _modify_policy:
216 :end-before: _modify_policy_end:
218 .. include:: admin_commands/kadmin_local.rst
219 :start-after: _delete_policy:
220 :end-before: _delete_policy_end:
224 You must cancel the policy from *all* principals before
225 deleting it. The *delete_policy* command will fail if the policy
226 is in use by any principals.
232 To retrieve a policy, use the :ref:`kadmin(1)` **get_policy** command.
234 You can retrieve the list of policies with the kadmin
235 **list_policies** command.
237 .. include:: admin_commands/kadmin_local.rst
238 :start-after: _get_policy:
239 :end-before: _get_policy_end:
241 .. include:: admin_commands/kadmin_local.rst
242 :start-after: _list_policies:
243 :end-before: _list_policies_end:
246 Policies and principals
247 ~~~~~~~~~~~~~~~~~~~~~~~
249 Policies can be applied to principals as they are created by using
250 the **-policy** flag to :ref:`add_principal`. Existing principals can
251 be modified by using the **-policy** or **-clearpolicy** flag to
252 :ref:`modify_principal`.
255 .. _updating_history_key:
257 Updating the history key
258 ~~~~~~~~~~~~~~~~~~~~~~~~
260 If a policy specifies a number of old keys kept of two or more, the
261 stored old keys are encrypted in a history key, which is found in the
262 key data of the ``kadmin/history`` principal.
264 Currently there is no support for proper rollover of the history key,
265 but you can change the history key (for example, to use a better
266 encryption type) at the cost of invalidating currently stored old
267 keys. To change the history key, run::
269 kadmin: change_password -randkey kadmin/history
271 This command will fail if you specify the **-keepold** flag. Only one
272 new history key will be created, even if you specify multiple key/salt
275 In the future, we plan to migrate towards encrypting old keys in the
276 master key instead of the history key, and implementing proper
277 rollover support for stored old keys.
285 Administrative privileges for the Kerberos database are stored in the
286 file :ref:`kadm5.acl(5)`.
290 A common use of an admin instance is so you can grant
291 separate permissions (such as administrator access to the
292 Kerberos database) to a separate Kerberos principal. For
293 example, the user ``joeadmin`` might have a principal for
294 his administrative use, called ``joeadmin/admin``. This
295 way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets
296 only when he actually needs to use those permissions.
301 Operations on the Kerberos database
302 -----------------------------------
304 The :ref:`kdb5_util(8)` command is the primary tool for administrating
305 the Kerberos database.
307 .. include:: admin_commands/kdb5_util.rst
308 :start-after: _kdb5_util_synopsis:
309 :end-before: _kdb5_util_synopsis_end:
313 .. include:: admin_commands/kdb5_util.rst
314 :start-after: _kdb5_util_options:
315 :end-before: _kdb5_util_options_end:
321 Dumping a Kerberos database to a file
322 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
324 To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)`
325 **dump** command on one of the KDCs.
327 .. include:: admin_commands/kdb5_util.rst
328 :start-after: _kdb5_util_dump:
329 :end-before: _kdb5_util_dump_end:
337 shell% kdb5_util dump dumpfile
340 shell% kbd5_util dump -verbose dumpfile
341 kadmin/admin@ATHENA.MIT.EDU
342 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
343 kadmin/history@ATHENA.MIT.EDU
345 kadmin/changepw@ATHENA.MIT.EDU
348 If you specify which principals to dump, you must use the full
349 principal, as in the following example::
351 shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU
352 kadmin/admin@ATHENA.MIT.EDU
356 Otherwise, the principals will not match those in the database and
359 shell% kdb5_util dump -verbose dumpfile K/M kadmin/admin
362 If you do not specify a dump file, kdb5_util will dump the database to
366 .. _restore_from_dump:
368 Restoring a Kerberos database from a dump file
369 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
371 To restore a Kerberos database dump from a file, use the
372 :ref:`kdb5_util(8)` **load** command on one of the KDCs.
374 .. include:: admin_commands/kdb5_util.rst
375 :start-after: _kdb5_util_load:
376 :end-before: _kdb5_util_load_end:
382 To dump a single principal and later load it, updating the database:
386 shell% kdb5_util dump dumpfile principal@REALM
389 shell% kdb5_util load -update dumpfile
395 If the database file exists, and the *-update* flag was not
396 given, *kdb5_util* will overwrite the existing database.
400 Using kdb5_util to dump and reload the principal database is
401 only necessary when upgrading from versions of krb5 prior
402 to 1.2.0---newer versions will use the existing database as-is.
407 Creating a stash file
408 ~~~~~~~~~~~~~~~~~~~~~
410 A stash file allows a KDC to authenticate itself to the database
411 utilities, such as :ref:`kadmind(8)`, :ref:`krb5kdc(8)`, and
414 To create a stash file, use the :ref:`kdb5_util(8)` **stash** command.
416 .. include:: admin_commands/kdb5_util.rst
417 :start-after: _kdb5_util_stash:
418 :end-before: _kdb5_util_stash_end:
424 shell% kdb5_util stash
425 kdb5_util: Cannot find/read stored master key while reading master key
426 kdb5_util: Warning: proceeding without master key
427 Enter KDC database master key: <= Type the KDC database master password.
430 If you do not specify a stash file, kdb5_util will stash the key in
431 the file specified in your :ref:`kdc.conf(5)` file.
434 Creating and destroying a Kerberos database
435 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
437 If you need to create a new Kerberos database, use the
438 :ref:`kdb5_util(8)` **create** command.
440 .. include:: admin_commands/kdb5_util.rst
441 :start-after: _kdb5_util_create:
442 :end-before: _kdb5_util_create_end:
444 If you need to destroy the current Kerberos database, use the
445 :ref:`kdb5_util(8)` **destroy** command.
447 .. include:: admin_commands/kdb5_util.rst
448 :start-after: _kdb5_util_destroy:
449 :end-before: _kdb5_util_destroy_end:
457 shell% kdb5_util -r ATHENA.MIT.EDU create -s
459 Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
460 master key name 'K/M@ATHENA.MIT.EDU'
461 You will be prompted for the database Master Password.
462 It is important that you NOT FORGET this password.
463 Enter KDC database master key: <= Type the master password.
464 Re-enter KDC database master key to verify: <= Type it again.
467 shell% kdb5_util -r ATHENA.MIT.EDU destroy
468 Deleting KDC database stored in '/usr/local/var/krb5kdc/principal', are you sure?
469 (type 'yes' to confirm)? <= yes
470 OK, deleting database '/usr/local/var/krb5kdc/principal'...
471 ** Database '/usr/local/var/krb5kdc/principal' destroyed.
475 .. _updating_master_key:
477 Updating the master key
478 ~~~~~~~~~~~~~~~~~~~~~~~
480 Starting with release 1.7, :ref:`kdb5_util(8)` allows the master key
481 to be changed using a rollover process, with minimal loss of
482 availability. To roll over the master key, follow these steps:
484 #. On the primary KDC, run ``kdb5_util list_mkeys`` to view the
485 current master key version number (KVNO). If you have never rolled
486 over the master key before, this will likely be version 1::
488 $ kdb5_util list_mkeys
489 Master keys for Principal: K/M@KRBTEST.COM
490 KVNO: 1, Enctype: aes256-cts-hmac-sha384-192, Active on: Thu Jan 01 00:00:00 UTC 1970 *
492 #. On the primary KDC, run ``kdb5_util use_mkey 1`` to ensure that a
493 master key activation list is present in the database. This step
494 is unnecessary in release 1.11.4 or later, or if the database was
495 initially created with release 1.7 or later.
497 #. On the primary KDC, run ``kdb5_util add_mkey -s`` to create a new
498 master key and write it to the stash file. Enter a secure password
499 when prompted. If this is the first time you are changing the
500 master key, the new key will have version 2. The new master key
501 will not be used until you make it active.
503 #. Propagate the database to all replica KDCs, either manually or by
504 waiting until the next scheduled propagation. If you do not have
505 any replica KDCs, you can skip this and the next step.
507 #. On each replica KDC, run ``kdb5_util list_mkeys`` to verify that
508 the new master key is present, and then ``kdb5_util stash`` to
509 write the new master key to the replica KDC's stash file.
511 #. On the primary KDC, run ``kdb5_util use_mkey 2`` to begin using the
512 new master key. Replace ``2`` with the version of the new master
513 key, as appropriate. You can optionally specify a date for the new
514 master key to become active; by default, it will become active
515 immediately. Prior to release 1.12, :ref:`kadmind(8)` must be
516 restarted for this change to take full effect.
518 #. On the primary KDC, run ``kdb5_util update_princ_encryption``.
519 This command will iterate over the database and re-encrypt all keys
520 in the new master key. If the database is large and uses DB2, the
521 primary KDC will become unavailable while this command runs, but
522 clients should fail over to replica KDCs (if any are present)
523 during this time period. In release 1.13 and later, you can
524 instead run ``kdb5_util -x unlockiter update_princ_encryption`` to
525 use unlocked iteration; this variant will take longer, but will
526 keep the database available to the KDC and kadmind while it runs.
528 #. Wait until the above changes have propagated to all replica KDCs
529 and until all running KDC and kadmind processes have serviced
530 requests using updated principal entries.
532 #. On the primary KDC, run ``kdb5_util purge_mkeys`` to clean up the
538 Operations on the LDAP database
539 -------------------------------
541 The :ref:`kdb5_ldap_util(8)` is the primary tool for administrating
542 the Kerberos LDAP database. It allows an administrator to manage
543 realms, Kerberos services (KDC and Admin Server) and ticket policies.
545 .. include:: admin_commands/kdb5_ldap_util.rst
546 :start-after: _kdb5_ldap_util_synopsis:
547 :end-before: _kdb5_ldap_util_synopsis_end:
551 .. include:: admin_commands/kdb5_ldap_util.rst
552 :start-after: _kdb5_ldap_util_options:
553 :end-before: _kdb5_ldap_util_options_end:
556 .. _ldap_create_realm:
558 Creating a Kerberos realm
559 ~~~~~~~~~~~~~~~~~~~~~~~~~
561 If you need to create a new realm, use the :ref:`kdb5_ldap_util(8)`
562 **create** command as follows.
564 .. include:: admin_commands/kdb5_ldap_util.rst
565 :start-after: _kdb5_ldap_util_create:
566 :end-before: _kdb5_ldap_util_create_end:
571 Modifying a Kerberos realm
572 ~~~~~~~~~~~~~~~~~~~~~~~~~~
574 If you need to modify a realm, use the :ref:`kdb5_ldap_util(8)`
575 **modify** command as follows.
577 .. include:: admin_commands/kdb5_ldap_util.rst
578 :start-after: _kdb5_ldap_util_modify:
579 :end-before: _kdb5_ldap_util_modify_end:
582 Destroying a Kerberos realm
583 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
585 If you need to destroy a Kerberos realm, use the
586 :ref:`kdb5_ldap_util(8)` **destroy** command as follows.
588 .. include:: admin_commands/kdb5_ldap_util.rst
589 :start-after: _kdb5_ldap_util_destroy:
590 :end-before: _kdb5_ldap_util_destroy_end:
593 Retrieving information about a Kerberos realm
594 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
596 If you need to display the attributes of a realm, use the
597 :ref:`kdb5_ldap_util(8)` **view** command as follows.
599 .. include:: admin_commands/kdb5_ldap_util.rst
600 :start-after: _kdb5_ldap_util_view:
601 :end-before: _kdb5_ldap_util_view_end:
604 Listing available Kerberos realms
605 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
607 If you need to display the list of the realms, use the
608 :ref:`kdb5_ldap_util(8)` **list** command as follows.
610 .. include:: admin_commands/kdb5_ldap_util.rst
611 :start-after: _kdb5_ldap_util_list:
612 :end-before: _kdb5_ldap_util_list_end:
617 Stashing service object's password
618 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
620 The :ref:`kdb5_ldap_util(8)` **stashsrvpw** command allows an
621 administrator to store the password of service object in a file. The
622 KDC and Administration server uses this password to authenticate to
625 .. include:: admin_commands/kdb5_ldap_util.rst
626 :start-after: _kdb5_ldap_util_stashsrvpw:
627 :end-before: _kdb5_ldap_util_stashsrvpw_end:
630 Ticket Policy operations
631 ~~~~~~~~~~~~~~~~~~~~~~~~
633 Creating a Ticket Policy
634 ########################
636 To create a new ticket policy in directory , use the
637 :ref:`kdb5_ldap_util(8)` **create_policy** command. Ticket policy
638 objects are created under the realm container.
640 .. include:: admin_commands/kdb5_ldap_util.rst
641 :start-after: _kdb5_ldap_util_create_policy:
642 :end-before: _kdb5_ldap_util_create_policy_end:
645 Modifying a Ticket Policy
646 #########################
648 To modify a ticket policy in directory, use the
649 :ref:`kdb5_ldap_util(8)` **modify_policy** command.
651 .. include:: admin_commands/kdb5_ldap_util.rst
652 :start-after: _kdb5_ldap_util_modify_policy:
653 :end-before: _kdb5_ldap_util_modify_policy_end:
656 Retrieving Information About a Ticket Policy
657 ############################################
659 To display the attributes of a ticket policy, use the
660 :ref:`kdb5_ldap_util(8)` **view_policy** command.
662 .. include:: admin_commands/kdb5_ldap_util.rst
663 :start-after: _kdb5_ldap_util_view_policy:
664 :end-before: _kdb5_ldap_util_view_policy_end:
667 Destroying a Ticket Policy
668 ##########################
670 To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)`
671 **destroy_policy** command.
673 .. include:: admin_commands/kdb5_ldap_util.rst
674 :start-after: _kdb5_ldap_util_destroy_policy:
675 :end-before: _kdb5_ldap_util_destroy_policy_end:
678 Listing available Ticket Policies
679 #################################
681 To list the name of ticket policies in a realm, use the
682 :ref:`kdb5_ldap_util(8)` **list_policy** command.
684 .. include:: admin_commands/kdb5_ldap_util.rst
685 :start-after: _kdb5_ldap_util_list_policy:
686 :end-before: _kdb5_ldap_util_list_policy_end:
691 Cross-realm authentication
692 --------------------------
694 In order for a KDC in one realm to authenticate Kerberos users in a
695 different realm, it must share a key with the KDC in the other realm.
696 In both databases, there must be krbtgt service principals for both realms.
697 For example, if you need to do cross-realm authentication between the realms
698 ``ATHENA.MIT.EDU`` and ``EXAMPLE.COM``, you would need to add the
699 principals ``krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU`` and
700 ``krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM`` to both databases.
701 These principals must all have the same passwords, key version
702 numbers, and encryption types; this may require explicitly setting
703 the key version number with the **-kvno** option.
705 In the ATHENA.MIT.EDU and EXAMPLE.COM cross-realm case, the administrators
706 would run the following commands on the KDCs in both realms::
708 shell%: kadmin.local -e "aes256-cts:normal"
709 kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM
710 Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
711 Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
712 kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
713 Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
714 Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
719 Even if most principals in a realm are generally created
720 with the **requires_preauth** flag enabled, this flag is not
721 desirable on cross-realm authentication keys because doing
722 so makes it impossible to disable preauthentication on a
723 service-by-service basis. Disabling it as in the example
724 above is recommended.
728 It is very important that these principals have good
729 passwords. MIT recommends that TGT principal passwords be
730 at least 26 characters of random ASCII text.
733 .. _changing_krbtgt_key:
735 Changing the krbtgt key
736 -----------------------
738 A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the
739 principal ``krbtgt/REALM``. The key for this principal is created
740 when the Kerberos database is initialized and need not be changed.
741 However, it will only have the encryption types supported by the KDC
742 at the time of the initial database creation. To allow use of newer
743 encryption types for the TGT, this key has to be changed.
745 Changing this key using the normal :ref:`kadmin(1)`
746 **change_password** command would invalidate any previously issued
747 TGTs. Therefore, when changing this key, normally one should use the
748 **-keepold** flag to change_password to retain the previous key in the
749 database as well as the new key. For example::
751 kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
755 After issuing this command, the old key is still valid
756 and is still vulnerable to (for instance) brute force
757 attacks. To completely retire an old key or encryption
758 type, run the kadmin **purgekeys** command to delete keys
759 with older kvnos, ideally first making sure that all
760 tickets issued with the old keys have expired.
762 Only the first krbtgt key of the newest key version is used to encrypt
763 ticket-granting tickets. However, the set of encryption types present
764 in the krbtgt keys is used by default to determine the session key
765 types supported by the krbtgt service (see
766 :ref:`session_key_selection`). Because non-MIT Kerberos clients
767 sometimes send a limited set of encryption types when making AS
768 requests, it can be important for the krbtgt service to support
769 multiple encryption types. This can be accomplished by giving the
770 krbtgt principal multiple keys, which is usually as simple as not
771 specifying any **-e** option when changing the krbtgt key, or by
772 setting the **session_enctypes** string attribute on the krbtgt
773 principal (see :ref:`set_string`).
775 Due to a bug in releases 1.8 through 1.13, renewed and forwarded
776 tickets may not work if the original ticket was obtained prior to a
777 krbtgt key change and the modified ticket is obtained afterwards.
778 Upgrading the KDC to release 1.14 or later will correct this bug.
783 Incremental database propagation
784 --------------------------------
789 At some very large sites, dumping and transmitting the database can
790 take more time than is desirable for changes to propagate from the
791 primary KDC to the replica KDCs. The incremental propagation support
792 added in the 1.7 release is intended to address this.
794 With incremental propagation enabled, all programs on the primary KDC
795 that change the database also write information about the changes to
796 an "update log" file, maintained as a circular buffer of a certain
797 size. A process on each replica KDC connects to a service on the
798 primary KDC (currently implemented in the :ref:`kadmind(8)` server) and
799 periodically requests the changes that have been made since the last
800 check. By default, this check is done every two minutes.
802 Incremental propagation uses the following entries in the per-realm
803 data in the KDC config file (See :ref:`kdc.conf(5)`):
805 ====================== =============== ===========================================
806 iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*.
807 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.
808 iprop_replica_poll *time interval* Indicates how often the replica should poll the primary KDC for changes to the database. The default is two minutes.
809 iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both primary and replica configuration files.
810 iprop_resync_timeout *integer* Specifies the number of seconds to wait for a full propagation to complete. This is optional on replica configurations. Defaults to 300 seconds (5 minutes).
811 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(5)`, 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.)
812 ====================== =============== ===========================================
814 Both primary and replica sides must have a principal named
815 ``kiprop/hostname`` (where *hostname* is the lowercase,
816 fully-qualified, canonical name for the host) registered in the
817 Kerberos database, and have keys for that principal stored in the
818 default keytab file (|keytab|). The ``kiprop/hostname`` principal may
819 have been created automatically for the primary KDC, but it must
820 always be created for replica KDCs.
822 On the primary KDC side, the ``kiprop/hostname`` principal must be
823 listed in the kadmind ACL file :ref:`kadm5.acl(5)`, and given the
824 **p** privilege (see :ref:`privileges`).
826 On the replica KDC side, :ref:`kpropd(8)` should be run. When
827 incremental propagation is enabled, it will connect to the kadmind on
828 the primary KDC and start requesting updates.
830 The normal kprop mechanism is disabled by the incremental propagation
831 support. However, if the replica has been unable to fetch changes
832 from the primary KDC for too long (network problems, perhaps), the log
833 on the primary may wrap around and overwrite some of the updates that
834 the replica has not yet retrieved. In this case, the replica will
835 instruct the primary KDC to dump the current database out to a file
836 and invoke a one-time kprop propagation, with special options to also
837 convey the point in the update log at which the replica should resume
838 fetching incremental updates. Thus, all the keytab and ACL setup
839 previously described for kprop propagation is still needed.
841 If an environment has a large number of replicas, it may be desirable
842 to arrange them in a hierarchy instead of having the primary serve
843 updates to every replica. To do this, run ``kadmind -proponly`` on
844 each intermediate replica, and ``kpropd -A upstreamhostname`` on
845 downstream replicas to direct each one to the appropriate upstream
848 There are several known restrictions in the current implementation:
850 - The incremental update protocol does not transport changes to policy
851 objects. Any policy changes on the primary will result in full
852 resyncs to all replicas.
853 - The replica's KDB module must support locking; it cannot be using the
855 - The primary and replica must be able to initiate TCP connections in
856 both directions, without an intervening NAT.
859 Sun/MIT incremental propagation differences
860 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
862 Sun donated the original code for supporting incremental database
863 propagation to MIT. Some changes have been made in the MIT source
864 tree that will be visible to administrators. (These notes are based
865 on Sun's patches. Changes to Sun's implementation since then may not
868 The Sun config file support looks for ``sunw_dbprop_enable``,
869 ``sunw_dbprop_master_ulogsize``, and ``sunw_dbprop_slave_poll``.
871 The incremental propagation service is implemented as an ONC RPC
872 service. In the Sun implementation, the service is registered with
873 rpcbind (also known as portmapper) and the client looks up the port
874 number to contact. In the MIT implementation, where interaction with
875 some modern versions of rpcbind doesn't always work well, the port
876 number must be specified in the config file on both the primary and
879 The Sun implementation hard-codes pathnames in ``/var/krb5`` for the
880 update log and the per-replica kprop dump files. In the MIT
881 implementation, the pathname for the update log is specified in the
882 config file, and the per-replica dump files are stored in
883 |kdcdir|\ ``/replica_datatrans_hostname``.