<!DOCTYPE html PUBLIC "XSLT-compat"> <html lang="en-GB"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" type="text/css" href="../../../../common.css"> <meta name="author" content="The Exim Project. <http://www.exim.org/>"> <meta name="copyright" content="Copyright ©2010 The Exim Project. All rights reserved"> <meta name="description" content="Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet."> <meta name="keywords" content="exim,smtp,mta,email"> <meta name="robots" content="noodp,noydir,index,follow"> <meta name="viewport" content="width=device-width"> <title>17. The dnslookup router</title> <link rel="stylesheet" type="text/css" href="../../../../doc/chapter.css"> <link rel="canonical" href="http://www.exim.org/exim-html-current/doc/html/spec_html/ch17.html"> </head> <body> <h1 id="header"><a href="../../../..">Exim Internet Mailer</a></h1> <div id="outer"> <ul id="nav_flow" class="nav"> <li><a href="../../../../index.html">Home</a></li> <li><a href="../../../../mirrors.html">Download</a></li> <li><a href="../../../../docs.html">Documentation</a></li> <li><a href="../../../../maillist.html">Mailing Lists</a></li> <li><a href="http://wiki.exim.org/">Wiki</a></li> <li><a href="http://www.exim.org/bugzilla/">Bugs</a></li> <li><a href="../../../../credits.html">Credits</a></li> <li class="search"><form action="http://www.google.com/search" method="get"> <span class="search_field_container"><input type="search" name="q" placeholder="Search Docs" class="search_field"></span><input type="hidden" name="hl" value="en"><input type="hidden" name="ie" value="UTF-8"><input type="hidden" name="as_qdr" value="all"><input type="hidden" name="q" value="site:www.exim.org"><input type="hidden" name="q" value="inurl:exim-html-current"> </form></li> </ul> <div id="inner"><div id="content"> <a class="previous_page" href="ch16.html"><-previous</a><a class="next_page" href="ch18.html">next-></a><div id="chapter" class="chapter"> <h2 id="CHAPdnslookup" class="">Chapter 17 - The dnslookup router</h2> <p> The <span class="docbook_command">dnslookup</span> router looks up the hosts that handle mail for the recipient’s domain in the DNS. A transport must always be set for this router, unless <span class="docbook_option">verify_only</span> is set. </p> <p> If SRV support is configured (see <span class="docbook_option">check_srv</span> below), Exim first searches for SRV records. If none are found, or if SRV support is not configured, MX records are looked up. If no MX records exist, address records are sought. However, <span class="docbook_option">mx_domains</span> can be set to disable the direct use of address records. </p> <p> MX records of equal priority are sorted by Exim into a random order. Exim then looks for address records for the host names obtained from MX or SRV records. When a host has more than one IP address, they are sorted into a random order, except that IPv6 addresses are always sorted before IPv4 addresses. If all the IP addresses found are discarded by a setting of the <span class="docbook_option">ignore_target_hosts</span> generic option, the router declines. </p> <p> Unless they have the highest priority (lowest MX value), MX records that point to the local host, or to any host name that matches <span class="docbook_option">hosts_treat_as_local</span>, are discarded, together with any other MX records of equal or lower priority. </p> <p> If the host pointed to by the highest priority MX record, or looked up as an address record, is the local host, or matches <span class="docbook_option">hosts_treat_as_local</span>, what happens is controlled by the generic <span class="docbook_option">self</span> option. </p> <div class="section"> <h3 id="SECTprowitdnsloo" class="">1. Problems with DNS lookups</h3> <p> There have been problems with DNS servers when SRV records are looked up. Some mis-behaving servers return a DNS error or timeout when a non-existent SRV record is sought. Similar problems have in the past been reported for MX records. The global <span class="docbook_option">dns_again_means_nonexist</span> option can help with this problem, but it is heavy-handed because it is a global option. </p> <p> For this reason, there are two options, <span class="docbook_option">srv_fail_domains</span> and <span class="docbook_option">mx_fail_domains</span>, that control what happens when a DNS lookup in a <span class="docbook_command">dnslookup</span> router results in a DNS failure or a “try again” response. If an attempt to look up an SRV or MX record causes one of these results, and the domain matches the relevant list, Exim behaves as if the DNS had responded “no such record”. In the case of an SRV lookup, this means that the router proceeds to look for MX records; in the case of an MX lookup, it proceeds to look for A or AAAA records, unless the domain matches <span class="docbook_option">mx_domains</span>, in which case routing fails. </p> </div> <div class="section"> <h3 id="SECID118" class="">2. Private options for dnslookup</h3> <p> The private options for the <span class="docbook_command">dnslookup</span> router are as follows: </p> <p> </p> <table> <tr> <td><span class="docbook_option">check_secondary_mx</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set, the router declines unless the local host is found in (and removed from) the list of hosts obtained by MX lookup. This can be used to process domains for which the local host is a secondary mail exchanger differently to other domains. The way in which Exim decides whether a host is the local host is described in section <a href="ch13.html#SECTreclocipadd" title="13. Starting the daemon and the use of network interfaces">13.8</a>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">check_srv</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> The <span class="docbook_command">dnslookup</span> router supports the use of SRV records (see RFC 2782) in addition to MX and address records. The support is disabled by default. To enable SRV support, set the <span class="docbook_option">check_srv</span> option to the name of the service required. For example, </p> <div class="docbook_literallayout"><pre> check_srv = smtp </pre></div> <p> looks for SRV records that refer to the normal smtp service. The option is expanded, so the service name can vary from message to message or address to address. This might be helpful if SRV records are being used for a submission service. If the expansion is forced to fail, the <span class="docbook_option">check_srv</span> option is ignored, and the router proceeds to look for MX records in the normal way. </p> <p> When the expansion succeeds, the router searches first for SRV records for the given service (it assumes TCP protocol). A single SRV record with a host name that consists of just a single dot indicates “no such service for this domain”; if this is encountered, the router declines. If other kinds of SRV record are found, they are used to construct a host list for delivery according to the rules of RFC 2782. MX records are not sought in this case. </p> <p> When no SRV records are found, MX records (and address records) are sought in the traditional way. In other words, SRV records take precedence over MX records, just as MX records take precedence over address records. Note that this behaviour is not sanctioned by RFC 2782, though a previous draft RFC defined it. It is apparently believed that MX records are sufficient for email and that SRV records should not be used for this purpose. However, SRV records have an additional “weight” feature which some people might find useful when trying to split an SMTP load between hosts of different power. </p> <p> See section <a href="ch17.html#SECTprowitdnsloo" title="17. The dnslookup router">17.1</a> above for a discussion of Exim’s behaviour when there is a DNS lookup error. </p> <p> </p> <table> <tr> <td><span class="docbook_option">mx_domains</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">domain list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> A domain that matches <span class="docbook_option">mx_domains</span> is required to have either an MX or an SRV record in order to be recognized. (The name of this option could be improved.) For example, if all the mail hosts in <span class="docbook_emphasis">fict.example</span> are known to have MX records, except for those in <span class="docbook_emphasis">discworld.fict.example</span>, you could use this setting: </p> <div class="docbook_literallayout"><pre> mx_domains = ! *.discworld.fict.example : *.fict.example </pre></div> <p> This specifies that messages addressed to a domain that matches the list but has no MX record should be bounced immediately instead of being routed using the address record. </p> <p> </p> <table> <tr> <td><span class="docbook_option">mx_fail_domains</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">domain list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> If the DNS lookup for MX records for one of the domains in this list causes a DNS lookup error, Exim behaves as if no MX records were found. See section <a href="ch17.html#SECTprowitdnsloo" title="17. The dnslookup router">17.1</a> for more discussion. </p> <p> </p> <table> <tr> <td><span class="docbook_option">qualify_single</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> When this option is true, the resolver option RES_DEFNAMES is set for DNS lookups. Typically, but not standardly, this causes the resolver to qualify single-component names with the default domain. For example, on a machine called <span class="docbook_emphasis">dictionary.ref.example</span>, the domain <span class="docbook_emphasis">thesaurus</span> would be changed to <span class="docbook_emphasis">thesaurus.ref.example</span> inside the resolver. For details of what your resolver actually does, consult your man pages for <span class="docbook_emphasis">resolver</span> and <span class="docbook_emphasis">resolv.conf</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">rewrite_headers</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> If the domain name in the address that is being processed is not fully qualified, it may be expanded to its full form by a DNS lookup. For example, if an address is specified as <span class="docbook_emphasis">dormouse@teaparty</span>, the domain might be expanded to <span class="docbook_emphasis">teaparty.wonderland.fict.example</span>. Domain expansion can also occur as a result of setting the <span class="docbook_option">widen_domains</span> option. If <span class="docbook_option">rewrite_headers</span> is true, all occurrences of the abbreviated domain name in any <span class="docbook_emphasis">Bcc:</span>, <span class="docbook_emphasis">Cc:</span>, <span class="docbook_emphasis">From:</span>, <span class="docbook_emphasis">Reply-to:</span>, <span class="docbook_emphasis">Sender:</span>, and <span class="docbook_emphasis">To:</span> header lines of the message are rewritten with the full domain name. </p> <p> This option should be turned off only when it is known that no message is ever going to be sent outside an environment where the abbreviation makes sense. </p> <p> When an MX record is looked up in the DNS and matches a wildcard record, name servers normally return a record containing the name that has been looked up, making it impossible to detect whether a wildcard was present or not. However, some name servers have recently been seen to return the wildcard entry. If the name returned by a DNS lookup begins with an asterisk, it is not used for header rewriting. </p> <p> </p> <table> <tr> <td><span class="docbook_option">same_domain_copy_routing</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> Addresses with the same domain are normally routed by the <span class="docbook_command">dnslookup</span> router to the same list of hosts. However, this cannot be presumed, because the router options and preconditions may refer to the local part of the address. By default, therefore, Exim routes each address in a message independently. DNS servers run caches, so repeated DNS lookups are not normally expensive, and in any case, personal messages rarely have more than a few recipients. </p> <p> If you are running mailing lists with large numbers of subscribers at the same domain, and you are using a <span class="docbook_command">dnslookup</span> router which is independent of the local part, you can set <span class="docbook_option">same_domain_copy_routing</span> to bypass repeated DNS lookups for identical domains in one message. In this case, when <span class="docbook_command">dnslookup</span> routes an address to a remote transport, any other unrouted addresses in the message that have the same domain are automatically given the same routing without processing them independently, provided the following conditions are met: </p> <ul> <li> <p> No router that processed the address specified <span class="docbook_option">headers_add</span> or <span class="docbook_option">headers_remove</span>. </p> </li> <li> <p> The router did not change the address in any way, for example, by “widening” the domain. </p> </li> </ul> <p> </p> <table> <tr> <td><span class="docbook_option">search_parents</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> When this option is true, the resolver option RES_DNSRCH is set for DNS lookups. This is different from the <span class="docbook_option">qualify_single</span> option in that it applies to domains containing dots. Typically, but not standardly, it causes the resolver to search for the name in the current domain and in parent domains. For example, on a machine in the <span class="docbook_emphasis">fict.example</span> domain, if looking up <span class="docbook_emphasis">teaparty.wonderland</span> failed, the resolver would try <span class="docbook_emphasis">teaparty.wonderland.fict.example</span>. For details of what your resolver actually does, consult your man pages for <span class="docbook_emphasis">resolver</span> and <span class="docbook_emphasis">resolv.conf</span>. </p> <p> Setting this option true can cause problems in domains that have a wildcard MX record, because any domain that does not have its own MX record matches the local wildcard. </p> <p> </p> <table> <tr> <td><span class="docbook_option">srv_fail_domains</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">domain list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> If the DNS lookup for SRV records for one of the domains in this list causes a DNS lookup error, Exim behaves as if no SRV records were found. See section <a href="ch17.html#SECTprowitdnsloo" title="17. The dnslookup router">17.1</a> for more discussion. </p> <p> </p> <table> <tr> <td><span class="docbook_option">widen_domains</span></td> <td>Use: <span class="docbook_emphasis">dnslookup</span> </td> <td>Type: <span class="docbook_emphasis">string list</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> If a DNS lookup fails and this option is set, each of its strings in turn is added onto the end of the domain, and the lookup is tried again. For example, if </p> <div class="docbook_literallayout"><pre> widen_domains = fict.example:ref.example </pre></div> <p> is set and a lookup of <span class="docbook_emphasis">klingon.dictionary</span> fails, <span class="docbook_emphasis">klingon.dictionary.fict.example</span> is looked up, and if this fails, <span class="docbook_emphasis">klingon.dictionary.ref.example</span> is tried. Note that the <span class="docbook_option">qualify_single</span> and <span class="docbook_option">search_parents</span> options can cause some widening to be undertaken inside the DNS resolver. <span class="docbook_option">widen_domains</span> is not applied to sender addresses when verifying, unless <span class="docbook_option">rewrite_headers</span> is false (not the default). </p> </div> <div class="section"> <h3 id="SECID119" class="">3. Effect of qualify_single and search_parents</h3> <p> When a domain from an envelope recipient is changed by the resolver as a result of the <span class="docbook_option">qualify_single</span> or <span class="docbook_option">search_parents</span> options, Exim rewrites the corresponding address in the message’s header lines unless <span class="docbook_option">rewrite_headers</span> is set false. Exim then re-routes the address, using the full domain. </p> <p> These two options affect only the DNS lookup that takes place inside the router for the domain of the address that is being routed. They do not affect lookups such as that implied by </p> <div class="docbook_literallayout"><pre> domains = @mx_any </pre></div> <p> that may happen while processing a router precondition before the router is entered. No widening ever takes place for these lookups. </p> </div> </div> <a class="previous_page" href="ch16.html"><-previous</a><a class="next_page" href="ch18.html">next-></a> </div></div> <iframe id="branding" name="branding" src="../../../../branding/branding.html" height="0" frameborder="no" scrolling="no"></iframe><div id="footer">Website design by <a href="https://secure.grepular.com/">Mike Cardwell</a>, of <a href="http://cardwellit.com/">Cardwell IT Ltd.</a> </div> <div class="left_bar"></div> <div class="right_bar"></div> <div id="toc"> <ul class="hidden"></ul> <img src="../../../../doc/contents.png" width="16" height="155"> </div> </div> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script><script type="text/javascript" src="../../../../common.js"></script><script type="text/javascript" src="../../../../doc/chapter.js"></script> </body> </html>
