Установка Synadm

Admin

Основные характеристики synadm

Назначение — удобный интерфейс командной строки ко всем (или почти всем) возможностям Admin API Synapse.
Сайт / репозиторий — https://codeberg.org/synadm/synadm (проект переехал туда с GitHub)
Документация — https://synadm.readthedocs.io/
Установка (Debian/Ubuntu, включая контейнеры Incus с Debian):
```
sudo apt update
sudo apt install python3-pip
pip3 install synadm --user   # или с sudo pip3 install synadm
```
Или через pipx (рекомендуется для изоляции):
```
sudo apt install pipx
pipx install synadm
```

После установки командой pipx install synadm может появиться примерно такое сообщение:

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
your PATH in your shell's config file (i.e. ~/.bashrc).
done!

Это значит, что команда synadm уже лежит в директории /root/.local/bin, но оболочка (bash) её пока не видит, потому что эта папка не добавлена в переменную PATH для пользователя root.

Самый простой способ исправить

Выполните команду, которую предлагает pipx:
```
pipx ensurepath
```
Она добавит строку вида export PATH="$HOME/.local/bin:$PATH" в твой ~/.profile (или ~/.bashrc, в зависимости от версии pipx и Debian).
После выполнения перезагрузите оболочку (или выйдите и войдите заново в контейнер, если это контейнер Incus), чтобы изменения применились:
```
exec bash   # или просто выйдите из контейнера и зайдите снова: exit → incus exec ...
```

Проверьте, что всё заработало:

which synadm          # должен показать /root/.local/bin/synadm
synadm --version      # должен вывести версию, например 0.49.2

Если pipx ensurepath говорит что-то вроде «already in PATH» или не помогло — сделайте вручную (это надёжнее).

Ручной способ (если ensurepath не сработал)

Откройте файл ~/.profile (для root это /root/.profile) :

nano /root/.profile

В самый конец добавьте:

# pipx binaries
if [ -d "$HOME/.local/bin" ] ; then
    PATH="$HOME/.local/bin:$PATH"
fi

Сохраните (Ctrl+O → Enter → Ctrl+X), затем обновите текущую сессию:

source /root/.profile
# или просто
exec bash

Проверьте снова which synadm — должно работать.

Почему это происходит именно с root

pipx по умолчанию ставит пакеты в ~/.local/bin (для текущего пользователя).
В Debian для root по умолчанию ~/.local/bin не входит в PATH (в отличие от обычных пользователей в некоторых дистрибутивах).
pipx ensurepath как раз и добавляет эту директорию автоматически.

Admin

Настройка 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.

Варианты

http://localhost:8008 — стандартный порт Client-Server API в deb-пакете
https://matrix.ваш.домен.tld — если у вас настроен reverse-proxy с TLS
/var/run/synapse.sock — если используете unix-сокет

Взаимосвязь

Должен соответствовать настройкам 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 (обновление интерактивно) или измените файл вручную.

База знаний (кластер NBICS)

Установка Synadm

Основные характеристики synadm

Самый простой способ исправить

Ручной способ (если ensurepath не сработал)

Почему это происходит именно с root

Настройка Synadm

Вот подробное описание вопросов, которые задаст мастер настройки:

1. Synapse admin user name []:

2. Synapse admin user token [NOT SET]:

3. Synapse protocol (http, unix) [http]:

4. Synapse base URL (or path to socket) [http://localhost:8008]:

5. Synapse Admin API path [/_synapse/admin]:

6. Matrix API path [/_matrix]:

7. Default output format (yaml, json, minified, human, pprint):

8. Default http timeout [30]:

9. Homeserver name ("auto-retrieval" or the domain part in your MXID) [auto-retrieval]:

10. Verify certificate [True]:

11. Server discovery mode (used with homeserver name auto-retrieval) (well-known, dns) [well-known]:

Итоговая взаимосвязь (коротко)