Squirrelmail and WASD PHP

These are some guidelines for installing and configuring Squirrelmail for PHP under WASD.

http://www.squirrelmail.org/

It is not a definitive document.  It is basically just a description of how I managed to get Squirrelmail running.  There are undoubtably alternate approaches.  These guidelines were developed using Squirrelmail out-of-the-box.  These guidelines are based on the Squirrelmail QuickAndDirty installation notes (http://www.squirrelmail.org/wiki/en_US/QuickAndDirty). 

This software configuration information is provided under the terms of the GNU General Public Licence as published by the Free Software Foundation; version 2 of the License, or any later version.

16 January 2005

Disclaimer

I am not an administrator, not even a casual user of Squirrelmail.  I undertook this exercise to demonstrate how it might be supported under WASD PHP.  There is no point in querying me personally on Squirrelmail setup, quirks, changes, etc.  If there is something incorrect within these guidelines or information by which they could be improved then by all means advise me.  Likewise if it's suspected WASD or WASD PHP is misbehaving itself or requires refinement.

mark.daniel@wasd.vsm.com.au

Session File Access Conflict

PHP-based webmail applications that use HTML frames are prone to conflicts of access to it's on-disk session files.  This is well known and documented issue with CSWS PHP 1.2 (PHP 4.3.2) that takes two forms.  File-access conflict, where one frame reports the session file locked by another process.  This can be circumvented using the  DECC$FILE_SHARING  feature logical name.  When this is enabled a second issue immediately has the potential to cause problems.  It would appear as if the session file is emptied by one process (frame) while attempting to be read by another (frame).  This results in an error message and/or ACCVIO.  Obviously this is a major issue.  Anyone has a fix for these behaviours?

Squirrelmail seems particularly prone to this problem.  See Session Acccess Kludge for a workaround.

Requirements

These guidelines were developed in the following environment.  Other combinations may work, or may not.

Installation

Restore the archive to disk.
$ set process /parse=extended
$ set default ODS5_DISK:[000000]
$ vmstar -xf
dev:[dir]Squirrelmail-1^.4^.4-rc1.tar
This creates a directory
ODS5_DISK:[Squirrelmail-1^4.^4-rc1]

File-System

A concealed device logical name must be defined.  To make this permanent it needs to placed in a system or Web-related startup procedure. 
$ define /system /executive /translation=concealed -
         Squirrelmail
ODS5_DISK:[Squirrelmail-1^.4^.4-rc1.]
This directory structure must be made accessable to the default WASD server and scripting accounts.
 
$ sechan == "$ht_exe:sechan"
$ sechan /asif=runtime
ODS5_DISK:[000000]Squirrelmail-1^.4^.4-rc1.dir
$ sechan /asif=runtime ODS5_DISK:[Squirrelmail-1^.4^.4-rc1...]*.*
If a different account is used to execute Squirrelmail similar considerations will need to be made.

Runtime Storage

Squirrelmail documentation recommends storing it's session and other runtime data outside of the Squirrelmail application tree.  This is sage advice, removing one less security issue and making version updates straight-forward.  A directory structure separate from the Squirrelmail source will be created.  The will be pointed to in the Squirrelmail configuration refered to later
$ create /directory ODS5_DISK:[Squirrelmail-data.session]
$ create /directory
ODS5_DISK:[Squirrelmail-data.attachments]
This directory structure must be made readable by the server account and writeable by the scripting account.
$ sechan /asif=scratch ODS5_DISK:[000000]Squirrelmail-data.dir
$ sechan /asif=scratch
ODS5_DISK:[Squirrelmail-data...]*.dir
$ set file /version=1 ODS5_DISK:[000000]Squirrelmail-data.dir
$ set file /version=1
ODS5_DISK:[Squirrelmail-data...]*.dir
If a different account is used to execute Squirrelmail similar considerations will need to be made.

A concealed device logical name must be defined.  To make this permanent it needs to placed in a system or Web-related startup procedure. 
$ define /system /executive /translation=concealed
-
         Squirrelmail-data ODS5_DISK:[Squirrelmail-data.]
Unwanted files may accumulate over time in these areas.  This can happen if a user does not explicitly logout of their Squirrelmail session and then creates another from a fresh browser.  Some routine cleanup is required.  The wrapper script provides for deleting session and attachment files older than two days each time it is first started up.

PHP Configuration

Squirrelmail requires some tailored initialization parameters.
$ copy ht_root:[src.php]php.ini Squirrelmail:[000000]phpwasd.ini
$ edit
Squirrelmail:[000000]phpwasd.ini
Modify or add the following parameters:
include_path = ".:.."
extension = php_pcre.exe
extension = php_session.exe
extension =
php_xml.exe
session.save_path = /Squirrelmail-data/session
Check Squirrelmail configuration documentation for other recommended settings.

WASD Scripting Wrapper

A Squirrelmail-specific wrapper procedure  SquirrelmAIL.COM  can be placed in  HT_ROOT:[CGI-BIN]
$! SQUIRRELMAIL.COM
$ set noon
$!(clean up any lingering session files, etc., older than two
days)
$ define /user sys$output nl:
$ define /user sys$error nl:
$ delete squirrelmail-data:[sessions...]*.*;*
/before=-2-00:00:00
$ define /user sys$output nl:
$ define /user sys$error nl:
$ delete
squirrelmail-data:[attachments...]*.*;* /before=-2-00:00:00
$ define decc$argv_parse_style enable
$ define
decc$efs_case_preserve enable
$ define decc$efs_charset enable
$ define decc$efs_case_special enable
$ define
decc$enable_getenv_cache enable
$ define decc$posix_seek_stream_file enable
$ define decc$file_sharing enable
$ define
phpwasd$ini squirrelmail:[000000]phpwasd.ini
$ mcr cgi_exe:phpwasd.exe

WASD Mapping Rules

WASD mapping rules then make the application accessable.
 
# HTTPD$MAP
map /squirrelmail**/ /squirrelmail/index.php
exec /squirrelmail/**.php
(@cgi-bin:[000000]squirrelmail.com)/squirrelmail/*.php \
     ods=5 script=syntax=unix script=query=relaxed
map=once
pass /squirrelmail/* /squirrelmail/* dir=noaccess
If you wish to be able to browse the source using the Web server you can also add a rule something like
pass /_squirrelmail/* /ODS5_DISK/squirrelmail-1.4.4-rc1/*
Load these new rules into the server:
$ HTTPD /DO=MAP

Squirrelmail Configuration

A configuration file needs to be created before squirrelmail can be used.
$ copy squirrelmail:[config]config_default.php squirrelmail:[config]config.conf 
$ sechan
/asif=runtime squirrelmail:[config]config.php
$ edit squirrelmail:[config]config.php
Modify the value of  $data_dir  to reflect the data directory created earlier.
$data_dir = '/squirrelmail-data/';
At this stage other constants may be modified to suit the site.  For example:

Session Access Kludge

Squirrelmail, apparently in common with other PHP applications deployed on VMS, is very prone to failing due to conflicts of access to, or indeterminate contents of, it's on-disk session files.  After experimenting for some time searching for in vain for an elegant solution I decided on a quick-and-dirty workaround (for now).  The problem appears to occur when both HTML frames are accessing the server simultaneously.  I decided to slow one down!  I'm embarressed to recommend the following source code change.
$ edit sqirrelmail:[functions]global.php
and add the indicated line as shown.  The number of seconds in the  sleep()  statement can be varied according to the speed of processing at the local site.  I found ten seconds worked consistently on my development Alphastation 500/333.
function sqsession_is_active() {

    $sessid =
session_id();
    if ( empty( $sessid ) ) {
        /** this kludge just crudely slows down processing of the
left-hand frame **/
        if ($_SERVER['SCRIPT_NAME'] == '/squirrelmail/src/left_main.php')
sleep(10);
        session_start();
    }
}
This looks like it might make the application unworkable.  Eight seconds on a network application seems like an eternity.  In practice however, the delay is experienced infrequently.  Most of the activity of mail management is undertaken in the right-hand frame, with the left pretty much static.

Obviously a real solution, prefereably at the PHP level, needs to be developed if this sort of application is going to succeed on VMS.

Application Access

Using the above mapping rules the basic method for accessing the application is
http://the.host.name/squirrelmail/

- end of document -