Demo
Demo

Knowledge base

PMTA knowledge base›Block <vault>›Directive§ 3.3.23.1

server-url

<vault>

The address of the secrets vault
in the configuration this is a lineserver-urlinside the block <vault>
Where the node goes for secrets

The line names the vault server: the scheme, the name or address and, if needed, the port.

The scheme matters. http means the token and the secrets themselves travel over the network in plain text — that is, the vault stops being a vault. For anything other than a test bench, https is required.

This is an external dependency on the configuration reading path. An unavailable vault means the node will not read the signing keys and the certificate — and this will surface at reload.

The main trap is not noticing that a dependency has appeared. Before the vault was connected, the node read secrets from its own files and depended on nothing. After that, a configuration reload requires the vault to respond. And that is exactly the moment when people usually reload.
What the Hub does. It does not write it: secrets are placed on the node as files. When connecting a vault in the future, this dependency will have to be accounted for in the configuration apply order: today the Hub puts the file and reloads, and with a vault a third party appears between these steps.
Recommended values

The value is an address with a scheme:

What Note
https://name the usual case; the default port
https://name:port if the vault listens on a non-standard one
http://… test bench only: the token and secrets will go in plain text

Check availability before applying the configuration, not after.

The entry format comes from the manual (§ 3.3.23.1). The warnings about the scheme and the dependency at reload are ours.
Example configuration
# a vault on its own port, necessarily over https
<vault>
    server-url https://myvault:4500    access-token akhdfasdhf786282684734kjsdhf
</vault>
The manual’s example. The https scheme is not decoration here: both the token and the secrets themselves travel over this connection.
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 http for simplicity

our experience

What it costsThe token and secrets travel over the network in plain text. In such a setup the vault protects nothing and only adds a dependency.
How to spot itThe configuration has http://.
How to do it rightOnly https. If the vault’s certificate is self-signed, that is a separate question — but not a reason to give up encryption.

Not accounting for the dependency when applying configuration

our experience

What it costsThe node will not read the secrets while the vault is unavailable. Applying the configuration fails, and the cause is not in the configuration itself.
How to spot itThe reload fails even though the file has not changed.
How to do it rightCheck vault availability before applying — with the command from the reference, as a separate step.
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
server-url <url>
Values
http or https, the server name or address, a port if needed
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<vault>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The line has no inheritance: there is one <vault> block per node, and one address in it. PowerMTA does not support two vaults.
⇄

Related directives

2 relations

Works together with

domain-keyGlobalSigning keys are the main reason a vault is connected at all. § 3.3.23.1Lock down permissions on configuration filesThe vault removes secrets from the node’s files but does not cancel the requirements for the files themselves. § 3.3.23.1

How to check on the node
Vault availability is checked before applying the configuration:
curl -sI https://myvault:4500/v1/sys/health | head -1
A 200 or 429 code means the vault responds. No response means the configuration reload will fail: the node will not be able to read the secrets.
◇

What else to read

3 articles

◇Secrets in an external vaultSigning keys can be kept in HashiCorp Vault: the configuration keeps a path, and the engine fetches the key over HTTP and keeps it in memory without writing it to disk.◇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.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Key rotation · Node security
Neighboring settings of the block <vault>:access-tokencache-ttlAll 3 directives of the block →