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 load a single principal, either replacing or updating the database:
384 shell% kdb5_util load dumpfile principal
387 shell% kdb5_util load -update dumpfile principal
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 slave KDCs, either manually or by
514 waiting until the next scheduled propagation. If you do not have
515 any slave KDCs, you can skip this and the next step.
517 #. On each slave KDC, run ``kdb5_util list_mkeys`` to verify that the
518 new master key is present, and then ``kdb5_util stash`` to write
519 the new master key to the slave 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 slave KDCs (if any are present) during
533 this time period. In release 1.13 and later, you can instead run
534 ``kdb5_util -x unlockiter update_princ_encryption`` to use unlocked
535 iteration; this variant will take longer, but will keep the
536 database available to the KDC and kadmind while it runs.
538 #. On the master KDC, run ``kdb5_util purge_mkeys`` to clean up the
544 Operations on the LDAP database
545 -------------------------------
547 The :ref:`kdb5_ldap_util(8)` is the primary tool for administrating
548 the Kerberos LDAP database. It allows an administrator to manage
549 realms, Kerberos services (KDC and Admin Server) and ticket policies.
551 .. include:: admin_commands/kdb5_ldap_util.rst
552 :start-after: _kdb5_ldap_util_synopsis:
553 :end-before: _kdb5_ldap_util_synopsis_end:
557 .. include:: admin_commands/kdb5_ldap_util.rst
558 :start-after: _kdb5_ldap_util_options:
559 :end-before: _kdb5_ldap_util_options_end:
562 .. _ldap_create_realm:
564 Creating a Kerberos realm
565 ~~~~~~~~~~~~~~~~~~~~~~~~~
567 If you need to create a new realm, use the :ref:`kdb5_ldap_util(8)`
568 **create** command as follows.
570 .. include:: admin_commands/kdb5_ldap_util.rst
571 :start-after: _kdb5_ldap_util_create:
572 :end-before: _kdb5_ldap_util_create_end:
577 Modifying a Kerberos realm
578 ~~~~~~~~~~~~~~~~~~~~~~~~~~
580 If you need to modify a realm, use the :ref:`kdb5_ldap_util(8)`
581 **modify** command as follows.
583 .. include:: admin_commands/kdb5_ldap_util.rst
584 :start-after: _kdb5_ldap_util_modify:
585 :end-before: _kdb5_ldap_util_modify_end:
588 Destroying a Kerberos realm
589 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
591 If you need to destroy a Kerberos realm, use the
592 :ref:`kdb5_ldap_util(8)` **destroy** command as follows.
594 .. include:: admin_commands/kdb5_ldap_util.rst
595 :start-after: _kdb5_ldap_util_destroy:
596 :end-before: _kdb5_ldap_util_destroy_end:
599 Retrieving information about a Kerberos realm
600 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
602 If you need to display the attributes of a realm, use the
603 :ref:`kdb5_ldap_util(8)` **view** command as follows.
605 .. include:: admin_commands/kdb5_ldap_util.rst
606 :start-after: _kdb5_ldap_util_view:
607 :end-before: _kdb5_ldap_util_view_end:
610 Listing available Kerberos realms
611 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
613 If you need to display the list of the realms, use the
614 :ref:`kdb5_ldap_util(8)` **list** command as follows.
616 .. include:: admin_commands/kdb5_ldap_util.rst
617 :start-after: _kdb5_ldap_util_list:
618 :end-before: _kdb5_ldap_util_list_end:
623 Stashing service object's password
624 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
626 The :ref:`kdb5_ldap_util(8)` **stashsrvpw** command allows an
627 administrator to store the password of service object in a file. The
628 KDC and Administration server uses this password to authenticate to
631 .. include:: admin_commands/kdb5_ldap_util.rst
632 :start-after: _kdb5_ldap_util_stashsrvpw:
633 :end-before: _kdb5_ldap_util_stashsrvpw_end:
636 Ticket Policy operations
637 ~~~~~~~~~~~~~~~~~~~~~~~~
639 Creating a Ticket Policy
640 ########################
642 To create a new ticket policy in directory , use the
643 :ref:`kdb5_ldap_util(8)` **create_policy** command. Ticket policy
644 objects are created under the realm container.
646 .. include:: admin_commands/kdb5_ldap_util.rst
647 :start-after: _kdb5_ldap_util_create_policy:
648 :end-before: _kdb5_ldap_util_create_policy_end:
651 Modifying a Ticket Policy
652 #########################
654 To modify a ticket policy in directory, use the
655 :ref:`kdb5_ldap_util(8)` **modify_policy** command.
657 .. include:: admin_commands/kdb5_ldap_util.rst
658 :start-after: _kdb5_ldap_util_modify_policy:
659 :end-before: _kdb5_ldap_util_modify_policy_end:
662 Retrieving Information About a Ticket Policy
663 ############################################
665 To display the attributes of a ticket policy, use the
666 :ref:`kdb5_ldap_util(8)` **view_policy** command.
668 .. include:: admin_commands/kdb5_ldap_util.rst
669 :start-after: _kdb5_ldap_util_view_policy:
670 :end-before: _kdb5_ldap_util_view_policy_end:
673 Destroying a Ticket Policy
674 ##########################
676 To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)`
677 **destroy_policy** command.
679 .. include:: admin_commands/kdb5_ldap_util.rst
680 :start-after: _kdb5_ldap_util_destroy_policy:
681 :end-before: _kdb5_ldap_util_destroy_policy_end:
684 Listing available Ticket Policies
685 #################################
687 To list the name of ticket policies in a realm, use the
688 :ref:`kdb5_ldap_util(8)` **list_policy** command.
690 .. include:: admin_commands/kdb5_ldap_util.rst
691 :start-after: _kdb5_ldap_util_list_policy:
692 :end-before: _kdb5_ldap_util_list_policy_end:
697 Cross-realm authentication
698 --------------------------
700 In order for a KDC in one realm to authenticate Kerberos users in a
701 different realm, it must share a key with the KDC in the other realm.
702 In both databases, there must be krbtgt service principals for both realms.
703 For example, if you need to do cross-realm authentication between the realms
704 ``ATHENA.MIT.EDU`` and ``EXAMPLE.COM``, you would need to add the
705 principals ``krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU`` and
706 ``krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM`` to both databases.
707 These principals must all have the same passwords, key version
708 numbers, and encryption types; this may require explicitly setting
709 the key version number with the **-kvno** option.
711 In the ATHENA.MIT.EDU and EXAMPLE.COM cross-realm case, the administrators
712 would run the following commands on the KDCs in both realms::
714 shell%: kadmin.local -e "aes256-cts:normal"
715 kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM
716 Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
717 Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
718 kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
719 Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
720 Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
725 Even if most principals in a realm are generally created
726 with the **requires_preauth** flag enabled, this flag is not
727 desirable on cross-realm authentication keys because doing
728 so makes it impossible to disable preauthentication on a
729 service-by-service basis. Disabling it as in the example
730 above is recommended.
734 It is very important that these principals have good
735 passwords. MIT recommends that TGT principal passwords be
736 at least 26 characters of random ASCII text.
739 .. _changing_krbtgt_key:
741 Changing the krbtgt key
742 -----------------------
744 A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the
745 principal ``krbtgt/REALM``. The key for this principal is created
746 when the Kerberos database is initialized and need not be changed.
747 However, it will only have the encryption types supported by the KDC
748 at the time of the initial database creation. To allow use of newer
749 encryption types for the TGT, this key has to be changed.
751 Changing this key using the normal :ref:`kadmin(1)`
752 **change_password** command would invalidate any previously issued
753 TGTs. Therefore, when changing this key, normally one should use the
754 **-keepold** flag to change_password to retain the previous key in the
755 database as well as the new key. For example::
757 kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
761 After issuing this command, the old key is still valid
762 and is still vulnerable to (for instance) brute force
763 attacks. To completely retire an old key or encryption
764 type, run the kadmin **purgekeys** command to delete keys
765 with older kvnos, ideally first making sure that all
766 tickets issued with the old keys have expired.
768 Only the first krbtgt key of the newest key version is used to encrypt
769 ticket-granting tickets. However, the set of encryption types present
770 in the krbtgt keys is used by default to determine the session key
771 types supported by the krbtgt service (see
772 :ref:`session_key_selection`). Because non-MIT Kerberos clients
773 sometimes send a limited set of encryption types when making AS
774 requests, it can be important to for the krbtgt service to support
775 multiple encryption types. This can be accomplished by giving the
776 krbtgt principal multiple keys, which is usually as simple as not
777 specifying any **-e** option when changing the krbtgt key, or by
778 setting the **session_enctypes** string attribute on the krbtgt
779 principal (see :ref:`set_string`).
781 Due to a bug in releases 1.8 through 1.13, renewed and forwarded
782 tickets may not work if the original ticket was obtained prior to a
783 krbtgt key change and the modified ticket is obtained afterwards.
784 Upgrading the KDC to release 1.14 or later will correct this bug.
789 Incremental database propagation
790 --------------------------------
795 At some very large sites, dumping and transmitting the database can
796 take more time than is desirable for changes to propagate from the
797 master KDC to the slave KDCs. The incremental propagation support
798 added in the 1.7 release is intended to address this.
800 With incremental propagation enabled, all programs on the master KDC
801 that change the database also write information about the changes to
802 an "update log" file, maintained as a circular buffer of a certain
803 size. A process on each slave KDC connects to a service on the master
804 KDC (currently implemented in the :ref:`kadmind(8)` server) and
805 periodically requests the changes that have been made since the last
806 check. By default, this check is done every two minutes. If the
807 database has just been modified in the previous several seconds
808 (currently the threshold is hard-coded at 10 seconds), the slave will
809 not retrieve updates, but instead will pause and try again soon after.
810 This reduces the likelihood that incremental update queries will cause
811 delays for an administrator trying to make a bunch of changes to the
812 database at the same time.
814 Incremental propagation uses the following entries in the per-realm
815 data in the KDC config file (See :ref:`kdc.conf(5)`):
817 ====================== =============== ===========================================
818 iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*.
819 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.
820 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.
821 iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and slave configuration files.
822 iprop_resync_timeout *integer* Specifies the number of seconds to wait for a full propagation to complete. This is optional on slave configurations. Defaults to 300 seconds (5 minutes).
823 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.)
824 ====================== =============== ===========================================
826 Both master and slave sides must have a principal named
827 ``kiprop/hostname`` (where *hostname* is the lowercase,
828 fully-qualified, canonical name for the host) registered in the
829 Kerberos database, and have keys for that principal stored in the
830 default keytab file (|keytab|). In release 1.13, the
831 ``kiprop/hostname`` principal is created automatically for the master
832 KDC, but it must still be created for slave KDCs.
834 On the master KDC side, the ``kiprop/hostname`` principal must be
835 listed in the kadmind ACL file :ref:`kadm5.acl(5)`, and given the
836 **p** privilege (see :ref:`privileges`).
838 On the slave KDC side, :ref:`kpropd(8)` should be run. When
839 incremental propagation is enabled, it will connect to the kadmind on
840 the master KDC and start requesting updates.
842 The normal kprop mechanism is disabled by the incremental propagation
843 support. However, if the slave has been unable to fetch changes from
844 the master KDC for too long (network problems, perhaps), the log on
845 the master may wrap around and overwrite some of the updates that the
846 slave has not yet retrieved. In this case, the slave will instruct
847 the master KDC to dump the current database out to a file and invoke a
848 one-time kprop propagation, with special options to also convey the
849 point in the update log at which the slave should resume fetching
850 incremental updates. Thus, all the keytab and ACL setup previously
851 described for kprop propagation is still needed.
853 If an environment has a large number of slaves, it may be desirable to
854 arrange them in a hierarchy instead of having the master serve updates
855 to every slave. To do this, run ``kadmind -proponly`` on each
856 intermediate slave, and ``kpropd -A upstreamhostname`` on downstream
857 slaves to direct each one to the appropriate upstream slave.
859 There are several known restrictions in the current implementation:
861 - The incremental update protocol does not transport changes to policy
862 objects. Any policy changes on the master will result in full
863 resyncs to all slaves.
864 - The slave's KDB module must support locking; it cannot be using the
866 - The master and slave must be able to initiate TCP connections in
867 both directions, without an intervening NAT.
870 Sun/MIT incremental propagation differences
871 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
873 Sun donated the original code for supporting incremental database
874 propagation to MIT. Some changes have been made in the MIT source
875 tree that will be visible to administrators. (These notes are based
876 on Sun's patches. Changes to Sun's implementation since then may not
879 The Sun config file support looks for ``sunw_dbprop_enable``,
880 ``sunw_dbprop_master_ulogsize``, and ``sunw_dbprop_slave_poll``.
882 The incremental propagation service is implemented as an ONC RPC
883 service. In the Sun implementation, the service is registered with
884 rpcbind (also known as portmapper) and the client looks up the port
885 number to contact. In the MIT implementation, where interaction with
886 some modern versions of rpcbind doesn't always work well, the port
887 number must be specified in the config file on both the master and
890 The Sun implementation hard-codes pathnames in ``/var/krb5`` for the
891 update log and the per-slave kprop dump files. In the MIT
892 implementation, the pathname for the update log is specified in the
893 config file, and the per-slave dump files are stored in
894 |kdcdir|\ ``/slave_datatrans_hostname``.