/* $Id: INSTALL,v 1.27.2.1 2004/09/08 13:59:32 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 (> 4.0.14) or postgresql installation
- a working smtp server (Postfix, Exim, QMail or Sendmail)
- the DBMail source (www.dbmail.org)
- GNU Make. On Linux systems, your standard 'make' program is GNU Make. On
  *BSD systems, make sure you install and use 'gmake'. 


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. You can
	do this by issueing the following command. This step is only
	necessary when you do not have a database for DBMail yet. Note that
	you will be prompted for the MySQL root password.

	mysqladmin create dbmail -u root -p

	This creates a database with the name "dbmail". Now you have to give
	a non-root user access to this database. Start the MySQL command-line
	client as root:

	mysql -u root -p 

	and enter the following command:

	GRANT ALL ON dbmail.* to dbmail@localhost identified by '<pass>'

	Where <pass> should be replaced with the password you want for
	the dbmail user. After this step, the database is ready to be
	used by the dbmail user. The next step is the creation of the
	database tables used by DBMail. Log out of the MySQL client and run 
	the following command from the command line. You will have to
	enter the password you set in the previous step.

	mysql -u dbmail dbmail -p < sql/mysql/create_tables_innoDB.mysql

	If you cannot use InnoDB, replace creates_table_innoDB.mysql by
	create_tables.mysql. This is not recommended though. In future
	versions, DBMail will only support MySQL with transaction support,
	which is only given by InnoDB at the moment.
	
	After this, the DBMAIL tables will have been created and we can go
	on to the compilation and installation of DBMail itself.

	Postgresql setup
	----------------
	
	First you need to create the postgresql user dbmail is going to use.
	This is done by. Note that this command can only be performed by
	user postgres or another PostgreSQL user with the privileges to
	create users and and databases.

	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 '<password>';

	In a postgresql console, with <password> replaced by the actual 
	password you want to use. 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.  Of 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.

	Make sure to set your database name, user and host are configured
	in dbmail.conf. Other options in the configuration file are 
	documented there.

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.

	e.g. when working with PostgreSQL, this is the configure command:

	./configure --with-pgsql

	After running configure, 'make all' will build the executables.
	
	Running 'make install' 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-users utility. The other way is doing it in the database
	itself. To do it using the dbmail-users utility and do the following:

	dbmail-users -a <username> -w <password> -g <clientid>\
	             -m <maxmail> [-s 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. Add K or M for kilobytes and megabytes. 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, unless
	the users username is something like foo@bar.org, where bar.org is 
	a domain the mailserver deliveres to.
	
	example: 
	./dbmail-users -a john -w secret -g 0 -m 25M\
	               -s 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.	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-lmtpd. LMTP is the preferred solution because it offers more
	robust error handling and because it is a daemon, high traffic servers
	will have reduced delays which would be incurred starting up a
	dbmail-smtp process for each message.

	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.

	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.

	Setup for LMTP should be straightforward if your MTA supports it.

6.	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-util program. This program will also check the
	integrity of the dbmail database and, if nescessary, fix it. The
	dbmail-util 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-util program in a daily
	interval from cron:

	0 3 * * * /usr/local/sbin/dbmail-util -c -r f -p -d >> /dev/null 2>&1
	
7.	Starting the servers

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

8.	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 dbmail website at http://www.dbmail.org.

	Please note that DBMail logs a lot of relevant data to the maillog
	(often 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.  


