Demo
Demo

Knowledge base

PMTA knowledge base›Command§ 6.3.5

reload

critical

Apply a changed configuration without stopping
A safe operation — a failure means “nothing changed”

The command rereads the configuration and enables it. The manual gives it both a preference and a guarantee.

The preference: reload rather than stop and start — it is more efficient and does not interrupt work.

The guarantee matters more. A configuration with an error is not applied halfway: the command fails, and the node keeps running on exactly what it was running on. A failure means not a broken node but an unchanged one.

That is exactly why a reload is safe to try. The worst that can happen is that the settings do not change, and the command’s output will say so. For a system that edits configuration automatically, this behavior is worth more than convenience: a failed edit does not leave the node in an intermediate state.

Not everything is picked up by a reload. A few directives need a restart, and each of them is marked in its own section of the manual (config-reload).

The main trap is assuming a successful reload means a correct configuration. It only means the file parsed. A setting that is syntactically correct but written in the wrong block will apply silently: the line will end up somewhere other than intended, and what works will not be what was expected. A separate parse check will not catch this either — it checks the same grammar.
What the Hub does. It calls it over SSH — pmta reload after every delivery of files to the node. Sending is not interrupted. The same command is the “Reload configuration” operation in control, through POST /command with the node key.

Before reloading, the Hub runs test config and puts the previous files back on error, and afterwards it checks that the engine responds. The guarantee of “never applied halfway” is what makes the scheme safe: if the reload fails, the node stays on the previous configuration.

The Hub reads the command output — it and the exit code determine whether the edit was applied.

Recommended values

The order of applying an edit:

Step Why
parse check learn about an error before applying
reload enable the settings without interrupting sending
reading the output make sure it went through, not just that it was called
checking the effective values correct grammar does not yet mean “landed where needed”

The last step is the one skipped most often. A setting written in the wrong block will parse and apply — and this will be discovered by behavior, not by an error. The commands that print the effective queue and address settings answer this question directly.

Leave restarts for the marked directives. A restart stops sending, and on a node with regular edits that is a noticeable loss.

The order of applying is our recommendation. From the manual here are the preference for a reload over a restart and the guarantee that a configuration with an error is not applied partially.
Example configuration
# the right order: check, apply, confirm
pmta test config
pmta reloadpmta show settings gmail.com/mta-news-1
The highlighted line applies the settings. The top one catches an error before applying, the bottom one answers a question neither of the others will catch — whether the line got into the queue it was written for.
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 ends3 mistakes▶

Treating a successful reload as proof of a correct setting

§ 6.3.5

What it costsSuccess means the file parsed. A setting written in the wrong block is syntactically correct and will apply silently — what works will not be what was intended, and there will be no error.
How to spot itThe edit is applied, but the node’s behavior has not changed.
How to do it rightAfter applying, ask for the effective values with the queue and address settings commands — they will show where the line landed.

Restarting instead of reloading

§ 3.1

What it costsA restart stops sending, a reload does not. On a node where edits happen regularly, this adds up to a noticeable loss of sending time — and none of it is needed.
How to spot itA delivery gap exactly as long as the restart after every edit.
How to do it rightReload. Restart only for the directives that directly require it.

Not reading the command's output

§ 6.3.5

What it costsOn a parse error the command fails, and the node stays on the previous settings. Without reading the output this looks like a successful apply — while the edit has no effect.
How to spot itA configuration change has no effect at all, while the file looks correct.
How to do it rightRead the output or check the exit code. For automation this is a mandatory step, not an optional one.
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.
⇄

Related entries

3 relations

Works together with

Configuration parse checkA parse check: its place is before applying, not instead of it. § 6.3.40

Can be replaced by

Starting and stopping the engineThe heavy way of applying — with sending stopped; only a few directives need it. § 6.3.5

Where you can see it

Reloading settings versus restarting the serviceThe mechanism this command carries out. § 6.3.5

Referenced from

Change a signing key without interrupting sendingOne and the same command applies both adding the new key and removing the old one. § 1.6.2Troubleshooting mail receptionThe command that performs the step. § 4.2.4Replace the configuration file over the networkThe same output from the command line. § 8.2.2Change a sending address when messages are already queuedThe change takes effect with a configuration reload; a service restart is not needed. § 9.5.1

How to check on the node
Make sure the reload went through, not just that it was called:
pmta reload
pmta show status | tail -1
The command prints “Configuration reloaded.”; with an error in the file the reload does not go through, the node stays on the previous configuration, and the output names the error.
◇

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.◇Four value types the whole config is written inBoolean, domain pattern, regular expression and time interval — defined once in § 3.2 and then used by all directives.◇Reloading settings versus restarting the serviceThe configuration is read at startup, and after that edits are picked up by the reload command — except for the directives the manual marks as requiring a restart.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Configuration lifecycle
Priority
critical