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

include

GlobalХаб задаёт сам

Подключить ещё один файл конфигурации
в конфигурации это строкаincludeвнутри блока Global
То же имя ещё 4:<domain>Global<smtp-pattern-list><source><virtual-mta>— часть из них другие настройки, часть та же самая
Конфигурация из нескольких файлов

Строка подключает ещё один файл, и его содержимое читается так, будто написано прямо здесь. Задумано это для парка: общее держат в одном файле, различия между узлами — в отдельных, и каждый узел подключает своё.

Маски допустимы — одной строкой можно подтянуть каталог файлов.

Вместо пути можно указать адрес HTTP. Требования к нему жёсткие: абсолютный, со схемой http или https, без имени пользователя, строки запроса и якоря. Если нужны заголовки запроса — например, Authorization, — берут блок <include-config>.

Строка работает не только на уровне узла. Её же можно написать внутри <source>, <domain>, <virtual-mta> и <smtp-pattern-list> — там подключаемое становится частью соответствующего блока.

Главная ловушка — доверие к источнику по HTTP. Руководство сопровождает эту форму отдельным предупреждением, и оно не про безопасность в общем смысле: подменённый или просто испорченный файл въезжает в конфигурацию как своя строка. Ошибка настройки, приехавшая по сети, выглядит на узле точно так же, как своя.
Что делает Хаб. Пишет — ровно одну строку, и на ней держится вся раскладка: include /etc/pmta/virtualhost.txt в конце рабочего файла.

Файлов у узла два, и делит их не удобство, а совместимость. В /etc/pmta/config живут управление, приём жалоб и политики получателей; в /etc/pmta/virtualhost.txt — логины подачи, пул и адреса отправки. Раскладка общая с Protosender: те же имена блоков, то же деление, — поэтому узел, настроенный Хабом, подключается к модулю работы с PMTA в Protosender, и наоборот.

Оба файла Хаб собирает целиком и перезаписывает при каждом применении. Подключение, добавленное на узле руками, следующее применение сотрёт — это стоит помнить при разборе «куда делась моя строка».

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

Три формы значения — и третья требует решения, а не настройки:

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

Про HTTP отдельно. Файл тянется при чтении конфигурации, то есть при запуске и при каждой перезагрузке. Недоступный источник — это неудачная перезагрузка в тот момент, когда она нужнее всего.

Формы значения, требования к адресу и предупреждение про доверие — из руководства (§ 3.3.1.53). Замечание про доступность источника при перезагрузке — наше.
Пример в конфигурации
# общее в одном файле, различия узлов — в отдельных
include /etc/pmta/vmtas.txtinclude https://10.1.2.3:4000/my/config/file
Обе строки из руководства. Вторая тянет файл по сети при каждом чтении конфигурации: источник должен быть доверенным и доступным, иначе перезагрузка не пройдёт.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

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

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

Тянут конфигурацию с источника, которому не обязаны доверять

§ 3.3.1.53

Чем чреватоПодключённые строки становятся конфигурацией узла без всякой проверки. Испорченный файл — это не отказ подключения, а рабочий узел с чужими настройками; вендор предупреждает об этом отдельно.
Как заметитьПоведение узла меняется без правок в его собственных файлах.
Как правильноПодключать только свои источники и по https. Если нужен доступ по ключу — брать <include-config> с заголовком авторизации.

Дописывают include в конфигурацию, которую собирает Хаб

наш опыт

Чем чреватоХаб перезаписывает свои файлы целиком при каждом применении. Строка, дописанная руками, исчезает — и вместе с ней всё, что она подключала.
Как заметитьНастройка работала, после очередного применения перестала, и в файле её нет.
Как правильноМенять то, что генерирует Хаб, а не результат. Для настроек, у которых экрана нет, — заводить их в генераторе, а не дописывать в файл.

Кладут в адрес строку запроса или логин

§ 3.3.1.53

Чем чреватоТребования к адресу жёсткие: абсолютный, http или https, без userinfo, строки запроса и якоря. Адрес с параметрами не будет принят.
Как заметитьКонфигурация не применяется, ошибка указывает на строку подключения.
Как правильноПараметры и ключи выносить в заголовки запроса — то есть в <include-config> с http-extra-headers.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
include { FILENAME | scheme://host[:port][/path] }
Значения
путь к файлу, маска или абсолютный адрес http/https без userinfo, строки запроса и якоря
Применение
reload, перезапуск не нужен
Очередь
уже поставленное в очередь не затронет
Где писать
Global, <source>, <domain>, <virtual-mta>, <smtp-pattern-list>
Сколько раз
можно повторять
Всё здесь — из руководства, с разделом.
Наследование
Наследования у самой строки нет — она не значение, а подстановка: подключённое читается на том месте, где стоит строка. Отсюда и правило области: написанная в корне файла, она добавляет строки уровня узла; написанная внутри <source>, <domain>, <virtual-mta> или <smtp-pattern-list> — строки соответствующего блока. Наследуются уже сами подключённые директивы, каждая по своим правилам.
⇄

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

3 связи

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

Закрыть права на файлы конфигурацииПодключаемые файлы — часть конфигурации, и права на них должны быть такими же. § 1.6.3

Работают в паре

Подключение конфигурации по HTTP с заголовками запросаТа же подгрузка по HTTP, но с возможностью задать заголовки запроса — например, авторизацию. inference

На что влияет

Главный файл конфигурации узлаПодключаемое становится частью той же конфигурации: строки читаются так, будто написаны здесь. § 3.3.1.53

Сюда ссылаются

include<source>Та же директива в корне файла; там она добавляет строки уровня узла. § 3.3.1.53include<domain>Та же директива в корне файла; там она добавляет строки уровня узла. § 3.3.10.104include<virtual-mta>Та же директива в корне файла; там она добавляет строки уровня узла. § 3.3.12.14include<smtp-pattern-list>Та же директива в корне файла; там она добавляет строки уровня узла. § 3.3.1.53http-extra-headers<include-config>Обычная форма подключения заголовков не поддерживает — ради них и существует блок. § 3.3.24

Как проверить на узле
Собранную конфигурацию MTA целиком не печатает: проверяют, что подключённые файлы разбираются и какие подключения стоят:
pmta test config
grep -rn '^ *include ' /etc/pmta/
Если ожидаемой строки нет, а файл на месте, проверьте две вещи: тот ли путь и не переписал ли конфигурацию генератор. Для HTTP-формы — доступен ли источник: curl -sI https://10.1.2.3:4000/my/config/file.
◇

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

3 статьи

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

В Хабе
Значение
Хаб подбирает сам — темп, стадия прогрева, метрики
Цена ошибки
опасно: последствия переживут откат
Сценарии
Жизненный цикл конфигурации · Безопасность узла
Соседние настройки блока Global:postmasterdomain-macrovolume-audit-api-keythread-reusethread-max-priorityВсе 108 директив блока →