mxhop

Documentation · v0.3.0

Everything mxhop does, and what each of it costs you.

Ten pages. The configuration reference is exhaustive — every key, its type, its default and its limit. The rest explains the behaviour those keys buy, including the parts that will surprise you.

Start here if you have five minutes

A working forwarder, end to end. Everything else on these pages makes this safer or more observable; none of it is needed to see mail move.

# 1. install
curl -fsSLO https://mxhop.tooling.ninja/install.sh && less install.sh && sh install.sh

# 2. the smallest config that works
mkdir -p /etc/mxhop /var/lib/mxhop/spool
cat > /etc/mxhop/mxhop.toml <<'TOML'
hostname = "mx.example.com"
listen = "0.0.0.0:25"
spool_dir = "/var/lib/mxhop/spool"

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

# 3. prove it before DNS points at you
mxhop check
/etc/mxhop/mxhop.toml: ok — mx.example.com on 0.0.0.0:25, 1 alias for example.com, no SRS — forwarded mail keeps the original envelope sender and will fail SPF, no TLS, no SPF/DKIM/DMARC check at all, a deferred message retried after 1, 5, 15, 60, 240 minutes and then every 4 hours, given up on after 48 hours, no ARC seal, no metrics or health endpoint

Read that output rather than skimming it. Every clause is mxhop telling you what it will not be doing. The minimal config forwards mail and fails SPF at the destination, so most of it lands in spam. Authentication and DNS are what turn that into mail that arrives.

The pages

Reference Configuration Every key in the file: type, default, accepted range, and what check says when it is wrong. Unknown keys are errors, so this list is complete by construction. Reference Routing and aliases The four target forms, the order addresses resolve in, catch-alls, loop detection, expansion limits, and how recipients are grouped into deliveries. Concepts Authentication SPF, DKIM, DMARC with their per-stage time budgets; the two enforcement modes; SRS envelope rewriting; ARC sealing. Why forwarding breaks each one. Concepts Queue and spool The on-disk format field by field, the retry schedule and its limits, frozen/, delivery reports and the rule that stops them becoming backscatter. Reference SMTP surface Commands accepted, extensions advertised, every timeout and limit, and a table of every reply code mxhop can give with what each one means. Reference DNS Six record types, in the order to publish them, with the command to verify each. Includes the one that is not in your zone and is the most common reason mail is refused. Reference Observability All eighteen metrics with their types, the health endpoint's output, every field a log line can carry — and the list of what never appears in one. Guides Scenarios Seven worked setups with complete configs: one personal domain, many domains, shared team aliases, moving off a hosted forwarder, an internal host, a staging MX, a second backup MX. Guides Troubleshooting Symptom, cause, fix. Mail in spam, mail refused, nothing arriving, a queue that grows, certificates that stop working, health that says no. Reference CLI and signals Three subcommands, four flags, three environment variables, three signals and two exit codes. On its own page because it is the operator interface.

Conventions used here

Something missing or wrong here is a bug in the documentation. The repository takes issues for both kinds.