Demo
Demo

Knowledge base

PMTA knowledge base›Procedure§ 2

Upgrading the engine

upgrading to a newer version
License check as the first step, not after

The procedure here is short, but the first three steps are about the license, and this is not a formality.

The key must be valid for the version being installed. The license is tied to the major version: a key from the previous one will not start the new one.

The support term is checked separately. Where the license has a field with the support end date, the current date must not exceed it — otherwise the upgrade will turn out to be impossible after the old package has already been replaced.

And only then — upgrading the package with the standard package manager.

The manual does not describe a rollback. Upgrading the package replaces the running engine, and returning to the previous version is a separate task the manual is silent about.

The main trap is upgrading and discovering an invalid license. The package is replaced first, and the license is checked by the engine at startup. If the key does not fit, the node is left with a new package that does not start and an old one that is already gone. Sending stops, and the solution is asking support for a key, that is, waiting. That is exactly why the license check comes before, not after.
What the Hub does. It does not upgrade the engine — whoever owns the node does that.

⚠️ And it cannot warn about expiration: the license tier and term do not come in telemetry, and the channel for vendor warnings — an email to the postmaster address — is not set in our setup (pmtawatch).

The Hub will restore the configuration after the upgrade: it keeps it with versions and applies it again. But a sending pause while the package is replaced is unavoidable.

Recommended values

What to check before upgrading:

What What skipping it risks
the key is valid for the new version the node does not start, the old package is already gone
the support term has not expired the same, but discovered later
the configuration is saved it will have to be restored from memory
a window for the pause replacing the package stops sending

There is no rollback — so the checks replace it. Everything that can be learned before replacing the package has to be learned before it.

Choose the window by the queue, not by the clock. Stopping is safe for messages — they stay on disk — but it is safer to do it when the queue is smaller.

The list of checks and the advice about the window are ours. From the manual here come the requirement of a license valid for the new version, the support term check and the order of steps itself.
Example configuration
# the checks come first — the manual does not describe a rollback
pmta show licenserpm -Uvh PowerMTA-new-version.rpm
pmta show version && pmta test config
The highlighted line answers both license questions at once — tier and term. Skipping it means learning about an invalid key when the old package is already gone.
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▶

Upgrading the package without checking the license

§ 2.6

What it costsThe check happens when the new engine starts, when the old package is already gone. The node is left with something that does not start, and sending stays stopped until a key comes from support.
How to spot itAfter the upgrade the engine does not start, and the log shows a license refusal.
How to do it rightQuery the license tier and term before upgrading. This is the only protection — the manual does not describe a rollback.

Assuming queued messages will be lost

§ 2.6

What it costsThe opposite: messages sit on disk and are picked up after the start. Because of this fear the upgrade is postponed until an “empty queue” that never happens.
How to spot itThe upgrade gets postponed for months.
How to do it rightChoose the window by queue size instead of waiting for the queue to empty. The pause equals the time it takes to replace the package.

Counting on a rollback

§ 2.6

What it costsThe manual does not describe one. Returning to the previous version is a separate task you will have to solve yourself, at the moment when sending has already stopped.
How to spot itThe upgrade plan contains a step “if anything goes wrong, we will roll back.”
How to do it rightReplace the hope for a rollback with pre-upgrade checks and a saved configuration.
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

Depends on

License fileDuring an upgrade the file stays in place, but the key in it must be valid for the new version. § 2

Works together with

Installing on LinuxA first installation goes through the same steps, only without the license compatibility check. § 2.2

Referenced from

openssl-security-levelGlobalMoving to PowerMTA 6 from an earlier version is the moment when old keys and certificates are first checked by the new OpenSSL. § 3.3.1.51Engine versionThe procedure in which this command is one of the steps. inferenceLicense informationThe procedure in which this command is one of the steps. inferenceEngine version rollback and configuration via the APIThe procedure in which the mechanism is applied. inference

How to check on the node
After the upgrade, check the same things as after installation:
pmta show version && pmta show license
pmta test config
pmta show status
The Queues line in the last command should match what it was before the upgrade: during the package replacement messages sit on disk and are picked up after startup.
◇

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