 
INTRODUCTION
------------

This program attempts to allow users to easily set forwarding addresses on
their email account.  It allows the setting and removing of forwards,
with the option of keeping a local copy of the fowarded mail also.
It supports sendmail/qmail style .forward file formats, as well as an
sql and mdaemon implementation.

PREREQUISITES
-------------

The following prerequisites are REQUIRED.

  1. A successful HORDE 2.x installation and all which that entails.

  2. For the "forwards" driver, an ftp server installed, running, and working
     on your mailhost, a mail program which supports .forward files, and
     your php must have the ftp extension compiled in and enabled.

  3. For the SQL driver, a working sql installation, mail software that will
     honor the sql forwards, and the proper php sql support compiled in
     and enabled.

  4. For the mdaemon driver, a working mdaemon installation on the same
     host machine.

  5. For the qmail driver, the VFS package from PEAR (http://pear.php.net).
     You can install it with `pear install VFS'.

INSTALLING Forwards
-------------------

Forwards is intended to be installed inside the HORDE package directory.

Since Forwards is written in PHP, there is no compilation necessary;
simply expand the distribution where you want it to reside (normally
into a directory inside the HORDE directory). 

For example, with the Apache webserver's default document
root of '/usr/local/apache/htdocs'  and your HORDE install in a directory
under that called 'horde' you would type:

   cd /usr/local/apache/htdocs/horde
   tar zxvf /path/to/forwards.tgz

CONFIGURING Forwards
--------------------

1. We assume that you already have a working HORDE installation.

2. Configuring Forwards

   To configure Forwards, change to the config/ directory of the
   installed distribution, and make copies of all of the configuration
   "dist" files without the "dist" suffix:

      cd config/
      for foo in *.dist; do cp $foo `basename $foo .dist`; done

   Documentation on the format of those files can be found in each
   file; open each in an editor and make changes as suggested within.

3. Configuring HORDE

   To make Forwards appear in Horde, you may need to add an entry to the Horde
   horde/config/registry.php file.  If not already present, you want to add
   a section that looks like:

$this->applications['forwards'] = array(
    'fileroot' => dirname(__FILE__) . '/../forwards',
    'webroot' => $this->applications['horde']['webroot'] . '/forwards',
    'icon' => $this->applications['horde']['webroot'] . '/forwards/graphics/arrow.gif',
    'name' => _("Forwards"),
    'allow_guests' => false,
    'show' => true,
    'status' => 'active'
);

4. Optional Configuration of IMP

   If you have IMP installed, and want to include Forwards in the IMP menu
   bar, you can add the application to IMP as well.  Edit the file
   horde/imp/config/conf.php and include 'forwards' in the list of menu apps,
   for example, it might look like the following:

   $conf['menu']['apps'] = array('turba','passwd','vacation', 'forwards');

THINGS THAT CAN GO WRONG
------------------------

Realize that this module, when using the ftp driver,  works by setting up a
.forward file in the user's account.  It does this (at the moment) in a
exclusive fashion.  If a .forward already exists, it must be removed first;
it does not append/prepend to the existing file.  This means you can not set
both a forward and a vacation message at the same time.  This is rarely an
issue, as you rarely want to both forward your mail and have a vacation notice
on the forwarding (rather than receiving) end.

If in doubt, please run the horde/test.php file and make sure ftp and/or
sql support is enabled in php.

OBTAINING SUPPORT
-----------------

There is a mailing list for support:
  sork@lists.horde.org 

You can subscribe or view the archives at: 
  http://lists.horde.org/mailman/listinfo/sork/


CREDITS
-------

See the seperate CREDITS file under the docs/ directory.

COURIER NOTES:
--------------
I'm told this module will work okay with courier if you add the line

|| dotforward

to the user's .courier file.  Otherwise courier won't use the .forward file.
So, an example .courier file might contain:

|| dotforward
./Maildir

Someday we may add code to the module to check for, and if missing insert this
code in the .courier file, but then again maybe we won't.  Until then, either
add this line to all their files, or find another way of enabling this
functionality (anyone know how to set courier's DEFAULTDELIVERY to do this?)
Tjeerd van der Zee wrote "or set this as default delivery in etc/courierd"
so this may work to make it a global change?

SECURITY NOTE:
--------------

In the "forwards" ftp-driven driver, there are some security concerns to
evaluate.  The basic idea is that it uses ftp to the mailhost to setup or
remove the .forward file in the user's login directory.

We run Horde/IMP on the mailhost, so the files are created on the
same machine via the loopback network interface. Our ftp server is 
completely firewalled off from the network, allowing only access from
localhost.  Hence even though it uses ftp with clear text passwords,
it is a rather secure setup as the data should never leave the mail
server and no other hosts can access the machine via ftp.  We also
don't allow any interactive (shell) logins to the machine -- doing
so might also effect the security of this module.

Using this module to another host will result in a security risk as 
passwords will be transmitted by ftp in the clear.  Installation on
a machine with shell logins may also effect security.  It is up to
the installer to evaluate the security risks.
