Joshua Hirsig aeeacc2437 Document query_ip_allowlist requirement

The proxy's Docker IP must be in TS6's query_ip_allowlist.txt,
otherwise logins will fail with error 520 after anti-flood kicks in.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-14 17:49:24 +01:00

2.3 KiB

Raw Blame History

ts3-query-proxy

A translation layer that bridges the legacy TeamSpeak 3 ServerQuery raw protocol (TCP port 10011) to TeamSpeak 6's SSH Query interface (TCP port 10022).

Why?

TeamSpeak 6 dropped support for the raw ServerQuery protocol on port 10011. Many existing tools (like TS3MusicBot) rely on this protocol. This proxy sits in front of TS6 and transparently translates raw query connections to SSH query sessions, requiring zero changes to existing tools.

How it works

TS3MusicBot ──TCP:10011──▶ ts3-query-proxy ──SSH:10022──▶ TeamSpeak 6
              (raw query)                     (ssh query)

Client connects to the proxy on TCP port 10011
Proxy sends the standard TS3 ServerQuery welcome banner
Client sends login serveradmin <password>
Proxy captures credentials and opens an SSH session to TS6
All subsequent commands are proxied bidirectionally

Quick start (Docker)

docker compose up -d

The proxy expects a TeamSpeak 6 server reachable at hostname teamspeak6 on port 10022 (SSH query). Adjust via environment variables:

Variable	Default	Description
`TS6_HOST`	`teamspeak6`	TS6 server hostname
`TS6_SSH_PORT`	`10022`	TS6 SSH query port
`LISTEN_PORT`	`10011`	Port the proxy listens on

Important: query_ip_allowlist

TeamSpeak 6 restricts which IPs can use the ServerQuery interface. The proxy container's IP (its Docker network IP) must be listed in the TS6 server's query_ip_allowlist.txt:

# Find the proxy container's subnet (e.g. 172.18.0.0/16)
docker network inspect your_ts6_network --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'

# Add it to the allowlist inside the TS6 container
docker exec teamspeak6 sh -c 'echo "172.18.0.0/16" >> /var/tsserver/query_ip_allowlist.txt'

# Restart TS6 to apply
docker restart teamspeak6

Without this, logins through the proxy will fail with error id=520.

Docker Compose example

services:
  ts3query-proxy:
    image: ghcr.io/yourusername/ts3-query-proxy:latest
    # or: build: .
    restart: unless-stopped
    ports:
      - "10011:10011"
    environment:
      - TS6_HOST=teamspeak6
      - TS6_SSH_PORT=10022
    networks:
      - your_ts6_network

networks:
  your_ts6_network:
    external: true

License

MIT

2.3 KiB Raw Blame History