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