masqmail-0.2

annotate man/masqmail.route.5 @ 179:ec3fe72a3e99

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