Demo
Demo

Knowledge base

PMTA knowledge base›Block <vault>›Directive§ 3.3.23.3

cache-ttl

<vault>

How long a key from the vault is kept in the node's memory
in the configuration this is a linecache-ttl 24hinside the block <vault>
A trade-off between key freshness and trips to the vault

The default is 24h. The line sets how long a key obtained from the vault lives in the node’s memory before it is requested again.

And a separate caveat that is easy to forget: a missing key is always cached for an hour. This line does not change that value — it is hard-coded.

This leads to two different wait times. A key that was changed in the vault reaches the node within the period from this line. A key that was added after an unsuccessful lookup reaches it no sooner than an hour later.

The line lives in the <vault> block together with the vault address and the access token.

The main trap is the hour for a missing key. The sequence of actions that seems natural — configure the node, see that the key is missing, add it to the vault and wait — leads to an hour of downtime. And this line cannot shorten it.

The right order is the reverse: first the key in the vault, then the reference to it in the configuration.

The other half is rotation. A key change reaches the node within the period from this line, and a day by default means a day during which the node signs with the old key taken from the vault.

What the Hub does. It does not write it: it does not use the vendor’s secret vault. The Hub keeps signing keys itself, publishes the records and distributes the files to nodes on its own, and in the configuration refers to them by paths.

That is why rotation follows our own rules — a new selector, waiting for queues to drain, removing the old one — and is not complicated by the hour-long cache of a missing key.

Recommended values

What to set. The period is chosen by how often keys change:

Value When
24h (default) keys change on a schedule, and a day of delay is acceptable
1h–2h rotation is frequent or a key may be revoked urgently
longer than a day the vault is far or unreliable, and keys hardly ever change

A short period costs a trip to the vault for every key — and the vault must be available at that moment. A long one saves trips at the cost of a delay during rotation.

The 24h default and the hour-long caching of a missing key come from the manual, § 3.3.23.3. The analysis of the two different wait times and the breakdown of cases are ours.
Example configuration
# rotation is frequent — a day of delay is too much
<vault>
    server-url https://10.1.2.3:4500
    access-token akhdfasdhf786282684734kjsdhf
    cache-ttl 2h</vault>
The line applies to found keys. A missing key is always cached for an hour, and that value is not configurable.
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▶

Adding a key to the vault after the node failed to find it

§ 3.3.23.3

What it costsA missing key is cached for an hour, and that value is not configurable. The node will not see the added key for a whole hour, however you edit this line.
How to spot itThe key is in the vault, the signature is not applied, and there are no errors.
How to do it rightFlush the secrets cache with a command — or put the key in the vault before referring to it in the first place.

Keeping a day with frequent rotation

our experience

What it costsA key change reaches the node within the period from this line. A day means a day of signing with a key that has already been replaced or revoked in the vault.
How to spot itAfter rotation the node keeps signing with the previous selector.
How to do it rightShorten the period or flush the secrets cache right after rotation.
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
cache-ttl <time-interval>
Values
a time interval, for example 2h
Default
24h § 3.3.23.3
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<vault>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <vault> and applies to the whole vault: there is one block per node, and an individual key cannot have its own period.
⇄

Related directives

2 relations

Works together with

domain-keyGlobalSigning keys are what is most often taken from the vault; the cache period decides how fast their change arrives. § 3.3.23.3Lock down permissions on configuration filesA vault is an alternative to keys on disk; it does not cancel the configuration file permissions. § 3.3.23.3

How to check on the node
The line is visible in the configuration; the cache behavior is checked over time:
grep -n -A4 '^<vault>' /etc/pmta/config
pmta clear secretscache
The second command flushes the secrets cache — the only way not to wait for the period to expire during rotation or after adding a missing key.
◇

What else to read

3 articles

◇Secrets in an external vaultSigning keys can be kept in HashiCorp Vault: the configuration keeps a path, and the engine fetches the key over HTTP and keeps it in memory without writing it to disk.◇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.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Key rotation · Node security
Neighboring settings of the block <vault>:access-tokenserver-urlAll 3 directives of the block →