Demo
Demo

Knowledge base

PMTA knowledge base›Block <transmissions-api>›Directive§ 3.3.20.4

log-tls

<transmissions-api>

Whether to log the course of the TLS handshake at the Transmissions API input
in the configuration this is a linelog-tls falseinside the block <transmissions-api>
The same name 2:<domain><source><transmissions-api>— some of them are other settings, some are the same one
Details of the API submission handshake

With the value true the engine logs how encryption negotiation with the submitting client went. Off by default.

The switch and the TLS settings themselves live in different blocks. Input encryption is configured in <transmissions-api-listener>, while this switch lives in <transmissions-api>. The split is confusing: people look for the logging next to what it logs.

It writes to the engine’s common log, not a separate one — unlike the web monitor with its own log.

The line is needed exactly for the duration of an investigation. Successful handshakes are monotonous, and on a submission flow the volume is noticeable.

The main trap is looking for the switch in the input block. The encryption settings are there, but the logging is in the neighboring block. Until this is noticed, it seems the logging simply does not work.
What the Hub does. It does not write it: our submission goes over SMTP, and there is no API block in the configuration. The closest counterpart for SMTP submission is log-tls in <source>.
Recommended values

Enabled for the duration of an investigation and turned off afterwards:

Value When
no (default) normal operation
yes investigating why the submitting client does not negotiate encryption

The order of investigation. First make sure the client reaches the input at all, then enable logging, look at the cause, turn it off.

The false default and the purpose come from the manual (§ 3.3.20.4). That the example in this section shows the wrong directive is our finding. The advice to turn it off after the investigation is ours.
Example configuration
# for the duration of the investigation: the submitting client does not negotiate encryption
<transmissions-api>
    api-key 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
    log-tls yes</transmissions-api>
The manual in this section (§ 3.3.20.4) shows log-data yes in the example — not the directive the section is about. The example here is corrected.
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▶

Looking for the switch in the input block next to the TLS settings

our experience

What it costsThe encryption settings and the logging of their course are split across two blocks. Until this is noticed, the line is written in the wrong place, and no entries appear.
How to spot itThe line sits in the input block, and there is nothing in the log.
How to do it rightWrite it in <transmissions-api>, not in <transmissions-api-listener>.

Leaving logging on after the investigation

our experience

What it costsEvery connection of a submitting client adds lines to the engine’s common log — the very one where delivery history is searched for.
How to spot itThe log grows faster than usual, and rotation speeds up.
How to do it rightReturn no right after the investigation.
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.20.4
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<transmissions-api>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
No inheritance: the line is written in <transmissions-api> and applies to all API submission. It has no per-input split — there may be several inputs, but the switch is one.
⇄

Related directives

2 relations

Works together with

log-requests<transmissions-api>Both write to the engine log: this one about the handshake, that one about the requests themselves. § 3.3.20.2

Applies to

tls-min-version<transmissions-api-listener>Logs the course of the very handshake that the input settings control. inference

How to check on the node
The entries go into the engine’s common log:
grep -i "tls" /var/log/pmta/pmta.log | tail -30
The lines show the version, the cipher and the step at which it broke. Nothing with the line on means things did not get as far as negotiation: the client did not reach the input.
◇

What else to read

3 articles

◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇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.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connect a sending platform
Neighboring settings of the block <transmissions-api>:log-datalog-requestsapi-keymax-message-sizeAll 5 directives of the block →