honeybbq/tsdns repository overview

⁠tsdns

Enhanced TeamSpeak TSDNS server with regex matching, multiple storage backends, and a management API.

中文文档⁠

⁠Features

• Protocol Compatibility: Implements the TSDNS protocol (TCP port 41144).
• Advanced Matching: Supports regex matching and flexible wildcard patterns.
• Multi-Target Support: A single domain can resolve to multiple IP:Port combinations.
• Management API: HTTP REST API for managing records without server restarts.
• Storage Backends: Supports SQLite, PostgreSQL, MySQL, and Redis.
• Pure Go SQLite: Uses a no-CGO SQLite driver for cross-platform compatibility.
• Caching: In-memory cache with configurable background refresh.
• Zero-Config Local Management: Unix Domain Socket enabled by default in Docker and Linux packages for seamless CLI usage without tokens.
• TSDNS Rules:
  • Exact and wildcard domain matching (* and *.domain).
  • Regex matching (via reg: prefix).
  • Advanced globs (e.g., ts-*-server.com).
  • $PORT placeholder substitution (via port 0).
  • NORESPONSE support (empty target list).

⁠Installation

⁠1. Quick Install (Script)

The easiest way to install the latest tsdns binary on Linux, macOS, or FreeBSD:

curl -fsSL https://raw.githubusercontent.com/HoneyBBQ/tsdns/main/scripts/install.sh | sh

⁠2. Native Packages (Recommended for Linux)

Download the .deb, .rpm, or .apk package from the Releases⁠ page.

Debian / Ubuntu:

sudo dpkg -i tsdns_*.deb
sudo systemctl enable --now tsdns

CentOS / RHEL / Fedora:

sudo rpm -ivh tsdns_*.rpm
sudo systemctl enable --now tsdns

Alpine:

sudo apk add --allow-untrusted tsdns_*.apk

⁠3. Docker

docker run -d --name tsdns \
  -p 41144:41144 \
  -p 8080:8080 \
  -e TSDNS_API_TOKEN=your-secret-token \
  -e TSDNS_STORAGE_DSN=sqlite:/data/tsdns.sqlite \
  -v tsdns-data:/data \
  honeybbq/tsdns:latest

⁠4. From Source

Requires Go 1.25 or later.

go install github.com/honeybbq/tsdns/cmd/tsdns@latest

⁠Library

The protocol server is published as a separate module with no third-party dependencies. Applications that provide their own RecordRepository can use the core without downloading the CLI, HTTP API, metrics, or storage backend dependencies.

go get github.com/honeybbq/tsdns/[email protected]

import tsdns "github.com/honeybbq/tsdns/core"

server, err := tsdns.NewServer("0.0.0.0").
	WithRepository(repository).
	Build()

repository must implement tsdns.RecordRepository. Logging and metrics use the standard library slog.Logger and the small tsdns.Metrics interface.

⁠Usage

⁠1. Configuration

Configure via config.yaml or environment variables.

tsdns:
  listen: "0.0.0.0:41144"
  cache_refresh_interval: "30s"
api:
  listen: "0.0.0.0:8080"
  token: "my-token"
storage:
  dsn: "sqlite:./tsdns.sqlite"

⁠2. Management

Records can be managed via the CLI or the REST API.

CLI examples:

# Add a simple record
tsdns records add --domain ts.example.com --target 1.2.3.4:9987 --token my-token

# Add multiple targets with $PORT (port 0)
tsdns records add --domain *.example.com --target "1.2.3.4:0 [2001:db8::1]:9987" --token my-token

# Add a regex record
tsdns records add --domain "reg:^ts\d+\.example\.com$" --target "1.2.3.4:9987" --token my-token

API example:

curl -X POST http://localhost:8080/api/v1/records \
  -H "Authorization: Bearer my-token" \
  -d '{
    "domain": "ts.example.com",
    "targets": ["1.2.3.4:9987", "5.6.7.8:0"]
  }'

⁠3. Query Verification

printf "ts.example.com\n" | nc localhost 41144

⁠Configuration

Configurable via environment variables:

⁠Storage Options

Set the backend via TSDNS_STORAGE_DSN:

⁠Admin API

⁠Project Structure

• cmd/tsdns/: Application entry point.
• internal/: Core implementation details (API, CLI, config, storage).
• repository/: Database-specific driver implementations.
• record.go: Core domain model and repository interface.

⁠License

MIT License. See LICENSE⁠.