ServerQuery — административный интерфейс сервера TeamSpeak 3. Подключаетесь терминалом, печатаете команды — сервер отвечает текстом. Никакой графики, зато полный контроль: то, что в клиенте разложено по десяти меню, здесь делается одной строкой.
Обычному владельцу сервера он нужен минимум в трёх ситуациях: вернуть потерянную админку, разбанить себя и посмотреть, что происходит на сервере, когда клиент под рукой, а прав не хватает. Эта статья — рабочий минимум: как подключиться безопасно, какие команды знать и как не попасть под флуд-защиту.
Два интерфейса: raw и SSH
Сервер слушает query-подключения на двух портах, и это два разных протокола.
| Raw | SSH | |
|---|---|---|
| Порт | 10011/TCP | 10022/TCP |
| Шифрование | Нет — всё открытым текстом | Да |
| Чем подключаться | telnet, netcat, PuTTY (режим Raw) | обычный ssh-клиент |
| Логин | командой login после подключения | логин и пароль при подключении |
Команды и ответы в обоих одинаковые. Разница только в транспорте: raw — исторический протокол «как есть», SSH оборачивает его в шифрованный канал. Официальный quickstart прямо называет raw устаревшим выбором и рекомендует протокол с шифрованием.
Что выбрать — зависит от того, откуда вы подключаетесь:
- С самого сервера (по SSH зашли на машину, дальше
telnet 127.0.0.1 10011) — raw достаточно: трафик не покидает машину. - Удалённо — только SSH-вариант:
ssh serveradmin@ts.example.com -p 10022. Пароль — тот же, что у командыlogin.
Почему 10011 нельзя открывать наружу
Raw-протокол передаёт всё открытым текстом — включая логин и пароль serveradmin. Любой узел между вами и сервером может их прочитать. А украденный serveradmin — это не «поломали чат»: это создание и удаление виртуальных серверов, раздача прав, доступ к базе клиентов.
Поэтому правило простое: 10011 доступен только с localhost. В ts3server.ini это строка query_ip=127.0.0.1, страховка на уровне фаервола — в справочнике по портам.
Удалённо работать это не мешает. SSH-туннель пробрасывает локальный порт до сервера:
ssh -L 10011:127.0.0.1:10011 user@ts.example.comПока туннель открыт, telnet localhost 10011 на вашей машине попадает на query-порт сервера, а по сети трафик идёт внутри SSH. Это стандартная схема: так же к серверу ходят панели управления хостеров — с localhost, а не через открытый в интернет порт.
Логин: serveradmin
Учётную запись serveradmin сервер создаёт при первом запуске и печатает пароль в консоль:
------------------------------------------------------------------
Server Query Admin Account created
loginname= "serveradmin", password= "NNbz7d20"
------------------------------------------------------------------Больше пароль нигде не показывается. Если сервер стартовал под systemd — ищите блок в journalctl -u ts3server за дату первого запуска или в логах каталога logs/.
Сменить пароль можно двумя способами:
- Изнутри сессии — команда
clientsetserverquerylogin client_login_name=serveradmin. Сервер сам сгенерирует новый пароль и вернёт его в ответе. - Перезапуском — остановить сервер и запустить один раз с параметром
serveradmin_password=НовыйПароль. Работает и когда старый пароль утерян — полная процедура восстановления доступа разобрана в статье про потерянный privilege key.
Первая сессия: синтаксис и обязательные команды
Подключаемся и видим приглашение:
TS3
Welcome to the TeamSpeak 3 ServerQuery interface, type "help" for a
list of commands and "help <command>" for information on a specific command.Каждая команда — слово, параметры — пары ключ=значение, опции — с минусом: clientlist -uid -ip. Ответ всегда заканчивается строкой статуса; error id=0 msg=ok — успех, всё остальное — код и текст отказа.
Одна особенность, о которую спотыкаются все: пробелы в значениях запрещены. Вместо пробела — \s, вместо слэша — \/, вместо вертикальной черты — \p. Написать banreason=go away нельзя, нужно banreason=go\saway.
Типовая сессия целиком:
login serveradmin NNbz7d20
error id=0 msg=ok
use port=9987
error id=0 msg=ok
serverinfo
virtualserver_port=9987 virtualserver_name=TeamSpeak\s]I[\sServer virtualserver_clientsonline=3 ...
error id=0 msg=ok
quituse — обязательный шаг, который забывают чаще всего. После login вы подключены к инстансу, а не к серверу: команды вроде clientlist вернут ошибку invalid serverID, пока не выбран виртуальный сервер. use port=9987 выбирает его по голосовому порту, use sid=1 — по номеру.
Шпаргалка по командам
| Команда | Что делает | Пример |
|---|---|---|
help | Справка; help команда — по конкретной команде | help clientkick |
login | Авторизация | login serveradmin NNbz7d20 |
use | Выбрать виртуальный сервер | use port=9987 |
whoami | Кто я и на каком сервере | whoami |
serverinfo | Всё о выбранном сервере: имя, слоты, аптайм | serverinfo |
clientlist | Кто онлайн | clientlist -uid -ip |
clientinfo | Подробности о клиенте по его clid | clientinfo clid=5 |
channellist | Дерево каналов с ID | channellist -flags |
servergrouplist | Серверные группы и их sgid | servergrouplist |
privilegekeyadd | Создать ключ привилегий | privilegekeyadd tokentype=0 tokenid1=6 tokenid2=0 |
clientkick | Кикнуть с сервера (reasonid=5) или из канала (4) | clientkick clid=5 reasonid=5 reasonmsg=AFK |
banclient | Забанить клиента онлайн | banclient clid=5 time=3600 banreason=spam |
banlist | Список банов с их banid | banlist |
bandel | Снять бан | bandel banid=3 |
serverstop | Остановить виртуальный сервер | serverstop sid=1 |
serverstart | Запустить виртуальный сервер | serverstart sid=1 |
logview | Показать лог сервера | logview lines=30 |
quit | Закрыть сессию | quit |
Полный справочник встроен в сервер: help перечисляет все команды, а в каталоге дистрибутива serverquerydocs/ лежит текстовый файл по каждой — с правами, параметрами и примером.
Практические сценарии
Выдать себе админку
Классика: сервер работает, а Server Admin — ни у кого. Решение — новый privilege key. Сначала узнаём sgid группы:
servergrouplist
sgid=6 name=Server\sAdmin type=1 iconid=300 savedb=1|sgid=7 name=Normal type=1 ...
error id=0 msg=okСоздаём ключ на группу с этим sgid:
privilegekeyadd tokentype=0 tokenid1=6 tokenid2=0
token=eKnFZQ9EK7G7MhtuQB6+N2B1PNZZ6OZL3ycDp2OW
error id=0 msg=okСтроку token= вводим в клиенте: Permissions → Use Privilege Key. Ключ одноразовый. Что делать с группами дальше — в разборе системы прав.
Посмотреть, кто онлайн
clientlist -uid
clid=5 cid=7 client_database_id=40 client_nickname=ScP client_type=0 client_unique_identifier=P7qd...=|clid=6 ...
error id=0 msg=okclid — временный номер сессии, живёт до отключения клиента; именно его принимают clientkick и banclient. client_type=1 — это query-клиенты, включая вас самих. Опция -ip покажет адреса, -groups — группы.
Забанить и разбанить
Бан по clid из списка выше, время в секундах, причина — с экранированием пробелов:
banclient clid=5 time=3600 banreason=spam\sin\schat
banid=2
banid=3
error id=0 msg=okОбратите внимание: правил создалось два — сервер банит отдельно IP-адрес и уникальный идентификатор клиента (а при наличии — и myTeamSpeak-ID, тогда правила три). time=0 или без time — бан навсегда.
Снять бан — найти номера правил и удалить каждое:
banlist
banid=2 ip=203.0.113.7 created=1259444002242 invokername=admin reason=spam\sin\schat enforcements=0|banid=3 uid=P7qd...= ...
error id=0 msg=ok
bandel banid=2
error id=0 msg=ok
bandel banid=3
error id=0 msg=okbandelall сносит все баны разом — уместно, только если список и так мусорный.
Понять, почему человек не может зайти
Два инструмента. Первый — banlist: поле enforcements считает, сколько раз правило сработало. Ненулевое значение у свежего бана — вот и причина. Второй — лог:
logview lines=30В логе видно каждый отказ: сработавший бан, неверный пароль сервера, исчерпанные слоты. Это быстрее, чем гадать по описанию «у меня не подключается».
Флуд-защита: почему сервер банит за команды
ServerQuery считает команды: по умолчанию — не больше 10 за 3 секунды с одного адреса. Сверх лимита сервер отвечает ошибкой client is flooding, а если поток не останавливается — временно банит адрес. Отсюда типичный сюрприз: скрипт бэкапа или веб-панель работали-работали и вдруг «забанены на своём же сервере».
Правильное решение — не поднимать лимиты, а файл query_ip_allowlist.txt в каталоге сервера (в старых версиях он назывался query_ip_whitelist.txt). Адреса из него флуд-защита не ограничивает. Формат — один адрес или CIDR-подсеть на строку; в свежей инсталляции там уже лежит 127.0.0.1:
127.0.0.1
203.0.113.10Официальная документация рекомендует вписывать сюда адрес веб-панели или скрипта. Обратная сторона очевидна: адрес из allowlist может слать команды без ограничений — вписывайте только свои машины. Есть и зеркальный файл query_ip_denylist.txt — перечисленным в нём адресам query-доступ закрыт полностью.
Сами лимиты, если очень нужно, меняются командой instanceedit serverinstance_serverquery_flood_commands=10 serverinstance_serverquery_flood_time=3.
TeamSpeak 6: raw больше нет
В TeamSpeak 6 Server классический raw-интерфейс на 10011 убрали. Остались два способа: SSH-запросы на 10022 и WebQuery — те же команды поверх HTTP (порт 10080) и HTTPS (10443), появившиеся ещё в сервере 3.12.
Отличия WebQuery от классики: запрос — обычный HTTP-вызов вида /1/clientlist, ответ — JSON, а вместо пары логин-пароль — API-ключ, который создаётся командой apikeyadd scope=manage lifetime=0 и печатается при первом запуске сервера рядом с паролем serveradmin. Для скриптов это удобнее: не нужно держать соединение и разбирать экранирование, достаточно curl.
Принцип безопасности не изменился: HTTP-порт 10080 — такой же нешифрованный канал с админ-доступом, как и 10011, и наружу его открывать нельзя. Либо localhost и туннель, либо HTTPS на 10443 с ограничением по адресам.
Официальные источники
doc/serverquery/serverquery.html— руководство по ServerQuery из дистрибутива сервера: синтаксис, экранирование, флуд-защита, справочник командdoc/server_quickstart.md— там же: протоколы query-доступа, параметрыquery_*,query_ip_allowlistserverquerydocs/*.txt— там же: справка по каждой команде с правами и примерамиdoc/webquery.md— там же: работа с WebQuery через HTTP и JSON- teamspeak/teamspeak6-server — официальный репозиторий TeamSpeak 6 Server: список портов и query-интерфейсов новой версии