masqmail: 6538aa6969e5 docs/old-manual/docs/masqmail.conf.5.html

masqmail

view docs/old-manual/docs/masqmail.conf.5.html @ 78:6538aa6969e5

next version will be 0.2.24

author	meillo@marmaro.de
date	Sat, 19 Jun 2010 10:51:23 +0200
parents
children

line source

1 <body text="#000000" link="#0000ff" bgcolor="#ffffff"><center><table width="80%">

2 <tr><td><h1>masqmail.conf</h1>

3 <h2>masqmail configuration file</h2>

6 <h2>Description</h2>

8 This man page describes the syntax of the main configuration file

9 of masqmail. Its usual location is /etc/masqmail/masqmail.conf

11 The configuration consists of lines of the form

13 val = expression

15 Where val is a variable name and expression a string,

16 which can be quoted with '"'. If the expression is on multiple lines

17 or contains characters other than letters, digits or the characters

18 '.', '-', '_', '/', it must be quoted. You can use quotes inside quotes

19 by escaping them with a backslash.

21 Each val has a type, which can be boolean, numeric, string

22 or list. A boolean variable can be set with one of the values 'on',

23 'yes', and 'true' or 'off', 'no' and 'false'. List items are separated

24 with ';'. For some values patterns (like '*','?') can be used. The

25 spaces before and after the '=' are optional.

27 Most lists (exceptions: local_hosts,

28 local_nets, listen_addresses, online_routes and online_gets) accept

29 files. These will be recognized by a leading slash '/'. The contents

30 of these files will be included at the position of the file name,

31 there can be items or other files before and after the file entry. The

32 format of the files is different though, within these files each entry

33 is on another line. (And not separated by semicolons). This makes it

34 easy to include large lists which are common in different

35 configuration files, so they do not have to appear in every

36 configuration file.

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

43 <h2>Options</h2>

46 run_as_user = boolean

48 If this is set, masqmail runs with the user id of the user who

49 invoked it and never changes it. This is for debugging purposes

50 only. If the user is not root, masqmail will not be able to

51 listen on a port < 1024 and will not be able to deliver local mail

52 to others than the user.

57 use_syslog = boolean

59 If this is set, masqmail uses syslogd for logging. It uses facility

60 MAIL. You still have to set log_dir for debug files.

65 debug_level = n

67 Set the debug level. Valid values are 0 to 6, increasing it further

68 makes no difference. Be careful if you set this as high as 5 or higher,

69 the logs may very soon fill your hard drive.

74 mail_dir = file

76 The directory where local mail is stored,

77 usually /var/spool/mail or /var/mail.

82 spool_dir = file

84 The directory where masqmail stores its spool files (and later also

85 other stuff). It must have a subdirectory input.

86 Masqmail needs read and write permissions for this

87 directory. I suggest to use /var/spool/masqmail.

92 host_name = string

94 This is used in different places: Masqmail identifies itself in the

95 greeting banner on incoming connections and in the HELO/EHLO command

96 for outgoing connections with this name, it is used in the Received:

97 header and to qualify the sender of a locally originating message.

99 If the string begins with a slash '/', it it assumed that it is a

100 filename, and the first line of this file will be used. Usually this will

101 be '/etc/mailname' to make masqmail conform to Debian policies.

102

103 It is not used to find whether an address is local.

104 Use local_hosts for that.

105

106

107

108

109 remote_port = n

110

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

112 This option is deprecated. Use host_name in the route

113 configuration instead. See <a href="masqmail.route.5.html">masqmail.route</a>.

114

115

116

117

118 local_hosts = list

119

120 A semicolon ';' separated list of hostnames which are considered

121 local. Normally you set it to "localhost;foo;foo.bar.com" if your host

122 has the fully qualified domain name 'foo.bar.com'.

123

124

125

126

127 local_nets = list

128

129 A semicolon ';' separated list of hostnames which are on the

130 'local' net. Delivery to these hosts is attempted immediately. You can

131 use patterns with '*', eg. "*.bar.com".

132

133

134

135

136 local_addresses = list

137

138 A semicolon ';' separated list of fully qualified email-addresses

139 which are considered local although their domain name part is not in

140 the list of local_hosts.

141 For example: There are two people working at your

142 LAN: person1@yourdomain and person2@yourdomain. But there are

143 other persons @yourdomain which are NOT local. So you can not put

144 yourdomain to the list of local_hosts. If person1 now wants

145 to write to person2@yourdomain and this mail should not leave the LAN

146 then you can put

147 local_addresses = "person1@yourdomain;person2@yourdomain"

148 to your masqmail.conf.

149

150

151

152

153 not_local_addresses = list

154

155 A semicolon ';' separated list of fully qualified email-addresses

156 which are considered not local although their domain name part is in

157 the list of local_hosts.

158 This ist the opposite of the previous case. The majority of addresses

159 of a specific domain are local. But some users are not. With this

160 option you can easily exclude these users.

161 Example:

162 local_hosts = "localhost;myhost;mydomain.net"

163 not_local_addresses = "eric@mydomain.net"

164

165

166

167

168 listen_addresses = list

169

170 A semicolon ';' separated list of interfaces on which connections

171 will be accepted. An interface ist defined by a hostname, optionally

172 followed by a colon ':' and a number for the port. If this is left out,

173 port 25 will be used.

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

175 Note that the names are resolved to IP addreses. If your host has

176 different names which resolve to the same IP, use only one of them,

177 otherwise you will get an error message.

178

179

180

181

182

183 do_save_envelope_to = boolean

184

185 If this is set to true, a possibly existing Envelope-to: header in an

186 incoming mail which is received via either pop3 or smtp will be saved as

187 an X-Orig-Envelope-to: header.

188 This is useful if you retrieve mail from a pop3 server with either masqmail

189 or fetchmail, and the server supports Envelope-to: headers, and you want to make use

190 of those with a mail filtering tool, eg. procmail. It cannot be preserved because

191 masqmail sets such a header by itself.

192 Default is false.

193

194

195

196

197 do_relay = boolean

198

199 If this is set to false, mail with a return path that is not local and a

200 destination that is also not local will not be accepted via smtp and a 550

201 reply will be given. Default is true.

202 Note that this will not protect you from spammers using open relays, but from

203 users unable to set their address in their mail clients.

204

205

206

207

208 do_queue = boolean

209

210 If this is set, mail will not be delivered immediately when

211 accepted. Same as calling masqmail with the -odq option.

212

213

214

215

216 online_routes.name = list

217

218

219 Replace name with a name to identify a connection. Set this

220 to a filename (or a list of filenames) for the special route configuration for that

221 connection. You will use that name to call masqmail with the

222 -qo option every time a connection to your ISP is set

223 up.

224

225 Example: Your ISP has the name FastNet. Then you write the

226 following line in the main configuration:

227

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

229

230 /etc/masqmail/fastnet.route is the route configuration

231 file, see <a href="masqmail.route.5.html">masqmail.route</a>. As soon as a link to FastNet has been set up, you

232 call masqmail -qo FastNet. Masqmail will then

233 read the specified file and send the mails.

234

235

236

237

238

239 connect_route.name = list

240

241 Old name for online_routes.

242

243

244

245

246

247 local_net_route = file

248

249 This is similar to online_routes.name but for the

250 local net. Recipient addresses that are in local_nets will be

251 routed using this route configuration. Main purpose is to define a

252 mail server with mail_host in your local network. In simple

253 environments this can be left unset. If unset, a default route

254 configuration will be used.

255

256

257

258

259 alias_file = file

260

261 Set this to the location of your alias file. If unset, no aliasing

262 will be done.

263

264

265

266

267 alias_local_caseless = boolean

268

269 If this is set, local parts in the alias file will be matched

270 disregarding upper/lower case.

271

272

273

274

275 pipe_fromline = boolean

276

277 If this is set, a from line will be prepended to the output stream whenever

278 a pipe command is called after an alias expansion. Default is false.

279

280

281

282

283 pipe_fromhack = boolean

284

285 If this is set, each line beginning with 'From ' is replaced with '>From ' whenever

286 a pipe command is called after an alias expansion. You probably want this if you have

287 set pipe_fromline above. Default is false.

288

289

290

291

292 mbox_default = string

293

294 The default local delivery method. Can be one of mbox, mda or

295 maildir (the latter only if maildir support is enabled at compile

296 time). Default is mbox. You can override this for each user by using

297 the mbox_users, mda_users or maildir_users options

298 (see below).

299

300

301

302

303

304 mbox_users = list

305

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

307

308

309

310

311 mda_users = list

312

313 A list of users which wish local delivery to an mda. You have to

314 set mda (see below) as well.

315

316

317

318

319 maildir_users = list

320

321 A list of users which wish delivery to a qmail style maildir. The

322 path to maildir is ~/Maildir/. The maildir will be created if it

323 does not exist.

324

325

326

327

328 mda = expand string

329

330 If you want local delivery to be transferred to an mda (Mail

331 Delivery Agent), set this to a command. The argument will be expanded

332 on delivery time, you can use variables beginning with a '$' sign,

333 optionally enclosed in curly braces. Variables you can use are:

334 uid - the unique message id. This is not necessarily identical with

335 the Message ID as given in the Message ID: header.

336 received_host - the host the mail was received from

337 ident - the ident, this is either the ident delivered by the ident

338 protocol or the user id of the sender if the message was received locally.

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

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

341 return_path - the complete return path (sender).

342 rcpt_local - the local part of the recipient.

343 rcpt_domain - the domain part of the recipient.

344 rcpt - the complete recipient address.

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

346 For the mda, as for pipe commands, a few environment variables will

347 be set as well. See <a href="masqmail.8.html">masqmail</a>. To use environment variables for the mda,

348 the '$' sign has to be escaped with a backslash, otherwise they will

349 be tried to be expanded with the internal variables.

350

351

352

353

354

355 mda_fromline = boolean

356

357 If this is set, a from line will be prepended to the output stream whenever

358 a message is delivered to an mda. Default is false.

359

360

361

362

363 mda_fromhack = boolean

364

365 If this is set, each line beginning with 'From ' is replaced with '>From ' whenever

366 a message is delivered to an mda. You probably want this if you have

367 set mda_fromline above. Default is false.

368

369

370

371

372 online_detect = string

373

374 Defines the method MasqMail uses to detect whether there is

375 currently an online connection. It can have the

376 values file, pipe or mserver.

377

378 When it is set to file, MasqMail first checks for the

379 existence of online_file (see below) and if it exists, it reads

380 it. The content of the file should be the name of the current

381 connection as defined with connect_route.name (without

382 a trailing newline character).

383

384 When it is set to pipe, MasqMail calls the executable given by

385 the online_pipe option (see below) and reads the current online

386 status from its standard output.

387

388 When it is set to mserver, MasqMail connects to the

389 masqdialer server using the value of mserver_iface and asks it

390 whether a connection exists and for the name, which should be the name

391 of the current connection as defined with connect_route.name.

392

393 No matter how MasqMail detects the online status, only messages

394 that are accepted at online time will be delivered using the

395 connection. The spool still has to be emptied with masqmail -qo

396 connection.

397

398

399

400

401 online_file = file

402

403 This is the name of the file checked for when MasqMail determines

404 whether it is online. The file should only exist when there is

405 currently a connection. Create it in your ip-up script with eg.

406

407 echo -n <name> > /tmp/connect_route

408 chmod 0644 /tmp/connect_route

409

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

411

412

413

414

415 online_pipe = file

416

417 This is the name of the executable which will be called to determine

418 the online status. This executable should just print the name oif the current

419 connection to the standard output and return a zero status code. masqmail assumes

420 it is offline if the script returns with a non zero status. Simple example:

421

422 #!/bin/sh

423

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

425 cat /tmp/connect_route

426 exit 0

427

428 Of course, instead of the example above you could as well use file as

429 the online detection method, but you can do something more sophisticated.

430

431

432

433

434 mserver_iface = interface

435

436 The interface the masqdialer server is listening to. Usually this

437 will be "localhost:224" if mserver is running on the same host as

438 masqmail. But using this option, you can also let masqmail run on

439 another host by setting mserver_iface to another hostname,

440 eg. "foo:224".

441

442

443

444

445 get.name = file

446

447 Replace name with a name to identify a get

448 configuration. Set this to a filename for the get configuration. These

449 files will be used to retrieve mail when called with the -g option.

450

451

452

453

454 online_gets.name = list

455

456 Replace name with a name to identify an online

457 configuration. Set this to a filename (or a list of filenames) for the get configuration. These

458 files will be used to retrieve mail when called with the -go option.

459

460

461

462

463 ident_trusted_nets = list

464

465 list is a list of networks of the form a.b.c.d/e

466 (eg. 192.168.1.0/24), from which the ident given by the ident protocol

467 will be trusted, so a user can delete his mail from the queue if the

468 ident is identical to his login name.

469

470

471

472

473 errmsg_file = file

474

475 Set this to a template which will be used to generate delivery failure

476 reports. Variable parts within the template begin with a dollar sign and

477 are identical to those which can be used as arguments for the mda command,

478 see mda above. Additional information can be included with

479 @failed_rcpts, @msg_headers and @msg_body, these must be at the

480 beginning of a line and will be replaced with the list of the failed recipients,

481 the message headers and the message body of the failed message.

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

483

484

485

486

487 warnmsg_file = file

488

489 Set this to a template which will be used to generate delivery warning

490 reports. It uses the same mechanisms for variables as errmsg_file,

491 see above.

492

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

494

495

496

497

498 warn_intervals = list

499

500 Set this to a list of time intervals, at which delivery warnings (starting

501 with the receiving time of the message) shall be generated.

502 A warning will only be generated just after an attempt to deliver the

503 mail and if that attempt failed temporarily. So a warning may be generated after

504 a longer time, if there was no attempt before.

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

506

507

508

509

510 max_defer_time = time

511

512 This is the maximum time, in which a temporarily failed mail will be kept

513 in the spool. When this time is exceeded, it will be handled as a delivery failure,

514 and the message will be bounced.

515 The excedence of this time will only be noticed if the message was actually

516 tried to be delivered. If, for example, the message can only be delivered when

517 online, but you have not been online for that time, no bounce will be generated.

518 Default is 4d (4 days)

519

520

521

522

523 log_user = name

524

525 Replace name with a valid local or remote mail address.

526 If this option is not empty, then a copy of every mail,

527 that passes trough the masqmail system will also be sent to the

528 given mail address.

529 For example you can feed your mails into a program like hypermail for

530 archiving purpose by placing an appropriate pipe command in masqmail.alias

531

532

533

534

535

536 <h2>Author</h2>

537

538 masqmail was written by Oliver Kurth

539 <oku@masqmail.cx>You will find the newest version of

540 masqmail at <a href = "http://masqmail.cx/masqmail/">http://masqmail.cx/masqmail/</a> or search for it

541 in freshmeat (<a href = "http://www.freshmeat.net">http://www.freshmeat.net</a>). There is also a mailing list,

542 you will find information about it at masqmails main site.

543

544

545

546 <h2>Bugs</h2>

547

548 You should report them to the mailing list.

549

550

551

552 <h2>See also</h2>

553

554

555 <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>

556

557

558

559

560

561 <h2>Comments</h2>

562

563 This man page was written using <a href="http://masqmail.cx/xml2man/">xml2man</a> by the same

564 author.

565

566

567

568 </td></tr></table></center>

569 </body>