Domain Name System configuration

vSMTP can handle complex DNS situations. A default configuration is applied on the root domain and virtual domains inherit from it. Specific values can be updated on root domain or on a per virtual domain basis.

vSMTP relies on Benjamin Fry’s Trust-DNS crate to handle DNS queries.

DNS parameters are stored in the [server.dns] and [server.virtual.dns] tables and sub-tables. Please refer to vSMTP reference guide and Trust-DNS repository for detailed information.

DNS resolver

The default behavior of the upstream resolver is defined by the operating system /etc/resolv.conf file. Alternative configurations such as Google or CloudFlare Public DNS may be applied using the type field in the server.dns table.

type = "system" | "google" | "cloudflare"

Please see Google and CloudFlare privacy statement for important information about what they track.

Locating the target host

Section 5 of RFC5321 covers the sequence to identify a server that accepts email for a domain. The SMTP client first looks up a DNS MX RR, and if is not found, falls back to a DNS A or AAAA request. If a CNAME record is found, the resulting name is processed as if it were the initial name.

This mechanism suffers from two major drawbacks.

  • A DNS overload because of an email service semantic.
  • If there are no SMTP listeners at the A/AAAA addresses, message delivery will be attempted repeatedly many times before the sending Mail Transfer Agent (MTA) gives up, implying:
    • a delay notification to the sender in the case of misdirected mail,
    • a waste of IT resources at the sender.

The “Null MX” protocol solves these issues.

Resolver options

DNS Options can be set in the TOML [server.dns.options] table.

ParametervalueDescriptionDefault value
timeoutintegerSpecify the timeout for a request.5 seconds.
attemptsintegerusize Number of retries after lookup failure before giving up.2 attempts.
rotatetrue/falseRotate through the resource records in the response.No rotation.
validatetrue/falseUse DNSSec to validate the request.False.
ip_strategyenum1The ip_strategy for the Resolver to use when lookup Ipv4 or Ipv6 addresses.IPv4 then IPv6.
cache_sizeintegerCache size is in number of records.32 records.
num_concurrent_reqsintegerNumber of concurrent requests per query.2 concurrent requests.
preserve_intermediatestrue/falsePreserve all intermediate records in the lookup response, such as CNAME records.True.

Ipv4Only, Ipv6Only, Ipv4AndIpv6, Ipv6thenIpv4, Ipv4thenIpv6

A Resolver configuration example :

type = "cloudflare"

timeout = "5s"
cache_size = 500
ip_strategy = "Ipv6thenIpv4"
validate = true

Advanced parameters are available. Please check vSMTP reference guide and Trust-DNS repository.

DNS and SMTP return codes

In case of a DNS failure, the RFC 3463, Enhanced Mail System Status Codes, registers two specific SMTP return codes.

TextDirectory server failure.
Basic status code451, 550
DescriptionThe network system was unable to forward the message, because a directory server was unavailable. This is useful only as a persistent transient error. The inability to connect to an Internet DNS server is one example of the directory server failure error.
TextUnable to route.
Basic status codeNot given.
DescriptionThe mail system was unable to determine the next hop for the message because the necessary routing information was unavailable from the directory server. This is useful for both permanent and persistent transient errors. A DNS lookup returning only an SOA (Start of Administration) record for a domain name is one example of the unable to route error.

Reverse DNS queries

Most email authentication mechanisms rely on reverse DNS queries. The configuration of these protocol-related queries is registered in their corresponding TOML tables.

However, for specific DNS reverse queries can also be directly using the vSL reverse lookup function.

RFC 7372 registers status codes to be returned if a message is being rejected or deferred specifically because of email authentication failures.

TextReverse DNS validation failed.
Basic status code550
DescriptionAn SMTP client’s IP address failed a reverse DNS validation check, contrary to local policy requirements.

Protocol-specific return codes are described in the corresponding chapters.