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/HOST`` (where *HOST* is the hostname of the admin
30 server) or ``kadmin/admin``. 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 WARNING: 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 WARNING: 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 the history key
256 ~~~~~~~~~~~~~~~~~~~~~~~~
258 If a policy specifies a number of old keys kept of two or more, the
259 stored old keys are encrypted in a history key, which is found in the
260 key data of the ``kadmin/history`` principal.
262 Currently there is no support for proper rollover of the history key,
263 but you can change the history key (for example, to use a better
264 encryption type) at the cost of invalidating currently stored old
265 keys. To change the history key, run::
267 kadmin: change_password -randkey kadmin/history
269 This command will fail if you specify the **-keepold** flag. Only one
270 new history key will be created, even if you specify multiple key/salt
273 In the future, we plan to migrate towards encrypting old keys in the
274 master key instead of the history key, and implementing proper
275 rollover support for stored old keys.
283 Administrative privileges for the Kerberos database are stored in the
284 file :ref:`kadm5.acl(5)`.
288 A common use of an admin instance is so you can grant
289 separate permissions (such as administrator access to the
290 Kerberos database) to a separate Kerberos principal. For
291 example, the user ``joeadmin`` might have a principal for
292 his administrative use, called ``joeadmin/admin``. This
293 way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets
294 only when he actually needs to use those permissions.
299 Operations on the Kerberos database
300 -----------------------------------
302 The :ref:`kdb5_util(8)` command is the primary tool for administrating
303 the Kerberos database.
305 .. include:: admin_commands/kdb5_util.rst
306 :start-after: _kdb5_util_synopsis:
307 :end-before: _kdb5_util_synopsis_end:
311 .. include:: admin_commands/kdb5_util.rst
312 :start-after: _kdb5_util_options:
313 :end-before: _kdb5_util_options_end:
319 Dumping a Kerberos database to a file
320 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
322 To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)`
323 **dump** command on one of the KDCs.
325 .. include:: admin_commands/kdb5_util.rst
326 :start-after: _kdb5_util_dump:
327 :end-before: _kdb5_util_dump_end:
335 shell% kdb5_util dump dumpfile
338 shell% kbd5_util dump -verbose dumpfile
339 kadmin/admin@ATHENA.MIT.EDU
340 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
341 kadmin/history@ATHENA.MIT.EDU
343 kadmin/changepw@ATHENA.MIT.EDU
346 If you specify which principals to dump, you must use the full
347 principal, as in the following example::
349 shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU
350 kadmin/admin@ATHENA.MIT.EDU
354 Otherwise, the principals will not match those in the database and
357 shell% kdb5_util dump -verbose dumpfile K/M kadmin/admin
360 If you do not specify a dump file, kdb5_util will dump the database to
364 .. _restore_from_dump:
366 Restoring a Kerberos database from a dump file
367 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
369 To restore a Kerberos database dump from a file, use the
370 :ref:`kdb5_util(8)` **load** command on one of the KDCs.
372 .. include:: admin_commands/kdb5_util.rst
373 :start-after: _kdb5_util_load:
374 :end-before: _kdb5_util_load_end:
380 To dump a single principal and later load it, updating the database:
384 shell% kdb5_util dump dumpfile principal@REALM
387 shell% kdb5_util load -update dumpfile
393 If the database file exists, and the *-update* flag was not
394 given, *kdb5_util* will overwrite the existing database.
396 Using kdb5_util to upgrade a master KDC from krb5 1.1.x:
400 shell% kdb5_util dump old-kdb-dump
401 shell% kdb5_util dump -ov old-kdb-dump.ov
402 [Create a new KDC installation, using the old stash file/master password]
403 shell% kdb5_util load old-kdb-dump
404 shell% kdb5_util load -update old-kdb-dump.ov
406 The use of old-kdb-dump.ov for an extra dump and load is necessary
407 to preserve per-principal policy information, which is not included in
408 the default dump format of krb5 1.1.x.
412 Using kdb5_util to dump and reload the principal database is
413 only necessary when upgrading from versions of krb5 prior
414 to 1.2.0---newer versions will use the existing database as-is.
419 Creating a stash file
420 ~~~~~~~~~~~~~~~~~~~~~
422 A stash file allows a KDC to authenticate itself to the database
423 utilities, such as :ref:`kadmind(8)`, :ref:`krb5kdc(8)`, and
426 To create a stash file, use the :ref:`kdb5_util(8)` **stash** command.
428 .. include:: admin_commands/kdb5_util.rst
429 :start-after: _kdb5_util_stash:
430 :end-before: _kdb5_util_stash_end:
436 shell% kdb5_util stash
437 kdb5_util: Cannot find/read stored master key while reading master key
438 kdb5_util: Warning: proceeding without master key
439 Enter KDC database master key: <= Type the KDC database master password.
442 If you do not specify a stash file, kdb5_util will stash the key in
443 the file specified in your :ref:`kdc.conf(5)` file.
446 Creating and destroying a Kerberos database
447 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
449 If you need to create a new Kerberos database, use the
450 :ref:`kdb5_util(8)` **create** command.
452 .. include:: admin_commands/kdb5_util.rst
453 :start-after: _kdb5_util_create:
454 :end-before: _kdb5_util_create_end:
456 If you need to destroy the current Kerberos database, use the
457 :ref:`kdb5_util(8)` **destroy** command.
459 .. include:: admin_commands/kdb5_util.rst
460 :start-after: _kdb5_util_destroy:
461 :end-before: _kdb5_util_destroy_end:
469 shell% kdb5_util -r ATHENA.MIT.EDU create -s
471 Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
472 master key name 'K/M@ATHENA.MIT.EDU'
473 You will be prompted for the database Master Password.
474 It is important that you NOT FORGET this password.
475 Enter KDC database master key: <= Type the master password.
476 Re-enter KDC database master key to verify: <= Type it again.
479 shell% kdb5_util -r ATHENA.MIT.EDU destroy
480 Deleting KDC database stored in '/usr/local/var/krb5kdc/principal', are you sure?
481 (type 'yes' to confirm)? <= yes
482 OK, deleting database '/usr/local/var/krb5kdc/principal'...
483 ** Database '/usr/local/var/krb5kdc/principal' destroyed.
487 Updating the master key
488 ~~~~~~~~~~~~~~~~~~~~~~~
490 Starting with release 1.7, :ref:`kdb5_util(8)` allows the master key
491 to be changed using a rollover process, with minimal loss of
492 availability. To roll over the master key, follow these steps:
494 #. On the master KDC, run ``kdb5_util list_mkeys`` to view the current
495 master key version number (KVNO). If you have never rolled over
496 the master key before, this will likely be version 1::
498 $ kdb5_util list_mkeys
499 Master keys for Principal: K/M@KRBTEST.COM
500 KVNO: 1, Enctype: des-cbc-crc, Active on: Wed Dec 31 19:00:00 EST 1969 *
502 #. On the master KDC, run ``kdb5_util use_mkey 1`` to ensure that a
503 master key activation list is present in the database. This step
504 is unnecessary in release 1.11.4 or later, or if the database was
505 initially created with release 1.7 or later.
507 #. On the master KDC, run ``kdb5_util add_mkey -s`` to create a new
508 master key and write it to the stash file. Enter a secure password
509 when prompted. If this is the first time you are changing the
510 master key, the new key will have version 2. The new master key
511 will not be used until you make it active.
513 #. Propagate the database to all replica KDCs, either manually or by
514 waiting until the next scheduled propagation. If you do not have
515 any replica KDCs, you can skip this and the next step.
517 #. On each replica KDC, run ``kdb5_util list_mkeys`` to verify that
518 the new master key is present, and then ``kdb5_util stash`` to
519 write the new master key to the replica KDC's stash file.
521 #. On the master KDC, run ``kdb5_util use_mkey 2`` to begin using the
522 new master key. Replace ``2`` with the version of the new master
523 key, as appropriate. You can optionally specify a date for the new
524 master key to become active; by default, it will become active
525 immediately. Prior to release 1.12, :ref:`kadmind(8)` must be
526 restarted for this change to take full effect.
528 #. On the master KDC, run ``kdb5_util update_princ_encryption``. This
529 command will iterate over the database and re-encrypt all keys in
530 the new master key. If the database is large and uses DB2, the
531 master KDC will become unavailable while this command runs, but
532 clients should fail over to replica KDCs (if any are present)
533 during this time period. In release 1.13 and later, you can
534 instead run ``kdb5_util -x unlockiter update_princ_encryption`` to
535 use unlocked iteration; this variant will take longer, but will
536 keep the database available to the KDC and kadmind while it runs.
538 #. Wait until the above changes have propagated to all replica KDCs
539 and until all running KDC and kadmind processes have serviced
540 requests using updated principal entries.
542 #. On the master KDC, run ``kdb5_util purge_mkeys`` to clean up the
548 Operations on the LDAP database
549 -------------------------------
551 The :ref:`kdb5_ldap_util(8)` is the primary tool for administrating
552 the Kerberos LDAP database. It allows an administrator to manage
553 realms, Kerberos services (KDC and Admin Server) and ticket policies.
555 .. include:: admin_commands/kdb5_ldap_util.rst
556 :start-after: _kdb5_ldap_util_synopsis:
557 :end-before: _kdb5_ldap_util_synopsis_end:
561 .. include:: admin_commands/kdb5_ldap_util.rst
562 :start-after: _kdb5_ldap_util_options:
563 :end-before: _kdb5_ldap_util_options_end:
566 .. _ldap_create_realm:
568 Creating a Kerberos realm
569 ~~~~~~~~~~~~~~~~~~~~~~~~~
571 If you need to create a new realm, use the :ref:`kdb5_ldap_util(8)`
572 **create** command as follows.
574 .. include:: admin_commands/kdb5_ldap_util.rst
575 :start-after: _kdb5_ldap_util_create:
576 :end-before: _kdb5_ldap_util_create_end:
581 Modifying a Kerberos realm
582 ~~~~~~~~~~~~~~~~~~~~~~~~~~
584 If you need to modify a realm, use the :ref:`kdb5_ldap_util(8)`
585 **modify** command as follows.
587 .. include:: admin_commands/kdb5_ldap_util.rst
588 :start-after: _kdb5_ldap_util_modify:
589 :end-before: _kdb5_ldap_util_modify_end:
592 Destroying a Kerberos realm
593 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
595 If you need to destroy a Kerberos realm, use the
596 :ref:`kdb5_ldap_util(8)` **destroy** command as follows.
598 .. include:: admin_commands/kdb5_ldap_util.rst
599 :start-after: _kdb5_ldap_util_destroy:
600 :end-before: _kdb5_ldap_util_destroy_end:
603 Retrieving information about a Kerberos realm
604 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
606 If you need to display the attributes of a realm, use the
607 :ref:`kdb5_ldap_util(8)` **view** command as follows.
609 .. include:: admin_commands/kdb5_ldap_util.rst
610 :start-after: _kdb5_ldap_util_view:
611 :end-before: _kdb5_ldap_util_view_end:
614 Listing available Kerberos realms
615 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
617 If you need to display the list of the realms, use the
618 :ref:`kdb5_ldap_util(8)` **list** command as follows.
620 .. include:: admin_commands/kdb5_ldap_util.rst
621 :start-after: _kdb5_ldap_util_list:
622 :end-before: _kdb5_ldap_util_list_end:
627 Stashing service object's password
628 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
630 The :ref:`kdb5_ldap_util(8)` **stashsrvpw** command allows an
631 administrator to store the password of service object in a file. The
632 KDC and Administration server uses this password to authenticate to
635 .. include:: admin_commands/kdb5_ldap_util.rst
636 :start-after: _kdb5_ldap_util_stashsrvpw:
637 :end-before: _kdb5_ldap_util_stashsrvpw_end:
640 Ticket Policy operations
641 ~~~~~~~~~~~~~~~~~~~~~~~~
643 Creating a Ticket Policy
644 ########################
646 To create a new ticket policy in directory , use the
647 :ref:`kdb5_ldap_util(8)` **create_policy** command. Ticket policy
648 objects are created under the realm container.
650 .. include:: admin_commands/kdb5_ldap_util.rst
651 :start-after: _kdb5_ldap_util_create_policy:
652 :end-before: _kdb5_ldap_util_create_policy_end:
655 Modifying a Ticket Policy
656 #########################
658 To modify a ticket policy in directory, use the
659 :ref:`kdb5_ldap_util(8)` **modify_policy** command.
661 .. include:: admin_commands/kdb5_ldap_util.rst
662 :start-after: _kdb5_ldap_util_modify_policy:
663 :end-before: _kdb5_ldap_util_modify_policy_end:
666 Retrieving Information About a Ticket Policy
667 ############################################
669 To display the attributes of a ticket policy, use the
670 :ref:`kdb5_ldap_util(8)` **view_policy** command.
672 .. include:: admin_commands/kdb5_ldap_util.rst
673 :start-after: _kdb5_ldap_util_view_policy:
674 :end-before: _kdb5_ldap_util_view_policy_end:
677 Destroying a Ticket Policy
678 ##########################
680 To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)`
681 **destroy_policy** command.
683 .. include:: admin_commands/kdb5_ldap_util.rst
684 :start-after: _kdb5_ldap_util_destroy_policy:
685 :end-before: _kdb5_ldap_util_destroy_policy_end:
688 Listing available Ticket Policies
689 #################################
691 To list the name of ticket policies in a realm, use the
692 :ref:`kdb5_ldap_util(8)` **list_policy** command.
694 .. include:: admin_commands/kdb5_ldap_util.rst
695 :start-after: _kdb5_ldap_util_list_policy:
696 :end-before: _kdb5_ldap_util_list_policy_end:
701 Cross-realm authentication
702 --------------------------
704 In order for a KDC in one realm to authenticate Kerberos users in a
705 different realm, it must share a key with the KDC in the other realm.
706 In both databases, there must be krbtgt service principals for both realms.
707 For example, if you need to do cross-realm authentication between the realms
708 ``ATHENA.MIT.EDU`` and ``EXAMPLE.COM``, you would need to add the
709 principals ``krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU`` and
710 ``krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM`` to both databases.
711 These principals must all have the same passwords, key version
712 numbers, and encryption types; this may require explicitly setting
713 the key version number with the **-kvno** option.
715 In the ATHENA.MIT.EDU and EXAMPLE.COM cross-realm case, the administrators
716 would run the following commands on the KDCs in both realms::
718 shell%: kadmin.local -e "aes256-cts:normal"
719 kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM
720 Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
721 Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
722 kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
723 Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
724 Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
729 Even if most principals in a realm are generally created
730 with the **requires_preauth** flag enabled, this flag is not
731 desirable on cross-realm authentication keys because doing
732 so makes it impossible to disable preauthentication on a
733 service-by-service basis. Disabling it as in the example
734 above is recommended.
738 It is very important that these principals have good
739 passwords. MIT recommends that TGT principal passwords be
740 at least 26 characters of random ASCII text.
743 .. _changing_krbtgt_key:
745 Changing the krbtgt key
746 -----------------------
748 A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the
749 principal ``krbtgt/REALM``. The key for this principal is created
750 when the Kerberos database is initialized and need not be changed.
751 However, it will only have the encryption types supported by the KDC
752 at the time of the initial database creation. To allow use of newer
753 encryption types for the TGT, this key has to be changed.
755 Changing this key using the normal :ref:`kadmin(1)`
756 **change_password** command would invalidate any previously issued
757 TGTs. Therefore, when changing this key, normally one should use the
758 **-keepold** flag to change_password to retain the previous key in the
759 database as well as the new key. For example::
761 kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
765 After issuing this command, the old key is still valid
766 and is still vulnerable to (for instance) brute force
767 attacks. To completely retire an old key or encryption
768 type, run the kadmin **purgekeys** command to delete keys
769 with older kvnos, ideally first making sure that all
770 tickets issued with the old keys have expired.
772 Only the first krbtgt key of the newest key version is used to encrypt
773 ticket-granting tickets. However, the set of encryption types present
774 in the krbtgt keys is used by default to determine the session key
775 types supported by the krbtgt service (see
776 :ref:`session_key_selection`). Because non-MIT Kerberos clients
777 sometimes send a limited set of encryption types when making AS
778 requests, it can be important to for the krbtgt service to support
779 multiple encryption types. This can be accomplished by giving the
780 krbtgt principal multiple keys, which is usually as simple as not
781 specifying any **-e** option when changing the krbtgt key, or by
782 setting the **session_enctypes** string attribute on the krbtgt
783 principal (see :ref:`set_string`).
785 Due to a bug in releases 1.8 through 1.13, renewed and forwarded
786 tickets may not work if the original ticket was obtained prior to a
787 krbtgt key change and the modified ticket is obtained afterwards.
788 Upgrading the KDC to release 1.14 or later will correct this bug.
793 Incremental database propagation
794 --------------------------------
799 At some very large sites, dumping and transmitting the database can
800 take more time than is desirable for changes to propagate from the
801 master KDC to the replica KDCs. The incremental propagation support
802 added in the 1.7 release is intended to address this.
804 With incremental propagation enabled, all programs on the master KDC
805 that change the database also write information about the changes to
806 an "update log" file, maintained as a circular buffer of a certain
807 size. A process on each replica KDC connects to a service on the
808 master KDC (currently implemented in the :ref:`kadmind(8)` server) and
809 periodically requests the changes that have been made since the last
810 check. By default, this check is done every two minutes. If the
811 database has just been modified in the previous several seconds
812 (currently the threshold is hard-coded at 10 seconds), the replica
813 will not retrieve updates, but instead will pause and try again soon
814 after. This reduces the likelihood that incremental update queries
815 will cause delays for an administrator trying to make a bunch of
816 changes to the database at the same time.
818 Incremental propagation uses the following entries in the per-realm
819 data in the KDC config file (See :ref:`kdc.conf(5)`):
821 ====================== =============== ===========================================
822 iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*.
823 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.
824 iprop_replica_poll *time interval* Indicates how often the replica should poll the master KDC for changes to the database. The default is two minutes.
825 iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and replica configuration files.
826 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).
827 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.)
828 ====================== =============== ===========================================
830 Both master and replica sides must have a principal named
831 ``kiprop/hostname`` (where *hostname* is the lowercase,
832 fully-qualified, canonical name for the host) registered in the
833 Kerberos database, and have keys for that principal stored in the
834 default keytab file (|keytab|). In release 1.13, the
835 ``kiprop/hostname`` principal is created automatically for the master
836 KDC, but it must still be created for replica KDCs.
838 On the master KDC side, the ``kiprop/hostname`` principal must be
839 listed in the kadmind ACL file :ref:`kadm5.acl(5)`, and given the
840 **p** privilege (see :ref:`privileges`).
842 On the replica KDC side, :ref:`kpropd(8)` should be run. When
843 incremental propagation is enabled, it will connect to the kadmind on
844 the master KDC and start requesting updates.
846 The normal kprop mechanism is disabled by the incremental propagation
847 support. However, if the replica has been unable to fetch changes
848 from the master KDC for too long (network problems, perhaps), the log
849 on the master may wrap around and overwrite some of the updates that
850 the replica has not yet retrieved. In this case, the replica will
851 instruct the master KDC to dump the current database out to a file and
852 invoke a one-time kprop propagation, with special options to also
853 convey the point in the update log at which the replica should resume
854 fetching incremental updates. Thus, all the keytab and ACL setup
855 previously described for kprop propagation is still needed.
857 If an environment has a large number of replicas, it may be desirable
858 to arrange them in a hierarchy instead of having the master serve
859 updates to every replica. To do this, run ``kadmind -proponly`` on
860 each intermediate replica, and ``kpropd -A upstreamhostname`` on
861 downstream replicas to direct each one to the appropriate upstream
864 There are several known restrictions in the current implementation:
866 - The incremental update protocol does not transport changes to policy
867 objects. Any policy changes on the master will result in full
868 resyncs to all replicas.
869 - The replica's KDB module must support locking; it cannot be using the
871 - The master and replica must be able to initiate TCP connections in
872 both directions, without an intervening NAT.
875 Sun/MIT incremental propagation differences
876 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
878 Sun donated the original code for supporting incremental database
879 propagation to MIT. Some changes have been made in the MIT source
880 tree that will be visible to administrators. (These notes are based
881 on Sun's patches. Changes to Sun's implementation since then may not
884 The Sun config file support looks for ``sunw_dbprop_enable``,
885 ``sunw_dbprop_master_ulogsize``, and ``sunw_dbprop_slave_poll``.
887 The incremental propagation service is implemented as an ONC RPC
888 service. In the Sun implementation, the service is registered with
889 rpcbind (also known as portmapper) and the client looks up the port
890 number to contact. In the MIT implementation, where interaction with
891 some modern versions of rpcbind doesn't always work well, the port
892 number must be specified in the config file on both the master and
895 The Sun implementation hard-codes pathnames in ``/var/krb5`` for the
896 update log and the per-replica kprop dump files. In the MIT
897 implementation, the pathname for the update log is specified in the
898 config file, and the per-replica dump files are stored in
899 |kdcdir|\ ``/replica_datatrans_hostname``.