Kerberos/Docker is a project that enables the easy deployment of a MIT Kerberos V5 architecture in a cluster of Docker containers. It is beneficial for running integration tests on projects using Kerberos, as well as for learning and testing Kerberos solutions and administration.
See MIT Kerberos V5 and Docker, and browse the code with SourceGraph.
Use an operating system compatible with docker, and install:
- Docker engine (without
sudofor running thedockercommand and withoverlay2driver). - Docker compose
- GNU Make (if not already available).
- GNU Bash (if not already available).
Only if you want to generate other Docker configurations, install:
- Python 3 (if not already available, with
pipandvenv).
Only if you want to use Java on your host machine:
- Java 8 and Maven 3 (if not already available).
To check the compatible version, see the traces of the Check version on GitHub actions (CI) web interface, see here.
To run tests, install Bats, see ./.ci/install.sh.
Note:
- For Linux and macOS workstations, it works on all distributions.
- For Windows workstations, it works on Windows Subsystem for Linux, but you should connect to the Docker container to interact with the Kerberos server.
After installation, there are three containers with a web server on each one to check if it turns:
krb5-machine-example-comkrb5-kdc-server-example-comkrb5-service-example-com
The goal is to connect from krb5-machine-example-com to krb5-service-example-com with SSH and Kerberos authentication (using GSSAPIAuthentication).
Here is the cluster architecture:
Read more about the documentation in doc folder.
Execute:
make install
It will use the ./build-ubuntu-example-com folder, with Docker containers under Ubuntu and with the Kerberos realm EXAMPLE.COM.
If you want to use another OS for the Docker containers and/or other Kerberos realm, you need to use make gen-conf, see the Prerequisites section.
See Makefile with make usage for all commands.
Execute:
make clean
To delete network-analyser, do ./network-analyser/clean-network-analyser.sh.
For the Ubuntu operating system in the Docker container:
To delete ubuntu:24.04 and minimal-ubuntu:latest Docker images, do docker rmi ubuntu:24.04 minimal-ubuntu.
This project is tested with Bash Automated Testing System (BATS).
After installing BATS (see version in Prerequisites part) and the environment of containers to test, do:
make test
This project uses continuous integration with GitHub Actions.
View all workflow runs on the CI here.
You can create a Wireshark instance running in a Docker container built from a Docker image named network-analyser.
See more details in ./network-analyser/README.md.
You can connect with an interactive session to a Docker container:
docker exec -it <container_name_or_id> bash
To debug Kerberos client or server:
export KRB5_TRACE=/dev/stdout
To debug the SSH client:
ssh -vvv username@host
To debug the ssh server:
/usr/sbin/sshd -f /etc/ssh/sshd_config -d -e
Kerberos services
On krb5-kdc-server-example-com Docker container, there are 2 Kerberos services krb5-admin-service and krb5-kdc:
supervisorctl status
See all opened ports on a machine:
netstat -tulpn
Check that each machine has a synchronized time (with ntp protocol and date to check).
See Troubleshooting and Kerberos reserved ports.
Conflict private IP addresses
To create example.com network Docker, the private sub-network 10.5.0.0/24
should be free and private IP addresses 10.5.0.0/24 should be free also. Check
your routing table with route -n, test free IP addresses with
ping -c 1 -w 2 <host>, and check request paths with traceroute <host>.
If the issue persists, you can do make clean or docker network rm example.com.
Working on your computer (host machine) for debugging code
Modify your /etc/hosts to resolve bidirectionally IP addresses with the DNS of the Kerberos cluster:
# /etc/hosts
# ...
# Kerberos cluster
# IP FQDN hostname
10.5.0.1 krb5-machine-example-com.example.com krb5-machine-example-com
10.5.0.2 krb5-kdc-server-example-com.example.com krb5-kdc-server-example-com
10.5.0.3 krb5-service-example-com.example.com krb5-service-example-com
# ...
You can ping krb5-kdc-server-example-com|10.5.0.2 Kerberos KDC server, and check if
Kerberos server port is opened: nmap -A 10.5.0.2/32 -p 88 (or if SSH
server port: nmap -A 10.5.0.3/32 -p 22).
Now you can debug code and run kinit bob directly on the host machine.
The order of entries and names is essential in /etc/hosts.
To resolve a name from an IP address, the resolver takes the first one (horizontally) if multiple names
are possible; and to resolve IP address from the name, the resolver takes the first entry (vertically)
if multiple IP addresses are possible: You can use resolveip <IP|name>, getent hosts <IP|name>
Or take a look at /etc/hosts.
- Add LDAP as a database for the Kerberos architecture
- Add other connectors and services (PostgreSQL, MongoDB, nfs, Hadoop), only OpenSSH for the moment
- Add Java, Python, or C to connect with Kerberos authentication
- ROBINSON Trevor (eztenia). Kerberos. Canonical Ltd. Ubuntu Article, November 2014. Link: https://help.ubuntu.com/community/Kerberos.
- MIGEON Jean. Protocol, Installation and Single Sign On, The MIT Kerberos Admnistrator's how-to Guide. MIT Kerberos Consortium, July 2008. p 62.
- BARRETT Daniel, SILVERMAN Richard, BYRNES Robert. SSH, The Secure Shell: The Definitive Guide, 2nd Edition. O'Reilly Media, June 2009. p. 672. Notes: Chapter 11. ISBN-10: 0596008953, ISBN-13: 978-0596008956
- GARMAN, Jason. Kerberos: The Definitive Guide, 2nd Edition. O'Reilly Media, March 2010. p. 272. ISBN-10: 0596004036, ISBN-13: 978-0596004033.
- O’MALLEY Owen, ZHANG Kan, RADIA Sanjay, MARTI Ram, and HARRELL Christopher. Hadoop Security Design. Yahoo! Research Paper, October 2009. p 19.
- MATTHIAS Karl, KANE Sean. Docker: Up & Running. O'Reilly Media, June 2015. p. 232. ISBN-10: 1491917571, ISBN-13: 978-1491917572.