Exim4U Installation Guide This installation Guide is designed to take you through the steps necessary for installing Exim4U and all of its dependent software. These days, most of the dependent software that is to be installed is included in the repositories of the major Linux vendors such as RedHat, CentOS, Debian, Ubuntu, etc. Therefore, detailed instructions for compiling, configuring and installing the various dependent packages from source is not included. Please note that Exim4U was developed on a CentOS system and we have included some references to RedHat/CentOS where applicable. However, Exim4U and all of its dependent software packages should install and run just fine on any of the other major Linux and Unix distributions as well. 1. Install and configure the following packages: * Apache - Tested with Version 2.2.3 thru 2.4.12. * MySQL - Tested with Version 5.0.77 thru 5.6.24. * SQLite - Tested with Version 3.3.6 thru 3.8.9 (SQLite3). * PHP - Tested with Version 5.1.6 thru 5.6.8. * Perl - Tested With Version 5.8.8 thru 5.18.4. * php-pdo - Tested with Version 5.3.29 thru 5.6.8. * php-openssl - Tested with Version 5.3.29 thru 5.6.8. * php-imap - Tested with Version 5.3.29 thru 5.6.8. Note: php extensions, such as php-pdo, php-openssl and php-imap, may use a slightly different prefix, such as php5-pdo instead of php-pdo. Also, some distributions include some or all of these php extensions with the base php package. Use "php -m" to see exactly what php extensions are included on your installation. You should also consider running your own DNS nameserver by installing bind9/named. While this is not an absolute requirement, Exim4U's URI Block List lookups are DNS lookups and some of the URI blocking servers (specifically URIBL) will deny querries from large volume servers, such as large ISPs, that issue millions of queries daily. So, it is best to implement and use your own bind9/named DNS nameserver. Otherwise, if you depend on someone elses nameserver, such as a large ISP's nameserver, then you may end up having your lookups denied which can potentially cause erroneous mail rejections. 2. Install: ClamAV (Clamd and Freshclam) - Tested with Version 0.98.4 thru 0.98.6. Configure /etc/freshclam.conf and /etc/clamd.conf. Make sure and specify the TCP socket as 3310 for clamd in /etc/clamd.conf: TCPSocket 3310 Otherwise, without the TCPSocket specified, Exim4U's exim configuration will not specify the ClamAV version in the mail headers. Normally a header will be added that starts with this: X-Scanned-By: ClamAV 0.95.3 . . . . . If the mail headers don't include a line that starts as above then the TCPSocket variable has probably not been set in /etc/clamd.conf. Add to /etc/rc.local: /usr/bin/freshclam --daemon & 3. Install: SpamAssassin - Tested With Version 3.3.2 - 3.4.1. Refer to the SPAMASSASSIN help file in the docs directory of this Exim4U distribution. 4. Install: Exim - Tested With Version 4.69 thru 4.85. Install Exim, preferably a recent version. If you are installing from scratch, exim must be compiled with MySQL, SQLite, spf, DKIM and the embedded Perl engine enabled. Copy Exim4U's exim configuration files from etc/exim/* to the target machine. All files in this directory should be copied to /etc/exim. Then, change user and group ownerships to root for all files copied to /etc/exim. From within the etc/exim directory in this distribution (as user = root) execute: cp -r * /etc/exim After copying files to /etc/exim then (as user = root) execute: chown -R root:root /etc/exim/* The primary file that needs to be edited for specifying site specific information is exim4u_local.conf.inc. This file is self documented so just read through the file and specify the appropriate information as detailed therein. The main exim configuration file for exim4u is /etc/exim/exim.conf which is typically not modified. The configuration files required in the /etc/exim directory for exim4u to work properly are described as follows: exim4u_acl_check_dkim.conf.inc - DKIM ACL include file. exim4u_backup_mx_host_names - Backup MX host names to be excluded from all spam checks. exim4u_backup_mx_rl_host_names - Backup MX host names to be excluded from rate limiting only. exim4u_global_spam_virus - SpamAssassin and ClamAV settings. exim4u_hostnames+hostIPs - Local host names and IP addresses. exim4u_IPblacklist - Blacklisted IPs here. exim4u_IPskip_sender_verify - IPs for which to omit verification of senders email address. exim4u_IPwhitelist - Whitelisted IPs here. exim4u_local.conf.inc - Site specific information. exim4u_local_rl.conf.inc - Sender ratelimit include file. exim4u_relay_from_hosts - IP addresses of hosts which can use our host as an outgoing relay. exim4u_sender_rl_addr - Sender email addresses to be exempted from sender ratelimit checks. exim4u_sender_rl_dom - Sender IP addresses to be exempted from sender IP ratelimit checks. exim-acl-check-spf.conf.inc - SPF include file. (Usually not modified) exim.conf - Main exim configuration file. (Usually not modified) exim-greylist.conf.inc - Greylisting include file. (Usually not modified) exim-group-router.conf.inc - Group router include file. (Usually not modified) exim-mailinglist-router.conf.inc - Router for the Exim4U Simple Mailing List. exim-mailinglist-transport.conf.inc -Transport for the Exim4U Simple Mailing List. exim.pl directory - Perl script and files for URIBL/SURBL/DBL checks. (Usually not modified) All of the above files whose name begin with "exim4u_" should be modified to include appropriate site specific configuration options. Refer to the EXIM_README document regarding Exim4U compatibility with various Exim versions and to determine which exim.conf version to install on your mail server. Choose from: - exim versions prior to 4.83 should use: etc/exim/exim.conf-SINGLE_COLONS_IN_HEADERS_REMOVE - exim 4.83, 4.84 and 4.85 should use: etc/exim/exim.conf-HEADERS_REMOVE_WITH_COLONS_COMMENTED_OUT - exim versions after exim 4.85 should use: etc/exim/exim.conf-DOUBLE_COLONS_IN_HEADERS_REMOVE exim.conf is identical to etc/exim/exim.conf-DOUBLE_COLONS_IN_HEADERS_REMOVE and which should be used for exim versions after exim 4.85. If you decide to use clear-text passwords (not recommended) then you must edit and modify the Authentication Configuration at the end of etc/exim/exim.conf on lines 1425 thru 1433 as described therein. Refer to the etc/exim/exim.pl/README2 document and configure crontab entrys to update the three-level-tlds and two-level-tlds files in the etc/exim/exim.pl directory for the URIBL/SURBL/DBL checks. Create the SQLite database (SQLite3) for greylisting. You can do this with the sqlite3 command. The sqlite3 script for setting up the greylisting database is named mk-greylist-db.sql and it is in the xtrasw/exim-greylist directory of this distribution. You must also ensure that it's owned by the Exim user/group. To create the database and set the correct ownership execute: sqlite3 /var/spool/exim/db/greylist.db < xtrasw/exim-greylist/mk-greylist-db.sql chown exim:exim /var/spool/exim/db/greylist.db Note that this command assumes that the greylist.db file is located in the /var/spool/exim/db directory. You may change the location as per your exim installation, however, you must then also modify etc/exim/exim-greylist.conf.inc and xtrasw/exim-greylist/greylist-tidy.sh to specify the location of greylist.db within those two scripts as well. Install the script xtrasw/exim-greylist/greylist-tidy.sh in cron.daily to prevent the database from growing forever without bound. This script simply deletes entries from the greylist table that are older than 7 days: cp xtrasw/exim-greylist/greylist-tidy.sh /etc/cron.daily Install perl-Mail-SPF-Query. This perl module may be downloaded from the CPAN site at: http://search.cpan.org/dist/Mail-SPF-Query/ To install the perl tarball: gzip -dc Mail-SPF-Query-1.999.1.tar.gz | tar -xof - cd perl-Mail-SPF-Query-1.999.1 perl Makefile.PL make make test make install Put the following command in rc.local: /usr/bin/spfd.perl-msq -path=/tmp/spfd --socket-user exim --socket-group exim --set-user exim & Install the script xtrasw/exim-tidydb/exim-tidydb in cron.daily to prevent the exim databases from growing forever without bound. This script simply deletes older entries from the database: cp xtrasw/exim-tidydb/exim-tidydb /etc/cron.daily Update etc/exim/exim.pl/surbl_whitelist.txt to include any URLs that you want whitelisted from the URIBL/SURBL/DBL checks in exim and add the etc/exim/exim.pl/README2 script to your root user's crontab. 5. Configure mysql You must create a new MySQL database for Exim4U. You may do this either interactively (which is easiest) or manually. To set the database up interactively simply run the mysql_setup/mysql.sh bash shell script, which will prompt with a few questions, and then set the database up for you automatically. Afterward, make sure to immediately proceed to Step 6, login to the Exim4U web interface and change the siteadmin password from 'PASSWD' to some other secure password. If you created the MySQL database interactively then skip the remainder of this section and proceed to Step 6. Alternatively, if you prefer to set the MySQL database up manually, then proceed as follows. First, edit the mysql_setup/mysql.sql file to match your configuration and then run it manually within MySQL. You must edit the mysql_setup/mysql.sql file and change the first two instances of the word 'CHANGE' to the default system UID and GID to be used for new domains if one is not specified. Most installations opt to create a user and a group both named exim4u and then use the UID and GID for exim4u. Change the third instance of the word 'CHANGE' to the password you want for the exim4u database user. This is the same mysql password you chose when editing /etc/exim/exim4u_local.conf.inc above. Then, you must decide which type of encryption that you will use. Exim4u supports SHA512, MD5 and DES password encryption along with clear-text passwords (although not recommended). Most recent Linux and BSD versions generally support SHA512 which is considered most secure. Some older distributions may use the older MD5 or DES encryption. The default password that is installed by both the interactive mysql.sh script and the manual mysql.sql script is "PASSWD" and lines 160 - 170 of mysql_setup/mysql.sql are used to specify the password, "PASSWD", as encrypted in SHA512, MD5 or DES or as a clear-text password. If you are using SHA512 then lines 160 - 170 should be set to: -- SHA512 encryption of 'PASSWD' for crypt field: '$6$4HTy8Ts3TvC1$FFAVbY1N3nKiuYi7eV3DQ0clbGS9MYrVEOjerUUQgc0sdYWfqceYbfLyPnBUK92soHAS15j.w7H05eDQn3erL/', -- -- MD5 encryption of 'PASSWD' for crypt field: -- '$1$12345678$JCW6RgxAyYiRf00lURaOE.', -- -- DES encryption of 'PASSWD' for crypt field: -- '0A/4rVI7XZP6Y', -- -- Clear-text password: -- 'PASSWD', Whereas if you are using MD5 then lines 160 - 170 should be set to: -- SHA512 encryption of 'PASSWD' for crypt field: -- '$6$4HTy8Ts3TvC1$FFAVbY1N3nKiuYi7eV3DQ0clbGS9MYrVEOjerUUQgc0sdYWfqceYbfLyPnBUK92soHAS15j.w7H05eDQn3erL/', -- -- MD5 encryption of 'PASSWD' for crypt field: '$1$12345678$JCW6RgxAyYiRf00lURaOE.', -- -- DES encryption of 'PASSWD' for crypt field: -- '0A/4rVI7XZP6Y', -- -- Clear-text password: -- 'PASSWD', Whereas if you are using DES then lines 160 - 170 should be set to: -- SHA512 encryption of 'PASSWD' for crypt field: -- '$6$4HTy8Ts3TvC1$FFAVbY1N3nKiuYi7eV3DQ0clbGS9MYrVEOjerUUQgc0sdYWfqceYbfLyPnBUK92soHAS15j.w7H05eDQn3erL/', -- -- MD5 encryption of 'PASSWD' for crypt field: -- '$1$12345678$JCW6RgxAyYiRf00lURaOE.', -- -- DES encryption of 'PASSWD' for crypt field: '0A/4rVI7XZP6Y', -- -- Clear-text password: -- 'PASSWD', Whereas if you are using clear-text, then 160 - 170 should be set to: -- SHA512 encryption of 'PASSWD' for crypt field: -- '$6$4HTy8Ts3TvC1$FFAVbY1N3nKiuYi7eV3DQ0clbGS9MYrVEOjerUUQgc0sdYWfqceYbfLyPnBUK92soHAS15j.w7H05eDQn3erL/', -- -- MD5 encryption of 'PASSWD' for crypt field: -- '$1$12345678$JCW6RgxAyYiRf00lURaOE.', -- -- DES encryption of 'PASSWD' for crypt field: -- '0A/4rVI7XZP6Y', -- -- Clear-text password: 'PASSWD', Note that you are simply including the encrypted password for the encryption method that you are using while also commenting out the encrypted passwords for the encryption methods that you are not using. Save the file, and run: mysql -u -p < mysql_setup/mysql.sql where: = Your MYSQL root username The script will then prompt you for your MYSQL root username's password. 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. For example, if = root Then, the command would be: mysql -u root -p < mysql_setup/mysql.sql This should create the database and add the right users. Make sure that you immediately change the siteadmin password from 'PASSWD' to some other secure password the first time that you login to the Exim4U web interface. 6. Install Exim4U's web interface and login to the Exim4U web interface. Exim4U's web interface is comprised of a set of php scripts located in: home/exim4u/public_html/exim4u First, copy home/exim4u/public_html/exim4u/config/variables.php.sample to home/exim4u/public_html/exim4u/config/variables.php. This file, variables.php, is your main configuration file for the Exim4U web interface. Now, edit home/exim4u/public_html/exim4u/config/variables.php and change the following settings. Change the '$sqlpass' on line 10 to the exim4u database user's password which you chose which setting up the MySQL database in the last step. Change the '$cryptscheme' line to either "SHA512", "MD5", or "DES" depending on your encryption scheme or "CLEAR" for clear-text passwords (not recommended). Another change to make in that file is the '$uid' and '$gid'. Make these the same default UID and GID you chose in mysql.sql. Then, specify $mailroot. The default value is: $mailroot = "/home/exim4u/mail/"; You must manually create the $mailroot directory and make sure that this directory belongs to the configured $uid and $gid. Copy home/exim4u/public_html/exim4u/* to a directory named exim4u within your webserver's document root directory. The files should be readable by apache but not writable by apache. For example; cp -r home/exim4u/public_html/exim4u/* /exim4u/ chown -R :apache /exim4u find /exim4u -type d -exec chmod 755 {} \; find /exim4u -type f -exec chmod 644 {} \; More specifically, with a DocumentRoot = /home/exim4u/public_html, then; cp -r home/exim4u/public_html/exim4u/* /home/exim4u/public_html/exim4u/ chown -R exim4u:apache /home/exim4u/public_html/exim4u find /home/exim4u/public_html/exim4u -type d -exec chmod 755 {} \; find /home/exim4u/public_html/exim4u -type f -exec chmod 644 {} \; The permissions on the /exim4u/sysconfig/variables.php file should be set so that the owner has read/write access, the group (apache) has read access and all other users have no access. For example: chmod 640 /exim4u/config/variables.php or, with a DocumentRoot = /home/exim4u/public_html, then; chmod 640 /home/exim4u/public_html/exim4u/config/variables.php You should now be able to browse to Exim4U's web interface on the VirtualHost you set up in Apache. Refer to the README file step 1 for an example VirtualHost setup. With the example VirtualHost, you would access the Exim4U web interface with the following syntax: https://domain.tld/exim4u or (non-secure); http://domain.tld/exim4u Once connected, you should log in as: Username: siteadmin Password: PASSWD Once logged in, please click on the 'Site Password' link on the left, and immediately change the siteadmin password. Then, start setting up your mail domains. Thereafter, you will log in as "siteadmin" with your designated password for site administration. After you have setup a minimum of one (1) mail domain then you may log in to each domain's admin account using the email address and password that were specified when you setup the domain. Mail users may then be added to each mail domain. All mail users may also log in to their user account using their email address and password. Admins and users should login with their email address as follows: Username: Email address (such as user@domain.tld) Password: Assigned password 7. Install Dovecot (or Courier) from your Linux distributions repository or from source. Sample Dovecot configuration files are provided in this Exim4U distribution at etc and etc/dovecot. Note that you must replace CHANGE with your mysql password in etc/dovecot-sql.conf. The default dovecot configuration file is etc/dovecot.conf. Whereas, the Dovecot configuration files for multiple IPs and SSL certificates are in the directory etc/dovecot. Each configuration file for each IP is named dovecot.IP.conf. For example, dovecot.127.0.0.1.conf is for the local machine whereas dovecot.111.222.333.444.conf is for IP address 111.222.333.444. The service script for dovecot must be modified for multi IPs/SSL certificates. Example service scripts are included in etc/init.d. An example Dovecot service script for multi IPs is located at etc/init.d/dovecot-MULTI_IP and the corresponding default Dovecot service script is located at etc/init.d/dovecot. If you decide to use clear-text passwords (not recommended) then you must edit and modify /etc/dovecot-sql.conf as described therein on lines 4 thru 8. 8. Install Webmail Refer to the WEBMAIL documentation file in this distribution's docs directory for installing Exim4U's Webmail Groupware which is a customized version of Horde Groupware Webmail Edition. Alternatively, install your favorite webmail product, such as Squirrel Mail or Round Cube, in /webmail (eg.: /home/exim4u/public_html/webmail). 9. Install Exim4U's User Menu and Admin Menu interfaces from the user_menu and admin_menu directories. The user_menu directory contains the User Menu interface html scripts while the admin_menu directory contains the Admin Menu interface html scripts. Copy the home/exim4u/public_html/user_menu directory and its contents to your apache document root directory: cp -r home/exim4u/public_html/user_menu Edit user_menu/index.html and substitute your host name for 'hostname.tld'. Copy the home/exim4u/public_html/admin_menu directory and its contents to your apache document root directory: cp -r home/exim4u/public_html/admin_menu Edit admin_menu/index.html and substitute your host name for 'hostname.tld' which occurs twice in this file. You should now be able to browse directly to Exim4U's User Menu and Admin Menu on the VirtualHost you set up in Apache. Refer to the README file step 1 for an example VirtualHost setup. With the example VirtualHost, you would access the Exim4U User Menu and Admin Menu interfaces with the following syntax: https://domain.tld/user_menu https://domain.tld/admin_menu or (non-secure); http://domain.tld/user_menu http://domain.tld/admin_menu 10. Install the Heirloom mail package. In RedHat/CentOS, the Heirloom package is available from the RepoForge (formally RPMforge) repository and can be installed with yum as follows: yum install nail The Heirloom mailx (or nail) command is used in the eximstats, spamreport and spamdel scripts. The nail command has been deprecated in favor of the mailx command, however, some distributions continue to use the older nail version instead. Either will work fine. See: http://heirloom.sourceforge.net/mailx.html 11. Install and configure eximstats and eximstats.sh. First, copy the home/exim4u/public_html/eximstats directory and its contents to your apache document root directory: cp -r home/exim4u/public_html/eximstats Then, copy the contents of this distributions xtrasw/eximstats directory (eximstats-1.58a.src and eximstats.sh) to /usr/local/bin or any other directory of your choice: cp -r xtrasw/eximstats/* /usr/local/bin Edit eximstats.sh in its destination directory and change the following variables in the script to the appropriate values for your installation: * eximstats_cmd=/usr/local/bin/eximstats-1.58a.src * mailcommand=/usr/bin/nail (Should be mailx or nail from Heirloom project) * logfile=/var/log/exim/main.log.1 * destdir=/home/exim4u/public_html/eximstats * htmlfile=/home/exim4u/public_html/eximstats/eximstats.html * txtfile=/home/exim4u/public_html/eximstats/eximstats.txt where; * eximstats_cmd - Location of the eximstats command. * mailcommand - Heirloom mail command (nail or mailx). * logfile - Location of the exim log file to be parsed. * destdir - Destination directory for charts. * htmlfile - Destination directory for html output. * txtfile - Destination directory for text output. You should setup a crontab entry to run eximstats.sh daily after your log rotation has occurred. 12. Install and configure the Spam Box Report The Spam Box Report is designed primarily for POP users that do not otherwise have access to the server's spam folders from their POP email clients. Spam Box is a term that describes the POP user's spam folder that resides on the server. Mail that has been tagged as spam by Exim4u is placed in each user's spam folder. Refer to the file etc/exim/exim4u_global_spam_virus for a detailed description of how Exim4U processes spam. The Spam Box Report will send a list of all mail in each user's spam folder to each user. The Spam Box Report can be turned off/on in the Exim4U web interface. The Spam Box Report also includes a link to webmail for easy access to the spam folder. To install the Spam Box Report, copy xtrasw/spam_box_report/spamreport to /usr/local/bin or any other directory of your choice: cp xtrasw/spam_box_report/spamreport /usr/local/bin For the report to work properly, seven variables must be specified as follows; Specify the mail command: mailcommand=/usr/bin/nail # Should be mailx or nail from Heirloom project. Specify webmail url: webmailurl="https://hostname.tld/webmail"; Specify the email address that the spam report is to be sent from: fromadd="postmaster@hostname.tld"; Put the IMAP file name of your server's spambox folders here: spamfolder=".INBOX.spam" Specify the mysql user name, msql password and mysql database name: mysql_uname="exim4u"; mysql_pword="CHANGE"; mysql_dbase="exim4u"; You should setup a crontab entry to run spamreport daily. 13. Install and configure the Spam Box Deletion Utility The Spam Box Deletion Utility removes old spam from the server's spam folders. This utility should be run daily and is configured by default to remove all mail that is over 10 days old from the Spam Boxes. To install the Spam Box Deletion Utility, copy xtrasw/spam_box_delete/spamdel to /usr/local/bin or any other directory of your choice: cp xtrasw/spam_box_delete/spamdel /usr/local/bin For the report to work properly, seven variables must be specified as follows; Specify the mail command: mailcommand=/usr/bin/nail # Should be mailx or nail from Heirloom project. Specify the email address where the spam report will be sent: emailaddr="postmaster@hostname.tld" Put the IMAP file name of your server's spambox folders here: spamfolder=".INBOX.spam" Specify the age of the spam in days to be deleted. All spam older than this will be deleted during each run. (Default is 10 days). deletedays="10" Specify the mysql user name, msql password and mysql database name: mysql_uname="exim4u"; mysql_pword="CHANGE"; mysql_dbase="exim4u"; You should setup a crontab entry to run spamdel daily. 14. Install and configure the spamalert script This script detects outgoing ratelimit violations which are usually bulk spam originating from internal user accounts that have been compromised via hacking or viruses, etc. Upon detection, an email is then sent to the designated admin address to report the outgoing ratelimit violation. Copy xtrasw/spamalert/spamalert to your installation from the Exim4U 3.0.0 distribution's root directory. Then, the Logwarn program must be downloaded, compiled and installed for this script to work. Logwarn is maintained on GitHub here: https://github.com/archiecobbs/logwarn The current release of Logwarn is published here: https://code.google.com/p/logwarn/downloads/list The most current release as of 2015-05-17 is logwarn-1.0.11.tar.gz which can be downloaded, extracted and compiled as follows: wget https://logwarn.googlecode.com/files/logwarn-1.0.11.tar.gz tar xvzpf logwarn-1.0.11.tar.gz cd logwarn-1.0.11 ./configure make sudo make install Create the following directory where Logwarn stores its log data: /var/lib/logwarn sudo mkdir /var/lib/logwarn Then, put the following entry in your root crontab which will run this script every 10 minutes: # Check for sender ratelimit spammer. */10 * * * * /spamalert > /dev/null 2>&1 15. Install the favicon and the placeholder pages for Munin and phpMyAdmin to your webserver's document root directory: cp favicon.ico cp -r munin cp -r phpadmin 16. Now, the document root of your apache website installation should have all of the files and directories that are contained in this distribution in home/exim4u/public_html as follows: * exim4u - Directory containing the Exim4U php scripts. * eximstats - Directory containing the eximstats place holder or output files. * favicon.ico - Favicon file. * user_menu - Directory containing the Exim4U user interface. * admin_menu - Directory containing the Exim4U admin interface. * munin - Directory containing the Munin place holder or output files. * phpadmin - Directory containing the phpMyAdmin place holder or output files. * webmail - Directory containing the webmail (horde) php scripts. 17. Install Optional Software; Mailman, Munin, phpMyAdmin and Webmin. 18. Done!