mxhop

Guides · troubleshooting

Symptom, cause, fix.

Ordered by how often each one actually happens. The first two cover most of it, and both are DNS rather than mxhop.

Start with these three commands

# 1. does mxhop agree with what you think you configured
mxhop check

# 2. is it well right now
mxhop health

# 3. what is waiting, and why
jq -r '[.id, .attempts, .last_reply] | @tsv' \
  /var/lib/mxhop/spool/queue/*.json 2>/dev/null

That third one answers most "mail is not arriving" questions outright. last_reply is the destination's own sentence about why it would not take the message.

Mail arrives, but lands in spam

Check the PTR record first — it is the usual answer

From a machine that is not the server:

dig +short -x 203.0.113.10
mx.example.com.
# and the round trip receivers actually check
dig +short A mx.example.com
203.0.113.10

Both must agree, and the name must match your hostname exactly. Missing, generic (vps-1234.provider.net), or pointing somewhere else and several large receivers distrust you whatever else is right. Fix it at your IP provider's panel, not in your DNS zone.

Read the real headers rather than guessing

In Gmail: open the message, "Show original". That page tells you precisely which check failed:

spf=pass  dkim=pass  dmarc=pass  arc=pass   <- all well
spf=fail  <- SRS missing, or SPF does not authorise this host
dkim=fail <- something altered the bytes before it reached you
dmarc=fail<- neither SPF nor DKIM aligned with the From: domain

Each one points at a different fix, and guessing between them wastes a day. See Authentication.

No [srs] block

mxhop check says so in plain words: no SRS — forwarded mail keeps the original envelope sender and will fail SPF. Add the block, and make sure the SRS domain's SPF authorises this host and its MX points here.

A new IP with no sending history

Nothing is wrong. A fresh address has no reputation, and large receivers are cautious with low-volume senders they have not seen. Mark a few as "not spam" in the destination mailbox and it settles over a week or two. Check the IP is not on a blocklist from a previous tenant — that one does not settle on its own.

Nothing arrives at all

Is anything listening, from outside?

openssl s_client -starttls smtp -connect mx.example.com:25 -quiet <<'EOF'
EHLO probe.example
QUIT
EOF
220 mx.example.com mxhop ready

No greeting means it is not reachable, and almost always a firewall or a provider blocking port 25 outbound and inbound on cheap plans. Many providers block 25 by default and will unblock on request; some will not at all.

Does the MX record point here?

dig +short MX example.com
10 mx.example.com.

If you changed it recently, the old value may still be cached for its TTL. A trailing dot matters in zone files; some providers add it for you and some do not.

Is the socket unit stopped?

With socket activation, systemctl status mxhop can look fine while nothing is listening, because the socket unit is the thing that binds the port:

systemctl status mxhop.socket
systemctl enable --now mxhop.socket

The reverse also catches people: stopping only mxhop.service looks like it worked, and systemd starts it again the moment a sender connects.

Is the alias actually there?

mxhop check prints the alias count and the domains. A count lower than you expect means a block is misspelled — [domains."example.com".aliases], with the quotes, is easy to get subtly wrong and produces no error because an empty domain is legal.

Senders say my server refused their mail

550 5.7.1 … fails DMARC and that domain asks for failures to be rejected

Working as intended. That message forged a From: domain which publishes p=reject, and forwarding it would have put the forgery on your reputation. mxhop_auth_refusals_total counts these, and on a public MX it will not be zero.

If a legitimate sender hits this, their own DKIM is broken before it reaches you — their problem to fix, and refusing is the honest answer. To confirm rather than assume, set enforce = "off" briefly and read what the verdicts say.

550 5.7.1 on a domain you thought was configured

mxhop refuses a domain it was not configured for — it is not an open relay. mxhop check lists the domains it will accept. A typo in the domain name, or a config file that is not the one being read: check --config and MXHOP_CONFIG, because the service and your shell can easily disagree.

451 4.7.1 could not finish checking …

An authentication stage ran out of its time budget. Almost always slow DNS. The sender will retry and it usually succeeds; if it is persistent, the host's resolver is the thing to look at — a local caching resolver fixes it. Never treated as a pass, which is why it is a 451 and not a quiet acceptance.

554 5.4.6 this message has already passed through this host

A mail loop. Usually an alias forwarding to an address that resolves back to one of your own domains, or a destination mailbox with a forwarding rule pointing back at you. mxhop check catches loops inside the alias table; this reply catches the ones that go out through someone else and come back.

The queue keeps growing

Read last_reply before anything else

jq -r '.last_reply' /var/lib/mxhop/spool/queue/*.json | sort | uniq -c | sort -rn
  47 451 4.7.0 Too many connections from this IP
   3 421 4.3.2 Try again later

That is the destination rate-limiting you, and it resolves itself. A single destination dominating the list means the problem is with that one destination, not with mxhop.

Is the runner running?

mxhop_queue_sweeps_total should climb every sweep_seconds. Flat means the runner has stopped and nothing is being retried — restart, and check the logs for what it said on the way down.

Is DNS answering?

mxhop health has a resolver line. Without DNS nothing can be delivered, so everything defers and the queue grows at exactly the rate mail arrives.

Is the disk full?

spool: no in mxhop health. While that is true mxhop refuses incoming mail rather than accepting what it cannot store — correct, but it means senders are being turned away. df -h on the spool filesystem, and remember frozen/ is never pruned automatically.

TLS stopped working

The certificate renewed and nothing told mxhop

The commonest TLS failure by a wide margin. mxhop reads the certificate at startup and on SIGHUP; a renewal that writes new files changes nothing until one of those happens. Senders that require TLS start deferring — quietly, because a deferral is not an error anybody emails you about.

# the fix, once
certbot renew --deploy-hook "systemctl reload mxhop"

# confirm it took: the fingerprint is logged on reload
systemctl reload mxhop && journalctl -u mxhop -n 3 -o cat
TLS certificate reloaded; new connections use it certificate=/etc/letsencrypt/live/mx.example.com/fullchain.pem sha256=4f:2a:...

The service cannot read the key

mxhop check opens both files as the user that will run and names that user. A certbot directory readable only by root is the classic case — certbot defaults to 0700 on live/ and archive/. Give the mxhop group read access on both directories; copying the files instead means you have to remember to copy them again every renewal.

An incomplete chain

Use fullchain.pem, not cert.pem. A missing intermediate works in some clients and fails in others, so the symptom is that some senders defer — far harder to spot than everything breaking.

openssl s_client -starttls smtp -connect mx.example.com:25 2>&1 | grep -i verify
Verify return code: 0 (ok)

It will not start

MessageFix
cannot listen: Address already in useSomething else holds port 25 — often Postfix or Exim preinstalled by the distribution. ss -tlnp 'sport = :25', then disable it.
cannot listen: Permission deniedPort 25 needs privilege. Use the socket-activated unit, or CAP_NET_BIND_SERVICE, or a high port behind a port mapping.
cannot open the spoolThe directory does not exist or is not writable by the running user. install -d -o mxhop -g mxhop -m 0750 /var/lib/mxhop/spool.
unknown field `…`, expected one of …A misspelled key. The message lists the keys that block accepts; see the reference.
via = "…" has no addressA via host that does not resolve. Fix the name or the internal DNS. check refuses to pass this because the mail would have nowhere to go.
the unit fails at ExecStartPremxhop check failed, so systemd would not start the service. This is deliberate — a bad config means the previously running process keeps serving. Run mxhop check by hand to see why.

Still stuck

Collect these four things before opening an issue — they answer most of what anyone would ask you:

mxhop --version
mxhop check
mxhop health
journalctl -u mxhop -n 50 -o cat

Log output is safe to share — no message content, no subjects, no headers beyond the Message-ID. Your config file is not: it names the mailboxes you forward to and the paths to your SRS and ARC keys. Redact the addresses, and never paste the key files themselves.