masqmail

annotate docs/xml/masqmail.route.5.xml @ 1:af25f5c39d90

added diff from debian (masqmail-0.2.21-4)
author meillo@marmaro.de
date Fri, 26 Sep 2008 20:56:23 +0200
parents
children
rev   line source
meillo@0 1 <?xml version="1.0" standalone='no'?>
meillo@0 2 <!DOCTYPE spec SYSTEM "man.dtd">
meillo@0 3
meillo@0 4 <manpage name="masqmail.route" section="5" desc="masqmail route configuration file">
meillo@0 5
meillo@0 6 <description>
meillo@0 7 <p>This man page describes the syntax of the route configuration files
meillo@0 8 of <manref name = "masqmail" section="8" href="masqmail.8.html"/>. Their usual locations are in <file>/etc/masqmail/</file>.</p>
meillo@0 9 </description>
meillo@0 10
meillo@0 11 <options>
meillo@0 12
meillo@0 13 <option>
meillo@0 14 <p><opt>protocol</opt> = <arg>string</arg></p>
meillo@0 15 <optdesc>
meillo@0 16 <p><arg>string</arg> can be one of 'smtp' or 'pipe', default is
meillo@0 17 'smtp'. If set to 'smtp', mail will be sent with the SMTP protocol to
meillo@0 18 its destination. If set to 'pipe', you also have to set 'pipe'
meillo@0 19 to a command, the message will then be piped to a program. See option 'pipe' below.</p>
meillo@0 20 </optdesc>
meillo@0 21 </option>
meillo@0 22
meillo@0 23 <option>
meillo@0 24 <p><opt>mail_host</opt> = <arg>string</arg></p>
meillo@0 25 <optdesc>
meillo@0 26 <p>This is preferably the mail server of your ISP. All outgoing
meillo@0 27 messages will be sent to this host which will distribute them to their
meillo@0 28 destinations. If you do not set this mails will be sent
meillo@0 29 directly. Because the mail server is probably 'near' to you, mail
meillo@0 30 transfer will be much faster if you use it.</p>
meillo@0 31 <p>You can optionally give a port number following the host name
meillo@0 32 and a colon, eg mail_host="mail.foo.com:25".</p>
meillo@0 33 </optdesc>
meillo@0 34 </option>
meillo@0 35
meillo@0 36 <option>
meillo@0 37 <p><opt>resolve_list</opt> = <arg>list</arg></p>
meillo@0 38 <optdesc>
meillo@0 39 <p>Specify the method how the domain of the server is resolved. Possible values are
meillo@0 40 dns_mx, dns_a, byname. For 'dns_mx', the domain is assumed to be an MX
meillo@0 41 pointer to a list of host names, these will be tried each in order
meillo@0 42 (lowest preference value first, equal preference values in random
meillo@0 43 order). For 'dns_a', the domain is assumed to be an A pointer. For
meillo@0 44 'byname', the library function <manref name="gethostbyname" section="3"/> will be used.</p>
meillo@0 45 <p>The default is "dns_mx;dns_a;byname".</p>
meillo@0 46 </optdesc>
meillo@0 47 </option>
meillo@0 48
meillo@0 49 <option>
meillo@0 50 <p><opt>connect_error_fail</opt> = <arg>boolean</arg></p>
meillo@0 51 <optdesc>
meillo@0 52 <p>If this is set, a connection error will cause a mail delivery to
meillo@0 53 fail, ie. it will be bounced. If it is unset, it will just be defered.</p>
meillo@0 54 <p>Default is false. The reason for this is that masqmail is designed
meillo@0 55 for non permanent internet connections, where such errors may occur
meillo@0 56 quite often, and a bounce would be annoying.</p>
meillo@0 57 <p>For the default local_net route is is set to true.</p>
meillo@0 58 </optdesc>
meillo@0 59 </option>
meillo@0 60
meillo@0 61 <option>
meillo@0 62 <p><opt>helo_name</opt> = <arg>string</arg></p>
meillo@0 63 <optdesc>
meillo@0 64 <p>Set the name given with the HELO/EHLO command. If this is not
meillo@0 65 set, <opt>host_name</opt> from <file>masqmail.conf</file> will be used, if
meillo@0 66 the <opt>do_correct_helo</opt> option (see below) is unset.</p>
meillo@0 67 </optdesc>
meillo@0 68 </option>
meillo@0 69
meillo@0 70 <option>
meillo@0 71 <p><opt>do_correct_helo</opt> = <arg>boolean</arg></p>
meillo@0 72 <optdesc>
meillo@0 73 <p>If this is set, masqmail tries to look up your host name as it
meillo@0 74 appears on the internet and sends this in the HELO/EHLO command. Some
meillo@0 75 servers are so picky that they want this. Which is really
meillo@0 76 crazy. It just does not make any sense to lie about ones own identity,
meillo@0 77 because it can always be looked up by the server. Nobody should
meillo@0 78 believe in the name given by HELO/EHLO anyway. If this is not
meillo@0 79 set, <opt>host_name</opt> from <file>masqmail.conf</file> or as given with
meillo@0 80 the <opt>helo_name</opt> (see above) will be used.</p>
meillo@0 81 </optdesc>
meillo@0 82 </option>
meillo@0 83
meillo@0 84 <option>
meillo@0 85 <p><opt>do_pipelining</opt> = <arg>boolean</arg></p>
meillo@0 86 <optdesc>
meillo@0 87 <p>If this is set to false, masqmail will not use ESMTP PIPELINING, even
meillo@0 88 if the server announces that it is able to cope with it. Default is true.</p>
meillo@0 89 <p>You do not want to set this to false unless the mail setup on the
meillo@0 90 remote server side is really broken. Keywords: wingate.</p>
meillo@0 91 </optdesc>
meillo@0 92 </option>
meillo@0 93
meillo@0 94 <option>
meillo@0 95 <p><opt>allowed_mail_locals</opt> = <arg>list</arg></p>
meillo@0 96 <optdesc>
meillo@0 97 <p>This is a semicolon ';' separated list of local parts which will be
meillo@0 98 allowed to send mail through this connection. If unset
meillo@0 99 and <opt>not_allowed_mail_locals</opt> is also unset, all users are
meillo@0 100 allowed.</p>
meillo@0 101 </optdesc>
meillo@0 102 </option>
meillo@0 103
meillo@0 104 <option>
meillo@0 105 <p><opt>not_allowed_mail_locals</opt> = <arg>list</arg></p>
meillo@0 106 <optdesc>
meillo@0 107 <p>This is a semicolon ';' separated list of local parts which will be
meillo@0 108 not allowed to send mail through this connection. Local
meillo@0 109 parts in this list will not be allowed to use this route even if they
meillo@0 110 are part of <opt>allowed_mail_locals</opt> (see above).</p>
meillo@0 111 </optdesc>
meillo@0 112 </option>
meillo@0 113
meillo@0 114 <option>
meillo@0 115 <p><opt>allowed_return_paths</opt> = <arg>list</arg></p>
meillo@0 116 <optdesc>
meillo@0 117 <p>This is a semicolon ';' separated list of addresses. Messages which
meillo@0 118 have one one of these addresses as the return path will be used using
meillo@0 119 this route (if not also in <opt>not_allowed_return_paths</opt> or an item
meillo@0 120 in <opt>not_allowed_mail_locals</opt> matches).</p>
meillo@0 121 <p>Patterns containing '?' and '*' can be used. The special item "&lt;&gt;" matches
meillo@0 122 the null sender address (eg. failure notices or delivery notifications).</p>
meillo@0 123 </optdesc>
meillo@0 124 </option>
meillo@0 125
meillo@0 126 <option>
meillo@0 127 <p><opt>not_allowed_return_paths</opt> = <arg>list</arg></p>
meillo@0 128 <optdesc>
meillo@0 129 <p>This is a semicolon ';' separated list of addresses. Messages which
meillo@0 130 have one one of these addresses as the return path will <em>not</em> be used using
meillo@0 131 this route (even if also in <opt>allowed_return_paths</opt> or an item
meillo@0 132 in <opt>allowed_mail_locals</opt> matches).</p>
meillo@0 133 <p>Patterns containing '?' and '*' can be used. The special item "&lt;&gt;" matches
meillo@0 134 the null sender address (eg. failure notices or delivery notifications).</p>
meillo@0 135 </optdesc>
meillo@0 136 </option>
meillo@0 137
meillo@0 138 <option>
meillo@0 139 <p><opt>allowed_rcpt_domains</opt> = <arg>list</arg></p>
meillo@0 140 <optdesc>
meillo@0 141 <p>A list of recipient domains where mail will be sent to. This is for
meillo@0 142 example useful if you use this route configuration when connected to
meillo@0 143 another LAN via ppp. Patterns containing '?' and '*' can be used.</p>
meillo@0 144 </optdesc>
meillo@0 145 </option>
meillo@0 146
meillo@0 147 <option>
meillo@0 148 <p><opt>not_allowed_rcpt_domains</opt> = <arg>list</arg></p>
meillo@0 149 <optdesc>
meillo@0 150 <p>A list of recipient domains where mail will <em>not</em> be sent
meillo@0 151 to. This is for example useful if you send mail directly (<opt>mail_host</opt> is
meillo@0 152 not set) and you know of hosts that will not accept mail from you
meillo@0 153 because they use a dialup list (eg. <url href="http://maps.vix.com/dul/"/>. If any domain
meillo@0 154 matches both <opt>allowed_rcpt_domains</opt> and <opt>not_allowed_rcpt_domains</opt>,
meillo@0 155 mail will not be sent to this domain. Patterns containing '?' and '*' can be used.</p>
meillo@0 156 </optdesc>
meillo@0 157 </option>
meillo@0 158
meillo@0 159 <option>
meillo@0 160 <p><opt>set_h_from_domain</opt> = <arg>string</arg></p>
meillo@0 161 <optdesc>
meillo@0 162 <p>Replace the domain part in 'From:' headers with this value. This
meillo@0 163 may be useful if you use a private, outside unknown address on your
meillo@0 164 local LAN and want this to be replaced by the domain of the address of
meillo@0 165 your email addrsss on the internet. Note that this is different to <opt>
meillo@0 166 set_return_path_domain</opt>, see below.</p>
meillo@0 167 </optdesc>
meillo@0 168 </option>
meillo@0 169
meillo@0 170 <option>
meillo@0 171 <p><opt>set_return_path_domain</opt> = <arg>string</arg></p>
meillo@0 172 <optdesc>
meillo@0 173 <p>Sets the domain part of the envelope from address. Some hosts check
meillo@0 174 whether this is the same as the net the connection is coming from. If
meillo@0 175 not, they reject the mail because they suspect spamming. It should be
meillo@0 176 a valid address, because some mail servers also check
meillo@0 177 that. You can also use this to set it to your usual address on the
meillo@0 178 internet and put a local address only known on your LAN in the
meillo@0 179 configuration of your mailer. Only the domain part will
meillo@0 180 be changed, the local part remains unchanged. Use <opt>
meillo@0 181 map_return_path_addresses</opt> for rewriting local parts.</p>
meillo@0 182 </optdesc>
meillo@0 183 </option>
meillo@0 184
meillo@0 185 <option>
meillo@0 186 <p><opt>map_h_from_addresses</opt> = <arg>list</arg></p>
meillo@0 187 <optdesc>
meillo@0 188 <p>This is similar to <opt>set_h_from_domain</opt>, but more flexible. Set
meillo@0 189 this to a list which maps local parts to a full RFC 822 compliant
meillo@0 190 email address, the local parts (the <em>keys</em>) are separated from
meillo@0 191 the addresses (the <em>values</em>) by colons (':').</p>
meillo@0 192
meillo@0 193 <p>Example:</p>
meillo@0 194
meillo@0 195 <p>map_h_from_addresses = "john: John Smith &lt;jsmith@mail.academic.edu&gt;;
meillo@0 196 charlie: Charlie Miller &lt;cmiller@mx.commercial.com&gt;"</p>
meillo@0 197 <p>You can use patterns, eg. * as keys.</p>
meillo@0 198 </optdesc>
meillo@0 199 </option>
meillo@0 200
meillo@0 201 <option>
meillo@0 202 <p><opt>map_h_reply_to_addresses</opt> = <arg>list</arg></p>
meillo@0 203 <optdesc>
meillo@0 204 <p>Same as <opt>map_h_from_addresses</opt>, but for the 'Reply-To:' header.</p>
meillo@0 205 </optdesc>
meillo@0 206 </option>
meillo@0 207
meillo@0 208 <option>
meillo@0 209 <p><opt>map_h_mail_followup_to_addresses</opt> = <arg>list</arg></p>
meillo@0 210 <optdesc>
meillo@0 211 <p>Same as <opt>map_h_from_addresses</opt>, but for the 'Mail-Followup-To:'
meillo@0 212 header. Useful when replying to mailing lists.</p>
meillo@0 213 </optdesc>
meillo@0 214 </option>
meillo@0 215
meillo@0 216 <option>
meillo@0 217 <p><opt>map_return_path_addresses</opt> = <arg>list</arg></p>
meillo@0 218 <optdesc>
meillo@0 219 <p>This is similar to <opt>set_return_path_domain</opt>, but more
meillo@0 220 flexible. Set this to a list which maps local parts to a full RFC 821
meillo@0 221 compliant email address, the local parts (the keys) are
meillo@0 222 separated from the addresses (the values) by colons
meillo@0 223 (':'). Note that this option takes RFC 821 addresses
meillo@0 224 while <opt>map_h_from_addresses</opt> takes RFC 822 addresses. The
meillo@0 225 most important difference is that RFC 821 addresses have no full
meillo@0 226 name.</p>
meillo@0 227
meillo@0 228 <p>Example:</p>
meillo@0 229 <p>
meillo@0 230 map_return_path_addresses =
meillo@0 231 "john: &lt;jsmith@mail.academic.edu&gt;;
meillo@0 232 charlie: &lt;cmiller@mx.commercial.com&gt;"
meillo@0 233 </p>
meillo@0 234 <p>You can use patterns, eg. * as keys.</p>
meillo@0 235 </optdesc>
meillo@0 236 </option>
meillo@0 237
meillo@0 238 <option>
meillo@0 239 <p><opt>expand_h_sender_address</opt> = <arg>boolean</arg></p>
meillo@0 240 <optdesc>
meillo@0 241 <p>This sets the domain of the sender address as given by the Sender:
meillo@0 242 header to the same address as in the envelope return path address
meillo@0 243 (which can be set by either <opt>set_return_path_domain</opt> or <opt>map_return_path_addresses</opt>).
meillo@0 244 This is for mail clients (eg. Microsoft Outlook) which use this address as the sender
meillo@0 245 address. Though they should use the From: address, see RFC
meillo@0 246 821. If <manref name="fetchmail" section="1" href="http://www.fetchmail.org"/> encounters an unqualified Sender:
meillo@0 247 address, it will be expanded to the domain of the pop server, which is
meillo@0 248 almost never correct. Default is true.</p>
meillo@0 249 </optdesc>
meillo@0 250 </option>
meillo@0 251
meillo@0 252 <option>
meillo@0 253 <p><opt>expand_h_sender_domain</opt> = <arg>boolean</arg></p>
meillo@0 254 <optdesc>
meillo@0 255 <p>Like <opt>expand_h_sender_address</opt>, but sets the domain only.
meillo@0 256 Deprecated, will be removed in a later version.</p>
meillo@0 257 </optdesc>
meillo@0 258 </option>
meillo@0 259
meillo@0 260 <option>
meillo@0 261 <p><opt>last_route</opt> = <arg>boolean</arg></p>
meillo@0 262 <optdesc>
meillo@0 263 <p>If this is set, a mail which would have been delivered using this
meillo@0 264 route, but has failed temporarily, will not be tried to be delivered
meillo@0 265 using the next route.</p>
meillo@0 266 <p>If you have set up a special route with filters using the lists
meillo@0 267 'allowed_rcpt_domains', 'allowed_return_paths', and
meillo@0 268 'allowed_mail_locals' or their complements (not_), and the mail
meillo@0 269 passing these rules should be delivered using this route only, you
meillo@0 270 should set this to 'true'. Otherwise the mail would be passed to the
meillo@0 271 next route (if any), unless that route has rules which prevent
meillo@0 272 that.</p>
meillo@0 273 <p>Default is false.</p>
meillo@0 274 </optdesc>
meillo@0 275 </option>
meillo@0 276
meillo@0 277 <option>
meillo@0 278 <p><opt>auth_name</opt> = <arg>string</arg></p>
meillo@0 279 <optdesc>
meillo@0 280 <p>Set the authentication type for ESMTP AUTH authentification.
meillo@0 281 Currently only 'cram-md5' and 'login' are supported.</p>
meillo@0 282 </optdesc>
meillo@0 283 </option>
meillo@0 284
meillo@0 285 <option>
meillo@0 286 <p><opt>auth_login</opt> = <arg>string</arg></p>
meillo@0 287 <optdesc>
meillo@0 288 <p>Your account name for ESMTP AUTH authentification.</p>
meillo@0 289 </optdesc>
meillo@0 290 </option>
meillo@0 291
meillo@0 292 <option>
meillo@0 293 <p><opt>auth_secret</opt> = <arg>string</arg></p>
meillo@0 294 <optdesc>
meillo@0 295 <p>Your secret for ESMTP AUTH authentification.</p>
meillo@0 296 </optdesc>
meillo@0 297 </option>
meillo@0 298
meillo@0 299 <option>
meillo@0 300 <p><opt>pop3_login</opt> = <arg>file</arg></p>
meillo@0 301 <optdesc>
meillo@0 302 <p>If your Mail server requires SMTP-after-POP, set this to a
meillo@0 303 get configuration (see <manref name="masqmail.get" section="5" href="masqmail.get.5.html"/>).
meillo@0 304 If you login to the POP server
meillo@0 305 before you send, this is not necessary.</p>
meillo@0 306 </optdesc>
meillo@0 307 </option>
meillo@0 308
meillo@0 309 <option>
meillo@0 310 <p><opt>wrapper</opt> = <arg>command</arg></p>
meillo@0 311 <optdesc>
meillo@0 312 <p>If set, instead of opening a connection to a remote server, <arg>command</arg> will
meillo@0 313 be called and all traffic will be piped to its
meillo@0 314 stdin and from its stdout. Purpose is to tunnel ip traffic, eg. for ssl.</p>
meillo@0 315 <p>Example for ssl tunneling:</p>
meillo@0 316 <p>wrapper="/usr/bin/openssl s_client -quiet -connect pop.gmx.net:995 2>/dev/null"</p>
meillo@0 317 </optdesc>
meillo@0 318 </option>
meillo@0 319
meillo@0 320 <option>
meillo@0 321 <p><opt>pipe</opt> = <arg>command</arg></p>
meillo@0 322 <optdesc>
meillo@0 323 <p>If set, and protocol is set to 'pipe', <arg>command</arg> will be
meillo@0 324 called and the message will be piped to its stdin. Purpose is to use
meillo@0 325 gateways to uucp, fax, sms or whatever else.</p>
meillo@0 326 <p>You can use variables to give as arguments to the command, these
meillo@0 327 are the same as for the mda in the main configuration, see <manref
meillo@0 328 name="masqmail.conf" section="5" href="masqmail.conf.5.html"/>.</p>
meillo@0 329 </optdesc>
meillo@0 330 </option>
meillo@0 331
meillo@0 332 <option>
meillo@0 333 <p><opt>pipe_fromline = <arg>boolean</arg></opt></p>
meillo@0 334 <optdesc>
meillo@0 335 <p>If this is set, and protocol is set to 'pipe', a from line will be prepended to the output stream whenever
meillo@0 336 a pipe command is called. Default is false.</p>
meillo@0 337 </optdesc>
meillo@0 338 </option>
meillo@0 339
meillo@0 340 <option>
meillo@0 341 <p><opt>pipe_fromhack = <arg>boolean</arg></opt></p>
meillo@0 342 <optdesc>
meillo@0 343 <p>If this is set, and protocol is set to 'pipe', each line beginning with 'From '
meillo@0 344 is replaced with '>From ' whenever a pipe command is called. You probably want this if you have
meillo@0 345 set <opt>pipe_fromline</opt> above. Default is false.</p>
meillo@0 346 </optdesc>
meillo@0 347 </option>
meillo@0 348
meillo@0 349 </options>
meillo@0 350
meillo@0 351 <section name = "Author">
meillo@0 352 <p>masqmail was written by Oliver Kurth
meillo@0 353 &lt;oku@masqmail.cx&gt;</p><p>You will find the newest version of
meillo@0 354 masqmail at <url href="http://masqmail.cx/masqmail/"/> or search for it
meillo@0 355 in freshmeat (<url href="http://www.freshmeat.net"/>). There is also a mailing list,
meillo@0 356 you will find information about it at masqmails main site.</p>
meillo@0 357 </section>
meillo@0 358
meillo@0 359 <section name = "Bugs">
meillo@0 360 <p>You should report them to the mailing list.</p>
meillo@0 361 </section>
meillo@0 362
meillo@0 363 <section name = "See also">
meillo@0 364 <p>
meillo@0 365 <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"/>
meillo@0 366 </p>
meillo@0 367 </section>
meillo@0 368
meillo@0 369 <section name = "Comments">
meillo@0 370 <p>This man page was written using <manref name="xml2man" section="1"
meillo@0 371 href="http://masqmail.cx/xml2man/"/> by the same
meillo@0 372 author.</p>
meillo@0 373 </section>
meillo@0 374
meillo@0 375 </manpage>
meillo@0 376