База знаний PMTA›Точка API§ 8.4

Выполнить команду по сети

критично

/command

🔴 Консоль узла, доступная запросом

Выполняет команду консоли узла, переданную запросом, — почти любую из тех, что понимает pmta.

Вызов — POST /command с полями формы command — текст команды без слова pmta — и format. Формат ответа — json или xml со структурой либо json-text и xml-text: консольный текст, обёрнутый в документ.

Исключения названы в руководстве: register, deregister и интерактивные команды вроде resolve –interactive так не выполняются.

🔴 Это полноценная консоль по сети: сюда проходит и удаление писем, и смена режима очереди, и перечитывание конфигурации. Руководство авторизует запрос ключом из http-api-key в заголовке X-API-Key, а ключ даёт полный доступ с любого адреса — хранить его надо как пароль администратора.

Главная ловушка — судить об успехе по коду ответа. Отказ команды приходит с кодом 200: исход лежит в поле status, а причина — в message. Разбор, который смотрит только на код, примет отказ за выполненную команду.

И второе, замеченное Хабом на живом MTA: json-text на части команд отдаёт пустую строку там, где json отдаёт структуру.

Что делает Хаб. Пользуется постоянно — это его канал управления узлом. Операции кабинета — приостановить и возобновить очередь, щадящий и обычный режим, повтор, снять и вернуть адрес, удалить очередь, перечитать конфигурацию, сбросить кэш DNS, повернуть журналы — уходят сюда с ключом узла и форматом json. Отсюда же читающие команды: состояние, очереди на паузе и в щадящем режиме, снятые адреса.

Из операций по SSH идут только остановка, запуск и перезапуск службы; применение конфигурации — запись файлов, проверка и перечитывание — тоже идёт по SSH.

Рекомендуемые значения

Какой формат брать:

format	Что приходит	Когда
json	структура в data	программе — так читает Хаб
xml	структура в XML	программе, которой удобнее XML
json-text	консольный текст строкой в data	показать человеку как есть
xml-text	консольный текст в XML	то же для XML

Поля command и format, четыре формата, исключения и авторизация ключом — из руководства (§ 8.4, § 3.3.1.58.5). Исход в поле status при коде 200 и пустой json-text на части команд — наблюдение Хаба.

Пример в конфигурации

# команда консоли по сети: ключ из http-api-key
curl -s -H 'X-API-Key: KEY' 'http://127.0.0.1:8080/command' -F command='show version' -F format=json

Руководство авторизует команды ключом; запрос без ключа к тому же упрётся в защиту http-csrf-protection, включённую по умолчанию.

жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.

Совместимость

PowerMTA 6.0

описана в руководстве этой версии · платформа: любая

С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.

⇄

Связанные записи

4 связи

Без чего не работает

Как узел решает, впустить ли запрос по HTTPМеханизм, который здесь и виден. § 8.4

Зависит от

Форматы вывода командМеханизм, который здесь и виден. § 8.4

Конфликтует

Подключить узел к консоли вендораТа же выдача из командной строки. § 8.4 Разрешить имя и подключитьсяТа же выдача из командной строки. § 8.4

Как проверить на узле

Проверить, что команда проходит и исход читается из тела:

curl -s -H 'X-API-Key: KEY' 'http://127.0.0.1:8080/command' -F command='show version' -F format=json
grep -n 'http-api-key' /etc/pmta/config

В ответе смотрят поле status: success — команда выполнена. Код 403 — ключ не совпал ни с одной строкой http-api-key.

◇

Что ещё почитать

3 статьи

◇Что узел рассказывает о себе и по каким каналамСемь поверхностей наблюдения: веб-монитор, консоль в четырёх форматах, журнал, учёт, поиск по учёту, метрики и выгрузка во внешнюю аналитику.◇Два обработчика входящих отчётов и что с ними делатьОтказы письмом и жалобы разбираются двумя одинаково устроенными блоками; у каждого свой список адресов и своя пара решений о судьбе письма.◇Пять способов очереди отдать письмоОчередь не обязана ходить по SMTP: она умеет писать в файл, запускать программу, стучаться по HTTP или выбрасывать.

В Хабе

Цена ошибки: опасно: последствия переживут откат
Сценарии: Аварийная остановка · Собрать телеметрию
Важность: критично