Demo
Demo

Knowledge base

PMTA knowledge base›Block <virtual-mta-pool>›Directive§ 3.3.13.3

domain-key

<virtual-mta-pool>

The same signing key, declared at the pool level
in the configuration this is a linedomain-keyinside the block <virtual-mta-pool>
The same name 3:<domain-key-list>Global<virtual-mta><virtual-mta-pool>— some of them are other settings, some are the same one
One declaration that goes to every member

The same line as at the node level, declared inside <virtual-mta-pool>. The definition is on the general page; what matters here is what this place changes.

A pool hands out, it does not share. The declaration is inherited by every pool member: all of the pool’s addresses get the same key. This is not a “pool key” — it is a way to write one declaration instead of several identical ones.

A member can override it. If the <virtual-mta> itself has its own declaration, it is stronger than the pool one — like everything set closer to the point of sending.

The main trap is taking the pool for a shared scope. A key declared here ends up with each pool address separately. For signing this makes no difference — the key is the same — but the habit of thinking “the pool is shared” is costly with other directives: pool limits are also handed out to each member, not shared among all.
What the Hub does. It uses pools but distributes keys by stream: each sending address has its own key, and a pool-level declaration is not needed. It will be needed if pools appear where all addresses sign the same way.
Recommended values

Appropriate when all members have the same key. Then one declaration instead of a dozen identical ones is a direct benefit.

Not appropriate when addresses sign differently. In that case the declarations are written in the streams themselves.

Remember the priority. A member’s declaration overrides the pool one rather than supplementing it.

The “when it is appropriate” split is ours. From the manual here are the line’s composition and the fact that the directives listed in the pool section are inherited by the members.
Example configuration
# one key for the whole pool — instead of a declaration in each stream
<virtual-mta-pool warm>
    domain-key s1, *, /etc/pmta/key.pem    virtual-mta mta1
    virtual-mta mta2
</virtual-mta-pool>
Both mta1 and mta2 will get the declaration — each its own, identical one. If one of them has its own declaration, that one wins.
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▶

Assuming the key is declared “for the pool”

§ 3.3.13

What it costsIt is declared for each member. For signing there is no difference, but the same habit with pool limits is costly: they too are handed out to each member rather than shared.
How to spot itReasoning about a “pool key” in the configuration’s description.
How to do it rightRead pool lines as “for each member,” not “for all together.”

Declaring in a pool a key needed by one address

our experience

What it costsAll members get it. They will not start signing with someone else’s key — the choice is made by sending domain — but the set of keys on the node grows, and rotation gets more complicated.
How to spot itThe pool has more declarations than sending addresses that need them.
How to do it rightKeep in the pool only what is common to all members.
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
domain-key <see-reference>
Values
three comma-separated values — a selector, a domain or an asterisk, a file path or a reference to a secrets vault
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<virtual-mta-pool>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The declaration is inherited by each pool member rather than applying to the pool as a whole. A member’s own declaration (<virtual-mta>) overrides the pool one; node-level general declarations remain a fallback. It is picked up by pmta reload.
⇄

Related directives

2 relations

Same name in other blocks

domain-keyGlobalThe full definition of the line — composition, selection rule, working with a secrets vault. § 3.3.1.55.1

Applies to

A group of sending addresses with traffic sharesOne of the settings a pool hands out to its members. § 3.3.13.3

How to check on the node
The effective set of keys for a specific address is printed by its settings command:
pmta show vmta-settings mta1 | grep -i domain-key
grep -i 'DKIM-Signature' /var/log/pmta/pmta.log | tail -5
The first command shows the value after merging — it shows whether the member got the pool declaration. The Hub does not declare keys at the pool level.
◇

What else to read

3 articles

◇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.◇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.◇Warm-up built into the engineA warmed-up address hands the first N messages of the day for each receiver to its cold partner; the partner sends them itself and builds history.

In the Hub
Managed at
DNS → Signing keys
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sending address rotation
Neighboring settings of the block <virtual-mta-pool>:virtual-mtamax-smtp-msg-ratemax-smtp-outsuppression-listsinclude-headers-fromAll 9 directives of the block →