Local User Autoresponder and Mail Forwarder plugin for SquirrelMail
===================================================================
Ver 3.0, 2007/07/18


Authors: Jonathan Bayer <jbayer@spamcop.net>
         Paul Lesniewski <paul@squirrelmail.org>
         Dan Astoorian



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

This plugin allows users to set an auto-reply message to 
incoming email, which is most commonly used to notify the 
sender of one's absence.  This plugin also allows users to
specify that mail be forwarded to (an)other email address(es).
You can use the autoresponder or forwarding components 
independently of one another, or use them both.  

This plugin is limited to use with mail systems where mail 
users have real local accounts, or at least where users have
FTP access to "home" directories that the mail server knows
about when delivering mail.  Please note that this plugin is
ONLY a front-end for configuring autoreplies and/or forwarding
addresses and IS NOT responsible for executing those 
functionalities during the mail delivery process.  Before 
installing this plugin, you need to have a fully functioning
autoresponder/forwarder system in place on your mail server.

This plugin is capable of managing vacation and/or .forward
files on your server via either FTP or a local SUID program.  
If you use the SUID program, it will only work on a local system
(or possibly via a NFS mount or similar).  Also supported are 
lookups of FTP server name in LDAP.

This plugin is based on the vacation plugin written by 
Ronald Luten <r.luten@oad.nl>, which was itself based upon 
a plugin called "Mail Configuration" that was available back 
when Squirrels were still living in caves.  That plugin was 
written by Chris Wakelin <c.d.wakelin@rdg.ac.uk> and was
also based losely on the "Forward File Editor" add-on for 
TWIG (see http://twig.screwdriver.net/addons.php3) by 
<monica-k@usa.net>.  No one can say credit isn't given 
where credit is due.

See the INSTALL file for setup instructions.

Also see the "contrib" directory for a sample Python script 
that can be used to pre-populate all user .forward.fwd, 
.vacation.subj, .vacation.sq, and .vacation.pref files.  It
was developed under Python 2.3, but may also run under 2.2.



License
=======

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



Donations
=========

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

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



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

  * SquirrelMail version 1.4.0 or above

  * Compatibility plugin version 2.0.7 or above, unless
    using SquirrelMail 1.5.2+

  * Unless you are only using this plugin for mail forwarding,
    the vacation program needs to be installed and your
    mail system needs to be configured to use it.  For most 
    sendmail configurations it also means you need to put 
    a symbolic link in /etc/smrsh to the vacation program. 
    The RPM for RedHat can be found here:
    ftp://ftp.redhat.com/pub/contrib/libc6/i386/vacation-1.2.2-2.i386.rpm

  * The configuration (vacation/.forward) files usually need to 
    reside in the top level of the users' home directories

  * If you use the FTP backend, the PHP FTP extension needs
    to be enabled (--enable-ftp).  Please see:
    http://php.net/manual/ref.ftp.php



Configuration
============= 
      
The configuration options for the plugin functionality are all
documented in the config.sample.php file.

When using the suid backend, you can usually configure it without 
adding any options, however, the configure command accepts the 
following options:

  --enable-webuser[=USER]                -- Specify the user that is allowed 
                                            to run the program (default is
                                            "apache")

  --enable-auth=shadow                   -- Authenticate against 
                                            passwords in /etc/shadow

  --enable-auth=passwd                   -- Authenticate against 
                                            passwords in /etc/passwd

  --enable-auth=pam                      -- Use PAM for authentication

  --enable-pamservice=SERVICE            -- Specify service name 
                                            for use with PAM

  --enable-vacation[=PATH]               -- Enable running the vacation 
                                            command (in order to be able 
                                            to execute the "init" command)

  --enable-vacation-init-flag[=FLAG]     -- Specify flag to pass to the
                                            vacation command for use when 
                                            initializing the vacation 
                                            database (e.g., -I)

  --enable-vacation-userarg              -- Specify that the username should 
                                            be passed as an argument to the 
                                            vacation "init" command

  --enable-vacation-pathenv[=DIR:DIR...] -- PATH to pass to vacation "init"
                                            command

  --enable-empty-passwords               -- Permit empty passwords in passwd 
                                            or shadow files (not recommended)

  --enable-min-uid=UID                   -- Don't allow uids less than this 
                                            minimum to run the program

  --enable-silent                        -- Never send messages to stderr

  --enable-filenames[=VALUE]             -- VALUE can be any of the following:
                                              * "restricted" (default) 
                                                Requires remote filenames to 
                                                begin with ".forward" or 
                                                ".vacation" 
                                              * "dotfiles" 
                                                Requires remote filenames to 
                                                begin with "." 
                                              * "any" 
                                                Permits remote filenames to 
                                                begin with any legal character
                                              * "subdirectories" (NOT RECOMMENDED!)
                                                Allows subdirectories to be 
                                                accessed (e.g., mail/.forward)

  --enable-homedir-prefix=PATH           -- (Advanced) Specify a path to be 
                                            prefixed to home directories

  --enable-create-homedir                -- (Advanced) Create home directory 
                                            if it doesn't exist

  --enable-remote-filemode=mode          -- Set the file permissions to use when 
                                            creating remote files

  --enable-homedirmode=mode              -- Set the directory permissions to use
                                            when creating home directories (use
                                            with --enable-create-homedir) 

  --enable-remote-chars=CHARSET          -- (Advanced) Change the set of 
                                            characters which may appear in a 
                                            remote filename to this list

  --disable-remote-chars                 -- Do not restrict characters in
                                            remote filenames (NOT RECOMMENDED!)

  --disable-webuser                      -- Permit any user to run the program
                                            (NOT RECOMMENDED!)

For more details regarding these configuration options, consult 
"./configure --help" as well as the comments at the top of the 
suid_backend/squirrelmail_autoresponder_forwarder_proxy.c file.



Troubleshooting
=============== 
      
  * If vacation messages are not being sent when mail arrives or
    mail is not being forwarded to the addresses you designated, 
    first verify that you have correctly installed and configured
    your mail server to correctly serve vacation responses and/or
    forward incoming mail.  This plugin IS NOT RESPONSIBLE for 
    providing that functionality in your mail server.  You MUST 
    first have a *fully functioning* autoreply/forwarding system 
    on your mail server BEFORE you attempt to use this plugin.

  * If you are having problems configuring and compiling the suid
    backend, you can try to compile it manually.  For example:

       cc -DUSESHADOW squirrelmail_autoresponder_forwarder_proxy.c -o squirrelmail_autoresponder_forwarder_proxy -lcrypt

  * If you have any problems running the suid binary backend,
    you need to turn on $vac_debug and $debug_suid_output_file
    (at the bottom of config.php).  If you see error numbers 
    when the plugin fails to work correctly, here is a key to
    the errors used in the suid backend:

    ERR_OK            0    --  No error
    ERR_NOTFOUND      1    --  File not found
    ERR_BADPASS       32   --  Bad password
    ERR_USAGE         33   --  Usage error
    ERR_RESTRICTED    34   --  Not allowed to use this program
    ERR_REMOTEFILE    35   --  Illegal remote filename
    ERR_LOCALFILE     36   --  Illegal local filename
    ERR_CONFIG        37   --  Global configuration problem
    ERR_USER          38   --  Problem with this user
    ERR_HOME          39   --  Problem accessing home directory
    ERR_SOURCEFILE    40   --  Problem opening/stat()ing source file
    ERR_DESTFILE      41   --  Problem opening/deleting dest file
    ERR_COPYFILE      42   --  Problem copying file contents
    ERR_UNLINK        43   --  Problem unlinking file
    ERR_FILETYPE      44   --  Not a regular file
    ERR_EXEC          45   --  Exec() of vacation program failed
    ERR_NOTSUPPORTED  46   --  Feature not enabled
    ERR_PRIVILEGE     125  --  Unexpected privileges problem
    ERR_UNEXPECTED    126  --  Other unexpected error

  * If you are receiving error 34 when using the suid backend, if the
    user who runs your web server is not "apache", you need to use
    the "--enable-webuser" configuration option to specify the correct
    user.

  * If you are receiving error 46 when using the suid backend and you
    have enabled $initialize_when_create or $initialize_when_change in 
    the configuration file, make sure you configured the suid backend 
    with "--enable-vacation".

  * If you are receiving error 127 when using the suid backend, you
    may have PHP settings that prohibit or limit how PHP can create
    command pipes.  Please check your PHP configuration or any SELinux
    restrictions that may be in place.

  * When using the ftp backend along with $www_initialize, similar PHP
    (or SELinux) issues (see above) may affect the correct operation 
    of the initialization command.  Also check that you can correctly
    run the vacation command as the user that runs your web server
    (see below).

  * If you are using $initialize_when_create or $initialize_when_change
    with the FTP backend, the web server probably needs the ability to 
    change to the target user in order to correctly run the 
    $www_initialize command.  You should make sure to add the web server 
    user as a "sudoer" for each and every one of your webmail users, or 
    figure out something more clever (and send in your ideas).  Here is 
    one way to accomplish the former - add this to your sudoers file, 
    usually /etc/sudoers (make sure to change "apache" to whatever user 
    runs your web server):

       Runas_Alias MAILUSERS = {list of users using webmail and need vacation functionality}
       apache ALL=(MAILUSERS) NOPASSWD: /usr/bin/vacation

  * If you are using the FTP backend and files are not being created
    with the correct umask (some MTAs will refuse to read vacation
    files with group write permission), check your FTP server configuration.
    For WU-FTP, the needed change is reportedly as such:  edit /etc/ftpaccess
    and change the "defumask" line to read:

       defumask 022 all

    Then restart the server.



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

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

  * Read the Troubleshooting section herein.  Have you verified 
    that your mail system's vacation/forwarding functionality 
    already works?  Please do not send inquiries asking why your 
    mail system's autoreply functionality does not work unless 
    you are convinced it is because this plugin has created 
    wrongly-formatted vacation or .forward files.

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

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

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



TODO
====

  * Possibly split Autoresponder and Mail Forwarding into 
    two separate Options blocks and thus two separate management
    screens
  * When $allow_black_hole is 2, users can elect to forego local
    mail delivery when no forwarding or autoresponse is turned
    on, but the plugin doesn't upload a .forward file under that
    circumstance.  We could add another configuration setting that
    specifies the contents of .forward when it should be just 
    sending mail to /dev/null (or similar) and use that to upload
    .forward in this case.... here is what the configuration 
    docs looked like for that setting:
//    2  =  Allow "no local delivery" under any circumstance (NOT
//          recommended and probably does NOT work as expected -
//          when no forwarding nor autoreply is active, this plugin
//          does not install a .forward file and thus does not
//          actually prevent local delivery)



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

  v3.0 2007/07/18
    * Changed plugin name: make sure to deactivate and remove
      any older vacation_local plugin you might have before
      installing this one; reconfiguration from scratch is 
      also highly recommended.
    * Changed the default value of $sq_vacation_subject_file;
      when upgrading from Vacation Local 2.0, you should check
      this setting carefully
    * Several exploits in the SUID backend were identified by
      Dan Astoorian, and he provided a re-write of the backend
      IMMEDIATE upgrade is recommended for all users of the
      SUID backend
    * Updates to bring plugin into step with newest SquirrelMail
      plugin specifications
    * This plugin can now be used as ONLY a mail forwarding
      management interface (without an autoresponder).
      See $maintain_autoresponder
    * Added 1.5.2 compatibility
    * Added several new configuration possibilities (mostly for
      somewhat more unusual mail systems): see the configuration
      file for more details about $auth_user_localpart_only,
      $other_forward_file_contents_*, $aliases_full_email_format,
      $forward_file_format_pattern, $forward_file_format_replace,
      $auto_enable_autoresponder, $allow_black_hole, etc.
    * Added default vacation subject/message (set by admin)
    * Don't upload vacation or forward files unless user clicks
      the Submit button
    * Reworded the "no local delivery" option (inverted meaning
      in the interface)
    * Added script to help pre-populate .forward/.vacation files
    * Several other small fixes and enhancements

  v2.1 2005/10/25
    * Added optional init (vacation -I)
    * Added support for vacation -h flag
    * Added options in config.mk for compilation on FreeBSD
    * Added SSL FTP functionality 
    * Escaped all arguments to suid calls
    * Only make one FTP connection per page request instead of one
      for each get, put, delete, etc.
    * Added PAM authentication option to the suid script
      (Thanks to Christiane Ruetten <cr@inef.uni-duisburg.de>)
    * Added $vacation_command_quotes and $local_delivery_syntax
      for Qmail compatibility
    * Strip extraneous non-standard newline characters from
      list of forward addresses and vacation message
    * Add umask config setting so new files have predictable permissions

  v2.0 2005/03/17
    * Integrated FTP functionality.
    * Added optional .forward file functionality
    * Added LDAP lookups of FTP server (thanks to acqant@optonline.net)

  v1.0 31/01/05
    * Fixed security exploit that allowed arbitrary suid command 
      execution as well as retrieval of any system file whatsoever.
      The name of the binary has changed, so please be sure to 
      remove all traces of the ftpfile executable from /usr/local/sbin
      or wherever else you may have installed it!
    * Changed plugin name to reduce confusion.  This means you need to 
      manually remove older versions of this plugin under the vacation 
      directory, as this version will install into the vacation_local 
      directory.
    * Lots of code cleanup.  No more register_globals=On code, no more
      one-off internationalization, no more non-standard HTML.  Whew.

  v0.15
    * Updated to work with SquirrelMail 1.4, updated for faster performance 
      model, updated for new version reporting API, internationalized most 
      of the output, cleaned up a bunch of code (it still is somewhat messy), etc.

  v0.14
    * Fixed bug in ftpfile program which would fail when an 
      absolute path was specified for the data directory

  v0.13
    * Fixed problem with program not setting the owner/group/permissions properly.

  v0.11
    * Function sqStripSlashes was removed from Squirrelmail. So 
      I inserted it into the plugin itself.

