/* $Id: INSTALL,v 1.23 2004/03/19 15:04:19 ilja 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
	is supported from version 4.0.14 upwards. Earlier versions of MySQL lack some
	SQL features that are needed for DBMail, like support for the INSERT...SELECT
	statement.

	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 configure & make
	Run the configure script. This script uses pg_config or mysql_config (depending on
	--with-mysql or --with-pgsql) to detect where the libraries and include files
	for these databases are.

	After running configure, a 'make all' should suffice to build the executables.
	Running install-dbmail.sh will install the executables in /usr/local/sbin
	
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 

	There are two ways to connect your MTA to DBMail. The MTA can start a 
	dbmail-smtp process and pipe SMTP commands and messages to it, or it can
	use lmtp (Local Mail Transport Protocol) to deliver via dbmail-lmtp. The
	preferred solution, especially for high traffic servers, it to use dbmail-lmtp,
	because it is does not have to start a new process on every delivery, thereby
	saving resources.

	The specifics of delivering to DBMail from your MTA can be found in the
	INSTALL.<MTA Name> files. Currently there is documentation for Postfix and
	Exim.

	You have a choice here between using dbmail-smtp or dbmail-lmtp here. If you are
	using Postfix, the preferred solution is to use dbmail-lmtp, especially on high
	traffic servers. The reason for this is that dbmail-smtp will start a new process
	for every delivery, which takes more time than using dbmail-lmtp, which uses a 
	daemon that your MTA connects to.
	
	Please note that if you use LMTP, the dbmail-lmtp daemon (dbmail-lmtpd) needs 
	to be running in order to be able to deliver mail.

	If you use a different kind of mta that we do not have documentation for: 
	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.

	If your MTA supports LMTP for delivery, setup should be quite straightforward.

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
	
8.	Starting the servers

	If you want users to be able to retrieve email via IMAP or POP3, run
	dbmail-imapd and/or dbmail-pop3d

9.	Problems
	--------
	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.

	Please note that DBMail logs a lot of relevant data to the maillog (mostly
	located at /var/log/maillog or /var/log/mail.log). This can help you often
	if something is not working, e.g. if there's no connection to the database.

