Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 3.1

Reloading settings versus restarting the service

critical

reloading the configuration
A reload does not interrupt delivery, a restart does

The configuration is read once at startup. After that there are two ways to apply an edit, and they are not equivalent.

Reloading settings — the pmta reload command. The manual explicitly calls it more efficient: the engine rereads the files without stopping delivery. Most edits are picked up this way.

Restarting the service stops sending for the duration of the restart. Few directives need it, and each of them is marked in its own section of the manual — we have twenty-eight of these.

There is also a third case that is easy to miss. The web monitor port requires a restart not of the engine but of the monitor service itself. The difference is significant: one costs sending, the other does not.

What a reload does not do. It does not check the file in advance: parsing happens at the moment of applying, and an error will surface right then. A separate check command exists precisely to find out about an error before, not after.

The main trap is the habit of restarting “just in case.” Restarting after every configuration edit turns an ordinary settings change into a delivery gap as long as the restart. On a node where edits happen regularly — and with management from the Hub they do — this is a noticeable share of lost sending time, and none of it is needed.
What the Hub does. It applies edits with a reload: after the files are delivered to the node, pmta reload runs, and sending is not interrupted.

Before that the Hub runs a parse check and shows a preview — so an error is caught before applying, not after.

The Hub writes no directives that require a service restart. The web monitor’s lines require a monitor restart — the Hub performs it itself after every apply. Two lines that a reload did not pick up were removed from the templates: run-as-root on Aug 29, 2026 and enable-source-ip-limits-on-sending-ip on Sep 15, 2026.

Recommended values

The choice is simple, and it is determined not by habit but by the directive:

What was changed How to apply it
a regular setting with a reload — delivery is not interrupted
a directive marked as requiring a restart by restarting the engine service
the web monitor port by restarting the monitor service, without touching the engine
the vendor’s analytics settings the manual advises a restart, although a reload is enough

Check before applying. The check command parses the file without applying anything — its place is before every reload, and especially after an edit over the network, which does not check the contents.

Twenty-eight directives require a restart. There is no need to memorize them: the mark is in each one’s section, and in the catalog such pages have their own indicator.

The advice to check before applying is ours. From the manual here are that a reload is more efficient, that most edits are picked up by it and that the exceptions are marked on each directive separately.
Example configuration
# the order of an edit: check first, then apply
pmta test config
pmta reload# and only for marked directives:
systemctl restart pmta
The highlighted line is the usual path. The bottom one is needed only when the changed directive directly requires it; sending stops for the duration of the restart.
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▶

Restarting the service after every edit

§ 3.1

What it costsA restart stops sending, a reload does not. On a node with regular edits this adds up to a noticeable share of lost sending time, and none of it is needed.
How to spot itDelivery reports show a gap exactly as long as the restart after every configuration edit.
How to do it rightApply with a reload. Restart only when the changed directive directly requires it.

Applying without checking the parse

§ 3.1

What it costsA reload parses the file at the moment of applying. The error will surface right then — and if the file came over the network, what was there before no longer exists anywhere.
How to spot itThe reload fails, the node runs on the old settings, and the fix has to be made on the node itself.
How to do it rightPut a parse check before every apply.

Restarting the engine for the monitor port

§ 3.3.1.30

What it costsThe web monitor port needs a restart of the monitor service, not the engine. Restarting the engine stops sending — for a setting that has nothing to do with sending.
How to spot itA delivery gap after an edit unrelated to delivery.
How to do it rightRead the mark in the directive’s section: it distinguishes these two cases. Restart exactly what is named.
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.
Inheritance
The mechanism has no inheritance — it is a way of applying, not a setting. But it acts on the whole bundle of files: a reload rereads the main file and everything it includes with an include line — that is, in our case, also the file with the sending address blocks.
⇄

Related entries

3 relations

Does not work without

Apply a changed configuration without stoppingThe command behind this mechanism. § 3.1

Affects

run-as-rootGlobalOne of the few directives for which a reload is not enough. § 3.3.1.9

Applies to

The node's main configuration fileA reload acts on the main file and on everything it includes. § 3.1

Referenced from

http-mgmt-portGlobalThe only monitor directive whose restart the manual mentions directly; in practice all of its settings require a restart. § 3.3.1.58.1Starting and stopping the engineA settings reload does the same as a restart, but without stopping delivery. inferenceInvestigating a startup failureThe mechanism this step relies on. inferenceConfigurationThe mechanism that is visible here. § 5.6Clear the secrets cacheThe mechanism the command works with. inferenceConfiguration through the API and the file do not reconcileA related mechanism: they work together. § 8.3

How to check on the node
Check that the reload went through, not just that it was invoked:
pmta test config && pmta reload
pmta show status
The reload command prints the parse result: on an error the settings stay as they were, and its output says so. The status summary shows the time of the last apply — it tells whether the node actually picked up the edit.
◇

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.◇How the node selects a source and combines its settingsA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.

In the Hub
Cost of a mistake
disruptive: applying it interrupts the node
Scenarios
Configuration lifecycle
Priority
critical