meillo@56: meillo@56:

masqmail.conf

meillo@56:

masqmail configuration file

meillo@56: meillo@56: meillo@56:

Description

meillo@56: meillo@56:

This man page describes the syntax of the main configuration file meillo@56: of masqmail. Its usual location is /etc/masqmail/masqmail.conf

meillo@56: meillo@56:

The configuration consists of lines of the form

meillo@56: meillo@56:

val = expression

meillo@56: meillo@56:

Where val is a variable name and expression 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.

meillo@56: meillo@56:

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.

meillo@56: meillo@56:

Most lists (exceptions: local_hosts, meillo@56: local_nets, listen_addresses, online_routes and online_gets) 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.

meillo@56: meillo@56:

Blank lines and lines starting with '#' are ignored.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

Options

meillo@56: meillo@56: meillo@56:

run_as_user = boolean

meillo@56: meillo@56:

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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

use_syslog = boolean

meillo@56: meillo@56:

If this is set, masqmail uses syslogd for logging. It uses facility meillo@56: MAIL. You still have to set log_dir for debug files.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

debug_level = n

meillo@56: meillo@56:

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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

mail_dir = file

meillo@56: meillo@56:

The directory where local mail is stored, meillo@56: usually /var/spool/mail or /var/mail.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

spool_dir = file

meillo@56: meillo@56:

The directory where masqmail stores its spool files (and later also meillo@56: other stuff). It must have a subdirectory input. meillo@56: Masqmail needs read and write permissions for this meillo@56: directory. I suggest to use /var/spool/masqmail.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

host_name = string

meillo@56: meillo@56:

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.

meillo@56: meillo@56:

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.

meillo@56: meillo@56:

It is not used to find whether an address is local. meillo@56: Use local_hosts for that.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

remote_port = n

meillo@56: meillo@56:

The remote port number to be used. This defaults to port 25.

meillo@56:

This option is deprecated. Use host_name in the route meillo@56: configuration instead. See masqmail.route.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

local_hosts = list

meillo@56: meillo@56:

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'.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

local_nets = list

meillo@56: meillo@56:

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".

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

local_addresses = list

meillo@56: meillo@56:

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 local_hosts.

meillo@56:

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

meillo@56:

local_addresses = "person1@yourdomain;person2@yourdomain"

meillo@56:

to your masqmail.conf.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

not_local_addresses = list

meillo@56: meillo@56:

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 local_hosts.

meillo@56:

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.

meillo@56:

Example:

meillo@56:

local_hosts = "localhost;myhost;mydomain.net"

meillo@56:

not_local_addresses = "eric@mydomain.net"

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

listen_addresses = list

meillo@56: meillo@56:

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.

meillo@56:

You can set this to "localhost:25;foo:25" if your hostname is 'foo'.

meillo@56:

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:

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

do_save_envelope_to = boolean

meillo@56: meillo@56:

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.

meillo@56:

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.

meillo@56:

Default is false.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

do_relay = boolean

meillo@56: meillo@56:

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.

meillo@56:

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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

do_queue = boolean

meillo@56: meillo@56:

If this is set, mail will not be delivered immediately when meillo@56: accepted. Same as calling masqmail with the -odq option.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

online_routes.name = list

meillo@56: meillo@56: meillo@56:

Replace name 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: -qo option every time a connection to your ISP is set meillo@56: up.

meillo@56: meillo@56:

Example: Your ISP has the name FastNet. Then you write the meillo@56: following line in the main configuration:

meillo@56: meillo@56:

online_routes.FastNet = "/etc/masqmail/fastnet.route"

meillo@56: meillo@56:

/etc/masqmail/fastnet.route is the route configuration meillo@56: file, see masqmail.route. As soon as a link to FastNet has been set up, you meillo@56: call masqmail -qo FastNet. Masqmail will then meillo@56: read the specified file and send the mails.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

connect_route.name = list

meillo@56: meillo@56:

Old name for online_routes.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

local_net_route = file

meillo@56: meillo@56:

This is similar to online_routes.name 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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

alias_file = file

meillo@56: meillo@56:

Set this to the location of your alias file. If unset, no aliasing meillo@56: will be done.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

alias_local_caseless = boolean

meillo@56: meillo@56:

If this is set, local parts in the alias file will be matched meillo@56: disregarding upper/lower case.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

pipe_fromline = boolean

meillo@56: meillo@56:

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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

pipe_fromhack = boolean

meillo@56: meillo@56:

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 pipe_fromline above. Default is false.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

mbox_default = string

meillo@56: meillo@56:

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 mbox_users, mda_users or maildir_users options meillo@56: (see below). meillo@56:

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

mbox_users = list

meillo@56: meillo@56:

A list of users which wish delivery to an mbox style mail folder.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

mda_users = list

meillo@56: meillo@56:

A list of users which wish local delivery to an mda. You have to meillo@56: set mda (see below) as well.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

maildir_users = list

meillo@56: meillo@56:

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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

mda = expand string

meillo@56: meillo@56:

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:

meillo@56:

uid - the unique message id. This is not necessarily identical with meillo@56: the Message ID as given in the Message ID: header.

meillo@56:

received_host - the host the mail was received from

meillo@56:

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.

meillo@56:

return_path_local - the local part of the return path (sender).

meillo@56:

return_path_domain - the domain part of the return path (sender).

meillo@56:

return_path - the complete return path (sender).

meillo@56:

rcpt_local - the local part of the recipient.

meillo@56:

rcpt_domain - the domain part of the recipient.

meillo@56:

rcpt - the complete recipient address.

meillo@56:

Example:

mda="/usr/bin/procmail -Y -d ${rcpt_local}"

meillo@56:

For the mda, as for pipe commands, a few environment variables will meillo@56: be set as well. See masqmail. 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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

mda_fromline = boolean

meillo@56: meillo@56:

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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

mda_fromhack = boolean

meillo@56: meillo@56:

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 mda_fromline above. Default is false.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

online_detect = string

meillo@56: meillo@56:

Defines the method MasqMail uses to detect whether there is meillo@56: currently an online connection. It can have the meillo@56: values file, pipe or mserver.

meillo@56: meillo@56:

When it is set to file, MasqMail first checks for the meillo@56: existence of online_file (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 connect_route.name (without meillo@56: a trailing newline character).

meillo@56: meillo@56:

When it is set to pipe, MasqMail calls the executable given by meillo@56: the online_pipe option (see below) and reads the current online meillo@56: status from its standard output.

meillo@56: meillo@56:

When it is set to mserver, MasqMail connects to the meillo@56: masqdialer server using the value of mserver_iface 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 connect_route.name.

meillo@56: meillo@56:

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 -qo meillo@56: connection.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

online_file = file

meillo@56: meillo@56:

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.

meillo@56: meillo@56:

echo -n > /tmp/connect_route

meillo@56:

chmod 0644 /tmp/connect_route

meillo@56: meillo@56:

Do not forget to delete it in your ip-down script.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

online_pipe = file

meillo@56: meillo@56:

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:

meillo@56: meillo@56:

#!/bin/sh

meillo@56:

[ -e /tmp/connect_route ] || exit 1

meillo@56:

cat /tmp/connect_route

meillo@56:

exit 0

meillo@56: meillo@56:

Of course, instead of the example above you could as well use file as meillo@56: the online detection method, but you can do something more sophisticated.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

mserver_iface = interface

meillo@56: meillo@56:

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 mserver_iface to another hostname, meillo@56: eg. "foo:224".

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

get.name = file

meillo@56: meillo@56:

Replace name 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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

online_gets.name = list

meillo@56: meillo@56:

Replace name 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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

ident_trusted_nets = list

meillo@56: meillo@56:

list 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.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

errmsg_file = file

meillo@56: meillo@56:

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 mda 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.

meillo@56:

Default is /usr/share/masqmail/tpl/failmsg.tpl.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

warnmsg_file = file

meillo@56: meillo@56:

Set this to a template which will be used to generate delivery warning meillo@56: reports. It uses the same mechanisms for variables as errmsg_file, meillo@56: see above. meillo@56:

meillo@56:

Default is /usr/share/masqmail/tpl/warnmsg.tpl.

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

warn_intervals = list

meillo@56: meillo@56:

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.

meillo@56:

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.

meillo@56:

Default is "1h;4h;8h;1d;2d;3d"

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

max_defer_time = time

meillo@56: meillo@56:

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.

meillo@56:

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.

meillo@56:

Default is 4d (4 days)

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

log_user = name

meillo@56: meillo@56:

Replace name with a valid local or remote mail address.

meillo@56:

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.

meillo@56:

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

meillo@56: meillo@56: meillo@56: meillo@56: meillo@56: meillo@56:

Author

meillo@56: meillo@56:

masqmail was written by Oliver Kurth meillo@56:

You will find the newest version of meillo@56: masqmail at http://masqmail.cx/masqmail/ or search for it meillo@56: in freshmeat (http://www.freshmeat.net). There is also a mailing list, meillo@56: you will find information about it at masqmails main site.

meillo@56: meillo@56: meillo@56: meillo@56:

Bugs

meillo@56: meillo@56:

You should report them to the mailing list.

meillo@56: meillo@56: meillo@56: meillo@56:

Comments

meillo@56: meillo@56:

This man page was written using xml2man by the same meillo@56: author.

meillo@56: meillo@56: meillo@56: meillo@56:

meillo@56:

masqmail.conf

masqmail configuration file

Description

Options

Author

Bugs

See also

Comments