Demo
Demo

Knowledge base

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

auth-password

<domain>

The password the node uses to identify itself to the receiver
in the configuration this is a lineauth-passwordinside the block <domain>
A secret stored in the configuration in plain text

The password for outgoing authentication. It works in a pair with auth-username: authentication starts when the receiver has advertised the AUTH extension, a supported mechanism is among its mechanisms, and at least one of the two lines is non-empty.

The # sign is not allowed in the password. The manual warns about this separately: the engine treats it as the start of a comment, and everything after it is discarded. The password silently becomes shorter — and the refusal will come from the receiver and look like invalid credentials.

The password sits in the configuration in plain text. Neither encryption nor a reference to a secret store is provided for this line — it is protected only by the file system.

The main trap is a hash sign in the password. A generated password may well contain one, and the truncation happens silently: in the configuration the line looks correct, while only its beginning goes into the conversation. The error then comes from the receiver, and people look for it anywhere but in a punctuation mark.
What the Hub does. It does not write it: nodes send directly to recipients. If a relay scenario appears, the password will have to be put into the configuration in plain text — and file permissions will become the only protection.
Recommended values

Exclude the hash sign when generating. This is not a recommendation but an engine limitation.

Configuration file permissions. The password is in it in plain text; all that protects it is the owner and the access mode.

The mechanism matters more than length. CRAM-MD5 does not send the password over the network at all; PLAIN and LOGIN do, and on an unencrypted connection their use is restricted by use-unencrypted-plain-auth.

The advice about generation and file permissions is ours. From the manual here come the ban on the hash sign with the reason for it and clearing with an empty string.
Example configuration
# a password without a hash sign — otherwise it will be silently truncated
<domain relay.example.com>
    auth-username relay-user
    auth-password s3cr3t-no-hash-sign</domain>
The engine treats everything after the hash sign as a comment and does not include it in the password — there will be no error or warning.
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▶

Using a generated password with a hash sign

§ 3.3.10.64

What it costsEverything after the hash sign is discarded as a comment. The password silently becomes shorter, the receiver responds with a refusal, and the cause is looked for in the credentials on its side.
How to spot itAn authentication refusal with a password known to be correct.
How to do it rightRegenerate the password without a hash sign.

Leaving the configuration readable

our experience

What it costsAny user on the node can read the password to someone else’s relay. Neither encryption nor a secret store is provided for this line.
How to spot itThe configuration file’s permissions are broader than the service user’s.
How to do it rightLock down the file: the owner is the service user, and access is for that user only.
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-password <string>
Values
a password as a string; the hash sign is not allowed — the engine treats it as the start of a comment; 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

Does not work without

Lock down permissions on configuration filesA secret in the configuration protected only by file permissions — hence the requirements for them. § 3.3.10.64

Referenced from

auth-username<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

How to check on the node
The password is printed in the settings output in plain text — the command is best run where nobody sees the output:
pmta show settings relay.example.com/vmta1 | grep -i auth-password
ls -l /etc/pmta/config
Configuration file permissions are the only thing protecting the password: in the line itself it is in plain text. 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>:use-unencrypted-plain-authdisable-acct-recordsbounce-afterretry-afterdkim-signAll 135 directives of the block →