Demo
Demo

Knowledge base

PMTA knowledge base›Block <source>›Directive§ 3.3.7.13

allow-starttls

<source>set by the Hub

Whether to let the client start encryption during submission
in the configuration this is a lineallow-starttls falseinside the block <source>
Without this line the node does not even offer encryption

The line allows the node to advertise the STARTTLS extension to clients submitting through this source. The default is false, and this matters: without the line the node does not even mention encryption, and submission goes in plain text, passwords included.

It works only together with a certificate. smtp-server-tls-certificate at the node level is what the node will present; without it there is nothing to present.

This is a permission, not a requirement. The client may not use it. Two neighboring lines can insist: require-starttls — encryption before any commands, and require-starttls-before-auth — encryption at least before the password.

It has to go into the right source. The permission is granted to the block the submitter’s address falls under; in a narrow block it overrides the value of the wide one.

The main trap is putting the permission in a submission source rather than the general one. Submission sources are selected by login, while STARTTLS is offered before authentication: at the moment the extension is advertised, the node does not yet know who has arrived. So encryption has to be allowed in the source matched by address — usually <source> 0/0.
What the Hub does. It writes true — in the base configuration, in the general 0/0 source, and the comment there explains why: STARTTLS is offered before authentication, while submission sources are selected by login, and the line would not work in them. Without it, a platform configured for encrypted submission drops off with “failed to send test.”
Recommended values

The value is boolean, and the question is in which source:

Where Applies to Why
<source> 0/0 all submitters STARTTLS is advertised before authentication — this is the only place that works
a source by login nobody by the time of advertising, the login has not been given yet
a narrow subnet that subnet if submission comes only from there

And a certificate is mandatory at the node level: without it the permission gives nothing.

The false default comes from the manual (§ 3.3.7.13). The rule about the source matched by address is ours, from the base configuration template.
Example configuration
# this is how the Hub writes the base configuration — in the general source
<source 0/0>
    allow-starttls true    allow-unencrypted-plain-auth yes
</source>
The line is in the block matched by address, not in the submission sources: those are selected by login, and encryption is offered earlier. A comment about this is in the template itself.
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▶

Putting the permission in a submission source

our-experience

What it costsSubmission sources are selected by login, while STARTTLS is offered before authentication. The line does not work, the node says nothing about encryption, and a platform with mandatory TLS does not connect at all.
How to spot itThe platform reports “failed to send test,” and submission does not go through.
How to do it rightPut it in <source> 0/0 or in a subnet block that matches by the submitter’s address.

Allowing encryption without a node certificate

our-experience

What it costsThere is nothing to present, and the negotiation fails. Meanwhile the configuration says “encryption allowed.”
How to spot itThe client sees the STARTTLS offer, but the connection does not come up.
How to do it rightSet smtp-server-tls-certificate at the node level. The Hub issues a self-signed one itself.
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
allow-starttls <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.13
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<source>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <source> and merges by the source rule: a narrower block overrides a wider one. But source selection happens before authentication, by the submitter’s address — which is why named sources and sources by login never get to this line.
⇄

Related directives

2 relations

Does not work without

smtp-server-tls-certificateGlobalPermission to start encryption is pointless without a certificate: there will be nothing to present. § 3.3.1.10

Works together with

require-starttls<source>The strict form of the requirement: the client must encrypt before any commands except the greeting and service ones. § 3.3.7.14

Referenced from

allow-unencrypted-plain-auth<source>The encryption permission is what makes this setting meaningful: without it there are simply no encrypted connections. § 3.3.7.13log-tls<source>There is nothing to log until clients of this source are allowed to start encryption. § 3.3.7.33immediate-tls<smtp-listener>Another way to encrypt submission: there encryption begins at the client’s command, here from the first byte. § 3.3.17.2

How to check on the node
Checked from outside — whether the node advertises the extension at all:
openssl s_client -starttls smtp -connect localhost:25 -quiet
A successful negotiation means both the permission and the certificate are in place. A refusal saying STARTTLS is not supported means either there is no line or it is in a source that did not match by address.
◇

What else to read

3 articles

◇Submission over HTTPS on its own listener, modeled on SparkPostA separate entry point: its own listener with a certificate, its own keys and a reserved source name through which the usual submission settings apply to such mail.◇The receiver declares an encryption requirement on its websiteThe node fetches the recipient domain’s policy over HTTPS and, if it is in enforce mode, delivers only when the MX matches, the connection is encrypted and the certificate is verified.◇The receiver declares an encryption requirement in its DNS zoneThe node looks at the recipient domain’s DANE records and, if STARTTLS is required, sends only over an encrypted channel with a certificate verified by fingerprint.

In the Hub
Value
The Hub picks it itself — pace, warm-up stage, metrics
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connection encryption
Neighboring settings of the block <source>:require-starttls-before-authrequire-starttlssmtp-serviceretain-x-dkim-keyprocess-x-dkim-keyAll 74 directives of the block →