Demo
Demo
База знаний PMTA›Блок <acct-file>›Директива§ 3.3.11.18

http-webhook-extra-headers

<acct-file>Хаб задаёт сам

Файл с дополнительными заголовками запроса вебхука
в конфигурации это строкаhttp-webhook-extra-headersвнутри блока <acct-file>
Единственный способ добавить к запросу заголовок

MTA умеет добавлять к запросу вебхука произвольные заголовки только из файла — по одному на строку. Записать их прямо в конфигурацию нельзя.

Главное применение — авторизация. Приёмник должен как-то узнать, что пачка пришла от нужного узла, и заголовок Authorization — то место, где это принято писать.

Второе применение — переопределить тип содержимого. По умолчанию он выводится из расширения пути, и если приёмник ждёт другого, строка Content-Type в этом файле его перебивает.

Отдельный файл — это к лучшему. Токен не попадает ни в адрес, ни в саму конфигурацию: у файла свои права, и читает его только MTA.

Главная ловушка — оставить файлу обычные права. В нём лежит секрет приёмника. Конфигурацию читают и копируют, но у неё хотя бы есть репутация файла с секретами; у файла заголовков её нет, и права ему часто оставляют от создания.
Что делает Хаб. Пишет — кладёт /etc/pmta/mtahub-headers.txt с одной строкой Authorization: Bearer <токен> и ставит права 600. Токен на 48 знаков выдаётся узлу один раз и хранится в nodes.webhook_token_encrypted.

Имя файла своё, не общее. Если узел позже подключат к Protosender, его токен ляжет рядом, а не поверх нашего.

Приёмник принимает токен и заголовком Authorization: Bearer, и заголовком X-MTAHub-Token; сверка идёт постоянным по времени сравнением, а на неверный токен и на несуществующий узел ответ одинаковый — подбирать по разнице ответов нечего.

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

В файле — по заголовку на строку:

Заголовок Зачем
Authorization приёмник узнаёт узел
Content-Type переопределить выведенный из расширения
свой если приёмник требует

Права на файл — 600, владелец тот, от кого работает MTA.

Формат файла и оба применения — из руководства (§ 3.3.11.18). Права 600 и довод про то, что отдельный файл лучше адреса, — наши.
Пример в конфигурации
# в конфигурации — только путь
<acct-file /var/log/pmta/mtahub-webhook.json>
    http-webhook-url https://hub.example.com/api/telemetry/pmta/7
    http-webhook-extra-headers /etc/pmta/mtahub-headers.txt</acct-file>

# в файле /etc/pmta/mtahub-headers.txt — по заголовку на строку:
#     Authorization: Bearer d41d8cd98f00b204e9800998ecf8427e
Содержимое файла показано комментарием: в конфигурации его нет и быть не может. Права на него — 600.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

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

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

Оставляют файлу заголовков права по умолчанию

наш опыт

Чем чреватоСекрет приёмника оказывается читаем всем, кто имеет доступ к узлу, и попадает в резервные копии наравне с обычными файлами.
Как заметитьls -l показывает права шире 600.
Как правильноchmod 600 и владелец — пользователь MTA.

Пишут заголовки прямо в конфигурацию

§ 3.3.11.18

Чем чреватоДиректива принимает только путь к файлу. Попытка записать заголовок строкой не даст ничего, и запрос уйдёт без него — то есть без авторизации.
Как заметитьПриёмник отвечает 401 при полностью верном токене в конфигурации.
Как правильноВынести заголовки в файл и указать путь к нему.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
http-webhook-extra-headers <path>
Значения
путь к файлу; в файле — по одному заголовку HTTP на строку
Применение
reload, перезапуск не нужен
Очередь
уже поставленное в очередь не затронет
Где писать
<acct-file>
Сколько раз
один раз в блоке
Всё здесь — из руководства, с разделом.
Наследование
Наследования нет: строка живёт внутри своего <acct-file> и действует на запросы только этого потока. У двух блоков учёта могут быть разные приёмники и разные файлы заголовков.
⇄

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

2 связи

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

Закрыть права на файлы конфигурацииВ файле лежит токен приёмника, поэтому права на него значат столько же, сколько сам токен. § 1.6.3

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

http-webhook-url<acct-file>Заголовки добавляются к тому самому запросу, которым уходит пачка. § 3.3.11.18

Как проверить на узле
Проверять надо и права, и содержимое — одной командой:
ls -l /etc/pmta/mtahub-headers.txt && head -c 40 /etc/pmta/mtahub-headers.txt
Права должны быть 600. Если приёмник отвечает 401, сверять надо именно этот файл: MTA отправляет то, что в нём написано, и ошибку в заголовке сам не заметит.
◇

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

3 статьи

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

В Хабе
Значение
Хаб подбирает сам — темп, стадия прогрева, метрики
Цена ошибки
обратимо: вредит, пока стоит
Сценарии
Собрать телеметрию
Соседние настройки блока <acct-file>:http-webhook-urlhttp-webhook-max-intervalhttp-webhook-max-connectionshttp-webhook-connect-timeouthttp-webhook-ca-fileВсе 26 директив блока →