Virtual Host Login ("vlogin") plugin for SquirrelMail
=====================================================
Ver 3.8.0, 2005/10/19

Authors: Paul Lesneiwski <pdontthink@angrynerds.com>
         Ryan Orth <snubber-sm@seahat.com>


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

VLogin is...
   a plugin for squirrelmail for installations that host more than one domain
   and need some amount of customization for each domain without installing
   a separate SquirrelMail for each domain.  Vlogin can do a lot of things,
   such as:

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

   VLogin may also be used in a context where you only want to enable per-user
   or service level settings and you do not host multiple domains.



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



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 grok 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.  All 
   configuration options are located in the file config.php, but please
   read below to understand how they work.  Also, turn on the $vlogin_debug 
   flag if you're having trouble configuring the plugin.


   To determine the correct IMAP login, the plugin takes the host portion of 
   the URL that was used to access the login page, manipulates it in any number
   of ways, and then combines it 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.

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

   Note that if the user logs in with a full username that includes a host name
   (detected by sensing the presence of an @ sign) such as "paul@virt.domain.com",
   then this plugin 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).

   IMPORTANT WARNING: Make sure your config.php file contains NO linefeeds
   (blank lines) after the last ?> in the file!  Otherwise you'll face nasty
   (and seemingly unrelated) consequences.



   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.

   $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

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

   $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).

   $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.dat 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 creating 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.dat 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.

   $useSessionBased
   ----------------
   tells vlogin if it can store its configuration settings in the user's
   PHP session, which helps boost performance.  To use this setting, you
   need to install the Multilogin plugin and 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.

   $virtualDomains
   ---------------
   is an array that lets you override any SquirrelMail or VLogin settings
   on a per-domain basis.  Any of the attributes you see when you run 
   SquirrelMail's config/conf.pl configuration script and select 
   Organization Preferences (#1), Server Settings (#2), or Folder Defaults 
   (#3) can be overridden, as well as any 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 applied the Multilogin
          source patch.

   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.dat.sample

   $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.  ;>


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



CHANGE LOG
==========

 v3.8.0  2005.10.19  Paul Lesneiwski <pdontthink@angrynerds.com>
    *  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 <pdontthink@angrynerds.com>
    *  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 <pdontthink@angrynerds.com>
    *  Added $usernameDomainIsHost
    *  Added $stripDomainFromUserSubstitution
    *  Fixed broken sendmail-style virtual user table functionality

 v3.6  08.02.2005  Paul Lesneiwski <pdontthink@angrynerds.com>
    *  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 <pdontthink@angrynerds.com>
    *  Added ability to disable options on Display Preferences,
       Personal Information, and Folder Preferences screens.

 v3.4.1  22.08.2004  Paul Lesneiwski <pdontthink@angrynerds.com>
    *  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 <pdontthink@angrynerds.com>
    *  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 <pdontthink@angrynerds.com>
    *  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 <pdontthink@angrynerds.com>
    *  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 <pdontthink@angrynerds.com>
    *  (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 <pdontthink@angrynerds.com>
    *  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 <pdontthink@angrynerds.com>
    *  Minor update for compatibility with password_forget plugin.
    *  Minor update for compatibility with login_alias plugin.


 v2.5  09.01.2003  Paul Lesneiwski <pdontthink@angrynerds.com>
    *  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.

