Mercurial > masqmail
annotate docs/masqmail.conf.5 @ 40:8071dc6c6ed1
next version will be 0.3.0
author | meillo@marmaro.de |
---|---|
date | Mon, 10 May 2010 11:03:26 +0200 |
parents | 4fee89792559 |
children | 03817f849106 |
rev | line source |
---|---|
40 | 1 .TH masqmail.conf 5 2010-05-07 masqmail-0.3.0 "File Formats" |
34 | 2 |
0 | 3 .SH NAME |
4 masqmail.conf \- masqmail configuration file | |
34 | 5 |
6 | |
0 | 7 .SH DESCRIPTION |
8 | |
34 | 9 This man page describes the syntax of the main configuration file of masqmail. |
10 Its usual location is \fI/etc/masqmail/masqmail.conf\fR | |
0 | 11 |
12 The configuration consists of lines of the form | |
13 | |
34 | 14 \fBval\fR = \fIexpression\fR |
0 | 15 |
34 | 16 Where \fBval\fR is a variable name and \fIexpression\fR a string, |
17 which can be quoted with double quotes `"'. | |
18 If the expression is on multiple lines or contains characters other than letters, | |
19 digits or the characters `.', `-', `_', `/', it must be quoted. | |
20 You can use quotes inside quotes by escaping them with a backslash. | |
0 | 21 |
34 | 22 Each val has a type, which can be boolean, numeric, string or list. |
23 A boolean variable can be set with one of the values `on', `yes', and `true' or `off', `no' and `false'. | |
24 List items are separated with semicolons `;'. | |
25 For some values patterns (like `*',`?') can be used. | |
26 The spaces before and after the equal sign `=' are optional. | |
0 | 27 |
34 | 28 Most lists (exceptions: \fBlocal_hosts\fR, \fBlocal_nets\fR, \fBlisten_addresses\fR, |
29 \fBonline_routes\fR, and \fBonline_gets\fR) accept files. | |
30 These will be recognized by a leading slash `/'. | |
31 The contents of these files will be included at the position of the file name, | |
32 there can be items or other files before and after the file entry. | |
33 The format of the files is different though, within these files each entry is on another line. | |
34 (And not separated by semicolons). | |
35 This makes it easy to include large lists which are common in different configuration files, | |
36 so they do not have to appear in every configuration file. | |
0 | 37 |
34 | 38 Blank lines and lines starting with a hash `#' are ignored. |
39 | |
0 | 40 |
41 .SH OPTIONS | |
34 | 42 |
0 | 43 .TP |
34 | 44 \fBrun_as_user = \fIboolean\fR |
0 | 45 |
34 | 46 If this is set, masqmail runs with the user id of the user who invoked it and never changes it. |
47 This is for debugging purposes only. | |
48 If the user is not root, masqmail will not be able to listen on a port < 1024 | |
49 and will not be able to deliver local mail to others than the user. | |
50 | |
0 | 51 .TP |
34 | 52 \fBuse_syslog = \fIboolean\fR |
0 | 53 |
34 | 54 If this is set, masqmail uses syslogd for logging. |
55 It uses facility MAIL. | |
56 You still have to set \fBlog_dir\fR for debug files. | |
57 | |
0 | 58 .TP |
34 | 59 \fBdebug_level = \fIn\fR |
0 | 60 |
34 | 61 Set the debug level. |
62 Valid values are 0 to 6, increasing it further makes no difference. | |
63 Be careful if you set this as high as 5 or higher, the logs may very soon fill your hard drive. | |
64 | |
0 | 65 .TP |
34 | 66 \fBmail_dir = \fIfile\fR |
0 | 67 |
34 | 68 The directory where local mail is stored, usually \fI/var/spool/mail\fR or \fI/var/mail\fR. |
69 | |
0 | 70 .TP |
34 | 71 \fBspool_dir = \fIfile\fR |
0 | 72 |
34 | 73 The directory where masqmail stores its spool files (and later also other stuff). |
74 It must have a subdirectory \fIinput\fR. | |
75 Masqmail needs read and write permissions for this directory. | |
76 I suggest to use \fI/var/spool/masqmail\fR. | |
0 | 77 |
78 .TP | |
34 | 79 \fBhost_name = \fIstring\fR |
0 | 80 |
34 | 81 This is used in different places: Masqmail identifies itself in the greeting banner |
82 on incoming connections and in the HELO/EHLO command for outgoing connections with this name, | |
83 it is used in the Received: header and to qualify the sender of a locally originating message. | |
0 | 84 |
34 | 85 If the string begins with a slash `/', it it assumed that it is a filename, |
86 and the first line of this file will be used. | |
87 Usually this will be `/etc/mailname' to make masqmail conform to Debian policies. | |
0 | 88 |
34 | 89 It is not used to find whether an address is local. Use \fBlocal_hosts\fR for that. |
90 | |
0 | 91 .TP |
34 | 92 \fBremote_port = \fIn\fR |
0 | 93 |
94 The remote port number to be used. This defaults to port 25. | |
95 | |
34 | 96 This option is deprecated. |
97 Use \fBhost_name\fR in the route configuration instead. | |
98 See \fBmasqmail.route(5)\fR. | |
99 | |
0 | 100 .TP |
34 | 101 \fBlocal_hosts = \fIlist\fR |
0 | 102 |
34 | 103 A semicolon `;' separated list of hostnames which are considered local. |
104 Normally you set it to "localhost;foo;foo.bar.com" if your host has the | |
105 fully qualified domain name `foo.bar.com'. | |
0 | 106 |
107 .TP | |
34 | 108 \fBlocal_nets = \fIlist\fR |
0 | 109 |
34 | 110 A semicolon `;' separated list of hostnames which are on the `local' net. |
111 Delivery to these hosts is attempted immediately. | |
112 You can use patterns with `*', e.g. "*.bar.com". | |
0 | 113 |
114 .TP | |
34 | 115 \fBlocal_addresses = \fIlist\fR |
0 | 116 |
34 | 117 A semicolon `;' separated list of fully qualified email-addresses which are |
118 considered local although their domain name part is not in the list of \fBlocal_hosts\fR. | |
0 | 119 |
34 | 120 For example: There are two people working at your LAN: person1@yourdomain and person2@yourdomain. |
121 But there are other persons @yourdomain which are NOT local. | |
122 So you can not put yourdomain to the list of local_hosts. | |
123 If person1 now wants to write to person2@yourdomain and this mail should not leave the LAN then you can put | |
0 | 124 |
125 local_addresses = "person1@yourdomain;person2@yourdomain" | |
126 | |
127 to your masqmail.conf. | |
34 | 128 |
0 | 129 .TP |
34 | 130 \fBnot_local_addresses = \fIlist\fR |
0 | 131 |
34 | 132 A semicolon `;' separated list of fully qualified email-addresses which are |
133 considered not local although their domain name part is in the list of \fBlocal_hosts\fR. | |
0 | 134 |
34 | 135 This is the opposite of the previous case. |
136 The majority of addresses of a specific domain are local. | |
137 But some users are not. | |
138 With this option you can easily exclude these users. | |
0 | 139 |
140 Example: | |
141 | |
142 local_hosts = "localhost;myhost;mydomain.net" | |
143 | |
144 not_local_addresses = "eric@mydomain.net" | |
34 | 145 |
0 | 146 .TP |
34 | 147 \fBlisten_addresses = \fIlist\fR |
0 | 148 |
34 | 149 A semicolon `;' separated list of interfaces on which connections will be accepted. |
150 An interface ist defined by a hostname, optionally followed by a colon `:' and a number for the port. | |
151 If this is left out, port 25 will be used. | |
0 | 152 |
34 | 153 You can set this to "localhost:25;foo:25" if your hostname is `foo'. |
0 | 154 |
34 | 155 Note that the names are resolved to IP addreses. |
156 If your host has different names which resolve to the same IP, | |
157 use only one of them, otherwise you will get an error message. | |
158 | |
0 | 159 .TP |
34 | 160 \fBdo_save_envelope_to = \fIboolean\fR |
0 | 161 |
34 | 162 If this is set to true, a possibly existing Envelope-to: header in an incoming mail |
163 which is received via either pop3 or smtp will be saved as an X-Orig-Envelope-to: header. | |
0 | 164 |
34 | 165 This is useful if you retrieve mail from a pop3 server with either masqmail or fetchmail, |
166 and the server supports Envelope-to: headers, | |
167 and you want to make use of those with a mail filtering tool, e.g. procmail. | |
168 It cannot be preserved because masqmail sets such a header by itself. | |
0 | 169 |
170 Default is false. | |
34 | 171 |
0 | 172 .TP |
34 | 173 \fBdo_relay = \fIboolean\fR |
0 | 174 |
34 | 175 If this is set to false, mail with a return path that is not local and a destination |
176 that is also not local will not be accepted via smtp and a 550 reply will be given. | |
177 Default is true. | |
0 | 178 |
34 | 179 Note that this will not protect you from spammers using open relays, |
180 but from users unable to set their address in their mail clients. | |
181 | |
0 | 182 .TP |
34 | 183 \fBdo_queue = \fIboolean\fR |
0 | 184 |
34 | 185 If this is set, mail will not be delivered immediately when accepted. |
186 Same as calling masqmail with the \fB\-odq\fR option. | |
0 | 187 |
188 .TP | |
34 | 189 \fBonline_routes.\fIname\fR = \fIlist\fR |
0 | 190 |
34 | 191 Replace \fIname\fR with a name to identify a connection. |
192 Set this to a filename (or a list of filenames) for the special route configuration for that connection. | |
193 You will use that name to call masqmail with the \fB\-qo\fR option every time a | |
194 connection to your ISP is set up. | |
0 | 195 |
34 | 196 Example: Your ISP has the name FastNet. |
197 Then you write the following line in the main configuration: | |
0 | 198 |
34 | 199 \fBonline_routes.FastNet\fR = \fI"/etc/masqmail/fastnet.route"\fR |
0 | 200 |
34 | 201 \fI/etc/masqmail/fastnet.route\fR is the route configuration file, see \fBmasqmail.route(5)\fR. |
202 As soon as a link to FastNet has been set up, you call masqmail \fB\-qo \fIFastNet\fR. | |
203 Masqmail will then read the specified file and send the mails. | |
0 | 204 |
34 | 205 .TP |
206 \fBconnect_route.\fIname\fR = \fIlist\fR | |
0 | 207 |
34 | 208 Old name for \fBonline_routes\fR. |
209 | |
0 | 210 .TP |
34 | 211 \fBlocal_net_route = \fIfile\fR |
0 | 212 |
34 | 213 This is similar to \fBonline_routes.\fIname\fR but for the local net. |
214 Recipient addresses that are in local_nets will be routed using this route configuration. | |
215 Main purpose is to define a mail server with mail_host in your local network. | |
216 In simple environments this can be left unset. | |
217 If unset, a default route configuration will be used. | |
0 | 218 |
34 | 219 .TP |
220 \fBalias_file = \fIfile\fR | |
0 | 221 |
34 | 222 Set this to the location of your alias file. |
223 If unset, no aliasing will be done. | |
224 | |
0 | 225 .TP |
34 | 226 \fBalias_local_caseless = \fIboolean\fR |
0 | 227 |
228 If this is set, local parts in the alias file will be matched disregarding upper/lower case. | |
34 | 229 |
0 | 230 .TP |
34 | 231 \fBpipe_fromline = \fIboolean\fR |
0 | 232 |
34 | 233 If this is set, a from line will be prepended to the output stream whenever |
234 a pipe command is called after an alias expansion. | |
235 Default is false. | |
236 | |
0 | 237 .TP |
34 | 238 \fBpipe_fromhack = \fIboolean\fR |
0 | 239 |
34 | 240 If this is set, each line beginning with `From ' is replaced with `>From ' |
241 whenever a pipe command is called after an alias expansion. | |
242 You probably want this if you have set \fBpipe_fromline\fR above. | |
243 Default is false. | |
244 | |
0 | 245 .TP |
34 | 246 \fBmbox_default = \fIstring\fR |
0 | 247 |
34 | 248 The default local delivery method. |
249 Can be one of mbox, mda or maildir (the latter only if maildir support is enabled at compile time). | |
250 Default is mbox. | |
251 You can override this for each user by using the \fBmbox_users\fR, \fBmda_users\fR, | |
252 or \fBmaildir_users\fR options (see below). | |
253 | |
0 | 254 .TP |
34 | 255 \fBmbox_users = \fIlist\fR |
0 | 256 |
257 A list of users which wish delivery to an mbox style mail folder. | |
34 | 258 |
0 | 259 .TP |
34 | 260 \fBmda_users = \fIlist\fR |
0 | 261 |
34 | 262 A list of users which wish local delivery to an mda. |
263 You have to set \fBmda\fR (see below) as well. | |
264 | |
0 | 265 .TP |
34 | 266 \fBmaildir_users = \fIlist\fR |
0 | 267 |
34 | 268 A list of users which wish delivery to a qmail style maildir. |
269 The path to maildir is ~/Maildir/. | |
270 The maildir will be created if it does not exist. | |
271 | |
0 | 272 .TP |
34 | 273 \fBmda = \fIexpand string\fR |
0 | 274 |
34 | 275 If you want local delivery to be transferred to an mda (Mail Delivery Agent), |
276 set this to a command. | |
277 The argument will be expanded on delivery time, | |
278 you can use variables beginning with a dolloar sign `$', optionally enclosed in curly braces. | |
279 Variables you can use are: | |
0 | 280 |
34 | 281 uid - the unique message id. |
282 This is not necessarily identical with the Message ID as given in the Message ID: header. | |
0 | 283 |
284 received_host - the host the mail was received from | |
285 | |
34 | 286 ident - the ident, this is either the ident delivered by the ident protocol |
287 or the user id of the sender if the message was received locally. | |
0 | 288 |
289 return_path_local - the local part of the return path (sender). | |
290 | |
291 return_path_domain - the domain part of the return path (sender). | |
292 | |
293 return_path - the complete return path (sender). | |
294 | |
295 rcpt_local - the local part of the recipient. | |
296 | |
297 rcpt_domain - the domain part of the recipient. | |
298 | |
299 rcpt - the complete recipient address. | |
300 | |
301 Example: | |
302 | |
16 | 303 mda="/usr/bin/procmail \-Y \-d ${rcpt_local}" |
0 | 304 |
34 | 305 For the mda, as for pipe commands, a few environment variables will be set as well. |
306 See \fBmasqmail(8)\fR. | |
307 To use environment variables for the mda, the dollar sign `$' has to be escaped with a backslash, | |
308 otherwise they will be tried to be expanded with the internal variables. | |
0 | 309 |
310 .TP | |
34 | 311 \fBmda_fromline = \fIboolean\fR |
0 | 312 |
34 | 313 If this is set, a from line will be prepended to the output stream whenever |
314 a message is delivered to an mda. | |
315 Default is false. | |
0 | 316 |
317 .TP | |
34 | 318 \fBmda_fromhack = \fIboolean\fR |
0 | 319 |
34 | 320 If this is set, each line beginning with `From ' is replaced with `>From ' |
321 whenever a message is delivered to an mda. | |
322 You probably want this if you have set \fBmda_fromline\fR above. | |
323 Default is false. | |
324 | |
325 .TP | |
326 \fBonline_detect = \fIstring\fR | |
0 | 327 |
34 | 328 Defines the method masqmail uses to detect whether there is currently an online connection. |
329 It can have the values \fBfile\fR, \fBpipe\fR, or \fBmserver\fR. | |
0 | 330 |
34 | 331 When it is set to \fBfile\fR, masqmail first checks for the existence of \fBonline_file\fR |
332 (see below) and if it exists, it reads it. | |
333 The content of the file should be the name of the current connection as defined | |
334 with \fBconnect_route.\fIname\fR (trailing whitespace is removed). | |
0 | 335 |
34 | 336 When it is set to \fBpipe\fR, masqmail calls the executable given by the |
337 \fBonline_pipe\fR option (see below) and reads the current online status from its standard output. | |
0 | 338 |
34 | 339 When it is set to \fBmserver\fR, masqmail connects to the masqdialer server |
340 using the value of \fBmserver_iface\fR and asks it whether a connection exists and for the name, | |
341 which should be the name of the current connection as defined with \fBconnect_route.\fIname\fR. | |
0 | 342 |
34 | 343 No matter how masqmail detects the online status, |
344 only messages that are accepted at online time will be delivered using the connection. | |
345 The spool still has to be emptied with masqmail \fB\-qo\fIconnection\fR. | |
346 | |
0 | 347 .TP |
34 | 348 \fBonline_file = \fIfile\fR |
0 | 349 |
34 | 350 This is the name of the file checked for when masqmail determines whether it is online. |
351 The file should only exist when there is currently a connection. | |
352 Create it in your ip-up script with e.g. | |
0 | 353 |
37
4fee89792559
updated config example and man page to new default online file
meillo@marmaro.de
parents:
34
diff
changeset
|
354 echo \-n <name> > /var/run/masqmail/masqmail-route |
0 | 355 |
37
4fee89792559
updated config example and man page to new default online file
meillo@marmaro.de
parents:
34
diff
changeset
|
356 chmod 0644 /var/run/masqmail/masqmail-route |
0 | 357 |
358 Do not forget to delete it in your ip-down script. | |
34 | 359 |
0 | 360 .TP |
34 | 361 \fBonline_pipe = \fIfile\fR |
0 | 362 |
34 | 363 This is the name of the executable which will be called to determine the online status. |
364 This executable should just print the name of the current connection to | |
365 the standard output and return a zero status code. | |
366 masqmail assumes it is offline if the script returns with a non zero status. | |
367 Simple example: | |
0 | 368 |
369 #!/bin/sh | |
370 | |
37
4fee89792559
updated config example and man page to new default online file
meillo@marmaro.de
parents:
34
diff
changeset
|
371 [ \-e /var/run/masqmail/masqmail-route ] || exit 1 |
0 | 372 |
37
4fee89792559
updated config example and man page to new default online file
meillo@marmaro.de
parents:
34
diff
changeset
|
373 cat /var/run/masqmail/masqmail-route |
0 | 374 |
375 exit 0 | |
376 | |
34 | 377 Of course, instead of the example above you could as well use \fBfile\fR as |
378 the online detection method, but you can do something more sophisticated. | |
379 | |
0 | 380 .TP |
34 | 381 \fBmserver_iface = \fIinterface\fR |
0 | 382 |
34 | 383 The interface the masqdialer server is listening to. |
384 Usually this will be "localhost:224" if mserver is running on the same host as masqmail. | |
385 But using this option, you can also let masqmail run on another host by setting | |
386 \fBmserver_iface\fR to another hostname, e.g. "foo:224". | |
0 | 387 |
34 | 388 .TP |
389 \fBget.\fIname\fR = \fIfile\fR | |
0 | 390 |
34 | 391 Replace \fIname\fR with a name to identify a get configuration. |
392 Set this to a filename for the get configuration. | |
393 These files will be used to retrieve mail when called with the \-g option. | |
394 | |
0 | 395 .TP |
34 | 396 \fBonline_gets.\fIname\fR = \fIlist\fR |
0 | 397 |
34 | 398 Replace \fIname\fR with a name to identify an online configuration. |
399 Set this to a filename (or a list of filenames) for the get configuration. | |
400 These files will be used to retrieve mail when called with the \-go option. | |
0 | 401 |
402 .TP | |
34 | 403 \fBident_trusted_nets = \fIlist\fR |
0 | 404 |
34 | 405 \fIlist\fR is a list of networks of the form a.b.c.d/e (e.g. 192.168.1.0/24), |
406 from which the ident given by the ident protocol will be trusted, | |
407 so a user can delete his mail from the queue if the ident is identical to his login name. | |
408 | |
0 | 409 .TP |
34 | 410 \fBerrmsg_file = \fIfile\fR |
0 | 411 |
34 | 412 Set this to a template which will be used to generate delivery failure reports. |
413 Variable parts within the template begin with a dollar sign and are identical | |
414 to those which can be used as arguments for the mda command, see \fBmda\fR above. | |
415 Additional information can be included with @failed_rcpts, @msg_headers and @msg_body, | |
416 these must be at the beginning of a line and will be replaced with the list of the failed recipients, | |
417 the message headers and the message body of the failed message. | |
0 | 418 |
419 Default is /usr/share/masqmail/tpl/failmsg.tpl. | |
420 | |
34 | 421 .TP |
422 \fBwarnmsg_file = \fIfile\fR | |
0 | 423 |
34 | 424 Set this to a template which will be used to generate delivery warning reports. |
425 It uses the same mechanisms for variables as \fBerrmsg_file\fR, see above. | |
0 | 426 |
427 Default is /usr/share/masqmail/tpl/warnmsg.tpl. | |
34 | 428 |
0 | 429 .TP |
34 | 430 \fBwarn_intervals\fR = \fIlist\fR |
0 | 431 |
34 | 432 Set this to a list of time intervals, at which delivery warnings |
433 (starting with the receiving time of the message) shall be generated. | |
0 | 434 |
34 | 435 A warning will only be generated just after an attempt to deliver the mail |
436 and if that attempt failed temporarily. | |
437 So a warning may be generated after a longer time, if there was no attempt before. | |
0 | 438 |
439 Default is "1h;4h;8h;1d;2d;3d" | |
34 | 440 |
0 | 441 .TP |
34 | 442 \fBmax_defer_time\fR = \fItime\fR |
0 | 443 |
34 | 444 This is the maximum time, in which a temporarily failed mail will be kept in the spool. |
445 When this time is exceeded, it will be handled as a delivery failure, | |
446 and the message will be bounced. | |
0 | 447 |
34 | 448 The excedence of this time will only be noticed if the message was actually tried to be delivered. |
449 If, for example, the message can only be delivered when online, | |
450 but you have not been online for that time, no bounce will be generated. | |
0 | 451 |
452 Default is 4d (4 days) | |
453 | |
34 | 454 .TP |
455 \fBlog_user = \fIname\fR | |
456 | |
457 Replace \fIname\fR with a valid local or remote mail address. | |
0 | 458 |
34 | 459 If this option is not empty, then a copy of every mail, |
460 that passes trough the masqmail system will also be sent to the given mail address. | |
0 | 461 |
34 | 462 For example you can feed your mails into a program like hypermail |
463 for archiving purpose by placing an appropriate pipe command in masqmail.alias | |
0 | 464 |
34 | 465 |
0 | 466 .SH AUTHOR |
467 | |
34 | 468 Masqmail was written by Oliver Kurth. |
469 It is now maintained by Markus Schnalke <meillo@marmaro.de>. | |
0 | 470 |
34 | 471 You will find the newest version of masqmail at \fBhttp://prog.marmaro.de/masqmail/\fR. |
26
607221b0dac1
added myself as maintainer; updated URL of the website
meillo@marmaro.de
parents:
16
diff
changeset
|
472 There is also a mailing list, you will find information about it at masqmail's main site. |
0 | 473 |
34 | 474 |
0 | 475 .SH BUGS |
476 | |
34 | 477 Please report bugs to the mailing list. |
478 | |
0 | 479 |
480 .SH SEE ALSO | |
481 | |
34 | 482 \fBmasqmail(8)\fR, \fBmasqmail.route(5)\fR, \fBmasqmail.get(5)\fR |