1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/man/masqmail.conf.5	Sat May 29 22:07:07 2010 +0200
     1.3 @@ -0,0 +1,492 @@
     1.4 +.TH masqmail.conf 5 2010-05-07 masqmail-0.2.22 "File Formats"
     1.5 +
     1.6 +.SH NAME
     1.7 +masqmail.conf \- masqmail configuration file
     1.8 +
     1.9 +
    1.10 +.SH DESCRIPTION
    1.11 +
    1.12 +This man page describes the syntax of the main configuration file of masqmail.
    1.13 +Its usual location is \fI/etc/masqmail/masqmail.conf\fR
    1.14 +
    1.15 +The configuration consists of lines of the form
    1.16 +
    1.17 +\fBval\fR = \fIexpression\fR
    1.18 +
    1.19 +Where \fBval\fR is a variable name and \fIexpression\fR a string,
    1.20 +which can be quoted with double quotes `"'.
    1.21 +If the expression is on multiple lines or contains characters other than letters,
    1.22 +digits or the characters `.', `-', `_', `/', it must be quoted.
    1.23 +You can use quotes inside quotes by escaping them with a backslash.
    1.24 +
    1.25 +Each val has a type, which can be boolean, numeric, string or list.
    1.26 +A boolean variable can be set with one of the values `on', `yes', and `true' or `off', `no' and `false'.
    1.27 +List items are separated with semicolons `;'.
    1.28 +For some values patterns (like `*',`?') can be used.
    1.29 +The spaces before and after the equal sign `=' are optional.
    1.30 +
    1.31 +Most lists (exceptions: \fBlocal_hosts\fR, \fBlocal_nets\fR, \fBlisten_addresses\fR,
    1.32 +\fBonline_routes\fR, and \fBonline_gets\fR) accept files.
    1.33 +These will be recognized by a leading slash `/'.
    1.34 +The contents of these files will be included at the position of the file name,
    1.35 +there can be items or other files before and after the file entry.
    1.36 +The format of the files is different though, within these files each entry is on another line.
    1.37 +(And not separated by semicolons).
    1.38 +This makes it easy to include large lists which are common in different configuration files,
    1.39 +so they do not have to appear in every configuration file.
    1.40 +
    1.41 +Blank lines and lines starting with a hash `#' are ignored.
    1.42 +
    1.43 +
    1.44 +.SH OPTIONS
    1.45 +
    1.46 +.TP
    1.47 +\fBrun_as_user = \fIboolean\fR
    1.48 +
    1.49 +If this is set, masqmail runs with the user id of the user who invoked it and never changes it.
    1.50 +This is for debugging purposes only.
    1.51 +If the user is not root, masqmail will not be able to listen on a port < 1024
    1.52 +and will not be able to deliver local mail to others than the user.
    1.53 +
    1.54 +.TP
    1.55 +\fBuse_syslog = \fIboolean\fR
    1.56 +
    1.57 +If this is set, masqmail uses syslogd for logging.
    1.58 +It uses facility MAIL.
    1.59 +You still have to set \fBlog_dir\fR for debug files.
    1.60 +
    1.61 +.TP
    1.62 +\fBdebug_level = \fIn\fR
    1.63 +
    1.64 +Set the debug level.
    1.65 +Valid values are 0 to 6, increasing it further makes no difference.
    1.66 +Be careful if you set this as high as 5 or higher, the logs may very soon fill your hard drive.
    1.67 +
    1.68 +.TP
    1.69 +\fBlog_dir = \fIfile\fR
    1.70 +
    1.71 +The directory where log are stored, if syslog is not used.
    1.72 +Debug files are stored in this directory anyways.
    1.73 +\fI/var/log/masqmail\fR is a common value.
    1.74 +\fIfile\fR must be an absolute path.
    1.75 +
    1.76 +.TP
    1.77 +\fBmail_dir = \fIfile\fR
    1.78 +
    1.79 +The directory where local mail is stored, usually \fI/var/spool/mail\fR or \fI/var/mail\fR.
    1.80 +\fIfile\fR must be an absolute path.
    1.81 +
    1.82 +.TP
    1.83 +\fBspool_dir = \fIfile\fR
    1.84 +
    1.85 +The directory where masqmail stores its spool files (and later also other stuff).
    1.86 +It must have a subdirectory \fIinput\fR.
    1.87 +Masqmail needs read and write permissions for this directory.
    1.88 +I suggest to use \fI/var/spool/masqmail\fR.
    1.89 +\fIfile\fR must be an absolute path.
    1.90 +
    1.91 +.TP
    1.92 +\fBhost_name = \fIstring\fR
    1.93 +
    1.94 +This is used in different places: Masqmail identifies itself in the greeting banner
    1.95 +on incoming connections and in the HELO/EHLO command for outgoing connections with this name,
    1.96 +it is used in the Received: header and to qualify the sender of a locally originating message.
    1.97 +
    1.98 +If the string begins with a slash `/', it it assumed that it is a filename,
    1.99 +and the first line of this file will be used.
   1.100 +Usually this will be `/etc/mailname' to make masqmail conform to Debian policies.
   1.101 +
   1.102 +It is not used to find whether an address is local. Use \fBlocal_hosts\fR for that.
   1.103 +
   1.104 +.TP
   1.105 +\fBremote_port = \fIn\fR
   1.106 +
   1.107 +The remote port number to be used. This defaults to port 25.
   1.108 +
   1.109 +This option is deprecated.
   1.110 +Use \fBhost_name\fR in the route configuration instead.
   1.111 +See \fBmasqmail.route(5)\fR.
   1.112 +
   1.113 +.TP
   1.114 +\fBlocal_hosts = \fIlist\fR
   1.115 +
   1.116 +A semicolon `;' separated list of hostnames which are considered local.
   1.117 +Normally you set it to "localhost;foo;foo.bar.com" if your host has the
   1.118 +fully qualified domain name `foo.bar.com'.
   1.119 +
   1.120 +.TP
   1.121 +\fBlocal_nets = \fIlist\fR
   1.122 +
   1.123 +A semicolon `;' separated list of hostnames which are on the `local' net.
   1.124 +Delivery to these hosts is attempted immediately.
   1.125 +You can use patterns with `*', e.g. "*.bar.com".
   1.126 +
   1.127 +.TP
   1.128 +\fBlocal_addresses = \fIlist\fR
   1.129 +
   1.130 +A semicolon `;' separated list of fully qualified email-addresses which are
   1.131 +considered local although their domain name part is not in the list of \fBlocal_hosts\fR. 
   1.132 +
   1.133 +For example: There are two people working at your LAN: person1@yourdomain and person2@yourdomain.
   1.134 +But there are other persons @yourdomain which are NOT local.
   1.135 +So you can not put yourdomain to the list of local_hosts.
   1.136 +If person1 now wants to write to person2@yourdomain and this mail should not leave the LAN then you can put
   1.137 +
   1.138 +local_addresses = "person1@yourdomain;person2@yourdomain"
   1.139 +
   1.140 +to your masqmail.conf.
   1.141 +
   1.142 +.TP
   1.143 +\fBnot_local_addresses = \fIlist\fR
   1.144 +
   1.145 +A semicolon `;' separated list of fully qualified email-addresses which are
   1.146 +considered not local although their domain name part is in the list of \fBlocal_hosts\fR. 
   1.147 +
   1.148 +This is the opposite of the previous case.
   1.149 +The majority of addresses of a specific domain are local.
   1.150 +But some users are not.
   1.151 +With this option you can easily exclude these users.
   1.152 +
   1.153 +Example:
   1.154 +
   1.155 +local_hosts = "localhost;myhost;mydomain.net"
   1.156 +
   1.157 +not_local_addresses = "eric@mydomain.net"
   1.158 +
   1.159 +.TP
   1.160 +\fBlisten_addresses = \fIlist\fR
   1.161 +
   1.162 +A semicolon `;' separated list of interfaces on which connections will be accepted.
   1.163 +An interface ist defined by a hostname, optionally followed by a colon `:' and a number for the port.
   1.164 +If this is left out, port 25 will be used.
   1.165 +
   1.166 +You can set this to "localhost:25;foo:25" if your hostname is `foo'.
   1.167 +
   1.168 +Note that the names are resolved to IP addreses.
   1.169 +If your host has different names which resolve to the same IP,
   1.170 +use only one of them, otherwise you will get an error message.
   1.171 +
   1.172 +.TP
   1.173 +\fBdo_save_envelope_to = \fIboolean\fR
   1.174 +
   1.175 +If this is set to true, a possibly existing Envelope-to: header in an incoming mail
   1.176 +which is received via either pop3 or smtp will be saved as an X-Orig-Envelope-to: header.
   1.177 +
   1.178 +This is useful if you retrieve mail from a pop3 server with either masqmail or fetchmail,
   1.179 +and the server supports Envelope-to: headers,
   1.180 +and you want to make use of those with a mail filtering tool, e.g. procmail.
   1.181 +It cannot be preserved because masqmail sets such a header by itself.
   1.182 +
   1.183 +Default is false.
   1.184 +
   1.185 +.TP
   1.186 +\fBdo_relay = \fIboolean\fR
   1.187 +
   1.188 +If this is set to false, mail with a return path that is not local and a destination
   1.189 +that is also not local will not be accepted via smtp and a 550 reply will be given.
   1.190 +Default is true.
   1.191 +
   1.192 +Note that this will not protect you from spammers using open relays,
   1.193 +but from users unable to set their address in their mail clients.
   1.194 +
   1.195 +.TP
   1.196 +\fBdo_queue = \fIboolean\fR
   1.197 +
   1.198 +If this is set, mail will not be delivered immediately when accepted.
   1.199 +Same as calling masqmail with the \fB\-odq\fR option.
   1.200 +
   1.201 +.TP
   1.202 +\fBonline_routes.\fIname\fR = \fIlist\fR
   1.203 +
   1.204 +Replace \fIname\fR with a name to identify a connection.
   1.205 +Set this to a filename (or a list of filenames) for the special route configuration for that connection.
   1.206 +You will use that name to call masqmail with the \fB\-qo\fR option every time a
   1.207 +connection to your ISP is set up.
   1.208 +
   1.209 +Example: Your ISP has the name FastNet.
   1.210 +Then you write the following line in the main configuration:
   1.211 +
   1.212 +\fBonline_routes.FastNet\fR = \fI"/etc/masqmail/fastnet.route"\fR
   1.213 +
   1.214 +\fI/etc/masqmail/fastnet.route\fR is the route configuration file, see \fBmasqmail.route(5)\fR.
   1.215 +As soon as a link to FastNet has been set up, you call masqmail \fB\-qo \fIFastNet\fR.
   1.216 +Masqmail will then read the specified file and send the mails.
   1.217 +
   1.218 +.TP
   1.219 +\fBconnect_route.\fIname\fR = \fIlist\fR
   1.220 +
   1.221 +Old name for \fBonline_routes\fR.
   1.222 +
   1.223 +.TP
   1.224 +\fBlocal_net_route = \fIfile\fR
   1.225 +
   1.226 +This is similar to \fBonline_routes.\fIname\fR but for the local net.
   1.227 +Recipient addresses that are in local_nets will be routed using this route configuration.
   1.228 +Main purpose is to define a mail server with mail_host in your local network.
   1.229 +In simple environments this can be left unset.
   1.230 +If unset, a default route configuration will be used.
   1.231 +
   1.232 +.TP
   1.233 +\fBalias_file = \fIfile\fR
   1.234 +
   1.235 +Set this to the location of your alias file.
   1.236 +If unset, no aliasing will be done.
   1.237 +
   1.238 +.TP
   1.239 +\fBalias_local_caseless = \fIboolean\fR
   1.240 +
   1.241 +If this is set, local parts in the alias file will be matched disregarding upper/lower case.
   1.242 +
   1.243 +.TP
   1.244 +\fBpipe_fromline = \fIboolean\fR
   1.245 +
   1.246 +If this is set, a from line will be prepended to the output stream whenever
   1.247 +a pipe command is called after an alias expansion.
   1.248 +Default is false.
   1.249 +
   1.250 +.TP
   1.251 +\fBpipe_fromhack = \fIboolean\fR
   1.252 +
   1.253 +If this is set, each line beginning with `From ' is replaced with `>From '
   1.254 +whenever a pipe command is called after an alias expansion.
   1.255 +You probably want this if you have set \fBpipe_fromline\fR above.
   1.256 +Default is false.
   1.257 +
   1.258 +.TP
   1.259 +\fBmbox_default = \fIstring\fR
   1.260 +
   1.261 +The default local delivery method.
   1.262 +Can be one of mbox, mda or maildir (the latter only if maildir support is enabled at compile time).
   1.263 +Default is mbox.
   1.264 +You can override this for each user by using the \fBmbox_users\fR, \fBmda_users\fR,
   1.265 +or \fBmaildir_users\fR options (see below).
   1.266 +
   1.267 +.TP
   1.268 +\fBmbox_users = \fIlist\fR
   1.269 +
   1.270 +A list of users which wish delivery to an mbox style mail folder.
   1.271 +
   1.272 +.TP
   1.273 +\fBmda_users = \fIlist\fR
   1.274 +
   1.275 +A list of users which wish local delivery to an mda.
   1.276 +You have to set \fBmda\fR (see below) as well.
   1.277 +
   1.278 +.TP
   1.279 +\fBmaildir_users = \fIlist\fR
   1.280 +
   1.281 +A list of users which wish delivery to a qmail style maildir.
   1.282 +The path to maildir is ~/Maildir/.
   1.283 +The maildir will be created if it does not exist.
   1.284 +
   1.285 +.TP
   1.286 +\fBmda = \fIexpand string\fR
   1.287 +
   1.288 +If you want local delivery to be transferred to an mda (Mail Delivery Agent),
   1.289 +set this to a command.
   1.290 +The argument will be expanded on delivery time,
   1.291 +you can use variables beginning with a dolloar sign `$', optionally enclosed in curly braces.
   1.292 +Variables you can use are:
   1.293 +
   1.294 +uid - the unique message id.
   1.295 +This is not necessarily identical with the Message ID as given in the Message ID: header.
   1.296 +
   1.297 +received_host - the host the mail was received from
   1.298 +
   1.299 +ident - the ident, this is either the ident delivered by the ident protocol
   1.300 +or the user id of the sender if the message was received locally.
   1.301 +
   1.302 +return_path_local - the local part of the return path (sender).
   1.303 +
   1.304 +return_path_domain - the domain part of the return path (sender).
   1.305 +
   1.306 +return_path - the complete return path (sender).
   1.307 +
   1.308 +rcpt_local - the local part of the recipient.
   1.309 +
   1.310 +rcpt_domain - the domain part of the recipient.
   1.311 +
   1.312 +rcpt - the complete recipient address.
   1.313 +
   1.314 +Example:
   1.315 +
   1.316 +mda="/usr/bin/procmail \-Y \-d ${rcpt_local}"
   1.317 +
   1.318 +For the mda, as for pipe commands, a few environment variables will be set as well.
   1.319 +See \fBmasqmail(8)\fR.
   1.320 +To use environment variables for the mda, the dollar sign `$' has to be escaped with a backslash,
   1.321 +otherwise they will be tried to be expanded with the internal variables.
   1.322 +
   1.323 +.TP
   1.324 +\fBmda_fromline = \fIboolean\fR
   1.325 +
   1.326 +If this is set, a from line will be prepended to the output stream whenever
   1.327 +a message is delivered to an mda.
   1.328 +Default is false.
   1.329 +
   1.330 +.TP
   1.331 +\fBmda_fromhack = \fIboolean\fR
   1.332 +
   1.333 +If this is set, each line beginning with `From ' is replaced with `>From '
   1.334 +whenever a message is delivered to an mda.
   1.335 +You probably want this if you have set \fBmda_fromline\fR above.
   1.336 +Default is false.
   1.337 +
   1.338 +.TP
   1.339 +\fBonline_detect = \fIstring\fR
   1.340 +
   1.341 +Defines the method masqmail uses to detect whether there is currently an online connection.
   1.342 +It can have the values \fBfile\fR, \fBpipe\fR, or \fBmserver\fR.
   1.343 +
   1.344 +When it is set to \fBfile\fR, masqmail first checks for the existence of \fBonline_file\fR
   1.345 +(see below) and if it exists, it reads it.
   1.346 +The content of the file should be the name of the current connection as defined
   1.347 +with \fBconnect_route.\fIname\fR (trailing whitespace is removed).
   1.348 +
   1.349 +When it is set to \fBpipe\fR, masqmail calls the executable given by the
   1.350 +\fBonline_pipe\fR option (see below) and reads the current online status from its standard output.
   1.351 +
   1.352 +When it is set to \fBmserver\fR, masqmail connects to the masqdialer server
   1.353 +using the value of \fBmserver_iface\fR and asks it whether a connection exists and for the name,
   1.354 +which should be the name of the current connection as defined with \fBconnect_route.\fIname\fR.
   1.355 +
   1.356 +No matter how masqmail detects the online status,
   1.357 +only messages that are accepted at online time will be delivered using the connection.
   1.358 +The spool still has to be emptied with masqmail \fB\-qo\fIconnection\fR.
   1.359 +
   1.360 +.TP
   1.361 +\fBonline_file = \fIfile\fR
   1.362 +
   1.363 +This is the name of the file checked for when masqmail determines whether it is online.
   1.364 +The file should only exist when there is currently a connection.
   1.365 +Create it in your ip-up script with e.g.
   1.366 +
   1.367 +echo \-n <name> > /var/run/masqmail/masqmail-route
   1.368 +
   1.369 +chmod 0644 /var/run/masqmail/masqmail-route
   1.370 +
   1.371 +Do not forget to delete it in your ip-down script.
   1.372 +
   1.373 +.TP
   1.374 +\fBonline_pipe = \fIfile\fR
   1.375 +
   1.376 +This is the name of the executable which will be called to determine the online status.
   1.377 +This executable should just print the name of the current connection to
   1.378 +the standard output and return a zero status code.
   1.379 +masqmail assumes it is offline if the script returns with a non zero status.
   1.380 +Simple example:
   1.381 +
   1.382 +#!/bin/sh
   1.383 +
   1.384 +[ \-e /var/run/masqmail/masqmail-route ] || exit 1
   1.385 +
   1.386 +cat /var/run/masqmail/masqmail-route
   1.387 +
   1.388 +exit 0
   1.389 +
   1.390 +Of course, instead of the example above you could as well use \fBfile\fR as
   1.391 +the online detection method, but you can do something more sophisticated.
   1.392 +
   1.393 +.TP
   1.394 +\fBmserver_iface = \fIinterface\fR
   1.395 +
   1.396 +The interface the masqdialer server is listening to.
   1.397 +Usually this will be "localhost:224" if mserver is running on the same host as masqmail.
   1.398 +But using this option, you can also let masqmail run on another host by setting
   1.399 +\fBmserver_iface\fR to another hostname, e.g. "foo:224".
   1.400 +
   1.401 +.TP
   1.402 +\fBget.\fIname\fR = \fIfile\fR
   1.403 +
   1.404 +Replace \fIname\fR with a name to identify a get configuration.
   1.405 +Set this to a filename for the get configuration.
   1.406 +These files will be used to retrieve mail when called with the \-g option.
   1.407 +
   1.408 +.TP
   1.409 +\fBonline_gets.\fIname\fR = \fIlist\fR
   1.410 +
   1.411 +Replace \fIname\fR with a name to identify an online configuration.
   1.412 +Set this to a filename (or a list of filenames) for the get configuration.
   1.413 +These files will be used to retrieve mail when called with the \-go option.
   1.414 +
   1.415 +.TP
   1.416 +\fBident_trusted_nets = \fIlist\fR
   1.417 +
   1.418 +\fIlist\fR is a list of networks of the form a.b.c.d/e (e.g. 192.168.1.0/24),
   1.419 +from which the ident given by the ident protocol will be trusted,
   1.420 +so a user can delete his mail from the queue if the ident is identical to his login name.
   1.421 +
   1.422 +.TP
   1.423 +\fBerrmsg_file = \fIfile\fR
   1.424 +
   1.425 +Set this to a template which will be used to generate delivery failure reports.
   1.426 +Variable parts within the template begin with a dollar sign and are identical
   1.427 +to those which can be used as arguments for the mda command, see \fBmda\fR above.
   1.428 +Additional information can be included with @failed_rcpts, @msg_headers and @msg_body,
   1.429 +these must be at the beginning of a line and will be replaced with the list of the failed recipients,
   1.430 +the message headers and the message body of the failed message.
   1.431 +
   1.432 +Default is /usr/share/masqmail/tpl/failmsg.tpl.
   1.433 +
   1.434 +.TP
   1.435 +\fBwarnmsg_file = \fIfile\fR
   1.436 +
   1.437 +Set this to a template which will be used to generate delivery warning reports.
   1.438 +It uses the same mechanisms for variables as \fBerrmsg_file\fR, see above.
   1.439 +
   1.440 +Default is /usr/share/masqmail/tpl/warnmsg.tpl.
   1.441 +
   1.442 +.TP
   1.443 +\fBwarn_intervals\fR = \fIlist\fR
   1.444 +
   1.445 +Set this to a list of time intervals, at which delivery warnings
   1.446 +(starting with the receiving time of the message) shall be generated.
   1.447 +
   1.448 +A warning will only be generated just after an attempt to deliver the mail
   1.449 +and if that attempt failed temporarily.
   1.450 +So a warning may be generated after a longer time, if there was no attempt before.
   1.451 +
   1.452 +Default is "1h;4h;8h;1d;2d;3d"
   1.453 +
   1.454 +.TP
   1.455 +\fBmax_defer_time\fR = \fItime\fR
   1.456 +
   1.457 +This is the maximum time, in which a temporarily failed mail will be kept in the spool.
   1.458 +When this time is exceeded, it will be handled as a delivery failure,
   1.459 +and the message will be bounced.
   1.460 +
   1.461 +The excedence of this time will only be noticed if the message was actually tried to be delivered.
   1.462 +If, for example, the message can only be delivered when online,
   1.463 +but you have not been online for that time, no bounce will be generated.
   1.464 +
   1.465 +Default is 4d (4 days)
   1.466 +
   1.467 +.TP
   1.468 +\fBlog_user = \fIname\fR
   1.469 +
   1.470 +Replace \fIname\fR with a valid local or remote mail address.
   1.471 +
   1.472 +If this option is set, then a copy of every mail,
   1.473 +that passes through the masqmail system will also be sent to the given mail address.
   1.474 +
   1.475 +For example you can feed your mails into a program like hypermail
   1.476 +for archiving purpose by placing an appropriate pipe command in masqmail.alias
   1.477 +
   1.478 +
   1.479 +.SH AUTHOR
   1.480 +
   1.481 +Masqmail was written by Oliver Kurth.
   1.482 +It is now maintained by Markus Schnalke <meillo@marmaro.de>.
   1.483 +
   1.484 +You will find the newest version of masqmail at \fBhttp://prog.marmaro.de/masqmail/\fR.
   1.485 +There is also a mailing list, you will find information about it at masqmail's main site.
   1.486 +
   1.487 +
   1.488 +.SH BUGS
   1.489 +
   1.490 +Please report bugs to the mailing list.
   1.491 +
   1.492 +
   1.493 +.SH SEE ALSO
   1.494 +
   1.495 +\fBmasqmail(8)\fR, \fBmasqmail.route(5)\fR, \fBmasqmail.get(5)\fR