4.1.1.4 Create the Database

You will use the kdb5_util command on the Master KDC to create the Kerberos database and the optional stash file. The stash file is a local copy of the master key that resides in encrypted form on the KDC's local disk. The stash file is used to authenticate the KDC to itself automatically before starting the kadmind and krb5kdc daemons (e.g., as part of the machine's boot sequence). The stash file, like the keytab file (see See The Keytab File, for more information) is a potential point-of-entry for a break-in, and if compromised, would allow unrestricted access to the Kerberos database. If you choose to install a stash file, it should be readable only by root, and should exist only on the KDC's local disk. The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the master password itself.

Note that kdb5_util will prompt you for the master key for the Kerberos database. This key can be any string. A good key is one you can remember, but that no one else can guess. Examples of bad keys are words that can be found in a dictionary, any common or popular name, especially a famous person (or cartoon character), your username in any form (e.g., forward, backward, repeated twice, etc.), and any of the sample keys that appear in this manual. One example of a key which might be good if it did not appear in this manual is “MITiys4K5!”, which represents the sentence “MIT is your source for Kerberos 5!” (It's the first letter of each word, substituting the numeral “4” for the word “for”, and includes the punctuation mark at the end.)

The following is an example of how to create a Kerberos database and stash file on the master KDC, using the kdb5_util command. (The line that begins with => is a continuation of the previous line.) Replace ATHENA.MIT.EDU with the name of your Kerberos realm.

     shell% /usr/local/sbin/kdb5_util create -r ATHENA.MIT.EDU -s
     Initializing database '/usr/local/var/krb5kdc/principal' for
     => realm 'ATHENA.MIT.EDU',
     master key name 'K/M@ATHENA.MIT.EDU'
     You will be prompted for the database Master Password.
     It is important that you NOT FORGET this password.
     Enter KDC database master key:  <= Type the master password.
     Re-enter KDC database master key to verify:  <= Type it again.
     shell%

This will create five files in the directory specified in your kdc.conf file: two Kerberos database files, principal.db, and principal.ok; the Kerberos administrative database file, principal.kadm5; the administrative database lock file, principal.kadm5.lock; and the stash file, .k5stash. (The default directory is /usr/local/var/krb5kdc.) If you do not want a stash file, run the above command without the -s option.