Как это работает
Восстановление и диагностика
Как вернуть доступ к панели при потере пароля или аутентификатора администратора, проверить состояние сервера и собрать архив для поддержки.
Команда maran нужна на тот случай, когда вход в саму панель недоступен. Она ставится вместе с
панелью, не добавляет ни службы, ни порта, ни сетевых запросов и работает только из оболочки на самом
сервере.
| Команда | Когда использовать |
|---|---|
maran admin-reset-password | Администратор потерял пароль или аутентификатор, а панель не может отправить письмо для сброса. |
maran status | Нужно узнать, какие службы работают и что панель сообщает о себе, даже если сама панель не отвечает. |
maran collect-diagnostics | Нужно передать архив для поддержки тому, кто помогает вам разобраться. |
Запуск от root
Команда доступна только root намеренно: она умеет выдать доступ к учётной записи администратора.
Запускайте её по полному пути, чтобы она работала при любом PATH, который сохраняет ваш sudo:
sudo /usr/local/sbin/maran status
Пользователь без прав root получает одну строку с отказом и больше ничего.
Сбросить пароль администратора
sudo /usr/local/sbin/maran admin-reset-password admin@example.com
Укажите адрес электронной почты или имя пользователя администратора. Дальше команда:
- Принимает только администратора с активным входом. Клиент, приостановленный администратор или приглашённый, но не принявший приглашение, получают понятный отказ; у клиентской зоны есть свой сброс по почте.
- Отменяет ранее выданные ссылки для сброса, так что действующая ссылка всегда одна.
- Снимает блокировку после неудачных входов и завершает все сеансы учётной записи.
- Показывает ссылку для сброса один раз, в вашем терминале. Она действует один час и срабатывает
один раз. Она не попадает ни в журналы, ни в запись аудита, а вывод в канал или файл команда
отклоняет, если вы не добавили
--allow-non-terminal.
Откройте ссылку в браузере и задайте новый пароль. Если у панели не настроен публичный адрес, команда
выведет путь, начинающийся с /, и сообщит об этом; допишите перед ним адрес вашей панели.
Каждое использование фиксируется в журнале аудита панели и в журнале аутентификации сервера
(authpriv) с указанием учётной записи и того, была ли снята двухфакторная защита. Имя оператора берётся
из SUDO_USER и является заявленным, а не подтверждённым.
Если администраторов нет вовсе, команда сообщает об этом и отправляет вас на страницу первичной настройки вместо того, чтобы создать администратора.
Если потерян ещё и аутентификатор
sudo /usr/local/sbin/maran admin-reset-password admin@example.com --clear-two-factor
Так дополнительно удаляется двухфакторная привязка администратора, и при следующем входе хватит нового пароля. Применяйте это, только если аутентификатор действительно потерян: защита учётной записи снижается, пока администратор не подключит его заново, поэтому сразу после входа включите двухфакторную защиту снова. Без этого флага двухфакторная защита не затрагивается никогда.
Если правильные коды двухфакторной аутентификации не принимаются
Коды аутентификатора вычисляются по времени, поэтому сервер, у которого ушли часы, отклоняет любой правильный код. Панель следит за часами: если последняя проверка нашла, что часы не синхронизированы с источником времени, отклонённый код сообщает об этом («Часы сервера не синхронизированы…»), а не только «Код неверен». На главной странице в разделе «Требует внимания» появляется «Часы сервера не синхронизированы», на странице «Мониторинг» видна карточка «Часы» с причиной, а оператор получает письмо, когда часы остаются несинхронизированными десять проверок подряд, и ещё одно, когда они восстановятся.
Сама панель время не меняет. Включите службу синхронизации времени и дайте ей связаться с сервером времени:
sudo timedatectl set-ntp true # Debian и Ubuntu: systemd-timesyncd
sudo systemctl enable --now chronyd # AlmaLinux и Rocky Linux: chrony
timedatectl # ищите «System clock synchronized: yes»
Панель читает собственный вердикт ядра, а ядро перестаёт считать часы синхронизированными, когда его оценка возможной ошибки превышает шестнадцать секунд. Часы, ушедшие на несколько секунд, которые ядро ещё считает синхронизированными, не отмечаются.
Сменить собственный пароль
Любой, кто вошёл в панель (администратор или клиент), может сменить свой пароль без ссылки сброса по почте. Откройте меню под своим именем, выберите Профиль и защита и воспользуйтесь карточкой Пароль: Текущий пароль, Новый пароль и Подтверждение пароля, затем Сменить пароль.
- Новый пароль должен быть не короче минимума, который политика безопасности задаёт для сброса и приглашений; более короткий отклоняется. Сообщение сейчас всегда называет 12 символов, каким бы ни был минимум политики (задача #300).
- Неверный текущий пароль отклоняется с 400
CurrentPasswordIncorrectи сообщением «Текущий пароль указан неверно.» Попытка засчитывается в блокировку учётной записи точно так же, как неудачный вход, а пока учётная запись заблокирована, любая попытка получает тот же ответ. - При успехе панель сообщает «Пароль изменён. Все остальные устройства отключены.» Устройство, на котором вы сменили пароль, остаётся в системе; все остальные сеансы завершаются.
Эндпоинт POST /api/v1/auth/change-password разделяет ограничение частоты со входом. Каждая
смена и каждый отказ записываются в журнал аудита как «Пароль изменён», без какого-либо из паролей.
Остальные коды ошибок перечислены в разделе Коды ошибок API.
Проверить состояние сервера
sudo /usr/local/sbin/maran status
В первом разделе видно, активны и включены ли панель, агент, PostgreSQL и веб-сервер (передача файлов добавляется, когда администратор её включил). Второй раздел содержит собственный отчёт панели: доступность базы данных, связь с агентом, ожидающие миграции, версия, число администраторов и открыто ли ещё окно первичной настройки. Второй раздел может не сработать, не скрыв первый. Код возврата 0 означает, что всё в порядке, иначе 1. Секретов команда не выводит.
Нижний предел свободного места
Агент держит нижний предел свободного места: сколько MiB должно оставаться доступным в файловой
системе, прежде чем он начнёт работу, которая туда пишет. Это 1 ГиБ, если вы не изменили значение
в /etc/maran/agent.env:
MARAN_AGENT_FREE_SPACE_FLOOR_MIB=1024
Установщик записывает 1024 и сохраняет ваше значение при повторном запуске. Юнит передаёт его
агенту как --free-space-floor-mib; без флага агент применяет те же 1024. Значение должно быть
целым числом от 1. С нулём или любым другим значением агент не запустится: нечитаемый предел нельзя
принимать за нулевой. Изменить его может только root; ничто из того, что отправляет панель, предел не несёт.
Пока в файловой системе, куда операция будет писать, доступно меньше предела, следующие операции отклоняются до того, как что-либо записано:
- создание аккаунта,
- создание резервной копии,
- восстановление резервной копии,
- приём загрузки.
Отказ возвращается как ошибка AgentBelowFreeSpaceFloor (HTTP 503). В ответе и в причине сбоя
задачи резервного копирования или восстановления она читается на вашем языке как «На сервере почти
закончилось место на диске…». Файловая система, которую не удалось измерить, тоже отклоняется, а
не пропускается. Приостановка, удаление и любое чтение продолжают работать, так что место можно
освободить из панели.
Предел проверяется перед началом работы, а не резервируется: другой процесс всё ещё может заполнить диск после проверки, и пути записи сохраняют для этого случая собственную обработку по принципу «всё или ничего».
Предупреждение о приближении к пределу
Панель отправляет оператору письмо, когда в корневой файловой системе десять проверок подряд доступно меньше двух пределов, так что предупреждение приходит до начала отказов. Второе письмо сообщает, когда свободного места снова достаточно. Если домашние каталоги аккаунтов лежат в отдельной файловой системе, отказ по-прежнему следует за ней, но предупреждение ему не предшествует: оно следит только за корневой файловой системой.
Собрать архив для поддержки
sudo /usr/local/sbin/maran collect-diagnostics
Команда записывает maran-diagnostics-<время>-<номер>.tar.gz в /root, читаемый только для root. Другой
каталог задаётся через --out DIR (абсолютный путь, принадлежащий root и недоступный другим на запись), а
журналы можно исключить флагом --no-logs.
Что входит в архив:
- отчёт о службах из
maran status, включая сведения о базе данных и миграциях; - версия операционной системы, юниты systemd панели и состояние её служб;
- два конфигурационных файла Maran для веб-сервера;
- ИМЕНА настроек панели, но не их значения;
- субъект, издатель и срок действия сертификата панели;
- правила межсетевого экрана;
- если нет
--no-logs, журнал панели, агента и веб-сервера за последние семь дней (с ограничением размера) и конец собственных журналов панели верхнего уровня.
Что команда никогда не читает: файлы и домашние каталоги клиентов, журналы самих сайтов, резервные
копии, дампы баз данных, закрытые ключи и значения из panel.env.
Из каждого текста удаляются известные секреты и типичные формы секретов, затем готовый архив распаковывается и проверяется ещё раз. Если проверка что-то находит, архив удаляется, а команда завершается с ошибкой, а не оставляет пакет, который вы могли бы отправить.
Просмотрите архив перед отправкой. Очистка убирает то, что этот сервер заведомо хранит, но её полноту доказать нельзя. IP-адреса, имена хостов и доменные имена клиентов не удаляются. Распакуйте архив, прочитайте его и отправляйте только тем, кому доверяете такие сведения.
Читать журналы и менять их подробность
Панель и агент сервера пишут в журнал systemd: читайте их командами journalctl -u maran-api и
journalctl -u maran-agent. Их размер ограничивает journald. Файлы в /var/log/maran ротируются
правилами, которые установщик кладёт в /etc/logrotate.d/: журнал установки ротируется раз в месяц (хранятся
двенадцать), журналы веб-сервера самой панели ежедневно (тридцать), журналы веб-сервера сайтов
ежедневно (четырнадцать), журнал FTPS раз в неделю (четыре). На уже установленном сервере
запустите установщик повторно, чтобы получить правило для журнала установки.
Меняйте уровень журнала панели без перезапуска. Мониторинг → Уровень журнала панели показывает, с каким уровнем панель пишет журнал, и позволяет администратору выбрать: подробный, отладка, информация (обычный уровень), предупреждение, ошибка или критический. Изменение действует со следующей строки, сохраняется после перезапуска и записывается в журнал аудита с прежним и новым уровнем. Повышайте его на время разбора проблемы, затем верните обратно. Ни один уровень не заставит панель записать пароль, ключ или токен. Уровень журнала самого агента сервера так пока изменить нельзя.