Administering the Kerberos Database

The Kerberos database is the backbone of Kerberos and must be maintained properly. This section provides some of the procedures on how to administer the Kerberos database, such as backing up and restoring the database, setting up parallel progation, and administering the stash file. The steps to set up the database initially can be found in "How to Configure a Master KDC".

Backing Up and Propagating the Kerberos Database

Propagating the Kerberos database from the master KDC to the slave KDCs is one of the most important configuration tasks. If propagation doesn't happen often enough, the master KDC and slave KDCs will become out-of-sync, so if the master KDC goes down, the slave KDCs will not have the most recent database information. Also, if a slave KDC has been configured as a master for purposes of load balancing, the clients using that slave as a master KDC will not have the latest information. Therefore, it is important to make sure the propagation occurs often enough, based on how often you change the Kerberos database.

When you configure the master KDC, you set up the kprop_script in a cron job to automatically back up the Kerberos database to the /var/krb5/slave_datatrans dump file and propagate it to the slave KDCs. But, as with any file, the Kerberos database can become corrupted. If this happens on one of the slave KDCs, you might never notice, since the next automatic propagation of the database installs a fresh copy. However, if it happens to the master KDC, the corrupted database is propagated to all of the slaves during the next propagation. And, the corrupted backup overwrites the previous uncorrupted backup file on the master KDC.

Because there is no "safe" backup copy in this scenario, you should also set up a cron job to periodically copy the slave_datatrans dump file to another location or to create another separate backup copy by using the dump command of kdb5_util. Then, if your database becomes corrupted, you can restore the most recent backup on the master KDC by using the load command of kdb5_util.

Another important note is that, because the database dump file contains principal keys, you need to protect the file from being accessed by unauthorized users (by default, the database dump file has read/write permissions only as root). This includes using only the kprop command to propagate the database dump file, which encrypts the data being transferred. Also, kprop propagates the data only to the slave KDCs, which minimizes the chance of accidentally sending the database dump to unauthorized hosts.

If the Kerberos database is updated after it has been propagated and if the database subsequently is corrupted before the next propagation, the slaves will not contain the updates: the updates will be lost. Because of this scenario, if you add significant updates to the database before a regularly scheduled propagation, you should manually propagate the database to avoid data loss.

kpropd.acl File

The kpropd.acl file on a KDC provides a list of host principal names, one per line, that specifies the systems from which the KDC can receive an updated database through the propagation mechanism. If the master KDC is used to propagate all the slave KDCs, the kpropd.acl file on each slave needs to contain only the host principal name of the master.

However, the SEAM installation and subsequent configuration steps in this guide instruct you to add the same kpropd.acl file to the master and slave KDCs. The file contains all the KDC host principal names. This configuration allows you to propagate from any KDC, in case the propagating KDCs become temporarily unavailable. And, keeping an identical copy on all KDCs makes it easy to maintain.

kprop_script Command

The kprop_script command uses the kprop command to propagate the Kerberos database to other KDCs. (If the kprop_script is run on a slave KDC, it propagates the slave's copy of the Kerberos database to other KDCs.) The kprop_script accepts a list of host names for arguments, separated by spaces, which denote the KDCs to propagate.

When the kprop_script is run, it creates a backup of the Kerberos database to the /var/krb5/slave_datatrans file and copies the file to the specified KDCs. The Kerberos database is locked until the propagation is finished.

How to Back Up the Kerberos Database

1. Become superuser on the master KDC.

2. Back up the Kerberos database by using the dump command of kdb5_util.

   # /usr/krb5/sbin/kdb5_util dump [-verbose] [-d dbname] [filename [principals...]]

   -verbose	Prints the name of each principal and policy that is being backed up.
   dbname	The name of the database to back up. Note that ".db" is appended to whatever database name is specified, and an absolute path for the file can be specified. If the -d option is not specified, the default database name is /var/krb5/principal, which actually becomes /var/krb5/principal.db.
   filename	The file to back up the database. An absolute path for the file can be specified. If you don't specify a file, the database is dumped to standard output.
   principal	A list of one or more principals (separated by a space) to back up. You must use fully-qualified principal names. If you don't specify principals, the entire database is backed up.

Example--Backing Up the Kerberos Database

The following example backs up the Kerberos database to a file called dumpfile. Because the -verbose option is specified, each principal is printed as it is backed up.

# kbd5_util dump -verbose dumpfile 
kadmin/kdc1.eng.acme.com@ENG.ACME.COM 
krbtgt/eng.acme.com@ENG.ACME.COM 
kadmin/history@ENG.ACME.COM 
pak/admin@ENG.ACME.COM 
pak@ENG.ACME.COM
changepw/kdc1.eng.acme.com@ENG.ACME.COM
#

The following example backs up the pak and pak/admin principals from the Kerberos database.

# kdb5_util dump -verbose dumpfile pak/admin@ENG.ACME.COM pak@ENG.ACME.COM
pak/admin@ENG.ACME.COM
pak@ENG.ACME.COM
#

How to Restore the Kerberos Database

1. Become superuser on the master KDC.

2. Restore the Kerberos database by using the load command of kdb_util.

   # /usr/krb5/sbin/kdb5_util load [-verbose] [-d dbname] [-update] [filename]

   -verbose	Prints the name of each principal and policy that is being restored.
   dbname	The name of the database to restore. Note that ".db" is appended to whatever database name is specified, and an absolute path for the file can be specified. If the -d option is not specified, the default database name is /var/krb5/principal, which actually becomes /var/krb5/principal.db.
   -update	Updates the existing database; otherwise a new database is created or the existing database is overwritten.
   filename	The file from which to restore the database. An absolute path for the file can be specified.

Example--Restoring the Kerberos Database

The following example restores the database called database1.db into the current directory from the dumpfile file. Since the -update option isn't specified, a new database is created by the restore.

# kdb5_util load -d database1 dumpfile

How to Manually Propagate the Kerberos Database to the Slave KDCs

This procedure shows you how to propagate the Kerberos database using the kprop command. You can use this if you need to sync a slave KDC with the master KDC outside the periodic cron job. And, unlike the kprop_script, you can use kprop to propagate just the current database backup without first making a new backup of the database.

1. Become superuser on the master KDC.

2. (Optional) Back up the database by using the kdb5_util command.

   # /usr/krb5/sbin/kdb5_util dump /var/krb5/slave_datatrans

3. Propagate the database to a slave KDC by using the kprop command.

   # /usr/krb5/lib/kprop -f /var/krb5/slave_datatrans slave_KDC

If you want to back up the database and propagate it to a slave KDC outside the periodic cron job, you can also use the kprop_script command as follows:

# /usr/krb5/lib/kprop_script slave_KDC

Setting Up Parallel Propagation

In most cases, the master KDC is used exclusively to propagate its database to the slave KDCs. However, if your site has a lot of slave KDCs, you might want to consider load-sharing the propagation process, known as parallel propagation.

Parallel propagation allows specific slave KDCs to share the propagation duties with the master KDC. This enables the propagation to be done faster and to lighten the work for the master KDC.

For example, say your site has one master and six slaves (shown in Figure 3-2), where slave-1 through slave-3 consist of one logical grouping and slave-4 through slave-6 consist of the other. To set up parallel propagation, you could have the master KDC propagate the database to slave-1 and slave-4, and those slaves could in turn propagate the database to the slaves in their group.

Figure 3-2 Example Parallel Propagation Configuration

How to Set Up Parallel Propagation

This is not a detailed step-by-step procedure, but a high-level list of configuration steps to enable parallel propagation.

1. On the master KDC, change the kprop_script entry in its cron job to include arguments for only the slaves that will perform the succeeding propagation (propagation slaves).

2. On each propagation slave, add a kprop_script entry to its cron job, which must include arguments for the slaves to propagate. To successfully propagate in parallel, the cron job should be set up to run after the propagation slave is itself propagated with the new database.

   ---

   Note -

   Determining how long it will take for a propagation slave to be propagated depends on factors such as network bandwidth and the size of the database.

   ---

3. On each slave KDC, set up the appropriate permissions to be propagated. This is done by adding the host principal name of its propagating KDC to its kpropd.acl file.

Example -- Setting Up Parallel Propagation

Using the example in Figure 3-2, the master KDC's kprop_script entry would look something like this:

10 3 * * * /usr/krb5/lib/kprop_script slave-1.acme.com slave-4.acme.com

slave-1's kprop_script entry would look something like this (note that the propagation on the slave starts an hour after it is propagated by the master):

10 4 * * * /usr/krb5/lib/kprop_script slave-2.acme.com slave-3.acme.com

The kpropd.acl file on the propagation slaves would have to contain the following entry:

host/master.acme.com@ACME.COM

The kpropd.acl file on the slaves being propagated by slave-1 would have to contain the following entry:

host/slave-1.acme.com@ACME.COM

Administering the Stash File

The stash file contains the master key for the Kerberos database, which is automatically created when you create a Kerberos database. If the stash file gets corrupted, you can use the stash command of kdb5_util(1M) to replace the corrupted file. The only time you should need to remove a stash file is after removing the Kerberos database with the destroy command of kdb5_util. Because the stash file isn't automatically removed with the database, you have to remove it to finish the cleanup.

How to Remove a Stash File

1. Become superuser on the KDC that contains the stash file.

2. Remove the stash file.

   # rm stash_file

   stash_file

   The path to the stash file. By default, the stash file is located at /var/krb5/.k5.realm.

If you need to recreate the stash file, you can use the -f option of the kdb5_util command.