Demo
Demo

Knowledge base

PMTA knowledge base›Block <virtual-mta>›Directive§ 3.3.12.14

include

<virtual-mta>

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

The form and the rules are the same: a path, a mask or an HTTP address. The lines are read as settings of this sending address.

The manual’s example names the typical case directly — signing keys. There are many of them, they change during rotation, and they are awkward to keep in a shared file; a separate file per sending address solves this with one line.

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

The main trap is missing the address line. Having moved the sending address settings into a file, it is easy to forget that smtp-source-host also has to be set somewhere. Without it the sending address does not stay empty but silently takes the node’s general set — and messages go out from the wrong address, without any error.
What the Hub does. It does not write it: the Hub generates sending address definitions in full — address, name, signing key, limits, receiver rules — and rewrites them on every apply. It puts signing keys on the node as files but refers to them with a domain-key line, not by including configuration.
Recommended values

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

Value When
a file path signing keys or limits are moved out separately
a mask a file per sending address
an HTTP address settings are distributed centrally

What is better not put into such a file — the smtp-source-host line: it is what the sending address exists for, and it should be visible in its definition.

The value forms and the example with signing keys come from the manual (§ 3.3.12.14). The advice not to move out the address line is ours.
Example configuration
# signing keys are moved out of the sending address definition
<virtual-mta mta1>
    include /etc/pmta/domain-keys.txt    include https://10.1.2.3:4000/dkim/keys.txt
</virtual-mta>
The manual’s example. There is no smtp-source-host line visible in this block — if it is not in the included files either, the sending address will silently take the node’s general set.
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▶

Moving everything out, including the address line

§ 9.2

What it costsThe sending address definition becomes unreadable: the block does not tell which address it sends from. And if the line is not in the file either, the address silently inherits the node’s set.
How to spot itSeveral sending addresses have the same delivery address in accounting.
How to do it rightKeep smtp-source-host in the block itself. Move out what is long and changes — keys and limits.

Distributing signing keys over HTTP without an authorization header

our experience

What it costsThe regular include form does not support headers, and the address cannot contain a login. A file with private keys becomes accessible to anyone who knows the address.
How to spot itIt is discovered during an access review, not in operation.
How to do it rightUse <include-config> with http-extra-headers — there the Authorization header is set by a file.
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
<virtual-mta>
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. The included directives are then inherited in the usual sending address order — the node, <virtual-mta-pool>, the address itself — and the closer to the message, the stronger.
⇄

Related directives

2 relations

Same name in other blocks

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

Applies to

The sending address — what it is made ofThe included lines become the settings of this sending address. § 3.3.12.14

How to check on the node
What is ultimately in effect for the sending address is shown by the node itself:
pmta show vmta-settings mta1
The output should have Source Host IP and Source Host filled in, and signing keys listed as separate lines. Empty means the included file did not bring them, and the node’s general set is in effect.
◇

What else to read

3 articles

◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.◇Warm-up built into the engineA warmed-up address hands the first N messages of the day for each receiver to its cold partner; the partner sends them itself and builds history.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sending address rotation
Neighboring settings of the block <virtual-mta>:host-namedomain-keysmtp-source-hostsmtp-proxy-source-hostproxy-protocolAll 15 directives of the block →