masqmail

annotate man/masqmail.route.5 @ 223:9814e75de61c

find changesets by author, revision, files, or words in the commit message
updated docs to STARTTLS wrappers
author meillo@marmaro.de
date Fri, 23 Jul 2010 11:18:20 +0200
parents 8cddc65765bd
children 9397d10fd771
rev   line source
meillo@142 1 .TH masqmail.route 5 2010-07-06 masqmail-0.2.25 "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@171 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@222 77 \fBinstant_helo\fR = \fIboolean\fR
meillo@222 78
meillo@222 79 If this is set, masqmail does not wait for the greeting of the SMTP server
meillo@222 80 after opening the connection.
meillo@222 81 Instead it says EHLO right away (ESMTP is assumed).
meillo@222 82 Use this option with wrappers that eat the 220 greeting of the SMTP server.
meillo@223 83 Common examples are STARTTLS wrappers, like `openssl s_client -starttls smtp ...'.
meillo@222 84
meillo@222 85 If this option is set and a 220 greeting is received though,
meillo@222 86 everything should still work.
meillo@222 87 Please don't rely on that and keep in mind that RFC 2821 says that the client
meillo@222 88 SHOULD wait for the 220 greeting of the server.
meillo@222 89
meillo@222 90 Default: false
meillo@222 91
meillo@222 92
meillo@222 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@223 191 .nf
meillo@0 192 map_h_from_addresses = "john: John Smith <jsmith@mail.academic.edu>; charlie: Charlie Miller <cmiller@mx.commercial.com>"
meillo@223 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@223 218 .nf
meillo@0 219 map_return_path_addresses = "john: <jsmith@mail.academic.edu>; charlie: <cmiller@mx.commercial.com>"
meillo@223 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 \fBwrapper\fR = \fIcommand\fR
meillo@0 275
meillo@34 276 If set, instead of opening a connection to a remote server,
meillo@34 277 \fIcommand\fR will be called and all traffic will be piped to its stdin and from its stdout.
meillo@34 278 Purpose is to tunnel ip traffic, eg. for ssl.
meillo@0 279
meillo@223 280 Example for SMTP over SSL tunneling:
meillo@223 281 .nf
meillo@223 282 wrapper="/usr/bin/openssl s_client \-quiet \-connect mail.gmx.net:465 2>/dev/null"
meillo@223 283 .fi
meillo@0 284
meillo@223 285 SMTP over SSL is supported since masqmail-0.1.8.
meillo@223 286 It is marked obsolete by the IETF but is still in use.
meillo@171 287
meillo@171 288
meillo@223 289 Example for encryption with STARTTLS (RFC-3207):
meillo@223 290 .nf
meillo@223 291 # don't forget the instant_helo, otherwise it won't work
meillo@223 292 instant_helo=true
meillo@180 293 wrapper="/usr/bin/openssl s_client \-quiet \-starttls smtp \-connect mail.gmx.net:25 2>/dev/null"
meillo@223 294 .fi
meillo@223 295
meillo@223 296 This is supported since masqmail-0.2.28.
meillo@223 297 STARTTLS supersedes SMTP over SSL.
meillo@180 298
meillo@180 299 Note for openssl:
meillo@180 300 Ensure that stderr is redirected.
meillo@180 301 Do *not* use \-crlf in the wrapper command, because masqmail does already insert CRLF.
meillo@180 302 However, you might want to specify \-crlf if you want to test your wrapper command
meillo@180 303 interactively on the command line.
meillo@34 304
meillo@0 305 .TP
meillo@34 306 \fBpipe\fR = \fIcommand\fR
meillo@0 307
meillo@34 308 If set, and protocol is set to `pipe',
meillo@34 309 \fIcommand\fR will be called and the message will be piped to its stdin.
meillo@34 310 Purpose is to use gateways to uucp, fax, sms or whatever else.
meillo@0 311
meillo@34 312 You can use variables to give as arguments to the command,
meillo@34 313 these are the same as for the mda in the main configuration, see \fBmasqmail.conf(5)\fR.
meillo@0 314
meillo@0 315 .TP
meillo@34 316 \fBpipe_fromline = \fIboolean\fR
meillo@0 317
meillo@34 318 If this is set, and protocol is set to `pipe',
meillo@34 319 a from line will be prepended to the output stream whenever a pipe command is called.
meillo@34 320 Default is false.
meillo@0 321
meillo@0 322 .TP
meillo@34 323 \fBpipe_fromhack = \fIboolean\fR
meillo@0 324
meillo@34 325 If this is set, and protocol is set to `pipe',
meillo@34 326 each line beginning with `From ' is replaced with `>From ' whenever a pipe command is called.
meillo@34 327 You probably want this if you have set \fBpipe_fromline\fR above.
meillo@34 328 Default is false.
meillo@0 329
meillo@34 330
meillo@0 331 .SH AUTHOR
meillo@0 332
meillo@34 333 Masqmail was written by Oliver Kurth.
meillo@34 334 It is now maintained by Markus Schnalke <meillo@marmaro.de>.
meillo@0 335
meillo@95 336 You will find the newest version of masqmail at \fBhttp://marmaro.de/prog/masqmail/\fR.
meillo@26 337 There is also a mailing list, you will find information about it at masqmail's main site.
meillo@0 338
meillo@34 339
meillo@0 340 .SH BUGS
meillo@0 341
meillo@34 342 Please report bugs to the mailing list.
meillo@0 343
meillo@0 344 .SH SEE ALSO
meillo@0 345
meillo@192 346 \fBmasqmail(8)\fR, \fBmasqmail.conf(5)\fR