Restart Kerberos Manually

The Kerberos authentication protocol is an encrypted ticketing system at the heart of Apple's Open Directory. It is the basis for Mac OS X's "Single Sign On" features, and a required component for integration with Windows Active Directory domains. Unfortunately, it's possible for the Kerberos service to stop functioning properly, and when it dies, a good number of your network services die with it.

Ideally, you can simply click the "Kerberize" button in the "General" pane of Server Admin's Open Directory settings. That should restart the service. This article for when you find yourself in less than ideal circumstances.

Why Kerberos Can Stop On OS X Server:

When the Kerberos service fails, the likely culprit is a DNS issue. This isn't the only reason Kerberos can break, but it's most common and the easiest to test for. The Kerberos KDC service (or Key Distribution Center), requires matching forward and reverse DNS lookups, and changing a server's hostname or IP manually (or losing connection to your DNS servers) can require the machine to be re-Kerberized. Since Tiger, Mac OS X has also been designed to dynamically set a machine's hostname on boot using a reverse lookup, meaning that external changes to a server's DNS listings can cause it to change names and break its original Kerberos realm.

Before you try to restart Kerberos, you'll want to know which (if any) of these things went wrong. If you aren't sure how to go about this, check with whomever in your organization controls Domain Name Service, or use the procedure from the beginning of our article on setting up Open Directory.

How To Start Kerberos From The Command Line:

Once your server is properly registered in DNS, you can begin reconstructing your Kerberos realm. The first step is to create a new edu.mit.Kerberos file, which Mac OS X can fortunately do (somewhat) automatically. Open the Terminal and type:

sudo kerberosautoconfig -r REALM -m HOSTNAME

For this command, HOSTNAME is the fully qualified domain name of your server, such as server.example.com. REALM is the server's DNS name again, but this time in all capital letters, like SERVER.EXAMPLE.COM. Next you'll create a KDC database for the new Kerberos realm:

kdcsetup -f /LDAPv3/127.0.0.1 -w -a DIRADMIN -p PASSWORD REALM

Here DIRADMIN is the name of any user with directory administration privileges, and PASSWORD is their actual login password. Once that's done, you can Kerberize the server's Open Directory domain with the following:

sudo slapconfig -kerberize -f DIRADMIN REALM

Finally, configure the Single Sign On mechanism to utilize Kerberos authentication for all applicable OS X services.

sudo sso_util configure -r REALM -a DIRADMIN -p PASSWORD all

This should once again leave you with a fully-functioning Kerberos installation on your Open Directory server, all without ever having had to reboot the machine.

If you're following this procedure, keep one additional things in mind: Because the kdcsetup and sso_util commands unfortunately requires that you provide a password on the command line (and therefore store that password in your command history), it's good security practice to change that user's password immediately after this process.

Recommended Reading: For an illustrated overview of the Kerberos authentication Process, there's the handy Kerberos Chart [PDF - 72KB] at Computer World. For more depth into how Kerberos works on OS X, there's an excellent three-part article at AFP548.com.