Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 8.2.2

Replace the configuration file over the network

/configFile commit
🔴 Without checking the contents

Writes the submitted configuration files to the node — one or more per request.

The call is POST /configFile as a multipart/form-data form: op=commit, and for each file file.N.name (the full path), file.N.op=write and file.N.content. The format field — json or xml — sets the response form, xml by default.

🔴 There is no content check: the endpoint will write a broken configuration too. And by itself it applies nothing — for the write to take effect, the configuration is reloaded separately.

A file from a subdirectory can be written only if it is already included from the main configuration.

Writing requires the key from http-api-key in the X-API-Key header — regardless of the address level in http-access.

The main trap is treating a successful response as a check. success means “the file is written”, not “the configuration is correct”. The error surfaces at the next reload — and by then the new file is already on disk. The safe order: keep the previous file, write the new one, check it with test config and only then reload.
What the Hub does. It does not use it. It puts files over SSH, keeps the previous ones alongside, checks the configuration with test config and only then reloads; on any error it puts the previous files back.
Recommended values

Form fields:

Field Required What it sets
op yes commit — write the files
file.N.name yes the full path of the N-th file
file.N.op yes write — write it
file.N.content yes the contents; with @ curl substitutes a local file
format no json or xml, xml by default
The form fields, the lack of a check, the need to reload and the mandatory key come from the manual (§ 8.2, § 8.2.2). The safe write order is ours.
Example configuration
# write a file and check the configuration on the node right away
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'pmta test config
The endpoint only writes: checking and reloading are separate steps, and they must be done before the queue comes to rely on the new file.
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

Configuration parse checkThe same output from the command line. § 8.2.2Apply a changed configuration without stoppingThe same output from the command line. § 8.2.2

Can be replaced by

ConfigurationThe same subject on the monitor screen. inference

Affects

The node's main configuration fileThe file this output refers to. § 8.2.2

Referenced from

Read the configuration file over the networkThe same thing, returned by a request. § 8.2.1

How to check on the node
After writing, make sure the configuration is correct, and only then reload:
pmta test config
pmta reload
If test config prints an error, do not reload: put the previous file back and repeat the check.
◇

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
dangerous: effects outlast a rollback
Scenarios
Configuration lifecycle