/* $Id: INSTALL.postfix 1653 2005-03-10 13:40:13Z paul $ */


Using DBMail with Postfix
=========================
Author: Ilja Booij
Date:   19-03-2004

1. 	Prerequisites

	* A DBMail installation
	* A Postfix installation
	
	This document will assume that your Postfix configuration files are
	located at /etc/postfix/

	Make sure you've read and executed the steps from the INSTALL file 
	before configuring your MTA. You'll want to be sure that DBMail is
	ready to deliver mails before sending your messages to it!

2.	Using LMTP

	in /etc/postfix/master.cf add:

	dbmail-lmtp     unix    -       -       n       -       -       lmtp
	
	If you want verbose output in the mail log, add -v to lmtp, like this:

	dbmail-lmtp     unix    -       -       n       -       -       lmtp -v

	Mind that you get a LOT of output in your logs when using this setting.
	
	If one or more destinations in your mydestination list are not 
	DNS-resolvable, DNS lookups must be disabled for the dbmail-lmtp daemon:
	
	dbmail-lmtp     unix    -       -       n       -       -       lmtp 
	    -o disable_dns_lookups=yes

	If you want to send all the email the MTA accepts to DBMail, use the
	following setting in /etc/postfix/main.cf:

	mailbox_transport = dbmail-lmtp:<host>:<port>

	If you want to decide if DBMail should be used per domain please add
	the following in /etc/postfix/transport.cf:

	<domain>        dbmail-lmtp:<host>:<port>

	Where <domain> should replaced by the mail domain you receive mail for.
	It is possible to have several domain entries here. For <host> and
	<port> fill out the host and port on which the dbmail-lmtp daemon runs.
	If unsure about which port they run on, check your dbmail.conf file. 
	The standard port for the lmtp service is port 24. An example of a 
	transport file is below:

	example.com		dbmail-lmtp:localhost:24
	anotherexample.com	dbmail-lmtp:localhost:24

	NOTE: If you are using Postfix 2.0 or later, and you are NOT using a
	MySQL-built alias list (see section 4. for instructions on how to
	implement this) you must use the following setting in main.cf:  
	
	local_recipient_maps =
	
	Otherwise, Postfix will reject your dbmail recipients with a big fat 
	"User unknown in local recipient table" error.
	
	now run:

	# postmap /etc/postfix/transport
	# postfix reload

	and you're on your way!

3.	Using the Pipe interface (dbmail-smtp)

	in /etc/postfix/master.cf add:
	
	dbmail-smtp    unix  -       n       n       -       -       pipe
	    flags=  user=<dbmailuser>:<dbmailgroup> 
		argv=/usr/local/sbin/dbmail-smtp -d ${recipient} -r ${sender}
	
	where <dbmailuser> and <dbmailgroup> should be the user and group the
	dbmail-smtp program should run as. The ${recipient} and ${sender} 
	fields are filled in by Postfix.

	To send all email to DBMail, add this in /etc/postfix/main.cf

	mailbox_transport = dbmail-smtp:

	If you want to decide whether or not to send to DBMail per domain,
	add this in /etc/postfix/transport:
	
	<domain>        dbmail-smtp:

	See the section on running Postfix with LMTP if you don't understand
	the transport file.

	now run:
	# postmap /etc/postfix/transport
	# postfix reload

	And your mail will be delivered!

4.	Postfix can also interface directly with MySQL or PostgreSQL to check 
	for aliases before sending mail to dbmail (pipe or LMTP). This can 
	improve performance, especially on a high-traffic server (SPAM!).
	In the case of the use of dbmail-smtp, this is especially useful,
	because it saves a process starting up and connecting to the database 
	on every message.

	To use MySQL or PostgreSQL with Postfix, first install the 
	postfix-mysql or postfix-pgsql packages (they're in Debian, probably 
	also in other distros). 

	Create a file in your Postfix config directory (/etc/postfix), with
	the name sql-recipients.cf, and put the following in it:

	user = <username>
	password = <password>
	hosts = <dbhost>
	dbname = <dbname>
	table = dbmail_aliases
	select_field = alias
	where_field = alias

	Where you replace <username>, <password>, <dbhost> and <dbname> by the
	database username, password, host and name of the dbmail database.

	Now we need to tell Postfix to use this file. Add the following line
	in main.cf:

	local_recipient_maps = mysql:/etc/postfix/sql-recipients.cf

	This tells Postfix to use the database to check if a recipient is 
	present in the database. Postfix will refuse the message  if a 
	recipient is not present.

5.	Notes
	
	It's possible to use dbmail-lmtp on same domains, and dbmail-smtp on
	other domains. Just make both entries in /etc/postfix/master.cf and
	add transport entries for both.