1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/man/masqmail.route.5	Sat May 29 22:07:07 2010 +0200
     1.3 @@ -0,0 +1,308 @@
     1.4 +.TH masqmail.route 5 2010-05-07 masqmail-0.2.22 "File Formats"
     1.5 +
     1.6 +.SH NAME
     1.7 +masqmail.route \- masqmail route configuration file
     1.8 +
     1.9 +
    1.10 +.SH DESCRIPTION
    1.11 +
    1.12 +This man page describes the syntax of the route configuration files of \fBmasqmail (8)\fR.
    1.13 +Their usual locations are in \fI/etc/masqmail/\fR.
    1.14 +
    1.15 +.SH OPTIONS
    1.16 +
    1.17 +.TP
    1.18 +\fBprotocol\fR = \fIstring\fR
    1.19 +
    1.20 +\fIstring\fR can be one of `smtp' or `pipe', default is `smtp'.
    1.21 +If set to `smtp', mail will be sent with the SMTP protocol to its destination.
    1.22 +If set to `pipe', you also have to set `pipe' to a command, the message will then be piped to a program.
    1.23 +See option `pipe' below.
    1.24 +
    1.25 +.TP
    1.26 +\fBmail_host\fR = \fIstring\fR
    1.27 +
    1.28 +This is preferably the mail server of your ISP.
    1.29 +All outgoing messages will be sent to this host which will distribute them to their destinations.
    1.30 +If you do not set this mails will be sent directly.
    1.31 +Because the mail server is probably `near' to you, mail transfer will be much faster if you use it.
    1.32 +
    1.33 +You can optionally give a port number following the host name and a colon, eg mail_host="mail.foo.com:25".
    1.34 +
    1.35 +.TP
    1.36 +\fBresolve_list\fR = \fIlist\fR
    1.37 +
    1.38 +Specify the method how the domain of the server is resolved.
    1.39 +Possible values are dns_mx, dns_a, byname.
    1.40 +For `dns_mx', the domain is assumed to be an MX pointer to a list of host names,
    1.41 +these will be tried each in order (lowest preference value first, equal preference values in random order).
    1.42 +For `dns_a', the domain is assumed to be an A pointer.
    1.43 +For `byname', the library function \fBgethostbyname(3)\fR will be used.
    1.44 +
    1.45 +The default is "dns_mx;dns_a;byname".
    1.46 +
    1.47 +.TP
    1.48 +\fBconnect_error_fail\fR = \fIboolean\fR
    1.49 +
    1.50 +If this is set, a connection error will cause a mail delivery to fail, ie. it will be bounced.
    1.51 +If it is unset, it will just be defered.
    1.52 +
    1.53 +Default is false.
    1.54 +The reason for this is that masqmail is designed for non permanent internet connections,
    1.55 +where such errors may occur quite often, and a bounce would be annoying.
    1.56 +
    1.57 +For the default local_net route is is set to true.
    1.58 +
    1.59 +.TP
    1.60 +\fBhelo_name\fR = \fIstring\fR
    1.61 +
    1.62 +Set the name given with the HELO/EHLO command. If this is not set,
    1.63 +\fBhost_name\fR from \fImasqmail.conf\fR will be used,
    1.64 +if the \fBdo_correct_helo\fR option (see below) is unset.
    1.65 +
    1.66 +.TP
    1.67 +\fBdo_correct_helo\fR = \fIboolean\fR
    1.68 +
    1.69 +If this is set, masqmail tries to look up your host name as it appears
    1.70 +on the internet and sends this in the HELO/EHLO command.
    1.71 +Some servers are so picky that they want this.
    1.72 +Which is really crazy.
    1.73 +It just does not make any sense to lie about ones own identity,
    1.74 +because it can always be looked up by the server.
    1.75 +Nobody should believe in the name given by HELO/EHLO anyway.
    1.76 +If this is not set, \fBhost_name\fR from \fImasqmail.conf\fR or as given with
    1.77 +the \fBhelo_name\fR (see above) will be used.
    1.78 +
    1.79 +.TP
    1.80 +\fBdo_pipelining\fR = \fIboolean\fR
    1.81 +
    1.82 +If this is set to false, masqmail will not use ESMTP PIPELINING,
    1.83 +even if the server announces that it is able to cope with it.
    1.84 +Default is true.
    1.85 +
    1.86 +You do not want to set this to false unless the mail setup on the
    1.87 +remote server side is really broken.
    1.88 +Keywords: wingate.
    1.89 +
    1.90 +.TP
    1.91 +\fBallowed_mail_locals\fR = \fIlist\fR
    1.92 +
    1.93 +This is a semicolon `;' separated list of local parts which will be allowed
    1.94 +to send mail through this connection.
    1.95 +If unset and \fBnot_allowed_mail_locals\fR is also unset, all users are allowed.
    1.96 +
    1.97 +.TP
    1.98 +\fBnot_allowed_mail_locals\fR = \fIlist\fR
    1.99 +
   1.100 +This is a semicolon `;' separated list of local parts which will be not allowed
   1.101 +to send mail through this connection.
   1.102 +Local parts in this list will not be allowed to use this route even if they
   1.103 +are part of \fBallowed_mail_locals\fR (see above).
   1.104 +
   1.105 +.TP
   1.106 +\fBallowed_return_paths\fR = \fIlist\fR
   1.107 +
   1.108 +This is a semicolon `;' separated list of addresses.
   1.109 +Messages which have one one of these addresses as the return path will be used using this route
   1.110 +(if not also in \fBnot_allowed_return_paths\fR or an item in \fBnot_allowed_mail_locals\fR matches).
   1.111 +
   1.112 +Patterns containing `?' and `*' can be used.
   1.113 +The special item "<>" matches the null sender address (eg. failure notices or delivery notifications).
   1.114 +
   1.115 +.TP
   1.116 +\fBnot_allowed_return_paths\fR = \fIlist\fR
   1.117 +
   1.118 +This is a semicolon `;' separated list of addresses.
   1.119 +Messages which have one one of these addresses as the return path will not
   1.120 +be used using this route (even if also in \fBallowed_return_paths\fR
   1.121 +or an item in \fBallowed_mail_locals\fR matches).
   1.122 +
   1.123 +Patterns containing `?' and `*' can be used.
   1.124 +The special item "<>" matches the null sender address (eg. failure notices or delivery notifications).
   1.125 +
   1.126 +.TP
   1.127 +\fBallowed_rcpt_domains\fR = \fIlist\fR
   1.128 +
   1.129 +A list of recipient domains where mail will be sent to.
   1.130 +This is for example useful if you use this route configuration when connected to another LAN via ppp.
   1.131 +Patterns containing `?' and `*' can be used.
   1.132 +
   1.133 +.TP
   1.134 +\fBnot_allowed_rcpt_domains\fR = \fIlist\fR
   1.135 +
   1.136 +A list of recipient domains where mail will not be sent to.
   1.137 +This is for example useful if you send mail directly (\fBmail_host\fR is not set)
   1.138 +and you know of hosts that will not accept mail from you because they use a dialup list
   1.139 +(eg. \fBhttp://maps.vix.com/dul/\fR).
   1.140 +If any domain matches both \fBallowed_rcpt_domains\fR and \fBnot_allowed_rcpt_domains\fR,
   1.141 +mail will not be sent to this domain.
   1.142 +Patterns containing `?' and `*' can be used.
   1.143 +
   1.144 +.TP
   1.145 +\fBset_h_from_domain\fR = \fIstring\fR
   1.146 +
   1.147 +Replace the domain part in `From:' headers with this value.
   1.148 +This may be useful if you use a private, outside unknown address on your local LAN
   1.149 +and want this to be replaced by the domain of the address of your email addrsss on the internet.
   1.150 +Note that this is different to \fBset_return_path_domain\fR, see below.
   1.151 +
   1.152 +.TP
   1.153 +\fBset_return_path_domain\fR = \fIstring\fR
   1.154 +
   1.155 +Sets the domain part of the envelope from address.
   1.156 +Some hosts check whether this is the same as the net the connection is coming from.
   1.157 +If not, they reject the mail because they suspect spamming.
   1.158 +It should be a valid address, because some mail servers also check that.
   1.159 +You can also use this to set it to your usual address on the internet
   1.160 +and put a local address only known on your LAN in the configuration of your mailer.
   1.161 +Only the domain part will be changed, the local part remains unchanged.
   1.162 +Use \fBmap_return_path_addresses\fR for rewriting local parts.
   1.163 +
   1.164 +.TP
   1.165 +\fBmap_h_from_addresses\fR = \fIlist\fR
   1.166 +
   1.167 +This is similar to \fBset_h_from_domain\fR, but more flexible.
   1.168 +Set this to a list which maps local parts to a full RFC 822 compliant email address,
   1.169 +the local parts (the keys) are separated from the addresses (the values) by colons (`:').
   1.170 +
   1.171 +Example:
   1.172 +
   1.173 +map_h_from_addresses = "john: John Smith <jsmith@mail.academic.edu>; charlie: Charlie Miller <cmiller@mx.commercial.com>"
   1.174 +
   1.175 +You can use patterns, eg. * as keys.
   1.176 +
   1.177 +.TP
   1.178 +\fBmap_h_reply_to_addresses\fR = \fIlist\fR
   1.179 +
   1.180 +Same as \fBmap_h_from_addresses\fR, but for the `Reply-To:' header.
   1.181 +
   1.182 +.TP
   1.183 +\fBmap_h_mail_followup_to_addresses\fR = \fIlist\fR
   1.184 +
   1.185 +Same as \fBmap_h_from_addresses\fR, but for the `Mail-Followup-To:' header.
   1.186 +Useful when replying to mailing lists.
   1.187 +
   1.188 +.TP
   1.189 +\fBmap_return_path_addresses\fR = \fIlist\fR
   1.190 +
   1.191 +This is similar to \fBset_return_path_domain\fR, but more flexible.
   1.192 +Set this to a list which maps local parts to a full RFC 821 compliant email address,
   1.193 +the local parts (the keys) are separated from the addresses (the values) by colons (`:').
   1.194 +Note that this option takes RFC 821 addresses while \fBmap_h_from_addresses\fR takes RFC 822 addresses.
   1.195 +The most important difference is that RFC 821 addresses have no full name.
   1.196 +
   1.197 +Example:
   1.198 +
   1.199 +map_return_path_addresses = "john: <jsmith@mail.academic.edu>; charlie: <cmiller@mx.commercial.com>"
   1.200 +
   1.201 +You can use patterns, eg. * as keys.
   1.202 +
   1.203 +.TP
   1.204 +\fBexpand_h_sender_address\fR = \fIboolean\fR
   1.205 +
   1.206 +This sets the domain of the sender address as given by the Sender: header
   1.207 +to the same address as in the envelope return path address
   1.208 +(which can be set by either \fBset_return_path_domain\fR or \fBmap_return_path_addresses\fR).
   1.209 +This is for mail clients (eg. Microsoft Outlook) which use this address as the sender address.
   1.210 +Though they should use the From: address, see RFC 821.
   1.211 +If \fBfetchmail(1)\fR encounters an unqualified Sender: address,
   1.212 +it will be expanded to the domain of the pop server, which is almost never correct.
   1.213 +Default is true.
   1.214 +
   1.215 +.TP
   1.216 +\fBexpand_h_sender_domain\fR = \fIboolean\fR
   1.217 +
   1.218 +Like \fBexpand_h_sender_address\fR, but sets the domain only.
   1.219 +Deprecated, will be removed in a later version.
   1.220 +
   1.221 +.TP
   1.222 +\fBlast_route\fR = \fIboolean\fR
   1.223 +
   1.224 +If this is set, a mail which would have been delivered using this route,
   1.225 +but has failed temporarily, will not be tried to be delivered using the next route.
   1.226 +
   1.227 +If you have set up a special route with filters using the lists `allowed_rcpt_domains',
   1.228 +`allowed_return_paths', and `allowed_mail_locals' or their complements (not_),
   1.229 +and the mail passing these rules should be delivered using this route only,
   1.230 +you should set this to `true'.
   1.231 +Otherwise the mail would be passed to the next route (if any),
   1.232 +unless that route has rules which prevent that.
   1.233 +
   1.234 +Default is false.
   1.235 +
   1.236 +.TP
   1.237 +\fBauth_name\fR = \fIstring\fR
   1.238 +
   1.239 +Set the authentication type for ESMTP AUTH authentication.
   1.240 +Currently only `cram-md5' and `login' are supported.
   1.241 +
   1.242 +.TP
   1.243 +\fBauth_login\fR = \fIstring\fR
   1.244 +
   1.245 +Your account name for ESMTP AUTH authentication.
   1.246 +
   1.247 +.TP
   1.248 +\fBauth_secret\fR = \fIstring\fR
   1.249 +
   1.250 +Your secret for ESMTP AUTH authentication.
   1.251 +
   1.252 +.TP
   1.253 +\fBpop3_login\fR = \fIfile\fR
   1.254 +
   1.255 +If your Mail server requires SMTP-after-POP,
   1.256 +set this to a get configuration (see \fBmasqmail.get(5)\fR).
   1.257 +If you login to the POP server before you send, this is not necessary.
   1.258 +
   1.259 +.TP
   1.260 +\fBwrapper\fR = \fIcommand\fR
   1.261 +
   1.262 +If set, instead of opening a connection to a remote server,
   1.263 +\fIcommand\fR will be called and all traffic will be piped to its stdin and from its stdout.
   1.264 +Purpose is to tunnel ip traffic, eg. for ssl.
   1.265 +
   1.266 +Example for ssl tunneling:
   1.267 +
   1.268 +wrapper="/usr/bin/openssl s_client \-quiet \-connect pop.gmx.net:995 2>/dev/null"
   1.269 +
   1.270 +.TP
   1.271 +\fBpipe\fR = \fIcommand\fR
   1.272 +
   1.273 +If set, and protocol is set to `pipe',
   1.274 +\fIcommand\fR will be called and the message will be piped to its stdin.
   1.275 +Purpose is to use gateways to uucp, fax, sms or whatever else.
   1.276 +
   1.277 +You can use variables to give as arguments to the command,
   1.278 +these are the same as for the mda in the main configuration, see \fBmasqmail.conf(5)\fR.
   1.279 +
   1.280 +.TP
   1.281 +\fBpipe_fromline = \fIboolean\fR
   1.282 +
   1.283 +If this is set, and protocol is set to `pipe',
   1.284 +a from line will be prepended to the output stream whenever a pipe command is called.
   1.285 +Default is false.
   1.286 +
   1.287 +.TP
   1.288 +\fBpipe_fromhack = \fIboolean\fR
   1.289 +
   1.290 +If this is set, and protocol is set to `pipe',
   1.291 +each line beginning with `From ' is replaced with `>From ' whenever a pipe command is called.
   1.292 +You probably want this if you have set \fBpipe_fromline\fR above.
   1.293 +Default is false.
   1.294 +
   1.295 +
   1.296 +.SH AUTHOR
   1.297 +
   1.298 +Masqmail was written by Oliver Kurth.
   1.299 +It is now maintained by Markus Schnalke <meillo@marmaro.de>.
   1.300 +
   1.301 +You will find the newest version of masqmail at \fBhttp://prog.marmaro.de/masqmail/\fR.
   1.302 +There is also a mailing list, you will find information about it at masqmail's main site.
   1.303 +
   1.304 +
   1.305 +.SH BUGS
   1.306 +
   1.307 +Please report bugs to the mailing list.
   1.308 +
   1.309 +.SH SEE ALSO
   1.310 +
   1.311 +\fBmasqmail(8)\fR, \fBmasqmail.conf(5)\fR, \fBmasqmail.get(5)\fR