Knowledge base

PMTA knowledge base›Mechanism§ 3.2

Four value types the whole config is written in

critical

Syntax definitions

Defined once, used everywhere

The manual defines four value types in a separate short section and then simply refers to them from hundreds of directives. Knowing these four means understanding the grammar of any configuration line.

Boolean. Four spellings for two values: yes, no, true, false. The engine accepts all of them equally, so whoever reads the configuration must treat all four as equivalent, and whoever writes it should pick one spelling and stick to it.

Time interval. A string like 1w2d12h or 300s, where w is weeks, d days, h hours, m minutes, s seconds. The parts are concatenated, without spaces or symbols. The manual has no separate unit field anywhere: the unit is always inside the value.

Regular expression. Perl-compatible (PCRE), written between slashes: /^421 .* too many errors/. The dialect is foreign and complete — details on the regex-dialect page.

Domain pattern. Five forms, and they are the ones worth remembering: they appear in every block that matches something against a domain. The difference between two of them is a trap, described below.

The main trap is two nearly identical pattern forms. *.domain catches only subdomains and not the domain itself; [*.]domain catches both the domain and its subdomains. The difference is two brackets, and the consequence is serious: a rule written for *.example.com silently does not apply to example.com. No parse error, no warning — the block simply does not match, and something more general applies instead.

What the Hub does. It writes the configuration itself, so it chooses the spelling for the author: booleans — yes/no and true/false mixed (a legacy of the templates), intervals — in the compact form like 10m, patterns — so far only * and 0/0.

The inconsistency in booleans is harmless for the engine but inconvenient for a person reading the finished file: two forms in one file look like a difference in meaning that does not exist.

The Hub does not write regular expressions at all — it assembles pattern rules from a list of domains, not from an expression.

Recommended values

What to write when writing by hand:

Type	Form	What to watch
boolean	yes or no	pick one spelling for the whole file
interval	10m, 4d12h, 300s	the unit is required: a bare number is not an interval
expression	/…/ between slashes	PCRE dialect, escaping as in Perl
pattern	[*.]domain	almost always this form, not *.domain

An interval without a unit is not an interval. The manual does not describe lines like bounce-after 4: for this type the unit is always inside the value, and a bare number makes no sense here.

Both kinds of patterns are also covered on the domain-matching page — along with the manual’s example where both forms stand side by side and you can see how they differ in a live config.

The table and the advice to stick to one spelling are ours. From the manual here are the set of four types, all five pattern forms, the interval syntax and the fact that expressions are Perl-compatible.

Example configuration

# four types in four lines
<domain [*.]example.com>
    use-starttls yes                 # boolean: yes | no | true | false    bounce-after 4d12h               # interval: w d h m s concatenated
    max-msg-rate 500/h
</domain>
<smtp-pattern-list too-many>
    reply /^421 .* too many errors/ mode=backoff   # PCRE expression
</smtp-pattern-list>

The header of the first block is the fifth type, a domain pattern: the bracketed form catches both example.com and its subdomains. The form without brackets would catch only the subdomains.

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▶

Writing an interval as a bare number

§ 3.2

What it costsFor this type the unit is always inside the value; there is no separate field for it anywhere. A bare number is not described in the manual, and there is nothing to base a guess about how the engine will interpret it on.

How to spot itConfiguration validation rejects the line, or the interval turns out to be different from what was expected.

How to do it rightAlways write the unit: 300s, 10m, 4d12h. The parts are concatenated, without spaces.

Mixing the four boolean spellings in one file

§ 3.2

What it costsFor the engine all four are equivalent, and there will be no error. But a person reading the file sees yes in one line and true in the next and looks for a difference that does not exist.

How to spot itBoth spellings occur in the same file, usually at the boundary between two templates or two authors.

How to do it rightPick one spelling and bring the file to it. Whoever writes a parser for someone else’s config should treat all four as one value.

Reading an asterisk with a dot as “the domain and everything under it”

§ 3.2

What it costsThe form catches only subdomains. The rule does not apply to the domain itself, where the main mail goes, and something more general applies instead.

How to spot itThe setting is visible in the file, but the queue settings command prints the default for the domain.

How to do it rightWrite [*.]domain. Check with two queue settings calls — for the domain and for its subdomain.

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.

Inheritance

Types have no inheritance: they are the grammar of a value, not a setting. The directives written with them are inherited — by the rules of their block. The only thing worth remembering during merging: a value written with different boolean spellings merges as the same thing — yes is not “stronger” than true.

⇄

Related entries

1 relation

Applies to

The node's main configuration fileThe very file that is written in these four types. § 3.2

Referenced from

relay-addressGlobalThe value can be a regular expression, and that has its own parsing. § 3.2 Address lists — named and unnamedPatterns in a list are regular expressions of the same dialect as everywhere else in the configuration. § 3.2 address<address-list>A pattern in slashes is a regular expression of the same dialect as everywhere else in the configuration. § 3.2 body-pattern-file<email-patterns>The value is a regular expression, and the dialect rules are shared with the rest of the configuration. § 3.2 allow-smtputf8<source>An international address is a separate kind of value, not an ordinary string: it has its own parsing. § 3.1 How the policy for a receiver is assembledThe pattern forms are described there, including the asterisk-and-dot trap. § 3.2

How to check on the node

Whether what is written parses is checked by the engine itself, before applying:

pmta test config
pmta show settings example.com/mta-news-1

The first command catches grammar violations: an unknown unit in an interval, an unclosed expression, a wrong pattern form. The second catches what the first will not: the pattern parsed but matched something other than expected. The asterisk trap shows only with the second command.

◇

What else to read

3 articles

◇Accept, route, deliverA message’s path inside the node: accept, decide where, deliver — and all the settings live between these three steps.◇Reloading settings versus restarting the serviceThe configuration is read at startup, and after that edits are picked up by the reload command — except for the directives the manual marks as requiring a restart.◇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: safe: a wrong value breaks nothing
Scenarios: Configuration lifecycle · Tune the pace for a provider
Priority: critical