DHCP management and failover platform for Technitium DNS Server.

Tessera monitors DHCP health through distributed voter agents and automatically fails over to a standby server when consensus is reached.

git clone https://github.com/ArtificialFoundry/tessera.git
cd tessera
mkdir -p config data/backups

Generate your secrets:

# Technitium API token (from your Technitium dashboard)
echo "your-technitium-api-token" > config/token
chmod 600 config/token

# Admin key for Tessera write operations
openssl rand -hex 32 > config/admin-key

Define your DHCP servers in config/servers.json:

[
  {"name": "dns-1", "url": "https://192.0.2.1:53443", "role": "active", "priority": 0},
  {"name": "dns-2", "url": "https://192.0.2.2:53443", "role": "candidate", "priority": 10}
]

Start with Docker:

docker compose up -d

Open http://localhost:8780 — you should see the dashboard.

Voters are lightweight health checkers deployed on your infrastructure VMs. You need at least 3 voters to form a quorum.

From the dashboard (easiest):

1. Go to Voters → click Generate Token
2. Follow the wizard — set an optional IP restriction and expiry
3. Copy the one-time token shown at the end
4. On each voter machine, run:

curl -O https://your-tessera/voter/tessera-install-voter.sh
sudo bash tessera-install-voter.sh \
  --tessera-url http://tessera-host:8780 \
  --auto-register \
  --registration-token <paste-token-here>

That's it. The installer auto-detects the hostname, registers with Tessera, receives a PSK, installs the voter script, and starts a 30-second health check timer.

With Docker (on the voter machine):

# After registration, you'll have a voter.conf with VOTER_NAME and VOTER_PSK
docker run -d \
  --name tessera-voter \
  --network host \
  --cap-add NET_RAW --cap-add NET_ADMIN \
  --restart unless-stopped \
  -v /path/to/voter.conf:/etc/tessera/voter.conf:ro \
  tessera-voter:latest

--network host + capabilities are needed for the DHCP broadcast probe.

Back on the dashboard, go to Failover — you should see voter cards appearing with HTTP ✓ and DHCP ✓ badges.

Voters (deployed on 3+ VMs)
  ├── HTTP probe  → Technitium API responsive?
  ├── DHCP probe  → nmap broadcast — actually serving leases?
  └── POST /api/v1/vote (HMAC-signed, every 30s)

Tessera
  ├── Collects votes, evaluates quorum
  ├── 3 consecutive DOWN rounds → failover to candidate
  ├── 5 consecutive UP rounds → failback to original
  └── Syncs scopes, backups config, enforces drift

Vote logic: overall status is "up" if either check passes. Both individual results (http_status, dhcp_status) are shown as badges in the dashboard.

Admin actions (anything that writes) prompt for your admin key on first use. The key is stored in your browser tab and cleared when you close it.

Each voter reads /etc/tessera/voter.conf:

VOTER_NAME="voter-1"
VOTER_PSK="hmac-psk-hex-string"
TESSERA_URL="http://tessera-host:8780"
CHECK_TIMEOUT="5"

Tip: Increase DHCP_TIMEOUT on VMs where DHCP broadcasts cross VLANs or where CPU contention causes occasional timeouts (e.g., DHCP_TIMEOUT="10").

uv sync --all-extras

# Backend
uv run uvicorn tessera.app:create_app --factory --reload --port 8780

# Frontend (separate terminal)
cd frontend && npm ci && npm run dev

# Quality checks
uv run pytest                           # 274 tests
uv run ruff check src/ tests/           # Lint
uv run ruff format --check src/ tests/  # Format
uv run mypy src/                        # Type check (strict)

[
  {"name": "dns-1", "url": "https://192.0.2.1:53443", "role": "active", "priority": 0},
  {"name": "dns-2", "url": "https://192.0.2.2:53443", "role": "candidate", "priority": 10},
  {"name": "dns-mon", "url": "https://192.0.2.4:53443", "role": "observer", "priority": 99}
]

{"name": "dns-3", "url": "...", "role": "candidate", "priority": 20, "token": "per-server-token"}

export TESSERA_ADMIN_API_KEY=$(openssl rand -hex 32)

# Read (no auth)
curl http://tessera:8780/api/v1/servers

# Write (auth required)
curl -X POST http://tessera:8780/api/v1/servers/dns-2/promote \
  -H "Authorization: Bearer <your-key>"

curl -X POST http://tessera:8780/api/v1/voters/tokens \
  -H "Authorization: Bearer <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{"bind_ip": "192.168.1.0/24", "ttl": 3600}'

curl -X POST http://tessera:8780/api/v1/voters/register \
  -H "Content-Type: application/json" \
  -d '{"token": "<one-time-token>", "name": "voter-4"}'

{
  "voter-1": "generated-psk-hex",
  "voter-2": "another-psk-hex"
}

sudo cp voter/tessera-voter.sh /usr/local/bin/
sudo chmod 755 /usr/local/bin/tessera-voter.sh
sudo cp voter/tessera-voter.service voter/tessera-voter.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now tessera-voter.timer

uv sync --frozen
sudo mkdir -p /etc/tessera /var/lib/tessera/backups

TESSERA_SERVERS_FILE=/etc/tessera/servers.json \
TESSERA_ADMIN_API_KEY=$(cat config/admin-key) \
uv run uvicorn tessera.app:create_app --factory --host 0.0.0.0 --port 8780

GPLv3