mxhop

Reference · configuration

Every key in the file.

The parser rejects unknown keys, so this list is complete: anything not on this page is a config error with a line number, not an undocumented feature. Three keys are required; everything else has a default stated here.

The shape of the file

# required
hostname = "mx.example.com"
listen = "0.0.0.0:25"
spool_dir = "/var/lib/mxhop/spool"

# optional, shown with its default
max_message_bytes = 26214400

[outbound]
ipv6 = false

[domains."example.com".aliases]
hi = "you@gmail.com"

[tls]
certificate = "/etc/letsencrypt/live/mx.example.com/fullchain.pem"
key = "/etc/letsencrypt/live/mx.example.com/privkey.pem"

[srs]
domain = "example.com"
secret_file = "/etc/mxhop/srs.key"
max_age_days = 7

[auth]
enabled = true
enforce = "dmarc"

[arc]
domain = "example.com"
selector = "arc1"
key_file = "/etc/mxhop/arc.key"

[queue]
retry_minutes = [1, 5, 15, 60, 240]
lifetime_hours = 48
sweep_seconds = 60

[observe]
listen = "127.0.0.1:9779"

Order does not matter, and neither does whitespace. What matters is that a block you include must be complete: [tls] without a key, or [arc] without a selector, is an error rather than a half-configured feature. Omit the whole block to turn the feature off.

Top level

KeyType / defaultMeaning
hostname stringrequired

The name this host calls itself. Used in the 220 greeting, in EHLO when delivering onward, in the Received: trace it adds, and as the default DSN sender (postmaster@<hostname>).

It must match the A record that resolves to this machine and the PTR of the address it sends from. Receivers check that round trip, and a mismatch is treated as a strong spam signal regardless of everything else being right.

listen socket addressrequired

Address and port to accept mail on, e.g. "0.0.0.0:25", "[::]:25", "127.0.0.1:2525". Port 25 needs privilege; see the service install for how to avoid needing it.

Ignored when systemd hands over a socket — then the socket unit's ListenStream decides, and mxhop logs which address it actually got.

spool_dir pathrequired

Where messages wait for a destination that is not taking them. mxhop creates tmp/, queue/ and frozen/ under it at startup.

Must be writable by the running user and must survive restarts: everything in it is mail somebody is waiting for. Mode 0750 is right — queued mail is mail. See Queue and spool.

max_message_bytes integerdefault 26214400(25 MiB)

Largest message accepted. Advertised to senders as SIZE in the EHLO response, so a well-behaved sender declines to start rather than being cut off; one that ignores it gets 552 5.3.4 at the point the limit is passed.

Set it at or above what your destination mailbox accepts. Gmail takes 25 MB, so the default matches; a lower value here means you refuse mail the destination would have taken.

[outbound]

ipv6 booleandefault false Whether to use IPv6 when delivering onward. Off by default, and deliberately: an IPv6 sending address needs its own PTR and its own SPF authorisation, and several large receivers hold IPv6 senders to a stricter standard than IPv4. Turn it on once you have a AAAA, a matching PTR, and SPF that covers both.

Leaving out the whole block is the same as ipv6 = false.

[domains."…".aliases]

One block per domain you accept mail for. A domain with no aliases accepts nothing. Four target forms are accepted, and Routing and aliases covers resolution order, loops and limits in full.

name = "addr"stringOne recipient.
name = ["a", "b"]array of stringsSeveral. Each gets its own delivery attempt and its own fate — one can be delivered while another defers.
name = { to, via }tableDeliver to to by connecting to the host via, skipping the MX lookup. check resolves every via host and fails if one has no address.
name = { reject }tableRefuse at RCPT TO with this reply, used verbatim. Must be a valid SMTP reply string, e.g. "550 5.1.1 no mail here".
"*" = …any of the aboveCatch-all, matched only after every literal alias has missed.

[tls]

Omit the block and mxhop does not advertise STARTTLS at all; senders that require encryption will refuse to deliver to you. Include it and STARTTLS appears in the EHLO response.

certificatepathrequired in blockPEM certificate chain. Use the full chain, not just the leaf — a missing intermediate works in some clients and fails in others, which is the worst kind of broken.
keypathrequired in blockPEM private key matching the certificate.

check opens both files as the user that will run mxhop, and tells you which user that was. A certificate that root can read and the service cannot is the single most common way this block fails, and it fails at startup rather than at parse time, so check looks for it deliberately.

Reload after renewal with SIGHUP (systemctl reload mxhop): the certificate is re-read, the new SHA-256 fingerprint is logged, new connections use it and open ones are untouched. Without that hook mxhop keeps serving the expired certificate.

[srs]

Rewrites the envelope sender of forwarded mail into a signed address at a domain of yours, so the destination's SPF check passes. Omit the block and forwarded mail keeps the original envelope sender, which the destination will check against the sender's SPF record, see your address, and fail. See Authentication.

domainstringrequired in blockThe domain rewritten addresses live at. Its SPF record must authorise this host, and its MX must point here — bounces come back to these addresses and mxhop has to be able to receive and verify them.
secret_filepathrequired in blockThe signing key. One key per line; the first is used for new addresses, the rest are still accepted, which is how rotation works.
max_age_daysintegerdefault 7max 365How long a rewritten address stays valid. A bounce arriving later than this is refused, because an address that never expires is a relay anyone who sees one can use forever.

The secret must be mode 0600. Anyone who can read it can forge an address this host will relay, which makes you an open relay in everything but name. check warns by name when the mode is looser, naming whether it is the group or everyone on the host.

[auth]

Omit the block and you get the defaults below. See Authentication for what each check does and why forwarding breaks it.

enabledbooleandefault trueWhether to check SPF, DKIM and DMARC at all. With false, nothing is checked and nothing is stamped: every forgery addressed to one of your aliases is forwarded over your own reputation. There is no good reason to set this in production.
enforce"off" | "dmarc"default "dmarc"

"off" checks and stamps an Authentication-Results header but refuses nothing. "dmarc" also refuses a message that fails DMARC when the From: domain publishes p=reject, with 550 5.7.1 at end of DATA.

Start at "off" for a few days and read the logs; switch to "dmarc" once you know what your mail looks like.

[arc]

Seals each forwarded message with what authentication found here, so a receiver that trusts this host can honour a DMARC pass that the forwarding itself broke. Omit the block and no seal is added. RSA keys only.

domainstringrequired in blockThe signing domain, which is where the public key is published.
selectorstringrequired in blockNames this key within the domain, so you can publish a second one before retiring the first. mxhop check prints the exact TXT record name built from these two.
key_filepathrequired in blockPEM RSA private key. An Ed25519 key is refused with a message saying so rather than failing obscurely later. Mode 0600, same reasoning as the SRS secret.
openssl genrsa -out /etc/mxhop/arc.key 2048
chmod 600 /etc/mxhop/arc.key
chown mxhop:mxhop /etc/mxhop/arc.key
mxhop check
/etc/mxhop/mxhop.toml: publish the ARC public key as a TXT record at arc1._domainkey.example.com

[queue]

Omit the block and you get the defaults, which are reasonable. Every bound below is enforced by check with an explanation, not silently clamped.

retry_minutes array of integersdefault [1, 5, 15, 60, 240]1–32 entrieseach 1–1440

Minutes to wait before each attempt. The last entry repeats for as long as the message stays queued, so the default means 1, 5, 15, 60, 240 and then every four hours.

The one-minute first retry exists for greylisting, which is a deliberate first-attempt rejection and the most common reason a legitimate message is deferred. An empty list is refused — that is a queue that accepts mail and never tries again. A 0 is refused: a destination that said "try later" and is tried in the same instant is a destination that rate-limits you next.

lifetime_hours integerdefault 48range 1–720 How long to keep trying before giving up, moving the message to frozen/ and sending a delivery report if the sender can be proved. 48 hours is the conventional value and what senders expect.
sweep_seconds integerdefault 60max 3600 How often the runner walks the queue looking for messages whose next attempt is due. It does not control retry timing — that is retry_minutes — only the granularity with which the schedule is noticed. There is little reason to change it.

[observe]

listensocket addressrequired in blockWhere to serve /metrics and /healthz. Nothing else is served; any other path is a 404.

Bind this to localhost. It is unauthenticated, and the metric output says which domains this host handles and how much mail they get. 127.0.0.1:9779 and a reverse proxy, or your monitoring agent on the same host.

Without this block there is no endpoint, so mxhop health has nothing to ask and says so. A container healthcheck needs it.

Full metric list and the health endpoint's output are on Observability.

When it is wrong

Every diagnostic carries the file path and, where the parser knows one, the line — so problems are clickable in an editor. check reports all of them, sorted by line, rather than stopping at the first.

mxhop check
/etc/mxhop/mxhop.toml:14: queue.retry_minutes must not contain 0: a destination that said "try later" and is tried again in the same instant is a destination that rate-limits us next /etc/mxhop/mxhop.toml:22: via = "mail.internal.example" has no address, so mail for legacy would have nowhere to go and nothing in DNS would say so /etc/mxhop/mxhop.toml: 2 problems found

Exit code is 1. A misspelled key is one of these, not a silently ignored line:

mxhop check
/etc/mxhop/mxhop.toml:9: unknown field `retries`, expected one of `retry_minutes`, `lifetime_hours`, `sweep_seconds`