Demo
Demo

Knowledge base

PMTA knowledge base›File§ 1.6.3

The node's main configuration file

critical

PowerMTA main configuration file
A plain text file — and a secrets store as well

All of the node’s configuration lives in one text file: /etc/pmta/config on Linux, c:\pmta\config.dat on Windows. The format is UTF-8, one line per directive, # starts a comment that runs to the end of the line. The encoding was chosen for a reason: domains and addresses in national alphabets are written into the file as is, without escaping.

It is read at startup and on the reload command. The manual explicitly advises reloading rather than restarting: a reload is more efficient and does not interrupt delivery. It picks up most edits; the few directives that require a restart are marked in their sections — we have twenty-eight of them.

There is more than one file. The second main one is /etc/pmta/config-defaults, with the defaults the main file is laid over. Plus the main file can include other files with an include line — by path, by mask and even over HTTP.

It is a secrets store. The manual says so in a separate section: the file holds passwords, API keys and private signing keys — in plain text. Permissions on it are not a wish but a requirement: chown pmta:pmta and chmod 640. The included files too, especially those holding keys.

The file can be replaced over the network. The web monitor accepts it with a POST request to /configFile, in the file field — with the admin right. There is no content check: whatever was sent is what gets written.

The main trap is replacement over the network without a check. Uploading through the web monitor writes the file directly and does not check its contents. An error in the uploaded text will surface not on writing but on the next settings reload — that is, when the only place left to fix it is on the node itself. The rule is simple: first pmta test config, then apply.
What the Hub does. It assembles the whole file from the fleet’s state, shows a preview, applies it and can roll back. The main file holds the general node settings, the sending address blocks are moved into /etc/pmta/virtualhost.txt, and the sending addresses that go through proxies into /etc/pmta/proxy.txt; both are included with include lines. The whole layout rests on those lines; the addresses file format is shared with Protosender, and both read it.

The Hub puts the files in place over SSH rather than with a request to the web monitor: that way there is something to go back to on rollback and something to show in the preview.

⚠️ The Hub writes submission passwords into the file in plain text — otherwise the engine will not accept them. That is what makes permissions on the file mandatory rather than desirable.

Recommended values

The file has no values of its own — it has requirements:

What How it should be
owner and permissions pmta:pmta, 640 — the manual gives these commands directly
encoding UTF-8; national domains are written as is
included files the same permissions, especially where signing keys are
applying edits pmta reload, not a restart
before applying pmta test config — always, and especially after an edit over the network

Secrets can be moved out of the file. The manual suggests storing signing keys in Vault and referencing them from the configuration (vault-support) — then the file holds a reference rather than the key itself.

The order of applying edits and the advice to check beforehand are ours. From the manual here are the paths of both main files, the encoding, the commands for setting permissions, the list of secrets and the fact that an HTTP upload writes the file without checking.
Example configuration
# the main file: general node settings, sending addresses — in the included file
host-id 5
smtp-listener 0/0:2525
smtp-listener 0/0:25
include /etc/pmta/virtualhost.txt   # sending address blocks
The highlighted line is the two-file layout: node settings in the main file, sending addresses separately. The file included by this line needs the same permissions: the address blocks hold signing keys.
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▶

Applying the file without checking the parse

§ 3.1

What it costsAn error in the text will surface on the settings reload. If the file came over the network, it will have to be fixed on the node itself — what was there before is not left anywhere.
How to spot itThe settings reload fails, and the startup log has a line with the file’s line number.
How to do it rightPut pmta test config before every apply. For an edit over the network all the more so: the upload does not check the contents.

Setting permissions on the main file and forgetting the included ones

§ 1.6.3

What it costsThe manual names included files separately: they hold private signing keys. A protected main file with an open included file protects nothing.
How to spot itThe main file has 640 permissions, while the file with address blocks has 644 or the owner root.
How to do it rightSet permissions on the whole bundle at once, including the directory with keys. Check with a file listing, not from memory.

Restarting the service instead of reloading the settings

§ 3.1

What it costsA restart interrupts delivery, a reload does not — the manual explicitly calls it more efficient. A restart is needed for a few directives, and each of them is marked in its own section.
How to spot itAfter every configuration edit, reports show a delivery gap as long as the restart.
How to do it rightApply with pmta reload. Restart only when the edited directive directly requires it.
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.
Reference data
Syntax
Not described in this chapter — directive and block syntax is defined in chapter 3. This entry records the file's location, sensitivity and permission expectations only.
Everything here comes from the manual, with the section.
Inheritance
The file has no inheritance, but it has a reading order: first config-defaults with the defaults, then the main file on top of them, and an include line pastes the contents of the included file at the place where it stands. Merging settings inside is the business of blocks and their rules.
⇄

Related entries

7 relations

Does not work without

Lock down permissions on configuration filesThe file holds passwords and signing keys, so permissions on it are mandatory. § 1.6.3

Depends on

Four value types the whole config is written inThe values in the file are written in four types defined once. § 3.2

Works together with

The defaults fileThe second main file: the defaults this one is laid over. § 1.6.3includeGlobalThe main file can include others — by path, by mask and over HTTP. § 3.3.1.53

Affects

http-extra-headers<include-config>Included files carry the same sensitivity as the main one. § 1.6.3

Applies to

Node backup and restoreThe configuration directory is the first thing listed for restoring a node. § 1.8

Where you can see it

Replace the configuration file over the networkThe file can be replaced over the network with a request to the web monitor — without a content check. § 3.1

Referenced from

Change a signing key without interrupting sendingBoth edits — adding and removing the key — are made in the main file or in an included one. § 1.6.2Reloading settings versus restarting the serviceA reload acts on the main file and on everything it includes. § 3.1http-accessGlobalThe operator level and above opens reading the configuration through the API — that is, the whole file with all the secrets in it. § 3.1Where the node writes why it did not startA startup failure is most often caused by an edit of exactly this file. § 4.2.1ConfigurationThe file this output refers to. § 5.6Configuration through the API and the file do not reconcileThe file the mechanism is concerned with. § 8.3

How to check on the node
Two different properties need checking: whether the file parses and whether it is protected:
pmta test config
ls -l /etc/pmta/config /etc/pmta/virtualhost.txt
pmta reload
The first command parses the file without applying it — its place is before every apply. The second shows the owner and permissions: pmta:pmta and 640 are expected, for the included files too. The third applies the settings without stopping delivery.
◇

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.◇Accept, route, deliverA message’s path inside the node: accept, decide where, deliver — and all the settings live between these three steps.◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.

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