masqmail

annotate docs/old-manual/config.html @ 155:b5ab9cb2f18a

shut down on errors reading config file while reading config file, log to log file note: this breaks after SIGHUP
author meillo@marmaro.de
date Thu, 08 Jul 2010 09:43:27 +0200
parents
children
rev   line source
meillo@56 1
meillo@56 2
meillo@56 3
meillo@56 4
meillo@56 5
meillo@56 6
meillo@56 7
meillo@56 8
meillo@56 9 <HTML>
meillo@56 10 <HEAD>
meillo@56 11 <TITLE>MasqMail - Manual
meillo@56 12 </TITLE>
meillo@56 13 </HEAD>
meillo@56 14 <BODY TEXT="#000000" LINK="#0000ff" BGCOLOR="#ffffff">
meillo@56 15
meillo@56 16 <center>
meillo@56 17 <table width="80%">
meillo@56 18 <tr><td>
meillo@56 19 <table width="100%" bgcolor="#0000aa" cellspacing=0 cellpadding=0>
meillo@56 20 <tr>
meillo@56 21 <td>
meillo@56 22 <a href="manual.html">
meillo@56 23 <img width="20" src = "../images/u_arrow.gif" alt = "manual">
meillo@56 24 </a>
meillo@56 25 </td>
meillo@56 26 <td align=center width="100%"><font size="6" color = "#ffffff">Configuration</font></td>
meillo@56 27 <td>
meillo@56 28 <a href="./alias.html">
meillo@56 29 <img width="20" src = "../images/l_arrow.gif" alt = "Alias Format">
meillo@56 30 </a>
meillo@56 31 </td>
meillo@56 32 <td>
meillo@56 33 <a href="./faq.html">
meillo@56 34 <img width="20" src = "../images/r_arrow.gif" alt = "Frequently Asked Questions">
meillo@56 35 </a>
meillo@56 36 </td>
meillo@56 37 </tr>
meillo@56 38 </table>
meillo@56 39
meillo@56 40
meillo@56 41 <p>The configuration consists of lines of the form</p>
meillo@56 42
meillo@56 43 <i>val</i> = <i>expression</i>
meillo@56 44
meillo@56 45 <p>Where <i>val</i> is a variable name and <i>expression</i> a string,
meillo@56 46 which can be quoted with '"'. If the expression is on multiple lines
meillo@56 47 or contains characters other than letters, digits or the charcaters
meillo@56 48 '.', '-', '_', '/', it <em>must</em> be quoted. Unfortunately, you
meillo@56 49 cannot use quotes inside quotes. (Will be implemented in a later
meillo@56 50 version.)</p>
meillo@56 51
meillo@56 52 <p>Each val has a <i>type</i>, which can be boolean, numeric, string
meillo@56 53 or list. A boolean variable can be set with one of the values 'on',
meillo@56 54 'yes', and 'true' or 'off', 'no' and 'false'. List items are separated
meillo@56 55 with ';'. For some values patterns (like '*','?') can be used. The
meillo@56 56 spaces before and after the '=' are optional.</p>
meillo@56 57
meillo@56 58 <p>Most lists (exceptions: local_hosts, local_nets and
meillo@56 59 listen_addresses) accept files. These will be recognized by a leading
meillo@56 60 slash '/'. The contents of these files will be included at the
meillo@56 61 position of the file name, there can be items or other files before
meillo@56 62 and after the file entry. The format of the files is different
meillo@56 63 though, within these files each entry is on another line. (And not
meillo@56 64 separated by semicolons). This makes it easy to include large lists
meillo@56 65 which are common in different configuration files, so they do not have
meillo@56 66 to appear in every configuration file.</p>
meillo@56 67
meillo@56 68 <p>Blank lines and lines starting with '#' are ignored.</p>
meillo@56 69
meillo@56 70 <h4><font color = "#ff0000">Main Configuration</font></h4>
meillo@56 71
meillo@56 72 <b>run_as_user</b>, Type: <i>boolean</i>, default: <i>false</i>
meillo@56 73
meillo@56 74 <p>If this is set, masqmail runs with the user id of the user who
meillo@56 75 invoked it and never changes it. This is for debugging purposes
meillo@56 76 <em>only</em>. If the user is not root, masqmail will not be able to
meillo@56 77 listen on a port &lt; 1000 and will not be able to deliver local mail
meillo@56 78 to others than the user.</p>
meillo@56 79
meillo@56 80 <b>use_syslog</b>, Type: <i>boolean</i>, default: <i>false</i>
meillo@56 81
meillo@56 82 <p>If this is set, masqmail uses syslogd for logging. It uses facility
meillo@56 83 <i>MAIL</i>. You still have to set <b>log_dir</b> for debug files.</p>
meillo@56 84
meillo@56 85 <b>debug_level</b>, Type: <i>numeric</i>, default: <i>0</i>
meillo@56 86
meillo@56 87 <p>Set the debug level. Valid values are 0 to 6, increasing it further
meillo@56 88 makes no difference. Be careful if you set this as high as 5 or higher,
meillo@56 89 the logs may very soon fill your hard drive.</p>
meillo@56 90
meillo@56 91 <b>mail_dir</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 92
meillo@56 93 <p>The directory where local mail is stored, usually /var/spool/mail.</p>
meillo@56 94
meillo@56 95 <b>spool_dir</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 96
meillo@56 97 <p>The directory where masqmail stores its spool files (and later also
meillo@56 98 other stuff). It <em>must</em> have a subdirectory
meillo@56 99 <i>input</i>. Masqmail needs read and write permissions for this
meillo@56 100 directory. I suggest to use /var/spool/masqmail.</p>
meillo@56 101
meillo@56 102 <b>log_dir</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 103
meillo@56 104 <p>The directory where masqmail puts its log files, these are
meillo@56 105 <i>masqmail.log</i> and <i>debug.log</i>. Masqmail needs write
meillo@56 106 permission.</p>
meillo@56 107
meillo@56 108 <b>host_name</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 109
meillo@56 110 <p>This is used in different places: Masqmail identifies itself in the
meillo@56 111 greeting banner on incoming connections and in the HELO/EHLO command
meillo@56 112 for outgoing connections with this name, it is used in the Received:
meillo@56 113 header and to qualify the sender of a locally originating message.</p>
meillo@56 114
meillo@56 115 <p>It is <em>not</em> used to find whether an address is local. Use
meillo@56 116 <b>local_hosts</b> for that.</p>
meillo@56 117
meillo@56 118 <b>local_hosts</b>, Type: <i>list</i>, default: <i>none</i>
meillo@56 119
meillo@56 120 <p>A semicolon ';' separated list of hostnames which are considered
meillo@56 121 local. Normally you set it to "localhost;foo;foo.bar.com" if your host
meillo@56 122 has the fully qualified domain name 'foo.bar.com'.</p>
meillo@56 123
meillo@56 124 <b>local_nets</b>, Type: <i>list</i>, default: <i>none</i>
meillo@56 125
meillo@56 126 <p>A semicolon ';' separated list of hostnames which are on the
meillo@56 127 'local' net. Delivery to these hosts is attempted immediately. You can
meillo@56 128 use patterns with '*', eg. "*.bar.com".</p>
meillo@56 129
meillo@56 130 <b>listen_addresses</b>, Type: <i>list</i>, default: <i>none</i>
meillo@56 131
meillo@56 132 <p>A semicolon ';' separated list of interfaces on which connections
meillo@56 133 will be accepted. An interface ist defined by a hostname, optionally
meillo@56 134 followed by a colon ':' and a number for the port. If this is left out,
meillo@56 135 port 25 will be used.</p>
meillo@56 136
meillo@56 137 <p>You can set this to "localhost:25;foo:25" if your hostname is 'foo'.</p>
meillo@56 138
meillo@56 139 <b>do_queue</b>, Type: <i>boolean</i>, default: <i>false</i>
meillo@56 140
meillo@56 141 <p>If this is set, mail will not be delivered immediately when
meillo@56 142 accepted. Same as calling masqmail with the -odq option.</p>
meillo@56 143
meillo@56 144 <b>connect_route.&lt;name&gt;</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 145
meillo@56 146 <p>Replace &lt;name&gt; with a name to identify a connection. Set this
meillo@56 147 to a filename for the special <i>route</i> configuration for that
meillo@56 148 connection. You will use that name to call masqmail with the -qo option
meillo@56 149 every time a connection to your ISP is set up.</p>
meillo@56 150
meillo@56 151 <p>Example: Your ISP has the name <i>FastNet</i>. Then you write the
meillo@56 152 following line in the main configuration:</p>
meillo@56 153
meillo@56 154 <p><pre>connect_route.FastNet = "/etc/masqmail/fastnet.route"</pre></p>
meillo@56 155
meillo@56 156 <p>/etc/masqmail/fastnet.route is the route configuration file, see
meillo@56 157 below. As soon as a link to FastNet has been set up, you call masqmail
meillo@56 158 -qoFastNet. Masqmail will then read the specified file and send the
meillo@56 159 mails.</p>
meillo@56 160
meillo@56 161 <b>local_net_route</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 162
meillo@56 163 <p>This is similar to <b>connect_route.&lt;name&gt;</b> but for the
meillo@56 164 local net. Recipient addresses that are in <b>local_nets</b> will be
meillo@56 165 routed using this route configuration. Main purpose is to define a
meillo@56 166 mail server with <b>mail_host</b> in your local network. In simple
meillo@56 167 environments this can be left unset. If unset, a default route
meillo@56 168 configuration will be used.</p>
meillo@56 169
meillo@56 170 <b>alias_file</b>
meillo@56 171
meillo@56 172 <p>Set this to the location of your alias file. If unset, no aliasing
meillo@56 173 will be done.</p>
meillo@56 174
meillo@56 175 <b>online_detect</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 176
meillo@56 177 <p>Defines the method MasqMail uses to detect whether there is
meillo@56 178 currently an online connection. It can have the values <em>file</em>
meillo@56 179 or <em>mserver</em>.</p>
meillo@56 180
meillo@56 181 <p>When it is set to <em>file</em>, MasqMail first checks for the
meillo@56 182 existence of <b>online_file</b> (see below) and if it exists, it reads
meillo@56 183 it. The content of the file should be the name of the current
meillo@56 184 connection as defined with <b>connect_route.&lt;name&gt;</b> (without
meillo@56 185 a trailing newline character).</p>
meillo@56 186
meillo@56 187 <p>When it is set to <em>mserver</em>, MasqMail connects to the
meillo@56 188 masqdialer server using the value of <b>mserver_iface</b> and asks it
meillo@56 189 whether a connection exists and for the name, which should be the name
meillo@56 190 of the current connection as defined with
meillo@56 191 <b>connect_route.&lt;name&gt;</b>.</p>
meillo@56 192
meillo@56 193 <p>The online status is checked either when masqmail receives a mail
meillo@56 194 with an address outside your LAN or when called with the -qo option
meillo@56 195 (without arguments).</p>
meillo@56 196
meillo@56 197 <b>online_file</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 198
meillo@56 199 <p>This is the name of the file checked for when MasqMail determines
meillo@56 200 whether it is online. The file should only exist when there is
meillo@56 201 currently a connection. Create it in your ip-up script with eg.</p>
meillo@56 202
meillo@56 203 <p><pre>
meillo@56 204 echo -n &lt;name&gt; &gt; /tmp/connect_route
meillo@56 205 chmod 0644 /tmp/connect_route
meillo@56 206 </pre></p>
meillo@56 207
meillo@56 208 <p>Do not forget to delete it in your ip-down script.</p>
meillo@56 209
meillo@56 210 <b>mserver_iface</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 211
meillo@56 212 <p>The interface the masqdialer server is listening to. Usually this
meillo@56 213 will be "localhost:224" if mserver is running on the same host as
meillo@56 214 masqmail. But using this option, you can also let masqmail run on
meillo@56 215 another host by setting mserver_iface to another hostname,
meillo@56 216 eg. "foo:224".</p>
meillo@56 217
meillo@56 218 <b>get.&lt;name&gt;</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 219
meillo@56 220 <p>Replace &lt;name&gt; with a name to identify a <i>get</i>
meillo@56 221 configuration. Set this to a filename for the <i>get</i>
meillo@56 222 configuration. These files will be used to retrieve mail when called
meillo@56 223 with the -g option.</p>
meillo@56 224
meillo@56 225 <h4><font color = "#ff0000">Route Configuration</font></h4>
meillo@56 226
meillo@56 227 <b>mail_host</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 228
meillo@56 229 <p>This is preferably the mail server of your ISP. All outgoing
meillo@56 230 messages will be sent to this host which will distribute them to their
meillo@56 231 destinations. If you do not set this mails will be sent
meillo@56 232 directly. Because the mail server is probably 'near' to you, mail
meillo@56 233 transfer will be much faster if you use it.</p>
meillo@56 234
meillo@56 235 <b>do_correct_helo</b>, Type: <i>boolean</i>, default: <i>false</i>
meillo@56 236
meillo@56 237 <p>If this is set, masqmail tries to look up your host name as it
meillo@56 238 appears on the internet and sends this in the HELO/EHLO command. Some
meillo@56 239 servers are so picky that they want this. <em>Which is really
meillo@56 240 crazy. It just does not make any sense to lie about ones own identity,
meillo@56 241 because it can always be looked up by the server. Nobody should
meillo@56 242 believe in the name given by HELO/EHLO anyway.</em> If this is not
meillo@56 243 set, <b>host_name</b> will be used.</p>
meillo@56 244
meillo@56 245 <b>allowed_mail_locals</b>, Type: <i>list</i>, default: <i>none(all)</i>
meillo@56 246
meillo@56 247 <p>This is a semicolon ';' separated list of local parts which will be
meillo@56 248 allowed to send mail through this connection. If unset and
meillo@56 249 <b>not_allowed_mail_locals</b> is also unset, all users are
meillo@56 250 allowed.</p>
meillo@56 251
meillo@56 252 <b>not_allowed_mail_locals</b>, Type: <i>list</i>, default: <i>none</i>
meillo@56 253
meillo@56 254 <p>This is a semicolon ';' separated list of local parts which will be
meillo@56 255 <em>not</em> allowed to send mail through this connection. <em>Local
meillo@56 256 parts in this list will not be allowed to use this route even if they
meillo@56 257 are part of <b>allowed_mail_locals</b> (see above).</em></p>
meillo@56 258
meillo@56 259 <b>allowed_rcpt_domains</b>, Type: <i>list</i>, default: <i>none(all)</i>
meillo@56 260
meillo@56 261 <p>A list of recipient domains where mail will be sent to. This is for
meillo@56 262 example useful if you use this route configuration when connected to
meillo@56 263 another LAN via ppp. Patterns containing '?' and '*' can be used.</p>
meillo@56 264
meillo@56 265 <b>not_allowed_rcpt_domains</b>, Type: <i>list</i>, default: <i>none</i>
meillo@56 266
meillo@56 267 <p>A list of recipient domains where mail will <em>not</em> be sent
meillo@56 268 to. This is for example useful if you send mail directly (mail_host
meillo@56 269 ist not set) and you know of hosts that will not accept mail from you
meillo@56 270 because they use a dialup list (eg. <a
meillo@56 271 href="http://maps.vix.com/dul/"> maps.vix.com/dul/</a>). If any domain
meillo@56 272 matches <em>both</em> <b>allowed_rcpt_domains</b> and
meillo@56 273 <b>not_allowed_rcpt_domains</b>, mail will <em>not</em> be sent to
meillo@56 274 this domain. Patterns containing '?' and '*' can be used.</p>
meillo@56 275
meillo@56 276 <b>set_h_from_domain</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 277
meillo@56 278 <p>Replace the domain part in 'From:' headers with this value. This
meillo@56 279 may be useful if you use a private, outside unknown address on your
meillo@56 280 local LAN and want this to be replaced by the domain of the address of
meillo@56 281 your email addrsss on the internet. <em>Note that this is different to
meillo@56 282 <b>set_return_path_domain</b>, see below.</em></p>
meillo@56 283
meillo@56 284 <b>set_h_reply_to_domain</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 285
meillo@56 286 <p>Same as <b>set_h_from_domain</b>, but for the 'Reply-To' header.</p>
meillo@56 287
meillo@56 288 <b>set_return_path_domain</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 289
meillo@56 290 <p>Sets the domain part of the envelope from address. Some hosts check
meillo@56 291 whether this is the same as the net the connection is coming from. If
meillo@56 292 not, they reject the mail because they suspect spamming. It should be
meillo@56 293 a <em>valid</em> address, because some mail servers also check
meillo@56 294 that. You can also use this to set it to your usual address on the
meillo@56 295 internet and put a local address only known on your LAN in the
meillo@56 296 configuration of your mailer. <em>Only the <em>domain</em> part will
meillo@56 297 be changed, the local part remains unchanged. Use
meillo@56 298 <b>map_return_path_addresses</b> for rewriting local parts</em>.</p>
meillo@56 299
meillo@56 300 <b>map_h_from_addresses</b>, Type: <i>list</i>, default: <i>none</i>
meillo@56 301
meillo@56 302 <p>This is similar to <b>set_h_from_domain</b>, but more flexible. Set
meillo@56 303 this to a list which maps local parts to a full RFC 822 compliant
meillo@56 304 email address, the local parts (the <em>keys</em>) are separated from
meillo@56 305 the addresses (the <em>values</em>) by colons (':').</p>
meillo@56 306
meillo@56 307 <p>Example:</p>
meillo@56 308
meillo@56 309 <p><pre>
meillo@56 310 map_h_from_addresses =
meillo@56 311 "john: John Smith &lt;jsmith@mail.academic.edu&gt;;
meillo@56 312 charlie: Charlie Miller &lt;cmiller@mx.commercial.com&gt;"
meillo@56 313 </pre></p>
meillo@56 314
meillo@56 315 <b>map_h_reply_to_addresses</b>, Type: <i>list</i>, default: <i>none</i>
meillo@56 316
meillo@56 317 <p>Same as <b>map_h_from_addresses</b>, but for the 'Reply-To:' header.</p>
meillo@56 318
meillo@56 319 <b>map_return_path_addresses</b>, Type: <i>list</i>, default: <i>none</i>
meillo@56 320
meillo@56 321 <p>This is similar to <b>set_return_path_domain</b>, but more
meillo@56 322 flexible. Set this to a list which maps local parts to a full RFC 821
meillo@56 323 compliant email address, the local parts (the <em>keys</em>) are
meillo@56 324 separated from the addresses (the <em>values</em>) by colons
meillo@56 325 (':'). Note that this option takes <em>RFC 821</em> addresses
meillo@56 326 while <b>map_h_from_addresses</b> takes <em>RFC 822</em> addresses. The
meillo@56 327 most important difference is that RFC 821 addresses have no full
meillo@56 328 name.</p>
meillo@56 329
meillo@56 330 <p>Example:</p>
meillo@56 331 <p><pre>
meillo@56 332 map_return_path_addresses =
meillo@56 333 "john: &lt;jsmith@mail.academic.edu&gt;;
meillo@56 334 charlie: &lt;cmiller@mx.commercial.com&gt;"
meillo@56 335 </pre></p>
meillo@56 336
meillo@56 337 <b>expand_h_sender_domain</b>, Type: <i>boolean</i>, default: <i>true</i>
meillo@56 338
meillo@56 339 <p>This sets the domain of the sender address as given by the Sender:
meillo@56 340 header to the same domain as in the envelope return path address
meillo@56 341 (which can be set by either <b>set_return_path_domain</b> or
meillo@56 342 <b>map_return_path_addresses</b>). This is for mail clients
meillo@56 343 (eg. Microsoft Outlook) which use this address as the sender
meillo@56 344 address. <em>Though they should use the From: address, see RFC
meillo@56 345 821. </em>If <i>fetchmail</i> encounters an unqualified Sender:
meillo@56 346 address, it will be expanded to the domain of the pop server, which is
meillo@56 347 almost never correct. </p>
meillo@56 348
meillo@56 349 <b>auth_name</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 350
meillo@56 351 <p>Set the authentication type for ESMTP AUTH authentification.
meillo@56 352 Currently only 'cram-md5' is supported.</p>
meillo@56 353
meillo@56 354 <b>auth_login</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 355
meillo@56 356 <p>Your account name for ESMTP AUTH authentification.</p>
meillo@56 357
meillo@56 358 <b>auth_secret</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 359
meillo@56 360 <p>Your secret for ESMTP AUTH authentification.</p>
meillo@56 361
meillo@56 362 <b>pop_login</b>, Type: <i>string</i>, default: <i>none</i>
meillo@56 363
meillo@56 364 <p>If your Mail server requires SMTP-after-POP, set this to a
meillo@56 365 <i>get</i> configuration. If you login to the POP server
meillo@56 366 <em>before</em> you send, this is not necessary. See the <a href =
meillo@56 367 "get.html"</a>get configuration</a> for more information.</p>
meillo@56 368
meillo@56 369 </td></tr>
meillo@56 370
meillo@56 371 <tr><td>
meillo@56 372 <p>
meillo@56 373 <hr>
meillo@56 374 <address><a href = "mailto:kurth@innominate.de">Oliver Kurth</a></address>
meillo@56 375 Last modified: Tue May 30 15:19:56 CEST 2000
meillo@56 376 <br>
meillo@56 377 This page was created using <a href="http://www.freddyfrog.com/hacks/genpage/">Genpage</a> - Version: 1.0.6
meillo@56 378 </p>
meillo@56 379
meillo@56 380 </table>
meillo@56 381 </center>
meillo@56 382
meillo@56 383 </BODY>
meillo@56 384 </HEAD>
meillo@56 385