All posts

Kerberos Setup in Linux

Install and configure a Kerberos KDC and its clients on Linux end to end: kdc.conf, krb5.conf, the KDC database, ACLs, the admin principal, keytabs and a test from both server and client.

9 min read Linux

TL;DR

  • Kerberos is the authentication standard across the Hadoop ecosystem, so setting up a KDC is a prerequisite for securing HDFS, YARN, Hive and Spark.
  • Install krb5-workstation on every node and krb5-server on one, then configure kdc.conf (KDC behaviour) and krb5.conf (client behaviour) to agree on the realm.
  • kdb5_util create -s builds the principal database; the ACL file decides who may administer it; kadmin.local creates the first admin.
  • Services authenticate with keytabs rather than passwords, which is why the last step is exporting one and testing kinit -kt from a client machine.
  • The configuration files, database creation, principals, kinit, keytab export and kinit -kt were run end to end on Rocky Linux 9 with MIT Kerberos 1.21.1, and the output shown is from that run. The systemctl steps, the scp copy and the error table were not run in that test.

Kerberos

Kerberos is an authentication protocol developed at MIT that lets two parties on an untrusted network prove who they are without sending a password over the wire. It works on tickets: a central server, the KDC (Key Distribution Center), issues them, and every service trusts the KDC rather than each user.

Kerberos is the standard authentication method in the Hadoop ecosystem, so HDFS, YARN, Hive, Kafka and Spark all expect it on a secured cluster.

How a login works

The KDC is two services in one process group. The Authentication Server (AS) checks who you are, and the Ticket Granting Server (TGS) hands out tickets for individual services.

 client                         KDC (krb5kdc)                 service
   |                    AS: Authentication Server                 |
   |  1. AS-REQ: "I am rangareddy@EXAMPLE.COM"                    |
   | -----------------------------> |                             |
   |  2. AS-REP: TGT (krbtgt/EXAMPLE.COM), encrypted with the     |
   | <----------------------------- |  user's key (password/keytab)
   |                    TGS: Ticket Granting Server               |
   |  3. TGS-REQ: "ticket for hdfs/node1" + TGT                   |
   | -----------------------------> |                             |
   |  4. TGS-REP: service ticket                                  |
   | <----------------------------- |                             |
   |  5. AP-REQ: service ticket                                   |
   | -------------------------------------------------------->   |

kinit performs steps 1 and 2 and stores the ticket-granting ticket (TGT) in the credential cache; klist shows it. Steps 3 to 5 happen automatically whenever a Kerberos-aware client talks to a service. A keytab is a file holding a principal’s long-term keys, so kinit -kt can do step 1 without anyone typing a password. That is why services use keytabs.

Install and configure the Kerberos server and clients

The KDC goes on one machine and the client packages on every other node. The examples use the realm EXAMPLE.COM and a KDC host named node1.example.com; replace both with your own.

Every machine must resolve node1.example.com (DNS or /etc/hosts) and the clocks must agree to within five minutes by default, because tickets carry timestamps.

Step 1: Install the Kerberos client

Run this on every node in the cluster:

sudo dnf install krb5-workstation krb5-libs

On RHEL 7 and older, yum replaces dnf. On Debian and Ubuntu the client package is krb5-user.

Step 2: Install the Kerberos server

The KDC usually goes on the master node, though that is a convention rather than a rule. Any server in the cluster will do.

sudo dnf install krb5-server

On Debian and Ubuntu the equivalents are krb5-kdc and krb5-admin-server, and the configuration lives in different directories, so follow the Ubuntu server guide linked at the end for those paths.

Step 3: Configure Kerberos

The configuration lives in two files: kdc.conf for the KDC and krb5.conf for every client, including the KDC machine itself.

3.1 kdc.conf

On the KDC machine, edit /var/kerberos/krb5kdc/kdc.conf:

[kdcdefaults]
 kdc_ports = 88
 kdc_tcp_ports = 88

[realms]
 EXAMPLE.COM = {
  acl_file = /var/kerberos/krb5kdc/kadm5.acl
  admin_keytab = /var/kerberos/krb5kdc/kadm5.keytab
  supported_enctypes = aes256-cts-hmac-sha384-192:normal aes128-cts-hmac-sha256-128:normal aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal
  max_life = 24h 0m 0s
  max_renewable_life = 7d 0h 0m 0s
 }

Keep one block per realm and put every setting for the realm inside it. supported_enctypes lists the encryption types the KDC creates keys for, and this list is AES only. The legacy DES and 3DES types are weak and MIT Kerberos disables weak crypto by default (allow_weak_crypto = false), so there is no reason to generate keys for them.

3.2 krb5.conf

On every machine, edit /etc/krb5.conf. The file is plain INI sections, with no surrounding braces:

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

[libdefaults]
 default_realm = EXAMPLE.COM
 dns_lookup_kdc = false
 dns_lookup_realm = false
 ticket_lifetime = 24h
 renew_lifetime = 7d
 forwardable = true
 rdns = false

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

[domain_realm]
 .example.com = EXAMPLE.COM
 example.com = EXAMPLE.COM

[realms] tells a client where the KDC is, and [domain_realm] maps host names to realms. With dns_lookup_kdc = false the client uses exactly what is in this file and does no SRV lookups. rdns = false stops the client from doing a reverse DNS lookup on service host names, a common source of “server not found in Kerberos database” errors.

Step 4: Create the KDC database

On the KDC machine:

sudo kdb5_util -r EXAMPLE.COM create -s

It prompts for a master password. The -s option stores the derived key in a stash file, so the KDC can start without asking for the password. Keep the master password somewhere safe anyway, because recovering the database needs it. The output of a successful run:

Initializing database '/var/kerberos/krb5kdc/principal' for realm 'EXAMPLE.COM',
master key name 'K/M@EXAMPLE.COM'

Step 5: Set the admin ACL

Edit /var/kerberos/krb5kdc/kadm5.acl:

*/admin@EXAMPLE.COM        *

This grants every principal whose instance is admin (for example root/admin) all administrative permissions on the realm. Use your own realm name.

Step 6: Create the admin principal

Run this on the KDC machine only. kadmin.local edits the database directly, so it needs no network and no password, which is exactly why it must only run where the database lives.

sudo kadmin.local

At the kadmin.local: prompt:

addprinc root/admin@EXAMPLE.COM
listprincs

addprinc asks for a password for the new principal. listprincs should now show the principals the database created itself plus yours:

K/M@EXAMPLE.COM
kadmin/admin@EXAMPLE.COM
kadmin/changepw@EXAMPLE.COM
krbtgt/EXAMPLE.COM@EXAMPLE.COM
root/admin@EXAMPLE.COM

krbtgt/EXAMPLE.COM is the principal whose key signs every TGT. Protect the database and the stash file like a root credential.

Step 7: Start the KDC and admin services

On the KDC machine, start both services and enable them so they come back after a reboot:

sudo systemctl enable --now krb5kdc
sudo systemctl enable --now kadmin
systemctl status krb5kdc kadmin

krb5kdc answers ticket requests on port 88, and kadmin (the kadmind daemon) accepts remote administration on port 749.

Test the setup

Test 1: on the KDC server

Check for tickets. A fresh session has none:

klist
klist: No credentials cache found (filename: /tmp/krb5cc_0)

Get a ticket for the admin principal and check again:

kinit root/admin
klist
Password for root/admin@EXAMPLE.COM:
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: root/admin@EXAMPLE.COM

Valid starting     Expires            Service principal
11/14/26 18:38:37  11/15/26 18:38:37  krbtgt/EXAMPLE.COM@EXAMPLE.COM
	renew until 11/21/26 18:38:37

The ticket is for krbtgt/EXAMPLE.COM, the TGT from step 2 of the diagram. It lasts 24 hours and can be renewed for 7 days, matching ticket_lifetime and renew_lifetime. To remove it, run kdestroy.

Test 2: from a client machine

The server test proves the KDC works. A client test proves what users and services actually depend on: the client config, the network path and the keytab.

1. Create a non-admin user. On the KDC:

sudo kadmin.local -q "addprinc rangareddy@EXAMPLE.COM"

2. Export a keytab for it.

sudo kadmin.local -q "xst -norandkey -k /tmp/rangareddy.keytab rangareddy@EXAMPLE.COM"

-norandkey keeps the principal’s existing keys instead of generating new ones, so the password you set still works. The command adds one entry per encryption type:

Entry for principal rangareddy@EXAMPLE.COM with kvno 1, encryption type aes128-cts-hmac-sha256-128 added to keytab WRFILE:/tmp/rangareddy.keytab.
Entry for principal rangareddy@EXAMPLE.COM with kvno 1, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/rangareddy.keytab.
Entry for principal rangareddy@EXAMPLE.COM with kvno 1, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/rangareddy.keytab.

List what a keytab holds with klist -kte:

klist -kte /tmp/rangareddy.keytab

3. Copy the keytab to the client and use it. A keytab is equivalent to a password, so copy it over a secure channel and make it readable only by its owner:

scp /tmp/rangareddy.keytab client1:/home/rangareddy/rangareddy.keytab
ssh client1 chmod 600 /home/rangareddy/rangareddy.keytab

On the client machine, with /etc/krb5.conf from step 3.2 in place:

kinit -kt /home/rangareddy/rangareddy.keytab rangareddy@EXAMPLE.COM
klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: rangareddy@EXAMPLE.COM

Valid starting     Expires            Service principal
11/14/26 18:38:37  11/15/26 18:38:37  krbtgt/EXAMPLE.COM@EXAMPLE.COM
	renew until 11/21/26 18:38:37

No password prompt appears, because the keytab supplied the key. A Hadoop or Spark service uses the same mechanism, for example with spark-submit --principal rangareddy@EXAMPLE.COM --keytab /home/rangareddy/rangareddy.keytab.

When it does not work

These are the errors you will meet most often, with the usual cause. They are the standard MIT Kerberos messages and were not reproduced in the test run.

Message Usual cause
Cannot contact any KDC for realm 'EXAMPLE.COM' krb5kdc is not running, port 88 is blocked, or the kdc = host name in krb5.conf does not resolve
Clock skew too great while getting initial credentials The client and KDC clocks differ by more than five minutes; sync both with chronyd or NTP
Preauthentication failed while getting initial credentials Wrong password, or a keytab whose key version no longer matches the database (for example after a cpw or xst without -norandkey)
Client not found in Kerberos database The principal name or realm is misspelled, or the principal was never created
Server not found in Kerberos database The service host name did not match the principal; check the host name used and rdns = false

The KDC log at /var/log/krb5kdc.log names the principal and the reason for each failed request, and is the first place to look.

References

Found this useful?

These posts and tools are free. If one saved you an afternoon, you can buy me a coffee.

Buy me a coffee

Comments

Questions, corrections and reviews are welcome. Sign in with GitHub to post; comments are stored in this site's public GitHub Discussions.