# Kerberos Server

MIT Kerberos V KDC + admin server container running on Ubuntu 26.04.

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `KRB5_REALM` | `EXAMPLE.ORG` | Kerberos realm (uppercase) |
| `KRB5_DOMAIN` | `example.org` | DNS domain mapped to the realm |
| `KRB5_KDC_HOST` | `localhost` | Hostname clients use to reach this KDC |
| `KRB5_MASTER_PASSWORD` | `changeit` | Database master key (set once, never changes) |
| `KRB5_ADMIN_PRINCIPAL` | `admin` | Name of the bootstrap admin principal |
| `KRB5_ADMIN_PASSWORD` | `changeit` | Password for `<admin>/admin@<REALM>` |

Copy `env.example` to `~/app-data/kerberos/kerberos.env` and fill in real values before first run.

## Build

```bash
./scripts/build.sh
```

## Run

```bash
./scripts/run-container.sh
```

The realm database is persisted in the `kerberos_data` volume (`/var/lib/krb5kdc`). Realm initialization runs only on first start.

## Ports

| Port | Protocol | Service |
|---|---|---|
| 88 | TCP/UDP | KDC |
| 464 | TCP/UDP | kpasswd |
| 749 | TCP | kadmin |

## Managing principals

Exec into the container and use `kadmin.local` (no password needed):

```bash
# List all principals
kadmin.local -q "listprincs"

# Add a principal
kadmin.local -q "addprinc username@REALM"

# Add a service principal and extract a keytab
kadmin.local -q "addprinc -randkey ldap/ldap.example.org@REALM"
kadmin.local -q "ktadd -k /tmp/ldap.keytab ldap/ldap.example.org@REALM"
```

## OpenLDAP SASL/GSSAPI integration

1. Create the LDAP service principal and extract a keytab:
   ```bash
   kadmin.local -q "addprinc -randkey ldap/ldap.example.org@REALM"
   kadmin.local -q "ktadd -k /tmp/ldap.keytab ldap/ldap.example.org@REALM"
   ```
2. Copy the keytab into the OpenLDAP container at `/etc/ldap/ldap.keytab`.
3. Set `KRB5_KTNAME=/etc/ldap/ldap.keytab` in the OpenLDAP container environment.
4. Install `libsasl2-modules-gssapi-mit` in the OpenLDAP image and enable the `GSSAPI` SASL mechanism.