/* $Id: INSTALL,v 1.19 2003/06/10 05:13:39 roel Exp $ 
   (c) 2000-2002 IC&S, The Netherlands */

DBMAIL installation
===================

This file describes the installation of DBMail. To read about extra 
features in dbmail you should consult the EXTRAS file.
Remember, DBmail is easy to install, as long as you exactly follow
these instructions.

What do you need?

- a working mysql or postgresql installation
- a working smtp server (postfix, exim or sendmail)
- the dbmail source (www.dbmail.org)


1.	Setup a database

	Currently,  DBMail supports both MySQL and PostgreSQL for mailstorage. 

	Mysql setup
	-----------

	Note: Since some DBmail tables can get VERY large (depending on your mailusage)
	we advise using InnoDB as database storage backend (included in the Mysql MAX
	package.).
	
	First you'll need to create the DBMAIL database in MYSQL.
	This is easy. You'll need the mysql commandline program for this. 
	Just do :
	
	mysql -u root -p < sql/mysql/create_tables.mysql
	
	for InnoDB:

	mysql -u root -p < sql/mysql/create_tables_innoDB.mysql
	
	in the dbmail source tree.
	After this, the DBMAIL tables will have been created.


	Postgresql setup
	----------------
	
	First you need to create the postgresql user dbmail is going to use. This
	is done by:

	createuser -U postgres dbmail

	Off course you can use an other username than dbmail, simply replace it. You
	can set a password for the user by doing a:

	ALTER USER dbmail WITH PASSWORD 'secret';

	In a postgresql console. After doing this you should create the database for
	dbmail:

	createdb -U dbmail dbmail

	The first dbmail is the user you just created, the second the name of the database. 
	Off course you can use an other databasename. After setting up the user and database
	it's time to create the tables, do a:

	psql -U dbmail dbmail < sql/postgresql/create_tables.pgsql

	Don't forget to start postgresql with the -i option, so it accepts TCP/IP connections.


2. 	Set the database settings

	Copy the dbmail.conf file to /etc
	Edit the dbmail.conf file and set everything in there
	to your likeings.

3.	Run build.sh

	If you want to use md5 hash passwords, you need to make sure the crypt() you link
	in supports them.  For most people this amounts to linking in GNU libc's libcrypt
	via entering -lcrypt instead of -lcrypto.

4.	Create users in the dbmail system

	Next you will need to create some users into the dbmail mailing sytem.
	Currently this can be done in two ways. One way is using the dbmail-adduser
	utility. The other way is doing it in the database itself. 
	To do it using the dbmail-adduser utility and do the following:

	dbmail-adduser a <username> <password> <clientid> <maxmail> [aliases]
	
	clientid can be left 0 (this is if you want certain mailadministrators administer 
	specific groups of mailusers). maxmail is the maximum number of bytes this user may
	have in his/her mailboxes. 0 is unlimited. 
	aliases are a number of aliases for this user. @domain are domain aliases.
	A user always needs to have at least one alias to receive mail. 
	
	example: 
	./dbmail-adduser a john secret 0 25000000 john@dude.org john@dude.net @net.com
	
	This will create a user john, with a password secret. It will set john's maillimit
	25 Mb and all mail for john@dude.org, john@dude.net and @net.com will be sent to john.
	The @net.com is a fallback alias. This means that all mail that cannot be delivered to
	an existing alias for a @net.com address will sent to john.

5.	
	Become root and run install-dbmail.sh, it will install the dbmail executables.
	This is not necessary if you have installed the binaries at step 4.


6.	Configure your MTA 

	-- MTA installation for postfix --
	
	In the master.cf file for postfix add the following:
	
	dbmail    unix  -       n       n       -       -       pipe
	    flags=  user=dbmail:dbmail argv=/usr/local/sbin/dbmail-smtp -d ${recipient}

	at the user= field you can add any user that is allowed to run dbmail-smtp. 
	I suggest adding a user dbmail with a group dbmail and have all dbmail programs 
	be run by that user. The dbmail daemons (pop and imap) will drop their root
	priviledges to the user which is defined in /etc/dbmail.conf.

	and insert into the /etc/postfix/transport file 

	<domain>		dbmail:

	for all domains you want dbmail to be destination for.
	
	Next run postmap /etc/postfix/transport

	Edit /etc/postfix/main.cf and add the line 
	transport_maps = hash:/etc/postfix/transport

	do a postfix reload and if everything goes well 
	mail should be delivered to dbmail. If not, try running 
	postfix with the -v option to see what's going on. If the 
	problem seems to be in dbmail, try changing the tracelevel in dbmail.conf.
	Tracelevel 5 will return a lot of debugging information.

	--	MTA installation for qmail -(thanks to Edward Allen)-

	Add your domain to /var/qmail/control/rcpthosts.  My
	file looks like:

	/var/qmail/control/rcpthosts:
	squeakerbill.com

	Next, add your domain:dbmail_user_name to /var/qmail/control/virtualdomains
	My file looks like:

	/var/qmail/control/virtualdomains:
	squeakerbill.com:dbmail

	Make sure the file /var/qmail/control/locals exists and is empty!

	Now create a file in the dbmail home directory called .qmail:

	 ~dbmail/.qmail:
	|/usr/local/sbin/dbmail-smtp -d ${RECIPIENT:7}

	The pipe tells qmail to pipe the email through a command.  The ${RECIPIEN
	T:7} takes the Environement Variable $RECIPIENT and chops off the first
	seven characters.  This is needed because the value of RECIPIENT is
	dbmail-the_email_address.  If your dbmail user is not dbmail, you'll need
	to change the 7 to the number of characters in your dbmail users's name plus
	one.  The other approach, I guess, would just be to add a dbmail alias of
	the form dbmail-allenej@squeakerbill.com for each user...

	It's that simple.  If you have any questions about qmail and dbmail, I'll
	try to answer them.  Keep in mind that I am new to dbmail.

	------------------------------------------------------------

	If you use a different kind of mta: The dbmail injector program, dbmail-smtp,
	can receive information in two ways. Either through raw mail (for example, 
	delivered by procmail) using the -n option or from a MTA with recipients 
	in the commandline using the -d option. Be carefull, the -n option is not fully 
	tested and may behave unexected. If possible use the -d option.

7.	Setting up the maintenance run

	The dbmail daemons and the smtp injector itself will never actually delete 
	mail from the database. The only program that will do this is the
	dbmail-maintanance program. This program will also check the integrity of 
	the dbmail database and, if nescessary, fix it.
	The dbmail-maintenance program will first delete all messages that are 
	set for final deletion. After that it will set all messages that have
	the delete status set to status final deletion. This way dbmail always has
	a backup based upon the interval difference between maintenance jobs. 
	We recommend running the dbmail-maintenance program in a daily interval
	from cron:

	0 3 * * * /usr/local/sbin/dbmail-maintenance -cfpd >> /dev/null 2>&1
	

	For problems you can subscribe to the dbmail mailinglist: 
	http://mailman.fastxs.nl/mailman/listinfo/dbmail
	
	Please always check the archives first.

	or check out the dbmailwebsite at http://www.dbmail.org.
