Demo
Demo

Knowledge base

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

log-tls

<domain>

Whether to log the course of TLS negotiation
in the configuration this is a linelog-tls falseinside the block <domain>
The same name 2:<domain><source><transmissions-api>— some of them are other settings, some are the same one
The only way to find out why encryption did not come together

The line enables detailed logging of the TLS negotiation with this receiver. The default is false.

This is a diagnostic switch, not a permanent setting. Accounting shows the result — the negotiated version and cipher or an empty field; the log shows why there is no result: STARTTLS was not offered, no common cipher was found, the certificate chain did not match.

Enable it in a targeted way and temporarily. There are many records, and at volume they noticeably add to the log.

The main trap is leaving it on after the investigation. The log grows, rotation speeds up, and the needed records about other events are pushed out sooner. A switch enabled for one receiver gets forgotten because the harm is not visible right away.
What the Hub does. It does not write it: it is enabled by hand for the duration of an investigation. Keep in mind that the Hub overwrites the configuration entirely on every apply — a line added by hand will disappear on the next apply, and this is exactly the case when that is how it should be.
Recommended values

The value is boolean, the question is when to enable it:

Value When
no (default) always in normal operation
yes investigation: the protocol version field in accounting is empty, and you need to understand why

Order of investigation. First accounting — is there a protocol version; if not, enable the log for one receiver, look at the cause, disable it.

The default false is from the manual (§ 3.3.10.108.17). The order of investigation and the warning about log volume are ours.
Example configuration
# for the duration of the investigation, for one receiver
<domain broken.example.com>
    use-starttls yes
    log-tls true</domain>
After the investigation the line is removed. It is not put into <domain *>: negotiation details with all receivers at once are a noticeable log volume with no benefit.
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 ends1 mistake▶

Forgetting to disable it after the investigation

our experience

What it costsThe log grows, rotation speeds up, and records about other events are pushed out before their time. This becomes noticeable when last week’s history is needed.
How to spot itThe logs for the needed day have already been deleted by rotation.
How to do it rightRemove the line right after the investigation. With edits through the Hub it will disappear anyway on the next configuration apply.
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
log-tls <boolean>
Values
yes | no | true | false
Default
false § 3.3.10.108.17
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 most precise match by receiver name wins. The same three levels apply by sending address — node, <virtual-mta-pool>, <virtual-mta>.
⇄

Related directives

1 relation

Does not work without

use-starttls<domain>There is nothing to log while encryption is off. § 3.3.10.108.17

How to check on the node
Records go to the node’s log; look for them by receiver name:
grep -i "tls" /var/log/pmta/pmta.log | tail -30
The lines show what the receiver offered, which version and cipher were negotiated, and at which step it failed. Empty with the line enabled — the matter never got to negotiation at all: the connection was not established.
◇

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
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connection encryption
Neighboring settings of the block <domain>:use-starttlsrequire-starttlssmtp-tls-min-versionuse-daneuse-mta-stsAll 135 directives of the block →