Demo
Demo

Knowledge base

PMTA knowledge base›Block <source>›Directive§ 3.3.7.60

retain-x-dkim-options

<source>

Whether to keep the X-DKIM-Options header in the message on delivery
in the configuration this is a lineretain-x-dkim-options falseinside the block <source>
Whether to show the recipient how signing is configured

The default is false: the header is removed before sending to someone else’s server. With true it stays in the message and reaches the recipient.

The manual names independence from the permission to read the header directly for the neighboring pairs — schedule and signing key. The section on this header is silent about the link, and it is reasonable to assume the same rule: processing and retention decide different questions and know nothing about each other.

The main trap is that the manual speaks with two voices about the “both off” case. The sections on header processing — three times, for three different headers — state: with processing off the header stays in the message. The retention sections of the neighboring headers — schedule and signing key — state the opposite: with both directives false the engine ignores the header but still removes it before delivery. The section on this header is silent about such a case.

The contradiction cannot be resolved by reading — only by testing on your own installation. Until it is tested, it is safer to assume the header stays.

What the Hub does. It does not write it: the header with signing settings plays no part in our submission, and there is no reason to remove it — if it does not arrive, there is nothing to remove.

The line that actually cleans messages here is a different one: remove-header in every source removes a set of submitting platforms’ service headers. There are no signing headers in that set.

Recommended values

What to set. The default is almost always right:

Value When
no (default) the usual case: the recipient has no need to see signing settings
yes investigating your own submission, when you need to see what the message arrived with

The second case is temporary, for the duration of an investigation. Keeping it on permanently means showing recipients the names of your selectors and signing domains.

The false default comes from the manual, § 3.3.7.60. The manual names independence from processing for the neighboring pairs (§ 3.3.7.47, § 3.3.7.59); here it is carried over by analogy. The breakdown of cases is ours.
Example configuration
# the header stays in the message — only for the duration of a submission investigation
<source 10.0.0.0/24>
    process-x-dkim-options true
    retain-x-dkim-options true</source>
Both lines are needed only together, for the duration of an investigation: the first makes the engine read the header, the second leaves it in place so that you can see what the message arrived with.
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▶

Considering the question settled by the manual

§ 3.3.7.47

What it costsAbout the “both directives off” case the manual has two mutually exclusive statements, both about removing the header. Choosing between them by the authority of the text is impossible.
How to spot itThe header behaves differently than expected from what was read.
How to do it rightSend a message with all service headers to your own mailbox and see what arrived. One check closes the question for your engine version.

Leaving it on after the investigation

our experience

What it costsRecipients keep seeing selectors and signing domains — and through them the whole setup of your signing.
How to spot itThe header with signing settings shows up in messages received in seed mailboxes.
How to do it rightReturn the default right after the investigation and do not keep it on in production sources.
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
retain-x-dkim-options <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.60
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<source>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <source> and follows source merging: a connection falls under all address blocks that cover it, and a narrow one overrides a broad one. For submission under a login the named block applies, and the line has to be repeated in it — we did not see inheritance from address blocks into a named one on our installation.
⇄

Related directives

2 relations

Same name in other blocks

retain-x-dkim-key<source>The same setting for the neighboring header, only the price of a mistake there is incomparably higher: the private key stays in the message. § 3.3.7.60

Applies to

Headers the sender uses to control deliveryThe “keep or remove” half for one of the six service headers. § 3.3.7.60

How to check on the node
The setting is visible in the configuration, the consequence — in the delivered message:
grep -n 'retain-x-dkim' /etc/pmta/config /etc/pmta/virtualhost.txt
No line means the default applies. What actually reached the recipient is more reliably checked in a seed mailbox: that is also the only way to resolve the manual’s contradiction about the “both off” case.
◇

What else to read

3 articles

◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on 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.◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connect a sending platform
Neighboring settings of the block <source>:process-x-jobjobid-prefixallow-mailmergeadd-message-id-headeradd-received-headerAll 74 directives of the block →