Demo
Demo

Knowledge base

PMTA knowledge base›Block <smtp-listener>›Directive§ 3.3.17.4

tls-certificate

<smtp-listener>

This listener's certificate
in the configuration this is a linetls-certificate inherited from smtp-server-tls-certificateinside the block <smtp-listener>
The same name 2:<smtp-listener><smtp-user><transmissions-api-listener>— some of them are other settings, some are the same one
A certificate of its own for a separate entry point

The line names the certificate for connections arriving at this listener’s address and port. The form is the same as at the node level: a file or a reference to the secrets store, with the password as the second word, also optional.

It is inherited from smtp-server-tls-certificate — the manual says so directly. If it is not set here, the node certificate is presented.

Why separate them. Different entry points may serve different names: platform submission on one address, report receiving on another. A certificate with a matching name on each entry point spares clients mismatch warnings.

The main trap is the same as with the node certificate: a plain-text password. It is the second part of the line and ends up in backups. If the key is encrypted, the password is worth keeping in the secrets store.
What the Hub does. It does not write it: the node has two listeners — the submission port and the MX port — and both take the certificate from the node level: a self-signed one issued by the Hub itself. A separate certificate will be needed if an entry point gets a name of its own.
Recommended values

The setting is inherited from the node — it is worth setting here only when this entry point must be different:

What When
do not set it one entry point or a shared name — the node certificate is used
a file of its own the entry point has its own name, and clients verify it
a reference to the store the private key must not sit as a file on the node
Inheritance from the node certificate and the notation come from the manual (§ 3.3.17.4). The advice about the entry point name is ours.
Example configuration
# configuring one entry point; the rest take the node value
<smtp-listener 127.0.0.1:25>
    tls-certificate /var/lib/pmta/smtp.pem aaaa</smtp-listener>
The manual’s example. The password here is in plain text — exactly the reason the distribution supports references to the secrets store.
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 ends2 mistakes▶

Configuring the listener instead of the node when there is only one entry point

§ 3.3.17.4

What it costsThere is one listener, and configuring it is equivalent to configuring the node — but it is harder to find: it sits inside a block, not at the root of the file. The next person will look in the common settings.
How to spot itThe setting is not at the root of the file, yet the node’s behavior does not match it.
How to do it rightWith one entry point, set it at the node level. A listener setting is needed where there are several entry points and they differ.

Changing one listener and expecting all of them to change

our experience

What it costsThe line applies only to its own address and port. A neighboring entry point keeps working with the node value, and the difference shows up in the behavior of different clients.
How to spot itSome submitters see the new behavior, others the old one.
How to do it rightChange it at the node level — then the change goes to all entry points that do not set their own.
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
tls-certificate <path>
Values
a path to a PEM file or a reference to the secrets store, with the password as the second word if needed
Default
inherited from smtp-server-tls-certificate § 3.3.17.4
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<smtp-listener>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <smtp-listener> and applies to connections to its address and port. If not set here, it is inherited from the node level — from smtp-server-tls-certificate. There are no levels between them: a listener either sets its own or takes the common one.
⇄

Related directives

2 relations

Same name in other blocks

smtp-server-tls-certificateGlobalThe same setting at the node level: if not set on the listener, it is inherited from there. § 3.3.17.4

Applies to

smtp-listenerGlobalThe line lives inside a listener and applies to connections to its address and port. § 3.3.17.4

Referenced from

tls-certificate<transmissions-api-listener>The same-named line of the mail listener; here it is about a separate entry point, the API’s own. § 3.3.21.1

How to check on the node
Check the port of the listener in question — a neighboring one may have a different value:
openssl s_client -starttls smtp -connect 127.0.0.1:25 2>/dev/null | openssl x509 -noout -subject
The name in the certificate must match the one clients use to reach this entry point. If it is the node’s rather than the listener’s, the line is not here, and the common certificate applies.
◇

What else to read

3 articles

◇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.◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.◇The load balancer header at the entranceThe node reads the PROXY header at the start of an incoming connection and treats the address from it as the source; this works for both kinds of entry point.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Node security · Connect a sending platform
Neighboring settings of the block <smtp-listener>:tls-min-versionimmediate-tlstls-v1.3-ciphersuitestls-cipher-server-preferencetls-ca-fileAll 18 directives of the block →