<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css"> div.added { background-color: #ffff99; } div.deleted { text-decoration: line-through; background-color: #FF7F7F; } div.changed { background-color: #99ff99; } div.off { } span.added { background-color: #ffff99; } span.deleted { text-decoration: line-through; background-color: #FF7F7F; } span.changed { background-color: #99ff99; } span.off { } pre.literallayout { background-color: #E8E8D0; padding-left: 0.5cm; padding-top: 5px; padding-bottom: 5px; } div[class=changed] pre.literallayout { background-color: #99ff99; padding-left: 0.5cm; padding-top: 5px; padding-bottom: 5px; } div.literallayout { background-color: #E8E8D0; padding-left: 0.5cm; padding-top: 5px; padding-bottom: 5px; } div[class=changed] div.literallayout { background-color: #99ff99; padding-left: 0.5cm; padding-top: 5px; padding-bottom: 5px; } </style><title>21. The queryprogram router</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /><link rel="start" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="up" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="prev" href="ch20.html" title="20. The manualroute router" /><link rel="next" href="ch22.html" title="22. The redirect router" /></head><body><div class="navheader"> <table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch20.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch22.html">Next</a></td></tr></table></div> <div class="chapter" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title"><a href="index.html#toc0203" id="CHAPdriverlast">21. The queryprogram router</a></h2></div></div> </div> <p> <a id="IIDquerou1" class="indexterm"></a> <a id="IIDquerou2" class="indexterm"></a> <a id="id572571" class="indexterm"></a> The <span><strong class="command">queryprogram</strong></span> router routes an address by running an external command and acting on its output. This is an expensive way to route, and is intended mainly for use in lightly-loaded systems, or for performing experiments. However, if it is possible to use the precondition options (<span><strong class="option">domains</strong></span>, <span><strong class="option">local_parts</strong></span>, etc) to skip this router for most addresses, it could sensibly be used in special cases, even on a busy host. There are the following private options: <a id="id572606" class="indexterm"></a> </p> <p> <a id="id572628" class="indexterm"></a> </p> <div class="informaltable"> <table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">command</strong></span></td><td align="center">Use: <span class="emphasis"><em>queryprogram</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div> <p> This option must be set. It specifies the command that is to be run. The command is split up into a command name and arguments, and then each is expanded separately (exactly as for a <span><strong class="command">pipe</strong></span> transport, described in chapter <a href="ch29.html" title="29. The pipe transport">29</a>). </p> <p> <a id="id572732" class="indexterm"></a> </p> <div class="informaltable"> <table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">command_group</strong></span></td><td align="center">Use: <span class="emphasis"><em>queryprogram</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div> <p> <a id="id572814" class="indexterm"></a> This option specifies a gid to be set when running the command while routing an address for deliver. It must be set if <span><strong class="option">command_user</strong></span> specifies a numerical uid. If it begins with a digit, it is interpreted as the numerical value of the gid. Otherwise it is looked up using <em class="function">getgrnam()</em>. </p> <p> <a id="id572851" class="indexterm"></a> </p> <div class="informaltable"> <table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">command_user</strong></span></td><td align="center">Use: <span class="emphasis"><em>queryprogram</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div> <p> <a id="id572933" class="indexterm"></a> This option must be set. It specifies the uid which is set when running the command while routing an address for delivery. If the value begins with a digit, it is interpreted as the numerical value of the uid. Otherwise, it is looked up using <em class="function">getpwnam()</em> to obtain a value for the uid and, if <span><strong class="option">command_group</strong></span> is not set, a value for the gid also. </p> <p> <span class="bold"><strong>Warning:</strong></span> Changing uid and gid is possible only when Exim is running as root, which it does during a normal delivery in a conventional configuration. However, when an address is being verified during message reception, Exim is usually running as the Exim user, not as root. If the <span><strong class="command">queryprogram</strong></span> router is called from a non-root process, Exim cannot change uid or gid before running the command. In this circumstance the command runs under the current uid and gid. </p> <p> <a id="id572992" class="indexterm"></a> </p> <div class="informaltable"> <table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">current_directory</strong></span></td><td align="center">Use: <span class="emphasis"><em>queryprogram</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>/</em></span></td></tr></tbody></table></div> <p> This option specifies an absolute path which is made the current directory before running the command. </p> <p> <a id="id573079" class="indexterm"></a> </p> <div class="informaltable"> <table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">timeout</strong></span></td><td align="center">Use: <span class="emphasis"><em>queryprogram</em></span></td><td align="center">Type: <span class="emphasis"><em>time</em></span></td><td align="right">Default: <span class="emphasis"><em>1h</em></span></td></tr></tbody></table></div> <p> If the command does not complete within the timeout period, its process group is killed and the message is frozen. A value of zero time specifies no timeout. </p> <p> The standard output of the command is connected to a pipe, which is read when the command terminates. It should consist of a single line of output, containing up to five fields, separated by white space. The maximum length of the line is 1023 characters. Longer lines are silently truncated. The first field is one of the following words (case-insensitive): </p> <div class="itemizedlist"> <ul type="disc"><li><p> <span class="emphasis"><em>Accept</em></span>: routing succeeded; the remaining fields specify what to do (see below). </p> </li><li><p> <span class="emphasis"><em>Decline</em></span>: the router declines; pass the address to the next router, unless <span><strong class="option">no_more</strong></span> is set. </p> </li><li><p> <span class="emphasis"><em>Fail</em></span>: routing failed; do not pass the address to any more routers. Any subsequent text on the line is an error message. If the router is run as part of address verification during an incoming SMTP message, the message is included in the SMTP response. </p> </li><li><p> <span class="emphasis"><em>Defer</em></span>: routing could not be completed at this time; try again later. Any subsequent text on the line is an error message which is logged. It is not included in any SMTP response. </p> </li><li><p> <span class="emphasis"><em>Freeze</em></span>: the same as <span class="emphasis"><em>defer</em></span>, except that the message is frozen. </p> </li><li><p> <span class="emphasis"><em>Pass</em></span>: pass the address to the next router (or the router specified by <span><strong class="option">pass_router</strong></span>), overriding <span><strong class="option">no_more</strong></span>. </p> </li><li><p> <span class="emphasis"><em>Redirect</em></span>: the message is redirected. The remainder of the line is a list of new addresses, which are routed independently, starting with the first router, or the router specified by <span><strong class="option">redirect_router</strong></span>, if set. </p> </li></ul></div> <p> When the first word is <span class="emphasis"><em>accept</em></span>, the remainder of the line consists of a number of keyed data values, as follows (split into two lines here, to fit on the page): </p> <pre class="literallayout">ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts> LOOKUP=byname|bydns DATA=<text> </pre><p> The data items can be given in any order, and all are optional. If no transport is included, the transport specified by the generic <span><strong class="option">transport</strong></span> option is used. The list of hosts and the lookup type are needed only if the transport is an <span><strong class="command">smtp</strong></span> transport that does not itself supply a list of hosts. </p> <p> The format of the list of hosts is the same as for the <span><strong class="command">manualroute</strong></span> router. As well as host names and IP addresses with optional port numbers, as described in section <a href="ch20.html#SECTformatonehostitem" title="20.5 Format of one host item">20.5</a>, it may contain names followed by <code class="literal">/MX</code> to specify sublists of hosts that are obtained by looking up MX records (see section <a href="ch20.html#SECThostshowused" title="20.6 How the list of hosts is used">20.6</a>). </p> <p> If the lookup type is not specified, Exim behaves as follows when trying to find an IP address for each host: First, a DNS lookup is done. If this yields anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim goes on to try a call to <em class="function">getipnodebyname()</em> or <em class="function">gethostbyname()</em>, and the result of the lookup is the result of that call. </p> <p> <a id="id573370" class="indexterm"></a> If the DATA field is set, its value is placed in the <em class="varname">$address_data</em> variable. For example, this return line </p> <pre class="literallayout">accept hosts=x1.y.example:x2.y.example data="rule1" </pre><p> routes the address to the default transport, passing a list of two hosts. When the transport runs, the string “<span class="quote">rule1</span>” is in <em class="varname">$address_data</em>. <a id="id573408" class="indexterm"></a> <a id="id573421" class="indexterm"></a> </p> </div> <div class="navfooter"> <table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch20.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch22.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div> </body></html>