masqmail
view man/masqmail.route.5 @ 431:34c919a8d74e
Bumps version number and updates Changelog and NEWS
| author | markus schnalke <meillo@marmaro.de> |
|---|---|
| date | Sat, 07 Feb 2015 11:17:53 +0100 |
| parents | 5593964ec779 |
| children |
line source
1 .TH masqmail.route 5 2015-02-07 masqmail-0.3.5 "File Formats"
3 .SH NAME
4 masqmail.route \- masqmail route configuration file
7 .SH DESCRIPTION
9 This man page describes the syntax of the route configuration files of \fBmasqmail (8)\fR.
10 Their usual locations are in \fI/etc/masqmail/\fR.
12 Mail will be sent with the SMTP protocol to its destination, unless
13 `pipe' is given.
14 In this case the message will be piped to the given program.
17 .SH ROUTE CONDITIONS
19 .TP
20 \fBallowed_senders\fR = \fIlist\fR
22 This is a semicolon `;' separated list of envelope sender addresses.
23 Messages which have one of these addresses as the return path (= mail
24 from) are allowed to use this route
25 (if not also in \fBdenied_senders\fR).
27 Glob patterns containing `?' and `*' can be used.
28 The special item "<>" matches the null sender address
29 (eg. failure notices or delivery notifications).
30 If the pattern doesn't contain an `@', it is seen as a pattern for the
31 local part only.
33 Example: \fImeillo;*@*example.org;web*@example.com\fP
35 (``meillo'' equals ``meillo@*'', i.e. the local part.)
37 .TP
38 \fBdenied_senders\fR = \fIlist\fR
40 This is a semicolon `;' separated list of envelope sender addresses.
41 Messages which have one of these addresses as the return path (=
42 mail from) will not
43 be sent using this route (even if also in \fBallowed_senders\fR).
45 Glob patterns containing `?' and `*' can be used.
46 The special item "<>" matches the null sender address
47 (eg. failure notices or delivery notifications).
48 If the pattern doesn't contain an `@', it is seen as a pattern for the
49 local part only.
51 Example: (see \fIallowed_senders\fP)
53 .TP
54 \fBallowed_recipients\fR = \fIlist\fR
56 A list of envelope recipient addresses where mail can be sent to using
57 this route.
58 This is for example useful if you use this route configuration when connected to another LAN via ppp.
59 Glob patterns containing `?' and `*' can be used.
61 Example: \fI*@example.org;*@*foo.bar\fP
63 (See also examples for \fIallowed_senders\fP)
65 .TP
66 \fBdenied_recipients\fR = \fIlist\fR
68 A list of envelope recipient addresses where mail will not be sent to
69 using this route.
70 This is for example useful if you send mail directly (\fBmail_host\fR is not set)
71 and you know of hosts that will not accept mail from you because they use a dialup list
72 (eg. \fBhttp://maps.vix.com/dul/\fR).
73 \fBdenied_recipients\fR overrules \fBallowed_recipients\fR.
74 Glob patterns containing `?' and `*' can be used.
76 Example: \fI*@spamblocker.example.org\fP
78 (See also examples for \fIallowed_senders\fP)
80 .TP
81 \fBallowed_from_hdrs\fR = \fIlist\fR
83 This is a semicolon `;' separated list of From header addresses.
84 Messages which have one of these addresses as the From header
85 are allowed to use this route
86 (if not also in \fBdenied_from_hdrs\fR).
88 Glob patterns containing `?' and `*' can be used.
89 If the pattern doesn't contain an `@', it is seen as a pattern for the
90 local part only.
92 Example: \fImeillo;*@*example.org;web*@example.com\fP
94 (``meillo'' equals ``meillo@*'', i.e. the local part.)
96 .TP
97 \fBdenied_from_hdrs\fR = \fIlist\fR
99 This is a semicolon `;' separated list of From header addresses.
100 Messages which have one of these addresses as the From header
101 will not be sent using this route (even if also in
102 \fBallowed_from_hdrs\fR).
104 Glob patterns containing `?' and `*' can be used.
105 If the pattern doesn't contain an `@', it is seen as a pattern for the
106 local part only.
108 Example: (see \fIallowed_from_hdrs\fP)
110 .TP
111 \fBlast_route\fR = \fIboolean\fR
113 If this is set, a mail which would have been delivered using this route,
114 but has failed temporarily, will not be tried to be delivered using the next route.
116 If you have set up a special route with filters using the lists
117 `allowed_recipients' and `allowed_senders' or their complements
118 (denied_),
119 and the mail passing these rules should be delivered using this route only,
120 you should set this to `true'.
121 Otherwise the mail would be passed to the next route (if any),
122 unless that route has rules which prevent that.
124 Default is false.
126 .TP
127 \fBconnect_error_fail\fR = \fIboolean\fR
129 If this is set, a connection error (or if a pipe command could not be
130 executed) will cause a mail delivery to fail, ie. it will be bounced.
131 If it is unset, it will just be defered.
133 Default is false.
134 The reason for this is that masqmail is designed for non permanent internet connections,
135 where such errors may occur quite often, and a bounce would be annoying.
137 You probably want to set this to true for permanent routes.
140 .SH SMTP CONFIGURATION
142 .TP
143 \fBmail_host\fR = \fIstring\fR
145 This is preferably the mail server of your ISP.
146 All outgoing messages will be sent to this host which will distribute them to their destinations.
147 If you do not set this mails will be sent directly.
148 Because the mail server is probably `near' to you, mail transfer will be much faster if you use it.
150 You can optionally give a port number following the host name and a colon, eg mail_host="mail.foo.com:25".
152 .TP
153 \fBresolve_list\fR = \fIlist\fR
155 Specify the method how the domain of the server is resolved.
156 Possible values are dns_mx, dns_a, byname.
157 For `dns_mx', the domain is assumed to be an MX pointer to a list of host names,
158 these will be tried each in order
159 (lowest preference value first, equal preference values in random order).
160 For `dns_a', the domain is assumed to be an A pointer.
161 For `byname', the library function \fBgethostbyname(3)\fR will be used.
163 For routes to a local network, where you likely don't have a DNS service,
164 use only `byname'.
166 The default is "dns_mx;dns_a;byname".
168 .TP
169 \fBhelo_name\fR = \fIstring\fR
171 Set the name given with the HELO/EHLO command. If this is not set,
172 \fBhost_name\fR from \fImasqmail.conf\fR will be used,
173 if the \fBdo_correct_helo\fR option (see below) is unset.
175 .TP
176 \fBdo_correct_helo\fR = \fIboolean\fR
178 If this is set, masqmail tries to look up your host name as it appears
179 on the internet and sends this in the HELO/EHLO command.
180 Some servers are so picky that they want this.
181 Which is really crazy.
182 It just does not make any sense to lie about ones own identity,
183 because it can always be looked up by the server.
184 Nobody should believe in the name given by HELO/EHLO anyway.
185 If this is not set, \fBhost_name\fR from \fImasqmail.conf\fR or as given with
186 the \fBhelo_name\fR (see above) will be used.
188 .TP
189 \fBinstant_helo\fR = \fIboolean\fR
191 If this is set, masqmail does not wait for the greeting of the SMTP server
192 after opening the connection.
193 Instead it says EHLO right away (ESMTP is assumed).
194 Use this option with wrappers that eat the 220 greeting of the SMTP server.
195 Common examples are STARTTLS wrappers, like `openssl s_client \-starttls smtp ...'.
197 If this option is set and a 220 greeting is received though,
198 everything should still work.
199 Please don't rely on that and keep in mind that RFC 2821 says that the client
200 SHOULD wait for the 220 greeting of the server.
202 Default: false
204 .TP
205 \fBdo_pipelining\fR = \fIboolean\fR
207 If this is set to false, masqmail will not use ESMTP PIPELINING,
208 even if the server announces that it is able to cope with it.
209 Default is true.
211 You do not want to set this to false unless the mail setup on the
212 remote server side is really broken.
213 Keywords: wingate.
216 .TP
217 \fBauth_name\fR = \fIstring\fR
219 Set the authentication type for ESMTP AUTH authentication.
220 Currently only `cram-md5' and `login' are supported.
222 .TP
223 \fBauth_login\fR = \fIstring\fR
225 Your account name for ESMTP AUTH authentication.
227 .TP
228 \fBauth_secret\fR = \fIstring\fR
230 Your secret for ESMTP AUTH authentication.
232 .TP
233 \fBwrapper\fR = \fIcommand\fR
235 If set, instead of opening a connection to a remote server,
236 \fIcommand\fR will be called and all traffic will be piped to its stdin and from its stdout.
237 Purpose is to tunnel ip traffic, eg. for ssl.
239 Example for SMTP over SSL tunneling:
240 .nf
241 wrapper="/usr/bin/openssl s_client \-quiet \-connect mail.gmx.net:465 2>/dev/null"
242 .fi
244 SMTP over SSL is supported since masqmail-0.1.8.
245 It is marked obsolete by the IETF but is still in use.
248 Example for encryption with STARTTLS (RFC-3207):
249 .nf
250 # don't forget the instant_helo, otherwise it won't work
251 instant_helo=true
252 wrapper="/usr/bin/openssl s_client \-quiet \-starttls smtp \-connect mail.gmx.net:25 2>/dev/null"
253 .fi
255 This is supported since masqmail-0.2.28.
256 STARTTLS supersedes SMTP over SSL.
258 Note for openssl:
259 Ensure that stderr is redirected.
260 Do *not* use \-crlf in the wrapper command, because masqmail does already insert CRLF.
261 However, you might want to specify \-crlf if you want to test your wrapper command
262 interactively on the command line.
265 .SH PIPE CONFIGURATION
267 .TP
268 \fBpipe\fR = \fIcommand\fR
270 \fIcommand\fR will be called and the message will be piped to its stdin.
271 Purpose is to use gateways to uucp, fax, sms or whatever else.
273 You can use variables to give as arguments to the command,
274 these are the same as for the mda in the main configuration, see \fBmasqmail.conf(5)\fR.
276 .TP
277 \fBpipe_fromline = \fIboolean\fR
279 Only if `pipe' is used.
280 A from line will be prepended to the output stream whenever a pipe command is called.
281 Default is false.
283 .TP
284 \fBpipe_fromhack = \fIboolean\fR
286 Only if `pipe' is used.
287 Each line beginning with `From ' is replaced with `>From ' whenever a pipe command is called.
288 You probably want this if you have set \fBpipe_fromline\fR above.
289 Default is false.
292 .SH ADDRESS REWRITE RULES
294 .TP
295 \fBset_h_from_domain\fR = \fIstring\fR
297 Replace the domain part in `From:' headers with this value.
298 This may be useful if you use a private, outside unknown address on your local LAN
299 and want this to be replaced by the domain of the address of your email address on the internet.
300 Note that this is different to \fBset_return_path_domain\fR, see below.
302 .TP
303 \fBset_h_reply_to_domain\fR = \fIstring\fR
305 Same as \fBset_h_from_domain\fP, but for the `Reply-To' header.
307 .TP
308 \fBset_return_path_domain\fR = \fIstring\fR
310 Sets the domain part of the envelope from address.
311 Some hosts check whether this is the same as the net the connection is coming from.
312 If not, they reject the mail because they suspect spamming.
313 It should be a valid address, because some mail servers also check that.
314 You can also use this to set it to your usual address on the internet
315 and put a local address only known on your LAN in the configuration of your mailer.
316 Only the domain part will be changed, the local part remains unchanged.
317 Use \fBmap_return_path_addresses\fR for rewriting local parts.
319 .TP
320 \fBmap_h_from_addresses\fR = \fIlist\fR
322 This is similar to \fBset_h_from_domain\fR, but more flexible.
323 Set this to a list which maps local parts to a full RFC 822 compliant email address,
324 the local parts (the keys) are separated from the addresses (the values) by colons (`:').
326 Example:
327 .nf
328 map_h_from_addresses = "john: John Smith <jsmith@mail.academic.edu>; charlie: Charlie Miller <cmiller@mx.commercial.com>"
329 .fi
331 You can use patterns, eg. * as keys.
333 .TP
334 \fBmap_h_reply_to_addresses\fR = \fIlist\fR
336 Same as \fBmap_h_from_addresses\fR, but for the `Reply-To:' header.
338 .TP
339 \fBmap_h_mail_followup_to_addresses\fR = \fIlist\fR
341 Same as \fBmap_h_from_addresses\fR, but for the `Mail-Followup-To:' header.
342 Useful when replying to mailing lists.
344 .TP
345 \fBmap_return_path_addresses\fR = \fIlist\fR
347 This is similar to \fBset_return_path_domain\fR, but more flexible.
348 Set this to a list which maps local parts to a full RFC 821 compliant email address,
349 the local parts (the keys) are separated from the addresses (the values) by colons (`:').
350 Note that this option takes RFC 821 addresses while \fBmap_h_from_addresses\fR takes RFC 822 addresses.
351 The most important difference is that RFC 821 addresses have no full name.
353 Example:
354 .nf
355 map_return_path_addresses = "john: <jsmith@mail.academic.edu>; charlie: <cmiller@mx.commercial.com>"
356 .fi
358 You can use patterns, eg. * as keys.
360 .TP
361 \fBexpand_h_sender_address\fR = \fIboolean\fR
363 This sets the domain of the sender address as given by the Sender: header
364 to the same address as in the envelope return path address
365 (which can be set by either \fBset_return_path_domain\fR or \fBmap_return_path_addresses\fR).
366 This is for mail clients (eg. Microsoft Outlook) which use this address as the sender address.
367 Though they should use the From: address, see RFC 821.
368 If \fBfetchmail(1)\fR encounters an unqualified Sender: address,
369 it will be expanded to the domain of the pop server, which is almost never correct.
370 Default is true.
372 .TP
373 \fBexpand_h_sender_domain\fR = \fIboolean\fR
375 Like \fBexpand_h_sender_address\fR, but sets the domain only.
376 Deprecated, will be removed in a later version.
379 .SH AUTHOR
381 Masqmail was written by Oliver Kurth.
382 It is now maintained by Markus Schnalke <meillo@marmaro.de>.
384 You will find the newest version of masqmail at \fBhttp://marmaro.de/prog/masqmail/\fR.
385 There is also a mailing list, you will find information about it at masqmail's main site.
388 .SH BUGS
390 Please report bugs to the mailing list.
392 .SH SEE ALSO
394 \fBmasqmail(8)\fR, \fBmasqmail.conf(5)\fR