Demo
Demo

Knowledge base

PMTA knowledge base›Block <source>›Directive§ 3.3.7.74

include

<source>

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

The form and the rules are the same as at the node level: a path, a mask or an HTTP address. What changes is the substitution place — the lines are read as settings of this <source> block, not of the node.

It can be repeated — the manual shows two lines in a row, a file and an address.

The practical meaning here is slightly different than at the node level. Sources differ between nodes more often than anything: each has its own submission subnets and its own permissions. Moving this part into a separate file is the most obvious way to keep the shared template and the local differences apart.

The main trap is forgetting that the substitution is positional. The line does not “include source settings” but inserts the file’s contents in its own place. The same file included at the root would add node-level lines — and most likely the configuration would not apply at all.
What the Hub does. It does not write it: it assembles the configuration in full and rewrites it on every apply. The Hub generates submission sources itself — by login and by “domain plus address” pair — and there is nothing to split between files.
Recommended values

Three forms of the value, as at the node level:

Value When
a file path node differences are moved out separately
a mask a set of files in one line
an HTTP address source settings are distributed centrally

The file must contain lines allowed in <source>. There is no “is this the right thing” check before applying: a mismatch will surface as a configuration parse error.

The value forms and the address requirements come from the manual (§ 3.3.7.74). The note about positional substitution is ours.
Example configuration
# node differences are moved out of the shared template
<source 0/0>
    include /etc/pmta/sourcecfg.txt    include http://10.1.2.3:4000/my/source/config
</source>
The manual’s example: both forms in one block, and both take effect. The file must contain lines allowed inside <source> — the substitution happens in this place.
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 ends2 mistakes▶

Including a file in the wrong context

§ 3.3.7.74

What it costsThe substitution is positional. A file with source settings included at the root yields node-level directives — and the configuration does not apply.
How to spot itThe reload fails, and the error points to a line from the included file, not to the include line itself.
How to do it rightKeep the “file — include place” pair obvious: the file name should name the context.

Adding an include to a configuration the Hub assembles

our experience

What it costsThe Hub rewrites its files in full on every apply, and the line disappears along with what it included.
How to spot itA setting stopped working after the next apply.
How to do it rightCreate such settings in the Hub itself, not in the output of its work.
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 <path-or-url>
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
<source>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
The line itself has no inheritance: it is a substitution, not a value. The included directives are then inherited by their own rules — as <source> settings, where a narrower block overrides a broader one.
⇄

Related directives

1 relation

Same name in other blocks

includeGlobalThe same directive at the root of the file; there it adds node-level lines. § 3.3.1.53

How to check on the node
The engine does not print a source’s assembled settings — includes are visible only in the files themselves:
grep -n -A20 '<source' /etc/pmta/config | grep -i 'source\|include'
If the included lines are not visible, check the path and that the file contains lines of a source specifically: the substitution is positional, and a directive from another context will be a parse error here.
◇

What else to read

3 articles

◇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.◇The group that grants management rightsMembership in the pmta group gives an unprivileged user the right to call the node’s commands and use submission.◇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.

In the Hub
Cost of a mistake
dangerous: effects outlast a rollback
Scenarios
Node security
Neighboring settings of the block <source>:smtp-serviceretain-x-dkim-keyprocess-x-virtual-mtadefault-virtual-mtaprocess-x-dkim-keyAll 74 directives of the block →