Demo
Demo

Knowledge base

PMTA knowledge base›Procedure§ 2.2

Installing on Linux

critical

Eight steps, two of them optional

The installation is a regular package install. The order matters in two places, and both are easy to miss.

The group is created in advance if you need a specific numeric ID. The package will create it itself, but with an ID the system chooses. On nodes where group IDs must match across machines, the group is created before installation.

The license key goes in before the first start. Without it the engine will not start, and the prepared machine will sit idle while the key is being requested.

The configuration is checked, not accepted as is. The package installs a template file, and it lacks lines without which the manual considers the node unconfigured — the responsible person’s address among them.

Starting is needed only once. After that the engine comes up by itself when the machine boots.

The debugger is installed optionally — with it the engine collects more information on a crash. The decision is worth making before a crash happens.

The main trap is taking the template file for a finished configuration. The package installs a file that is valid in form, the engine starts with it, and mail flows. And yet the node may lack the responsible person’s address, the needed listeners, and have vendor defaults where your own values are needed. The start will say nothing about it: it checks parsing, not sense.
What the Hub does. It does not perform the installation — the engine is installed by whoever sets up the node. The Hub connects to an already installed one: it checks the machine’s suitability and then puts its own configuration on top of the template.

So the license key and group creation steps stay entirely with a human, while the Hub takes over the configuration check — its file replaces the template.

⚠️ One step it does not cover: the responsible person’s address. The Hub does not write it and the template does not contain it — so the watchdog is left without a channel (pmtawatch).

Recommended values

What is decided before installation and what after:

Step When
numeric group ID before installation, otherwise the system chooses
license key before the first start
debugger before the first crash, not after
configuration after installation, but before live sending

The first three cannot be cheaply reversed after the fact. Changing the group ID after installation means redoing permissions across all directories; a debugger installed after a crash will tell you nothing about that crash.

Do not keep the template. It is good for making sure the engine works and for nothing beyond that.

The “before and after” split is ours. From the manual here are the list of steps itself, the optional group creation and debugger installation and the note that after the first start the engine starts by itself.
Example configuration
# the order in which the steps cannot be rearranged
groupadd -g 5000 pmta          # before installation, if the ID matters
rpm -Uvh PowerMTA-*.rpm
cp license /etc/pmta/license   # before the first startsystemctl start pmta
The highlighted line comes before the start for a reason: without the key the engine will not start. The top line is needed only where the numeric group ID must match across machines.
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▶

Keeping the template file as the working configuration

§ 2.4

What it costsThe engine starts with it and mail flows — which is why the problem is noticed late. Meanwhile the node may lack the responsible person’s address and have vendor defaults where your own values are needed.
How to spot itThe configuration looks untouched, while the node has long been in service.
How to do it rightCheck the template against the initial configuration requirements before live sending, not after.

Creating the group after installation

§ 2.4

What it costsThe package will create it itself with an ID the system chooses. Bringing the ID to the required one later means redoing permissions across all the engine’s directories.
How to spot itThe numeric group ID differs across the fleet’s nodes.
How to do it rightCreate the group before installation wherever the ID must match.

Installing the debugger after the first crash

§ 2.4

What it costsIt will tell you nothing about that crash — information is collected at the moment of the event. Deciding to install it makes sense only in advance.
How to spot itThere was a crash, and there is nothing to analyze.
How to do it rightInstall the debugger when setting up the node, not after the fact.
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

License fileThe file is put in place during installation; without it the engine will not start. § 2.2Initial configurationThe sixth installation step: the template is checked against the requirements, not accepted as is. § 2.2

Depends on

Prepare a machine for the engineAll the machine requirements must be met before this step. § 1.2

Works together with

The group that grants management rightsThis is the very group that is created in advance when its numeric ID must match across machines. § 2.2

Referenced from

Upgrading the engineA first installation goes through the same steps, only without the license compatibility check. § 2.2Installing on WindowsA related procedure: they share some of the steps. § 2.1Removing the engineA related procedure: they share some of the steps. § 2.4Running in an imageThe procedure in which the mechanism is applied. § 11.23

How to check on the node
After installation, three things are checked in a row:
pmta show version && pmta show license
pmta test config
ps -ef | grep -c '[p]mtad\|[p]mtawatch'
The first shows the version and that the license was accepted. The second shows that the configuration parses. The third shows that the watchdog is running next to the engine: without it the node will not come back up on its own after a crash.
◇

What else to read

3 articles

◇The activation key is a prerequisite for installation, not a step after itWithout an activation key from SparkPost support the engine neither installs nor runs, and the license tier sets the outbound connection ceiling: on Standard everything above 200 is ignored.◇Cloud restrictionsClouds restrict outbound mail on port 25 until you ask them to lift the limit, and mailbox providers treat their address ranges with suspicion.◇How to turn a sending plan into hardwareTwo constants for sizing any node: about 2 KB of memory per queued recipient and spool space proportional to the total size of the messages.

In the Hub
Cost of a mistake
disruptive: applying it interrupts the node
Scenarios
Prepare a node for sending
Priority
critical