1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
from spec on 25 November 2000 -->
<TITLE>Exim Specification - 32. The queryprogram router</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_31.html">previous</A>, <A HREF="spec_33.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC728" HREF="spec_toc.html#TOC728">32. The queryprogram router</A></H1>
<P>
<A NAME="IDX1647"></A>
The <EM>queryprogram</EM> router routes a domain 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 <EM>domains</EM>,
<EM>local_parts</EM> or <EM>condition</EM> generic options
to skip this router for most addresses, it could sensibly be used in
special cases. There are the following private options:
</P>
<P>
<P>
<A NAME="IDX1648"></A>
<A NAME="IDX1649"></A>
<H3><A NAME="SEC729" HREF="spec_toc.html#TOC729">command (queryprogram)</A></H3>
<P>
Type: string, expanded<BR>
Default: unset
</P>
<P>
This option must be set, and must start with a slash character. It specifies the
command that is to be run. It is expanded before use. Failure to expand causes
delivery to be deferred and the message to be frozen.
</P>
<P>
<A NAME="IDX1650"></A>
<H3><A NAME="SEC730" HREF="spec_toc.html#TOC730">command_group (queryprogram)</A></H3>
<P>
Type: string<BR>
Default: unset
</P>
<P>
<A NAME="IDX1651"></A>
This option specifies a gid to be set when running the command. If it begins
with a digit it is interpreted as the numerical value of the gid. Otherwise it
is looked up using <EM>getgrnam()</EM>.
</P>
<P>
<A NAME="IDX1652"></A>
<H3><A NAME="SEC731" HREF="spec_toc.html#TOC731">command_user (queryprogram)</A></H3>
<P>
Type: string<BR>
Default: unset
</P>
<P>
<A NAME="IDX1653"></A>
This option specifies the uid which is set when running the command.
If it begins with a digit it is interpreted as the numerical value of the uid.
Otherwise, it is looked up using <EM>getpwnam()</EM> to obtain a value for the uid
and, if
<EM>command_group</EM>
is not set, a value for the gid also.
</P>
<P>
<A NAME="IDX1654"></A>
<H3><A NAME="SEC732" HREF="spec_toc.html#TOC732">current_directory (queryprogram)</A></H3>
<P>
Type: string<BR>
Default: unset
</P>
<P>
This option specifies an absolute path which is made the current directory
before running the command. If it is not set, `/' is used.
</P>
<P>
<A NAME="IDX1655"></A>
<H3><A NAME="SEC733" HREF="spec_toc.html#TOC733">timeout (queryprogram)</A></H3>
<P>
Type: time<BR>
Default: 1h
</P>
<P>
If the command does not complete within the timeout period, its process
group
is killed and the message gets frozen. A value of zero time specifies no
timeout.
</P>
<P>
If
<EM>command_user</EM>
is not specified, the command is run as `nobody'. If the main configuration has
not defined a user and group for `nobody', it is looked up using
<EM>getpwnam()</EM>. If this fails, delivery is deferred and the message is frozen.
</P>
<P>
In previous versions of Exim the <EM>command_group</EM> and <EM>command_user</EM> options
were called <EM>group</EM> and <EM>user</EM>. Their names were changed when <EM>group</EM> and
<EM>user</EM> became generic router options.
</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 first field is one
of the following words:
</P>
<UL>
<LI>
OK: routing succeeded; the remaining fields specify what to do.
<LI>
<font color=green>
DECLINE: the router declines; pass the address to the next router, unless
<EM>no_more</EM> is set. (Formerly, FAIL was used for this; it remains for a while as
a synonym.)
</font>
<LI>
FORCEFAIL: routing failed; do not pass the address to any more routers.
<LI>
DEFER: routing could not be completed at this time; try again later.
<LI>
ERROR: some disastrous error occurred; freeze the message.
</UL>
<P>
When the first word is not OK, the remainder of the line is an error message
explaining what went wrong. For example:
<PRE>
FAIL queryprogram cannot route to unseen.discworld.fict.book
</PRE>
<P>
Otherwise, the line must be formatted as follows:
<PRE>
OK <<EM>transport name</EM>> <<EM>new domain</EM>> <<EM>option</EM>> <<EM>arbitrary text</EM>>
</PRE>
<P>
The second field is the name of a transport instance, or a plus
character, which means that the transport specified for the router using the
generic <EM>transport</EM> option is to be used, if set.
</P>
<P>
If the third field is not empty or a single plus character, it is a new domain
name to replace the current one. If a transport is specified and the fourth
field is not empty or a plus character, it specifies the method of looking up
the new name. This can be one of the words `byname', `bydns', `bydns_a', or
`bydns_mx'. For example,
<PRE>
OK smtp gate.star.fict.book bydns_a
</PRE>
<P>
causes the message to be sent using the <EM>smtp</EM> transport to the host
<EM>gate.star.fict.book</EM>, whose address is looked up as a DNS address record.
If the host turns out to be the local host, what happens is controlled by the
generic <EM>self</EM> option.
</P>
<P>
The fifth field, if present, is made available to the transport via the
expansion variable $<EM>route_option</EM>. For example, a line such as
<PRE>
OK special + + /computed/filename
</PRE>
<P>
sends the message to the <EM>special</EM> transport, which can use $<EM>route_option</EM>
in its configuration to access the text `/computed/filename'.
</P>
<P>
The fourth and fifth fields are ignored and the new domain name (if any) is
passed to the next router if no transport is specified in the response line
(that is, a plus character is given) and the generic <EM>transport</EM> option is also
unset.
<font color=green>
This counts as an explicitly configured `pass', and overrides <EM>no_more</EM>.
</font>
</P>
<P><HR><P>
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_31.html">previous</A>, <A HREF="spec_33.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
</BODY>
</HTML>
|
