Demo
Demo

Knowledge base

PMTA knowledge base›Block <smtp-pattern-list>›Directive§ 3.3.15.1

include

<smtp-pattern-list>

Include a rules file inside a receiver response list
in the configuration this is a lineincludeinside the block <smtp-pattern-list>
The same name 4:<domain>Global<smtp-pattern-list><source><virtual-mta>— some of them are other settings, some are the same one
Response parsing rules — 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 rules of this receiver response parsing list.

Moving to a file is especially appropriate here. Response parsing rules are the longest and most active part of the configuration: receivers change their wording, new codes appear, the list grows. Keeping it apart from the rest of the configuration and updating it centrally is the natural way to work.

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

The main trap is order. In a response parsing list the first match wins, and the substitution is positional: an included file wedges in in place of the line. A file included above your own rules can shadow all of them — and this cannot be seen from the configuration, which shows just one line.
What the Hub does. It does not write it: the Hub assembles the response parsing list itself from the policies template and rewrites it in full. We already have centralized rule updates — through the Hub itself.
Recommended values

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

Value When
a file path a long list is moved out of the configuration
a mask a set of files per receiver
an HTTP address rules are updated centrally

The line’s place matters more than its value. Put the include where the included rules should end up by priority: narrow ones above broad ones.

The value forms and the address requirements come from the manual (§ 3.3.15.1). The note about priority and the place of the include is ours.
Example configuration
# a long rule list is moved out and updated separately
<smtp-pattern-list blockList>
    include /etc/pmta/patterns.txt    include https://10.1.2.3:4000/smtp/patterns.txt
</smtp-pattern-list>
The manual’s example. Rules from the first file will end up above the rules from the second — and above everything written further down in the block itself: the first match wins.
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 above your own rules

§ 3.3.15.1

What it costsThe first match wins. A broad rule from the included file shadows the narrow ones written below it — and this is not visible from the configuration: there is just one include line there.
How to spot itThe rule was added to the block, the apply went through, and the behavior is the same.
How to do it rightPut the include where the included rules should be by priority. Keep narrow rules above the include line.

Updating the file without checking that the node has read it

§ 3.3.15.1

What it costsThe file is read when the configuration is read, not continuously. Updated rules do not take effect until there has been a reload.
How to spot itThe file was changed, but the behavior is the same.
How to do it rightAfter an update, reread the configuration and check the result with the command from the reference.
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
<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 a substitution in its place. The included rules then live by the rules of their list, where order matters and the first match wins — and the order is set precisely by where the include line stands.
⇄

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.1.53

Applies to

How the node responds to the receiving server's wordsThe included lines become the rules of this receiver response list. § 3.3.15.1

How to check on the node
The engine does not print the assembled rule list — the block is read together with the included files:
grep -rn -A30 '<smtp-pattern-list' /etc/pmta/
The lines of an included file take the place of the include line, and the resulting order is the check order. If a rule does not fire, look above it for a broader one — it covers it.
◇

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