Demo
Demo

Knowledge base

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

auth-username

<domain>

The user name the node uses to identify itself to the receiver
in the configuration this is a lineauth-usernameinside the block <domain>
When sending not to the open internet but through someone else’s relay

Ordinary mail sending to a receiver does not require authentication. It is needed where the node hands messages not to the final recipient but to an intermediate relay — its own gateway, a delivery service, a corporate server — and that relay only lets its own in.

The enabling condition is compound. Authentication starts when everything matches at once: the receiver has advertised the AUTH extension, a mechanism supported by the node is among its mechanisms, and at least one of the two lines — this one or auth-password — is non-empty.

Three mechanisms are supported: CRAM-MD5, LOGIN and PLAIN. The first does not send the password over the network; the other two do, and that is why their use on an unencrypted connection is separately restricted by the use-unencrypted-plain-auth line.

The main trap is “at least one of the two.” If you fill in only the name and forget the password, you still enable authentication — the node will start it with an empty password and get a refusal. The refusal will come from the receiver and look like a delivery problem, while the cause is a half-filled pair.
What the Hub does. It does not write it: Hub nodes send directly to recipients, not through an intermediate relay. The line will be needed if a scenario of delivery through someone else’s gateway appears.
Recommended values

Fill in the pair completely. A non-empty half enables authentication by itself.

A separate account for each node. A shared one for the whole fleet allows neither revoking access selectively nor telling from the relay’s logs who exactly sent.

An empty string clears the inherited value — this is how authentication is turned off for one recipient if it is set more broadly.

The requirement of a separate account per node is ours. From the manual here come the compound enabling condition, the three supported mechanisms and clearing with an empty string.
Example configuration
# we hand mail over through an intermediate relay that only lets its own in
<domain relay.example.com>
    auth-username relay-user    auth-password s3cr3t
</domain>
The pair is filled in completely: a non-empty half will enable authentication by itself, and the attempt will go out with an empty password.
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▶

Filling in only the name

§ 3.3.10.62

What it costsAuthentication is enabled anyway — with an empty password. The receiver responds with a refusal, and this looks like a delivery problem, not like an unfilled configuration line.
How to spot itRefusals mentioning authentication for one recipient.
How to do it rightFill in the pair completely or clear both lines with an empty value.

One account for the whole fleet

our experience

What it costsAccess cannot be revoked for one node — only for all at once. In the relay’s logs all nodes look the same, and figuring out whose stream raised questions is impossible.
How to spot itThe same name in the configuration of all nodes.
How to do it rightCreate a separate account per node.
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
auth-username <string>
Values
a user name as a string; an empty string clears the inherited value
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 value merges across <domain> blocks from general to specific: the best-matching block wins, not the last one in the file. An empty string (“”) clears the inherited value. It is picked up by pmta reload; it does not affect open connections.
⇄

Related directives

1 relation

Works together with

auth-password<domain>The second half of the pair. Authentication starts if at least one of the two is non-empty — both must be filled in. § 3.3.10.62

Referenced from

add-x-msys-api-header<domain>The service account and subaccount are set in the user name, not by this line. § 3.3.10.113.1add-x-msys-api-header-metadata<domain>The line works only inside traffic redirection, and that starts with authentication at the service. § 3.3.10.113.2sparkpost-sandbox<domain>Redirection starts with authentication with the service; without it, the sandbox has nothing to apply to. § 3.3.10.113.3sparkpost-ip-pool<domain>Redirection starts with authentication at the service; without it the line has nowhere to go. § 3.3.10.113.4

How to check on the node
The value is printed by the queue settings command; whether the receiver advertises the extension and which mechanisms it offers is visible in its response to EHLO:
pmta show settings relay.example.com/vmta1 | grep -i auth-username
grep -i '250-AUTH' /var/log/pmta/pmta.log | tail -5
The password is visible in the settings output: the command should not be run where someone is reading the output over your shoulder. The Hub does not set outgoing authentication.
◇

What else to read

3 articles

◇How the policy for a receiver is assembledSettings are assembled from the most general pattern to the most precise; the order of blocks in the file means nothing.◇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.◇Reputation monitoring inside the nodeThe engine itself watches the receiving servers’ replies and changes the queue mode on a pattern match — a reaction within the connection, not through telemetry.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Troubleshoot deliverability · Tune the pace for a provider
Neighboring settings of the block <domain>:file-destinationcommandconnect-timeoutallow-cancel-during-transferassume-delivery-upon-data-termination-timeoutAll 135 directives of the block →