Demo
Demo

Knowledge base

PMTA knowledge base›Block <include-config>›Directive§ 3.3.24.1

http-extra-headers

<include-config>

A file with headers for the configuration request
in the configuration this is a linehttp-extra-headersinside the block <include-config>
An access key — as a file, not in the address

The line names a file; each of its lines becomes a header of the HTTP request the node makes when fetching the configuration file.

It is designed for authorization. The manual gives exactly this example: Authorization with a key. The regular include form cannot do this — the address cannot contain a user name, a query string or a fragment, which means there is nowhere to pass the key through the address.

The node does not parse the contents. Only the form of the header line is checked; what header it is and what is in it does not matter to the engine.

The main trap is the file permissions. It holds the access key in plain form, and by default it is readable by everyone who has access to the configuration directory. Plus it gets into backups — that is, the key lives longer than anyone remembers it.
What the Hub does. It does not write it: the Hub assembles the configuration in full and puts it on the node itself rather than making the node fetch it. The opposite direction — the node pulling its configuration over HTTP — would mean the Hub has to be available at the moment the node reloads, and that is the worst moment for an external dependency.
Recommended values

The value is a file path. What goes in it and how to handle it:

What How
one header per line the usual form, Name: value
an access key in plain form — the engine offers no other options
file permissions as for the configuration, no broader
key rotation by editing the file and rereading the configuration

The engine will not check the contents. A typo in a header name will become not a configuration error but a refusal on the server side — and it will surface as a failed reload.

The file format and the fact that the contents are not parsed come from the manual (§ 3.3.24.1). The notes about permissions and key rotation are ours.
Example configuration
# the authorization header is set by a file
<include-config https://10.1.2.3:4000/my/config/file>
    http-extra-headers /etc/pmta/include-config-http-headers.txt</include-config>
The file contents from the manual — one line, Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bfd. The key is in plain text, so the file’s permissions are kept the same as for the configuration.
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▶

Leaving the file with the key accessible to everyone

§ 3.3.24.1

What it costsThe key is in plain text. Anyone with access to the configuration directory or its backup gains access to the configuration source — that is, the ability to substitute the node’s settings.
How to spot itIt is discovered during an access review, not in operation.
How to do it rightFile permissions — as for the configuration. And remember that the file gets into backups along with it.

Expecting the node to check the headers

§ 3.3.24.1

What it costsThe engine looks only at the form of the line. A typo in a header name or in the key will become a refusal on the server side, and on the node — a failed reload at an inconvenient moment.
How to spot itThe configuration stopped applying, and the cause is not in the configuration itself.
How to do it rightCheck the request from outside, with the command from the reference, before the configuration starts depending on it.

Putting an external dependency on the reload path

our experience

What it costsThe file is fetched on every configuration read. An unavailable source means the node cannot be reconfigured — exactly when that is usually needed.
How to spot itThe reload fails, although nothing was changed on the node.
How to do it rightEither keep a copy of the configuration locally and update it separately from reloads, or accept the dependency deliberately and monitor the source’s availability.
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
http-extra-headers <path>
Values
a file path, one HTTP header per line
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<include-config>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The line has no inheritance: it acts inside its <include-config> block. The block itself goes wherever include does — at the root of the file or inside <source>, <domain>, <virtual-mta>, <smtp-pattern-list> — and what it includes is read in its place.
⇄

Related directives

2 relations

Does not work without

Lock down permissions on configuration filesThe file usually holds an access key: its permissions must be the same as the configuration’s. § 1.6.3

Works together with

includeGlobalThe regular include form does not support headers — that is why this block exists. § 3.3.24

Referenced from

The node's main configuration fileIncluded files carry the same sensitivity as the main one. § 1.6.3

How to check on the node
That the request goes out with the right header is checked the same way as the address itself — from outside:
curl -sI -H "@/etc/pmta/include-config-http-headers.txt" https://10.1.2.3:4000/my/config/file
A 200 response means both the address and the header are accepted. 401 or 403 means the key did not fit, and on the node this will show up as a failed configuration reload, not as a warning.
◇

What else to read

3 articles

◇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.◇The group that grants management rightsMembership in the pmta group gives an unprivileged user the right to call the node’s commands and use submission.◇How the node selects a source and combines its settingsA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.

In the Hub
Cost of a mistake
dangerous: effects outlast a rollback
Scenarios
Node security