HOWTO setup a small server

Heimdal (Kerberos 5 Server)

Client Installation

Prerequisite: NTP Kerberos permits only small differences in the system times of the server and its clients. Therefore it is recommended to install a time server on the server and clients to avoid problems.

There are plenty of documents on the web on how to setup an MIT Kerberos server/clients. I prefer the Heimdal Kerberos server due to its multithreading support. The neccessary packages for the clients are:

apt-get install krb5-config libkrb5-25-heimdal heimdal-clients heimdal-kcm

During the installation some of the questions below must be answered (krb5-config). Typical answers look like that:

default Kerberos realm:

this is the name of your new REALM that should be identical to the domain name of the server in capital letters (EXAMPLE.COM)

DNS contains pointers

unless you know what this means, the default answer no is just fine

Kerberos servers for realm:

the FQDN (fully qualified domain name) of the server (server.example.com)

administrative server for realm

again, the FQDN' of the server (server.example.com)

To correct or change your answers at some time in the future, use:

# dpkg-reconfigure krb5-config

or edit /etc/krb5.conf manually as described in the next section.

Client Configuration

The Kerberos library configuration file /etc/krb5.conf is divided into sections. Each section begins with the section name in square brackets, e.g., [libdefaults]. Although section names might appear several times in the following excerpts, each of them should only be entered once in the complete configuration file. The excerpts are not complete: There might already be further entries in the sections in /etc/krb5.conf on the system. In principal, the configuration excerpts below should work with both the Heimdal and the MIT Kerberos library.

The following configuration of the Kerberos library should have been done by krb5-config and specifies the new REALM:

[libdefaults]
	default_realm = EXAMPLE.COM

[realms]
	EXAMPLE.COM = {
		kdc = server.example.com
		admin_server = server.example.com
	}

In some cases you want to change some behaviour of the Kerberos library. Ticket lifetimes can be increased by these lines in the libdefaults section:

[libdefaults]
	ticket_lifetime = 10d 0h 0m 0s
	renew_lifetime = 30d 0h 0m 0s

(Note: The maximum lifetime configured for the server and the principal might limit the maximum ticket lifetime as well! So this will only help, if server and principal configurations also permit these lifetimes.)

Server Installation

On the server the following additional packages are required:

apt-get install heimdal-kdc heimdal-docs

Server KDC Configuration

To avoid problems when using basic authentication in Apache2 (Request is a replay errors in the log files), the configuration of the Kerberos library on the server might require the following line in the libdefaults section:

[libdefaults]
	# required when using basic authentication with Apache2's
	# mod_auth_kerb module (`Request is a replay' errors);
	# `0' for MIT library and `false' for Heimdal library
	kdc_timesync = 0/false

Also useful in some cases:

[logging]
	kdc = SYSLOG:DEBUG:AUTH
	admin_server = SYSLOG:DEBUG:AUTH
	default = SYSLOG:DEBUG:AUTH

The default configuration of the KDC and the Kerberos library in general need no further changes. But if you want to restrict Kerberos to IPv4, you will have to set:

addresses = 0.0.0.0

The KDC database is already initialized during the installation of the KDC with the following commands. You will only have to run these commands again, if you want to reset the KDC database for some reason:

# rm -f /var/lib/heimdal-kdc/heimdal.db /var/lib/heimdal-kdc/m-key
# kstash --random-key
# kadmin -l
> init EXAMPLE.COM
> q

Later on we will need a testuser, so let us create it now:

# kadmin -l
> add testuser
> q

Finally, you can (re)start the Kerberos server and check, whether you are able to get a token:

# /etc/init.d/heimdal-kdc restart
# kinit testuser@EXAMPLE.COM

Server PAM Configuration

If you like to add Kerberos authentication to PAM, install the following package:

apt-get install libpam-heimdal

You will have to configure libpam-heimdal now. See the manual page of pam_krb5 for more details.

Server Remote Administration Configuration

The kadmind daemon is started by the inetd. By default, the following line (or similar) should exist in /etc/inetd.conf:

kerberos-adm    stream  tcp     nowait  root    /usr/sbin/tcpd /usr/lib/heimdal-servers/kadmind

If you do not want to use remote administration, comment this line and restart inetd. The kadmind daemon will not be running in this case (you can skip the rest of this section):

# /etc/init.d/openbsd-inetd restart

If you want to use remote administration, you will need an administrative principal. In order to add one, let us say root, you must on the one hand create the principal

# kadmin -l
> add root/admin
> q

and on the other hand configure his ACLs:

root/admin@EXAMPLE.COM	all

Due to a bug in the Debian package(?), you will also have to create a symlink to that ACL file:

# ln -s /etc/heimdal-kdc/kadmind.acl /var/lib/heimdal-kdc

Now you should be able to remotely administer your Kerberos database with kadmin.

Make sure kadmind is running properly. In my case, inetd did not start kadmind while the packages were installed (maybe due to the order of configuring and starting the services during their installation). Check for the kerberos-admline in /etc/inetd.conf and restart inetd as shown at the begining of this section.

Networking Requirements

Prerequisite: Shorewall In case of a packet filter (Shorewall), you will have to permit some traffic to make use of the Kerberos server. Check with netstat -tulpen which are actually required, as - depending on your configuration - some services may (not) be running on your system:

# Heimdal/Kerberos 5
#
# Kerberos v5 KDC
ACCEPT		net		$FW		tcp	88
ACCEPT		net		$FW		udp	88
# kpasswd
#ACCEPT		net		$FW		tcp	464
ACCEPT		net		$FW		udp	464
# kadmin v5 (required for remote administration)
#ACCEPT		net		$FW		tcp	749
# Kerberos v4 KDC
#ACCEPT		net		$FW		tcp	750
#ACCEPT		net		$FW		udp	750
# Kerberos 524
#ACCEPT		net		$FW		tcp	4444
#ACCEPT		net		$FW		udp	4444
#

and restart the packet filter:

# shorewall restart

Back to index.