Login Manager ("Vlogin") plugin for SquirrelMail
================================================
Ver 3.9.0, 2006/10/15

Authors: Paul Lesneiwski <paul@squirrelmail.org>
         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-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 below.



License
=======

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



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

   * Approximately SquirrelMail version 1.2.7 or above
   * Approximately PHP version 4.0.6 or above



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

   Before asking for help, did you read the FAQ below?  Did you turn
   on $vlogin_debug?  Did you search the SquirrelMail plugins mailing
   list for people reporting the same problem?

   Help requests are welcome at my personal email address, but I
   request that you first post to the SquirrelMail Plugins mailing
   list, where you'll get faster help from more people and other
   people with the same problem will be able to see how your issue
   was resolved.  If you don't get good answers that way, you may
   try emailing me directly.
   
   Info about the SquirrelMail Plugins mailing list can be found
   on the SquirrelMail web site.  It is currently located at:

   http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
   squirrelmail-plugins@lists.sourceforge.net



Quick Start
===========

   Since Vlogin has an extensive and somewhat intimidating configuration
   set, there are a few ways to use this plugin without having to wade
   through the entire configuration file.  There are both some "meta-
   configuration" sets offered as well as several sample configuration 
   files that can help ease installation and setup.  Vlogin will also
   work without any configuration whatsoever, if its default behavior
   suits your needs.

   Please note that all references to configuration files for Vlogin
   assume you are looking in the vlogin/data/ directory.

   If you install Vlogin without doing any configuration, its default
   behavior is to assume your IMAP usernames are to be in the format
   "username@example.net" and that the domain (in this case "example.net")
   is determined by looking at the domain used to come to the login
   page (so users only need to type in the "username" part of their 
   login).  The settings used come directly from the sample configuration
   file "config.sample.typical.php".  If your desired functionality
   is very similar to this, it is advised to copy "config.sample.typical.php"
   to "config.php" and modify that file as needed (perhaps by adding
   some domain-specific login image to the $virtualDomains array
   or changing the value of $numberOfDotSections or $removeDomainIfGiven,
   etc.  See below for more tips on common variations of this 
   configuration.

   There are some pre-configured "meta-configuration" sets that are 
   a very easy way to make use of a small subset of Vlogin's functionality.
   Currently, the following "meta-configuration" options are available,
   although more may be added depending on user feedback.

     $strip_domain_only
     ------------------
     turns on the settings needed to make sure user logins
     have any domain stripped off of them if given.  That
     is, "jamie@example.net" is changed to "jamie".

     $add_default_domain_only
     ------------------------
     turns on the settings needed to make sure that user
     logins always have the default SquirrelMail domain
     applied to them.

   To activate any of these, the file "meta_config.sample.php" should
   be copied to "meta_config.php" and then the one "meta configuration
   set" therein should be turned on.

   Also, if a regular "config.php" custom Vlogin configuration file
   is found *IN ADDITION* to one of the "meta configuration sets",
   the configuration settings in "config.php" will override the "meta
   configuration" settings, thus allowing you to fine-tune the "meta
   configuration set" behavior as needed.
   
   Finally, Vlogin also comes with some sample configuration files
   for use in some specific situations.  Whereas "config.sample.php"
   contains an exhaustive listing of all possible configuration settings,
   "config.sample.per_user_functions_only.php" is a suggested configuration
   set for environments where only the per-user settings functionality
   is desired (see $perUserSettingsFile setting explanation below).
   The "config.sample.service_level_functions_only.php" file is a 
   suggested configuration when only per-user group ("service level") 
   functionality is desired (see $serviceLevelBackend and associated
   setting explanations below).  And the "config.sample.typical.php" 
   file mentioned above is also available.  To make use of any of these 
   sample configuration sets, simply copy one of them to "config.php"
   (in the vlogin/data/ directory of course) and adjust the settings
   therein as needed.

   One semi-frequent variation on the settings in "config.sample.typical.php"
   is to turn on $dontUseHostName (and possibly $removeDomainIfGiven) if 
   usernames are of the format "username" (with no domain portion).  This 
   would allow, for example, different logos to be displayed on the login 
   page for different domains, but for local usernames to be used to login.
   You may want to watch out for the need to use 
   $smHostIsDomainThatUserLoggedInWith in this situation.

   Also, if you want to leave usernames completely unmolested and only
   do something like show a different image on the login page for each
   of your domains, make a copy of "config.sample.typical.php" and turn
   on $dontUseHostName and then add your domain customizations to the
   $virtualDomains array.

   Remember, using $vlogin_debug will help show how the username is 
   (or is not) being manipluated and is recommended to help fine-tune
   your configuration before asking for help.



FAQ
===

   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: 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.
        


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

   Vlogin configuration can be complex, but most applications of this plugin
   require little to no modification of the sample config.php file.  Please
   see the "Quick Start" section elsewhere for information about the most 
   common and easiest Vlogin settings.  

   The config.sample.php file contains documentation for each configuration
   setting, but please also read below to understand how they work.  Also, 
   turn on the $vlogin_debug flag if you're having trouble configuring the 
   plugin.

   All on/off settings should be set to 1 to turn on and 0 (zero) to turn off.

   When using Vlogin to append some form of the login page's URL to the 
   username, the host portion of the URL is taken and manipulated in any
   number of ways, and then combined with the username given on the login 
   page.  How the host name is manipulated and combined with the username 
   is highly configurable.  Most of these configuration parameters can be 
   used in conjunction with one another, but some are best not combined - use 
   the comments below (along with common sense) to determine the settings 
   that you need to make.  Also, refer to the file config.php.sample.typical 
   for one standard implementation.

   Note that if the user logs in with a full username that includes a host name
   (detected by sensing the presence of an @ sign, or whatever you set the $at
   setting to) such as "paul@example.com", then unless you specifically strip
   the domain off of the usernames, Vlogin by default will assume they know 
   what they are doing and not attempt to do any host name manipulation at all 
   (what is given is what is passed to IMAP).  Again, this is default behavior,
   which can be changed by using $removeDomainIfGiven if needed.

   Note that instead of keeping all of your per-domain settings in this one
   configuration file, you may also create multiple configuration files - one
   for each domain - in the vlogin/data/domains directory.  Each file is named:

      <domain name>.vlogin.config.php

   where <domain name> is the host name as it will look AFTER vlogin has 
   manipulated it per the settings below (as such, you'll probably only want to 
   include the $virtualDomains setting in that file (but feel free to experiment
   otherwise - one global setting that will work in this file is $vlogin_debug)).


   $useDomainFromVirtDomainsArray
   ------------------------------
   indicates that vlogin should use the "domain" setting from the 
   $virtualDomains array (see below) for the hostname portion of the login 
   username instead of using the parsed domain from the login URL (which will 
   still be used if "domain" is not given in the relevant $virtualDomains 
   section).  This makes many settings below obsolete as long as you always 
   specify a "domain" in all of your $virtualDomain entries.  Set this to
   zero only if you want to ensure that vlogin always uses the parsed login 
   URL for constructing and appending the domain portion of the user's login.

   $useDomainFromServerEnvironment
   -------------------------------
   indicates that vlogin should use the domain directly from the web server
   environment for the hostname portion of the login username instead of
   using the parsed domain from the login URL.  This makes many settings 
   below obsolete.  The value of this setting should be the name of the server
   environment variable to be used ("SERVER_NAME" is probably the most common).
   Set to a blank string to turn off.  

   $numberOfDotSections
   --------------------
   dictates the size (given in "dot sections") that the hostname should be.  
   Thus, "dot sections" are removed from the host name until it only contains 
   said number of sections.

   $removeFromFront 
   ----------------
   determines if, in order to reach the size given by $numberOfDotSections, 
   "dot sections" will be taken off the beginning of the host name (or, if 
   set to zero, the host name will be trimmed from the end).

   For example, with $numberOfDotSections = 2 and $removeFromFront = 1, these
   logins will be constructed:
      webmail.foo.com         ==>     username@foo.com
      server.webmail.foo.com  ==>     username@foo.com

   or with $numberOfDotSections = 2 and $removeFromFront = 0
      webmail.foo.com         ==>     username@webmail.foo
      server.webmail.foo.com  ==>     username@server.webmail

   $chopOffDotSectionsFromLeft
   ---------------------------
   indicates that a set number of "dot sections" should be removed from the
   front of the host name.  This is done after the host name is pruned by
   $numberOfDotSections, so be careful using it in conjunction with 
   $chopOffDotSectionsFromLeft.

   $chopOffDotSectionsFromRight
   ----------------------------
   indicates that a set number of "dot sections" should be removed from the 
   end of the host name.  This is done after the host name is pruned by
   $numberOfDotSections, so be careful using it in conjunction with 
   $chopOffDotSectionsFromRight.

   For example, with $chopOffDotSectionsFromLeft = 1, these logins will be 
   constructed:
      webmail.foo.com         ==>     username@foo.com
      server.webmail.foo.com  ==>     username@webmail.foo.com
   or with $chopOffDotSectionsFromLeft = 2
      webmail.foo.com         ==>     username@com
      server.webmail.foo.com  ==>     username@foo.com
   or with $chopOffDotSectionsFromRight = 1
      webmail.foo.com         ==>     username@webmail.foo
      server.webmail.foo.com  ==>     username@server.webmail.foo
   or with $chopOffDotSectionsFromRight = 2
      webmail.foo.com         ==>     username@webmail
      server.webmail.foo.com  ==>     username@server.webmail
   or with $chopOffDotSectionsFromLeft = 1 and $chopOffDotSectionsFromRight = 1
      webmail.foo.com         ==>     username@foo
      server.webmail.foo.com  ==>     username@webmail.foo

   $reverseDotSectionOrder 
   -----------------------
   forces the host name to be inverted by dot section.  For example, 
   www.domain.com would become com.domain.www (it is important to 
   note that this is done before any of the other vlogin settings are
   applied to the host name).

   $checkByExcludeList 
   -------------------
   indicates that any "dot sections" in the host name that match those given in
   the $notPartOfDomainName should be removed.

   $notPartOfDomainName
   --------------------
   is an array of "dot sections" that should be removed from the host name when
   $checkByExcludeList is set to 1.  Add to it as needed.

   For example, with $checkByExcludeList = 1 and $notPartOfDomainName 
   containing 'www' and 'mail', these logins will be constructed:
      www.foo.com       ==>     username@foo.com
      foo.mail.com      ==>     username@foo.com
      www.foo.mail.com  ==>     username@foo.com

   $always_prepend
   ---------------
   allows a static text string to be prepended to the user domain.  The
   given text will be prepended after all other rules have been applied
   (except hostname mapping or Qmail virtual domain unaliasing).

   $always_append
   --------------
   allows a static text string to be appended to the user domain.  The
   given text will be appended after all other rules have been applied
   (except hostname mapping or Qmail virtual domain unaliasing).

   $at and $dot
   ------------
   can be used when your IMAP logins use different characters where an
   "@" or "." are typically used in a standard email address.  Specify 
   replacement characters as needed.

   For example, with $at = '.',  these logins will be constructed:
      www.foo.com       ==>     username.foo.com
   or with $at = '.' and $dot = '-'
      www.foo.com       ==>     username.foo-com

   $atConversion
   -------------
   is useful if your users tend to confuse '@' and '%' in their email
   addresses.  You can specify a list of characters here that will, if 
   found in the user name, all be converted to whatever you have specified 
   for the $at setting.

   $forceLowercase
   ---------------
   makes sure that everything is done in lowercase, including the host
   name and the username.  Many IMAP servers are not case sensitive, so
   this setting can usually be ignored.  Please do not confuse this with
   the SquirrelMail $force_username_lowercase setting, although this 
   setting may have the same ultimate effect.

   $replacements
   -------------
   is a list of characters or character sequences that you may specify
   to be replaced in or removed from the host name.  Each item in this 
   list should have an associated replacement value or an empty string 
   in the case that it should be removed from the host name.  Note that 
   these replacements are done in the order given.  See the sample
   configuration file for examples.

   $alwaysAddHostName
   ------------------
   forces the host name to be added to the given user name, no matter
   what.  You'll probably only need to turn this on if you convert
   your "@" sign into a character that is also present in your usernames
   (such as ".").  You should try to avoid using this setting if possible.

   $putHostNameOnFrontOfUsername
   -----------------------------
   indicates that when the username and host name are combined together,
   the host name should be prepended to the username, instead of default
   behavior, which is to append it to the end of the username.  In both
   cases, the $at setting separates the two values.

   For example, with $putHostNameOnFrontOfUsername = 1 and $at = '.',
   these logins will be constructed:
      www.foo.com  ==>     www.foo.com.username

   $dontUseHostName
   ----------------
   allows you to turn off all host name manipulation and simply log in 
   with whatever the user typed into the login field.  This allows 
   you to use the other functionalities of the plugin such as specifying
   IMAP servers or login page images per domain (or user) without touching
   the login information.

   $dontUseHostnameUserList
   ------------------------
   allows you to specify a list of users for whom you'd like 
   $dontUseHostName to be turned on; all other users will get the value 
   as set for $dontUseHostName elsewhere in the configuration file.  
   The username used to log in must exactly match the usernames in this
   list to activate $dontUseHostName.

   $smHostIsDomainThatUserLoggedInWith
   -----------------------------------
   typically only used when $dontUseHostName is set to 1, this setting 
   is a way to avoid changing the username but at the same time grabbing
   the host name from the login URL and making sure the user's email
   domain is such (otherwise it will default to whatever is specified in 
   the main SquirrelMail configuration for ALL users -- but usually only
   when you turn on $dontUseHostName).

   $rawLoginIsOutgoingEmailAddress
   -------------------------------
   can be used if the original login usernames for your system are the
   correct outgoing email addresses, but for purposes of IMAP login
   are mapped to something else.  Turning this setting on preserves the
   original "raw" username and sets the users' outgoing email addresses
   as such.  Turn off the ability to edit personal identity in the main
   SquirrelMail configuration or users will be able to override this
   at will.  Also, use this with caution, since it trusts that the 
   original unmodified username input is a valid outgoing email address,
   so can possibly be a SECURITY LEAK.  There are probably other ways
   to configure Vlogin to get the desired behavior, or use one of the
   following plugins:
      Retrieve User Data
      http://www.squirrelmail.org/plugin_view.php?id=11
      Ask User Info
      http://www.squirrelmail.org/plugin_view.php?id=142
      New User Wizard
      http://www.squirrelmail.org/plugin_view.php?id=181

   $removeDomainIfGiven
   --------------------
   will strip off any domain information from the username if it was
   given as a full email address.  That is, if a user logs in with 
   "jose@domain.com", it will strip off "@domain.com".  The domain
   that is parsed from the URL by this plugin will be added back to
   the username unless you are using the $dontUseHostName functionality.
   This is a good way to force users to log into the domain that they
   used to access the login screen; thus they cannot trick Vlogin.
   It can also be used in the case that your usernames never include
   domain information but some users think (erroneously) that they 
   need to log in with their full email address.

   $usernameDomainIsHost
   ---------------------
   is a way to trust the user (careful!) that the hostname portion of
   the login username is the correct domain to use to determine all
   virtual domain settings for the user's login session.  Usually this
   is zero, since you usually want to keep users from logging in from
   the wrong domain.

   $virtualDomainDataDir
   ---------------------
   is an override of the SquirrelMail data directory specification, and
   is useful in that it allows you to insert the virtual domain name 
   and/or user name into that path (use the strings "###VIRTUAL_DOMAIN###" 
   and "###USERNAME###" respectively anywhere in this setting to do so).
   Note that another way to accomplish this is to override the data
   directory for any one (or more) domain(s) inside of the $virtualDomains
   array below.

   $allVirtualDomainsAreUnderOneHost
   ---------------------------------
   is a setting that indicates that the virtual domain host name will
   be part of the URI somewhere after the actual host, for sites that 
   host all of their virtual domains off of the same tree (usually for 
   reasons having to do with SSL certificate limitations).

   This setting's value must be a regular expression that will capture
   the domain portion of the URI in the first group (set of parenthesis).
   Leave as an empty string to turn this functionality off.

   For example, when the URI of the login page is something like:

      "http://www.onedomain.com/virtualdomain.com/mail",

   and the regular expression is '/[\/]*(.*?)(\/|$)/', the IMAP login 
   will be constructed as "username@virtualdomain.com".  Likewise, use
   '/domain=(.*?)(&|$)/' to parse the domain out of URIs like this:

      http://www.onedomain.com/mail/webmail.php?domain=virtualdomain.com

   $securePort
   -----------
   is the port that HTTPS is served over.  You should not need to 
   change this value.

   $stripDomainFromUserSubstitution
   --------------------------------
   removes the domain portion (if present) of the username given
   by the user ONLY when replacing values in the $virtualDomains
   array and $virtualDomainDataDir.  This setting has no effect 
   on how the username is handled anywhere else by this plugin.  
   Set to zero to leave the username as is.

   $usernameReplacements
   ---------------------
   is a list of characters or character sequences that you may specify
   to be replaced in or removed from the user name as given by the user.  
   Each item in this list should have an associated replacement value or 
   an empty string in the case that it should be removed from the user 
   name.  Note that these replacements are done in the order given and
   that they are done prior to the lookup for $sendmailVirtualUserTable, 
   in case you are also using that.  See the sample configuration file 
   for examples.

   $sendmailVirtualUserTable
   -------------------------
   is a string that specifies the full path to a sendmail-style virtual 
   user table which is used to remap user logins as specified in that file. 
   The table will be consulted after any host name manipulation has been 
   done and can be used in non sendmail environments as well.

   For example, if the virtual user table looks like:
      @mydomain.com              jose
      kobayashi@mydomain.com     masaki
      info@domain2.com          info@domain3.org

   Then someone who logs in as "kobayashi" (or "kobayashi@mydomain.com" as
   the case may be) will be logged in to IMAP as the user "masaki", and
   anyone else who logs in to the virtual domain "mydomain.com" (for example,
   "mike@mydomain.com") will be logged in to IMAP as user "jose".  
   "info@domain2.com" will be logged in to IMAP using "info@domain3.org".

   $translateHostnameTable
   -----------------------
   is a string that specifies the full path to a host name translation 
   table which is used to remap the domain host name that your users 
   use to log in.  Most users of this plugin should leave this as an
   empty string, since they will not need this functionality.  This 
   functionality might be necessary if your web services are provided 
   at a different location than your MX (email server) is.

   For example, if all users log in to SquirrelMail at 
   "www.companywebdomain.com/mail", but have email accounts in the 
   form "user@companyemail.com", then it'd be helpful to remap 
   "companywebdomain.com" to "companyemail.com".  

   Also, source host names can contain the wildcards * and ?
   which indicate "any number of (or zero) characters" and "one
   alphanumeric character" respectively.

   A sample translation table should look like:
      companywebdomain.com      companyemail.com
      mywebhost.*               myemailhost.org

   See the file hostmap.sample.php for more information and examples.
  
   Finally, note that all host translation is done after any pre-
   processing (per other settings such as $numberOfDotSections or
   $checkByExcludeList, etc) of the initial host name to give you
   maximum flexibility in dealing with what you get from the URI
   used by the user.

   $pathToQmail
   ------------
   is a string that should contain the installation path for 
   Qmail *if and only if* you are using Qmail/Vpopmail aliased
   domains and want to prevent users of aliased domains from 
   logging in to a domain alias and/or the actual domain, thus
   accidentally creting more than one preferences (and address
   book, etc) files for themselves.  Otherwise, please leave this
   as an empty string.

   Also, when using this functionality, please verify that the user 
   you run httpd with is able to read the file ~qmail/users/assign

   $default_org_logo
   -----------------
   allows an "org_logo" to be used as a fallback in case an org_logo
   setting for one of your domains does not actually exist.  Vlogin 
   does NOT check that $default_org_logo exists, however.  Leave as
   an empty string to always use the org_logo as given for each domain.

   $perUserSettingsFile
   --------------------
   is a string that specifies the full path to a file containing per-user
   setting overrides for any of the settings available in the main config
   file (usually you'll want to override SquirrelMail settings such as IMAP
   server address, etc.).  Any number of users may have their settings 
   individually changed, using the following format in that file (see 
   users.sample.php for an example):

   One user per line - username (as per their actual IMAP login) comes
   first, then any settings are given by specifying the setting name 
   and the desired value, separated by an equal sign - all fields are
   separated by commas (and optional whitespace).  For example:

      username@full.imap.login, imapServerAddress=localhost, imapPort=143

   When an array of values needs to be specified for a single setting,
   such as a list of plugins to be enabled for one user, the values
   are to be separated with a double comma.  For example:

      username@full.imap.login, domain=abc.com, enable_plugins=debugger,,username, imapPort=143

   Also note that usernames can contain the wildcards * and ? which
   indicate "any number of (or zero) characters" and "one alphanumeric 
   character" respectively.  

   For example, the username "jose_r*@domain.com" would match the 
   username "jose_rodriguez@domain.com" as well as "jose_riviera@domain.com".
   "jose?@domain.com" would match "jose5@domain.com", but not 
   "jose@domain.com", although the pattern "jose*@domain.com" would 
   match both "jose5@domain.com" and "jose@domain.com".  

   Finally, note that if a username listed in this file also matches 
   one or more username patterns, the exact match takes precedence, 
   so you may provide patterns with special overrides.

   $IMAPServerRules
   ----------------
   provides a mechanism to apply the same rules described elsewhere
   in this document to the user's domain in order to determine the
   correct IMAP server address for the user.  This is an array of 
   settings that mirror the configuration items: notPartOfDomainName,
   chopOffDotSectionsFromRight, chopOffDotSectionsFromLeft,
   numberOfDotSections, checkByExcludeList, at, dot, replacements,
   removeFromFront, translateHostnameTable, pathToQmail,
   reverseDotSectionOrder, always_prepend, and always_append.  For
   an explanation of how each of these behaves, see their analogues
   elsewhere in this document.  If any of these settings is contained
   in the $IMAPServerRules array, the user's IMAP server is 
   determined from those rules and used instead of the default 
   SquirrelMail IMAP server address.  NOTE that these rules are 
   applied to the domain part of the username given by the user, or
   if not given, to the domain name as determined from the URL.

   $SMTPServerRules
   ----------------
   provides a mechanism to apply the same rules described elsewhere
   in this document to the user's domain in order to determine the
   correct SMTP server address for the user.  This is an array of 
   settings that mirror the configuration items: notPartOfDomainName,
   chopOffDotSectionsFromRight, chopOffDotSectionsFromLeft,
   numberOfDotSections, checkByExcludeList, at, dot, replacements,
   removeFromFront, translateHostnameTable, pathToQmail,
   reverseDotSectionOrder, always_prepend, and always_append.  For
   an explanation of how each of these behaves, see their analogues
   elsewhere in this document.  If any of these settings is contained
   in the $SMTPServerRules array, the user's SMTP server is 
   determined from those rules and used instead of the default 
   SquirrelMail SMTP server address.  NOTE that these rules are 
   applied to the domain part of the username given by the user, or
   if not given, to the domain name as determined from the URL.

   $useSessionBased
   ----------------
   tells vlogin if it can store its configuration settings in the user's
   PHP session, which helps boost performance and ensures that custom
   settings are applied in all circumstances.  To use this setting, you
   need to install the Multilogin plugin (and, if using SquirrelMail
   1.5.1 or lower, the patch included with that plugin (quite simple, 
   don't worry)).  You need not enable Multilogin in conf.pl unless you 
   are also using it; just having it in place in the plugins directory 
   is all that is required.  Otherwise, leave this setting turned off, 
   and the old (deprecated) functionality will be used.

   NOTE: as of 1.5.2, because no source patch is required to turn this
   setting on, and because of the performance and stability it provides,
   this setting is highly recommended.  Just download and unpack the
   Multilogin plugin and set $useSessionBased to 1 and that's it.

   $virtualDomains
   ---------------
   is an array that lets you override any SquirrelMail or VLogin settings
   on a per-domain basis.  Most any of the attributes you see when you run 
   SquirrelMail's config/conf.pl configuration script can be overridden, 
   as well as most of the settings found in the vlogin config file itself.  
   For help with the format of this array, see any of the sample config 
   files.  Only those settings that you want to override need to be 
   listed; and there need not be any consistency between domains.  Note 
   that each domain is specified in this array by any string that is 
   unique to the virtual host name (not necessarily the whole host 
   name -- "mydomain" is probably enough to represent "mydomain.com").  
   See the sample configuration file for examples.

   It is possible to specify a global (or default) virtual domain by 
   using the name '*'.  If used, any domain not specified here will
   inherit the attributes specified in the global virtual domain.  Note
   that you MUST put this domain at the top of the list, or vlogin will
   complain very loudly.

   You may use the string "###VIRTUAL_DOMAIN###" (without the quotes) to
   insert the virtual domain name into any of these settings (such as 
   org_name, etc.)

   You may use the string "###USERNAME###" (without the quotes) to
   insert the user name into any of these settings (such as org_name, etc.)

   It is also possible to embed PHP code in many of the settings in the
   $virtualDomains array, but you must tell vlogin which ones you have 
   done so with.  Do so by defining a special "settingsWithEmbeddedPHP"
   setting for each domain.  This setting should be an array contianing
   the names of all settings that contain embedded PHP code.  Note that 
   in order to embed the PHP code, you need to wrap the entire value in 
   single quotes.  See the examples for "org_title" in the sample 
   configuration files.  Note that some settings can also use raw PHP 
   (not embedded), which will be evaluated much earlier than embedded 
   code - raw PHP may be slightly faster but embedded code may be 
   necessary depending on the availability of the variables you may be 
   using in your code at the time of evaluation.  See the examples of 
   both methods with the "motd" setting in the sample configuration files.

   Note that you may enable or disable individual plugins for a given domain
   by adding the keywords "enable_plugins" and "disable_plugins" to this 
   array.  Each of these keywords should have as its associated value an
   array listing the targeted plugin names.  The names in each list should 
   match the exact plugin name (same as the directory it redsides in).
   Of course, as with most other vlogin configuration options, these settings
   are completely optional.  See the config.php.sample file (near the bottom)
   for a syntax example.

   It is also possible to disable options page items for a domain (also
   in the per-user config file) by adding the keyword "disable_options"
   to this array.  This keyword should have an array as its value.  
   That array should be a list of option names (enclosed in quotes) that 
   should be removed from any of the options pages you desire (Display 
   Preferences, Folder Preferences, Personal Information).  This 
   functionality is a good compliment to the Forced Preferences plugin or a 
   good way to disallow a user from entering a fake email address on the
   Personal Information screen.  See the config.php.sample file for an 
   example.  The options you may currently disable follows, but this is 
   ever-changing, so check the source code for the most up-to-date list.

      Display Preferences
         chosen_theme   
         custom_css
         language
         javascript_setting
         js_autodetect_results
         show_num
         alt_index_colors
         page_selector
         page_selector_max
         show_full_date
         wrap_at
         editor_size
         editor_height
         location_of_buttons
         use_javascript_addr_book
         show_html_default
         enable_forward_as_attachment
         forward_cc
         include_self_reply_all
         show_xmailer_default
         attachment_common_show_images
         pf_cleandisplay
         mdn_user_support
         compose_new_win
         compose_width
         compose_height
         sig_first
         reply_focus
         internal_date_sort
         sort_by_ref
         
      Folder Preferences
         folder_prefix
         trash_folder
         sent_folder
         draft_folder
         location_of_bar
         left_size
         left_refresh
         unseen_notify
         unseen_type
         collapse_folders
         unseen_cum
         date_format
         hour_format
         search_memory
         mailbox_select_style
         
      Personal Preferences
         full_name
         email_address
         reply_to
         signature
         identities_link
         timezone
         reply_citation_style
         reply_citation_start
         reply_citation_end
         use_signature
         prefix_sig

   Also, be aware that you do not need to put anything in this array
   for vlogin to work.  If you only need user name reconstruction and no
   other per-domain customization, then you can leave it empty (or only
   include those domains that require any customization).

   NOTE - A few settings such as IMAP server might not work by just making
          the setting in $virtualDomains.  In this case, you should make sure
          you are using $useSessionBased and have the Multilogin plugin (and
          applied the Multilogin source patch if using SquirrelMail versions 
          less than 1.5.2).

   Other plugins may make use of the $virtualDomains array by simply 
   accessing it in the global scope and using unique setting names 
   appropriate for the plugin.  For example, the email_footer plugin 
   can add a different outgoing footer to emails for any domain if
   you add "email_footer" and/or "email_footer_HTML" to the $virtualDomains
   array.  See the documentation for other plugins for information about
   the settings names they expect here.

   Finally, keep in mind that you can split out the $virtualDomains array
   into a separate file for each of your domains if desired, as explained
   at the top of this document (in the directory vlogin/data/domains).

   $serviceLevelBackend
   --------------------
   When different user classes exist, you can define them using
   "service levels" and attach different sets of SquirrelMail
   settings to each one.  The $serviceLevelBackend setting turns
   on the "service level" functionality and tells where and how 
   to determine what service level group the current user belongs 
   to.  Currently, you may choose from:

      0 = off, not in use
      1 = internal (see $internalServiceLevelFile)
      2 = SQL (see $sqlServiceLevelDSN and $sqlServiceLevelQuery)

   Whatever back end to the "service level" functionality you choose,
   the back end is expected to return the name of a service level
   for the current user (or an empty value if no service level is
   found for the user).  The names of the service levels are arbitrary
   and may be defined as needed, as long as a corresponding settings
   file is found in the vlogin/data/service_levels directory (file
   names should be in the form <service level name>.php).  See the 
   sample "premium" settings file in that directory for an example.
   Note that that file should contain any settings you want to override
   for the service level, most of which will usually be in the 
   $virtualDomains array.  Even if you do not use the $virtualDomains
   functionality in vlogin, you should still use it in this context,
   and simply use the default domain key of "*".  However, you are
   also free to use domain names in this context to define service
   levels differently for any domains you host.

   Note that because of the way some settings are initialized in
   the SquirrelMail core, there may be some settings that cannot
   be changed in this manner.  Trial and error is the best way to
   determine which ones work the best.
   
   $internalServiceLevelFile
   -------------------------
   When using Vlogin's internally supplied service level file, specify 
   the path to it here.  More details about this file are available in 
   the provided sample file vlogin/data/service_levels.sample.php

   $sqlServiceLevelQuery
   ---------------------
   When using a SQL database to specify user service levels, this 
   setting must be a valid SQL query that extracts ONLY the service 
   level value for the given user.
  
      %1 in this query will be replaced with the user name

   An example is included in the sample configuration file.

   $SQLDatabaseDomainLookup
   $SQLDatabaseUserLookup
   $SQLDatabaseServiceLevelLookup
   -------------------------------
   indicate that Vlogin settings can be found in a SQL database backend.
   These setting's values should be the queries used to look up those settings 
   in the database.  
 
      %1 in each query will be replaced with the user name, domain or
         service level when looking for per-user, per-domain or per-
         service level settings

   The queries should return a set of setting names and their values (two 
   columns per row).  Also, please make sure that $vlogin_dsn has been 
   correctly configured.  A sample Vlogin settings table DDL is as follows 
   (MySQL, easily converted to other database syntax):

      CREATE TABLE squirrelmail_settings (
         username      varchar(128) default '',
         domain        varchar(128) default '',
         service_level varchar(128) default '',
         setting_name  varchar(128) NOT NULL,
         setting_value varchar(255) default '',
         PRIMARY KEY (username, domain, service_level, setting_name),
         UNIQUE KEY squirrelmailm_setting (username, domain, service_level, setting_name),
         KEY username (username),
         KEY domain (domain),
         KEY service_level (service_level)
      ) TYPE=MyISAM;

   A sample set of queries that can be used against this DDL might look like:

      $SQLDatabaseUserLookup = 
         'SELECT setting_name, setting_value FROM squirrelmail_settings WHERE username = "%1"';
      $SQLDatabaseDomainLookup = 
         'SELECT setting_name, setting_value FROM squirrelmail_settings WHERE domain = "%1"';
      $SQLDatabaseServiceLevelLookup = 
         'SELECT setting_name, setting_value FROM squirrelmail_settings WHERE service_level = "%1"';

   Note that with this kind of setup, you can streamline the definition 
   of settings that are the same for some users, domains or service
   levels (although this may also be too confusing to manage) by having
   the user, domain and/or service level columns for the same row non-null.

   Of course, if you have a separate table with all your domain settings,
   you can simply change the $SQLDatabaseDomainLookup query to reference
   that table, etc.

   Setting values of "true" and "false" (case insensitive) will be turned
   into their corresponding boolean values.  Values that should be 
   reconstructed as arrays should have their keys and values separated by
   equal signs (key and equal sign are optional) and their array elements 
   separated with double commas.  For example:  1=red,,2=green,,3=yellow
   Or this syntax is also acceptable:  red,,green,,yellow
   If an array only has one element, be sure to add a double comma to the
   end of the value like this:  1=red,,

   Note that all settings found in the database will override those found
   in any of the file-based configuration files (actual load order and 
   (inverse) precendence should be file-based per-domain, SQL per-domain, 
   file-based service level, SQL service level, file-based per-user, SQL 
   per-user).  If one of these settings is empty, no SQL database 
   functionality will be used to look up Vlogin settings for the 
   corresponding group (users, domains or service levels).

   $vlogin_dsn
   -----------
   When using a SQL database to specify user service levels or any
   other Vlogin settings, this must be a valid DSN that connects to 
   the database with enough permission to read the appropriate table.
   Theoretically, any SQL database supported by Pear should be supported
   here.  A MySQL example is included in the sample configuration file.  
   For more details about DSN syntax and list of supported database types, 
   please see:
      http://pear.php.net/manual/en/package.database.db.intro-dsn.php

   $vlogin_debug
   -------------
   allows you to view the IMAP login that is being constructed for you.
   Set to 1 to see why the damn plugin isn't working.  ;>



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...
   // setup.php files are loaded by plugins.php and as such,
   // the vlogin_version() function should be available.
   //
   // 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();
   }



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.9.0  2006.10.15  Paul Lesneiwski <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 Lesneiwski <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 Lesneiwski <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  27.02.2005  Paul Lesneiwski <paul@squirrelmail.org>
    *  Added $usernameDomainIsHost
    *  Added $stripDomainFromUserSubstitution
    *  Fixed broken sendmail-style virtual user table functionality

 v3.6  08.02.2005  Paul Lesneiwski <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 Lesneiwski",
       which could be remapped to "paul.lesneiwski@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 Lesneiwski <paul@squirrelmail.org>
    *  Added ability to disable options on Display Preferences,
       Personal Information, and Folder Preferences screens.

 v3.4.1  22.08.2004  Paul Lesneiwski <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 Lesneiwski <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 Lesneiwski <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 Lesneiwski <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 Lesneiwski <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 Lesneiwski <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 Lesneiwski <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 Lesneiwski <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.

