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 incremental or 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 or else configure the servers
for incremental propagation, based on how often you change the Kerberos database. Incremental propagation
is preferred over manual propagation because there is more administrative overhead when you
manually propagate the database. Also, there are inefficiencies when you do full propagation
of the 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, because 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 file 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 slave KDC provides a list of host principal
names, one name 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 Kerberos 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 enables
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 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 you can specify an absolute path for the file. If the -d option is not specified, the default database name is /var/krb5/principal.
- 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.
- principals
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 23-14 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/[email protected]
krbtgt/[email protected]
kadmin/[email protected]
pak/[email protected]
[email protected]
changepw/[email protected]
In the following example, the pak and pak/admin principals from the Kerberos
database are backed up.
# kdb5_util dump -verbose dumpfile pak/[email protected] [email protected]
pak/[email protected]
[email protected]
How to Restore the Kerberos Database
- Become superuser on the master KDC.
- On the master, stop the KDC daemons.
kdc1 # svcadm disable network/security/krb5kdc
kdc1 # svcadm disable network/security/kadmin
- Restore the Kerberos database by using the load command of the kdb_util command.
# /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 you can specify an absolute path for the file. If the -d option is not specified, the default database name is /var/krb5/principal.
- -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.
- Start the KDC daemons.
kdc1 # svcadm enable -r network/security/krb5kdc
kdc1 # svcadm enable -r network/security/kadmin
Example 23-15 Restoring the Kerberos Database
In the following example, the database called database1 is restored into the current
directory from the dumpfile file. Because the -update option isn't specified, a new
database is created by the restore.
# kdb5_util load -d database1 dumpfile
How to Convert a Kerberos Database After a Server Upgrade
If your KDC database was created on a server running the Solaris
8 or Solaris 9 release, converting the database allows you to take advantage
of the improved database format.
Before You Begin
Make sure that the database is using an older format.
- On the master, stop the KDC daemons.
kdc1 # svcadm disable network/security/krb5kdc
kdc1 # svcadm disable network/security/kadmin
- Create a directory to store a temporary copy of the database.
kdc1 # mkdir /var/krb5/tmp
kdc1 # chmod 700 /var/krb5/tmp
- Dump the KDC database.
kdc1 # kdb5_util dump /var/krb5/tmp/prdb.txt
- Save copies of the current database files.
kdc1 # cd /var/krb5
kdc1 # mv princ* tmp/
- Load the database.
kdc1 # kdb5_util load /var/krb5/tmp/prdb.txt
- Start the KDC daemons.
kdc1 # svcadm enable -r network/security/krb5kdc
kdc1 # svcadm enable -r network/security/kadmin
How to Reconfigure a Master KDC to Use Incremental Propagation
The steps in this procedure can be used to reconfigure an existing
master KDC to use incremental propagation. In this procedure, the following configuration parameters are
used:
Realm name = EXAMPLE.COM
DNS domain name = example.com
Master KDC = kdc1.example.com
Slave KDC = kdc2.example.com
admin principal = kws/admin
- Add entries to kdc.conf.
You need to enable incremental propagation and select the number of updates the KDC
master keeps in the log. See the kdc.conf(4) man page for more
information.
kdc1 # cat /etc/krb5/kdc.conf
[kdcdefaults]
kdc_ports = 88,750
[realms]
EXAMPLE.COM= {
profile = /etc/krb5/krb5.conf
database_name = /var/krb5/principal
admin_keytab = /etc/krb5/kadm5.keytab
acl_file = /etc/krb5/kadm5.acl
kadmind_port = 749
max_life = 8h 0m 0s
max_renewable_life = 7d 0h 0m 0s
sunw_dbprop_enable = true
sunw_dbprop_master_ulogsize = 1000
}
- Create the kiprop principal.
The kiprop principal is used to authenticate the master KDC server and to
authorize updates from the master KDC.
kdc1 # /usr/sbin/kadmin -p kws/admin
Enter password: <Type kws/admin password>
kadmin: addprinc -randkey kiprop/kdc1.example.com
Principal "kiprop/[email protected]" created.
kadmin: addprinc -randkey kiprop/kdc2.example.com
Principal "kiprop/[email protected]" created.
kadmin:
- Add the kiprop principal to the kadmind keytab file
Adding the kiprop principal to the kadm5.keytab file allows the kadmind command to
authenticate itself when it is started.
kadmin: ktadd -k /etc/krb5/kadm5.keytab kiprop/kdc1.example.com
Entry for principal kiprop/kdc1.example.com with kvno 3, encryption type AES-256 CTS mode
with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
Entry for principal kiprop/kdc1.example.com with kvno 3, encryption type AES-128 CTS mode
with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
Entry for principal kiprop/kdc1.example.com with kvno 3, encryption type Triple DES cbc
mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5/kadm5.keytab.
Entry for principal kiprop/kdc1.example.com with kvno 3, encryption type ArcFour
with HMAC/md5 added to keytab WRFILE:/etc/krb5/kadm5.keytab.
Entry for principal kiprop/kdc1.example.com with kvno 3, encryption type DES cbc mode
with RSA-MD5 added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin: quit
- On the master KDC, add a kiprop entry to kadm5.acl
This entry allows the master KDC to receive requests for incremental propagation from
the kdc2 server.
kdc1 # cat /etc/krb5/kadm5.acl
*/[email protected] *
kiprop/[email protected] p
- Comment out the kprop line in the root crontab file.
This step prevents the master KDC from propagating its copy of the KDC
database.
kdc1 # crontab -e
#ident "@(#)root 1.20 01/11/06 SMI"
#
# The root crontab should be used to perform accounting data collection.
#
# The rtc command is run to adjust the real time clock if and when
# daylight savings time changes.
#
10 3 * * * /usr/sbin/logadm
15 3 * * 0 /usr/lib/fs/nfs/nfsfind
1 2 * * * [ -x /usr/sbin/rtc ] && /usr/sbin/rtc -c > /dev/null 2>&1
30 3 * * * [ -x /usr/lib/gss/gsscred_clean ] && /usr/lib/gss/gsscred_clean
#10 3 * * * /usr/lib/krb5kprop_script kdc2.example.sun.com #SUNWkr5ma
- Restart kadmind.
kdc1 # svcadm restart network/security/kadmin
- Reconfigure all slave KDC servers that use incremental propagation.
See How to Reconfigure a Slave KDC to Use Incremental Propagation for complete instructions.
How to Reconfigure a Slave KDC to Use Incremental Propagation
- Add entries to krb5.conf.
The new entries enable incremental propagation and set the poll time to 2
minutes.
kdc2 # cat /etc/krb5/krb5.conf
[kdcdefaults]
kdc_ports = 88,750
[realms]
EXAMPLE.COM= {
profile = /etc/krb5/krb5.conf
database_name = /var/krb5/principal
admin_keytab = /etc/krb5/kadm5.keytab
acl_file = /etc/krb5/kadm5.acl
kadmind_port = 749
max_life = 8h 0m 0s
max_renewable_life = 7d 0h 0m 0s
sunw_dbprop_enable = true
sunw_dbprop_slave_poll = 2m
}
- Add the kiprop principal to the krb5.keytab file.
kdc2 # /usr/sbin/kadmin -p kws/admin
Enter password: <Type kws/admin password>
kadmin: ktadd kiprop/kdc2.example.com
Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type AES-256 CTS mode
with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/krb5.keytab.
Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type AES-128 CTS mode
with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/krb5.keytab.
Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type Triple DES cbc
mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5/krb5.keytab.
Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type ArcFour
with HMAC/md5 added to keytab WRFILE:/etc/krb5/krb5.keytab.
Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type DES cbc mode
with RSA-MD5 added to keytab WRFILE:/etc/krb5/krb5.keytab.
kadmin: quit
- Restart kpropd.
kdc2 # svcadm restart network/security/krb5_prop
How to Configure a Slave KDC to Use Full Propagation
This procedure shows how to reconfigure a slave KDC server running the Solaris
10 release to use full propagation. Normally, the procedure would only need to
be used if the master KDC server is running either the Solaris 9
release or an earlier release. In this case, the master KDC server
can not support incremental propagation, so the slave needs to be configured to
allow propagation to work.
In this procedure, a slave KDC named kdc3 is configured. This procedure uses
the following configuration parameters:
Realm name = EXAMPLE.COM
DNS domain name = example.com
Master KDC = kdc1.example.com
Slave KDC = kdc2.example.com and kdc3.example.com
admin principal = kws/admin
Online help URL = https://denver:8888/ab2/coll.384.1/SEAM/@AB2PageView/6956
Note - Adjust the URL to point to the “Graphical Kerberos Administration Tool” section, as described in the Online Help URL in the Graphical Kerberos Administration Tool.
Before You Begin
The master KDC must be configured. For specific instructions if this slave is
to be swappable, see Swapping a Master KDC and a Slave KDC.
- On the master KDC, become superuser.
- On the master KDC, start kadmin.
You must log in with one of the admin principal names that you created
when you configured the master KDC.
kdc1 # /usr/sbin/kadmin -p kws/admin
Enter password: <Type kws/admin password>
kadmin:
- On the master KDC, add slave host principals to the database, if not
already done.
For the slave to function, it must have a host principal. Note that
when the principal instance is a host name, the FQDN must be specified
in lowercase letters, regardless of the case of the domain name in the
/etc/resolv.conf file.
kadmin: addprinc -randkey host/kdc3.example.com
Principal "host/[email protected]" created.
kadmin:
- Quit kadmin.
kadmin: quit
- On the master KDC, edit the Kerberos configuration file (krb5.conf).
You need to add an entry for each slave. See the krb5.conf(4) man page
for a full description of this file.
kdc1 # cat /etc/krb5/krb5.conf
.
.
[realms]
EXAMPLE.COM = {
kdc = kdc1.example.com
kdc = kdc2.example.com
kdc = kdc3.example.com
admin_server = kdc1.example.com
}
- On the master KDC, add an entry for the master KDC and
each slave KDC into the kpropd.acl file.
See the kprop(1M) man page for a full description of this file.
kdc1 # cat /etc/krb5/kpropd.acl
host/[email protected]
host/[email protected]
host/[email protected]
- On all slave KDCs, copy the KDC administration files from the master KDC
server.
This step needs to be followed on all slave KDCs, because the
master KDC server has updated information that each KDC server needs. You can
use ftp or a similar transfer mechanism to grab copies of the
following files from the master KDC:
/etc/krb5/krb5.conf
/etc/krb5/kdc.conf
/etc/krb5/kpropd.acl
- On all slave KDCs, make sure that the Kerberos access control list file,
kadm5.acl, is not populated.
An unmodified kadm5.acl file would look like:
kdc2 # cat /etc/krb5/kadm5.acl
*/admin@___default_realm___ *
If the file has kiprop entries, remove them.
- On the new slave, start the kadmin command.
You must log in with one of the admin principal names that you
created when you configured the master KDC.
kdc2 # /usr/sbin/kadmin -p kws/admin
Enter password: <Type kws/admin password>
kadmin:
- Add the slave's host principal to the slave's keytab file by using kadmin.
This entry allows kprop and other Kerberized applications to function. Note that
when the principal instance is a host name, the FQDN must be specified
in lowercase letters, regardless of the case of the domain name in the
/etc/resolv.conf file.
kadmin: ktadd host/kdc3.example.com
Entry for principal host/kdc3.example.com with kvno 3, encryption type AES-256 CTS mode
with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/krb5.keytab.
Entry for principal host/kdc3.example.com with kvno 3, encryption type AES-128 CTS mode
with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/krb5.keytab.
Entry for principal host/kdc3.example.com with kvno 3, encryption type Triple DES cbc
mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5/krb5.keytab.
Entry for principal host/kdc3.example.com with kvno 3, encryption type ArcFour
with HMAC/md5 added to keytab WRFILE:/etc/krb5/krb5.keytab.
Entry for principal host/kdc3.example.com with kvno 3, encryption type DES cbc mode
with RSA-MD5 added to keytab WRFILE:/etc/krb5/krb5.keytab.
kadmin:
- Quit kadmin.
kadmin: quit
- On the master KDC, add the slave KDC name to the cron
job, which automatically runs the backups, by running crontab -e.
Add the name of each slave KDC server at the end of the
kprop_script line.
10 3 * * * /usr/lib/krb5/kprop_script kdc2.example.com kdc3.example.com
You might also want to change the time of the backups. This
entry starts the backup process every day at 3:10 AM.
- On the new slave, start the Kerberos propagation daemon.
kdc3 # svcadm enable network/security/krb5_prop
- On the master KDC, back up and propagate the database by using
kprop_script.
If a backup copy of the database is already available, it is not
necessary to complete another backup. See How to Manually Propagate the Kerberos Database to the Slave KDCs for further instructions.
kdc1 # /usr/lib/krb5/kprop_script kdc3.example.com
Database propagation to kdc3.example.com: SUCCEEDED
- On the new slave, create a stash file by using kdb5_util.
kdc3 # /usr/sbin/kdb5_util stash
kdb5_util: Cannot find/read stored master key while reading master key
kdb5_util: Warning: proceeding without master key
Enter KDC database master key: <Type the key>
- (Optional) On the new slave KDC, synchronize the master KDCs clock by using NTP
or another clock synchronization mechanism.
Installing and using the Network Time Protocol (NTP) is not required. However, every
clock must be within the default time that is defined in the libdefaults
section of the krb5.conf file for authentication to succeed. See Synchronizing Clocks Between KDCs and Kerberos Clients for
information about NTP.
- On the new slave, start the KDC daemon (krb5kdc).
kdc3 # svcadm enable network/security/krb5kdc
How to Verify That the KDC Servers Are Synchronized
If incremental propagation has been configured, this procedure ensures that the information on
the slave KDC has been updated.
- On the KDC master server, run the kproplog command.
kdc1 # /usr/sbin/kproplog -h
- On a KDC slave server, run the kproplog command.
kdc2 # /usr/sbin/kproplog -h
- Check that the last serial # and the last timestamp values match.
Example 23-16 Verifying That the KDC Servers Are Synchronized
The following is a sample of results from running the kproplog command on
the master KDC server.
kdc1 # /usr/sbin/kproplog -h
Kerberos update log (/var/krb5/principal.ulog)
Update log dump:
Log version #: 1
Log state: Stable
Entry block size: 2048
Number of entries: 2500
First serial #: 137966
Last serial #: 140465
First time stamp: Fri Nov 28 00:59:27 2004
Last time stamp: Fri Nov 28 01:06:13 2004The following is a sample of results from running the kproplog command on
a slave KDC server.
kdc2 # /usr/sbin/kproplog -h
Kerberos update log (/var/krb5/principal.ulog)
Update log dump:
Log version #: 1
Log state: Stable
Entry block size: 2048
Number of entries: 0
First serial #: None
Last serial #: 140465
First time stamp: None
Last time stamp: Fri Nov 28 01:06:13 2004Notice that the values for the last serial number and the last
timestamp are identical, which indicates that the slave is synchronized with the master KDC
server.
In the slave KDC server output, notice that no update entries exist in
the slave KDC server's update log. No entries exist because the slave
KDC server does not keep a set of updates, unlike the master KDC
server. Also, the KDC slave server does not include information on the first
serial number or the first timestamp because this is not relevant information.
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. 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.
Note - Do not use this procedure if you are using incremental propagation.
- 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
Example 23-17 Manually Propagating the Kerberos Database to the Slave KDCs Using kprop_script
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.
Note - Do not use this procedure if you are using incremental 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 23-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.
In turn, those KDC slaves could propagate the database to the KDC slaves
in their group.
Figure 23-2 Example of Parallel Propagation Configuration
Configuration Steps for Setting 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. These steps involve the following:
On the master KDC, changing the kprop_script entry in its cron job to include arguments for only the KDC slaves that will perform the succeeding propagation (the propagation slaves).
On each propagation slave, adding 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 Kerberos database.
On each slave KDC, setting 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 23-18 Setting Up Parallel Propagation
Using the example in Figure 23-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/[email protected]
The kpropd.acl file on the KDC slaves being propagated by slave-1 would contain
the following entry:
host/[email protected]
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 the kdb5_util utility 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 is not automatically removed with the database, you have to
remove the stash file to finish the cleanup.
How to Remove a Stash File
- Become superuser on the KDC that contains the stash file.
- Remove the stash file.
# rm stash-file
Where stash-file is the path to the stash file. By default, the stash
file is located at /var/krb5/.k5.realm.
Note - If you need to re-create the stash file, you can use the
-f option of the kdb5_util command.
