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.
- Kerberos
- Install and configure the Kerberos server and clients
- Test the setup
- When it does not work
- References
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-workstationon every node andkrb5-serveron one, then configurekdc.conf(KDC behaviour) andkrb5.conf(client behaviour) to agree on the realm.kdb5_util create -sbuilds the principal database; the ACL file decides who may administer it;kadmin.localcreates the first admin.- Services authenticate with keytabs rather than passwords, which is why the last step is exporting one and testing
kinit -ktfrom a client machine.- The configuration files, database creation, principals,
kinit, keytab export andkinit -ktwere run end to end on Rocky Linux 9 with MIT Kerberos 1.21.1, and the output shown is from that run. Thesystemctlsteps, thescpcopy 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
- MIT Kerberos documentation for
kdc.conf,krb5.confandkadminreference - Kerberos V5 System Administrator’s Guide for realm and database administration
- Hadoop in secure mode for how Hadoop services consume the keytabs created here
- Spark security for delegation tokens and
--principal/--keytabon a Kerberized cluster - Ubuntu server Kerberos guide for the Debian and Ubuntu package names and configuration paths
Found this useful?
These posts and tools are free. If one saved you an afternoon, you can 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.