Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.54.4

relay-debug

Global

Respond with a temporary refusal while acceptance rules are being checked
in the configuration this is a linerelay-debug falseinside the block Global
Room for error when editing acceptance rules

The default is false. Normally a recipient for whom relaying is not allowed is rejected with a final 5XX refusal — and the message bounces at the sender immediately.

With true a temporary 4XX refusal is returned instead. The sending server does not bounce the message but keeps trying.

The manual names the purpose directly: the line helps out while acceptance rules are being edited. While you change the configuration, you get the chance to look at the log, find refusals that should not be there and fix the rules before messages bounce.

The main trap is forgetting to turn it off. Debug mode erases the difference between “the rule is not ready yet” and “we do not want this sender.” Other servers will keep retrying for weeks messages you will never accept, and your node will keep answering them 4XX for weeks and logging it.

The other half: a temporary refusal hides the error from you. A bounced message is noticed right away — through a complaint, a report. A message the sender silently retries for the seventh day is not noticed in any way except the log nobody looks at.

What the Hub does. It does not write it — the vendor’s false remains.

The Hub sets acceptance rules by construction, with three patterns in the base configuration, and edits them not by hand but by regeneration. Debug mode would have helped in exactly the case we once had: role addresses were bounced with 550, and we did not find out right away that DMARC reports were being lost.

Recommended values

What to set. The line is temporary by purpose:

Value When
false (default) the acceptance rules have settled — the permanent state
true for the duration of a rule edit, with a switch-off date set in advance

The second makes sense to enable together with watching the log: without that, the mode only postpones the problem while showing nothing.

The false default, the “5XX versus 4XX” explanation and the purpose “for the duration of acceptance rule edits” come from the manual, § 3.3.1.54.4. The advice to set a switch-off date in advance is ours.
Example configuration
# for the duration of the rule edit — together with watching the log
relay-debug truerelay-address /^(dmarc|postmaster|abuse)@/
While the line is enabled, a mistakenly rejected message does not bounce: the sender will retry. This gives time to find the slip in the rules from the log and fix it.
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▶

Enabling it and forgetting to turn it off

our experience

What it costsOther servers keep retrying for weeks messages the node will never accept. The error in the acceptance rules shows up in no way except a growing log.
How to spot itThe log has long rows of identical temporary refusals to the same senders.
How to do it rightTurn it off, and set the switch-off date in advance when enabling the mode.

Enabling the mode without looking at the log

§ 3.3.1.54.4

What it costsThe point of the mode is to see mistaken refusals before they become bounced messages. Without watching the log it only postpones the problem.
How to spot itThe mode has been on for a long time, and nobody has looked at the log once.
How to do it rightLook at the log right after enabling it — and depending on the result, either fix the rules or turn the mode off.
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
relay-debug <boolean>
Values
yes | no | true | false
Default
false § 3.3.1.54.4
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
Global
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive is written at the root of the configuration file and applies to the whole node: it has no block, and no inheritance either. Debug mode is enabled for all acceptance rules at once — it cannot be selective.
⇄

Related directives

1 relation

Works together with

always-allow-relayingGlobalDebug mode softens the refusal issued by relay control — the very one this line opens. § 3.3.1.54.4

How to check on the node
The line is visible in the configuration; it makes sense only together with the log:
grep -n 'relay-debug' /etc/pmta/config
grep -i 'relaying denied' /var/log/pmta/pmta.log | tail -20
The second command is the actual work: in debug mode it shows everything that would have been bounced. Empty output with the mode enabled means the rules reject no one they should not — you can turn it off.
◇

What else to read

3 articles

◇Accept, route, deliverA message’s path inside the node: accept, decide where, deliver — and all the settings live between these three steps.◇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.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Configuration lifecycle · Connect a sending platform
Neighboring settings of the block Global:always-allow-relayingsmtp-listenerrelay-addresspickuprelay-domainAll 108 directives of the block →