Demo
Demo

Knowledge base

PMTA knowledge base›Block <dns>›Directive§ 3.3.16.1

precached-domains-file

<dns>

A file listing domains whose DNS is kept fresh at all times
in the configuration this is a lineprecached-domains-fileinside the block <dns>
The list of those resolved in advance

The value is a path to a text file with one domain per line.

The manual describes the usual order like this: the engine looks up a route in DNS when recipients are submitted for a domain — and only if it does not have one yet. The delay from this is small, but it exists, and it depends on how loaded the resolver and the queue are.

The domains listed in the file are resolved in advance and always. The point is to take name resolution out of the delivery path for the receivers that matter more than the rest.

Two neighboring lines set the schedule (precached-refresh-interval) and the ceiling (precached-max-domains); the whole mechanism is described in precached-domains.

The main trap is silent truncation. Only the first entries up to the ceiling are taken from the file, and the default ceiling is 500. A longer list is truncated, and nobody reports it: domains at the end of the file are resolved in the usual order, even though they look cached.

The second half: the file is read by the engine, and it needs the same permissions as the configuration. An unreadable file is not an apply error but simply an empty cache.

What the Hub does. It does not write it: there is no <dns> block in the configuration.

Our list would be short and obvious — the large receivers that carry the bulk of the volume. But along with it we would have to accept the mechanism’s main property: we would notice a receiver’s route change with a delay of one refresh interval.

Recommended values

What to set. A path to a file; the rules follow from the purpose:

Property Why
a short list every refresh means queries for all domains at once
only stable routes the engine will not notice a route change until the refresh
no more lines than the ceiling the rest is silently cut off

The list is worth keeping next to the configuration and editing together with it: it is part of the setup, not data.

The syntax, the file format and the analysis of the usual name resolution order come from the manual, § 3.3.16.1. The default ceiling of 500 comes from § 3.3.16.3. The requirements for the list are ours.
Example configuration
# the list file plus two lines for the schedule and the ceiling
<dns>
    precached-domains-file /etc/pmta/precached-domains.txt    precached-max-domains 500
    precached-refresh-interval 5m
</dns>
The file has one domain per line. If there are more lines than the ceiling, the extra ones are silently cut off — you have to compare these two numbers yourself.
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▶

Putting more domains in the file than the ceiling allows

§ 3.3.16.3

What it costsOnly the first entries up to the ceiling are taken. The rest are resolved in the usual order, and this is not reported.
How to spot itSome of the domains from the file are not visible in the cache contents.
How to do it rightCompare the number of lines with the ceiling and bring them into agreement.

Putting the file where the engine cannot read it

our experience

What it costsThe cache stays empty. There is no configuration apply error: the line is there, but for the engine the file is not.
How to spot itThe cache contents are empty, even though the list file exists.
How to do it rightKeep the file next to the configuration and with the same permissions.
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
precached-domains-file <path>
Values
a path to a text file, one domain per line
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<dns>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <dns> and applies to the whole node: there is one block per instance, and it has no inheritance. Different lists cannot be set for different sending streams.
⇄

Related directives

2 relations

Works together with

name-serverGlobalThe cache is refreshed through the same resolvers as regular name resolution. § 3.3.1.36precached-refresh-interval<dns>How often what is listed in this file gets refreshed. § 3.3.16.1

How to check on the node
The file, the ceiling and the cache contents are checked together:
grep -n -A4 '^<dns>' /etc/pmta/config
wc -l /etc/pmta/precached-domains.txt
pmta show precache
The number of lines in the file must not exceed the ceiling. The third command shows what actually got into the cache: a mismatch with the list means truncation.
◇

What else to read

3 articles

◇How the policy for a receiver is assembledSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.◇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.◇Reputation monitoring inside the nodeThe engine itself watches the receiving servers’ replies and changes the queue mode on a pattern match — a reaction within the connection, not through telemetry.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Troubleshoot deliverability · Tune the pace for a provider
Neighboring settings of the block <dns>:precached-refresh-intervalprecached-max-domainsAll 3 directives of the block →