masqmail

annotate man/masqmail.route.5 @ 421:f37384470855

find changesets by author, revision, files, or words in the commit message
Changed lockdir to /var/lock/masqmail; Create lockdir and piddir on startup. Moved the lockdir out of the spool dir. (When /var/lock is a ramdisk we do well to have the lock files there.) Added the new configure option --with-lockdir to change that location. Nontheless, if we run_as_user, then lock files are always stored in the spool dir directly. Instead of installing the lockdir and piddir at installation time, we create them on startup time now if they are missing. This is necessary if lockdir or piddir are a tmpfs.
author markus schnalke <meillo@marmaro.de>
date Wed, 30 May 2012 09:38:38 +0200
parents 08932c629849
children 5593964ec779
rev   line source
meillo@380 1 .TH masqmail.route 5 2012-01-18 masqmail-0.3.4 "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@316 81 \fBlast_route\fR = \fIboolean\fR
meillo@316 82
meillo@316 83 If this is set, a mail which would have been delivered using this route,
meillo@316 84 but has failed temporarily, will not be tried to be delivered using the next route.
meillo@316 85
meillo@317 86 If you have set up a special route with filters using the lists
meillo@317 87 `allowed_recipients' and `allowed_senders' or their complements
meillo@317 88 (denied_),
meillo@316 89 and the mail passing these rules should be delivered using this route only,
meillo@316 90 you should set this to `true'.
meillo@316 91 Otherwise the mail would be passed to the next route (if any),
meillo@316 92 unless that route has rules which prevent that.
meillo@316 93
meillo@316 94 Default is false.
meillo@316 95
meillo@318 96 .TP
meillo@318 97 \fBconnect_error_fail\fR = \fIboolean\fR
meillo@318 98
meillo@318 99 If this is set, a connection error (or if a pipe command could not be
meillo@318 100 executed) will cause a mail delivery to fail, ie. it will be bounced.
meillo@318 101 If it is unset, it will just be defered.
meillo@318 102
meillo@318 103 Default is false.
meillo@318 104 The reason for this is that masqmail is designed for non permanent internet connections,
meillo@318 105 where such errors may occur quite often, and a bounce would be annoying.
meillo@318 106
meillo@354 107 You probably want to set this to true for permanent routes.
meillo@318 108
meillo@316 109
meillo@316 110 .SH SMTP CONFIGURATION
meillo@34 111
meillo@0 112 .TP
meillo@34 113 \fBmail_host\fR = \fIstring\fR
meillo@0 114
meillo@34 115 This is preferably the mail server of your ISP.
meillo@34 116 All outgoing messages will be sent to this host which will distribute them to their destinations.
meillo@34 117 If you do not set this mails will be sent directly.
meillo@34 118 Because the mail server is probably `near' to you, mail transfer will be much faster if you use it.
meillo@0 119
meillo@0 120 You can optionally give a port number following the host name and a colon, eg mail_host="mail.foo.com:25".
meillo@34 121
meillo@0 122 .TP
meillo@34 123 \fBresolve_list\fR = \fIlist\fR
meillo@0 124
meillo@34 125 Specify the method how the domain of the server is resolved.
meillo@34 126 Possible values are dns_mx, dns_a, byname.
meillo@34 127 For `dns_mx', the domain is assumed to be an MX pointer to a list of host names,
meillo@354 128 these will be tried each in order
meillo@354 129 (lowest preference value first, equal preference values in random order).
meillo@34 130 For `dns_a', the domain is assumed to be an A pointer.
meillo@34 131 For `byname', the library function \fBgethostbyname(3)\fR will be used.
meillo@0 132
meillo@354 133 For routes to a local network, where you likely don't have a DNS service,
meillo@354 134 use only `byname'.
meillo@354 135
meillo@0 136 The default is "dns_mx;dns_a;byname".
meillo@34 137
meillo@0 138 .TP
meillo@34 139 \fBhelo_name\fR = \fIstring\fR
meillo@0 140
meillo@34 141 Set the name given with the HELO/EHLO command. If this is not set,
meillo@34 142 \fBhost_name\fR from \fImasqmail.conf\fR will be used,
meillo@34 143 if the \fBdo_correct_helo\fR option (see below) is unset.
meillo@0 144
meillo@0 145 .TP
meillo@34 146 \fBdo_correct_helo\fR = \fIboolean\fR
meillo@0 147
meillo@34 148 If this is set, masqmail tries to look up your host name as it appears
meillo@34 149 on the internet and sends this in the HELO/EHLO command.
meillo@34 150 Some servers are so picky that they want this.
meillo@34 151 Which is really crazy.
meillo@34 152 It just does not make any sense to lie about ones own identity,
meillo@34 153 because it can always be looked up by the server.
meillo@34 154 Nobody should believe in the name given by HELO/EHLO anyway.
meillo@34 155 If this is not set, \fBhost_name\fR from \fImasqmail.conf\fR or as given with
meillo@34 156 the \fBhelo_name\fR (see above) will be used.
meillo@0 157
meillo@0 158 .TP
meillo@222 159 \fBinstant_helo\fR = \fIboolean\fR
meillo@222 160
meillo@222 161 If this is set, masqmail does not wait for the greeting of the SMTP server
meillo@222 162 after opening the connection.
meillo@222 163 Instead it says EHLO right away (ESMTP is assumed).
meillo@222 164 Use this option with wrappers that eat the 220 greeting of the SMTP server.
meillo@337 165 Common examples are STARTTLS wrappers, like `openssl s_client \-starttls smtp ...'.
meillo@222 166
meillo@222 167 If this option is set and a 220 greeting is received though,
meillo@222 168 everything should still work.
meillo@222 169 Please don't rely on that and keep in mind that RFC 2821 says that the client
meillo@222 170 SHOULD wait for the 220 greeting of the server.
meillo@222 171
meillo@222 172 Default: false
meillo@222 173
meillo@222 174 .TP
meillo@34 175 \fBdo_pipelining\fR = \fIboolean\fR
meillo@0 176
meillo@34 177 If this is set to false, masqmail will not use ESMTP PIPELINING,
meillo@34 178 even if the server announces that it is able to cope with it.
meillo@34 179 Default is true.
meillo@0 180
meillo@34 181 You do not want to set this to false unless the mail setup on the
meillo@34 182 remote server side is really broken.
meillo@34 183 Keywords: wingate.
meillo@0 184
meillo@0 185
meillo@0 186 .TP
meillo@316 187 \fBauth_name\fR = \fIstring\fR
meillo@0 188
meillo@316 189 Set the authentication type for ESMTP AUTH authentication.
meillo@316 190 Currently only `cram-md5' and `login' are supported.
meillo@0 191
meillo@0 192 .TP
meillo@316 193 \fBauth_login\fR = \fIstring\fR
meillo@0 194
meillo@316 195 Your account name for ESMTP AUTH authentication.
meillo@0 196
meillo@0 197 .TP
meillo@316 198 \fBauth_secret\fR = \fIstring\fR
meillo@0 199
meillo@316 200 Your secret for ESMTP AUTH authentication.
meillo@0 201
meillo@0 202 .TP
meillo@316 203 \fBwrapper\fR = \fIcommand\fR
meillo@0 204
meillo@316 205 If set, instead of opening a connection to a remote server,
meillo@316 206 \fIcommand\fR will be called and all traffic will be piped to its stdin and from its stdout.
meillo@316 207 Purpose is to tunnel ip traffic, eg. for ssl.
meillo@316 208
meillo@316 209 Example for SMTP over SSL tunneling:
meillo@316 210 .nf
meillo@316 211 wrapper="/usr/bin/openssl s_client \-quiet \-connect mail.gmx.net:465 2>/dev/null"
meillo@316 212 .fi
meillo@316 213
meillo@316 214 SMTP over SSL is supported since masqmail-0.1.8.
meillo@316 215 It is marked obsolete by the IETF but is still in use.
meillo@316 216
meillo@316 217
meillo@316 218 Example for encryption with STARTTLS (RFC-3207):
meillo@316 219 .nf
meillo@316 220 # don't forget the instant_helo, otherwise it won't work
meillo@316 221 instant_helo=true
meillo@316 222 wrapper="/usr/bin/openssl s_client \-quiet \-starttls smtp \-connect mail.gmx.net:25 2>/dev/null"
meillo@316 223 .fi
meillo@316 224
meillo@316 225 This is supported since masqmail-0.2.28.
meillo@316 226 STARTTLS supersedes SMTP over SSL.
meillo@316 227
meillo@316 228 Note for openssl:
meillo@316 229 Ensure that stderr is redirected.
meillo@316 230 Do *not* use \-crlf in the wrapper command, because masqmail does already insert CRLF.
meillo@316 231 However, you might want to specify \-crlf if you want to test your wrapper command
meillo@316 232 interactively on the command line.
meillo@316 233
meillo@316 234
meillo@316 235 .SH PIPE CONFIGURATION
meillo@0 236
meillo@0 237 .TP
meillo@316 238 \fBpipe\fR = \fIcommand\fR
meillo@0 239
meillo@316 240 \fIcommand\fR will be called and the message will be piped to its stdin.
meillo@316 241 Purpose is to use gateways to uucp, fax, sms or whatever else.
meillo@316 242
meillo@316 243 You can use variables to give as arguments to the command,
meillo@316 244 these are the same as for the mda in the main configuration, see \fBmasqmail.conf(5)\fR.
meillo@316 245
meillo@316 246 .TP
meillo@316 247 \fBpipe_fromline = \fIboolean\fR
meillo@316 248
meillo@316 249 Only if `pipe' is used.
meillo@316 250 A from line will be prepended to the output stream whenever a pipe command is called.
meillo@316 251 Default is false.
meillo@316 252
meillo@316 253 .TP
meillo@316 254 \fBpipe_fromhack = \fIboolean\fR
meillo@316 255
meillo@316 256 Only if `pipe' is used.
meillo@316 257 Each line beginning with `From ' is replaced with `>From ' whenever a pipe command is called.
meillo@316 258 You probably want this if you have set \fBpipe_fromline\fR above.
meillo@316 259 Default is false.
meillo@316 260
meillo@316 261
meillo@316 262 .SH ADDRESS REWRITE RULES
meillo@0 263
meillo@0 264 .TP
meillo@34 265 \fBset_h_from_domain\fR = \fIstring\fR
meillo@0 266
meillo@34 267 Replace the domain part in `From:' headers with this value.
meillo@34 268 This may be useful if you use a private, outside unknown address on your local LAN
meillo@141 269 and want this to be replaced by the domain of the address of your email address on the internet.
meillo@34 270 Note that this is different to \fBset_return_path_domain\fR, see below.
meillo@0 271
meillo@0 272 .TP
meillo@138 273 \fBset_h_reply_to_domain\fR = \fIstring\fR
meillo@138 274
meillo@138 275 Same as \fBset_h_from_domain\fP, but for the `Reply-To' header.
meillo@138 276
meillo@138 277 .TP
meillo@34 278 \fBset_return_path_domain\fR = \fIstring\fR
meillo@0 279
meillo@34 280 Sets the domain part of the envelope from address.
meillo@34 281 Some hosts check whether this is the same as the net the connection is coming from.
meillo@34 282 If not, they reject the mail because they suspect spamming.
meillo@34 283 It should be a valid address, because some mail servers also check that.
meillo@34 284 You can also use this to set it to your usual address on the internet
meillo@34 285 and put a local address only known on your LAN in the configuration of your mailer.
meillo@34 286 Only the domain part will be changed, the local part remains unchanged.
meillo@34 287 Use \fBmap_return_path_addresses\fR for rewriting local parts.
meillo@0 288
meillo@0 289 .TP
meillo@34 290 \fBmap_h_from_addresses\fR = \fIlist\fR
meillo@0 291
meillo@34 292 This is similar to \fBset_h_from_domain\fR, but more flexible.
meillo@34 293 Set this to a list which maps local parts to a full RFC 822 compliant email address,
meillo@34 294 the local parts (the keys) are separated from the addresses (the values) by colons (`:').
meillo@0 295
meillo@0 296 Example:
meillo@223 297 .nf
meillo@0 298 map_h_from_addresses = "john: John Smith <jsmith@mail.academic.edu>; charlie: Charlie Miller <cmiller@mx.commercial.com>"
meillo@223 299 .fi
meillo@0 300
meillo@0 301 You can use patterns, eg. * as keys.
meillo@34 302
meillo@0 303 .TP
meillo@34 304 \fBmap_h_reply_to_addresses\fR = \fIlist\fR
meillo@0 305
meillo@34 306 Same as \fBmap_h_from_addresses\fR, but for the `Reply-To:' header.
meillo@0 307
meillo@0 308 .TP
meillo@34 309 \fBmap_h_mail_followup_to_addresses\fR = \fIlist\fR
meillo@0 310
meillo@34 311 Same as \fBmap_h_from_addresses\fR, but for the `Mail-Followup-To:' header.
meillo@34 312 Useful when replying to mailing lists.
meillo@0 313
meillo@0 314 .TP
meillo@34 315 \fBmap_return_path_addresses\fR = \fIlist\fR
meillo@0 316
meillo@34 317 This is similar to \fBset_return_path_domain\fR, but more flexible.
meillo@34 318 Set this to a list which maps local parts to a full RFC 821 compliant email address,
meillo@34 319 the local parts (the keys) are separated from the addresses (the values) by colons (`:').
meillo@34 320 Note that this option takes RFC 821 addresses while \fBmap_h_from_addresses\fR takes RFC 822 addresses.
meillo@34 321 The most important difference is that RFC 821 addresses have no full name.
meillo@0 322
meillo@0 323 Example:
meillo@223 324 .nf
meillo@0 325 map_return_path_addresses = "john: <jsmith@mail.academic.edu>; charlie: <cmiller@mx.commercial.com>"
meillo@223 326 .fi
meillo@0 327
meillo@0 328 You can use patterns, eg. * as keys.
meillo@34 329
meillo@0 330 .TP
meillo@34 331 \fBexpand_h_sender_address\fR = \fIboolean\fR
meillo@0 332
meillo@34 333 This sets the domain of the sender address as given by the Sender: header
meillo@34 334 to the same address as in the envelope return path address
meillo@34 335 (which can be set by either \fBset_return_path_domain\fR or \fBmap_return_path_addresses\fR).
meillo@34 336 This is for mail clients (eg. Microsoft Outlook) which use this address as the sender address.
meillo@34 337 Though they should use the From: address, see RFC 821.
meillo@34 338 If \fBfetchmail(1)\fR encounters an unqualified Sender: address,
meillo@34 339 it will be expanded to the domain of the pop server, which is almost never correct.
meillo@34 340 Default is true.
meillo@0 341
meillo@0 342 .TP
meillo@34 343 \fBexpand_h_sender_domain\fR = \fIboolean\fR
meillo@0 344
meillo@34 345 Like \fBexpand_h_sender_address\fR, but sets the domain only.
meillo@34 346 Deprecated, will be removed in a later version.
meillo@0 347
meillo@34 348
meillo@0 349 .SH AUTHOR
meillo@0 350
meillo@34 351 Masqmail was written by Oliver Kurth.
meillo@34 352 It is now maintained by Markus Schnalke <meillo@marmaro.de>.
meillo@0 353
meillo@95 354 You will find the newest version of masqmail at \fBhttp://marmaro.de/prog/masqmail/\fR.
meillo@26 355 There is also a mailing list, you will find information about it at masqmail's main site.
meillo@0 356
meillo@34 357
meillo@0 358 .SH BUGS
meillo@0 359
meillo@34 360 Please report bugs to the mailing list.
meillo@0 361
meillo@0 362 .SH SEE ALSO
meillo@0 363
meillo@192 364 \fBmasqmail(8)\fR, \fBmasqmail.conf(5)\fR