ServerQuery TeamSpeak 3: подключение, команды, автоматизация

Как подключиться к ServerQuery TeamSpeak 3 через telnet и SSH, базовые команды login/use/whoami, clientlist и banadd, экранирование спецсимволов, лимиты флуда и боты на Python.

ServerQuery - встроенный текстовый протокол управления TeamSpeak 3 сервером, тот же интерфейс, через который работают все боты и панели: от простых скриптов автокика до полноценных SinusBot-инсталляций. Освоить его напрямую полезно даже если вы пользуетесь готовыми ботами - когда что-то работает не так, диагностировать проблему через сырой telnet-сеанс быстрее, чем гадать по логам стороннего инструмента. В этой статье разбираем подключение, базовые команды, экранирование и защиту query-порта от злоупотреблений.

Подключение через telnet и netcat

ServerQuery слушает TCP-порт 10011 и говорит простым текстовым протоколом: команда и её аргументы в одной строке, ответ - в следующих. Подключиться можно любым telnet-клиентом или netcat:

telnet 203.0.113.10 10011

или

nc 203.0.113.10 10011

При успешном подключении сервер сразу присылает приветствие:

TS3

Welcome to the TeamSpeak 3 ServerQuery interface, type "help" for a list of commands and "help <command>" for information on a specific command.

Дальше вводятся команды построчно, каждая завершается ответом с кодом ошибки:

error id=0 msg=ok

id=0 означает успех, любое другое число - код ошибки, msg - человекочитаемое описание (в escaped-виде, см. раздел про экранирование ниже).

Открытый telnet не шифрует трафик, включая пароль ServerAdmin при логине - использовать его напрямую через интернет небезопасно. Для локального теста с самого сервера (127.0.0.1) это не проблема, но для управления с удалённой машины используйте ServerQuery по SSH.

Подключение через SSH

Начиная с версии 3.3.0 TeamSpeak 3 сервер поддерживает ServerQuery поверх SSH на порту 10022 - тот же набор команд, но с шифрованием транспорта. Подключение обычным SSH-клиентом:

ssh serveradmin@203.0.113.10 -p 10022

Логин и пароль - те же, что и для telnet-варианта (serveradmin и пароль ServerAdmin). После подключения командная строка идентична telnet-сессии: то же приветствие, тот же набор команд, тот же формат ответов. Для скриптов и автоматизации, работающих через интернет, SSH-вариант предпочтителен всегда, когда библиотека или бот его поддерживают.

Базовые команды: login, use, whoami

Сразу после подключения сессия не авторизована и привязана не к конкретному виртуальному серверу. Порядок действий:

login client_login_name=serveradmin client_login_password=SecretPass123
error id=0 msg=ok

use sid=1
error id=0 msg=ok

whoami
client_id=1 client_channel_id=0 client_nickname=serveradmin\sfrom\sConsole client_database_id=1 client_login_name=serveradmin client_unique_identifier=serveradmin client_origin_server_id=1
error id=0 msg=ok

• login - аутентификация по логину/паролю ServerAdmin (выдаётся при первом запуске сервера, см. статью установка и настройка TeamSpeak 3).
• use sid=1 - переключение сессии на конкретный виртуальный сервер по его sid (можно и по порту: use port=9987).
• whoami - проверка текущего контекста сессии: к какому серверу подключены и под каким логином.

Без login большинство административных команд вернут error id=2568 msg=insufficient\sclient\spermissions.

Просмотр состояния сервера

clientlist

clientlist
clid=3 cid=1 client_database_id=12 client_nickname=Vasya client_type=0|clid=5 cid=2 client_database_id=18 client_nickname=Petya client_type=0
error id=0 msg=ok

Записи в ответе разделяются символом |. Флаги можно комбинировать: clientlist -uid -away -groups добавит в вывод UID клиента, статус AFK и список групп.

channellist

channellist
cid=1 pid=0 channel_order=0 channel_name=Лобби channel_topic= total_clients=4|cid=2 pid=0 channel_order=1 channel_name=Игровой channel_topic= total_clients=1
error id=0 msg=ok

serverinfo

serverinfo
virtualserver_name=Мой\sклан virtualserver_status=online virtualserver_clientsonline=5 virtualserver_maxclients=32 virtualserver_uptime=183940
error id=0 msg=ok

Пробелы в значениях (например, в названии сервера) приходят экранированными как \s - подробнее в разделе про экранирование ниже.

clientinfo

Детальная информация по одному конкретному клиенту - полезно, когда clientlist уже дал clid, а нужны подробности (группы, IP, версия клиента):

clientinfo clid=5
client_nickname=Petya client_version=3.6.2\s[Build:\s1234567890] client_platform=Windows client_input_muted=0 client_output_muted=0 client_idle_time=1200
error id=0 msg=ok

Подписка на события через servernotifyregister

Вместо того чтобы опрашивать clientlist в цикле каждую секунду (это и есть основной источник лишней нагрузки от самодельных ботов), можно подписаться на события и получать их пушем прямо в открытую сессию:

servernotifyregister event=server
error id=0 msg=ok

servernotifyregister event=channel id=0
error id=0 msg=ok

После регистрации сервер сам присылает в ту же сессию уведомления вида notifycliententerview при заходе клиента и notifyclientleftview при выходе - без дополнительных запросов с вашей стороны. Для ботов и скриптов, которым важно реагировать быстро (например, автоматически выдавать группу новичкам), это заметно эффективнее поллинга и меньше нагружает и сервер, и сеть.

Управление: группы, сообщения, кик, бан

Добавить клиента в серверную группу

servergroupaddclient sgid=6 cldbid=25
error id=0 msg=ok

sgid - id серверной группы (список - командой servergrouplist), cldbid - id клиента в базе данных сервера (список - clientdblist). Подробно про группы и права - в статье права и группы TeamSpeak 3.

Отправить текстовое сообщение

sendtextmessage targetmode=2 target=1 msg=Сервер\sуйдёт\sна\sперезагрузку\sчерез\s5\sминут
error id=0 msg=ok

targetmode: 1 - конкретному клиенту, 2 - текущему каналу, 3 - всему серверу. target - id канала или клиента в зависимости от режима.

Кикнуть клиента

clientkick clid=5 reason_id=5 reasonmsg=Нарушение\sправил
error id=0 msg=ok

reason_id: 4 - кик из канала, 5 - кик с сервера.

Забанить по IP

banadd ip=198.51.100.20 banreason=Флуд\sв\sчате time=86400
error id=0 msg=ok

time - продолжительность бана в секундах, если не указан - бан бессрочный. Бан можно ставить и по uid вместо ip, что надёжнее для клиентов за динамическим адресом.

Экранирование спецсимволов

ServerQuery - текстовый протокол, где пробел и ряд других символов имеют служебное значение (разделители параметров и записей), поэтому все строковые значения экранируются перед отправкой и разэкранируются при чтении ответа:

Если пишете свой скрипт без готовой библиотеки, экранирование нужно реализовать вручную в обе стороны: перед отправкой команды - экранировать значения параметров, при разборе ответа - разэкранировать обратно. Забытое экранирование пробела в имени или сообщении - самая частая причина, почему команда возвращает синтаксическую ошибку вместо ожидаемого результата.

Pterohost - сервер TeamSpeak 3 с открытым ServerQuery-портом из коробки, без ручной настройки firewall под ботов. Промокод 4START даёт -20% на первый заказ. Арендовать сервер TeamSpeak 3

Лимиты флуда и защита query-порта

ServerQuery по умолчанию открыт всем, кто знает порт 10011 - это удобно для тестов, но небезопасно для сервера, торчащего в интернет напрямую. Два уровня защиты:

query_ip_allowlist и query_ip_denylist

В рабочем каталоге сервера лежат файлы query_ip_allowlist.txt и query_ip_denylist.txt (в более старых версиях сервера они назывались query_ip_whitelist.txt и query_ip_blacklist.txt). Формат - один IP или CIDR-подсеть на строку:

# query_ip_allowlist.txt
127.0.0.1
203.0.113.0/24

Если allowlist не пуст, подключиться к ServerQuery смогут только перечисленные там адреса - остальным сервер сразу разорвёт соединение. Denylist работает наоборот - блокирует конкретные адреса, даже если они прошли бы через общий доступ.

Встроенная защита от брутфорса

Сервер сам банит IP-адрес после нескольких неудачных попыток login подряд - это защищает пароль ServerAdmin от подбора через открытый telnet-порт. Если легитимный скрипт периодически получает error id=3329 (flood ban) - проверьте, не пытается ли он логиниться слишком часто с неверными данными, и не забудьте после правки credentials дождаться истечения бана либо снять его командой banclient со стороны администратора.

Боты и готовые интеграции

Не всегда нужно писать свой ServerQuery-клиент с нуля - для типовых задач есть готовые проекты:

• ts3audiobot - музыкальный бот с поддержкой YouTube и других источников, управляется как через текстовые команды в канале, так и напрямую через ServerQuery.
• SinusBot - более тяжёлый музыкальный/универсальный бот с веб-интерфейсом, плагинами и своим планировщиком.
• JTS3ServerMod - фреймворк модерации и автоматизации на Java: авто-перемещение AFK-клиентов, защита от флуда чатом, кастомные события на подключение/отключение.

Свой скрипт на Python

Для написания собственной автоматизации (например, синхронизация групп с внешней базой участников клана или Discord) удобна библиотека ts3 (пакет py-ts3 в PyPI) - она берёт на себя экранирование и разбор ответов:

import ts3

with ts3.query.TS3ServerConnection("telnet://serveradmin:SecretPass123@203.0.113.10:10011") as ts3conn:
    ts3conn.exec_("use", sid=1)
    clients = ts3conn.exec_("clientlist")
    for client in clients.parsed:
        print(client["client_nickname"], client["clid"])

Библиотека поддерживает и SSH-транспорт (ssh://), что предпочтительнее для скрипта, работающего за пределами локальной сети сервера. Если после развёртывания скрипта соединение не устанавливается - сначала проверьте базовую доступность порта штатными средствами диагностики, разобранными в статье не подключается к серверу TeamSpeak 3.

Pterohost - готовый TeamSpeak 3 сервер с ServerQuery-портом и SSH-доступом без танцев с конфигами. Промокод 4START даёт -20% на первый заказ. Заказать хостинг TeamSpeak 3

Часто задаваемые вопросы

Как подключиться к ServerQuery TeamSpeak 3?

Через telnet или netcat на TCP-порт 10011: telnet ip 10011 или nc ip 10011. Более безопасный вариант - ServerQuery по SSH на порту 10022 с логином и паролем ServerAdmin, трафик при этом шифруется, в отличие от открытого telnet.

Как получить права ServerAdmin в ServerQuery?

Команда login client_login_name=serveradmin client_login_password=<пароль>. Пароль ServerAdmin выводится в консоль при первом запуске сервера вместе с привилегированным ключом, либо задаётся заново командой serveradmin set password в интерфейсе панели.

Как экранировать спецсимволы в командах ServerQuery?

Пробел заменяется на \s, слэш на /, вертикальная черта на \p, обратный слэш на \, перевод строки на \n, возврат каретки на \r, таб на \t. Экранирование обязательно применять и к исходящим значениям, и учитывать при разборе ответов сервера.

Как ограничить доступ к ServerQuery по IP?

Через файлы query_ip_allowlist.txt и query_ip_denylist.txt в рабочем каталоге сервера (в старых версиях - query_ip_whitelist.txt и query_ip_blacklist.txt), по одному IP или подсети CIDR на строку. Allowlist разрешает подключение только перечисленным адресам, denylist - блокирует конкретные.

Какие боты умеют работать с ServerQuery TeamSpeak 3?

Популярные варианты: ts3audiobot и SinusBot для музыки, JTS3ServerMod для модерации и автоматизации на Java. Для своих скриптов на Python используется библиотека ts3 (py-ts3), которая реализует протокол ServerQuery и берёт на себя экранирование.