Demo
Demo
База знаний PMTA›Блок Global›Директива§ 3.3.1.58.25

http-enable-api-config

Globalнужен перезапуск

Включать ли правку конфигурации через HTTP
в конфигурации это строкаhttp-enable-api-config falseвнутри блока Global
Вторая конфигурация, которой нет в файле

Интерфейс появился в PowerMTA 5.5 и позволяет читать и менять отдельные части конфигурации по HTTP. Сейчас это два вида записей: списки адресов (в том числе списки подавления) и адреса отправки с их метками получателей. По умолчанию выключен.

🔴 Созданное через этот интерфейс меняется только через него. Руководство говорит прямо: «Any configuration created via this API can only be modified via the API». В файле конфигурации этих записей нет — они живут в отдельных файлах, /var/lib/pmta/config-api на Linux, и подтягиваются при каждой перезагрузке.

Значит, у узла становится два источника правды. Тот, кто читает файл конфигурации, видит не всю конфигурацию. Для парка, который собирает файл целиком и раскладывает по узлам, это прямая проблема: наш файл не описывает узел.

Выключение не удаляет. Записи становятся невидимы и вернутся, если интерфейс включить снова. Забытая правка может всплыть через год.

Каждая правка вызывает перезагрузку. Если она не проходит, правка отклоняется, а текст ошибки возвращается в ответе — иногда сбивающий с толку: попытка удалить используемый список даёт «нет такого списка», потому что удаление откатилось.

Главная ловушка — включить «на посмотреть» и завести одну запись. Дальше файл конфигурации перестаёт быть описанием узла, и разница обнаруживается не сразу, а при первом расхождении поведения с ожиданием. Выключение интерфейса разницу не убирает, а прячет.
Что делает Хаб. Не пишет — интерфейс остаётся выключенным, и это осознанно. Хаб собирает конфигурацию узла целиком и кладёт файлом; вторая конфигурация, живущая мимо файла, сломала бы это правило.

🔴 Если на узел приходит чужая конфигурация, это стоит проверить первым делом. Строка http-enable-api-config yes означает, что часть настроек узла лежит не в файле, и перенос их не захватит: каталог /var/lib/pmta/config-api надо переносить отдельно.

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

Для парка ответ один, и он в умолчании:

Значение Когда
no (умолчание) конфигурацию собирает и раскладывает Хаб
yes узел настраивают чужой программой по HTTP

Совместить два способа нельзя: записи, созданные интерфейсом, правятся только им.

Умолчание false, оба вида записей, правило «созданное через API правится только через API», каталог хранения и автоматическая перезагрузка — из руководства (§ 3.3.1.58.25, § 8.3). Вывод про два источника правды для парка — наш.
Пример в конфигурации
# включать только там, где узел настраивает чужая программа
http-mgmt-port 1000
http-api-key abcd_0123_abcd_0123_abcd_0123_ab
http-enable-api-config yes
Ключ рядом обязателен: чтение может пройти по уровню доступа, а правка — только по ключу.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

Типичные ошибки и проблемы

что делают не так и чем это кончается3 ошибки▶

Переносят узел, забрав только файл конфигурации

§ 8.3

Чем чреватоСписки адресов и адреса отправки, заведённые через интерфейс, в файле не лежат. На новом узле их не окажется, и разница вылезет поведением, а не ошибкой.
Как заметитьПосле переноса подавление не срабатывает или адрес отправки не находится.
Как правильноПереносить каталог /var/lib/pmta/config-api вместе с файлом.

Выключают интерфейс, чтобы «убрать» заведённое через него

§ 8.3

Чем чреватоЗаписи не удаляются, а скрываются. Повторное включение вернёт их — иногда спустя месяцы, когда причину уже не помнят.
Как заметитьПосле включения интерфейса появляются незнакомые списки и адреса отправки.
Как правильноУдалять записи через сам интерфейс, а потом уже выключать.

Принимают сообщение об ошибке правки за правду

§ 8.3

Чем чреватоКаждая правка вызывает перезагрузку, и при неудаче откатывается целиком. Ответ «нет такого списка» на удаление означает, что удаление отклонено, а список на месте и используется.
Как заметитьОшибка описывает не то, что вы делали.
Как правильноЧитать ответ как результат перезагрузки: сначала искать, кто использует запись, и только потом удалять.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
http-enable-api-config <boolean>
Значения
yes | no | true | false
Умолчание
false § 3.3.1.58.25
Применение
нужен перезапуск сервиса
Очередь
уже поставленное в очередь не затронет
Где писать
Global
Сколько раз
один раз в блоке
Всё здесь — из руководства, с разделом.
Наследование
Наследования нет: строка пишется в корне файла, раздел Global. Интерфейс либо включён на весь узел, либо нет; выборочно по видам записей или по адресам он не включается.
⇄

Связанные директивы

4 связи

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

http-api-keyGlobalЧтение может пройти по уровню доступа, но правка требует ключа всегда. § 8.3Адреса отправки через API настройкиОдин из двух видов записей, которые этот интерфейс позволяет заводить. § 3.3.1.58.25

Зависит от

http-accessGlobalЧитать созданное можно по уровню доступа, а менять — только по ключу. inference

Где применяется

http-mgmt-portGlobalИнтерфейс отвечает на том же порту, что и сам монитор. § 8.3

Как проверить на узле
Смотрим, не заведена ли часть конфигурации мимо файла:
ls -la /var/lib/pmta/config-api/ 2>/dev/null
Непустой каталог означает, что записи через интерфейс заводились — даже если сама строка сейчас выключена. Перенося узел, этот каталог надо забирать вместе с файлом конфигурации.
◇

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

3 статьи

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

В Хабе
Цена ошибки
обратимо: вредит, пока стоит
Сценарии
Жизненный цикл конфигурации
Соседние настройки блока Global:smtp-source-hostdomain-keysmtp-proxy-source-hosthost-namepostmasterВсе 108 директив блока →