Exim4U
                            README File

This README file provides a basic guide on how to get Exim4U working on
your system. You will need to have all of the listed software (Apache,
and SQL database, etc) already installed and configured.  Please refer
to the 'INSTALL' file for more detailed installation instructions.

REQUIREMENTS:
The following packages must be installed on your system, for Exim4U to
function properly:
    * Exim - Tested with version 4.69 thru 4.85. Must be compiled with
      MySQL, SQLite, spf, DKIM and the embedded Perl engine enabled.
    * MySQL - Tested with Version 5.0.77 thru 5.6.24.
    * SQLite - Tested with Version 3.3.6 thru 3.8.9 (SQLite3).
    * Apache - Tested with Version 2.2.3 thru 2.4.12.
    * PHP - Tested on 5.3.29 thru 5.6.8.
    * 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.
    * Perl - Tested with Version 5.8.8 thru 5.18.4.
    * Spamassassin - Tested with Version 3.3.2 - 3.4.1.
    * ClamAV - Tested with Version 0.98.4 thru 0.98.6.
    * Dovecot IMAP Server - Tested with Version 2.1.17 thru 2.2.16.
      (Courier IMAP is an alternative IMAP Server as discussed below.)

OPTIONAL SOFTWARE PACKAGES:
The following packages are optional but provide an enhanced environment
for Exim4U:
    * Mailman (http://www.gnu.org/software/mailman/index.html)
    * phpMyAdmin (http://www.phpmyadmin.net/home_page/index.php)
    * Munin (http://munin-monitoring.org)
    * Webmin (http://www.webmin.com/)

For users running RedHat/CentOS, you may consider also using the
atrmps and RepoForge (formally RPMforge) repositories which include
more current up-to-date versions of some packages.

NOTE FOR MIGRATING TO EXIM4U FROM VIRTUAL EXIM
If you are migrating from Virtual Exim (vexim2), please
follow the notes in the 'MIGRATE' file.

TABLE OF CONTENTS:
1) Apache Configuration
2) Exim Configuration
3) MySQL
4) SQLite
5) Exim4U Web Interface's Site Administrator
6) Setting Up Virtual Domains
7) Mail storage and Delivery
8) IMAP Servers For POP3 and IMAP Access
9) Webmail
10) Optional Software Packages

1) Apache Configuration

In this Exim4U distribution is a directory named home/exim4u/public_html.
The following directories and files are contained within this directory:
  * exim4u - Directory containing the Exim4U php scripts.
  * eximstats - Directory containing the output from running eximstats at 
    xtrasw/eximstats/eximstats.sh.
  * favicon.ico - Favicon file.
  * user_menu - The Exim4U User menu. Edit user_menu/index.html and
    substitute your host name for 'hostname.tld'.
  * admin_menu - The Exim4U Admin menu. Edit admin_menu/index.html and
    substitute your host name for 'hostname.tld' which occurs twice in
    this file.
  * munin - Directory place holder for the Munin package until it is
    installed.
  * phpadmin - Directory place holder for phpmyadmin until it is installed.
  * webmail - Directory containing Exim4U's webmail (Horde) software.

You have two options:
  1) Copy these directories and files into your current DocumentRoot for your
     domain or;
  2) Set up a new VirtualHost and point the DocumentRoot to the parent
     directory.

The apache configuration must be edited to properly reflect your preferred
virtual host configuration. It is recommended that the parent directory
(home/exim4u/public_html) be setup for secure SSL access using https.
Refer to your apache documentation for guidance. Here is an example 
of a secure SSL virtual host.  On RedHat/CentOS distributions, this virtual
host would be placed within /etc/httpd/conf.d/ssl.conf for SSL access:

  <VirtualHost 111.222.333.444:443>
      DocumentRoot "/home/exim4u/public_html"
      ServerName domain.tld:443
      redirectpermanent /zpanel https://domain.tld/admin_menu
      redirectpermanent /vexim https://domain.tld/exim4u
      redirectpermanent /sqmail/src/login.php https://domain.tld/webmail
      <Directory /home/exim4u/public_html/>
              AllowOverride All
      </Directory>
      ServerAdmin admin@domain.tld
      UseCanonicalName Off
      ErrorLog logs/ssl_error_log
      TransferLog logs/ssl_access_log
      LogLevel warn
      SSLEngine on
      SSLProtocol all -SSLv2
      SSLCertificateFile <path to ssl cert>/domain.tld.crt
      SSLCertificateKeyFile <path to SSL key>/domain.tld.key
      SSLCertificateChainFile <path to SSL bundle>/domain.tld.cabundle
      SetEnvIf User-Agent ".*MSIE.*" \
      nokeepalive ssl-unclean-shutdown \
      downgrade-1.0 force-response-1.0
      CustomLog logs/ssl_request_log \
      "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
  </VirtualHost>

Several recommended security precautions related to apache website files are included
in the SECURITY file in this distributions root directory.  These precautions will
help protect your Exim4U installation from hostile intruders and other potential
security issues.

2) Exim Configuration:

The exim configuration is contained in this Exim4U distribution in a directory
called etc/exim. All of the site specific files that users must always
edit upon installation to incorporate site specific functionality have file
names beginning with exim4u_. So, all of the files that begin with exim4u_
should be reviewed and configured according to your installation. The main
configuration file, exim.conf, should never be altered (unless
major modifications are envisioned). All of the files in etc/exim are
very well self documented. Here is a brief description of each file:

Site Specific Configuration Files - MODIFY THESE FILES FOR YOUR INSTALLATION
----------------------------------------------------------------------
* exim4u_backup_mx_host_names - Backup MX host names to be exempted from most spam checks. 
* exim4u_backup_mx_rl_host_names - Backup MX host names to be exempted from ratelimit checks only.
* exim4u_global_spam_virus - Spamassassin and ClamAV global settings.
* exim4u_hostnames+hostIPs - Host names and IP addresses for the local machine.
* exim4u_IPblacklist - Blacklisted IP Addresses.
* exim4u_IPskip_sender_verify - IP addresses to omit verification of senders email address (local part).
* exim4u_IPwhitelist - Whitelisted IP Addresses.
* exim4u_local.conf.inc - Primary site specific configuration settings. 
* exim4u_local_rl.conf.inc - Ratelimit configuration for outgoing mail.
* exim4u_relay_from_hosts - Hosts that can use our host as an outgoing relay.
* exim4u_sender_rl_addr - Internal sender email addresses to be exempted from outgoing ratelimit checks.
* exim4u_sender_rl_dom - Internal sender IP addresses to be exempted from outgoing IP ratelimit checks.

NOTE: You must specify the MYSQL password in etc/exim/exim4u_local.conf.inc which is denoted by 'CHANGE'.

Main Exim Configuration Files
--------------------------------------------
* exim.conf - The main exim configuration file.
* exim-acl-check-spf.conf - SPF configuration file for exim.conf.
* exim-greylist.conf - Greylisting configuration file for exim.conf.
* exim-group-router.conf - Group router configuration file for exim.conf.
* exim-mailinglist-router.conf.inc
* exim-mailinglist-transport.conf.inc
* exim.pl - Directory containing SURBL/URIBL/DBL Perl scripts.  
     
NOTE: There is one file in etc/exim/exim.pl that is site specific: surbl_whitelist.txt. This file is for
whitelisting URLs from the URIBL/SURBL/DBL checks in exim. Also, there are two other files in etc/exim/exim.pl
that should be updated periodically: three-level-tlds and two-level-tlds.  There is an update script in
etc/exim/exim.pl/README2 that should be added to your root user's crontab that will update these two files
automatically.

NOTE: Exim4U's Greylisting is triggered by a number of conditions as documented in etc/exim.conf.
The most frequent reason why Exim4U greylisting occurs is if the spamscore > 0.  In all instances,
greylisted mail is accepted after 5 minutes and all resenders are subsequently whitelisted 
from greylisting for 7 days.

3) MySQL:

You must create a new MySQL database for Exim4U. The procedure for doing
this is different according to whether you are doing a fresh install or
if you are migrating from Virtual Exim.  Follow the instructions in the
INSTALL file in this distribution's root directory if you are doing a
fresh install.  Whereas, follow the instructions in the MIGRATE file if 
are migrating from Virtual Exim.

4) SQLite:

You must create a new SQLite database which Exim4U uses for greylisting.
Instructions for creating this database are included in the INSTALL file
in this distributions root directory.

5) Exim4U Web Interface's Site Administrator:

The "site administrator" is able to add and delete domains from the Exim4U
web interface and create the initial postmaster users for the individual domains.

The default username and password for the siteadmin, are:
  Username: siteadmin
  Password: PASSWD

So, the first time that you run the Exim4U web interface you will login with
username=siteadmin and password=PASSWD. The password is case sensitive.
You should log in and change the siteadmin password immediately after
the initial installation.


6) Setting Up Virtual Domains:

Once the Exim4U web interface is configured properly, the siteadmin may specify
the local domains for which Exim accepts mail and the external domains for
which exim relays mail. Domains are easily added/removed from the siteadmin
pages. Local domains can also be enabled/disabled on the fly, while relay
domains are always enabled.


7) Mail storage and Delivery:

The default configuration assumes that mail will be stored in /home/exim4u/mail/.
If you want to change the path from '/home/exim4u/mail/', you need to edit
exim4u/config/variables.php and change 'mailroot' to the correct path.
Don't forget the / at the end.


8) IMAP Servers for POP3 and IMAP access:

There are two recommended IMAP servers to use with Exim4U; Dovecot and
Courier.  Dovecot is faster and uses less memory while Courier has been
around longer. Also, Courier has the advantage of supporting multiple SSL
certificates/IPs without needing multiple configuration files while Dovecot
currently requires multiple configuration files for each SSL certificate/IP.

Exim4U was tested extensively with Dovecot while its predecessor, Vexim,
was tested with Courier.  Either IMAP servers will do, however, this 
discussion will focus on Dovecot since Dovecot has predominantly been
used with Exim4u during its development.


9) Webmail

Detailed documentation for Exim4U's Webmail is located in the WEBMAIL help file
in this distribution's root directory.

Exim4U's Webmail is a modified version of Horde Groupware Webmail Edition.
Generic Horde documentation may be found at:

     http://www.horde.org/documentation.php

Alternatively, install your favorite webmail product, such as Squirrel Mail or
Round Cube, in <DocumentRoot>/webmail (eg.: /home/exim4u/public_html/webmail). 

10) Optional Software Packages:

a) Mailman

Mailman needs to be installed if you want to use mailing lists. The
default home location for mailman data files is /var/lib/mailman and the default
wrap location for the mailman program files is /usr/lib/mailman. If these are not
the locations for your installation, edit etc/exim/exim4u_local.conf.inc and
change the paths where ever 'mailman' is mentioned, and do the same in
exim4u/config/variables.php.

The following is an example Apache configuration for mailman:

#
#  httpd configuration settings for use with mailman.
#
ScriptAlias /mailman/ /usr/lib/mailman/cgi-bin/
<Directory /usr/lib/mailman/cgi-bin/>
    AllowOverride None
    Options ExecCGI
    Order allow,deny
    Allow from all
</Directory>
Alias /pipermail/ /var/lib/mailman/archives/public/
<Directory /var/lib/mailman/archives/public>
    Options Indexes MultiViews FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>
# Uncomment the following line, replacing www.example.com with your server's
# name, to redirect queries to /mailman to the listinfo page (recommended).
# RedirectMatch ^/mailman[/]*$ http://www.example.com/mailman/listinfo
RedirectMatch ^/mailman[/]*$ /mailman/listinfo
#

b) phpMyAdmin

phpMyAdmin provides an easy to use web interface to MySQL. With phpMyAdmin
you can easily add, modify and delete MySQL database structures on the fly.
phpMyAdmin's home page is:

	http://www.phpmyadmin.net/home_page/index.php

phpMyAdmin can be installed from the above website.  RedHat/CentOS users
can alternatively use the Repoforge repository.

c) Munin

Munin provides Linux server data in graphical formats which can be very 
useful.  For example, Munin provides exim mail queue graphs and Exim Mail 
Throughput graphs that can be very informative for the mail system 
administrator. Munin's home page is:

	http://munin.projects.linpro.no/

Munin can be installed from the above website.  RedHat/CentOS users
can alternatively use the Repoforge repository.

d) Webmin

Webmin is a web-based interface for system administration of Linux/Unix
systems. Using a web browser, users can setup user accounts, Apache, DNS, 
file sharing and much more. Webmin removes the need to manually 
edit Unix configuration files like /etc/passwd, and lets you manage 
a system from the console or remotely.

Webmin is an open source "panel" similar to c-Panel and Plesk. Webmin's
home page is:

	http://www.webmin.com/

Webmin can be installed from the above website.  RedHat/CentOS users
can alternatively use the RepoForge repository.