Login Manager ("Vlogin") plugin for SquirrelMail
================================================
Ver 3.10, 2008/07/06


Copyright (c) 2002-2008 Paul Lesniewski <paul@squirrelmail.org>
Copyright (c) 2001 Ryan Orth <snubber-sm@seahat.com>



Description
===========

Login Manager ("Vlogin") is a plugin for SquirrelMail that:

   * helps manage and manipulate usernames given at login time 

   * allows the use of different SquirrelMail settings (such as 
     login page image, or IMAP server) for each domain, each user, 
     or each user group

Vlogin is both useful if you just need to make sure that usernames 
given on the login page are consistent and/or if you host more than
one domain and wish to customize SquirrelMail for each domain but
do not want to install and manage a separate SquirrelMail installation 
for each one.  

Vlogin is also meant to help your users: if your user accounts are 
of the form "jose@example.net", it allows users to log in by only 
typing "jose" in the username field.

Finally, Vlogin is capable of supporting fairly complex systems 
where the SquirrelMail settings, appearance, access levels, and
behaviors are based on username, domain or "service level" (user
group).  

Despite the plugin name, even single-domain servers may find very
useful functionality herein, such as username consistency/simplicity,
or per-user settings or "service level" user settings groups, etc.

Some of Vlogin's helpful features include:

   * make sure all usernames given on login page do not have any domain 
     portion in them
   * make sure all usernames given on login page have the SquirrelMail
     default domain appended to them
   * make sure all usernames given on login page have the domain
     that corresponds to the domain in the URL of the login page 
     appended to them
   * allow users to log in with just a "user" when in fact their IMAP
     login might be something like "username@domain.com" 
   * show a different image on the login page for each of your domains
   * change most any SquirrelMail configuration setting on a per-domain,
     per-service level, or even per-user basis
   * access a sendmail, postfix or qmail style virtual users table
   * change IMAP servers (or any other settings) on a per-domain, per-
     service level, or even on a per-user basis
   * enable or disable certain plugins on a per-domain, per-service level
     or per-user basis
   * disable certain option page items on a per-domain, per-service level
     or per-user basis
   * dealias Qmail/Vpopmail aliased domains
   * domain name translation
   * access per-domain, per-service level or per-user settings stored in
     a SQL database
   * much more...

In order to help administrators avoid becoming overwhelmed by the 
possibilities Vlogin offers, there are several shortcuts available
to help install and quickly configure the plugin as needed.  See the
"Quick Start" section in the CONFIGURATION file.



License
=======

This plugin is released under the GNU General Public
License (see COPYING for details).



Donations
=========

If you or your company make regular use of this software, please
consider supporting Open Source development by donating to the authors
or inquire about hiring them to consult on other projects.  Donation/
wish list links for the author(s) are as follows:

Paul Lesniewski: https://sourceforge.net/donate/index.php?user_id=508228



Requirements
============

   * Compatibility plugin version 2.0.12 or above

   * SquirrelMail version 1.2.7 or above

   * PHP version 4.0.6 or above



Configuration
=============

   Please see the CONFIGURATION file for both a "Quick Start"
   guide as well as detailed information about all the available
   plugin configuration settings.
        


Plugin Installation Order
=========================

   Vlogin typically works best when installed before all other plugins.
   The only exception to this is under SquirrelMail 1.4.x, when a plugin 
   is in the list of "disable_plugins", in which case Vlogin should be
   installed after any such plugins.  In SquirrelMail 1.5.2 and above,
   this exception is no longer so.



Interacting With Other Plugins
==============================

   This plugin is compatible *as is* with both the password_forget and 
   login_alias amongst other plugins.

   However, some other plugins that work on the same hook as Vlogin 
   does but rely upon settings contained within Vlogin need to make 
   sure that they execute only after Vlogin does.  Vlogin provides an 
   easy way for such plugins to determine if Vlogin has loaded yet 
   and to load Vlogin immediately in the case that it has not yet 
   done so.  Plugin authors wanting to take advantage of this 
   functionality will need to use the following code in the beginning 
   of any function that relies upon Vlogin configuration settings:

   // Make sure Vlogin has loaded before continuing:
   //
   // Note that $args should be the arguments passed to
   // this hook by SquirrelMail to this plugin, but are
   // not absolutely mandatory.  Please attempt to get
   // them if at all possible from the hook call and 
   // uncomment the line near the bottom of this code
   // to pass them to Vlogin.
   // 
   // Only works against Vlogin version 3.8.1 and up.
   //
   // Note that the check_plugin_version() function is 
   // available as of SquirrelMail 1.5.2 or in Compatibility
   // plugin version 2.0.5 and up.
   //
   global $vlogin_remap_username_completed;
   if (check_plugin_version('vlogin', 3, 8, 1)
    && !$vlogin_remap_username_completed
    && file_exists(SM_PATH . 'plugins/vlogin/functions.php'))
   {
      include_once(SM_PATH . 'plugins/vlogin/functions.php');

      // use 'em if ya got 'em
      //vlogin_domain_do($args);
      vlogin_domain_do();
   }



Troubleshooting
===============

   Q: Vlogin is not changing the settings I have made in the $virtualDomains
      array.  It is still using the defaults in the main SquirrelMail 
      configuration.

   A: Please read about the $useSessionBased setting; if you have that setting
      turned off, you might be attempting to change values that Vlogin cannot 
      access unless you have $useSessionBased = 1 and the appropriate patches,
      etc.  This setting is faster and more powerful in general, so it is
      highly recommended if you can understand the extra requirements.

   Q: Vlogin does not seem to be seeing the changes I am making to its
      configuration file.

   A: Ensure that you are editing the correct configuraiton file.  
      If one is located under the main SquirrelMail configuration
      directory (specifically "config/config_vlogin/config.php"),
      it will always be used.  Otherwise, "config.php" in the
      plugins/vlogin/data directory will be used.  The same goes for
      the Vlogin meta configuration file and any other Vlogin
      configuration file you may be using:  if found under the main
      SquirrelMail configuration directory config/config_vlogin, it
      will be loaded from there, otherwise, it will be loaded from
      the plugins/vlogin/data directory.

   Q: Vlogin STILL isn't seeing configuration file changes!

   A: Please log out of SquirrelMail (and close all instances of the
      browser to be extra safe) and then log back in again.

   Q: I am getting a PHP error, something about "...eval()'d code"
      when I try to log in.

   A: If you are using per-user or SQL-backed settings for org_title, try
      encasing the org_title setting in quotes (try double quotes first) if 
      possible.  Or, if this is a problem with org_title as defined in the 
      normal config.php file or a different setting that has some PHP in it,
      please make sure that you have read about and correctly configured 
      the "settingsWithEmbeddedPHP" setting for that domain.



Help Requests
=============

Before looking for help elsewhere, please try to help yourself:

  * Read the Troubleshooting section herein.

  * Turn on $vlogin_debug in the configuration file.

  * Make sure the plugin is configured correctly by browsing to
    http://your-squirrelmail-location/src/configtest.php

  * Look to see if others have already asked about the same issue.
    There are tips and links for the best places to do this in
    the SquirrelMail mailing list posting guidelines:
    http://squirrelmail.org/wiki/MailingListPostingGuidelines
    You should also try Google or some other search engine.

  * If you cannot find any information about your issue, please
    first mail your help request to the squirrelmail-plugins
    mailing list.  Information about it can be found here:
    http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
    You MUST read the mailing list posting guidelines (see above)
    and include as much information about your issue (and your
    system) as possible.  Including configtest output, any debug
    output, the plugin configuration settings you've made and
    anything else you can think of to make it easier to diagnose
    your problem will get you the most useful responses.  Inquiries
    that do not comply with the posting guidelines are liable to
    be ignored.

  * If you don't get any replies on the mailing list, you are
    welcome to send a help request to the authors' personal
    address(es), but please be patient with the mailing list.



Todo
====

 * segregate settings between those that act to manipulate login username
   and those that affect settings based on the login, then clean up
   setting names and explanations (ugh)



Change Log
==========

 v3.10  2007/07/01  Paul Lesniewski <paul@squirrelmail.org>
    *  Added ability to store configuration files in the main
       SquirrelMail configuration directory
    *  Added ability to access virtual user tables in Berkeley/dbm
       style database format (Thanks to Ralph Stamm 
       <rstamm@student.ethz.ch>)
    *  Added configtest check for Multilogin patch when 
       $useSessionBased is turned on
    *  Added configtest check to help debug $allVirtualDomainsAreUnderOneHost
    *  Added ability to add domain to the username when using
       it to set the outgoing email address ($appendDomainToOutgoingEmailAddress)
    *  Fixed:  configuration not loading on logout_error hook
    *  Fixed fatal error in 1.5.2+ when vlogin is enabled 
       before multilogin
    *  Fixed problem where some settings not being correctly
       overridden when $useSessionBased is turned off (remember,
       $useSessionBased is recommended!)
    *  Reorganized documentation
    *  Prevent re-parsing of per-user settings file but once per session
    *  Redesigned some hook behavior to improve performance
    *  Update for 1.5.2 config_override hook name change (prefs_backend)

 v3.9.2  2007/01/19  Paul Lesniewski <paul@squirrelmail.org>
    *  Added ability to run a last-minute pattern replacement
       operation on the username right before it goes to the
       IMAP server.
    *  Added configuration test
    *  Fixed issue where login page not getting full config overrides

 v3.9.1  2007/01/14  Paul Lesniewski <paul@squirrelmail.org>
    *  Setting overrides were not working on signout page,
       at least after reloading it once or more - fixed.
    *  Added ability to turn off ALL plugins in the 
       disable_plugins setting
    *  Miscellaneous fixes for 1.5.2 compatibility

 v3.9.0  2006/10/15  Paul Lesniewski <paul@squirrelmail.org>
    *  Changed English name to reflect the more generic
       applications available herein.
    *  Adapted to 1.5.2 config override hook; if running
       1.5.2 or greater, $useSessionBased is highly 
       recommended and no longer requires any source patching
    *  Added functionality for better, easier interaction
       with other plugins that need to load AFTER vlogin
       does (plugin authors, see README file).
    *  Added $rawLoginIsOutgoingEmailAddress for using raw
       login username as outgoing email address (careful!!).
    *  Raw login username is saved in user session for access
       by anyone who needs it as "vlogin_original_username".
    *  Added $always_prepend and $always_append settings
    *  Added ability to derive IMAP and/or SMTP server addresses
       from the user's domain name (see $IMAPServerRules and 
       $SMTPServerRules)
    *  Better configuration file protection; note that sample
       configuration file names have changed
    *  Added "meta-configuration" to help admins who only need
       a subset of Vlogin functionality and don't want to have
       to understand the entire configuration system.
    *  Added "Quick Start" section to README file

 v3.8.0  2005/10/19  Paul Lesniewski <paul@squirrelmail.org>
    *  Added SQL backend for per-user, per-doamin or per-service
       level settings.
    *  Changed $allVirtualDomainsAreUnderOneHost to more flexible
       user-definable regexp.
    *  Added $default_org_logo setting
    *  Fallback to "typical" configuration settings if config.php
       is not found

 v3.7.0  2005/04/26  Paul Lesniewski <paul@squirrelmail.org>
    *  Added service level functionality.
    *  $debug changed to $vlogin_debug
    *  Refactored per user functionality.
    *  Fixed: use URI parsing when $useDomainFromVirtDomainsArray
       is on but domain not defined for domain being logged into.
    *  Update for changes in Multilogin plugin (v2.3.2).  If you
       are using $useSessionBased = 1, you MUST update your
       Multilogin plugin as well.
    *  Minor code cleanup
    *  Added "settingsWithEmbeddedPHP" setting for $virtualDomains
       array that allows any configuration setting's value to 
       contain embedded PHP code.  If your configuration file 
       previously contained the org_title setting overrides, you
       MUST add this as described in the docs! 
    *  Changed $allVirtualDomainsAreUnderOneSSLHost to 
       $allVirtualDomainsAreUnderOneHost; if you use this setting,
       make sure to update your config file!
    *  Compatibility plugin is no longer required

 v3.6.1  2005/02/27  Paul Lesniewski <paul@squirrelmail.org>
    *  Added $usernameDomainIsHost
    *  Added $stripDomainFromUserSubstitution
    *  Fixed broken sendmail-style virtual user table functionality

 v3.6  08.02.2005  Paul Lesniewski <paul@squirrelmail.org>
    *  Added $usernameReplacements to allow more powerful 
       manipulation of usernames (users can now, for instance,
       log in with their real name, such as "Paul Lesniewski",
       which could be remapped to "paul.lesniewski@mydomain.net")
    *  Added $forceLowercase
    *  Added $useDomainFromVirtDomainsArray (this is somewhat
       significant)
    *  Added $securePort
    *  Sendmail-style virtual user table functionality now 
       supports %1 variable replacement, where %1 in the 
       mapped value (left) will be replaced with what the
       user gave before the @ sign (Thanks to Pablo Giancarelli 
       <pablo.giancarelli@bircherasociados.com.ar>)
    *  Fixed disable_options functionality when $useSessionBased
       is turned off ($useSessionBased is recommeded, however)
    *  Tuned config override so that the $virtualDomains array 
       or the multilogin plugin can override vlogin's own config 
       settings and also so that multilogin and vlogin can work
       together better)
    *  Updated to work with new version of Login Alias plugin;
       if using Login Alias with this plugin, make sure you get
       at least version 2.4 of Login Alias, which was released
       at the same time as version 3.6 of this plugin

 v3.5  23.09.2004  Paul Lesniewski <paul@squirrelmail.org>
    *  Added ability to disable options on Display Preferences,
       Personal Information, and Folder Preferences screens.

 v3.4.1  22.08.2004  Paul Lesniewski <paul@squirrelmail.org>
    *  Added username replacement option for $virtualDomainDataDir
       as well as any of the values in the virtual domains array

 v3.4  06.05.2004  Paul Lesniewski <paul@squirrelmail.org>
    *  Enabling/Disabling plugins now works on a per-user basis.
    *  Now properly ignores port number in host URL (if any).
    *  Gets host name from the HTTP_X_FORWARDED_HOST server
       variable, if available, in order to facilitate using
       SquirrelMail in environments behind proxy servers that
       may rewrite the HTTP_HOST variable (Thanks to Jared 
       Rhine <jared@wordzoo.com>)
    *  Allow host name to be appended to username unconditionally
    *  Implemented reverse dot section order functionality and 
       added ability to replace or remove characters in host name 
       (Thanks to Mark van Cuijk <mark@phedny.net>)
    *  Added ability to separate domain settings in one file 
       per domain (Thanks to Andy Brook <ducky0@gmail.com>)
       
 v3.3  21.09.2003  Paul Lesniewski <paul@squirrelmail.org>
    *  Added abilty to strip domain information from usernames
       when users log in with full email addresses.  The domain
       parsed from the URL may or may not be added back on.  
       You can use this to force users to log in under the 
       domain used to get to the login page.
    *  Fixed replacement pattern for $checkByExcludeList (Thanks
       to Tarragon Allen <tarragon@onthe.net.au>)
    *  Fixed problem including virtual domain name in $data_dir 
       in the virtual domains array.
    *  Removed lockout functionality; there is a separate Lockout 
       plugin for that now

 v3.2  24.04.2003  Paul Lesniewski <paul@squirrelmail.org>
    *  Added global virtual domain capability (Thanks to Jeff 
       Hedlund <jhedlund@matrixsi.com>)
    *  Added ability to use the virtual domain's name in any
       of the domain's variables (Thanks to Jeff Hedlund 
       <jhedlund@matrixsi.com>)
    *  Added $atConversion functionality (see README) (Thanks to
       Tom Collins <tom@installco.com>)
    *  Fix for minor $notPartOfDomainName bug that matched (for
       instance) "webmail" with "mail"
    *  Fix for when the domain name is part of your usernames and 
       you are using login_alias, such that someone in "domain_1.com"
       can use an alias such as "jose" and no longer lock out 
       "jose@domain_2.com"
    *  Changed to dynamic global variables (was explicitly specified)
       so most any SquirrelMail setting should be automatically 
       available if it wasn't already
    *  New (optional) session-based functionality allows for better 
       performance
    *  Added ability to lock out an entire domain (disallow any 
       logins) or a specific list of users
    *  Note that configuration and data file locations have changed
       to the vlogin/data directory

 v3.1  26.03.2003  Paul Lesniewski <paul@squirrelmail.org>
    *  (When using sendmail-style virtual user table functionality:)
       Removes extraneous pieces of virtual user catchall
       mappings (in the form "@domain  catchallmapping+%1", 
       removes everything including and after the plus sign).
       (Thanks to Neil Darlow <neil@darlow.co.uk>)
    *  Added wildcard functionality to the per-user settings file
    *  Added functionality that allows the activation or deactivation 
       of specific plugins on a per-domain basis (experimental; may
       not work with all plugins).
    *  Updated session_recall patches for SquirrelMail versions 1.2.11 
       and v1.4
    *  Added ability to remap host names for those whose web URL
       is different than their email server's MX record (Thanks to
       Ville Walveranta <vwal@astronfortis.com>)
    *  Added ability to unalias Qmail/Vpopmail aliased domains so
       users using aliased domains don't accidentally create multiple
       preferences files (Thanks to Lelio della Pietra 
       <gandalf@writeme.tk>).
    *  Updated for compliance with new plugin version reporting API

 v3.0  03.03.2003  Paul Lesniewski <paul@squirrelmail.org>
    *  Updated to work with SquirrelMail v1.4
    *  New setup.php format for better overall SquirrelMail performance
    *  Makes use of optional session_recall hook to help those of
       you who can't get vlogin to do dynamic IMAP server settings otherwise


 v2.6  02.02.2003  Paul Lesniewski <paul@squirrelmail.org>
    *  Minor update for compatibility with password_forget plugin.
    *  Minor update for compatibility with login_alias plugin.


 v2.5  09.01.2003  Paul Lesniewski <paul@squirrelmail.org>
    *  Changed behavior of $numberOfDotSections to be based on the new 
         $removeFromFront setting.
    *  Added $chopOffDotSectionsFromLeft and $chopOffDotSectionsFromRight 
         and associated functionality.
    *  Changed $checkByExcludeList behavior to take out undesirables no
         matter where they are in the host name.
    *  Added $allVirtualDomainsAreUnderOneSSLHost and associated functionality.
    *  Added $sendmailVirtualUserTable and associated functionality.
    *  Added $perUserSettingsFile and associated functionality.
    *  Added $putHostNameOnFrontOfUsername and associated functionality.
    *  Updated for compatibility with Plugin Updates plugin
    *  Fixed php version checking so it works in all locales.         
    *  Fixed all E_NOTICE warnings
    *  Added $debug and associated functionality.

