Demo
Demo

Knowledge base

PMTA knowledge base›Block <virtual-mta>›Directive§ 3.3.12.5

host-name

<virtual-mta>critical

The name in the greeting for messages from this sending address
in the configuration this is a linehost-nameinside the block <virtual-mta>
The same name 1:Global<virtual-mta>— some of them are other settings, some are the same one
This sending address’s name — and its place in resolution

The syntax is the same as at the node level. What changes is the scope: the name applies only to messages leaving through this sending address.

But overriding the general name is not the last word. Name resolution for the greeting looks earlier at the name tied to the address itself — the second word of smtp-source-host. As long as it is there, this line has no effect.

Hence its real place. It is needed where no name is tied to the address: the address is given as a range, or the address line is omitted altogether and inherited from the node. In a regular fleet, where each sending address has its own “address plus name” pair, the directive is not needed at all.

The main trap. The line looks like a direct way to give a stream a name — and stays silent if a name is already tied to the address. The edit applies without errors and changes nothing; people look for the cause in DNS, while it lies in the resolution order.
What the Hub does. It writes it neither here nor at the node level: the name is set as the second word of smtp-source-host on each sending address. The Hub checks the forward and reverse records before putting an address into service — a mismatch shows as a warning, and the address can still be put into service.
Recommended values

The value is the same — a fully qualified domain name. The question here is a different one: whether the line is needed at all.

How the sending address is set Is this line needed
an “address plus name” pair in smtp-source-host no: the name is taken from there, resolution will not get here
an address as a CIDR range yes: a range has one name for all addresses, and there is nowhere else to set it
the address line is omitted yes, but better not to omit the address line

The name must match the reverse record of the address the message leaves from. With a range this condition cannot be met for all addresses at once — one more reason not to give addresses as ranges.

The directive’s place in resolution comes from the manual (§ 3.3.1.35). The conclusion “a fleet does not need it” is ours.
Example configuration
# the name is needed here precisely because the address is given as a range
<virtual-mta bulk>
    smtp-source-host 203.0.113.0/28
    host-name mail.example.com</virtual-mta>
A range has no name in the second position, so resolution goes further — down to this line. All sixteen addresses will introduce themselves with one name, and at best it can match the reverse record of only one of them.
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▶

Setting the name here when one is already tied to the address

§ 3.3.1.35

What it costsResolution takes the address’s name earlier. The line applies without errors and affects nothing; yet it creates the impression that the name is set — and the next person will look for the error in the wrong place.
How to spot itThe configuration has one name, EHLO shows another, and there are no errors on apply.
How to do it rightEither edit the second word of smtp-source-host or, if the line here is really needed, remove the name from the address pair.

One name for a range of addresses

our experience

What it costsThe addresses in the range have different reverse records, but there is one name in the greeting. It can match at most one address; for the rest the receiver sees a mismatch.
How to spot itSome messages from one sending address are delivered noticeably worse than the rest, and the difference matches the delivery address in accounting.
How to do it rightSplit the range into smtp-source-host lines — one address and its own name in each.
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
host-name <see-global>
Values
a fully qualified domain name
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<virtual-mta>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
Here the entry overrides the node’s general name for this sending address’s messages, and the pool one is an intermediate level: <virtual-mta-pool> hands its value to the members, and a member overrides it with its own. But this whole order applies only when resolution reaches it: a name tied to the address in smtp-source-host is stronger than any of the three levels.
⇄

Related directives

2 relations

Same name in other blocks

host-nameGlobalThe manual defines the directive at the node level; here is only what writing it inside a sending address changes. § 3.3.1.35

Applies to

The sending address — what it is made ofOne of the settings that make up a sending identity. § 3.3.12.5

How to check on the node
Look not at the configuration but at what the node actually introduces itself as:
swaks --server 203.0.113.10 --to probe@example.net --quit-after HELO
The name from EHLO is checked against dig -x 203.0.113.10 +short. If it is not the one set here, resolution took it earlier, from the “address plus name” pair, and it is smtp-source-host that needs editing.
◇

What else to read

3 articles

◇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.◇Backoff mode — the queue's second personalityA queue that a receiver has started refusing switches to a parallel set of limits, retries and routes — ten directives that act only in this mode.◇Warm-up built into the engineA warmed-up address hands the first N messages of the day for each receiver to its cold partner; the partner sends them itself and builds history.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Sending address rotation
Priority
critical
Neighboring settings of the block <virtual-mta>:smtp-source-hostdomain-keyproxy-include-tlvproxy-protocolinclude-headers-fromAll 15 directives of the block →