Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.35

host-name

Globalcritical

This node's names and the name in the SMTP greeting
in the configuration this is a linehost-nameinside the block Global
The same name 1:Global<virtual-mta>— some of them are other settings, some are the same one
Node names and the name in the greeting

Declares the fully qualified domain names the node answers to. It can be repeated, and the order matters: the first name is the main one, it goes into the Received headers and into the Message-ID that the node generates itself.

Which name ends up in the greeting is decided by a five-step resolution — the most convoluted order in this part of the manual. From top to bottom: the source default default-virtual-mta; if it names a sending address — the name tied to the matching address of that stream; if a pool — the name of its first member, without rotation; if the reserved value is set — the name of the stream whose address matched the connection address; otherwise — the first matching name from the general smtp-source-host or smtp-proxy-source-host; and only if nothing matched — the first name from here.

A side effect that is easy to forget. The manual writes that the directive behaves like relay-domain: the node starts accepting mail for the declared domain. By declaring a name, you also declare your readiness to serve it.

The main trap. Because of resolution, on many nodes this directive does not affect the greeting at all: the name is taken from the sending address — the second word of smtp-source-host — and editing it here achieves nothing. It looks like “the setting was not applied,” but in fact it is overridden.
What the Hub does. It does not write it at all. The Hub sets the greeting name as the second word of smtp-source-host on every sending address — that is a different directive, and resolution takes it earlier. The Hub checks the forward and reverse records before putting an address into service: a mismatch is a warning, not a ban.
Recommended values

What to set. The value is a fully qualified domain name; it can be repeated, the first is the main one. On a fleet node the choice is simple:

How to set it For whom Why
do not set it at all a fleet with a name on every sending address resolution never reaches this line
one node name a single node with one address the node name is the sender name
several names a node that accepts mail for several domains remember the side effect of accepting

Never count on one name for a fleet: five addresses need five names, and they are set on the addresses themselves, not here.

The five-step resolution, “the first is the main one” and the side effect of accepting mail come from the manual. The advice not to set it in a fleet is ours.
Example configuration
# the node's name — and with it, consent to accept mail for this domain
host-name mail.example.com
# while the greeting name for this address's messages is taken from here
<virtual-mta shop-example-com>
    smtp-source-host 203.0.113.10 shop.example.com
</virtual-mta>
Messages through shop-example-com will introduce themselves as shop.example.com, not mail.example.com: resolution takes the sending address’s name earlier. The top line meanwhile still means that the node accepts mail for mail.example.com.
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 ends3 mistakes▶

Editing the name here while it is set on the sending address

§ 3.3.1.35

What it costsResolution takes the sending address’s name earlier. The edit applies without errors and changes nothing — the node introduces itself with the old name.
How to spot itThe configuration has been reloaded, but EHLO shows the old name.
How to do it rightEdit the second word of smtp-source-host in the right sending address. Touch this directive only where the addresses have no names at all.

Declaring a name without intending to accept mail for it

§ 3.3.1.35

What it costsThe directive behaves like relay-domain: the node starts accepting messages for the declared domain. For a domain whose mail is handled by someone else, this is a quiet interception of part of the flow.
How to spot itThe node receives messages for a domain that is not served here; accounting shows incoming mail with unexpected recipients.
How to do it rightDeclare here only the names whose mail the node really must accept. The greeting name is not set here.

Setting a pool name as the source default and expecting names to rotate

§ 3.3.1.35

What it costsFor a pool, resolution takes the name of the first member and does not change it. All the pool’s addresses introduce themselves with one name, and for all but one it disagrees with the reverse record.
How to spot itA mismatch between the greeting name and the reverse record on all of the pool’s addresses except the first.
How to do it rightSet the name for each sending address separately — as the second word of smtp-source-host: then resolution never reaches the pool.
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 <fully-qualified-name>
Values
fully qualified domain names; repeatable, the first one counts as the main one
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
Global, <virtual-mta>
How many times
may be repeated
Everything here comes from the manual, with the section.
Inheritance
The directive is written at the root of the file, in the Global section, and applies to the whole node. Written inside <virtual-mta>, it overrides the general name for messages leaving through that sending address. But overriding is not the last word: the five-step resolution still looks earlier at the name tied to the address in smtp-source-host.
⇄

Related directives

4 relations

Depends on

smtp-source-hostGlobalResolution takes the name tied to the sending address earlier than this directive. § 3.3.1.35smtp-proxy-source-hostGlobalTakes part in the same resolution, including the case of selection by connection address. § 3.3.1.35default-virtual-mta<source>Resolution of the greeting name starts from this line: it decides which sending address to take the name from. § 3.3.1.35

Works together with

relay-domainGlobalA side effect: the node starts accepting the declared name as its own domain — exactly as if you had declared it with this directive. § 3.3.1.35

Referenced from

A group of sending addresses with traffic sharesA pool set as the source default always introduces itself with the first member’s name — without rotation. § 3.3.1.35host-name<virtual-mta>The manual defines the directive at the node level; here is only what writing it inside a sending address changes. § 3.3.1.35client<proxy>If the name in the second part of the line is not set, the sending address’s name is used. § 3.3.22.2

How to check on the node
Arguing about resolution is pointless — it is more reliable to look at what the node actually introduces itself as:
swaks --server 203.0.113.10 --to probe@example.net --quit-after HELO
The reply shows the name from the EHLO command. It must match what dig -x 203.0.113.10 +short returns. If the name is not the one you set here, resolution took it higher up, from the sending address, and that is where to edit it.
◇

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 · Message signing and authentication
Priority
critical
Neighboring settings of the block Global:smtp-source-hosthttp-accessdomain-keypostmastersmtp-proxy-source-hostAll 108 directives of the block →