==============================
INSTALLATION GUIDE FOR VEXIM 2
==============================

Contents:
  1.  Introduction
  2.  Possible setup combinations
  3.  Install: Apache 1.3.29
        3.1. Config: VirtualHosts
  4.  Install: MySQL 4.0.18
        4.1. Config: Add database + user
  5.  Install: PHP 4.3.4
        5.1. Config: Set up Apache for PHP
  6.  Install: ClamAV 0.68
        6.1. Config: Automatic definition updates
  7.  Install: SpamAssassin
  8.  Install: Exim 4.30
        8.1. Config: Set up routers etc
  9.  Install: Courier-IMAP
        9.1. Config: General Courier-IMAP
        9.2. Config: Set up IMAP
        9.3. Config: Set up POP3
  10.  Install: Vexim 2
        10.1. Config: Initialise settings
  11.  Install: Horde IMP Webmail
  12. Troubleshooting


1. Introduction
---------------
This installation guide is designed to show you through installing a
bare system with a complete e-mail solution, covering SMTP, POP3, IMAP,
webmail and the control panel Vexim with features such as anti-virus and
spam filtering.

Please note that through this guide, I have been using an sh shell.
If you're using anything different, you may have to alter the syntax.
Where a shell line begins with $ this indicates a normal user account,
and anything beginning with # is to be carried out as root. The entire
procedure could be done as root but that's just bad security practice.
There are commands for installing things under FreeBSD's package
management system (recommended) if you are running FreeBSD, and also
commands for compiling from source.
The "Source" instructions are mostly provided for the benefit of Linux
users.
You should only use one or the other, not both.


2. Possible setup combinations
------------------------------
The bare minimum to get e-mail running with Vexim is Apache, MySQL, PHP,
Exim and Vexim itself. For your users to access their e-mail, the author
recommends the use of the Courier-IMAP software which can provide IMAP
and/or POP3.

With the Courier-IMAP software providing IMAP facilities, you can
incorporate a webmail system - in this case, I will outline how to
install and set up the Horde IMP package, however other webmail packages
such as SquirrelMail will do the job just as well (personal taste).

If you already have Apache, PHP and MySQL running, please ensure you've
got another VirtualHost set up in Apache as detailed in section 3.1 and
the MySQL database and user in section 4.1.  Otherwise you can skip over
those sections.

Sections 6 and 7 for AV and spam aren't required, if you don't want
them, keep an eye out in section 8.1 when you will need to comment out
the relevant lines in the Exim configuration file.

Please remember that the Apache, PHP and MySQL sections are not the
target of this documentation - if you require any more details, please
consult their relevant websites and mailing list archives. Somebody on
the Vexim mailing list should be able to help you out if required.


3. Install: Apache 1.3.29
-------------------------
The latest stable version of the Apache 1.3 branch at the time of
writing is 1.3.29 however future versions of this branch are only
expected to fix bugs/security problems so there shouldn't be any
operational difference.

First create and change into a working directory for all of the
installations such as ~/vexim_install/

FreeBSD:
 # cd /usr/ports/www/apache13 && make install clean distclean

Source:
 $ wget http://www.apache.org/dist/httpd/apache_1.3.29.tar.gz
     If you're feeling kind, visit http://httpd.apache.org/download.cgi
     and get it from your nearest mirror
 
 $ tar zxvf apache_1.3.29.tar.gz && cd apache_1.3.29
 $ ./configure --prefix=/usr/local/apache1.3/ --enable-module=so
     Feel free to change the installation prefix if you wish... just remember it!
 $ make
 # make install


3.1. Config: VirtualHosts
------------------------
TODO - set up a good httpd.conf file and add virtual host for Vexim in
/www - also start httpd daemon.
Most apache users should know how to set up a <VirtualHost>, if you are
unsure, please check the documentation at http://httpd.apache.org/


4. Install: MySQL 4.0.18
------------------------
The latest version of MySQL production is 4.0.18 at the time of writing
this, installation procedures for MySQL may change between major
releases however. I will be using the binary releases (as recommended by
MySQL) for the x86 platform. If you require a different architecture,
download the Standard binary release from
http://www.mysql.com/downloads/mysql-4.0.html

FreeBSD:
 # cd /usr/ports/databases/mysql40-server && make install clean distclean
 # /usr/local/etc/rc.d/mysql-server.sh start
 # mysqladmin -u root password 'new-password'
     Change the text new-password to whatever you want... something
     secure as this provides root access to MySQL
 # mysqladmin -uroot -p create vexim

Source:
 $ wget http://mysql.mirror.anlx.net/Downloads/MySQL-4.0/mysql-standard-4.0.18-pc-linux-i686.tar.gz
     Again, visit http://www.mysql.com/downloads/mysql-4.0.html for
     mirrors

 # cd /usr/local
 # groupadd mysql
 # useradd -g mysql mysql
 # tar zxvf /PATH/TO/mysql-standard-4.0.18-pc-linux-i686.tar.gz
 # ln -s mysql-standard-4.0.18-pc-linux-i686 mysql
 # cd mysql
 # ./scripts/mysql_install_db
 # chown -R root .
 # chown -R mysql data
 # chgrp -R mysql .
 # ./support-files/mysql.server start
 # mysqladmin -uroot create vexim
 # ./bin/mysqladmin -u root password 'new-password'
     Change the text new-password to whatever you want... something
     secure as this provides root access to MySQL

     Now you need to set up MySQL to start on bootup. Copy the
     /usr/local/mysql/support-files/mysql.server script to your system's
     startup location (e.g. /etc/rc.d/rc.mysql) or if using an init.d
     based system (such as Redhat) then copy to /etc/rc.d/init.d/mysqld

     The startup/shutdown scripting varies between distros and so your
     mileage will vary...!


5. Install: PHP 4.3.4
---------------------
Once again, I'll repeat that PHP 4.3.4 is the latest version at time of
writing, however PHP 5 is in the RC stage at the moment so hopefully
I'll have this document updated for its impending release.

FreeBSD:
 # cd /usr/ports/lang/php4 && make install clean distclean
     From the menu that appears, choose:
       IMAP (if you will be running webmail now or in the future)
       gettext
       iconv
       crypt

Source:
 $ wget http://static.php.net/www.php.net/distributions/php-4.3.4.tar.bz2
     Mirrors available at
     http://uk.php.net/get/php-4.3.4.tar.bz2/from/www.php.net/mirror

 $ tar jxvf php-4.3.4.tar.bz2

    At this point, you need to decide if you will want to run a webmail
    service or not - if you do then you'll need IMAP support built into
    PHP now (you can always reinstall PHP later).

  === If you do NOT want IMAP support ===
  $ cd php-4.3.4
  $ ./configure --with-apxs=/usr/local/apache/bin/apxs \
  		--with-mysql=/usr/local/mysql/ \
		--with-gettext --with-pear --with-zlib
  === End of "no IMAP" section ===

  === If you DO want IMAP support ===
  We need imap-2002e which contains some libraries PHP wants...
  
  $ wget ftp://ftp.cac.washington.edu/imap/imap-2002e.tar.Z
  $ tar zxvf imap-2002e.tar.Z
  $ cd imap-2002e
 
    Now check out ./Makefile in your favourite text editor and find out
    which code represents your system. Note there are different codes
    depending on whether you use shadow passwords or not and some distro
    specific ones (i.e. Debian + Redhat). For my Slackware 9.1 testbed
    with shadow passwords, I'm using "slx".
 
  $ make slx SSLTYPE=none
     Change "slx" for your three character code but leave the
     SSLTYPE=none part on - this builds the IMAP libraries without
     OpenSSL support. As we're only using it on localhost, I personally
     can't see much point in making this ultra secure. However if you're
     spreading this installation out across machines then you may want
     to if you don't trust the security of the network.
  # mkdir /usr/local/imap-2002e
  # mkdir /usr/local/imap-2002e/lib
  # mkdir /usr/local/imap-2002e/include
  # cp ./c-client/*.c /usr/local/imap-2002e/lib/
  # cp ./c-client/*.h /usr/local/imap-2002e/include/
  # cp ./c-client/c-client.a /usr/local/imap-2002e/lib/libc-client.a
  $ cd ../php-4.3.4
  $ ./configure --with-apxs=/usr/local/apache/bin/apxs \
  		--with-mysql=/usr/local/mysql/ \
		--with-gettext --with-pear --with-zlib \
		--with-imap=/usr/local/imap-2002e/
  === End of "IMAP and PHP" section ===

  Now for the build of PHP:
  $ make
  # make install


5.1. Config: Set up Apache for PHP
----------------------------------
FreeBSD:
  This is done automatically when PHP is installed.

Source:
  TODO - add .php handlers to httpd.conf


6. Install: ClamAV 0.68
-----------------------
FreeBSD:
 # cd /usr/ports/security/clamav && make install clean distclean
   If prompted, do NOT check the box for "MILTER".

Source:
 $ wget http://heanet.dl.sourceforge.net/sourceforge/clamav/clamav-0.68.tar.gz
 $ tar zxvf clamav-0.68.tar.gz
 $ cd clamav-0.68
 # groupadd clamav
 # useradd -g clamav clamav
 $ ./configure
 $ make
 # make install

All:
  Edit /usr/local/etc/clamav.conf as root in a text editor and then:
  - comment out the line "Example" with a #
  - UNcomment the line "ScanMail" in the Mail Support section

  If you want to know about any virus infected e-mails, you can turn on
  logging options in this file.

FreeBSD:
  Add the line:
    clamav_clamd_enable="YES"
  to /etc/rc.conf, and then run:
    /usr/local/etc/rc.d/clamav-clamd.sh start

Source:
  In your rc.local (typically /etc/rc.d/rc.local), add the line:
    clamd
  to start the ClamAV daemon on bootup. You will want to run "clamd" as
  root now to get the daemon running.


6.1. Config: Automatic definition updates
----------------------------------
With Clam, AV definitions are distributed using a round-robin DNS system
which is accessed via the freshclam daemon.

FreeBSD and Source:
Edit /usr/local/etc/freshclam.conf then uncomment the UpdateLogFile line
and modify to read:
 UpdateLogFile /var/log/clam-update.log

Save the file then run:
 # freshclam -d

Source:
 You will want to put this in your rc.local file also, as done above
 with the clamd dameon.


8. Install: SpamAssassin
------------------------
FreeBSD:
 # cd /usr/ports/mail/p5-Mail-SpamAssassin && make install clean distclean
    Add the line:
    spamd_enable="YES"
    to /etc/rc.conf, and then run:
 # /usr/local/etc/rc.d/spamd.sh start

Source:
 TODO!


8. Install: Exim 4.30
---------------------
FreeBSD:
 # cd /usr/ports/mail/exim-mysql && make -DWITH_OPENSSL_BASE install clean distclean
   Add the line:
   exim_enable="YES"
 # pw groupadd vexim -g 90
 # pw useradd vexim -u 90 -g vexim -d /usr/local/mail -m -s /nonexistant
 
Source:
 $ wget ftp://ftp.demon.co.uk/pub/mirrors/exim/exim4/exim-4.34.tar.bz2
     Mirrors at http://www.exim.org/mirrors.html
 $ tar jxvf exim-4.34.tar.bz2
 $ wget http://duncanthrax.net/exiscan-acl/exiscan-acl-4.34-21.patch
     This patch will allow for AV and spam filtering. Latest version is
     at http://duncanthrax.net/exiscan-acl/ and should be checked if
     you're not patching for 4.34
 $ cd exim-4.34
 $ patch -p1 < ../exiscan-acl-4.34-21.patch
 $ cp src/EDITME Local/Makefile
 # groupadd -g 90 vexim
 # useradd -g vexim -u 90 -d /usr/local/mail vexim 
 
    The Exim build config file now needs to be edited to include the
    information we require. First open exim-4.34/Local/Makefile in your
    favourite text editor and then the following lines need to be
    searched for and then replaced as follows:

    Uncomment '# SUPPORT_TLS=yes'  to 'SUPPORT_TLS=yes'
    Uncomment '# EXIM_PERL=perl.o' to 'EXIM_PERL=perl.o'
    Replace the line starting 'CONFIGURE_FILE=' with
       'CONFIGURE_FILE=/usr/local/etc/exim/configure'
    You also need to 'EXIM_USER' and 'EXIM_GROUP' varliables to values
    suitable for your system. Please ready the documentation provided
    with exim to see what they should be.

 # make
 # make install


10. Install: Vexim 2
-------------------
 $ wget http://silverwraith.com/vexim/vexim2.tar.gz
 $ cd /www
 # tar zxvf /PATH/TO/vexim2.tar.gz

   Edit vexim2/setup/mysql.sql, and replace the word 'CHANGE' on lines 6
   and 7 with the default UID and GID under which delivers should
   happen. This UID and GID should be an actual user on your system. I
   use the "vexim" users we created above. It's UID and GID should both
   be 90 be default.
   Now, on like 69 which start "GRANT SELECT,...", change the word
   "CHANGE" to a password of your choosing. This with the password the
   web interface and Exim will both use to access the database. Make
   sure it is secure.
   Finally at the bottom of the file, there are two paragraphs commented
   out with '-- ' at their start. If your system uses MD5 passwords
   (FreeBSD, some Linux distros), uncomment the first paragraph as
   instructed in the file.
   If your system uses DES passwords (Usually Solaris and some other
   Linux distros), uncomment the second paragraph and instructed in the
   file. Save the file and exit now.

 # mysql -uroot -p vexim < vexim2/setup/mysql.sql

   Now edit vexim2/vexim/config/variables.php. You need to change the
   following settings:
     Change the '$sqlpass' on like 17 to the vexim database user's
     password which you chose which editing 'mysql.sql' in the last
     step.
     If your system uses DES passwords, change '$cryptscheme' to "des".

   Now we will configure Exim for VExim.
   Copy vexim2/docs/configure to /usr/local/etc/exim/configure
   Copy vexim2/docs/vexim* to /usr/local/etc/exim

   Edit /usr/local/etc/exim/configure now, and on line line 78 starting
   'hide mysql_servers', change the word 'CHANGE' to your vexim user's
   database password also.

   The ACL configuration starts on like 268. There are several ACL's
   here which *WILL* impact your ability to receive e-mail. Please look
   through each file that is mentioned there to see what each ACL does.
   By default, SpamAssassin, ClamAV, SPF and several DNS Block Lists are
   *ENABLED*. While most people will probably leave these on or tweak
   them slightly, they do increase the probability that you will be
   blocking mail. Almost all of this mail (if not all of it) should be
   spam, but please decide now if you want this mail blocked or not. If
   you do not want any mail blocked, please remove all lines starting
   '.include' in the ACLs.

 
10.1. Config: Initialise settings
--------------------------------
You should now be able to connect to the VExim website on the
VirtualHost you set up in Apache.

Once connected, you should log in as:
  Username: siteadmin
  Domain: <none>
  Password: CHANGE

Once logged in, please click on the 'Site Password' link on the left,
and change this password.

The interface at this point should be intuitive enough to use without
step-by-step intructions.
  Common commands such as adding domains and accounts, can be found
  through the menu on the left.
  If you wish you delete an account or domain, click on the trashcan
  icon next to it.
  If you wish to change the settings of an account or domain, simply
  click on the name of the account or domain.

  You should now add a domain, and then start Exim as shown below:


FreeBSD:
 # /usr/local/etc/rc.d/exim.sh start

Source:
 # exim -bd -q 30m