Demo
Demo

Knowledge base

PMTA knowledge base›API endpoint§ 8.2.1

Read the configuration file over the network

/configFile read
See what is on the node now

Returns the contents of a configuration file.

The call is GET /configFile?op=read&filename=/etc/pmta/config, optionally with format=json-text: then the file arrives as a string inside JSON, without it — the file itself as is.

Not everything can be read. The file must be in /etc/pmta/ (on Windows, in the installation directory), and a file from a subdirectory must also be included from the main configuration. Otherwise the response is 403, and a nonexistent file gives 404.

Useful for reconciliation: it shows what is actually on the node, not what we think is there.

For reading, the key is not required if the requesting address has at least the operator level in http-access; the key from http-api-key in the X-API-Key header lifts the address restriction.

The main trap is the monitor level. An address given only that level cannot read the configuration: it needs operator or a key. A 403 response in this case is not a broken endpoint but permissions.
What the Hub does. It does not ask: it writes configuration files to the node over SSH and checks them with commands on the machine itself. The Hub gives its own addresses in http-access the monitor level, which is not enough for this endpoint — reading would work only with the key.
Recommended values

Parameters:

Parameter Required What it sets
op yes read — read the file
filename yes the full path; only /etc/pmta/ and included files
format no json-text — the file as a string in JSON; without it, the file as is
The parameters, the directory limits and the 403 and 404 codes come from the manual (§ 8.2, § 8.2.1). The analysis of the monitor level is ours.
Example configuration
# the main configuration file as a string in JSON
curl -s 'http://127.0.0.1:8080/configFile?format=json-text&op=read&filename=/etc/pmta/config'
Without a key the request goes through only from an address with the operator level or higher; with the X-API-Key header, from any.
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

2 relations

Works together with

Replace the configuration file over the networkThe same thing, returned by a request. § 8.2.1ConfigurationThe screen that shows the same thing to a human. inference

Referenced from

List of configuration filesA neighboring catalog entry. § 8.2.3

How to check on the node
Check whether the endpoint lets the requesting address in:
curl -s -o /dev/null -w "%{http_code}\n" 'http://127.0.0.1:8080/configFile?op=read&filename=/etc/pmta/config'
grep -n 'http-access' /etc/pmta/config
Code 403 means the address falls short of operator or the file is outside /etc/pmta/; 404 means there is no such file.
◇

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
safe: a wrong value breaks nothing
Scenarios
Configuration lifecycle