Ein in Java 21 geschriebener DNS-Server für TeamSpeak 3 (TS3-DNS) mit Cluster-Unterstützung, webbasierter Admin-Oberfläche und integriertem Anti-Flood-Schutz.

Der Server ist MySQL/MariaDB-gestützt und kann optional mit einem Couchbase-Cache als verteilter Cluster betrieben werden. Mit einem vorgeschalteten Load Balancer lässt sich ein ausfallsicherer DNS-Cluster aufbauen.

1. Features
2. Voraussetzungen
3. Schnellstart
4. Datenbankstruktur
5. Konfiguration
6. Server starten
7. Admin UI
8. Anti-Flood-Schutz
9. Cluster-Betrieb (Master / Slave)
10. Lizenz

• DNS-Auflösung von Hostnamen/Domains auf TeamSpeak 3 Serveradressen (IP + Voice-Port)
• Datenbank-Cache – DNS-Abfragen werden gecacht, um die Datenbank zu entlasten
• Automatisches Server-Monitoring – der Master fragt regelmäßig alle TS3-Instanzen ab und aktualisiert Servername, Slot-Zahl und aktive Verbindungen in der Datenbank
• Failback-Funktion – bei einem Serverausfall werden alle Nodes benachrichtigt und leiten Clients automatisch auf einen Ersatzserver um
• Cluster-Modus – ein Master-Node und beliebig viele Slave-Nodes; erfordert optionalen Couchbase-Cache
• Admin UI – webbasierte Verwaltungsoberfläche (Standard: Port 8080) mit REST-API für DNS-Einträge, Server, Cluster-Status und Flood-Verwaltung
• Anti-Flood-Schutz – konfigurierbares Rate-Limiting pro IP, automatisches Bannen und persistente Ban-Verwaltung via MySQL-Tabelle flood_bans
• Java 21 – moderne Laufzeitumgebung

1. Datenbank anlegen – Zunächst die Datenbank erstellen, danach das Schema importieren:

   mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS ts3dns CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
   mysql -u root -p ts3dns < release/ts3dns.sql

2. Konfigurationsdatei anpassen – release/TS3DNS-Cluster.cfg bearbeiten (siehe Abschnitt 5).

3. Server starten:

   java -jar Java-TS3DNS-Cluster-Maven-1.0-jar-with-dependencies.jar

4. Admin UI öffnen (falls aktiviert): http://<server-ip>:8080/

Das SQL-Schema (release/ts3dns.sql) legt folgende Tabellen an:

Enthält die TeamSpeak 3 Hauptinstanzen, die über ServerQuery abgefragt werden.

Enthält die DNS-Einträge (Hostnamen → TS3-Serveradressen).

Wird beim ersten Start automatisch angelegt und speichert persistente IP-Sperren des Anti-Flood-Schutzes.

Alle Einstellungen befinden sich in release/TS3DNS-Cluster.cfg.

# Debug-Ausgaben aktivieren
default_debug = false

# Rolle dieses Nodes (exklusiv: genau einer muss Master sein)
default_master_server = true
default_slave_server  = false

# Standard-Fallback, wenn kein DNS-Eintrag gefunden wird
# Muss auf eine echte IP-Adresse eines Fallback-Servers gesetzt werden!
default_ip_for_dns   = 0.0.0.0
default_port_for_dns = 9987

# Netzwerk-Bindung des DNS-Ports
default_server_port = 41144
default_server_ip   = 0.0.0.0

# Machine-ID: 0 = alle Einträge; >= 1 = nur Einträge mit gleicher machine-id
default_machine_id = 0

# TS3-Nachrichten an Clients senden (1 = ja, 0 = nein)
default_send_messages = 1

mysql_host = 10.10.10.3
mysql_user = xxxxxx
mysql_pass = xxxxxx
mysql_db   = ts3dns
mysql_port = 3306

couchbase_enable       = false
couchbase_host         = 10.10.10.5
couchbase_bucket       = ts3dns
couchbase_username     = xxxxxx
couchbase_password     = xxxxxx
couchbase_table        = dnscache
couchbase_master_table = macache
couchbase_machine_id   = 1

# Web-Oberfläche aktivieren
admin_ui_enabled  = true
# Port des eingebetteten HTTP-Servers
admin_ui_port     = 8080
# Bind-Adresse (0.0.0.0 = alle Interfaces)
admin_ui_bind     = 0.0.0.0
# Zugangsdaten – MÜSSEN vor dem ersten Start geändert werden!
# Empfehlung: mindestens 12 Zeichen, Groß-/Kleinbuchstaben, Ziffern und Sonderzeichen verwenden.
admin_ui_username = admin
admin_ui_password = changeme

# Rate-Limiting aktivieren
flood_protection_enabled = true
# Maximale Anfragen pro IP innerhalb des Zeitfensters
flood_max_requests       = 10
# Länge des Zeitfensters in Sekunden
flood_window_seconds     = 1
# Anzahl geblockter Anfragen, ab der eine IP automatisch gebannt wird (0 = nie)
flood_auto_ban_threshold = 100
# Dauer eines automatischen Bans in Sekunden (0 = permanent)
flood_auto_ban_duration  = 3600

java -jar Java-TS3DNS-Cluster-Maven-1.0-jar-with-dependencies.jar

Der Server liest beim Start automatisch TS3DNS-Cluster.cfg aus dem aktuellen Verzeichnis.

Die Admin-Oberfläche ist ein eingebetteter HTTP-Server (basierend auf com.sun.net.httpserver) und wird über die Config-Schlüssel admin_ui_* konfiguriert.

Standard-URL: http://<server-ip>:8080/

Nach dem Login stehen folgende Bereiche zur Verfügung:

Sicherheitshinweis: Zugangsdaten (admin_ui_username / admin_ui_password) unbedingt vor dem ersten Start in der Konfigurationsdatei ändern. Es wird ein sicheres Passwort mit mindestens 12 Zeichen empfohlen.

Der integrierte Anti-Flood-Schutz schützt den DNS-Port (Standard: 41144) vor Überlastung durch zu viele Anfragen von einer einzelnen IP.

Funktionsweise:

• Jede eingehende Verbindung wird anhand der Quell-IP geprüft.
• Überschreitet eine IP das konfigurierte Limit (flood_max_requests pro flood_window_seconds), wird die Verbindung sofort getrennt.
• Ab flood_auto_ban_threshold geblockten Anfragen wird die IP automatisch für flood_auto_ban_duration Sekunden gesperrt.
• Sperren werden in der MySQL-Tabelle flood_bans gespeichert und überleben einen Server-Neustart.
• Einstellungen können zur Laufzeit über die Admin UI geändert werden, ohne den Server neu zu starten.

Der Cluster besteht aus einem Master-Node und beliebig vielen Slave-Nodes.

default_master_server = true
default_slave_server  = false

• Fragt alle TeamSpeak 3 Instanzen regelmäßig via ServerQuery ab.
• Aktualisiert Servernamen, Slot-Zahlen und aktive Verbindungen in der Datenbank.
• Erkennt Serverausfälle und benachrichtigt alle Nodes über den Couchbase-Cache.

default_master_server = false
default_slave_server  = true

• Beantwortet DNS-Anfragen und bedient TS3-Clients.
• Empfängt Failback-Benachrichtigungen vom Master.
• Leitet Clients bei einem Ausfall auf den konfigurierten Failback-Server um.

Ein gemeinsamer Couchbase Server ist zwingend erforderlich, damit Master und Slaves kommunizieren können:

couchbase_enable = true

Hinweis: Im Einzelbetrieb (nur ein Node) ist Couchbase optional und kann deaktiviert bleiben.

Über default_machine_id lassen sich DNS-Einträge auf bestimmte Nodes beschränken:

• 0 → Eintrag wird von allen Nodes bedient
• >= 1 → Eintrag wird nur von dem Node mit der gleichen Machine-ID bedient

Der Code steht unter der GNU General Public License Version 3 (GPLv3).

Wenn du das Projekt verwendest oder mithelfen möchtest, freue ich mich über eine Nachricht oder einen Pull Request. Viel Erfolg und Spaß damit!