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
- Defaults are stated, always. Where a key is optional this documentation gives the value you get by leaving it out. Where a default is a bad idea in public, it says so.
example.comis your domain,mx.example.comyour host,203.0.113.10its address,you@gmail.comthe mailbox you actually read. All reserved for documentation; none of them resolve.- Output shown is real output, with names replaced. Where something has not been verified in production it is marked.
- Durations in the file are numbers with the unit in the key.
retry_minutes,lifetime_hours,sweep_seconds,max_age_days. There is no"30s"string form anywhere.
Something missing or wrong here is a bug in the documentation. The repository takes issues for both kinds.