mxhop

Reference · DNS

Six records, in the order to publish them.

More mxhop installations are broken by DNS than by configuration, and the record that breaks them most often is not in your zone at all. Publish these in order; each step has a command that proves it before you depend on it.

Publish in this order

  1. A — the host exists

    mx.example.com.   300   IN   A   203.0.113.10
    
    # prove it
    dig +short A mx.example.com
    203.0.113.10
  2. PTR — reverse DNS, and it is not in your zone

    Set this at whoever owns the IP: your VPS provider's control panel, not your DNS host. It must resolve back to the exact name you use as hostname.

    dig +short -x 203.0.113.10
    mx.example.com.

    Get this wrong and nothing else matters. Several large receivers refuse mail outright from an address whose PTR is missing, generic, or does not resolve back to the EHLO name — whatever your SPF and DKIM say. Check that your provider will set one before you rent the machine; many cheap hosts will not.

  3. SPF — this host may send for the domain

    Needed because SRS rewrites the envelope sender into your domain, so the destination checks your SPF record.

    example.com.   300   IN   TXT   "v=spf1 a:mx.example.com -all"
    
    dig +short TXT example.com
    "v=spf1 a:mx.example.com -all"

    One SPF record per domain — two is an error that makes both unreliable. If the domain already sends through something else, add this host to the existing record rather than publishing a second. Start with ~all (softfail) and tighten to -all once you are sure nothing else sends.

  4. MX — mail for the domain comes here

    Last of the four, because this is the one that moves live mail. Until now nothing has changed for anybody.

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

    Keep the TTL low (300) while you are setting up, so a mistake is five minutes rather than a day. Raise it once the mail is flowing.

    Before you switch: run mxhop check, and test the host on a high port with a real message. An MX pointing at a host that is not ready defers everyone's mail.

  5. DMARC — tell receivers what to do, and get reports

    _dmarc.example.com.   300   IN   TXT   "v=DMARC1; p=none; rua=mailto:dmarc@example.com; pct=100"

    Start at p=none. It changes nothing about how mail is handled and starts the reports arriving. Read a fortnight of them, find the sender you forgot about, then move to p=quarantine and later p=reject. Publishing p=reject on a domain whose mail you have not watched is how people discover a forgotten sender by having its mail silently refused.

  6. ARC key — only if you configured [arc]

    mxhop check prints the exact record name and the key to publish, so there is nothing to work out:

    mxhop check
    /etc/mxhop/mxhop.toml: publish the ARC public key as a TXT record at arc1._domainkey.example.com
    
    arc1._domainkey.example.com.   300   IN   TXT   "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."

    A 2048-bit key fits in one TXT string in most DNS providers. If yours rejects the length, it needs splitting into quoted chunks — the provider concatenates them.

All of it at once

NameTypeValueWhere
mx.example.comA203.0.113.10your DNS
example.comMX10 mx.example.com.your DNS
example.comTXTv=spf1 a:mx.example.com -allyour DNS
_dmarc.example.comTXTv=DMARC1; p=none; rua=mailto:…your DNS
arc1._domainkey.example.comTXTv=DKIM1; k=rsa; p=…your DNS, with [arc]
203.0.113.10PTRmx.example.com.your IP provider

Several domains on one host

Every domain gets its own MX, SPF and DMARC, all pointing at the same host. Only one A and one PTR exist, because there is only one machine.

# each domain, separately
example.com.         MX    10 mx.example.com.
example.com.         TXT   "v=spf1 a:mx.example.com -all"
_dmarc.example.com.  TXT   "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

example.net.         MX    10 mx.example.com.
example.net.         TXT   "v=spf1 a:mx.example.com -all"
_dmarc.example.net.  TXT   "v=DMARC1; p=none; rua=mailto:dmarc@example.net"

# shared, once
mx.example.com.      A     203.0.113.10
203.0.113.10         PTR   mx.example.com.

The hostname in the config stays mx.example.com for all of them. It names the machine, not the domains it serves.

Prove it from outside

From a machine that is not the mail server, so you are testing public DNS rather than the host's own resolver:

# the four that must agree
dig +short MX example.com
dig +short A mx.example.com
dig +short -x 203.0.113.10
dig +short TXT example.com

# the round trip receivers check: the PTR name must resolve back to the IP
dig +short A "$(dig +short -x 203.0.113.10 | sed 's/\.$//')"
203.0.113.10

# does it actually take mail, with TLS
openssl s_client -starttls smtp -connect mx.example.com:25 -quiet <<'EOF'
EHLO probe.example
QUIT
EOF
220 mx.example.com mxhop ready

The round-trip check in the middle is the one worth automating. A PTR that resolves to a name whose A record points elsewhere fails forward-confirmed reverse DNS, and the symptom is intermittent refusals from some receivers — much harder to diagnose than an outright failure.