Настройка Synadm
Сразу после установки запустите настроку утилиты с помощью команды:
synadm config
Вот подробное описание вопросов, которые задаст мастер настройки:
1. Synapse admin user name []:
Что это
Локальная часть имени администратора (без @ и домена).
Т.е. если в Synapse есть администратор с логоном root, то полный MXID будет @root:ваш.домен.tld.
Зачем нужен
- synadm использует это имя для формирования запросов к Admin API, когда нужно указать, от чьего имени выполняется действие.
- Это поле помогает synadm понять, чей именно access token вы используете.
- В некоторых командах (например
synadm user details) это имя подставляется автоматически, если не указан другой пользователь.
Взаимосвязь
- Прямо влияет на поле Homeserver name (см. ниже) — если вы выбрали
auto-retrieval, synadm попытается узнать домен именно из этого MXID.
- Если имя указано неправильно → команды с
--user-id по умолчанию могут не сработать.
Рекомендация
Указывайте реальное имя существующего администратора.
Если введёте выдуманное — потом можно изменить через synadm config -u.
2. Synapse admin user token [NOT SET]:
Что это
Access token администратора (строка вида syt_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX).
Зачем нужен
Это основной способ аутентификации synadm при обращении к Admin API Synapse.
Без правильного токена почти все команды будут возвращать 401 Unauthorized.
Взаимосвязь
- Токен привязан к конкретному пользователю (который вы указали в поле 1).
- Если токен от другого пользователя → команды выполнятся от его имени (если у него есть права).
- Токен должен быть действующим и принадлежать пользователю с правами администратора.
Что делать, если токена пока нет
Можно ввести любой текст на первом этапе (чтобы пройти wizard), а потом обновить:
synadm config -t "syt_настоящий_токен"
Где взять
Element → Настройки → Справка и о программе → Access Token.
3. Synapse protocol (http, unix) [http]:
Что это
Протокол, по которому synadm будет подключаться к Synapse.
Варианты
http — обычное http-подключение (по TCP, например http://localhost:8008)unix — подключение через unix-сокет (файл на диске, например /var/run/synapse.sock)
Взаимосвязь
Определяет, как интерпретировать следующее поле — Synapse base URL.
Если выбрали unix → в следующем поле нужно будет указать путь к сокету, а не URL.
Рекомендация
Оставляйте http — это стандарт для большинства установок Synapse (особенно в deb-пакете).
4. Synapse base URL (or path to socket) [http://localhost:8008]:
Что это
Адрес, по которому synadm будет обращаться к серверу Synapse.
Варианты
Взаимосвязь
- Должен соответствовать настройкам
listeners в homeserver.yaml Synapse.
- Если Synapse слушает только на 127.0.0.1 — localhost подойдёт идеально.
- Если вы указали https — следующий параметр Verify certificate станет важным.
Рекомендация
Для контейнера и локального доступа — оставляйте http://localhost:8008.
5. Synapse Admin API path [/_synapse/admin]:
Что это
Базовый путь к Admin API на вашем сервере.
Зачем
Synapse по умолчанию использует именно /_synapse/admin.
Некоторые форки или кастомные сборки могут иметь другой путь.
Взаимосвязь
synadm добавляет этот путь ко всем запросам.
Например:
http://localhost:8008/_synapse/admin/v2/users
Рекомендация
Оставляйте дефолтное значение — /_synapse/admin.
6. Matrix API path [/_matrix]:
Что это
Базовый путь к стандартному Matrix Client-Server API.
Зачем
Некоторые команды synadm (особенно из группы matrix) используют обычный Matrix API, а не Admin API.
Взаимосвязь
Используется для команд типа synadm matrix whoami, synadm matrix login и т.д.
Рекомендация
Оставляйте дефолт — /_matrix.
7. Default output format (yaml, json, minified, human, pprint):
Что это
Формат, в котором synadm будет показывать результаты по умолчанию.
Варианты
- human — красивые таблицы/списки в терминале (самый читаемый)
- yaml — структурированный, удобно копировать в конфиги
- json — обычный JSON
- minified — сжатый JSON (для скриптов)
- pprint — красивый вывод через Python pprint
Взаимосвязь
Можно переопределить в любой команде флагом --output или -o, например:
synadm user list -o json
Рекомендация
human — лучший выбор для работы в терминале.
8. Default http timeout [30]:
Что это
Сколько секунд synadm будет ждать ответа от Synapse перед тем, как выдать ошибку таймаута.
Взаимосвязь
Если сервер очень медленный (например, через интернет с большим пингом) — можно увеличить до 60–120.
Для localhost — 30 секунд более чем достаточно.
Рекомендация
Оставляйте 30.
9. Homeserver name ("auto-retrieval" or the domain part in your MXID) [auto-retrieval]:
Что это
Домен вашего сервера (server_name в Synapse).
Варианты
auto-retrieval — synadm сам спросит у сервера (через .well-known или /_matrix/versions)- конкретный домен — например
matrix.example.com
Взаимосвязь
- Если вы выбрали
auto-retrieval → следующий параметр Server discovery mode становится активным.
- Используется для формирования правильных путей и проверки токена.
Рекомендация
Оставляйте auto-retrieval — это самый надёжный вариант.
10. Verify certificate [True]:
Что это
Включена ли проверка SSL/TLS-сертификата при подключении по https.
Взаимосвязь
- Если вы используете
http://localhost:8008 — проверка не применяется (игнорируется).
- Если укажете
https://... → при True synadm будет проверять сертификат (и может упасть, если он самоподписанный).
Рекомендация
Оставляйте True. Если используете самоподписанный сертификат — потом можно изменить на False через synadm config -u.
11. Server discovery mode (used with homeserver name auto-retrieval) (well-known, dns) [well-known]:
Что это
Способ, которым synadm узнаёт настоящий домен сервера, если выбран auto-retrieval.
Варианты
well-known — через файл /.well-known/matrix/server или /.well-known/matrix/client (рекомендуемый)dns — через SRV-записи в DNS (_matrix._tcp.example.com)
Взаимосвязь
Работает только если Homeserver name = auto-retrieval.
well-known — это то, что используют почти все клиенты и инструменты.
Рекомендация
Оставляйте well-known.
Итоговая взаимосвязь (коротко)
admin user name → используется для формирования MXID и привязки токена
↓
admin user token → основной ключ аутентификации
↓
protocol + base URL → куда именно synadm подключается
↓
Admin API path + Matrix API path → правильные пути внутри URL
↓
output format → как показывать результаты
↓
timeout → сколько ждать ответа
↓
Homeserver name + discovery mode → помогает правильно формировать запросы и проверять окружение
↓
Verify certificate → безопасность при использовании https
После завершения wizard все эти параметры сохраняются в файле /root/.config/synadm.yaml и используются по умолчанию во всех командах.
Если захотите что-то поменять позже — просто выполните synadm config -u (обновление интерактивно) или измените файл вручную.
Note: '/root/.local/bin' is not on your PATH environment variable. These apps will not be > > globally accessible until your PATH is updated. Run pipx ensurepath to automatically add it, > > or manually modify
