Knowledge base

One transport, one login, one way

Uniformity as a way not to get confused

The task. A managed node on which the Hub writes the configuration, checks it, puts it into effect, reads state and runs commands — today over two transports with two kinds of access, though one would do.

What it is made of:

The parts have different scopes. Node level; the scheme covers everything except installing the engine, which needs a shell. The monitor port must be reachable by the Hub, and the key must be stored where the Hub uses it.

How they interact. The whole scheme is in the order of actions, because writing neither checks nor puts into effect: read, write, check, reload, and on failure restore what was read. The Hub performs exactly this sequence today, only the write goes over SSH — so the scheme is about changing the transport. The trade-off is real: there are fewer access paths, but one key reaches both the configuration and any node command.

The main trap is treating a write through the API as applying it. /configFile commit only puts the files in place: without test config and reload the node runs on the previous configuration, and a broken file surfaces at the next reload or restart.
What the Hub does. It does not apply it — the setup describes how it could be simpler. The Hub places configuration files on the node and puts them into effect over SSH (pmta test config, pmta reload), restarts the service there as well, and reads state and sends control commands through the web monitor, with a key. Two transports and two kinds of access.
Recommended values

Order:

Step Call Why
read GET /configFile?op=read see divergence from what the Hub wrote
write POST /configFile with op=commit put the files in place
check POST /command with test config syntax before reloading
reload POST /command with reload put into effect
roll back POST /configFile with what was read if the reload failed
Reading, writing without checking, running commands and the key come from the manual (§ 8.2.1–8.2.3, § 8.4). The scheme itself is our hypothesis.
Example configuration
# write a file, check and reload — all with the key
curl -s -X POST -H 'X-API-Key: KEY' 'http://127.0.0.1:8080/configFile' -F op=commit -F format=json -F file.1.name=/etc/pmta/config -F file.1.op=write -F file.1.content='@/tmp/config.new'
curl -s -H 'X-API-Key: KEY' 'http://127.0.0.1:8080/command' -F command='test config' -F format=json
curl -s -H 'X-API-Key: KEY' 'http://127.0.0.1:8080/command' -F command='reload' -F format=json
KEY is the key from http-api-key; the command’s response is judged by the status field, not by the response code.
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.
How to check on the node
Check that the key opens configuration reading:
curl -s -H 'X-API-Key: KEY' 'http://127.0.0.1:8080/configFile?format=json-text&op=read&filename=/etc/pmta/config' | head -5
File contents in the response — reading works; comparing with what the Hub wrote will reveal edits made bypassing it.