INSTALL

/*
 (c) 2000-2004 IC&S, The Netherlands 
 (c) 2004-2012 NFG Net Facilities Group BV, The Netherlands, support@nfg.nl

FIXME: this information is somewhat outdated
TODO:
tell more about where to find what library
add information about utf8 setups for mysql users
add information about advanced setups with connection pools

*/

DBMAIL Installation
===================

What do you need?

- A working database, one of the following:
  - MySQL 5.0 or higher with InnoDB.
  - PostgreSQL 8.3 or higher.
  - SQLite 3 or higher.
  - Oracle 11.1 or higher.
- A working SMTP server (such as 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'. 
- Development files (libs, scripts and include files) for your database server.
  These will probably be provided by separate packages.
- Glib (>= 2.16) development headers and libraries.
- Gmime (>= 2.4) development headers and libraries.
- libSieve (>= 2.2.1) for Sieve support (libsieve.sf.net).
- Any standard libldap for LDAP support (only tested with OpenLDAP, however).
- mhash
- openssl
- libzdb (http://www.tildeslash.com/libzdb/)
- libevent


1.	Setup a database

	MySQL setup
	-----------

	First you'll need to create the DBMail database in MYSQL. You can do
	this by issuing 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.mysql

	After this, the DBMAIL tables will have been created and we can go
	on to the compilation and installation of DBMail itself.

	A special note to MySQL users: since DBMail 3.0 stores attachments in
	single rows, you need to set 'max_allowed_packet' in /etc/mysql/my.cnf 
	to a value that is larger than the largest email attachment you expect 
	to support.

	So if you accept emails upto say 20MB, you should set a value for
	'max_allowed_packet' of no less than 21MB, leaving some room for 
	network overhead. If you want to be safe: use 1.5 times the max 
	message size.


	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 -E utf8 -U postgres -O 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 database name. After
	setting up the user and database it's time to create the tables, do a:

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

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

	Finally, if you run PostgreSQL 9 or later you must make sure your
	postgresql.conf contains the following setting:

	bytea_output = 'escape'

	because DBMail can't handle the default 'hex' type output.	

	SQLite setup
	------------

	FIXME: this doesn't work in 3.0 (yet/anymore)

	Dbmail will automatically create the database specified in dbmail.conf. 
	All you need to do is make sure that the directory which will contain
	the database file exists, and is writable for the dbmail user.
	
	Oracle setup
	------------
	First create Oracle table spaces for DBMAIL schema. You can use as
	example script sql/oracle/dbmail_ts.sql. In case when you are performing
	this action on server where Oracle DB is installed you can invoke the
	script in following way

	sqlplus "/ as sysdba" @dbmail_ts.sql 

	Note that most likely you will need to alter this script in order to set 
	storage	limit values in way which meet your storage requirement/size. 

	Don't forget that for script execution you should have configured environment 
	with ORACLE_HOME, ORACLE_SID, ORACLE_BASE variables set. 

	Then create DBMAIL user:

	sqlplus "/ as sysdba" @sql/oracle/dbmail_grant.sql 

	If you need to you can change DBMAIL user name in this script. Also
	please note that the script will drop previously created DBMAIL user
	and schema. 

	After that you can upload DBMAIL data schema:
	sqlplus dbmail/dbmail @sql/oracle/dbmail_schema.sql 
	Please note that you should execute dbmail_schema.sql using 'dbmail'
	user instead of DBA user.

	However depending on you DB configuration you may need to perform 
	slightly other or some additional steps to properly configure DB
	storage and connectivity options so please ask Oracle DBA to assist you. 


2. 	Set the database settings

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

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

	dbmail.conf settings for Oracle (remote access)
	-----------------------------------------------
	First you should set up environment variable $ORACLE_HOME with path to Oracle
	instant client on your DBMAIL host.
	There is at least two possible way to fill DB connection options in dmail.conf. 
	1) You can configure dbmail.conf without using tnsnames.ora and Oracle services.
	In such case you should specify in 'host' and 'sqlport' a host and port where
	Oracle TNS listener accept connections. 'db' parameter should contain DBMAIL
	schema name.

	2) Or if you have Oracle Service configured for access to DBMAIL
	schema and this service described in $ORACLE_HOME/network/admin/tnsnames.ora
	then you should configure only following values in dbmail.conf - 'user', 'pass'
	and 'db'. 'db' option should contain service name. Options 'host' and 'sqlport'
	should be empty.
	E.g. 
	tnsnames.ora:
		DBMAIL_SRV = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)
			(HOST = 1.1.1.1)(PORT = 4521))
			(CONNECT_DATA = (SERVER = DEDICATED)(SERVICE_NAME = DBMAIL_SRV)
			(FAILOVER_MODE = (TYPE = SELECT)(METHOD = BASIC))))
	dbmail.conf:
		host =
		sqlport =
		user = dbmail
		pass = dbmail
		db = DBMAIL_SRV
	

3.	Run configure & make
	Run the configure script.

	e.g. 

	./configure --with-sieve 

	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 system.
	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 mail administrators
	administer specific groups of mail users). 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 mail server delivers 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 mail limit 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-deliver 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-deliver process for each message.

	The specifics of delivering to DBMail from your MTA can be found in the
	README.<MTA Name> files. Currently there is documentation for Postfix,
	Exim and QMail. Other setup information can also be found on the
	project wiki, at http://www.dbmail.org/dokuwiki

	If you use a different kind of MTA that we do not have documentation
	for: The dbmail injector program, dbmail-deliver, 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
	command line using the -d option. Be careful, the -n option is not
	fully tested and may behave unexpected. 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 necessary, 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 -ay &>/dev/null
	
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. If you are delivering email via
	LMTP, run dbmail-lmtpd (you should start LMTP before your MTA!).

8.	Problems
	--------
	For problems you can subscribe to the dbmail mailing list: 
	http://mailman.fastxs.nl/mailman/listinfo/dbmail
	
	Please also check the mailing list archives,
	the wiki at: http://www.dbmail.org/dokuwiki
	and the bugs at: http://www.dbmail.org/mantis

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