masqmail
view docs/xml/masqmail.route.5.xml @ 0:08114f7dcc23
this is masqmail-0.2.21 from oliver kurth
| author | meillo@marmaro.de |
|---|---|
| date | Fri, 26 Sep 2008 17:05:23 +0200 |
| parents | |
| children |
line source
1 <?xml version="1.0" standalone='no'?>
2 <!DOCTYPE spec SYSTEM "man.dtd">
4 <manpage name="masqmail.route" section="5" desc="masqmail route configuration file">
6 <description>
7 <p>This man page describes the syntax of the route configuration files
8 of <manref name = "masqmail" section="8" href="masqmail.8.html"/>. Their usual locations are in <file>/etc/masqmail/</file>.</p>
9 </description>
11 <options>
13 <option>
14 <p><opt>protocol</opt> = <arg>string</arg></p>
15 <optdesc>
16 <p><arg>string</arg> can be one of 'smtp' or 'pipe', default is
17 'smtp'. If set to 'smtp', mail will be sent with the SMTP protocol to
18 its destination. If set to 'pipe', you also have to set 'pipe'
19 to a command, the message will then be piped to a program. See option 'pipe' below.</p>
20 </optdesc>
21 </option>
23 <option>
24 <p><opt>mail_host</opt> = <arg>string</arg></p>
25 <optdesc>
26 <p>This is preferably the mail server of your ISP. All outgoing
27 messages will be sent to this host which will distribute them to their
28 destinations. If you do not set this mails will be sent
29 directly. Because the mail server is probably 'near' to you, mail
30 transfer will be much faster if you use it.</p>
31 <p>You can optionally give a port number following the host name
32 and a colon, eg mail_host="mail.foo.com:25".</p>
33 </optdesc>
34 </option>
36 <option>
37 <p><opt>resolve_list</opt> = <arg>list</arg></p>
38 <optdesc>
39 <p>Specify the method how the domain of the server is resolved. Possible values are
40 dns_mx, dns_a, byname. For 'dns_mx', the domain is assumed to be an MX
41 pointer to a list of host names, these will be tried each in order
42 (lowest preference value first, equal preference values in random
43 order). For 'dns_a', the domain is assumed to be an A pointer. For
44 'byname', the library function <manref name="gethostbyname" section="3"/> will be used.</p>
45 <p>The default is "dns_mx;dns_a;byname".</p>
46 </optdesc>
47 </option>
49 <option>
50 <p><opt>connect_error_fail</opt> = <arg>boolean</arg></p>
51 <optdesc>
52 <p>If this is set, a connection error will cause a mail delivery to
53 fail, ie. it will be bounced. If it is unset, it will just be defered.</p>
54 <p>Default is false. The reason for this is that masqmail is designed
55 for non permanent internet connections, where such errors may occur
56 quite often, and a bounce would be annoying.</p>
57 <p>For the default local_net route is is set to true.</p>
58 </optdesc>
59 </option>
61 <option>
62 <p><opt>helo_name</opt> = <arg>string</arg></p>
63 <optdesc>
64 <p>Set the name given with the HELO/EHLO command. If this is not
65 set, <opt>host_name</opt> from <file>masqmail.conf</file> will be used, if
66 the <opt>do_correct_helo</opt> option (see below) is unset.</p>
67 </optdesc>
68 </option>
70 <option>
71 <p><opt>do_correct_helo</opt> = <arg>boolean</arg></p>
72 <optdesc>
73 <p>If this is set, masqmail tries to look up your host name as it
74 appears on the internet and sends this in the HELO/EHLO command. Some
75 servers are so picky that they want this. Which is really
76 crazy. It just does not make any sense to lie about ones own identity,
77 because it can always be looked up by the server. Nobody should
78 believe in the name given by HELO/EHLO anyway. If this is not
79 set, <opt>host_name</opt> from <file>masqmail.conf</file> or as given with
80 the <opt>helo_name</opt> (see above) will be used.</p>
81 </optdesc>
82 </option>
84 <option>
85 <p><opt>do_pipelining</opt> = <arg>boolean</arg></p>
86 <optdesc>
87 <p>If this is set to false, masqmail will not use ESMTP PIPELINING, even
88 if the server announces that it is able to cope with it. Default is true.</p>
89 <p>You do not want to set this to false unless the mail setup on the
90 remote server side is really broken. Keywords: wingate.</p>
91 </optdesc>
92 </option>
94 <option>
95 <p><opt>allowed_mail_locals</opt> = <arg>list</arg></p>
96 <optdesc>
97 <p>This is a semicolon ';' separated list of local parts which will be
98 allowed to send mail through this connection. If unset
99 and <opt>not_allowed_mail_locals</opt> is also unset, all users are
100 allowed.</p>
101 </optdesc>
102 </option>
104 <option>
105 <p><opt>not_allowed_mail_locals</opt> = <arg>list</arg></p>
106 <optdesc>
107 <p>This is a semicolon ';' separated list of local parts which will be
108 not allowed to send mail through this connection. Local
109 parts in this list will not be allowed to use this route even if they
110 are part of <opt>allowed_mail_locals</opt> (see above).</p>
111 </optdesc>
112 </option>
114 <option>
115 <p><opt>allowed_return_paths</opt> = <arg>list</arg></p>
116 <optdesc>
117 <p>This is a semicolon ';' separated list of addresses. Messages which
118 have one one of these addresses as the return path will be used using
119 this route (if not also in <opt>not_allowed_return_paths</opt> or an item
120 in <opt>not_allowed_mail_locals</opt> matches).</p>
121 <p>Patterns containing '?' and '*' can be used. The special item "<>" matches
122 the null sender address (eg. failure notices or delivery notifications).</p>
123 </optdesc>
124 </option>
126 <option>
127 <p><opt>not_allowed_return_paths</opt> = <arg>list</arg></p>
128 <optdesc>
129 <p>This is a semicolon ';' separated list of addresses. Messages which
130 have one one of these addresses as the return path will <em>not</em> be used using
131 this route (even if also in <opt>allowed_return_paths</opt> or an item
132 in <opt>allowed_mail_locals</opt> matches).</p>
133 <p>Patterns containing '?' and '*' can be used. The special item "<>" matches
134 the null sender address (eg. failure notices or delivery notifications).</p>
135 </optdesc>
136 </option>
138 <option>
139 <p><opt>allowed_rcpt_domains</opt> = <arg>list</arg></p>
140 <optdesc>
141 <p>A list of recipient domains where mail will be sent to. This is for
142 example useful if you use this route configuration when connected to
143 another LAN via ppp. Patterns containing '?' and '*' can be used.</p>
144 </optdesc>
145 </option>
147 <option>
148 <p><opt>not_allowed_rcpt_domains</opt> = <arg>list</arg></p>
149 <optdesc>
150 <p>A list of recipient domains where mail will <em>not</em> be sent
151 to. This is for example useful if you send mail directly (<opt>mail_host</opt> is
152 not set) and you know of hosts that will not accept mail from you
153 because they use a dialup list (eg. <url href="http://maps.vix.com/dul/"/>. If any domain
154 matches both <opt>allowed_rcpt_domains</opt> and <opt>not_allowed_rcpt_domains</opt>,
155 mail will not be sent to this domain. Patterns containing '?' and '*' can be used.</p>
156 </optdesc>
157 </option>
159 <option>
160 <p><opt>set_h_from_domain</opt> = <arg>string</arg></p>
161 <optdesc>
162 <p>Replace the domain part in 'From:' headers with this value. This
163 may be useful if you use a private, outside unknown address on your
164 local LAN and want this to be replaced by the domain of the address of
165 your email addrsss on the internet. Note that this is different to <opt>
166 set_return_path_domain</opt>, see below.</p>
167 </optdesc>
168 </option>
170 <option>
171 <p><opt>set_return_path_domain</opt> = <arg>string</arg></p>
172 <optdesc>
173 <p>Sets the domain part of the envelope from address. Some hosts check
174 whether this is the same as the net the connection is coming from. If
175 not, they reject the mail because they suspect spamming. It should be
176 a valid address, because some mail servers also check
177 that. You can also use this to set it to your usual address on the
178 internet and put a local address only known on your LAN in the
179 configuration of your mailer. Only the domain part will
180 be changed, the local part remains unchanged. Use <opt>
181 map_return_path_addresses</opt> for rewriting local parts.</p>
182 </optdesc>
183 </option>
185 <option>
186 <p><opt>map_h_from_addresses</opt> = <arg>list</arg></p>
187 <optdesc>
188 <p>This is similar to <opt>set_h_from_domain</opt>, but more flexible. Set
189 this to a list which maps local parts to a full RFC 822 compliant
190 email address, the local parts (the <em>keys</em>) are separated from
191 the addresses (the <em>values</em>) by colons (':').</p>
193 <p>Example:</p>
195 <p>map_h_from_addresses = "john: John Smith <jsmith@mail.academic.edu>;
196 charlie: Charlie Miller <cmiller@mx.commercial.com>"</p>
197 <p>You can use patterns, eg. * as keys.</p>
198 </optdesc>
199 </option>
201 <option>
202 <p><opt>map_h_reply_to_addresses</opt> = <arg>list</arg></p>
203 <optdesc>
204 <p>Same as <opt>map_h_from_addresses</opt>, but for the 'Reply-To:' header.</p>
205 </optdesc>
206 </option>
208 <option>
209 <p><opt>map_h_mail_followup_to_addresses</opt> = <arg>list</arg></p>
210 <optdesc>
211 <p>Same as <opt>map_h_from_addresses</opt>, but for the 'Mail-Followup-To:'
212 header. Useful when replying to mailing lists.</p>
213 </optdesc>
214 </option>
216 <option>
217 <p><opt>map_return_path_addresses</opt> = <arg>list</arg></p>
218 <optdesc>
219 <p>This is similar to <opt>set_return_path_domain</opt>, but more
220 flexible. Set this to a list which maps local parts to a full RFC 821
221 compliant email address, the local parts (the keys) are
222 separated from the addresses (the values) by colons
223 (':'). Note that this option takes RFC 821 addresses
224 while <opt>map_h_from_addresses</opt> takes RFC 822 addresses. The
225 most important difference is that RFC 821 addresses have no full
226 name.</p>
228 <p>Example:</p>
229 <p>
230 map_return_path_addresses =
231 "john: <jsmith@mail.academic.edu>;
232 charlie: <cmiller@mx.commercial.com>"
233 </p>
234 <p>You can use patterns, eg. * as keys.</p>
235 </optdesc>
236 </option>
238 <option>
239 <p><opt>expand_h_sender_address</opt> = <arg>boolean</arg></p>
240 <optdesc>
241 <p>This sets the domain of the sender address as given by the Sender:
242 header to the same address as in the envelope return path address
243 (which can be set by either <opt>set_return_path_domain</opt> or <opt>map_return_path_addresses</opt>).
244 This is for mail clients (eg. Microsoft Outlook) which use this address as the sender
245 address. Though they should use the From: address, see RFC
246 821. If <manref name="fetchmail" section="1" href="http://www.fetchmail.org"/> encounters an unqualified Sender:
247 address, it will be expanded to the domain of the pop server, which is
248 almost never correct. Default is true.</p>
249 </optdesc>
250 </option>
252 <option>
253 <p><opt>expand_h_sender_domain</opt> = <arg>boolean</arg></p>
254 <optdesc>
255 <p>Like <opt>expand_h_sender_address</opt>, but sets the domain only.
256 Deprecated, will be removed in a later version.</p>
257 </optdesc>
258 </option>
260 <option>
261 <p><opt>last_route</opt> = <arg>boolean</arg></p>
262 <optdesc>
263 <p>If this is set, a mail which would have been delivered using this
264 route, but has failed temporarily, will not be tried to be delivered
265 using the next route.</p>
266 <p>If you have set up a special route with filters using the lists
267 'allowed_rcpt_domains', 'allowed_return_paths', and
268 'allowed_mail_locals' or their complements (not_), and the mail
269 passing these rules should be delivered using this route only, you
270 should set this to 'true'. Otherwise the mail would be passed to the
271 next route (if any), unless that route has rules which prevent
272 that.</p>
273 <p>Default is false.</p>
274 </optdesc>
275 </option>
277 <option>
278 <p><opt>auth_name</opt> = <arg>string</arg></p>
279 <optdesc>
280 <p>Set the authentication type for ESMTP AUTH authentification.
281 Currently only 'cram-md5' and 'login' are supported.</p>
282 </optdesc>
283 </option>
285 <option>
286 <p><opt>auth_login</opt> = <arg>string</arg></p>
287 <optdesc>
288 <p>Your account name for ESMTP AUTH authentification.</p>
289 </optdesc>
290 </option>
292 <option>
293 <p><opt>auth_secret</opt> = <arg>string</arg></p>
294 <optdesc>
295 <p>Your secret for ESMTP AUTH authentification.</p>
296 </optdesc>
297 </option>
299 <option>
300 <p><opt>pop3_login</opt> = <arg>file</arg></p>
301 <optdesc>
302 <p>If your Mail server requires SMTP-after-POP, set this to a
303 get configuration (see <manref name="masqmail.get" section="5" href="masqmail.get.5.html"/>).
304 If you login to the POP server
305 before you send, this is not necessary.</p>
306 </optdesc>
307 </option>
309 <option>
310 <p><opt>wrapper</opt> = <arg>command</arg></p>
311 <optdesc>
312 <p>If set, instead of opening a connection to a remote server, <arg>command</arg> will
313 be called and all traffic will be piped to its
314 stdin and from its stdout. Purpose is to tunnel ip traffic, eg. for ssl.</p>
315 <p>Example for ssl tunneling:</p>
316 <p>wrapper="/usr/bin/openssl s_client -quiet -connect pop.gmx.net:995 2>/dev/null"</p>
317 </optdesc>
318 </option>
320 <option>
321 <p><opt>pipe</opt> = <arg>command</arg></p>
322 <optdesc>
323 <p>If set, and protocol is set to 'pipe', <arg>command</arg> will be
324 called and the message will be piped to its stdin. Purpose is to use
325 gateways to uucp, fax, sms or whatever else.</p>
326 <p>You can use variables to give as arguments to the command, these
327 are the same as for the mda in the main configuration, see <manref
328 name="masqmail.conf" section="5" href="masqmail.conf.5.html"/>.</p>
329 </optdesc>
330 </option>
332 <option>
333 <p><opt>pipe_fromline = <arg>boolean</arg></opt></p>
334 <optdesc>
335 <p>If this is set, and protocol is set to 'pipe', a from line will be prepended to the output stream whenever
336 a pipe command is called. Default is false.</p>
337 </optdesc>
338 </option>
340 <option>
341 <p><opt>pipe_fromhack = <arg>boolean</arg></opt></p>
342 <optdesc>
343 <p>If this is set, and protocol is set to 'pipe', each line beginning with 'From '
344 is replaced with '>From ' whenever a pipe command is called. You probably want this if you have
345 set <opt>pipe_fromline</opt> above. Default is false.</p>
346 </optdesc>
347 </option>
349 </options>
351 <section name = "Author">
352 <p>masqmail was written by Oliver Kurth
353 <oku@masqmail.cx></p><p>You will find the newest version of
354 masqmail at <url href="http://masqmail.cx/masqmail/"/> or search for it
355 in freshmeat (<url href="http://www.freshmeat.net"/>). There is also a mailing list,
356 you will find information about it at masqmails main site.</p>
357 </section>
359 <section name = "Bugs">
360 <p>You should report them to the mailing list.</p>
361 </section>
363 <section name = "See also">
364 <p>
365 <manref name="masqmail" section="8" href="masqmail.8.html"/>, <manref name="masqmail.conf" section="5" href="masqmail.conf.5.html"/>, <manref name="masqmail.get" section="5" href="masqmail.get.5.html"/>
366 </p>
367 </section>
369 <section name = "Comments">
370 <p>This man page was written using <manref name="xml2man" section="1"
371 href="http://masqmail.cx/xml2man/"/> by the same
372 author.</p>
373 </section>
375 </manpage>