Demo
Demo

Knowledge base

PMTA knowledge base›Block <domain>›Directive§ 3.3.10.108.1

use-starttls

<domain>set by the Hub

Whether to encrypt the connection to this receiver
in the configuration this is a lineuse-starttls trueinside the block <domain>
Encryption to the receiver — on by default

The line allows the node to use the STARTTLS extension when the receiver offers it. The default is true, that is, encryption already works, and this line usually needs to be touched not to turn it on but to understand why it is off.

This is a permission, not a requirement. The receiver may not offer STARTTLS, or the negotiation may fail — and then the message will go out in plain text. Insisting on encryption is the job of the neighboring line require-starttls.

Almost all other TLS settings of this block depend on it: protocol versions, cipher sets, certificate verification, DANE and MTA-STS. By turning it off, you turn them all off at once.

The main trap is taking enabled encryption for guaranteed encryption. use-starttls without require-starttls means “we will encrypt if we can.” The share of messages sent in plain text does not catch the eye anywhere: delivery succeeded, there was no refusal.
What the Hub does. It writes yes in all fifteen blocks of the policy template — for large receivers and in the general one — explicitly, even though it is the default: the configuration should be readable without knowing the defaults. Right next to it is require-starttls yes: encryption is mandatory for us for all receivers, and unencrypted delivery counts as a failure, not a fallback.
Recommended values

The default is already right. The meaningful cases for turning it off are few:

Value When
yes (default) always
no the receiver advertises STARTTLS and then fails on it — a rare but real behavior of old servers

Turn it off only for a specific receiver, in its block, not in <domain *>. And only after the log shows that negotiation really fails.

The true default and the dependence of the other TLS settings come from the manual (§ 3.3.10.108.1). The advice to turn it off only pointwise is ours.
Example configuration
# encryption on and mandatory — this is how the Hub's policy template writes it
<domain $mailru>
    use-starttls yes    require-starttls yes
</domain>
The first line allows encryption, the second makes it mandatory. Without the second, the message will go out in plain text if the receiver did not support STARTTLS — and it will be an ordinary successful delivery.
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▶

Considering encryption guaranteed

§ 3.3.10.108.2

What it costsWithout require-starttls the message goes out in plain text every time encryption fails to be established. Delivery succeeds, there is no refusal, and this can be noticed only in accounting.
How to spot itSome messages have an empty protocol version field, even though encryption is “on.”
How to do it rightFor receivers where encryption is mandatory, put require-starttls yes next to it — and accept that some messages will then not go out at all.

Turning off encryption entirely because of one receiver

our experience

What it costsA line in <domain *> turns off encryption for the whole fleet. Along with it, certificate verification, DANE and MTA-STS stop working — that is, everything that depends on encryption.
How to spot itAll receivers have an empty protocol version field in accounting.
How to do it rightTurn it off in the specific receiver’s block, not in the common one. And first make sure from the log that the problem really is the negotiation.
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
use-starttls <boolean>
Values
yes | no | true | false
Default
true § 3.3.10.108.1
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<domain>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <domain> and merges by the usual rule for recipient blocks: the value from <domain *> sets the base, a specific receiver’s block refines it, and the most precise match wins. The same three levels also apply by sending address: node, <virtual-mta-pool>, <virtual-mta>.
⇄

Related directives

2 relations

Depends on

use-dane<domain>DANE verification makes sense only with encryption enabled — there is nothing for it to check without it. § 3.3.10.108.3

Works together with

require-starttls<domain>Decides what to do if encryption could not be established: give up on delivery or send in plain text. § 3.3.10.108.2

Referenced from

use-mta-sts<domain>The receiver’s policy requires an encrypted connection: without one the verification is bound to fail. § 3.3.10.108.4smtp-tls-max-version<domain>Version settings make sense only with encryption enabled. § 3.3.10.108.12smtp-client-certificate<domain>The client certificate is presented during the encrypted negotiation and plays no part without it. § 3.3.10.108.13smtp-tls-ca-file<domain>A certificate chain can be verified only on an encrypted connection. § 3.3.10.108.14smtp-tls-ciphers<domain>The cipher set is negotiated during encryption and does not apply without it. § 3.3.10.108.15smtp-tls-v1.3-ciphersuites<domain>The version 1.3 cipher set is negotiated during encryption and does not apply without it. § 3.3.10.108.16

How to check on the node
That the connection is actually encrypted is visible in accounting — there is a field with the protocol version:
pmtaacctfind --output csv[rcpt,dsnStatus,dlvTlsProtocol] /var/log/pmta/acct-*.csv | head -20
An empty version field means the message went out without encryption — if dlvTlsProtocol is named in record-fields; on Hub nodes it is not named, and the column is always empty. If there are many such records while the line is on, the receiver does not offer STARTTLS or the negotiation fails; log-tls logs the details.
◇

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
Managed at
DNS → Signing keys
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 <domain>:use-mta-stssmtp-tls-min-versionuse-danerequire-starttlssmtp-client-certificateAll 135 directives of the block →