Assumptions

These are step-by-step instructions for installing, configuring, and testing a Kerberos 5 master server and slave server. These instructions assume the following:

Installation Instructions for DAS-M

Step 1: Installing and Upgrading Kerberos RPMs

The following packages were already installed during the Red Hat 9 OS installation process:

krb5-libs-1.2.7-10
krbafs-1.1.1-9
krbafs-devel-1.1.1-9
pam_krb5-1.60-1
krb5-devel-1.2.7-10

I visited www.redhat.com and retrieved the following (newer) packages:

krb5-devel-1.2.7-14.i386.rpm
krb5-libs-1.2.7-14.i386.rpm
krb5-server-1.2.7-14.i386.rpm
krb5-workstation-1.2.7-14.i386.rpm

(It is always a good idea to get the most recent packages!)

Now on DAS-M, install/upgrade like this:

[root@das-m RPM]# rpm -Uvh krb5*rpm
warning: krb5-devel-1.2.7-14.i386.rpm: V3 DSA signature: NOKEY, key ID db42a60e
Preparing...                ########################################### [100%]
   1:krb5-libs              ########################################### [ 25%]
   2:krb5-devel             ########################################### [ 50%]
   3:krb5-server            ########################################### [ 75%]
   4:krb5-workstation       ########################################### [100%]

Here is the final listing of installed Kerberos-related packages:

krb5-server-1.2.7-14
krbafs-1.1.1-9
krbafs-devel-1.1.1-9
krb5-devel-1.2.7-14
krb5-workstation-1.2.7-14
pam_krb5-1.60-1
krb5-libs-1.2.7-14

Step 2: Make backups of the original Kerb5 configuration files

[root@das-m]# cd /etc
[root@das-m etc]# cp krb5.conf krb5.conf.org
[root@das-m etc]# cp krb.conf krb.conf.org
[root@das-m etc]# cp krb.realms krb.realms.org

[root@das-m etc]# cd /var/kerberos/krb5kdc
[root@das-m krb5kdc]# cp kdc.conf kdc.conf.org
[root@das-m krb5kdc]# cp kadm5.acl kadm5.acl.org


Step 3: Edit or replace Kerb5 config files for your environment

Modifications include hostnames, realm names, DNS information, and encryption types. Here are the actual config files that we are using in our production setup:

/etc/krb5.conf:

[logging]
 default = FILE:/var/log/krb5libs.log
 kdc = FILE:/var/log/krb5kdc.log
 admin_server = FILE:/var/log/kadmind.log

[libdefaults]
 ticket_lifetime = 24000
 default_realm = KERB.ORG
 dns_lookup_realm = false
 dns_lookup_kdc = false

[realms]
 KERB.ORG = {
  kdc = das-m.kerb.org:88
  kdc = das-s.kerb.org:88
  admin_server = das-m.kerb.org:749
  default_domain = kerb.org
 }

[domain_realm]
 .kerb.org = KERB.ORG
 kerb.org = KERB.ORG

[kdc]
 profile = /var/kerberos/krb5kdc/kdc.conf

[appdefaults]
 pam = {
   debug = false
   ticket_lifetime = 36000
   renew_lifetime = 36000
   forwardable = true
   krb4_convert = false
 }

/var/kerberos/krb5kdc/kdc.conf:

[kdcdefaults]
 acl_file = /var/kerberos/krb5kdc/kadm5.acl
 dict_file = /usr/share/dict/words
 admin_keytab = /var/kerberos/krb5kdc/kadm5.keytab
 v4_mode = nopreauth
 kdc_ports = 88
 kadmind_port = 749

[realms]
 KERB.ORG = {
  master_key_type = des3-hmac-sha1
  supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal
 }

/var/kerberos/krb5kdc/kadm5.acl:

super/admin@KERB.ORG       *
user/admin@KERB.ORG        clADMI

The first entry allows the administrative user "super/admin" to perform any administrative task. The second entry allows the administrative user "user/admin" to list principals and change passwords only. You can customize this file to allow different users different levels of administrative control over the database. For more details, check out the kadmind manpage.

Last, but not least, this is a good time to set permissions on the Kerberos configuration files and directories. The following permissions will work:

  /etc/krb5.conf            root.root  0644
  /etc/krb5.keytab          root.root  0600
  /var/kerberos/krb5kdc     root.root  0750
  /var/kerberos/krb5kdc/*   root.root  0600

Step 4: Create the Kerberos principal database with a stash file

The kdb5_util program, located in /usr/kerberos/sbin, allows you to create, destroy, dump, and restore Kerberos 5 databases. You can also create a stash file, which allows the server to boot without prompting the administrator for the database encryption password.

[root@das-m krb5kdc]# /usr/kerberos/sbin/kdb5_util create -s

Make sure that you do not lose this password, and also make sure that the password itself is not trivial. You will need this if you have to restore your database from a backup.

Step 5: Add some principals to the database

Now, you will need to add some principals (users) to the database. We will add the two administrative principals that were listed in the kadm5.acl file, and we will also add a regular principal (user) for testing purposes.

[root@das-m root]# kadmin.local
Authenticating as principal root/admin@KERB.ORG with password.
kadmin.local:  addprinc super/admin
WARNING: no policy specified for super/admin@KERB.ORG; defaulting to no policy
Enter password for principal "super/admin@KERB.ORG":
Re-enter password for principal "super/admin@KERB.ORG":
Principal "super/admin@KERB.ORG" created.

kadmin.local:  addprinc user/admin
WARNING: no policy specified for user/admin@KERB.ORG; defaulting to no policy
Enter password for principal "user/admin@KERB.ORG":
Re-enter password for principal "user/admin@KERB.ORG":
Principal "user/admin@KERB.ORG" created.

kadmin.local:  addprinc kitty
WARNING: no policy specified for kitty@KERB.ORG; defaulting to no policy
Enter password for principal "kitty@KERB.ORG":
Re-enter password for principal "kitty@KERB.ORG":
Principal "kitty@KERB.ORG" created.

kadmin.local: listprincs 
K/M@KERB.ORG
kadmin/admin@KERB.ORG
kadmin/changepw@KERB.ORG
kadmin/history@KERB.ORG
kitty@KERB.ORG
krbtgt/KERB.ORG@KERB.ORG
super/admin@KERB.ORG
user/admin@KERB.ORG

kadmin.local: exit


Step 6: Start the KDC and the kadmin daemon, then configure to start automatically at boot

[root@das-m root]# /etc/init.d/krb5kdc start
Starting Kerberos 5 KDC:                                   [  OK  ]
[root@das-m root]# /etc/init.d/kadmin start
Starting Kerberos 5 Admin Server:                          [  OK  ]

[root@das-m root]# netstat -tua | grep k
tcp        0      0 *:kerberos-adm          *:*                     LISTEN
udp        0      0 *:kpasswd               *:*
udp        0      0 das-m.kerb.org:kerberos *:*

[root@das-m root]# chkconfig kadmin off
[root@das-m root]# chkconfig --level 345 kadmin on
[root@das-m root]# chkconfig krb5kdc off
[root@das-m root]# chkconfig --level 345 krb5kdc on
[root@das-m root]# chkconfig --list kadmin
kadmin          0:off   1:off   2:off   3:on    4:on    5:on    6:off
[root@das-m root]# chkconfig --list krb5kdc
krb5kdc         0:off   1:off   2:off   3:on    4:on    5:on    6:off

Step 7: Test basic Kerb5 functionality on the KDC

[root@das-m root]# kadmin -p super/admin
Authenticating as principal super/admin with password.
Enter password:
kadmin:  exit

[root@das-m root]# kinit kitty
Password for kitty@KERB.ORG:
[root@das-m root]# klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: kitty@KERB.ORG
 
Valid starting     Expires            Service principal
10/20/03 10:25:55  10/20/03 20:25:55  krbtgt/KERB.ORG@KERB.ORG
 
 
Kerberos 4 ticket cache: /tmp/tkt0
klist: You have no tickets cached
[root@das-m root]# kdestroy
[root@das-m root]# klist
klist: No credentials cache found (ticket cache FILE:/tmp/krb5cc_0)
 
 
Kerberos 4 ticket cache: /tmp/tkt0
klist: You have no tickets cached

Step 8: Create KDC host principals

Your KDCs will need to have host principals, which are added to their respective keytabs. The keytab file is located here: /etc/krb5.keytab

[root@das-m root]# kadmin.local
Authenticating as principal root/admin@KERB.ORG with password.
kadmin.local:  addprinc -randkey host/das-m.kerb.org
WARNING: no policy specified for host/das-m.kerb.org@KERB.ORG; defaulting to no policy
Principal "host/das-m.kerb.org@KERB.ORG" created.

kadmin.local:  ktadd host/das-m.kerb.org
Entry for principal host/das-m.kerb.org with kvno 3, 
encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal host/das-m.kerb.org with kvno 3, 
encryption type DES cbc mode with CRC-32 added to keytab WRFILE:/etc/krb5.keytab.

kadmin.local:  addprinc -randkey host/das-s.kerb.org
WARNING: no policy specified for host/das-s.kerb.org@KERB.ORG; defaulting to no policy
Principal "host/das-s.kerb.org@KERB.ORG" created.

The keytab entry for das-s.kerb.org will be added later, when we configure the slave (DAS-S). Please note that the entire host principal scheme is dependent on FQDN hostnames being used, with the proper A and PTR records configured in DNS.

Step 9: Configure Log Rotatation

We also need to setup log rotation for kadmind and krb5kdc. First, let's add the following logrotate config scripts the the /etc/logrotate.d directory:

/etc/logrotated.d/kadmin

/var/log/kadmind.log {
    missingok
    notifempty
    create 0640 root root
    postrotate
        /etc/init.d/kadmin condrestart >/dev/null 2>&1 || true
    endscript
}

/etc/logrotate.d/krb5kdc

/var/log/krb5kdc.log {
    missingok
    notifempty
    create 0640 root root
    postrotate
        /etc/init.d/krb5kdc condrestart >/dev/null 2>&1 || true
    endscript
}

Now, if you want to test the log rotation without waiting for the weekly rotate, you can use the following command:

[root@das-m root]# logrotate -f -v /etc/logrotate.conf

You can then check for file rotation in /var/log:

[root@das-m root]# ls -l /var/log/k[a,r]*
-rw-r-----    1 root     root           71 Dec  8 09:15 /var/log/kadmind.log
-rw-r-----    1 root     root          241 Dec  8 09:15 /var/log/kadmind.log.1
-rw-r-----    1 root     root          241 Dec  8 09:07 /var/log/kadmind.log.2
-rw-r-----    1 root     root          241 Dec  8 09:01 /var/log/kadmind.log.3
-rw-r-----    1 root     root          349 Dec  8 09:15 /var/log/krb5kdc.log
-rw-r-----    1 root     root          915 Dec  8 09:15 /var/log/krb5kdc.log.1
-rw-r-----    1 root     root      1487535 Dec  8 09:07 /var/log/krb5kdc.log.2



You now have an operational KDC and Kadmind server!


Installation Instructions for DAS-S

The slave KDC on DAS-S (das-s.kerb.org) runs another complete instance of krb5kdc. However, it does NOT run kadmind, since there is only one master copy of the principal database, and it is located on DAS-M. The other difference is that DAS-S will run kpropd, a service that allows database propagation from DAS-M to DAS-S at scheduled intervals. Kpropd listens on TCP port 754.

Step 1: Install and Upgrade Kerberos RPM packages

This step is identical to Step 1 on DAS-M. Follow those directions.

Step 2: Make backups of the original Kerb5 configuration files

This step is identical to Step 2 on DAS-M. Follow those directions.

Step 3: Edit or replace Kerb5 config files for your environment

You can simply copy the same Kerberos configuration files that you used on DAS-M over to the appropriate directories on DAS-S. Note that configuring kadm5.acl is not necessary. You will need to have a kpropd ACL file (/var/kerberos/krb5kdc/kpropd.acl) with a single entry:

host/das-m.kerb.org@KERB.ORG

This allows DAS-M's kprop program to connect to kpropd, authenticate via kerberos, and replicate the database. For more information, look at the kpropd manpage.

Don't forget to check ownership and permissions of the configuration files. They should be:

  /etc/krb5.conf            root.root  0644
  /etc/krb5.keytab          root.root  0600
  /var/kerberos/krb5kdc     root.root  0750
  /var/kerberos/krb5kdc/*   root.root  0600

Step 4: Add the DAS-S host principal to DAS-S's keytab

[root@das-s root]# kadmin -p super/admin
Authenticating as principal super/admin with password.
Enter password:

kadmin:  ktadd host/das-s.kerb.org
Entry for principal host/das-s.kerb.org with kvno 4, 
encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal host/das-s.kerb.org with kvno 4, 
encryption type DES cbc mode with CRC-32 added to keytab WRFILE:/etc/krb5.keytab.

kadmin:  exit

Step 5: Start the kpropd service and configure it to start on boot

[root@das-s root]# /etc/init.d/kprop start
Starting Kerberos 5 Propagation Server:                    [  OK  ]
[root@das-s root]# chkconfig kprop off
[root@das-s root]# chkconfig --level 345 kprop on
[root@das-s root]# chkconfig --list kprop
kprop           0:off   1:off   2:off   3:on    4:on    5:on    6:off

Step 6: Manually replicate the Kerb5 database from DAS-M to DAS-S

On DAS-M, as root, run the following commands:

[root@das-m root]# /usr/kerberos/sbin/kdb5_util dump /var/kerberos/krb5kdc/slave_datatrans
[root@das-m root]# ls -al /var/kerberos/krb5kdc/slave_datatrans
-rw-------    1 root     root         6422 Oct 20 12:06 /var/kerberos/krb5kdc/slave_datatrans

[root@das-m root]# /usr/kerberos/sbin/kprop -d -f /var/kerberos/krb5kdc/slave_datatrans das-s.kerb.org
6422 bytes sent.
Database propagation to das-s.kerb.org: SUCCEEDED

Step 7: Getting the KDC started on DAS-S

Back on DAS-S, you should check the /var/kerberos/krb5kdc directory for the following files:

[root@das-s krb5kdc]# ls -l princ*
-rw-------    1 root     root        16384 Oct 20 12:10 principal
-rw-------    1 root     root         8192 Oct 20 12:10 principal.kadm5
-rw-------    1 root     root            0 Oct 20 12:10 principal.kadm5.lock
-rw-------    1 root     root            0 Oct 20 12:10 principal.ok

Another thing to check is the /var/log/messages file. For every successful Kerb5 database transfer, you should see an entry like this:

Oct 20 12:07:04 das-s kpropd[5697]: Connection from das-m.kerb.org

Now, we need to create the KDC stash file. You will be prompted for the database master password:

[root@das-s krb5kdc]# kdb5_util stash

Now, we can start the KDC service, and configure it to start automatically on boot. We should also check to make sure that the proper ports are listening:

[root@das-s log]# /etc/init.d/krb5kdc start
Starting Kerberos 5 KDC:                                   [  OK  ]

[root@das-s log]# chkconfig krb5kdc off
[root@das-s log]# chkconfig --level 345 krb5kdc on
[root@das-s log]# chkconfig --list krb5kdc
krb5kdc         0:off   1:off   2:off   3:on    4:on    5:on    6:off

[root@das-s log]# netstat -tua | grep k
tcp        0      0 *:krb5_prop             *:*                     LISTEN
udp        0      0 das-s.kerb.org:kerberos *:*

The /var/log/krb5kdc.log and /var/log/messages log files will both show information relating to the startup and shutdown of the KDC service.

Step 8: Test basic Kerb5 functionality on the KDC

This step is identical to Step 7 on DAS-M. Follow those directions. You should now have a fully functional slave KDC that will accept database transfers from the master KDC.

Step 9: Configure Log Rotation

This step is identical to step 9 on DAS-M. Follow those directions, except that you do not need to make the script for kadmind, since kadmind does not run on the slave.


Setting up Automatic Replication

As you have seen, you can "propagate" the Kerberos 5 principal database from DAS-M to DAS-S. On DAS-M, the kprop program initiates this, and on DAS-S, the kpropd service listens for and accepts connections. We still need to make this process automatic, so that changes on the master are pushed to the slaves on a regular basis. How long should this interval be? It depends on the size of your database, the number of slaves, the number of users, etc. In our environment, we decided that a 5-minute interval was sufficient. Therefore, we setup a cron script to run kprop every 5 minutes. This section shows you how to do it.

Create a text file named /usr/local/sbin/krb5prop.sh . It should have the following contents:

#!/bin/bash
# This shell script dumps the Kerberos database to a file, then
# securely transfers it over to the slave KDC

/usr/kerberos/sbin/kdb5_util dump /var/kerberos/krb5kdc/slave_datatrans

/usr/kerberos/sbin/kprop -f /var/kerberos/krb5kdc/slave_datatrans das-s.kerb.org > /dev/null

Change the permissions on the script to 0770. Then add the following line to /etc/crontab :

*/5 * * * * root /usr/local/sbin/krb5prop.sh

This will run the script every five minutes.

Restart the cron daemon:

[root@das-m etc]# /etc/init.d/crond restart
Stopping crond:                                            [  OK  ]
Starting crond:                                            [  OK  ]

You can check the logs on DAS-M and DAS-S to make sure that replication is occuring as scheduled. Another easy way to check is to look on DAS-S, in the /var/kerberos/krb5kdc directory. The timestamps on the principal* files should be changing every 5 minutes.

Note: If you have problems getting replication to work, you should (1)check your firewall config or temporarily disable the firewall and (2) make sure that the hostnames, DNS A and PTR records are correct, and that your /etc/hosts files do not have any entries which conflict with the DNS entries. For example, propagation will fail if DAS-S has an /etc/hosts entry for DAS-M that does not match DAS-M's FQDN.


Database Backup to the Local Disk

As an added safety precaution, we will setup an automated Kerberos database backup to a different partition on the same disk. If you are using RAID 1 or RAID 5, this may not be necessary. We use the kdcback.sh script in conjunction with cron to name the file, compress it, and save it. The files are saved in the /home/Backups directory. This is because /home is in a different disk partition from /var and /etc . Here are the details:

Create the backup directory and set permissions:

[root@das-m sbin]# mkdir /home/Backups
[root@das-m sbin]# chmod 0700 /home/Backups

Now, fire up your favourite editor and create the shell script kdcback.sh. It should look like this when you are done:

#!/bin/bash
 
# Kerb5-KDC database backup tool, runs from cron
# backups are stored in GZIP format in the /home/Backups directory
# uses the already-created /var/kerberos/krb5kdc/slave_datatrans dump file
 
# Generate date stamp for filename and define filename
DATESTAMP=`date +%j-%y`
BKUPFILE=$DATESTAMP.das-m.kerb5
BKUPDIR=/home/Backups
 
# Get rid of any existing backup file by the same name
/bin/rm -f $BKUPDIR/$BKUPFILE.gz
 
# Copy the Kerb5-KDC database dump to the backup directory
cp /var/kerberos/krb5kdc/slave_datatrans $BKUPDIR/$BKUPFILE
 
# Compress the backup file with GZIP
/bin/gzip $BKUPDIR/$BKUPFILE
 
# Change the permissions on the backup file so that it is read-only by root
/bin/chmod 0400 $BKUPDIR/$BKUPFILE.gz
 
exit 0

Save the file as /usr/local/sbin/kdcback.sh and change its permissions accordingly:

[root@das-m sbin]# chmod 0700 /usr/local/sbin/kdcback.sh

Now, we need to configure cron to run the script periodically. I have it setup to run hourly, but you could probably set it up to run twice a day or daily. It's up to you. Our hourly jobs run at 1 minute past the hour. A soft link was created in the /etc/cron.hourly directory to the new shell script:

[root@das-m sbin]# cd /etc/cron.hourly
[root@das-m cron.hourly]# ln -s /usr/local/sbin/kdcback.sh
[root@das-m cron.hourly]# ls -al
total 12
drwxr-xr-x    2 root     root         4096 Oct 23 09:51 .
drwxr-xr-x   59 root     root         8192 Oct 21 15:56 ..
lrwxrwxrwx    1 root     root           26 Oct 21 08:30 kdcback.sh -> /usr/local/sbin/kdcback.sh

Now, you should have an hourly backup with a history of daily snapshots. You can always restore from the last day on which the system was operating properly.


Kerberos 5 Server Setup Summary

The following Kerberos-related TCP and UDP ports are now listening on each server:

  On DAS-M

  krb5kdc UDP 88
  kpasswd UDP 464
  kadmind TCP 749

  On DAS-S

  krb5kdc UDP 88
  kpropd TCP 754

The following configuration files were modified:

The following scripts were created:


References

MIT Kerberos page
Kerberos Infrastructure HOWTO
Network Computing article on Kerberos
Red Hat 9 Kerberos Configuration Instructions
Jason Heiss' Kerberos-LDAP HOWTO