masqmail

annotate man/masqmail.route.5 @ 431:34c919a8d74e

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