Virtual Exim 2 README ========== Thanks for picking the Virtual Exim package, for your virtual mail hosting needs :-) This README provides a basic guide on how to get Virtual Exim working on your system. You will need to have all of the listed packets (Apache, and SQL database, etc) already installed and configured. If you would like a complete step-by-step guide on how to install each package, please follow the INSTALL file. There are a few requirements (listed below), and it is expected that you have *a little* knowledge of both MySQL and Exim. Before we go into any details, I'd like to thanks Philip Hazel and the Exim developers for a fine product. I would also like to thanks the postmasters at various domains for letting me play havoc with their mail while I set this up :-) Finally, a special note of thanks to Dan Bernstein for his Qmail MTA. Dan, thank you for educating me how mail delivery really shouldn't be done, on the Internet. You can always find the latest version of this software from: WEB: http://silverwraith.com/vexim This is the mail Virtual Exim website CVS: :pserver:firstname.lastname@example.org:/home/cvs password: anonymous This is the mail Virtual Exim CVS repository Requirements: The following packages must be installed on your system, for VExim to work: * Exim v4 compiled against mysql (tested on v3.23.x/v4.1x/4.2x) * Mysql (tested on v3.23.x/v4.0.x/4.1x/4.2x) * Apache (Tested in 1.3.27) * PHP v4 (tested on v4.3.x) + pear-DB * Perl + DBI module for creating the databases (optional) * Perl DBD-mysql or DBD-Pg modules for creating databases (optional) This might work on older versions of MySQL or PostgreSQL. This should work on versions of PHP back to 4.2.1, but not older (due to the use of global variables like $_POST). I have no idea about older versions of Exim, as I've never used them myself. You can try though if you know the configure file. You can create the MySQL databases without the perl script if you want, but if you are upgrading from VExim 1.x you will need it Installation steps for each component: NOTE FOR UPGRADING: If you are upgrading from a previous version of Virtual Exim, please follow the notes for 'UPGRADING' in each section! PARTS: Files and Apache Exim configuration MySQL Site Admin Virtual Domains Mailman Mail storage and Delivery POP3 and IMAP daemons (separate to this software) Files and Apache: In this distribution is a directory called 'vexim'. You have two options: 1) Copy this directory into your current DocumentRoot for your domain, and optionally rename the directory. 2) Set up a new VirtualHost and point the DocumentRoot to the vexim directory. Both should work equally well. UPGRADING: The above directions should work for users who are upgrading their installation Exim configuration: An example exim 'configure' file, has been included with this distribution as 'docs/configure'. Copy this to the location Exim expects its configuration file to be on your installation. You will also need to copy docs/vexim* to /usr/local/etc/exim/ The following lines are important and will need to be edited if you are using this configure, or copied to your own configure: MAILMAN_HOME=/usr/local/mailman MAILMAN_WRAP=MAILMAN_HOME/mail/mailman *** Edit these if your mailman is in a different location. ---------- MAILMAN_USER=mailnull MAILMAN_GROUP=mail *** These need to match the username and group under which exim runs ---------- primary_hostname=mail.silverwraith.com *** This is my mail server. There are many like it, but this one is mine. Make this like yours. ---------- # If you are using MySQL, uncomment the following two lines: #VIRTUAL_DOMAINS = SELECT DISTINCT CONCAT(domain, ' : ') FROM domains type = 'local' #RELAY_DOMAINS = SELECT DISTINCT CONCAT(domain, ' : ') FROM domains type = 'relay' ----- # If you are using PGSQL, uncomment the following four lines: #VIRTUAL_DOMAINS = SELECT DISTINCT domain || ' : ' FROM domains WHERE type = 'local' #RELAY_DOMAINS = SELECT DISTINCT domain || ' : ' FROM domains WHERE type = 'relay' *** Depending on the database type you are using, you will need to uncomment the appropriate lines in the config, to enable lookups. ---------- hostlist relay_from_hosts = 127.0.0.1 : 220.127.116.11 *** These control which domains you accept mail for and deliver locally (local_domains), which domains you accept mail for and deliver remotely (relay_to_domains), and which IP addresses are allowed to send mail to any domain. ---------- exim_user = mailnull exim_group = mail *** Specify here, the username and group under which Exim runs. This combination is also that under which mailman must run in order to work. ---------- # av_scanner = clamd:/tmp/clamd # spamd_address = 127.0.0.1 783 *** If you want to use either Anti-Virus scanning, or SpamAssassin, you will need to uncomment the appropriate line here. ---------- #hide mysql_servers = localhost::(/tmp/mysql.sock)/vexim/vexim/CHANGE *** This line configures database connectivity. You need to uncomment it and change the word 'CHANGE', to the password you will use for the 'vexim' database user, which we will set up in the next part. Also it is assumed that the mysql domain socket is /tmp/mysql.sock, which is where the FreeBSD port puts it. Other installations put it in /var/tmp, /usr/lib, or any number of other places. If yours isn't /tmp/mysql.sock, you will need to set this. ---------- ACL's *** We have split all of the ACL's into separate files, to make managing them easier. Please review the ACL section of the configure file. If there are ACL's you would rather not have executed, please comment out the '.include' line that references them, or edit the ACL file directly and comment them out. UPGRADING: The above directions should work for users who are upgrading their installation Databases and Authentication: When creating the databases you have two options. You can either use the SQL command files, or the perl script. If you are creating new databases, I *HIGHLY* recommend you use the SQL command files. They are much simpler. However, if you are migrating from Virtual Exim 1.x to 2.x, you will need to use the perl script to migrate the data. MySQL: If you want to create new MySQL databases, edit the setup/mysql.sql file and change the first two instances of the word 'CHANGE', to the default system UID and GID you want new domains to have if one is not specified. Change the third instance of the word 'CHANGE' to the password you want the 'vexim' database user to have. This is the same password you chose when editing Exim's configure file above. You also need to know if your system uses MD5 or DES passwords. BSD and Linux normally use MD5, whereas Solaris systems commonly use the older style DES. Uncomment the appropriate line, as noted by the comments, at the end of mysql.sql. Save the file, and run: mysql -u root -p < mysql.sql This should create the database and add the right users. The password you are prompted for when doing this should be your MySQL database's root user password. Finally, you will need to edit: vexim/config/variables.php Change the password for the vexim user as noted by the word 'CHANGE'. Set this to the same password that you chose in mysql.sql, and change the '$cryptscheme' line to either "md5", or "des" depending on what your operating system uses. The last change t0 make in that file is the '$uid' and '$gid'. Make these the same default UID and GID you chose in mysql.sql. PGSQL: The code has been tested by several users to work with Virtual Exim, and we try our best to make sure it always will. Unfortunately I don't have much PostgreSQL knowledge to support it fully. A database schema for it is included however, as setup/pgsql.sql to help you set up the database. UPGRADING: If you are upgrading your installation you will need to use the perl script. Executing it as: create_db.pl --act=migratemysql --dbtype=mysql --uid=90 --gid=90 --mailstore=/usr/local/mail should work fine. Change the 'uid' 'gid' and 'mailstore' to the default values you want to assign in the database. These should match the values in 'variables.php'. Site Admin: In order to add and delete domains from the database, you need to have a "site admin". This users can create the initial postmaster users for the individual domains. The default username and password for the siteadmin, are: Username: siteadmin Password: CHANGE The password is case sensitive. I recommend you log in and change this when you get a chance :-) UPGRADING: The above directions should work for users who are upgrading their installation Virtual Domains: Virtual Exim can now control which local domains Exim accepts mail for and which domains it relays mail for. The features are controlled by the siteadmin, and domains can be easily added/removed from the siteadmin pages. Local domains can also be enabled/disabled on the fly, but relay domains are always enabled. UPGRADING: The above directions should work for users who are upgrading their installation Mailman: Mailman needs to be installed if you want to use mailing lists. The default location is assumed to be /usr/local/mailman. If this is not the location of your installation, edit Exim's configure file, and change the paths where ever 'mailman' is mentioned, and do the same in vexim/config/variables.php UPGRADING: The above directions should work for users who are upgrading their installation Mail storage and Delivery: The mysql configuration assumes that mail will be stored in /usr/local/mail/domain.com/username/Maildir. If you want to change the path from '/usr/local/mail/', you need to edit the file: vexim/config/variables.php and change 'mailroot' to the correct path. Don't forget the / at the end. UPGRADING: The above directions should work for users who are upgrading their installation POP3 and IMAP daemons: There are many POP3 and IMAP daemons available today. Few of them are good, and fewer of those like MySQL. Two that we have found that work are: POP3 Only: Qpopper IMAP and/or POP3: The Courier-IMAP package Instructions for installing these have been included in this tarball in the following files: Qpopper: docs/clients/qpop-mysql.txt Courier-IMAP: docs/clients/freebsd-courierimap.txt (FreeBSD HOWTO) These documents are pretty clear and you should be able to use them as a template when compiling from source on most Unixes. Just remember the switches on 'configure' scripts for enabling mysql support :-) Instructions for configuring Cyrus and Cyrus IMAP are also available. However, we have not tested these so cannot guarantee they work. If you have success or problems with these instructions, please let us know! Cyrus: docs/clients/cyrus.txt UPGRADING: If you are upgrading, you will need to update your configs for your POP/IMAP daemons, as the database layout has changed. You should be able to follow the above instructions without problem.