masqmail
view man/masqmail.route.5 @ 316:d596ac8b5afb
heavy restructuring of masqmail.route(5) (sections)
| author | meillo@marmaro.de |
|---|---|
| date | Mon, 25 Apr 2011 15:17:30 +0200 |
| parents | e230bcd0f1c6 |
| children | 55b7bde95d37 |
line source
1 .TH masqmail.route 5 2010-12-08 masqmail-0.3.1 "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_mail_locals\fR = \fIlist\fR
22 This is a semicolon `;' separated list of local parts of envelope
23 senders (= mail from = return path) which will be allowed
24 to send mail through this connection.
25 If unset and \fBnot_allowed_mail_locals\fR is also unset, all users are allowed.
27 .TP
28 \fBnot_allowed_mail_locals\fR = \fIlist\fR
30 This is a semicolon `;' separated list of local parts of envelope
31 senders (= mail from = return path) which will be not allowed
32 to send mail through this connection.
33 Local parts in this list will not be allowed to use this route even if they
34 are part of \fBallowed_mail_locals\fR (see above).
36 .TP
37 \fBallowed_return_paths\fR = \fIlist\fR
39 This is a semicolon `;' separated list of addresses.
40 Messages which have one of these addresses as the return path (=
41 envelope sender = mail from) will be used using this route
42 (if not also in \fBnot_allowed_return_paths\fR or an item in \fBnot_allowed_mail_locals\fR matches).
44 Patterns containing `?' and `*' can be used.
45 The special item "<>" matches the null sender address (eg. failure notices or delivery notifications).
47 .TP
48 \fBnot_allowed_return_paths\fR = \fIlist\fR
50 This is a semicolon `;' separated list of addresses.
51 Messages which have one of these addresses as the return path (=
52 envelope sender = mail from) will not
53 be used using this route (even if also in \fBallowed_return_paths\fR
54 or an item in \fBallowed_mail_locals\fR matches).
56 Patterns containing `?' and `*' can be used.
57 The special item "<>" matches the null sender address (eg. failure notices or delivery notifications).
59 .TP
60 \fBallowed_rcpt_domains\fR = \fIlist\fR
62 A list of recipient domains (of envelope recipients) where mail will be sent to.
63 This is for example useful if you use this route configuration when connected to another LAN via ppp.
64 Patterns containing `?' and `*' can be used.
66 .TP
67 \fBnot_allowed_rcpt_domains\fR = \fIlist\fR
69 A list of recipient domains (of envelope recipients) where mail will not be sent to.
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 If any domain matches both \fBallowed_rcpt_domains\fR and \fBnot_allowed_rcpt_domains\fR,
74 mail will not be sent to this domain.
75 Patterns containing `?' and `*' can be used.
77 .TP
78 \fBlast_route\fR = \fIboolean\fR
80 If this is set, a mail which would have been delivered using this route,
81 but has failed temporarily, will not be tried to be delivered using the next route.
83 If you have set up a special route with filters using the lists `allowed_rcpt_domains',
84 `allowed_return_paths', and `allowed_mail_locals' or their complements (not_),
85 and the mail passing these rules should be delivered using this route only,
86 you should set this to `true'.
87 Otherwise the mail would be passed to the next route (if any),
88 unless that route has rules which prevent that.
90 Default is false.
93 .SH SMTP CONFIGURATION
95 .TP
96 \fBmail_host\fR = \fIstring\fR
98 This is preferably the mail server of your ISP.
99 All outgoing messages will be sent to this host which will distribute them to their destinations.
100 If you do not set this mails will be sent directly.
101 Because the mail server is probably `near' to you, mail transfer will be much faster if you use it.
103 You can optionally give a port number following the host name and a colon, eg mail_host="mail.foo.com:25".
105 .TP
106 \fBresolve_list\fR = \fIlist\fR
108 Specify the method how the domain of the server is resolved.
109 Possible values are dns_mx, dns_a, byname.
110 For `dns_mx', the domain is assumed to be an MX pointer to a list of host names,
111 these will be tried each in order (lowest preference value first, equal preference values in random order).
112 For `dns_a', the domain is assumed to be an A pointer.
113 For `byname', the library function \fBgethostbyname(3)\fR will be used.
115 The default is "dns_mx;dns_a;byname".
117 .TP
118 \fBconnect_error_fail\fR = \fIboolean\fR
120 If this is set, a connection error will cause a mail delivery to fail, ie. it will be bounced.
121 If it is unset, it will just be defered.
123 Default is false.
124 The reason for this is that masqmail is designed for non permanent internet connections,
125 where such errors may occur quite often, and a bounce would be annoying.
127 For the default local_net route it is set to true.
129 .TP
130 \fBhelo_name\fR = \fIstring\fR
132 Set the name given with the HELO/EHLO command. If this is not set,
133 \fBhost_name\fR from \fImasqmail.conf\fR will be used,
134 if the \fBdo_correct_helo\fR option (see below) is unset.
136 .TP
137 \fBdo_correct_helo\fR = \fIboolean\fR
139 If this is set, masqmail tries to look up your host name as it appears
140 on the internet and sends this in the HELO/EHLO command.
141 Some servers are so picky that they want this.
142 Which is really crazy.
143 It just does not make any sense to lie about ones own identity,
144 because it can always be looked up by the server.
145 Nobody should believe in the name given by HELO/EHLO anyway.
146 If this is not set, \fBhost_name\fR from \fImasqmail.conf\fR or as given with
147 the \fBhelo_name\fR (see above) will be used.
149 .TP
150 \fBinstant_helo\fR = \fIboolean\fR
152 If this is set, masqmail does not wait for the greeting of the SMTP server
153 after opening the connection.
154 Instead it says EHLO right away (ESMTP is assumed).
155 Use this option with wrappers that eat the 220 greeting of the SMTP server.
156 Common examples are STARTTLS wrappers, like `openssl s_client -starttls smtp ...'.
158 If this option is set and a 220 greeting is received though,
159 everything should still work.
160 Please don't rely on that and keep in mind that RFC 2821 says that the client
161 SHOULD wait for the 220 greeting of the server.
163 Default: false
165 .TP
166 \fBdo_pipelining\fR = \fIboolean\fR
168 If this is set to false, masqmail will not use ESMTP PIPELINING,
169 even if the server announces that it is able to cope with it.
170 Default is true.
172 You do not want to set this to false unless the mail setup on the
173 remote server side is really broken.
174 Keywords: wingate.
177 .TP
178 \fBauth_name\fR = \fIstring\fR
180 Set the authentication type for ESMTP AUTH authentication.
181 Currently only `cram-md5' and `login' are supported.
183 .TP
184 \fBauth_login\fR = \fIstring\fR
186 Your account name for ESMTP AUTH authentication.
188 .TP
189 \fBauth_secret\fR = \fIstring\fR
191 Your secret for ESMTP AUTH authentication.
193 .TP
194 \fBwrapper\fR = \fIcommand\fR
196 If set, instead of opening a connection to a remote server,
197 \fIcommand\fR will be called and all traffic will be piped to its stdin and from its stdout.
198 Purpose is to tunnel ip traffic, eg. for ssl.
200 Example for SMTP over SSL tunneling:
201 .nf
202 wrapper="/usr/bin/openssl s_client \-quiet \-connect mail.gmx.net:465 2>/dev/null"
203 .fi
205 SMTP over SSL is supported since masqmail-0.1.8.
206 It is marked obsolete by the IETF but is still in use.
209 Example for encryption with STARTTLS (RFC-3207):
210 .nf
211 # don't forget the instant_helo, otherwise it won't work
212 instant_helo=true
213 wrapper="/usr/bin/openssl s_client \-quiet \-starttls smtp \-connect mail.gmx.net:25 2>/dev/null"
214 .fi
216 This is supported since masqmail-0.2.28.
217 STARTTLS supersedes SMTP over SSL.
219 Note for openssl:
220 Ensure that stderr is redirected.
221 Do *not* use \-crlf in the wrapper command, because masqmail does already insert CRLF.
222 However, you might want to specify \-crlf if you want to test your wrapper command
223 interactively on the command line.
226 .SH PIPE CONFIGURATION
228 .TP
229 \fBpipe\fR = \fIcommand\fR
231 \fIcommand\fR will be called and the message will be piped to its stdin.
232 Purpose is to use gateways to uucp, fax, sms or whatever else.
234 You can use variables to give as arguments to the command,
235 these are the same as for the mda in the main configuration, see \fBmasqmail.conf(5)\fR.
237 .TP
238 \fBpipe_fromline = \fIboolean\fR
240 Only if `pipe' is used.
241 A from line will be prepended to the output stream whenever a pipe command is called.
242 Default is false.
244 .TP
245 \fBpipe_fromhack = \fIboolean\fR
247 Only if `pipe' is used.
248 Each line beginning with `From ' is replaced with `>From ' whenever a pipe command is called.
249 You probably want this if you have set \fBpipe_fromline\fR above.
250 Default is false.
253 .SH ADDRESS REWRITE RULES
255 .TP
256 \fBset_h_from_domain\fR = \fIstring\fR
258 Replace the domain part in `From:' headers with this value.
259 This may be useful if you use a private, outside unknown address on your local LAN
260 and want this to be replaced by the domain of the address of your email address on the internet.
261 Note that this is different to \fBset_return_path_domain\fR, see below.
263 .TP
264 \fBset_h_reply_to_domain\fR = \fIstring\fR
266 Same as \fBset_h_from_domain\fP, but for the `Reply-To' header.
268 .TP
269 \fBset_return_path_domain\fR = \fIstring\fR
271 Sets the domain part of the envelope from address.
272 Some hosts check whether this is the same as the net the connection is coming from.
273 If not, they reject the mail because they suspect spamming.
274 It should be a valid address, because some mail servers also check that.
275 You can also use this to set it to your usual address on the internet
276 and put a local address only known on your LAN in the configuration of your mailer.
277 Only the domain part will be changed, the local part remains unchanged.
278 Use \fBmap_return_path_addresses\fR for rewriting local parts.
280 .TP
281 \fBmap_h_from_addresses\fR = \fIlist\fR
283 This is similar to \fBset_h_from_domain\fR, but more flexible.
284 Set this to a list which maps local parts to a full RFC 822 compliant email address,
285 the local parts (the keys) are separated from the addresses (the values) by colons (`:').
287 Example:
288 .nf
289 map_h_from_addresses = "john: John Smith <jsmith@mail.academic.edu>; charlie: Charlie Miller <cmiller@mx.commercial.com>"
290 .fi
292 You can use patterns, eg. * as keys.
294 .TP
295 \fBmap_h_reply_to_addresses\fR = \fIlist\fR
297 Same as \fBmap_h_from_addresses\fR, but for the `Reply-To:' header.
299 .TP
300 \fBmap_h_mail_followup_to_addresses\fR = \fIlist\fR
302 Same as \fBmap_h_from_addresses\fR, but for the `Mail-Followup-To:' header.
303 Useful when replying to mailing lists.
305 .TP
306 \fBmap_return_path_addresses\fR = \fIlist\fR
308 This is similar to \fBset_return_path_domain\fR, but more flexible.
309 Set this to a list which maps local parts to a full RFC 821 compliant email address,
310 the local parts (the keys) are separated from the addresses (the values) by colons (`:').
311 Note that this option takes RFC 821 addresses while \fBmap_h_from_addresses\fR takes RFC 822 addresses.
312 The most important difference is that RFC 821 addresses have no full name.
314 Example:
315 .nf
316 map_return_path_addresses = "john: <jsmith@mail.academic.edu>; charlie: <cmiller@mx.commercial.com>"
317 .fi
319 You can use patterns, eg. * as keys.
321 .TP
322 \fBexpand_h_sender_address\fR = \fIboolean\fR
324 This sets the domain of the sender address as given by the Sender: header
325 to the same address as in the envelope return path address
326 (which can be set by either \fBset_return_path_domain\fR or \fBmap_return_path_addresses\fR).
327 This is for mail clients (eg. Microsoft Outlook) which use this address as the sender address.
328 Though they should use the From: address, see RFC 821.
329 If \fBfetchmail(1)\fR encounters an unqualified Sender: address,
330 it will be expanded to the domain of the pop server, which is almost never correct.
331 Default is true.
333 .TP
334 \fBexpand_h_sender_domain\fR = \fIboolean\fR
336 Like \fBexpand_h_sender_address\fR, but sets the domain only.
337 Deprecated, will be removed in a later version.
340 .SH AUTHOR
342 Masqmail was written by Oliver Kurth.
343 It is now maintained by Markus Schnalke <meillo@marmaro.de>.
345 You will find the newest version of masqmail at \fBhttp://marmaro.de/prog/masqmail/\fR.
346 There is also a mailing list, you will find information about it at masqmail's main site.
349 .SH BUGS
351 Please report bugs to the mailing list.
353 .SH SEE ALSO
355 \fBmasqmail(8)\fR, \fBmasqmail.conf(5)\fR