Demo
Demo

Knowledge base

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

precached-refresh-interval

<dns>

How often precached records are refreshed
in the configuration this is a lineprecached-refresh-interval 5minside the block <dns>
Your schedule instead of someone else’s time to live

The default is 5m. The line sets how often the engine re-resolves the domains from the precache list.

The manual describes this as a replacement for the record’s time to live: the interval is similar to it in meaning, but it is set manually and overrides the one set by the receiver. The usual TTLs for these domains are ignored.

Hence a direct consequence, which is exactly why this line is worth remembering: the receiver no longer controls how quickly you learn about a change in its route. You control it — with this very line.

It works only together with the list: precached-domains-file.

The main trap is an interval longer than what the receiver set. A short record TTL at a large receiver is not there for looks: it is its way to switch traffic quickly — move it off a failed node, spread it across sites. An interval of half an hour instead of five minutes disables this for half an hour.

The second half is the reverse: a short interval on a long list is a constant load on the resolver. The number of domains divided by the interval is the number of queries per second — and they go out always, not only when there are messages.

What the Hub does. It does not write it: the precache is not used at all, and there is no <dns> block in the configuration.
Recommended values

What to set. The interval is compared with the record TTL at the receiver itself:

Value When
5m (default) the list is short, the receivers are large and change routes
shorter the receiver sets a very short TTL, and falling behind is not an option
longer the list is large, and these domains’ routes have not changed for years

The guideline is simple: the interval must not be noticeably longer than the TTL the receiver set itself. It did not choose it at random.

The 5m default, the replacement of the record TTL and the fact that the usual TTLs for these domains are ignored come from the manual, § 3.3.16.2. The load calculation and the advice to compare with the receiver’s TTL are ours.
Example configuration
# an interval shorter than what large receivers set
<dns>
    precached-domains-file /etc/pmta/precached-domains.txt
    precached-refresh-interval 2m</dns>
These domains’ own record TTL is ignored: refreshing follows this schedule and only this schedule.
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▶

Choosing an interval longer than the receiver's record TTL

§ 3.3.16.2

What it costsA short TTL is the receiver’s way to switch traffic quickly. A long interval disables it: messages go to the old servers the whole time until the refresh.
How to spot itConnection failures to a receiver whose route has already changed.
How to do it rightCompare the interval with the record TTL at the receivers themselves and choose one no longer than that.

Setting a short interval on a long list

our experience

What it costsEvery refresh means queries for all the domains on the list at once, and they go out constantly. A mechanism meant to take load off the resolver starts creating it.
How to spot itThe resolver responds more slowly after the cache is turned on, while the queue is empty.
How to do it rightDo the math: the number of domains divided by the interval is queries per second. Shorten the list or lengthen the interval.
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-refresh-interval <time-interval>
Values
a time interval, for example 5m or 2m
Default
5m § 3.3.16.2
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 list at once: there is one block per node, and an individual domain cannot have an interval of its own. This is a significant limitation — receivers set different TTLs, while there is only one interval here.
⇄

Related directives

1 relation

Does not work without

precached-domains-file<dns>There is nothing to refresh until a file with the list of domains is named. § 3.3.16.2

Referenced from

precached-max-domains<dns>The ceiling and the interval together set the load: the number of domains divided by the interval. § 3.3.16.3

How to check on the node
The interval is read together with the list length — together they set the load:
grep -n -A4 '^<dns>' /etc/pmta/config
wc -l /etc/pmta/precached-domains.txt
dig +noall +answer +ttlid gmail.com MX | head -3
The third command shows the record TTL at the receiver — that is what the interval should be compared with. The number of domains divided by the interval gives the constant resolver load in queries per second.
◇

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-domains-fileprecached-max-domainsAll 3 directives of the block →