Index | Feature List | FAQ | Integrating POP3 and IMAP | Download Page
README | Credits | Wiki

---

                         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:[email protected]:/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 : 66.214.182.79 
    *** 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.