<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on September, 10 2009 by texi2html 1.78 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>Specification of the Exim Mail Transfer Agent: 21. The queryprogram router</title>
<meta name="description" content="Specification of the Exim Mail Transfer Agent: 21. The queryprogram router">
<meta name="keywords" content="Specification of the Exim Mail Transfer Agent: 21. The queryprogram router">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.78">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="The-queryprogram-router"></a>
<a name="SEC203"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="spec_20.html#SEC202" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="spec_22.html#SEC204" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec_20.html#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_22.html#SEC204" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h1 class="chapter"> 21. The queryprogram router </h1>
<p>The <code>queryprogram</code> 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 (<code>domains</code>,
<code>local_parts</code>, 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 name="IDX1841"></a>
</p>
<a name="IDX1842"></a>
<table>
<tr><td>
<p><code>command</code></p></td><td><p> Use: <em>queryprogram</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<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 <code>pipe</code> transport, described in chapter
<a href="spec_29.html#SEC235">The pipe transport</a>).
</p>
<a name="IDX1843"></a>
<table>
<tr><td>
<p><code>command_group</code></p></td><td><p> Use: <em>queryprogram</em></p></td><td><p> Type: <em>string</em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX1844"></a>
<p>This option specifies a gid to be set when running the command while routing an
address for deliver. It must be set if <code>command_user</code> 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 <code>getgrnam()</code>.
</p>
<a name="IDX1845"></a>
<table>
<tr><td>
<p><code>command_user</code></p></td><td><p> Use: <em>queryprogram</em></p></td><td><p> Type: <em>string</em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX1846"></a>
<p>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 <code>getpwnam()</code> to obtain a value for the uid and, if <code>command_group</code> is
not set, a value for the gid also.
</p>
<p><strong>Warning:</strong> 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 <code>queryprogram</code> 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>
<a name="IDX1847"></a>
<table>
<tr><td>
<p><code>current_directory</code></p></td><td><p> Use: <em>queryprogram</em></p></td><td><p> Type: <em>string</em></p></td><td><p> Default: <em>/</em>
</p></td></tr>
</table>
<p>This option specifies an absolute path which is made the current directory
before running the command.
</p>
<a name="IDX1848"></a>
<table>
<tr><td>
<p><code>timeout</code></p></td><td><p> Use: <em>queryprogram</em></p></td><td><p> Type: <em>time</em></p></td><td><p> Default: <em>1h</em>
</p></td></tr>
</table>
<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>
<ul class="toc">
<li>
<em>Accept</em>: routing succeeded; the remaining fields specify what to do (see
below).
</li><li>
<em>Decline</em>: the router declines; pass the address to the next router, unless
<code>no_more</code> is set.
</li><li>
<em>Fail</em>: 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.
</li><li>
<em>Defer</em>: 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.
</li><li>
<em>Freeze</em>: the same as <em>defer</em>, except that the message is frozen.
</li><li>
<em>Pass</em>: pass the address to the next router (or the router specified by
<code>pass_router</code>), overriding <code>no_more</code>.
</li><li>
<em>Redirect</em>: 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 <code>redirect_router</code>, if set.
</li></ul>
<p>When the first word is <em>accept</em>, 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>
<table><tr><td> </td><td><pre class="example">ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts>
LOOKUP=byname|bydns DATA=<text>
</pre></td></tr></table>
<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 <code>transport</code> option is
used. The list of hosts and the lookup type are needed only if the transport is
an <code>smtp</code> 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 <code>manualroute</code> router.
As well as host names and IP addresses with optional port numbers, as described
in section <a href="spec_20.html#SEC199">Format of one host item</a>, it may contain names followed by
‘<samp>/MX</samp>’ to specify sublists of hosts that are obtained by looking up MX records
(see section <a href="spec_20.html#SEC200">How the list of hosts is used</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 <code>getipnodebyname()</code> or <code>gethostbyname()</code>, and the
result of the lookup is the result of that call.
</p>
<a name="IDX1849"></a>
<p>If the DATA field is set, its value is placed in the <code>$address_data</code>
variable. For example, this return line
</p>
<table><tr><td> </td><td><pre class="example">accept hosts=x1.y.example:x2.y.example data="rule1"
</pre></td></tr></table>
<p>routes the address to the default transport, passing a list of two hosts. When
the transport runs, the string "rule1" is in <code>$address_data</code>.
<a name="IDX1850"></a>
<a name="IDX1851"></a>
</p>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="spec_20.html#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec_22.html#SEC204" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated on <i>September, 10 2009</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.78</i></a>.
</font>
<br>
</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a4080654d049ad31b216b761b9173c1f
>
files
>
123
