meillo@228: .TH masqmail.conf 5 2010-07-23 masqmail-0.3.0 "File Formats" meillo@34: meillo@0: .SH NAME meillo@0: masqmail.conf \- masqmail configuration file meillo@34: meillo@34: meillo@0: .SH DESCRIPTION meillo@0: meillo@34: This man page describes the syntax of the main configuration file of masqmail. meillo@34: Its usual location is \fI/etc/masqmail/masqmail.conf\fR meillo@0: meillo@0: The configuration consists of lines of the form meillo@0: meillo@34: \fBval\fR = \fIexpression\fR meillo@0: meillo@34: Where \fBval\fR is a variable name and \fIexpression\fR a string, meillo@34: which can be quoted with double quotes `"'. meillo@34: If the expression is on multiple lines or contains characters other than letters, meillo@174: digits or the characters `.', `-', `_', `/', ';', '@', ':', it must be quoted. meillo@34: You can use quotes inside quotes by escaping them with a backslash. meillo@0: meillo@174: Each \fBval\fP has a type, which can be boolean, numeric, string or list. meillo@34: A boolean variable can be set with one of the values `on', `yes', and `true' or `off', `no' and `false'. meillo@34: List items are separated with semicolons `;'. meillo@174: For some values, patterns (like `*',`?') can be used. meillo@174: The spaces in front of and after the equal sign `=' are optional. meillo@0: meillo@34: Most lists (exceptions: \fBlocal_hosts\fR, \fBlocal_nets\fR, \fBlisten_addresses\fR, meillo@192: and \fBonline_routes\fR) accept files. meillo@34: These will be recognized by a leading slash `/'. meillo@34: The contents of these files will be included at the position of the file name, meillo@34: there can be items or other files before and after the file entry. meillo@174: The format of the files is different though, within these files each entry is on another line meillo@174: and the entries are not separated by semicolons. meillo@34: This makes it easy to include large lists which are common in different configuration files, meillo@34: so they do not have to appear in every configuration file. meillo@0: meillo@34: Blank lines and lines starting with a hash `#' are ignored. meillo@34: meillo@0: meillo@0: .SH OPTIONS meillo@34: meillo@0: .TP meillo@34: \fBrun_as_user = \fIboolean\fR meillo@0: meillo@34: If this is set, masqmail runs with the user id of the user who invoked it and never changes it. meillo@34: This is for debugging purposes only. meillo@34: If the user is not root, masqmail will not be able to listen on a port < 1024 meillo@34: and will not be able to deliver local mail to others than the user. meillo@0: meillo@0: .TP meillo@34: \fBuse_syslog = \fIboolean\fR meillo@0: meillo@34: If this is set, masqmail uses syslogd for logging. meillo@34: It uses facility MAIL. meillo@34: You still have to set \fBlog_dir\fR for debug files. meillo@0: meillo@0: .TP meillo@34: \fBdebug_level = \fIn\fR meillo@0: meillo@34: Set the debug level. meillo@34: Valid values are 0 to 6, increasing it further makes no difference. meillo@34: Be careful if you set this as high as 5 or higher, the logs may very soon fill your hard drive. meillo@0: meillo@0: .TP meillo@44: \fBlog_dir = \fIfile\fR meillo@44: meillo@174: The directory where logs are stored, if syslog is not used. meillo@174: Debug files are always stored in this directory if debugging is enabled. meillo@44: \fIfile\fR must be an absolute path. meillo@44: meillo@151: Default: \fI/var/log/masqmail\fR meillo@151: meillo@44: .TP meillo@34: \fBmail_dir = \fIfile\fR meillo@0: meillo@34: The directory where local mail is stored, usually \fI/var/spool/mail\fR or \fI/var/mail\fR. meillo@44: \fIfile\fR must be an absolute path. meillo@0: meillo@152: Default: \fI/var/mail\fR meillo@152: meillo@0: .TP meillo@34: \fBspool_dir = \fIfile\fR meillo@0: meillo@34: The directory where masqmail stores its spool files (and later also other stuff). meillo@34: It must have a subdirectory \fIinput\fR. meillo@34: Masqmail needs read and write permissions for this directory. meillo@44: \fIfile\fR must be an absolute path. meillo@0: meillo@151: Default: \fI/var/spool/masqmail\fR meillo@151: meillo@0: .TP meillo@133: \fBlock_dir = \fIfile\fR meillo@133: meillo@133: The directory where masqmail stores its lock files. meillo@133: Masqmail needs read and write permissions for this directory. meillo@133: By default it is a directory ``lock'' inside of \fIspool_dir\fP. meillo@133: \fIfile\fR must be an absolute path. meillo@133: meillo@133: .TP meillo@34: \fBhost_name = \fIstring\fR meillo@0: meillo@34: This is used in different places: Masqmail identifies itself in the greeting banner meillo@34: on incoming connections and in the HELO/EHLO command for outgoing connections with this name, meillo@34: it is used in the Received: header and to qualify the sender of a locally originating message. meillo@0: meillo@34: If the string begins with a slash `/', it it assumed that it is a filename, meillo@34: and the first line of this file will be used. meillo@34: Usually this will be `/etc/mailname' to make masqmail conform to Debian policies. meillo@0: meillo@34: It is not used to find whether an address is local. Use \fBlocal_hosts\fR for that. meillo@0: meillo@156: Default: none; \fBhost_name\fP MUST be set in the config file meillo@156: meillo@0: .TP meillo@34: \fBlocal_hosts = \fIlist\fR meillo@0: meillo@34: A semicolon `;' separated list of hostnames which are considered local. meillo@153: Normally you should set it to "localhost;foo;foo.bar.com" if your host has the meillo@34: fully qualified domain name `foo.bar.com'. meillo@0: meillo@157: Default: localhost ; ; meillo@157: meillo@157: Example: \fIlocalhost;foo;foo.example.org\fR meillo@157: (if you have set \fBhost_name\fR to \fIfoo.example.org\fR) meillo@153: meillo@0: .TP meillo@34: \fBlocal_addresses = \fIlist\fR meillo@0: meillo@34: A semicolon `;' separated list of fully qualified email-addresses which are meillo@34: considered local although their domain name part is not in the list of \fBlocal_hosts\fR. meillo@238: This list can be seen as an addition to \fBlocal_hosts\fP. meillo@0: meillo@34: For example: There are two people working at your LAN: person1@yourdomain and person2@yourdomain. meillo@34: But there are other persons @yourdomain which are NOT local. meillo@34: So you can not put yourdomain to the list of local_hosts. meillo@34: If person1 now wants to write to person2@yourdomain and this mail should not leave the LAN then you can put meillo@0: meillo@0: local_addresses = "person1@yourdomain;person2@yourdomain" meillo@0: meillo@0: to your masqmail.conf. meillo@34: meillo@0: .TP meillo@34: \fBnot_local_addresses = \fIlist\fR meillo@0: meillo@34: A semicolon `;' separated list of fully qualified email-addresses which are meillo@34: considered not local although their domain name part is in the list of \fBlocal_hosts\fR. meillo@238: This list can be seen as a substraction to \fBlocal_hosts\fP. meillo@0: meillo@34: This is the opposite of the previous case. meillo@34: The majority of addresses of a specific domain are local. meillo@34: But some users are not. meillo@34: With this option you can easily exclude these users. meillo@0: meillo@0: Example: meillo@0: meillo@0: local_hosts = "localhost;myhost;mydomain.net" meillo@0: meillo@0: not_local_addresses = "eric@mydomain.net" meillo@34: meillo@0: .TP meillo@238: \fBlocal_nets = \fIlist\fR meillo@238: meillo@238: A semicolon `;' separated list of hostnames which are on the `local' net. meillo@238: Delivery to these hosts is attempted immediately. meillo@238: You can use patterns with `*', e.g. "*.bar.com". meillo@238: meillo@238: .TP meillo@34: \fBlisten_addresses = \fIlist\fR meillo@0: meillo@34: A semicolon `;' separated list of interfaces on which connections will be accepted. meillo@34: An interface ist defined by a hostname, optionally followed by a colon `:' and a number for the port. meillo@34: If this is left out, port 25 will be used. meillo@0: meillo@34: You can set this to "localhost:25;foo:25" if your hostname is `foo'. meillo@0: meillo@34: Note that the names are resolved to IP addreses. meillo@34: If your host has different names which resolve to the same IP, meillo@34: use only one of them, otherwise you will get an error message. meillo@0: meillo@206: Default: \fI127.0.0.1:25\fR (i.e. only local processes can connect) meillo@161: meillo@0: .TP meillo@34: \fBdo_save_envelope_to = \fIboolean\fR meillo@0: meillo@34: If this is set to true, a possibly existing Envelope-to: header in an incoming mail meillo@34: which is received via either pop3 or smtp will be saved as an X-Orig-Envelope-to: header. meillo@0: meillo@192: This is useful if you retrieve mail from a pop3 server with fetchmail, meillo@34: and the server supports Envelope-to: headers, meillo@34: and you want to make use of those with a mail filtering tool, e.g. procmail. meillo@34: It cannot be preserved because masqmail sets such a header by itself. meillo@0: meillo@0: Default is false. meillo@34: meillo@0: .TP meillo@34: \fBdo_relay = \fIboolean\fR meillo@0: meillo@34: If this is set to false, mail with a return path that is not local and a destination meillo@34: that is also not local will not be accepted via smtp and a 550 reply will be given. meillo@34: Default is true. meillo@0: meillo@34: Note that this will not protect you from spammers using open relays, meillo@34: but from users unable to set their address in their mail clients. meillo@0: meillo@0: .TP meillo@34: \fBdo_queue = \fIboolean\fR meillo@0: meillo@34: If this is set, mail will not be delivered immediately when accepted. meillo@34: Same as calling masqmail with the \fB\-odq\fR option. meillo@0: meillo@0: .TP meillo@34: \fBonline_routes.\fIname\fR = \fIlist\fR meillo@0: meillo@34: Replace \fIname\fR with a name to identify a connection. meillo@34: Set this to a filename (or a list of filenames) for the special route configuration for that connection. meillo@34: You will use that name to call masqmail with the \fB\-qo\fR option every time a meillo@34: connection to your ISP is set up. meillo@0: meillo@34: Example: Your ISP has the name FastNet. meillo@34: Then you write the following line in the main configuration: meillo@0: meillo@139: \fBonline_routes.FastNet\fR = \fI"/etc/masqmail/fastnet.route"\fR meillo@0: meillo@34: \fI/etc/masqmail/fastnet.route\fR is the route configuration file, see \fBmasqmail.route(5)\fR. meillo@34: As soon as a link to FastNet has been set up, you call masqmail \fB\-qo \fIFastNet\fR. meillo@34: Masqmail will then read the specified file and send the mails. meillo@0: meillo@0: .TP meillo@34: \fBconnect_route.\fIname\fR = \fIlist\fR meillo@0: meillo@34: Old name for \fBonline_routes\fR. meillo@0: meillo@0: .TP meillo@34: \fBlocal_net_route = \fIfile\fR meillo@0: meillo@234: This is similar to \fBonline_routes.\fIname\fR but used for delilvery to the local net. meillo@34: Recipient addresses that are in local_nets will be routed using this route configuration. meillo@34: Main purpose is to define a mail server with mail_host in your local network. meillo@34: In simple environments this can be left unset. meillo@234: If unset, a default route configuration (named ``default local_net_route'') will be used. meillo@0: meillo@0: .TP meillo@34: \fBalias_file = \fIfile\fR meillo@0: meillo@34: Set this to the location of your alias file. meillo@238: If not set, no aliasing will be done. meillo@238: meillo@238: Default: (i.e. no aliasing is done) meillo@0: meillo@0: .TP meillo@34: \fBalias_local_caseless = \fIboolean\fR meillo@0: meillo@242: If this is set, aliasing and the matching for \fBlocal_addresses\fP and meillo@242: \fBnot_local_addresses\fP will be done caseless. meillo@242: meillo@242: Note: Be sure to change this option only if the queue is empty as meillo@242: correct processing of queued messages is not guaranteed otherwise. meillo@34: meillo@238: Default: false meillo@238: meillo@0: .TP meillo@34: \fBpipe_fromline = \fIboolean\fR meillo@0: meillo@34: If this is set, a from line will be prepended to the output stream whenever meillo@34: a pipe command is called after an alias expansion. meillo@34: Default is false. meillo@0: meillo@0: .TP meillo@34: \fBpipe_fromhack = \fIboolean\fR meillo@0: meillo@34: If this is set, each line beginning with `From ' is replaced with `>From ' meillo@34: whenever a pipe command is called after an alias expansion. meillo@34: You probably want this if you have set \fBpipe_fromline\fR above. meillo@34: Default is false. meillo@0: meillo@0: .TP meillo@34: \fBmbox_default = \fIstring\fR meillo@0: meillo@34: The default local delivery method. meillo@205: Can be mbox or mda. meillo@205: You can override this for each user by using the \fBmbox_users\fR or \fBmda_users\fR (see below). meillo@0: meillo@238: Default: mbox. meillo@238: meillo@0: .TP meillo@34: \fBmbox_users = \fIlist\fR meillo@0: meillo@0: A list of users which wish delivery to an mbox style mail folder. meillo@34: meillo@0: .TP meillo@34: \fBmda_users = \fIlist\fR meillo@0: meillo@34: A list of users which wish local delivery to an mda. meillo@34: You have to set \fBmda\fR (see below) as well. meillo@0: meillo@0: .TP meillo@34: \fBmda = \fIexpand string\fR meillo@0: meillo@34: If you want local delivery to be transferred to an mda (Mail Delivery Agent), meillo@34: set this to a command. meillo@34: The argument will be expanded on delivery time, meillo@34: you can use variables beginning with a dolloar sign `$', optionally enclosed in curly braces. meillo@34: Variables you can use are: meillo@0: meillo@34: uid - the unique message id. meillo@34: This is not necessarily identical with the Message ID as given in the Message ID: header. meillo@0: meillo@0: received_host - the host the mail was received from meillo@0: meillo@34: ident - the ident, this is either the ident delivered by the ident protocol meillo@34: or the user id of the sender if the message was received locally. meillo@0: meillo@0: return_path_local - the local part of the return path (sender). meillo@0: meillo@0: return_path_domain - the domain part of the return path (sender). meillo@0: meillo@0: return_path - the complete return path (sender). meillo@0: meillo@0: rcpt_local - the local part of the recipient. meillo@0: meillo@0: rcpt_domain - the domain part of the recipient. meillo@0: meillo@0: rcpt - the complete recipient address. meillo@0: meillo@0: Example: meillo@0: meillo@16: mda="/usr/bin/procmail \-Y \-d ${rcpt_local}" meillo@0: meillo@34: For the mda, as for pipe commands, a few environment variables will be set as well. meillo@34: See \fBmasqmail(8)\fR. meillo@34: To use environment variables for the mda, the dollar sign `$' has to be escaped with a backslash, meillo@34: otherwise they will be tried to be expanded with the internal variables. meillo@34: meillo@0: .TP meillo@34: \fBmda_fromline = \fIboolean\fR meillo@0: meillo@34: If this is set, a from line will be prepended to the output stream whenever meillo@34: a message is delivered to an mda. meillo@34: Default is false. meillo@0: meillo@0: .TP meillo@34: \fBmda_fromhack = \fIboolean\fR meillo@0: meillo@34: If this is set, each line beginning with `From ' is replaced with `>From ' meillo@34: whenever a message is delivered to an mda. meillo@34: You probably want this if you have set \fBmda_fromline\fR above. meillo@34: Default is false. meillo@0: meillo@0: .TP meillo@34: \fBonline_detect = \fIstring\fR meillo@0: meillo@34: Defines the method masqmail uses to detect whether there is currently an online connection. meillo@164: It can have the values \fIfile\fR or \fIpipe\fR. meillo@0: meillo@112: When it is set to \fIfile\fR, masqmail first checks for the existence of \fBonline_file\fR meillo@34: (see below) and if it exists, it reads it. meillo@34: The content of the file should be the name of the current connection as defined meillo@34: with \fBconnect_route.\fIname\fR (trailing whitespace is removed). meillo@0: meillo@112: When it is set to \fIpipe\fR, masqmail calls the executable given by the meillo@34: \fBonline_pipe\fR option (see below) and reads the current online status from its standard output. meillo@0: meillo@34: No matter how masqmail detects the online status, meillo@34: only messages that are accepted at online time will be delivered using the connection. meillo@34: The spool still has to be emptied with masqmail \fB\-qo\fIconnection\fR. meillo@0: meillo@0: .TP meillo@34: \fBonline_file = \fIfile\fR meillo@0: meillo@34: This is the name of the file checked for when masqmail determines whether it is online. meillo@34: The file should only exist when there is currently a connection. meillo@34: Create it in your ip-up script with e.g. meillo@0: meillo@92: echo "connection-name" >/var/run/masqmail/masqmail-route meillo@0: meillo@37: chmod 0644 /var/run/masqmail/masqmail-route meillo@0: meillo@0: Do not forget to delete it in your ip-down script. meillo@34: meillo@0: .TP meillo@34: \fBonline_pipe = \fIfile\fR meillo@0: meillo@34: This is the name of the executable which will be called to determine the online status. meillo@34: This executable should just print the name of the current connection to meillo@34: the standard output and return a zero status code. meillo@34: masqmail assumes it is offline if the script returns with a non zero status. meillo@34: Simple example: meillo@0: meillo@0: #!/bin/sh meillo@0: meillo@37: [ \-e /var/run/masqmail/masqmail-route ] || exit 1 meillo@0: meillo@37: cat /var/run/masqmail/masqmail-route meillo@0: meillo@0: exit 0 meillo@0: meillo@129: Of course, instead of the example above you could as well use \fIfile\fR as meillo@34: the online detection method, but you can do something more sophisticated. meillo@34: meillo@158: \fIfile\fR must contain an absolute path to an executable program. meillo@158: It can contain optional arguments. meillo@0: meillo@158: Example: \fI/bin/echo foo\fR meillo@158: (This tells masqmail to be always online with connection `foo'.) meillo@158: meillo@164: For querying a masqdialer server meillo@164: (= asking it whether a connection exists and what its name is) meillo@164: use: meillo@92: meillo@92: online_method=pipe meillo@92: meillo@164: online_pipe="/usr/bin/mservdetect localhost 224" meillo@92: meillo@0: meillo@0: .TP meillo@34: \fBident_trusted_nets = \fIlist\fR meillo@0: meillo@34: \fIlist\fR is a list of networks of the form a.b.c.d/e (e.g. 192.168.1.0/24), meillo@34: from which the ident given by the ident protocol will be trusted, meillo@34: so a user can delete his mail from the queue if the ident is identical to his login name. meillo@0: meillo@0: .TP meillo@34: \fBerrmsg_file = \fIfile\fR meillo@0: meillo@34: Set this to a template which will be used to generate delivery failure reports. meillo@34: Variable parts within the template begin with a dollar sign and are identical meillo@34: to those which can be used as arguments for the mda command, see \fBmda\fR above. meillo@34: Additional information can be included with @failed_rcpts, @msg_headers and @msg_body, meillo@34: these must be at the beginning of a line and will be replaced with the list of the failed recipients, meillo@34: the message headers and the message body of the failed message. meillo@0: meillo@0: Default is /usr/share/masqmail/tpl/failmsg.tpl. meillo@34: meillo@0: .TP meillo@34: \fBwarnmsg_file = \fIfile\fR meillo@0: meillo@34: Set this to a template which will be used to generate delivery warning reports. meillo@34: It uses the same mechanisms for variables as \fBerrmsg_file\fR, see above. meillo@0: meillo@0: Default is /usr/share/masqmail/tpl/warnmsg.tpl. meillo@34: meillo@0: .TP meillo@34: \fBwarn_intervals\fR = \fIlist\fR meillo@0: meillo@34: Set this to a list of time intervals, at which delivery warnings meillo@34: (starting with the receiving time of the message) shall be generated. meillo@0: meillo@34: A warning will only be generated just after an attempt to deliver the mail meillo@34: and if that attempt failed temporarily. meillo@34: So a warning may be generated after a longer time, if there was no attempt before. meillo@0: meillo@0: Default is "1h;4h;8h;1d;2d;3d" meillo@34: meillo@0: .TP meillo@34: \fBmax_defer_time\fR = \fItime\fR meillo@0: meillo@34: This is the maximum time, in which a temporarily failed mail will be kept in the spool. meillo@34: When this time is exceeded, it will be handled as a delivery failure, meillo@34: and the message will be bounced. meillo@0: meillo@34: The excedence of this time will only be noticed if the message was actually tried to be delivered. meillo@34: If, for example, the message can only be delivered when online, meillo@34: but you have not been online for that time, no bounce will be generated. meillo@0: meillo@0: Default is 4d (4 days) meillo@34: meillo@0: .TP meillo@34: \fBlog_user = \fIname\fR meillo@0: meillo@34: Replace \fIname\fR with a valid local or remote mail address. meillo@0: meillo@44: If this option is set, then a copy of every mail, meillo@44: that passes through the masqmail system will also be sent to the given mail address. meillo@0: meillo@34: For example you can feed your mails into a program like hypermail meillo@34: for archiving purpose by placing an appropriate pipe command in masqmail.alias meillo@0: meillo@117: .TP meillo@117: \fBmax_msg_size\fR = \fIbytes\fR meillo@117: meillo@117: This option sets the maximum size in bytes masqmail will accept for delivery. meillo@117: This value is advertised to the SMTP client by the `SIZE' message during SMTP meillo@117: session setup. meillo@117: Clients pretending to send, or actually send, meillo@117: more than \fIbytes\fR will get a 552 error message. meillo@117: meillo@120: `0' means no fixed maximum size limit is in force. meillo@120: meillo@120: Default is 0 (= unlimited). meillo@117: meillo@134: .TP meillo@134: \fBdefer_all\fR = \fIboolean\fR meillo@134: meillo@134: If set to true, masqmail replies with ``421 service temporarily unavailable'' meillo@134: to any SMTP request and shuts the connection down. meillo@134: Note: This option is for debugging purposes only. meillo@134: meillo@134: Default: false meillo@134: meillo@34: meillo@0: .SH AUTHOR meillo@0: meillo@34: Masqmail was written by Oliver Kurth. meillo@34: It is now maintained by Markus Schnalke . meillo@0: meillo@95: You will find the newest version of masqmail at \fBhttp://marmaro.de/prog/masqmail/\fR. meillo@26: There is also a mailing list, you will find information about it at masqmail's main site. meillo@0: meillo@34: meillo@0: .SH BUGS meillo@0: meillo@34: Please report bugs to the mailing list. meillo@34: meillo@0: meillo@0: .SH SEE ALSO meillo@0: meillo@192: \fBmasqmail(8)\fR, \fBmasqmail.route(5)\fR