Administering the Kerberos Database
The Kerberos database is the backbone of Kerberos and must be maintained properly. This section provides some procedures on how to administer the Kerberos database, such as backing up and restoring the database, setting up parallel propagation, and administering the stash file. The steps to initially set up the database are 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 the slave KDCs will lose synchronization. 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 KDC for purposes of load balancing, the clients that use that slave KDC as a master KDC will not have the latest information. Therefore, you must make sure that 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 command 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 data corruption occurs on a slave KDC, you might never notice, since the next automatic propagation of the database installs a fresh copy. However, if corruption occurs on the master KDC, the corrupted database is propagated to all of the slave KDCs 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: 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 and write permissions only as root. To protect against unauthorized access, use only the kprop command to propagate the database dump file, which encrypts the data that is 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.
Caution - If the Kerberos database is updated after it has been propagated
and if the database subsequently is corrupted before the next propagation,
the KDC slaves will not contain the updates. The updates will be lost. For
this reason, if you add significant updates to the Kerberos database before
a regularly scheduled propagation, you should manually propagate the database
to avoid data loss.
The 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 propagation. 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 KDC.
However, the SEAM installation and subsequent configuration steps in this book instruct you to add the same kpropd.acl file to the master KDC and the slave KDCs. This 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, by keeping an identical copy on all KDCs, you make the configuration easy to maintain.
The kprop_script Command
The kprop_script command uses the kprop command to propagate the Kerberos database to other KDCs. If the kprop_script command is run on a slave KDC, it propagates the slave KDC'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
Become superuser on the master KDC.
Back up the Kerberos database by using the dump command of the kdb5_util command.
# /usr/sbin/kdb5_util dump [-verbose] [-d dbname] [filename [principals...]]
-verbose
Prints the name of each principal and policy that is being backed up.
dbname
Defines the name of the database to back up. Note that ".db" is appended to whatever database name is specified, and you can specify an absolute path for the file. If the -d option is not specified, the default database name is /var/krb5/principal, which actually becomes /var/krb5/principal.db.
filename
Defines the file that is used to back up the database. You can specify an absolute path for the file. If you don't specify a file, the database is dumped to standard output.
principal
Defines 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 any principals, the entire database is backed up.
Example--Backing Up the Kerberos Database
In the following example, the Kerberos database is backed up to a file called dumpfile. Because the -verbose option is specified, each principal is printed as it is backed up.
# kdb5_util dump -verbose dumpfile kadmin/kdc1.eng.example.com@ENG.EXAMPLE.COM krbtgt/eng.example.com@ENG.EXAMPLE.COM kadmin/history@ENG.EXAMPLE.COM pak/admin@ENG.EXAMPLE.COM pak@ENG.EXAMPLE.COM changepw/kdc1.eng.example.com@ENG.EXAMPLE.COM |
In the following example, the pak and pak/admin principals are backed up from the Kerberos database.
# kdb5_util dump -verbose dumpfile pak/admin@ENG.EXAMPLE.COM pak@ENG.EXAMPLE.COM pak/admin@ENG.EXAMPLE.COM pak@ENG.EXAMPLE.COM |
How to Restore the Kerberos Database
Become superuser on the master KDC.
Restore the Kerberos database by using the load command of kdb_util.
# /usr/sbin/kdb5_util load [-verbose] [-d dbname] [-update] [filename]
-verbose
Prints the name of each principal and policy that is being restored.
dbname
Defines the name of the database to restore. Note that ".db" is appended to whatever database name is specified, and you can specify an absolute path for the file. 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
Defines the file from which to restore the database. You can specify an absolute path for the file.
Example--Restoring the Kerberos Database
In the following example, the database called database1.db is restored 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 by using the kprop command. Use this procedure if you need to synchronize 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 Kerberos database.
Become superuser on the master KDC.
- (Optional)
Back up the database by using the kdb5_util command.
# /usr/sbin/kdb5_util dump /var/krb5/slave_datatrans
Propagate the database to a slave KDC by using the kprop command.
# /usr/lib/krb5/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/lib/krb5/kprop_script slave_KDC |
Setting Up Parallel Propagation
In most cases, the master KDC is used exclusively to propagate its Kerberos database to the slave KDCs. However, if your site has many slave KDCs, you might 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 sharing of duties enables the propagation to be done faster and to lighten the work for the master KDC.
For example, say your site has one master KDC and six slave KDCs (shown in Figure 8-2), where slave-1 through slave-3 consist of one logical grouping and slave-4 through slave-6 consist of another logical grouping. To set up parallel propagation, you could have the master KDC propagate the database to slave-1 and slave-4, and those KDC slaves could in turn propagate the database to the KDC slaves in their group.
Figure 8-2 Example of Parallel Propagation Configuration
How to Set Up Parallel Propagation
The following is not a detailed step-by-step procedure, but a high-level list of configuration steps to enable parallel propagation.
On the master KDC, change the kprop_script entry in its cron job to include arguments for only the KDC slaves that will perform the succeeding propagation (propagation slaves).
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 Kerberos database.
Note - 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.
On each slave KDC, set up the appropriate permissions to be propagated. This step 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 8-2, the master KDC's kprop_script entry would look similar to the following:
0 3 * * * /usr/lib/krb5/kprop_script slave-1.example.com slave-4.example.com |
The slave-1's kprop_script entry would look similar to the following:
0 4 * * * /usr/lib/krb5/kprop_script slave-2.example.com slave-3.example.com |
Note that the propagation on the slave starts an hour after it is propagated by the master.
The kpropd.acl file on the propagation slaves would contain the following entry:
host/master.example.com@EXAMPLE.COM |
The kpropd.acl file on the KDC slaves being propagated by slave-1 would contain the following entry:
host/slave-1.example.com@EXAMPLE.COM |