
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.

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.

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

The following prerequisites are REQUIRED.

  1. A successful Horde installation and all which that entails.

  2. An ftp server installed, running, and working on localhost.

  3. A mail program that respects .forward files ala sendmail.

  4. Your php must have the ftp extensions compiled in.

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

   If there is not already a "forwards" configuration stanza in your
   horde/config/registry.php file, then you need to add one.  You want
   a stanza that looks like:

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

The above is for Horde 2.0 and 2.1 versions. For Horde 2.2 change the last
line from from "'show' => true" to "'status' => 'active'" instead.
                                                                                
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 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 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?

QMAIL NOTES:
------------
The driver tries to set the mode (permissions) on the file, but this may or
may not work.  This may be significant, if your ftp server sets strange
permissions and we can't change them, as qmail will not work right with the
wrong permissions...

You should also be able to use the "forwards" driver if you install a
dot-forward patch to qmail.  But the qmail driver should work without
any patches or packges being added to qmail.
