Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.53

include

Globalset by the Hub

Include another configuration file
in the configuration this is a lineincludeinside the block Global
The same name 4:<domain>Global<smtp-pattern-list><source><virtual-mta>— some of them are other settings, some are the same one
A configuration of several files

The line includes another file, and its contents are read as if written right here. This is meant for a fleet: common settings are kept in one file, differences between nodes in separate ones, and each node includes its own.

Masks are allowed — one line can pull in a directory of files.

An HTTP address can be given instead of a path. The requirements for it are strict: absolute, with the http or https scheme, without a user name, a query string or a fragment. If request headers are needed — Authorization, for example — the <include-config> block is used.

The line works not only at the node level. It can also be written inside <source>, <domain>, <virtual-mta> and <smtp-pattern-list> — there the included content becomes part of the corresponding block.

The main trap is trusting an HTTP source. The manual accompanies this form with a separate warning, and it is not about security in general: a substituted or simply corrupted file enters the configuration as a line of its own. A configuration error that arrived over the network looks on the node exactly like a local one.
What the Hub does. It writes exactly one line, and the whole layout rests on it: include /etc/pmta/virtualhost.txt at the end of the working file.

The node has two files, and what divides them is not convenience but compatibility. /etc/pmta/config holds management, complaint receiving and receiver policies; /etc/pmta/virtualhost.txt holds submission logins, the pool and sending addresses. The layout is shared with Protosender: the same block names, the same division — which is why a node configured by the Hub connects to Protosender’s PMTA module, and vice versa.

The Hub assembles both files in full and overwrites them on every apply. An include added on the node by hand will be wiped out by the next apply — worth remembering when investigating “where did my line go.”

Recommended values

Three forms of the value — and the third calls for a decision rather than a setting:

Value When What to keep in mind
file path the usual case: common and specific settings in different files the same permissions as the configuration itself
mask a directory of files with one line the reading order is not specified
HTTP address the configuration is distributed centrally the source must be trusted and must respond at reload time

A separate note on HTTP. The file is pulled when the configuration is read, that is, at startup and on every reload. An unreachable source means a failed reload exactly when it is needed most.

The forms of the value, the address requirements and the trust warning come from the manual (§ 3.3.1.53). The remark about the source’s availability at reload is ours.
Example configuration
# common settings in one file, node differences in separate ones
include /etc/pmta/vmtas.txtinclude https://10.1.2.3:4000/my/config/file
Both lines are from the manual. The second pulls the file over the network on every configuration read: the source must be trusted and reachable, otherwise the reload will fail.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends3 mistakes▶

Pulling configuration from a source you have no obligation to trust

§ 3.3.1.53

What it costsIncluded lines become the node’s configuration with no check at all. A corrupted file is not a failed include but a working node with someone else’s settings; the vendor warns about this separately.
How to spot itThe node’s behavior changes with no edits to its own files.
How to do it rightInclude only your own sources, and over https. If key-based access is needed, use <include-config> with an authorization header.

Adding an include to a configuration the Hub assembles

our experience

What it costsThe Hub overwrites its files in full on every apply. A line added by hand disappears — and with it everything it included.
How to spot itThe setting worked, stopped after the next apply, and it is not in the file.
How to do it rightChange what the Hub generates, not the result. For settings that have no screen, add them in the generator rather than to the file.

Putting a query string or a login in the address

§ 3.3.1.53

What it costsThe address requirements are strict: absolute, http or https, without userinfo, a query string or a fragment. An address with parameters will not be accepted.
How to spot itThe configuration is not applied, and the error points to the include line.
How to do it rightMove parameters and keys into request headers — that is, into <include-config> with http-extra-headers.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
include { FILENAME | scheme://host[:port][/path] }
Values
a file path, a mask or an absolute http/https address without userinfo, a query string or a fragment
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
Global, <source>, <domain>, <virtual-mta>, <smtp-pattern-list>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
The line itself has no inheritance — it is not a value but a substitution: the included content is read in the place where the line stands. Hence the scope rule: written at the root of the file, it adds node-level lines; written inside <source>, <domain>, <virtual-mta> or <smtp-pattern-list>, lines of the corresponding block. The included directives themselves are inherited, each by its own rules.
⇄

Related directives

3 relations

Does not work without

Lock down permissions on configuration filesIncluded files are part of the configuration, and their permissions should be the same. § 1.6.3

Works together with

Including configuration over HTTP with request headersThe same loading over HTTP, but with the ability to set request headers — authorization, for example. inference

Affects

The node's main configuration fileThe included content becomes part of the same configuration: the lines are read as if written here. § 3.3.1.53

Referenced from

include<source>The same directive at the root of the file; there it adds node-level lines. § 3.3.1.53include<domain>The same directive at the root of the file; there it adds node-level lines. § 3.3.10.104include<virtual-mta>The same directive at the root of the file; there it adds node-level lines. § 3.3.12.14include<smtp-pattern-list>The same directive at the root of the file; there it adds node-level lines. § 3.3.1.53http-extra-headers<include-config>The regular include form does not support headers — that is why this block exists. § 3.3.24

How to check on the node
The engine does not print the assembled configuration as a whole: check that the included files parse and which includes are in place:
pmta test config
grep -rn '^ *include ' /etc/pmta/
If the expected line is missing while the file is in place, check two things: whether the path is right and whether the generator has overwritten the configuration. For the HTTP form — whether the source is reachable: curl -sI https://10.1.2.3:4000/my/config/file.
◇

What else to read

3 articles

◇How the node selects a source and combines its settingsA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.◇Accept, route, deliverA message’s path inside the node: accept, decide where, deliver — and all the settings live between these three steps.◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.

In the Hub
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
dangerous: effects outlast a rollback
Scenarios
Configuration lifecycle · Node security
Neighboring settings of the block Global:postmasterdomain-macrovolume-audit-api-keythread-reusethread-max-priorityAll 108 directives of the block →