FreeBSD 15.0 comes with MIT Kerberos 1.22.1 (released August 2025). All preceding versions of FreeBSD including any FreeBSD 14.x came with very outdated Heimdal 1.7 (carrying a few patches from version 7). This documents tries to describe migration path for a KDC running FreeBSD to FreeBSD 15.0 or newer.
Overview
Before upgrade of the system the Heimdal 1.7 Kerberos database needs to be dumped in a format that later would be understood by the MIT Kerberos. The keys in the dump need to be encrypted using master key of the future MIT installation. This creates a chicken-and-egg problem that is solved by instantiating MIT KDC before touching the old installation.
Detailed walk through
First, you need to update your FreeBSD system that runs Heimdal KDC to 14.4-RELEASE version or recent enough 14.3-STABLE version (after a93e1b731ae4 commit dated 27 October 2025). This brings a modification crucial to be able to dump the database in MIT format. Note that building just kadmin from recent stable/14 sources won't work, as update of Kerberos libraries is also required. Then, to solve the chicken-and-egg problem, you need to instantiate a MIT KDC on a FreeBSD 15.0 or later system. This must be a trusted secure machine, since the KDC master key is going to be generated there. The most straightforward secure solution is to install 15.0-RELEASE in a bhyve(8) virtual machine running right on the existing KDC.
Assuming you updated your KDC to 14.4-RELEASE or 14.3-STABLE that includes a93e1b731ae4 and you have a virtual machine running 15.0-RELEASE, let's start.
Instantiate a new KDC in a trusted 15.0-RELEASE install (usually a virtual machine)
1 vm# kdb5_util create -r REALM -s
2 Initializing database '/var/db/krb5kdc/principal' for realm 'REALM',
3 master key name 'K/M@REALM'
4 You will be prompted for the database Master Password.
5 It is important that you NOT FORGET this password.
6 Enter KDC database master key:
7 Re-enter KDC database master key to verify:
8 vm#
The password you entered for K/M@REALM is the KDC master password. It will be stored encrypted in /var/db/krb5kdc/.k5.REALM.
The newly created KDC database has 4 principals: K/M@REALM, kadmin/admin@REALM, kadmin/changepw@REALM, krbtgt/REALM@REALM. We want to dump this database to later be combined with the database we obtain from the KDC to be migrated.
Dump the Heimdal database in MIT format
Securely copy /var/db/krb5kdc/.k5.REALM to the running Heimdal installation. Obtain the dump in MIT format with keys re-encrypted using master key from the new installation:
Securely copy heimdal-raw.dump into the trusted 15.0-RELEASE where we have our new KDC instantiated.
Combine Heimdal and MIT database dumps
Along with important user and host credentials the Heimdal database contains some system credentials, that we don't want to import into the new database. Some of them already exist in the new MIT database, and we don't want to import them from the old. Some make no sense in MIT. Thus, the Heimdal database needs to be cleansed of some unwanted entries. Here is suggested filter, but please don't copy this command blindly, use your own discretion:
1 vm#awk '$7 !~ "(default|kadmin/.*|krbtgt/REALM|changepw/kerberos|WELLKNOWN/ANONYMOUS)@REALM" {print}' < heimdal-raw.dump > heimdal.dump
Append MIT entries to the dump:
1 vm#grep ^princ new-mit.dump >> heimdal.dump
Now the heimdal.dump contains both system principals for MIT and imported principals for users/hosts from legacy Heimdal installation.
Test the resulting dump with MIT KDC
This step can potentially be skipped. But you probably want to make sure that your new KDC is going to work with the restored database, so let's start the new KDC with restored database in our temporary environment. First, restore the database:
Then configure /etc/krb5.conf in your virtual environment, so that it uses local KDC. Start the KDC and test that some principal (with a password you know) imported from Heimdal works:
Upgrade the KDC to FreeBSD 15.x
Upgrade your KDC to the new FreeBSD version that is shipped with MIT Kerberos. If it is source based upgrade, or some other non-standard way to to upgrade, make sure that Heimdal installation is deleted. For source based upgrades this is done with delete-old targets:
1 kdc#make -DBATCH_DELETE_OLD_FILES delete-old delete-old-libs delete-old-dirs
Copy contents of /var/db/krb5kdc including the master key stashed in .k5.REALM from the temporary instance to the upgraded KDC /var/db/krb5kdc. Restore the database from the merged dump, unless you already did so in the testing step:
Your new MIT Kerberos KDC is ready to be started:
Note that the old database is left in /var/heimdal. It is up to your discretion when to delete it.