Tessera

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.

Quick Start

1. Deploy Tessera

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.

2. Add Voter Agents

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.

3. Verify

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

How It Works

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.

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.

Voter Configuration

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").

Development

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)

Documentation

Advanced

[
  {"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

License

GPLv3