--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/xml/masqmail.conf.5.xml	Fri Sep 26 17:05:23 2008 +0200
@@ -0,0 +1,561 @@
+<?xml version="1.0" standalone='no'?>
+<!DOCTYPE spec SYSTEM "man.dtd">
+
+<manpage name="masqmail.conf" section="5" desc="masqmail configuration file">
+
+<description>
+<p>This man page describes the syntax of the main configuration file
+of masqmail. Its usual location is <file>/etc/masqmail/masqmail.conf</file></p>
+
+<p>The configuration consists of lines of the form</p>
+
+<p><opt>val</opt> = <arg>expression</arg></p>
+
+<p>Where <opt>val</opt> is a variable name and <arg>expression</arg> a string,
+which can be quoted with '"'. If the expression is on multiple lines
+or contains characters other than letters, digits or the characters
+'.', '-', '_', '/', it <em>must</em> be quoted. You can use quotes inside quotes
+by escaping them with a backslash.</p>
+
+<p>Each val has a <i>type</i>, which can be boolean, numeric, string
+or list. A boolean variable can be set with one of the values 'on',
+'yes', and 'true' or 'off', 'no' and 'false'. List items are separated
+with ';'. For some values patterns (like '*','?') can be used. The
+spaces before and after the '=' are optional.</p>
+
+<p>Most lists (exceptions: <opt>local_hosts</opt>,
+<opt>local_nets</opt>, <opt>listen_addresses</opt>, <opt>online_routes</opt> and <opt>online_gets</opt>) accept
+files. These will be recognized by a leading slash '/'. The contents
+of these files will be included at the position of the file name,
+there can be items or other files before and after the file entry. The
+format of the files is different though, within these files each entry
+is on another line. (And not separated by semicolons). This makes it
+easy to include large lists which are common in different
+configuration files, so they do not have to appear in every
+configuration file.</p>
+
+<p>Blank lines and lines starting with '#' are ignored.</p>
+
+</description>
+
+<options>
+<option>
+<p><opt>run_as_user = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set, masqmail runs with the user id of the user who
+invoked it and never changes it. This is for debugging purposes 
+<em>only</em>. If the user is not root, masqmail will not be able to
+listen on a port &lt; 1024 and will not be able to deliver local mail
+to others than the user.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>use_syslog = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set, masqmail uses syslogd for logging. It uses facility
+MAIL. You still have to set <opt>log_dir</opt> for debug files.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>debug_level = <arg>n</arg></opt></p>
+<optdesc>
+<p>Set the debug level. Valid values are 0 to 6, increasing it further
+makes no difference. Be careful if you set this as high as 5 or higher,
+the logs may very soon fill your hard drive.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>mail_dir = <arg>file</arg></opt></p>
+<optdesc>
+<p>The directory where local mail is stored,
+usually <file>/var/spool/mail</file> or <file>/var/mail</file>.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>spool_dir = <arg>file</arg></opt></p>
+<optdesc>
+<p>The directory where masqmail stores its spool files (and later also
+other stuff). It <em>must</em> have a subdirectory <file>input</file>.
+Masqmail needs read and write permissions for this
+directory. I suggest to use <file>/var/spool/masqmail</file>.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>host_name = <arg>string</arg></opt></p>
+<optdesc>
+<p>This is used in different places: Masqmail identifies itself in the
+greeting banner on incoming connections and in the HELO/EHLO command
+for outgoing connections with this name, it is used in the Received:
+header and to qualify the sender of a locally originating message.</p>
+
+<p>If the string begins with a slash '/', it it assumed that it is a
+filename, and the first line of this file will be used. Usually this will
+be '/etc/mailname' to make masqmail conform to Debian policies.</p>
+
+<p>It is <em>not</em> used to find whether an address is local.
+Use <opt>local_hosts</opt> for that.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>remote_port = <arg>n</arg></opt></p>
+<optdesc>
+<p>The remote port number to be used. This defaults to port 25.</p>
+<p>This option is deprecated. Use <opt>host_name</opt> in the route
+configuration instead. See <manref name="masqmail.route" section="5"
+href="masqmail.route.5.html"/>.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>local_hosts = <arg>list</arg></opt></p>
+<optdesc>
+<p>A semicolon ';' separated list of hostnames which are considered
+local. Normally you set it to "localhost;foo;foo.bar.com" if your host
+has the fully qualified domain name 'foo.bar.com'.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>local_nets = <arg>list</arg></opt></p>
+<optdesc>
+<p>A semicolon ';' separated list of hostnames which are on the
+'local' net. Delivery to these hosts is attempted immediately. You can
+use patterns with '*', eg. "*.bar.com".</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>local_addresses = <arg>list</arg></opt></p>
+<optdesc>
+<p>A semicolon ';' separated list of fully qualified email-addresses
+which are considered local although their domain name part is not in
+the list of <opt>local_hosts</opt>. </p>
+<p>For example: There are two people working at your
+LAN: person1@yourdomain and person2@yourdomain. But there are
+other persons @yourdomain which are NOT local. So you can not put
+yourdomain to the list of local_hosts. If person1 now wants
+to write to person2@yourdomain and this mail should not leave the LAN
+then you can put</p>
+<p>local_addresses = "person1@yourdomain;person2@yourdomain"</p>
+<p>to your masqmail.conf.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>not_local_addresses = <arg>list</arg></opt></p>
+<optdesc>
+<p>A semicolon ';' separated list of fully qualified email-addresses
+which are considered not local although their domain name part is in
+the list of <opt>local_hosts</opt>. </p>
+<p>This ist the opposite of the previous case. The majority of addresses
+of a specific domain are local. But some users are not. With this
+option you can easily exclude these users.</p>
+<p>Example:</p>
+<p>local_hosts = "localhost;myhost;mydomain.net"</p>
+<p>not_local_addresses = "eric@mydomain.net"</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>listen_addresses = <arg>list</arg></opt></p>
+<optdesc>
+<p>A semicolon ';' separated list of interfaces on which connections
+will be accepted. An interface ist defined by a hostname, optionally
+followed by a colon ':' and a number for the port. If this is left out,
+port 25 will be used.</p>
+<p>You can set this to "localhost:25;foo:25" if your hostname is 'foo'.</p>
+<p>Note that the names are resolved to IP addreses. If your host has
+different names which resolve to the same IP, use only one of them,
+otherwise you will get an error message.
+</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>do_save_envelope_to = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set to true, a possibly existing Envelope-to: header in an
+incoming mail which is received via either pop3 or smtp will be saved as
+an X-Orig-Envelope-to: header.</p>
+<p>This is useful if you retrieve mail from a pop3 server with either masqmail
+or fetchmail, and the server supports Envelope-to: headers, and you want to make use
+of those with a mail filtering tool, eg. procmail. It cannot be preserved because
+masqmail sets such a header by itself.</p>
+<p>Default is false.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>do_relay = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set to false, mail with a return path that is not local and a
+destination that is also not local will not be accepted via smtp and a 550
+reply will be given. Default is true.</p>
+<p>Note that this will not protect you from spammers using open relays, but from
+users unable to set their address in their mail clients.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>do_queue = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set, mail will not be delivered immediately when
+accepted. Same as calling masqmail with the <opt>-odq</opt> option.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>online_routes.<arg>name</arg> = <arg>list</arg></opt></p>
+<optdesc>
+
+<p>Replace <arg>name</arg> with a name to identify a connection. Set this
+to a filename (or a list of filenames) for the special route configuration for that
+connection. You will use that name to call masqmail with the
+ <opt>-qo</opt> option every time a connection to your ISP is set
+up.</p>
+
+<p>Example: Your ISP has the name <i>FastNet</i>. Then you write the
+following line in the main configuration:</p>
+
+<p><opt>online_routes.FastNet</opt> = <arg>"/etc/masqmail/fastnet.route"</arg></p>
+
+<p><file>/etc/masqmail/fastnet.route</file> is the route configuration
+file, see <manref name="masqmail.route" section="5" href="masqmail.route.5.html"/>. As soon as a link to FastNet has been set up, you
+call masqmail <opt>-qo</opt> <arg>FastNet</arg>. Masqmail will then
+read the specified file and send the mails.</p>
+
+</optdesc>
+</option>
+
+<option>
+<p><opt>connect_route.<arg>name</arg> = <arg>list</arg></opt></p>
+<optdesc>
+<p>Old name for <opt>online_routes</opt>.</p>
+</optdesc>
+</option>
+
+
+<option>
+<p><opt>local_net_route = <arg>file</arg></opt></p>
+<optdesc>
+<p>This is similar to <opt>online_routes.<arg>name</arg></opt> but for the
+local net. Recipient addresses that are in <b>local_nets</b> will be
+routed using this route configuration. Main purpose is to define a
+mail server with <b>mail_host</b> in your local network. In simple
+environments this can be left unset. If unset, a default route
+configuration will be used.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>alias_file = <arg>file</arg></opt></p>
+<optdesc>
+<p>Set this to the location of your alias file. If unset, no aliasing
+will be done.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>alias_local_caseless = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set, local parts in the alias file will be matched
+disregarding upper/lower case.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>pipe_fromline = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set, a from line will be prepended to the output stream whenever
+a pipe command is called after an alias expansion. Default is false.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>pipe_fromhack = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set, each line beginning with 'From ' is replaced with '>From ' whenever
+a pipe command is called after an alias expansion. You probably want this if you have
+set <opt>pipe_fromline</opt> above. Default is false.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>mbox_default = <arg>string</arg></opt></p>
+<optdesc>
+<p>The default local delivery method. Can be one of mbox, mda or
+maildir (the latter only if maildir support is enabled at compile
+time). Default is mbox. You can override this for each user by using
+the <opt>mbox_users</opt>, <opt>mda_users</opt> or <opt>maildir_users</opt> options
+(see below).
+</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>mbox_users = <arg>list</arg></opt></p>
+<optdesc>
+<p>A list of users which wish delivery to an mbox style mail folder.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>mda_users = <arg>list</arg></opt></p>
+<optdesc>
+<p>A list of users which wish local delivery to an mda. You have to
+set <opt>mda</opt> (see below) as well.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>maildir_users = <arg>list</arg></opt></p>
+<optdesc>
+<p>A list of users which wish delivery to a qmail style maildir. The
+path to maildir is ~/Maildir/. The maildir will be created if it
+does not exist.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>mda = <arg>expand string</arg></opt></p>
+<optdesc>
+<p>If you want local delivery to be transferred to an mda (Mail
+Delivery Agent), set this to a command. The argument will be expanded
+on delivery time, you can use variables beginning with a '$' sign,
+optionally enclosed in curly braces. Variables you can use are:</p>
+<p>uid - the unique message id. This is not necessarily identical with
+the Message ID as given in the Message ID: header.</p>
+<p>received_host - the host the mail was received from</p>
+<p>ident - the ident, this is either the ident delivered by the ident
+protocol or the user id of the sender if the message was received locally.</p>
+<p>return_path_local - the local part of the return path (sender).</p>
+<p>return_path_domain - the domain part of the return path (sender).</p>
+<p>return_path - the complete return path (sender).</p>
+<p>rcpt_local - the local part of the recipient.</p>
+<p>rcpt_domain - the domain part of the recipient.</p>
+<p>rcpt - the complete recipient address.</p>
+<p>Example:</p><p>mda="/usr/bin/procmail -Y -d ${rcpt_local}"</p>
+<p>For the mda, as for pipe commands, a few environment variables will
+be set as well. See <manref name="masqmail" section="8"
+href="masqmail.8.html"/>. To use environment variables for the mda,
+the '$' sign has to be escaped with a backslash, otherwise they will
+be tried to be expanded with the internal variables.</p>
+
+</optdesc>
+</option>
+
+<option>
+<p><opt>mda_fromline = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set, a from line will be prepended to the output stream whenever
+a message is delivered to an mda. Default is false.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>mda_fromhack = <arg>boolean</arg></opt></p>
+<optdesc>
+<p>If this is set, each line beginning with 'From ' is replaced with '>From ' whenever
+a message is delivered to an mda. You probably want this if you have
+set <opt>mda_fromline</opt> above. Default is false.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>online_detect = <arg>string</arg></opt></p>
+<optdesc>
+<p>Defines the method MasqMail uses to detect whether there is
+currently an online connection. It can have the
+values <opt>file</opt>, <opt>pipe</opt> or <opt>mserver</opt>.</p>
+
+<p>When it is set to <opt>file</opt>, MasqMail first checks for the
+existence of <opt>online_file</opt> (see below) and if it exists, it reads
+it. The content of the file should be the name of the current
+connection as defined with <opt>connect_route.<arg>name</arg></opt> (without
+a trailing newline character).</p>
+
+<p>When it is set to <opt>pipe</opt>, MasqMail calls the executable given by
+the <opt>online_pipe</opt> option (see below) and reads the current online
+status from its standard output.</p>
+
+<p>When it is set to <opt>mserver</opt>, MasqMail connects to the
+masqdialer server using the value of <opt>mserver_iface</opt> and asks it
+whether a connection exists and for the name, which should be the name
+of the current connection as defined with <opt>connect_route.<arg>name</arg></opt>.</p>
+
+<p>No matter how MasqMail detects the online status, only messages
+that are accepted at online time will be delivered using the
+connection. The spool still has to be emptied with masqmail <opt>-qo</opt>
+<arg>connection</arg>.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>online_file = <arg>file</arg></opt></p>
+<optdesc>
+<p>This is the name of the file checked for when MasqMail determines
+whether it is online. The file should only exist when there is
+currently a connection. Create it in your ip-up script with eg.</p>
+
+<p>echo -n &lt;name&gt; &gt; /tmp/connect_route</p>
+<p>chmod 0644 /tmp/connect_route</p>
+
+<p>Do not forget to delete it in your ip-down script.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>online_pipe = <arg>file</arg></opt></p>
+<optdesc>
+<p>This is the name of the executable which will be called to determine
+the online status. This executable should just print the name oif the current
+connection to the standard output and return a zero status code. masqmail assumes
+it is offline if the script returns with a non zero status. Simple example:</p>
+
+<p>#!/bin/sh</p>
+<p></p>
+<p>[ -e /tmp/connect_route ] || exit 1</p>
+<p>cat /tmp/connect_route</p>
+<p>exit 0</p>
+
+<p>Of course, instead of the example above you could as well use <opt>file</opt> as
+the online detection method, but you can do something more sophisticated.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>mserver_iface = <arg>interface</arg></opt></p>
+<optdesc>
+<p>The interface the masqdialer server is listening to. Usually this
+will be "localhost:224" if mserver is running on the same host as
+masqmail. But using this option, you can also let masqmail run on
+another host by setting <opt>mserver_iface</opt> to another hostname,
+eg. "foo:224".</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>get.<arg>name</arg> = <arg>file</arg></opt></p>
+<optdesc>
+<p>Replace <arg>name</arg> with a name to identify a get
+configuration. Set this to a filename for the get configuration. These
+files will be used to retrieve mail when called with the -g option.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>online_gets.<arg>name</arg> = <arg>list</arg></opt></p>
+<optdesc>
+<p>Replace <arg>name</arg> with a name to identify an online
+configuration. Set this to a filename (or a list of filenames) for the get configuration. These
+files will be used to retrieve mail when called with the -go option.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>ident_trusted_nets = <arg>list</arg></opt></p>
+<optdesc>
+<p><arg>list</arg> is a list of networks of the form a.b.c.d/e
+(eg. 192.168.1.0/24), from which the ident given by the ident protocol
+will be trusted, so a user can delete his mail from the queue if the
+ident is identical to his login name.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>errmsg_file = <arg>file</arg></opt></p>
+<optdesc>
+<p>Set this to a template which will be used to generate delivery failure
+reports. Variable parts within the template begin with a dollar sign and
+are identical to those which can be used as arguments for the mda command,
+see <opt>mda</opt> above. Additional information can be included with
+@failed_rcpts, @msg_headers and @msg_body, these <b>must</b> be at the
+beginning of a line and will be replaced with the list of the failed recipients,
+the message headers and the message body of the failed message.</p>
+<p>Default is /usr/share/masqmail/tpl/failmsg.tpl.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>warnmsg_file = <arg>file</arg></opt></p>
+<optdesc>
+<p>Set this to a template which will be used to generate delivery warning
+reports. It uses the same mechanisms for variables as <opt>errmsg_file</opt>,
+see above.
+</p>
+<p>Default is /usr/share/masqmail/tpl/warnmsg.tpl.</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>warn_intervals</opt> = <arg>list</arg></p>
+<optdesc>
+<p>Set this to a list of time intervals, at which delivery warnings (starting
+with the receiving time of the message) shall be generated.</p>
+<p>A warning will only be generated just after an attempt to deliver the
+mail and if that attempt failed temporarily. So a warning may be generated after
+a longer time, if there was no attempt before.</p>
+<p>Default is "1h;4h;8h;1d;2d;3d"</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>max_defer_time</opt> = <arg>time</arg></p>
+<optdesc>
+<p>This is the maximum time, in which a temporarily failed mail will be kept
+in the spool. When this time is exceeded, it will be handled as a delivery failure,
+and the message will be bounced.</p>
+<p>The excedence of this time will only be noticed if the message was actually
+tried to be delivered. If, for example, the message can only be delivered when
+online, but you have not been online for that time, no bounce will be generated.</p>
+<p>Default is 4d (4 days)</p>
+</optdesc>
+</option>
+
+<option>
+<p><opt>log_user = <arg>name</arg></opt></p>
+<optdesc>
+<p>Replace <arg>name</arg> with a valid local or remote mail address.</p>
+<p>If this option is not empty, then a copy of every mail,
+that passes trough the masqmail system will also be sent to the
+given mail address.</p>
+<p>For example you can feed your mails into a program like <i>hypermail</i> for
+archiving purpose by placing an appropriate pipe command in masqmail.alias</p>
+</optdesc>
+</option>
+
+</options>
+
+<section name = "Author">
+<p>masqmail was written by Oliver Kurth
+&lt;oku@masqmail.cx&gt;</p><p>You will find the newest version of
+masqmail at <url href="http://masqmail.cx/masqmail/"/> or search for it
+in freshmeat (<url href="http://www.freshmeat.net"/>). There is also a mailing list,
+you will find information about it at masqmails main site.</p>
+</section>
+
+<section name = "Bugs">
+<p>You should report them to the mailing list.</p>
+</section>
+
+<section name = "See also">
+<p>
+<manref name="masqmail" section="8" href="masqmail.8.html"/>, <manref name="masqmail.route" section="5" href="masqmail.route.5.html"/>, <manref name="masqmail.get" section="5" href="masqmail.get.5.html"/>
+</p>
+</section>
+
+
+<section name = "Comments">
+<p>This man page was written using <manref name="xml2man" section="1"
+href="http://masqmail.cx/xml2man/"/> by the same
+author.</p>
+</section>
+
+</manpage>
+