1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/xml/masqmail.route.5.xml	Fri Sep 26 17:05:23 2008 +0200
     1.3 @@ -0,0 +1,376 @@
     1.4 +<?xml version="1.0" standalone='no'?>
     1.5 +<!DOCTYPE spec SYSTEM "man.dtd">
     1.6 +
     1.7 +<manpage name="masqmail.route" section="5" desc="masqmail route configuration file">
     1.8 +
     1.9 +<description>
    1.10 +<p>This man page describes the syntax of the route configuration files
    1.11 +of <manref name = "masqmail" section="8" href="masqmail.8.html"/>. Their usual locations are in <file>/etc/masqmail/</file>.</p>
    1.12 +</description>
    1.13 +
    1.14 +<options>
    1.15 +
    1.16 +<option>
    1.17 +<p><opt>protocol</opt> = <arg>string</arg></p>
    1.18 +<optdesc>
    1.19 +<p><arg>string</arg> can be one of 'smtp' or 'pipe', default is
    1.20 +'smtp'. If set to 'smtp', mail will be sent with the SMTP protocol to
    1.21 +its destination. If set to 'pipe', you also have to set 'pipe'
    1.22 +to a command, the message will then be piped to a program. See option 'pipe' below.</p>
    1.23 +</optdesc>
    1.24 +</option>
    1.25 +
    1.26 +<option>
    1.27 +<p><opt>mail_host</opt> = <arg>string</arg></p>
    1.28 +<optdesc>
    1.29 +<p>This is preferably the mail server of your ISP. All outgoing
    1.30 +messages will be sent to this host which will distribute them to their
    1.31 +destinations. If you do not set this mails will be sent
    1.32 +directly. Because the mail server is probably 'near' to you, mail
    1.33 +transfer will be much faster if you use it.</p>
    1.34 +<p>You can optionally give a port number following the host name
    1.35 +and a colon, eg mail_host="mail.foo.com:25".</p>
    1.36 +</optdesc>
    1.37 +</option>
    1.38 +
    1.39 +<option>
    1.40 +<p><opt>resolve_list</opt> = <arg>list</arg></p>
    1.41 +<optdesc>
    1.42 +<p>Specify the method how the domain of the server is resolved. Possible values are
    1.43 +dns_mx, dns_a, byname. For 'dns_mx', the domain is assumed to be an MX
    1.44 +pointer to a list of host names, these will be tried each in order
    1.45 +(lowest preference value first, equal preference values in random
    1.46 +order). For 'dns_a', the domain is assumed to be an A pointer. For
    1.47 +'byname', the library function <manref name="gethostbyname" section="3"/> will be used.</p>
    1.48 +<p>The default is "dns_mx;dns_a;byname".</p>
    1.49 +</optdesc>
    1.50 +</option>
    1.51 +
    1.52 +<option>
    1.53 +<p><opt>connect_error_fail</opt> = <arg>boolean</arg></p>
    1.54 +<optdesc>
    1.55 +<p>If this is set, a connection error will cause a mail delivery to
    1.56 +fail, ie. it will be bounced. If it is unset, it will just be defered.</p>
    1.57 +<p>Default is false. The reason for this is that masqmail is designed
    1.58 +for non permanent internet connections, where such errors may occur
    1.59 +quite often, and a bounce would be annoying.</p>
    1.60 +<p>For the default local_net route is is set to true.</p>
    1.61 +</optdesc>
    1.62 +</option>
    1.63 +
    1.64 +<option>
    1.65 +<p><opt>helo_name</opt> = <arg>string</arg></p>
    1.66 +<optdesc>
    1.67 +<p>Set the name given with the HELO/EHLO command. If this is not
    1.68 +set, <opt>host_name</opt> from <file>masqmail.conf</file> will be used, if
    1.69 +the <opt>do_correct_helo</opt> option (see below) is unset.</p>
    1.70 +</optdesc>
    1.71 +</option>
    1.72 +
    1.73 +<option>
    1.74 +<p><opt>do_correct_helo</opt> = <arg>boolean</arg></p>
    1.75 +<optdesc>
    1.76 +<p>If this is set, masqmail tries to look up your host name as it
    1.77 +appears on the internet and sends this in the HELO/EHLO command. Some
    1.78 +servers are so picky that they want this. Which is really
    1.79 +crazy. It just does not make any sense to lie about ones own identity,
    1.80 +because it can always be looked up by the server. Nobody should
    1.81 +believe in the name given by HELO/EHLO anyway. If this is not
    1.82 +set, <opt>host_name</opt> from <file>masqmail.conf</file> or as given with
    1.83 +the <opt>helo_name</opt> (see above) will be used.</p>
    1.84 +</optdesc>
    1.85 +</option>
    1.86 +
    1.87 +<option>
    1.88 +<p><opt>do_pipelining</opt> = <arg>boolean</arg></p>
    1.89 +<optdesc>
    1.90 +<p>If this is set to false, masqmail will not use ESMTP PIPELINING, even
    1.91 +if the server announces that it is able to cope with it. Default is true.</p>
    1.92 +<p>You do not want to set this to false unless the mail setup on the
    1.93 +remote server side is really broken. Keywords: wingate.</p>
    1.94 +</optdesc>
    1.95 +</option>
    1.96 +
    1.97 +<option>
    1.98 +<p><opt>allowed_mail_locals</opt> = <arg>list</arg></p>
    1.99 +<optdesc>
   1.100 +<p>This is a semicolon ';' separated list of local parts which will be
   1.101 +allowed to send mail through this connection. If unset
   1.102 +and <opt>not_allowed_mail_locals</opt> is also unset, all users are
   1.103 +allowed.</p>
   1.104 +</optdesc>
   1.105 +</option>
   1.106 +
   1.107 +<option>
   1.108 +<p><opt>not_allowed_mail_locals</opt> = <arg>list</arg></p>
   1.109 +<optdesc>
   1.110 +<p>This is a semicolon ';' separated list of local parts which will be
   1.111 +not allowed to send mail through this connection. Local
   1.112 +parts in this list will not be allowed to use this route even if they
   1.113 +are part of <opt>allowed_mail_locals</opt> (see above).</p>
   1.114 +</optdesc>
   1.115 +</option>
   1.116 +
   1.117 +<option>
   1.118 +<p><opt>allowed_return_paths</opt> = <arg>list</arg></p>
   1.119 +<optdesc>
   1.120 +<p>This is a semicolon ';' separated list of addresses. Messages which
   1.121 +have one one of these addresses as the return path will be used using
   1.122 +this route (if not also in <opt>not_allowed_return_paths</opt> or an item
   1.123 +in <opt>not_allowed_mail_locals</opt> matches).</p>
   1.124 +<p>Patterns containing '?' and '*' can be used. The special item "&lt;&gt;" matches
   1.125 +the null sender address (eg. failure notices or delivery notifications).</p>
   1.126 +</optdesc>
   1.127 +</option>
   1.128 +
   1.129 +<option>
   1.130 +<p><opt>not_allowed_return_paths</opt> = <arg>list</arg></p>
   1.131 +<optdesc>
   1.132 +<p>This is a semicolon ';' separated list of addresses. Messages which
   1.133 +have one one of these addresses as the return path will <em>not</em> be used using
   1.134 +this route (even if also in <opt>allowed_return_paths</opt> or an item
   1.135 +in <opt>allowed_mail_locals</opt> matches).</p>
   1.136 +<p>Patterns containing '?' and '*' can be used. The special item "&lt;&gt;" matches
   1.137 +the null sender address (eg. failure notices or delivery notifications).</p>
   1.138 +</optdesc>
   1.139 +</option>
   1.140 +
   1.141 +<option>
   1.142 +<p><opt>allowed_rcpt_domains</opt> = <arg>list</arg></p>
   1.143 +<optdesc>
   1.144 +<p>A list of recipient domains where mail will be sent to. This is for
   1.145 +example useful if you use this route configuration when connected to
   1.146 +another LAN via ppp. Patterns containing '?' and '*' can be used.</p>
   1.147 +</optdesc>
   1.148 +</option>
   1.149 +
   1.150 +<option>
   1.151 +<p><opt>not_allowed_rcpt_domains</opt> = <arg>list</arg></p>
   1.152 +<optdesc>
   1.153 +<p>A list of recipient domains where mail will <em>not</em> be sent
   1.154 +to. This is for example useful if you send mail directly (<opt>mail_host</opt> is
   1.155 +not set) and you know of hosts that will not accept mail from you
   1.156 +because they use a dialup list (eg. <url href="http://maps.vix.com/dul/"/>. If any domain
   1.157 +matches both <opt>allowed_rcpt_domains</opt> and <opt>not_allowed_rcpt_domains</opt>,
   1.158 +mail will not be sent to this domain. Patterns containing '?' and '*' can be used.</p>
   1.159 +</optdesc>
   1.160 +</option>
   1.161 +
   1.162 +<option>
   1.163 +<p><opt>set_h_from_domain</opt> = <arg>string</arg></p>
   1.164 +<optdesc>
   1.165 +<p>Replace the domain part in 'From:' headers with this value. This
   1.166 +may be useful if you use a private, outside unknown address on your
   1.167 +local LAN and want this to be replaced by the domain of the address of
   1.168 +your email addrsss on the internet. Note that this is different to <opt>
   1.169 +set_return_path_domain</opt>, see below.</p>
   1.170 +</optdesc>
   1.171 +</option>
   1.172 +
   1.173 +<option>
   1.174 +<p><opt>set_return_path_domain</opt> = <arg>string</arg></p>
   1.175 +<optdesc>
   1.176 +<p>Sets the domain part of the envelope from address. Some hosts check
   1.177 +whether this is the same as the net the connection is coming from. If
   1.178 +not, they reject the mail because they suspect spamming. It should be
   1.179 +a valid address, because some mail servers also check
   1.180 +that. You can also use this to set it to your usual address on the
   1.181 +internet and put a local address only known on your LAN in the
   1.182 +configuration of your mailer. Only the domain part will
   1.183 +be changed, the local part remains unchanged. Use <opt>
   1.184 +map_return_path_addresses</opt> for rewriting local parts.</p>
   1.185 +</optdesc>
   1.186 +</option>
   1.187 +
   1.188 +<option>
   1.189 +<p><opt>map_h_from_addresses</opt> = <arg>list</arg></p>
   1.190 +<optdesc>
   1.191 +<p>This is similar to <opt>set_h_from_domain</opt>, but more flexible. Set
   1.192 +this to a list which maps local parts to a full RFC 822 compliant
   1.193 +email address, the local parts (the <em>keys</em>) are separated from
   1.194 +the addresses (the <em>values</em>) by colons (':').</p>
   1.195 +
   1.196 +<p>Example:</p>
   1.197 +
   1.198 +<p>map_h_from_addresses = "john: John Smith &lt;jsmith@mail.academic.edu&gt;;
   1.199 +charlie: Charlie Miller &lt;cmiller@mx.commercial.com&gt;"</p>
   1.200 +<p>You can use patterns, eg. * as keys.</p>
   1.201 +</optdesc>
   1.202 +</option>
   1.203 +
   1.204 +<option>
   1.205 +<p><opt>map_h_reply_to_addresses</opt> = <arg>list</arg></p>
   1.206 +<optdesc>
   1.207 +<p>Same as <opt>map_h_from_addresses</opt>, but for the 'Reply-To:' header.</p>
   1.208 +</optdesc>
   1.209 +</option>
   1.210 +
   1.211 +<option>
   1.212 +<p><opt>map_h_mail_followup_to_addresses</opt> = <arg>list</arg></p>
   1.213 +<optdesc>
   1.214 +<p>Same as <opt>map_h_from_addresses</opt>, but for the 'Mail-Followup-To:'
   1.215 +header. Useful when replying to mailing lists.</p>
   1.216 +</optdesc>
   1.217 +</option>
   1.218 +
   1.219 +<option>
   1.220 +<p><opt>map_return_path_addresses</opt> = <arg>list</arg></p>
   1.221 +<optdesc>
   1.222 +<p>This is similar to <opt>set_return_path_domain</opt>, but more
   1.223 +flexible. Set this to a list which maps local parts to a full RFC 821
   1.224 +compliant email address, the local parts (the keys) are
   1.225 +separated from the addresses (the values) by colons
   1.226 +(':'). Note that this option takes RFC 821 addresses
   1.227 +while <opt>map_h_from_addresses</opt> takes RFC 822 addresses. The
   1.228 +most important difference is that RFC 821 addresses have no full
   1.229 +name.</p>
   1.230 +
   1.231 +<p>Example:</p>
   1.232 +<p>
   1.233 +map_return_path_addresses =
   1.234 +"john: &lt;jsmith@mail.academic.edu&gt;;
   1.235 +charlie: &lt;cmiller@mx.commercial.com&gt;"
   1.236 +</p>
   1.237 +<p>You can use patterns, eg. * as keys.</p>
   1.238 +</optdesc>
   1.239 +</option>
   1.240 +
   1.241 +<option>
   1.242 +<p><opt>expand_h_sender_address</opt> = <arg>boolean</arg></p>
   1.243 +<optdesc>
   1.244 +<p>This sets the domain of the sender address as given by the Sender:
   1.245 +header to the same address as in the envelope return path address
   1.246 +(which can be set by either <opt>set_return_path_domain</opt> or <opt>map_return_path_addresses</opt>).
   1.247 +This is for mail clients (eg. Microsoft Outlook) which use this address as the sender
   1.248 +address. Though they should use the From: address, see RFC
   1.249 +821. If <manref name="fetchmail" section="1" href="http://www.fetchmail.org"/> encounters an unqualified Sender:
   1.250 +address, it will be expanded to the domain of the pop server, which is
   1.251 +almost never correct. Default is true.</p>
   1.252 +</optdesc>
   1.253 +</option>
   1.254 +
   1.255 +<option>
   1.256 +<p><opt>expand_h_sender_domain</opt> = <arg>boolean</arg></p>
   1.257 +<optdesc>
   1.258 +<p>Like <opt>expand_h_sender_address</opt>, but sets the domain only.
   1.259 +Deprecated, will be removed in a later version.</p>
   1.260 +</optdesc>
   1.261 +</option>
   1.262 +
   1.263 +<option>
   1.264 +<p><opt>last_route</opt> = <arg>boolean</arg></p>
   1.265 +<optdesc>
   1.266 +<p>If this is set, a mail which would have been delivered using this
   1.267 +route, but has failed temporarily, will not be tried to be delivered
   1.268 +using the next route.</p>
   1.269 +<p>If you have set up a special route with filters using the lists
   1.270 +'allowed_rcpt_domains', 'allowed_return_paths', and
   1.271 +'allowed_mail_locals' or their complements (not_), and the mail
   1.272 +passing these rules should be delivered using this route only, you
   1.273 +should set this to 'true'. Otherwise the mail would be passed to the
   1.274 +next route (if any), unless that route has rules which prevent
   1.275 +that.</p>
   1.276 +<p>Default is false.</p>
   1.277 +</optdesc>
   1.278 +</option>
   1.279 +
   1.280 +<option>
   1.281 +<p><opt>auth_name</opt> = <arg>string</arg></p>
   1.282 +<optdesc>
   1.283 +<p>Set the authentication type for ESMTP AUTH authentification.
   1.284 +Currently only 'cram-md5' and 'login' are supported.</p>
   1.285 +</optdesc>
   1.286 +</option>
   1.287 +
   1.288 +<option>
   1.289 +<p><opt>auth_login</opt> = <arg>string</arg></p>
   1.290 +<optdesc>
   1.291 +<p>Your account name for ESMTP AUTH authentification.</p>
   1.292 +</optdesc>
   1.293 +</option>
   1.294 +
   1.295 +<option>
   1.296 +<p><opt>auth_secret</opt> = <arg>string</arg></p>
   1.297 +<optdesc>
   1.298 +<p>Your secret for ESMTP AUTH authentification.</p>
   1.299 +</optdesc>
   1.300 +</option>
   1.301 +
   1.302 +<option>
   1.303 +<p><opt>pop3_login</opt> = <arg>file</arg></p>
   1.304 +<optdesc>
   1.305 +<p>If your Mail server requires SMTP-after-POP, set this to a
   1.306 +get configuration (see <manref name="masqmail.get" section="5" href="masqmail.get.5.html"/>).
   1.307 +If you login to the POP server
   1.308 +before you send, this is not necessary.</p>
   1.309 +</optdesc>
   1.310 +</option>
   1.311 +
   1.312 +<option>
   1.313 +<p><opt>wrapper</opt> = <arg>command</arg></p>
   1.314 +<optdesc>
   1.315 +<p>If set, instead of opening a connection to a remote server, <arg>command</arg> will
   1.316 +be called and all traffic will be piped to its
   1.317 +stdin and from its stdout. Purpose is to tunnel ip traffic, eg. for ssl.</p>
   1.318 +<p>Example for ssl tunneling:</p>
   1.319 +<p>wrapper="/usr/bin/openssl s_client -quiet -connect pop.gmx.net:995 2>/dev/null"</p>
   1.320 +</optdesc>
   1.321 +</option>
   1.322 +
   1.323 +<option>
   1.324 +<p><opt>pipe</opt> = <arg>command</arg></p>
   1.325 +<optdesc>
   1.326 +<p>If set, and protocol is set to 'pipe', <arg>command</arg> will be
   1.327 +called and the message will be piped to its stdin. Purpose is to use
   1.328 +gateways to uucp, fax, sms or whatever else.</p>
   1.329 +<p>You can use variables to give as arguments to the command, these
   1.330 +are the same as for the mda in the main configuration, see <manref
   1.331 +name="masqmail.conf" section="5" href="masqmail.conf.5.html"/>.</p>
   1.332 +</optdesc>
   1.333 +</option>
   1.334 +
   1.335 +<option>
   1.336 +<p><opt>pipe_fromline = <arg>boolean</arg></opt></p>
   1.337 +<optdesc>
   1.338 +<p>If this is set, and protocol is set to 'pipe', a from line will be prepended to the output stream whenever
   1.339 +a pipe command is called. Default is false.</p>
   1.340 +</optdesc>
   1.341 +</option>
   1.342 +
   1.343 +<option>
   1.344 +<p><opt>pipe_fromhack = <arg>boolean</arg></opt></p>
   1.345 +<optdesc>
   1.346 +<p>If this is set, and protocol is set to 'pipe', each line beginning with 'From '
   1.347 +is replaced with '>From ' whenever a pipe command is called. You probably want this if you have
   1.348 +set <opt>pipe_fromline</opt> above. Default is false.</p>
   1.349 +</optdesc>
   1.350 +</option>
   1.351 +
   1.352 +</options>
   1.353 +
   1.354 +<section name = "Author">
   1.355 +<p>masqmail was written by Oliver Kurth
   1.356 +&lt;oku@masqmail.cx&gt;</p><p>You will find the newest version of
   1.357 +masqmail at <url href="http://masqmail.cx/masqmail/"/> or search for it
   1.358 +in freshmeat (<url href="http://www.freshmeat.net"/>). There is also a mailing list,
   1.359 +you will find information about it at masqmails main site.</p>
   1.360 +</section>
   1.361 +
   1.362 +<section name = "Bugs">
   1.363 +<p>You should report them to the mailing list.</p>
   1.364 +</section>
   1.365 +
   1.366 +<section name = "See also">
   1.367 +<p>
   1.368 +<manref name="masqmail" section="8" href="masqmail.8.html"/>, <manref name="masqmail.conf" section="5" href="masqmail.conf.5.html"/>, <manref name="masqmail.get" section="5" href="masqmail.get.5.html"/>
   1.369 +</p>
   1.370 +</section>
   1.371 +
   1.372 +<section name = "Comments">
   1.373 +<p>This man page was written using <manref name="xml2man" section="1"
   1.374 +href="http://masqmail.cx/xml2man/"/> by the same
   1.375 +author.</p>
   1.376 +</section>
   1.377 +
   1.378 +</manpage>
   1.379 +