REQUIREMENTS:
-------------

ALL Vadmin versions require the following:
  * PHP-4.1 or above (http://www.php.net/) compiled with
    the following features:
        + dba (--enable-dba)
          See: http://php.net/manual/ref.dba.php
        + [OPTIONAL] gdbm (--with-gdbm)
          This allows you to set the "flavor" setting for the 
          [storage] configuration in vadmin.conf.php to gdbm 
          (recommended), however, you may skip this and use
          one of the handlers that comes with the dba extension
          by default (perhaps db4, for example, but this will
          depend entirely on your PHP build).
          See: http://php.net/manual/ref.dba.php
        + [OPTIONAL] mcrypt (--with-mcrypt)
          If you choose to use Vadmin's libmcrypt support 
          (see the CRYPTO file for more information), you'll 
          need mcrypt support in PHP.
          See: http://www.php.net/mcrypt
  * Squirrelmail 1.4.0 or above
  * Apache web server
  * [OPTIONAL] libmcrypt support for strong cryptography
    (see the CRYPTO file for more information)

Vadmin versions 3.0 and above require the following:
  * Compatibility plugin, version 2.0.14 or above
        + http://squirrelmail.org/plugin_view.php?id=152
  * A user management system backend compatible with one
    of Vadmin's backend integration mechanisms.  Currently,
    VMailMgr and SQL/database-based backends are included
    with this package, but others are available from the
    authors (see the BACKENDS and README files) and new
    ones may be added in the future.

Vadmin versions 1.9.0 and 2.0 require the following:
  * VMailMgr
        + http://untroubled.org/vmailmgr/
  * Qmail-Autoresponder with a vmailmgr-enabling patch or
    comprable SQL-backed system.
        + http://www.untroubled.org/qmail-autoresponder/
        + http://www.mricon.com/SM/qmail-autoresponder-0.96.1-vmailmgr.patch
        + http://www.mricon.com/SM/qmail-autoresponder.vdeliver-postdeliver

Also, there may be requirements that are specific to each backend.
Please check the file BACKENDS to learn more about such requirements.



INSTALLATION:
-------------

First, untar the vadmin package into the plugins directory and
then change into the vadmin plugin directory.  Here is a example 
for the 3.0 version of the Vadmin plugin:

        $ cd plugins
        $ tar -zxvf vadmin-3.0-1.4.0.tar.gz
        $ cd vadmin



CONFIGURATION:
--------------

Note that because of the nearly infinite combination of configuration
and build options available when putting together a mail system, setting
up Vadmin for your system may not be a trivial task.  If you are not
familiar with the architecture of your mail system or are not prepared
to invest the time and energy needed to configure Vadmin, you may want
to refer to the SUPPORT section in the README file.

The sections below each correspond to directories contained within
the vadmin plugin by default.  Each section describes the files in
the directory and what you must do with those files to ensure the
proper functioning of Vadmin.


conf/
    The first order of business is setting up your configuration files.  
    They are located in the conf/ directory and are three: vadmin.conf.php,
    apache.conf, and one for the backend of your choice.  NOTE that all
    of them have a ".conf_example.php" suffix.  You need to copy or rename 
    them, removing that suffix, so they all end only with ".conf.php".
    I.e., cp vadmin.conf_example.php vadmin.conf.php

    vadmin.conf.php
        This is the heart of your configuration.  Peruse the comments 
        inside the config file itself and set your paths and other things
        appropriately.  Make sure you choose the correct backend, which
        determines which backend configuration file will be loaded.
    
    <backend>.conf.php
        This file contains settings that are particular to your backend
        and will need to be reviewed and adapted as needed to suit the
        details of your mail server.
        
    apache.conf
        Edit apache.conf and change two (possibly three) things -- the 
        path to your squirrelmail directory if it's not 
        /usr/share/squirrelmail (in which case some people at FHS might 
        want to have a word or two with you), and change "LLAMA" to some 
        unique string.  This is the encryption hash that will be used to 
        encrypt your vadmin data, including domain passwords.  Make it 
        something good.  If you don't change it from "LLAMA," you will 
        suffer the consequences when someone logs in and runs porn warez 
        from your server.

        Tip: if you use any symlinked directory names in the URL to your 
        SquirrelMail installation, you will probably need to use that 
        symlink (and not the actual/real path, although you can certainly
        have an entry for both) in the Directory path in apache.conf.  
        You can test by using src/configtest.php.

        Now, based on what you learned by reading the CRYPTO and SECURITY
        documents, you may also want to change the encryption algorithm 
        from "rc4_builtin".

        Once you have edited this file, you have two options.  If you have
        a /etc/httpd/conf.d directory (which is true for at least Red Hat
        Linux 8 and above), then just move that file into that dir.  I.e.:
        mv apache.conf /etc/httpd/conf.d/vadmin-apache.conf. 
    
        If you don't have the /etc/httpd/conf.d directory, then move the 
        file into /etc/httpd/conf and add the following line into your 
        global apache.conf:
        Include vadmin-apache.conf

        !!!IMPORTANT!!!
        Wherever you have moved this file, run the following commands
        on it:
        chown root:root vadmin-apache.conf
        chmod 0600 vadmin-apache.conf

        (For an in-depth explanation about how this file works, see the 
        SECURITY document.)

    [OPTIONAL]
    It is a good idea to move the conf directory into /etc/vadmin. 
    This makes things like backups much cleaner and is FHS compliant.  If
    you decide to do this, here are your steps (performed while in the
    vadmin plugin directory):

      1) Move the configuration directory:

         # mv conf /etc/vadmin

      2) Tell Vadmin its new location.  You can do this in one of two
         ways.  The first is by executing this perl command:

         # perl -pi.bak -e \ "s|configuration_path\s*=.*?;|configuration_path = '/etc/vadmin/';|" config_parser.php

         Or you can manually edit the file config_parser.php and set the 
         $configuration_path variable (which is highlighted and documented 
         near the top of that file) to point to '/etc/vadmin/'


/var/lib/vadmin
    You need to set up /var/lib/vadmin (or some other place, if you 
    have set a different path for the "[storage]->dir" setting in 
    conf/vadmin.conf.  For example, run the following commands:

        $ mkdir -p /var/lib/vadmin
        $ chown -R apache:apache /var/lib/vadmin
        $ chmod 0700 /var/lib/vadmin

    The second command may be different for you if your web server 
    runs as a different user or group.  On some platforms it is run
    as "nobody:nogroup" or "httpd:httpd".  Check your web server 
    configuration if in doubt.


modules/
    If you move the files in this directory somewhere, make sure you 
    reflect upon that in conf/vadmin.conf.  A good place to move them 
    is /usr/share/vadmin/modules.  This puts them out of the web root.


includes/
    Similar to the modules/ directory, the files herein would live well 
    in /usr/share/vadmin/includes (make sure to update conf/vadmin.conf
    if you do move them).



ENABLING VADMIN IN THE SQUIRRELMAIL INTERFACE:
----------------------------------------------

Go to your SquirrelMail config directory and run conf.pl.  
Choose option 8 and move vadmin from the "Available Plugins"
category to the "Installed Plugins" category.  Save and exit.

        $ cd ../../config/
        $ ./conf.pl



FINAL STEPS:
------------

Restart your web server and the plugin should be ready to use.
See the README file for usage information.

If the plugin does not seem to work, please see the README file 
and then send your support request to squirrelmail-plugins@lists.sf.net 
with [Vadmin] in the subject.  As always, you must include as many
details as possible about the system you are attempting to install 
the plugin on, along with the configuration settings you made in 
each of the vadmin configuration files.

