Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 8.3

Configuration through the API and the file do not reconcile

critical

Configuration API semantics
Two sources of truth — and they do not get along

A node’s configuration can be changed in two ways — with the file and with requests to the configuration API — and the two must not be combined: what was created by a request can only be edited by a request and is not visible in the configuration file.

Every change checks itself: after it the engine reloads the configuration, and if the reload fails the change is rejected and the error is returned in the response. A change either takes effect or does not exist.

API state is stored separately — in /var/lib/pmta/config-api, written at startup and on every reload. A disabled API ignores what was created but does not delete it: enable it again and it comes back.

The main trap is creating the same thing both ways. A list or sending address created by a request is not visible in the file and cannot be edited with it: edits to “one” object live in different places, and none of them describes the node as a whole.
What the Hub does. It edits only the file and keeps its versions; objects created through the API would not make it into those versions or a rollback — which is why the two ways must not be mixed.
Recommended values

The file and the configuration API:

Property File Configuration API
editing the whole file per object
checking a separate step a reload on every change
storage /etc/pmta /var/lib/pmta/config-api
what it covers everything address lists and sending addresses with domains
Editing only through the API, the automatic reload, rejection on error, storage and behavior when disabled come from the manual (§ 8.3). The comparison with the file is ours.
Example configuration
# enable the configuration API
http-enable-api-config yes
The API is off by default; any change needs the key from http-api-key.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
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

4 relations

Does not work without

Reloading settings versus restarting the serviceA related mechanism: they work together. § 8.3

Conflicts with

The node's main configuration fileThe file the mechanism is concerned with. § 8.3

Where you can see it

Address lists through the configuration APIA request that returns the same thing. § 8.3.2Sending addresses through the configuration APIA request that returns the same thing. § 8.3.3

Referenced from

How the API reports an errorA related mechanism: they work together. § 8.3.4Engine version rollback and configuration via the APIA related mechanism: they work together. § 8.3.1

How to check on the node
See what was created through the API:
ls -l /var/lib/pmta/config-api/
The files in this directory are all the configuration created by requests; it is not in /etc/pmta.
◇

What else to read

3 articles

◇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.◇Address lists — named and unnamedA list of addresses, domains, patterns or hashes; a named one is attached by directives such as suppression, an unnamed one lives inside an inbound mail processor.◇Two attachment points — and two different behaviorsA list attached to a source rejects the recipient at submission or bounces the message later; attached to a sending address or pool, it always accepts and then bounces.

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