Installing KDCs

When setting up Kerberos in a production environment, it is best to have multiple slave KDCs alongside with a master KDC to ensure the continued availability of the Kerberized services. Each KDC contains a copy of the Kerberos database. The master KDC contains the writable copy of the realm database, which it replicates to the slave KDCs at regular intervals. All database changes (such as password changes) are made on the master KDC. Slave KDCs provide Kerberos ticket-granting services, but not database administration, when the master KDC is unavailable. MIT recommends that you install all of your KDCs to be able to function as either the master or one of the slaves. This will enable you to easily switch your master KDC with one of the slaves if necessary (see Switching master and slave KDCs). This installation procedure is based on that recommendation.

Warning

• The Kerberos system relies on the availability of correct time information. Ensure that the master and all slave KDCs have properly synchronized clocks.
• It is best to install and run KDCs on secured and dedicated hardware with limited access. If your KDC is also a file server, FTP server, Web server, or even just a client machine, someone who obtained root access through a security hole in any of those areas could potentially gain access to the Kerberos database.

Install and configure the master KDC

Install Kerberos either from the OS-provided packages or from the source (See Building within a single tree).

Note

For the purpose of this document we will use the following names:

kerberos.mit.edu    - master KDC
kerberos-1.mit.edu  - slave KDC
ATHENA.MIT.EDU      - realm name
.k5.ATHENA.MIT.EDU  - stash file
admin/admin         - admin principal

See MIT Kerberos defaults for the default names and locations of the relevant to this topic files. Adjust the names and paths to your system environment.

Edit KDC configuration files

Modify the configuration files, krb5.conf and kdc.conf, to reflect the correct information (such as domain-realm mappings and Kerberos servers names) for your realm. (See MIT Kerberos defaults for the recommended default locations for these files).

Most of the tags in the configuration have default values that will work well for most sites. There are some tags in the krb5.conf file whose values must be specified, and this section will explain those.

If the locations for these configuration files differs from the default ones, set KRB5_CONFIG and KRB5_KDC_PROFILE environment variables to point to the krb5.conf and kdc.conf respectively. For example:

export KRB5_CONFIG=/yourdir/krb5.conf
export KRB5_KDC_PROFILE=/yourdir/kdc.conf

krb5.conf

If you are not using DNS TXT records (see Mapping hostnames onto Kerberos realms), you must specify the default_realm in the [libdefaults] section. If you are not using DNS SRV records (see Hostnames for KDCs), you must include the kdc tag for each realm in the [realms] section. To communicate with the kadmin server in each realm, the admin_server tag must be set in the [realms] section.

An example krb5.conf file:

[libdefaults]
    default_realm = ATHENA.MIT.EDU

[realms]
    ATHENA.MIT.EDU = {
        kdc = kerberos.mit.edu
        kdc = kerberos-1.mit.edu
        admin_server = kerberos.mit.edu
    }

kdc.conf

The kdc.conf file can be used to control the listening ports of the KDC and kadmind, as well as realm-specific defaults, the database type and location, and logging.

An example kdc.conf file:

[kdcdefaults]
    kdc_ports = 88,750

[realms]
    ATHENA.MIT.EDU = {
        kadmind_port = 749
        max_life = 12h 0m 0s
        max_renewable_life = 7d 0h 0m 0s
        master_key_type = aes256-cts
        supported_enctypes = aes256-cts:normal aes128-cts:normal
        # If the default location does not suit your setup,
        # explicitly configure the following values:
        #    database_name = /var/krb5kdc/principal
        #    key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU
        #    acl_file = /var/krb5kdc/kadm5.acl
    }

[logging]
    # By default, the KDC and kadmind will log output using
    # syslog.  You can instead send log output to files like this:
    kdc = FILE:/var/log/krb5kdc.log
    admin_server = FILE:/var/log/kadmin.log
    default = FILE:/var/log/krb5lib.log

Replace ATHENA.MIT.EDU and kerberos.mit.edu with the name of your Kerberos realm and server respectively.

Note

You have to have write permission on the target directories (these directories must exist) used by database_name, key_stash_file, and acl_file.

Create the KDC database

You will use the kdb5_util command on the master KDC to create the Kerberos database and the optional stash file.

Note

If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up. This means that the KDC will not be able to start automatically, such as after a system reboot.

kdb5_util will prompt you for the master password for the Kerberos database. This password can be any string. A good password is one you can remember, but that no one else can guess. Examples of bad passwords are words that can be found in a dictionary, any common or popular name, especially a famous person (or cartoon character), your username in any form (e.g., forward, backward, repeated twice, etc.), and any of the sample passwords that appear in this manual. One example of a password which might be good if it did not appear in this manual is “MITiys4K5!”, which represents the sentence “MIT is your source for Kerberos 5!” (It’s the first letter of each word, substituting the numeral “4” for the word “for”, and includes the punctuation mark at the end.)

The following is an example of how to create a Kerberos database and stash file on the master KDC, using the kdb5_util command. Replace ATHENA.MIT.EDU with the name of your Kerberos realm:

shell% kdb5_util create -r ATHENA.MIT.EDU -s

Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
master key name 'K/M@ATHENA.MIT.EDU'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key:  <= Type the master password.
Re-enter KDC database master key to verify:  <= Type it again.
shell%

This will create five files in LOCALSTATEDIR/krb5kdc (or at the locations specified in kdc.conf):

• two Kerberos database files, principal, and principal.ok
• the Kerberos administrative database file, principal.kadm5
• the administrative database lock file, principal.kadm5.lock
• the stash file, in this example .k5.ATHENA.MIT.EDU. If you do not want a stash file, run the above command without the -s option.

For more information on administrating Kerberos database see Operations on the Kerberos database.

Add administrators to the ACL file

Next, you need create an Access Control List (ACL) file and put the Kerberos principal of at least one of the administrators into it. This file is used by the kadmind daemon to control which principals may view and make privileged modifications to the Kerberos database files. The ACL filename is determined by the acl_file variable in kdc.conf; the default is LOCALSTATEDIR/krb5kdc/kadm5.acl.

The format of the file is:

client_principal      permissions     [target_principal]  [restrictions]

The client_principal (and optional target_principal) can include the * wildcard, so if you want any principal with the instance admin to have full permissions on the database, you could use the principal */admin@REALM where REALM is your Kerberos realm. target_principal can also include backreferences to client_principal, in which *number matches the component number in client_principal.

Note

A common use of an admin instance is so you can grant separate permissions (such as administrator access to the Kerberos database) to a separate kerberos principal. For example, the user joeadmin might have a principal for his administrative use, called joeadmin/admin. This way, joeadmin would obtain joeadmin/admin tickets only when he actually needs to use those permissions.

The permissions are represented by single letters. A lowercase character specifies that operation can be performed by the principal, while its uppercase counterpart indicates negative permission. The permissions are:

a	[Dis]allows the addition of principals or policies in the database
c	[Dis]allows the changing of passwords for principals in the database
d	[Dis]allows the deletion of principals or policies in the database
i	[Dis]allows inquiries to the database
l	[Dis]allows the listing of principals or policies in the database
m	[Dis]allows the modification of principals or policies in the database
s	[Dis]allows the explicit setting of the key for a principal
*	All privileges (admcil)
x	All privileges (admcil); identical to “*”

Restrictions are a string of flags. Allowed restrictions are:

[+|-]flagname	flag is forced to indicated value. The permissible flags are the same as the + and - flags for the kadmin add_principal and modify_principal commands.
-clearpolicy	policy is forced to clear
-policy pol	policy is forced to be pol
expire time	associated value will be forced to MIN(time, requested value)
pwexpire time	associated value will be forced to MIN(time, requested value)
maxlife time	associated value will be forced to MIN(time, requested value)
maxrenewlife time	associated value will be forced to MIN(time, requested value)

The above flags act as restrictions on any add or modify operation which is allowed due to that ACL line.

Here is an example of a kadm5.acl file.

Warning

The order of lines is important; permissions are determined by the first matching entry.

*/admin@ATHENA.MIT.EDU          *
joeadmin@ATHENA.MIT.EDU         ADMCIL
joeadmin/*@ATHENA.MIT.EDU  il   */root@ATHENA.MIT.EDU
*@ATHENA.MIT.EDU           cil  *1/admin@ATHENA.MIT.EDU
*/*@ATHENA.MIT.EDU         i
*/admin@EXAMPLE.COM        * -maxlife 9h -postdateable

In the above file, any principal in the ATHENA.MIT.EDU realm with an admin instance has all administrative privileges.

The user joeadmin has all permissions with his admin instance, joeadmin/admin@ATHENA.MIT.EDU (matches the first line). He has no permissions at all with his null instance, joeadmin@ATHENA.MIT.EDU (matches the second line). His root instance has inquire and list permissions with any other principal that has the instance root.

Any principal in ATHENA.MIT.EDU can inquire, list, or change the password of their admin instance, but not any other admin instance.

Any principal in the realm ATHENA.MIT.EDU (except for joeadmin@ATHENA.MIT.EDU, as mentioned above) has inquire privileges.

Finally, any principal with an admin instance in EXAMPLE.COM has all permissions, but any principal that they create or modify will not be able to get postdateable tickets or tickets with a life of longer than 9 hours.

Warning

If the kadmind ACL file is modified, the kadmind daemon needs to be restarted for changes to take effect.

Add administrators to the Kerberos database

Next you need to add administrative principals (i.e. principals who are allowed to administer Kerberos database) to the Kerberos database. You must add at least one principal now to allow communication between the Kerberos administration daemon kadmind and the kadmin program over the network for further administration. To do this, use the kadmin.local utility on the master KDC. kadmin.local is designed to be run on the master KDC host without using Kerberos authentication to an admin server; instead, it must have read and write access to the Kerberos database on the local filesystem.

The administrative principals you create should be the ones you added to the ACL file (see Add administrators to the ACL file).

In the following example, the administrative principal admin/admin is created:

shell% kadmin.local

kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU

WARNING: no policy specified for "admin/admin@ATHENA.MIT.EDU";
assigning "default".
Enter password for principal admin/admin@ATHENA.MIT.EDU:  <= Enter a password.
Re-enter password for principal admin/admin@ATHENA.MIT.EDU:  <= Type it again.
Principal "admin/admin@ATHENA.MIT.EDU" created.
kadmin.local:

Start the Kerberos daemons on the master KDC

At this point, you are ready to start the Kerberos KDC (krb5kdc) and administrative daemons on the Master KDC. To do so, type:

shell% krb5kdc
shell% kadmind

Each server daemon will fork and run in the background.

Note

Assuming you want these daemons to start up automatically at boot time, you can add them to the KDC’s /etc/rc or /etc/inittab file. You need to have a stash file in order to do this.

You can verify that they started properly by checking for their startup messages in the logging locations you defined in krb5.conf (see [logging]). For example:

shell% tail /var/log/krb5kdc.log
Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
shell% tail /var/log/kadmin.log
Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting

Any errors the daemons encounter while starting will also be listed in the logging output.

As an additional verification, check if kinit succeeds against the principals that you have created on the previous step (Add administrators to the Kerberos database). Run:

shell% kinit admin/admin@ATHENA.MIT.EDU

Install the slave KDCs

You are now ready to start configuring the slave KDCs.

Note

Assuming you are setting the KDCs up so that you can easily switch the master KDC with one of the slaves, you should perform each of these steps on the master KDC as well as the slave KDCs, unless these instructions specify otherwise.

Create host keytabs for slave KDCs

Each KDC needs a host key in the Kerberos database. These keys are used for mutual authentication when propagating the database dump file from the master KDC to the secondary KDC servers.

On the master KDC, connect to administrative interface and create the host principal for each of the KDCs’ host services. For example, if the master KDC were called kerberos.mit.edu, and you had a slave KDC named kerberos-1.mit.edu, you would type the following:

shell% kadmin
kadmin: addprinc -randkey host/kerberos.mit.edu
NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default"
Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created.

kadmin: addprinc -randkey host/kerberos-1.mit.edu
NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default"
Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created.

It is not strictly necessary to have the master KDC server in the Kerberos database, but it can be handy if you want to be able to swap the master KDC with one of the slaves.

Next, extract host random keys for all participating KDCs and store them in each host’s default keytab file. Ideally, you should extract each keytab locally on its own KDC. If this is not feasible, you should use an encrypted session to send them across the network. To extract a keytab on a slave KDC called kerberos-1.mit.edu, you would execute the following command:

kadmin: ktadd host/kerberos-1.mit.edu
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
    type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
    type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
    type des3-cbc-sha1 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
    type arcfour-hmac added to keytab FILE:/etc/krb5.keytab.

Configure slave KDCs

Database propagation copies the contents of the master’s database, but does not propagate configuration files, stash files, or the kadm5 ACL file. The following files must be copied by hand to each slave (see MIT Kerberos defaults for the default locations for these files):

• krb5.conf
• kdc.conf
• kadm5.acl
• master key stash file

Move the copied files into their appropriate directories, exactly as on the master KDC. kadm5.acl is only needed to allow a slave to swap with the master KDC.

The database is propagated from the master KDC to the slave KDCs via the kpropd daemon. You must explicitly specify the principals which are allowed to provide Kerberos dump updates on the slave machine with a new database. Create a file named kpropd.acl in the KDC state directory containing the host principals for each of the KDCs:

host/kerberos.mit.edu@ATHENA.MIT.EDU
host/kerberos-1.mit.edu@ATHENA.MIT.EDU

Note

If you expect that the master and slave KDCs will be switched at some point of time, list the host principals from all participating KDC servers in kpropd.acl files on all of the KDCs. Otherwise, you only need to list the master KDC’s host principal in the kpropd.acl files of the slave KDCs.

Then, add the following line to /etc/inetd.conf on each KDC (adjust the path to kpropd):

krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd

You also need to add the following line to /etc/services on each KDC, if it is not already present (assuming that the default port is used):

krb5_prop       754/tcp               # Kerberos slave propagation

Restart inetd daemon.

Alternatively, start kpropd as a stand-alone daemon with kpropd -S.

Now that the slave KDC is able to accept database propagation, you’ll need to propagate the database from the master server.

NOTE: Do not start the slave KDC yet; you still do not have a copy of the master’s database.

Propagate the database to each slave KDC

First, create a dump file of the database on the master KDC, as follows:

shell% kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans

Then, manually propagate the database to each slave KDC, as in the following example:

shell% kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu

Database propagation to kerberos-1.mit.edu: SUCCEEDED

You will need a script to dump and propagate the database. The following is an example of a Bourne shell script that will do this.

Note

Remember that you need to replace /usr/local/var/krb5kdc with the name of the KDC state directory.

#!/bin/sh

kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu"

kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans

for kdc in $kdclist
do
    kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc
done

You will need to set up a cron job to run this script at the intervals you decided on earlier (see Database propagation).

Now that the slave KDC has a copy of the Kerberos database, you can start the krb5kdc daemon:

shell% krb5kdc

As with the master KDC, you will probably want to add this command to the KDCs’ /etc/rc or /etc/inittab files, so they will start the krb5kdc daemon automatically at boot time.

Propagation failed?

Error

kprop: No route to host while connecting to server

Make sure that the hostname of the slave (as given to kprop) is correct, and that any firewalls beween the master and the slave allow a connection on port 754.

Error

kprop: Connection refused in call to connect while opening connection

If the slave is intended to run kpropd out of inetd, make sure that inetd is configured to accept krb5_prop connections. inetd may need to be restarted or sent a SIGHUP to recognize the new configuration. If the slave is intended to run kpropd in standalone mode, make sure that it is running.

Error

kprop: Server rejected authentication while authenticating to server

Make sure that:

1. The time is syncronized between the master and slave KDCs.
2. The master stash file was copied from the master to the expected location on the slave.
3. The slave has a keytab file in the default location containing a host principal for the slave’s hostname.

Add Kerberos principals to the database

Once your KDCs are set up and running, you are ready to use kadmin to load principals for your users, hosts, and other services into the Kerberos database. This procedure is described fully in Adding, modifying and deleting principals.

You may occasionally want to use one of your slave KDCs as the master. This might happen if you are upgrading the master KDC, or if your master KDC has a disk crash. See the following section for the instructions.

Switching master and slave KDCs

You may occasionally want to use one of your slave KDCs as the master. This might happen if you are upgrading the master KDC, or if your master KDC has a disk crash.

Assuming you have configured all of your KDCs to be able to function as either the master KDC or a slave KDC (as this document recommends), all you need to do to make the changeover is:

If the master KDC is still running, do the following on the old master KDC:

1. Kill the kadmind process.
2. Disable the cron job that propagates the database.
3. Run your database propagation script manually, to ensure that the slaves all have the latest copy of the database (see Propagate the database to each slave KDC).

On the new master KDC:

1. Start the kadmind daemon (see Start the Kerberos daemons on the master KDC).
2. Set up the cron job to propagate the database (see Propagate the database to each slave KDC).
3. Switch the CNAMEs of the old and new master KDCs. If you can’t do this, you’ll need to change the krb5.conf file on every client machine in your Kerberos realm.

Incremental database propagation

If you expect your Kerberos database to become large, you may wish to set up incremental propagation to slave KDCs. See Incremental database propagation for details.