PHP: Run-Time Environment for WASD

Contents

• Mark Berryman PHP Port
• PHPWASD
• Installation
• Update PHP
• Configure WASD
• Configure PHP
• Example Scripts
• Performance
• Command-line PHP
• DCLsymbol Extension
• Problems?
• Releases
• Acknowlegements

This is an interface to a PHP interpreter engine and environment for the WASD OpenVMS Web server. It is designed to be able to be used in standard CGI and CGIplus/RTE persistent scripting modes. The persistent modes provide a ~20x (yes, an approximate twenty times) improvement in script activation times and reduced load on server and system. PHPWASD cannot be used interactively or at the command line, it is only for scripting use. Note that this package does not contain the PHP engine, that has to be obtained separately from Mark Berryman.

Mark Berryman PHP Port

This port is more complete and up-to-date than any provided by HP, and seems always in-development. Thank you Mark Berryman.

The preceding decade of WASD PHP kits relied on elements of the CPQ/HP CSWS PHP releases. This and any subsequent release will rely on the Berryman kits. The PHP engine element can be updated independently to the WASD infrastructure supporting it.

http://www.theberrymans.com/php_kits/

These kits are provided as a ZIP archive PHP_xxx_n_n_n.ZIP where xxx is the platform (AXP or I64) and n_n_n is the major, minor and patch level release numbers of the contained PHP (e.g. 5_3_28 being 5.3.28). The PHP ZIP archive is supplied as a parameter to the INSTALL.COM procedure.

PHPWASD

This document and the kit requires WASD v10.0 or later. If not there yet it's worthwhile considering upgrading!

Where PHPWASD versions earlier than v1.4.4 have been installed it is strongly suggested the existing PHPWASD kit be renamed out of the way (as described in step 3 below) before installing this kit so there can be no interactions between kit contents. After successful installation and testing the previous directory trees may be deleted.

The WASD kit supplies the RTE source code, DCL installation and startup procedures, some elementary scripts, and this document — the WASD infrastructure — the Berryman kit provides the PHP environment, all executables including the PHPWASD interface — the PHP engine. With earlier kits local object code was used to build the required WASD RTE. All executables are now derived from the Mark Berryman kit. In fact it's not possible to build PHPWASD.EXE locally without the corresponding PHP header files which are not supplied with the Mark Berryman kit. However if you have the headers then the PHPWASD.C source file should compile and interoperate with any PHP 5 to date — 5.2 or earlier, 5.3 and 5.4 versions.

Installation

1. Obtain the PHPWASD kit from

   http://wasd.vsm.com.au/wasd/

2. Obtain the (most recent) platform-specific Mark Berryman kit from

   http://www.theberrymans.com/php_kits/

3. It is suggested that any existing PHPWASD kit be renamed out of the way before installing this kit so there can be no interactions between kit contents. After successful installation the previous directories may be deleted.

   $ RENAME WASD_ROOT:[000000]PHP.DIR WASD_ROOT:[000000]PHP_nnn.DIR
   $ RENAME WASD_ROOT:[SRC]PHP.DIR WASD_ROOT:[SRC]PHP_nnn.DIR
   

4. UNZIP the PHPWASD archive

   $ SET DEFAULT WASD_ROOT:[000000]
   $ UNZIP location:PHPWASD144.ZIP
   

5. Install the WASD infrastructure and PHP engine

   $ SET DEFAULT WASD_ROOT:[SRC.PHP]
   $ @WASD_ROOT:[SRC.PHP]INSTALL location:PHP_xxx_n_n_n.ZIP
   

6. Check release notes in the respective directory of WASD_ROOT:[PHP.xxx] for any recommendations against the release.

7. Configure the Web server

8. Configure the PHP environment

9. Start scripting  :^)  Try the example scripts.

   With the default configuration PHP script files are placed into [CGI-BIN] by the INSTALL.COM procedure (examples from WASD_ROOT:[SRC.PHP.SCRIPTS]).

10. When you're satisfied you want to keep it add

    $ @WASD_ROOT:[SRC.PHP]PHP_STARTUP.COM

    (or the equivalent) to your system/Web startup procedures

The content of the Mark Berryman kit as restored to the WASD_ROOT:[PHP.xxx] directory (as of PHP 5.3.28 kit).

The PHP release may be updated independent of the WASD infrastructure.

1. Obtain the (most recent) platform-specific Mark Berryman kit from

   http://www.theberrymans.com/php_kits/

2. It is suggested that any existing PHP directory be renamed out of the way before installing this kit so there can be no interactions between kit contents. After successful installation the previous directory may be deleted.

   $ RENAME WASD_ROOT:[000000]PHP.DIR WASD_ROOT:[000000]PHP_nnn.DIR
   

   In any case, ensure you can access and if required continue to use the in-production PHP.INI configuration file!

3. Install the PHP engine and other elements

   $ SET DEFAULT WASD_ROOT:[SRC.PHP]
   $ @INSTALL PHP location:PHP_xxx_n_n_n.ZIP
   

4. Check release notes in the respective directory of WASD_ROOT:[PHP] and make any configuration adjustments that might be recommended for the release.

There are various ways to employ the WASD PHP interpreter. It can be used in vanilla CGI mode (not recommended), or in persistent CGIplus/RTE mode. Benchmarking indicates the CGIplus/RTE use reduces activation time to 5% of CGI (yes, that's correct, by more than an order of magnitude). There are subtle differences in the way CGIplus and RTE parse and provide the PATH_INFO data. See the "WASD Scripting" document for more detail.

Configuration and Mapping

One or more of the following approaches can be implemented.

• Server global configuration (WASD_CONFIG_GLOBAL) can be used to indicate to directory listings and file access the role of the file and its content-type.

  # WASD_CONFIG_GLOBAL
  [AddType]
  .INI   text/plain  initialization file
  .PHP   text/plain  PHP source
  .PHPS  text/plain  PHP source
  .PHTML text/plain  PHP source
  

  Server global configuration may also be used to activate the CGI PHP engine (not recommended).
  Do not mix CGI and RTE configurations (below). Choose one or the other.

  # WASD_CONFIG_GLOBAL
  [DclScriptRunTime]
  .PHP $PHP_ROOT:[000000]PHP_CGI.EXE
  

• The following rule requires the PHP script files to be located in the site administrator controlled /cgi-bin/ path. This may be changed using appropriate rules.

  # WASD_CONFIG_MAP
  exec /cgi-bin/*.php* ($cgi-bin:[000000]phpwasd.exe)/cgi-bin/*.php* \
       script=query=relaxed
  

• The following rule would allow .php type files anywhere in the mapped directory structure to be executed. Deploy with caution as this allows any PHP script in the tree to be activated. PHP applications often require this approach to mapping. See PHP Applications for further comment. The script=as= is optional but it is often recommended to run applications in a dedicated account separate to the rest of the server environment. Note immediately following the exec rule is a pass rule providing access to all the non-PHP resources (style sheets, icons, images, etc.) often associated with an application.

  # WASD_CONFIG_MAP
  exec /app/**.php* (cgi-bin:[000000]phpwasd.exe)/app_root/*.php* \
       script=query=relaxed map=once ods=5 script=as=APP_ACCOUNT
  pass /app/* /app_root/*
  

PHP Applications

A PHP application is a package of PHP scripts and associated resources such as style-sheets, icons and other non-script files, in a single directory tree, often with various elements collected together, such as icons and scripts, but sometimes with multiple instances of these or with them interspersed amongst each other. That is, as a complex mix of file purposes.

The following rule allows .php type files anywhere in the application tree to be executed. Deploy exercising due diligence. The script=as= is optional but the recommended approach for the reasons provided above. Note immediately following the exec rule is a pass rule providing access to all the non-script resources associated with the application.

# WASD_CONFIG_MAP
exec /app/**.php* (cgi-bin:[000000]phpwasd.exe)/app_root/*.php* \
     script=query=relaxed map=once ods=5 script=as=APP_ACCOUNT
pass /app/* /app_root/*

The WASD serving model uses two independent accounts, one for more static resources and the other for overtly dynamic content, that is scripts, and is considered the minimum best practise from a security perspective. A breach in the scripting environment has less chance to compromise or damage the server core, and vice versa. Better practise is an account for every major processing system (web-based application) handled by the server. In either case the multiple accounts needing to access the application tree potentially complicates the file protection requirements.

With an interpreter such as PHP, the scripting engine, and therefore the scripting account, requires only read access to the source files and directories. If the application additionally needs to write into some portion of the file-system then of course this needs to be carefully considered and implemented. At the very least the server account requires read access to the directories so that the script may be located before activating the scripting engine. If the application tree contains non-script resources to be served then they also require read access for the server account.

There are three basic approaches. The examples are illustrative only.

1. Other considerations ignored, the simplest is to make the directory tree WORLD READ (with or without propagation ACL).

   APP.DIR;1             0.50KB    1-FEB-2014 05:16  [SYSTEM]
     (RWED,RWED,R,R)
             (DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:RWED,GROUP:R,WORLD:R)
   

   EXAMPLE.PHP;1            1KB    1-FEB-2014 05:16  [SYSTEM]
     (RWED,RWED,R,R)
   

2. The second involves an ACL that provides access to the specific accounts involved in serving up the application (this is the WASD model).

   APP.DIR;1             0.50KB    1-FEB-2014 05:16  [SYSTEM]
           (RWED,RWED,,)
             (IDENTIFIER=WASD_HTTP_SERVER,ACCESS=READ)
             (IDENTIFIER=WASD_HTTP_NOBODY,ACCESS=READ)
             (IDENTIFIER=*,ACCESS=NONE)
             (IDENTIFIER=WASD_HTTP_NOBODY,OPTIONS=DEFAULT,ACCESS=READ)
             (IDENTIFIER=*,OPTIONS=DEFAULT,ACCESS=NONE)
             (DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:RWED,GROUP:,WORLD:)
   

   EXAMPLE.PHP;1            1KB    1-FEB-2014 05:16  [SYSTEM]
           (RWED,RWED,,)
             (IDENTIFIER=WASD_HTTP_SERVER,ACCESS=READ)
             (IDENTIFIER=WASD_HTTP_NOBODY,ACCESS=READ)
   

3. The third involves creating a rights identifier, granting that to both the server and scripting(/application) accounts, and then applying an ACL to the directory tree providing READ access to that rights identifier.

   APP.DIR;1             0.50KB    1-FEB-2014 05:16  [SYSTEM]
           (RWED,RWED,,)
             (IDENTIFIER=APP_ACCESS,ACCESS=READ)
             (IDENTIFIER=*,ACCESS=NONE)
             (IDENTIFIER=APP_ACCESS,OPTIONS=DEFAULT,ACCESS=READ)
             (IDENTIFIER=*,OPTIONS=DEFAULT,ACCESS=NONE)
             (DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:RWED,GROUP:,WORLD:)
   

   EXAMPLE.PHP;1            1KB    1-FEB-2014 05:16  [SYSTEM]
           (RWED,RWED,,)
             (IDENTIFIER=APP_ACCESS,ACCESS=READ)
             (IDENTIFIER=*,ACCESS=NONE)
   

No PHP or Zend Logos?

By default WASD validates query strings in its own inimitable fashion (correctly in the author's HO). This validation interferes with the requesting of the internally generated PHP and Zend logos (as are included by the php_info.php script) and may similarly for other PHP scripts. To disable query string validation by WASD include the following WASD_CONFIG_MAP rule at an appropriate location before or at mapping of PHP scripts.

set /**.php* script=query=relaxed

PHP on ODS-5 Volumes

For scripts requiring extended file specification (EFS, located on ODS-5 volumes) the script path needs to be mapped as ODS-5.

set /**.php* script=query=relaxed ods=5

When a script environment is mapped as residing on an ODS-5 volume, any VMS-syntax file specifications contained in PATH_TRANSLATED and SCRIPT_NAME are automatically translated to Unix-style syntax. This has been demonstrated to better support PHP applications derived from such environments, in particular allowing relative directory references. This occurs whether or not the path is SET using script=syntax=unix.

For example; by default a request's underlying CGI variables might be:

After mapping being on ODS-5 and subsequent translation they are presented as:

Script Default or Home Directory

The PHPWASD engine will by default chdir() to the Unix-style syntax equivalent of the directory containing the PHP script file. It also does a setenv() against the environment variable PATH to this same string. This location may be explicitly provided using the value of CGI variable SCRIPT_DEFAULT and set on a per-script or general basis using the mapping rule Set script=default=<string>. It will accept either VMS and Unix specifications depending on the requirements of the script itself.

set /php-bin/mumble.php* script=default="/mumble_device/000000"
set /php-bin/mumble.php* script=default="mumble_device:[000000]"

"Watch" Mode

This is a basic facility to assist in debugging the interactions between the WASD server, PHPWASD scripting engine, script activation and input/output. It does not provide for debugging of the script itself but may be of some elementary assistance when investigating the environment the script is activating under. There are a number of methods for activating "watch" mode.

• Defining the logical name PHPWASD$WATCH_SCRIPT_NAME to contain a (case-sensitive) string from the SCRIPT_NAME variable.

  $ define /system phpwasd$watch_script_name "php_info"
  

• Defining the logical name PHPWASD$WATCH_REMOTE_ADDR to contain the IP address of the "watching" browser.

  $ define /system phpwasd$watch_remote_addr "192.168.0.2"
  

• Adding the string "#watch" to the first line of the PHP script.
  

  <?php #watch
  echo "<h1><center>Testing the PHPINFO () function</center></h1><br>\n";
  phpinfo (INFO_ALL);
  ?>
  

• Having a string "#watch:remote_addr=..." in the first line of the PHP script, specifying the IP address of the "watching" browser.
  

  <?php #watch:remote_addr=192.168.0.2
  echo "<h1><center>Testing the PHPINFO () function</center></h1><br>\n";
  phpinfo (INFO_ALL);
  ?>
  

When either of the logical names is defined without the other each operates to enable "watch" completely independently. When defined concurrently both must match for "watch" to be enabled. For example; when PHPWASD$WATCH_SCRIPT_NAME is defined only that script is "watch"ed; when PHPWASD$WATCH_REMOTE_ADDR is defined, all scripts activated by the specified host are "watch"ed; when both are defined only the specified script can be "watch"ed by the specified host. Similar (but different :-) constraints apply to the script-embedded string.

A WATCH statement contains a statement number, timestamp, and then some free-form text (that hopefully is self-explanatory). WATCH output can also comprise a hex-dump of a block of data.

Configure PHP

The author of PHPWASD is only a PHP novice, so anything in this section should be taken with a large pinch of salt. Any scripting environment should be approached with due caution and diligence. Please ensure you are familiar with PHP and its security requirements in particular before betting the company on anything in this section.

PHP configuration is accomplished using the PHP.INI file, by default located in the PHP_ROOT:[000000] directory. The Mark Berryman kit provides suggested development and production examples in WASD_ROOT:[PHP]PHP.INI* which may be copied to the above location and modified as required.

Mapping rules configure on a per-request basis. Logical names and configuration file content are loaded once at persistent PHPWASD engine startup. Changes to configuration need to be loaded into any instantiated PHP engine(s) using $HTTPD/DO=DCL=PURGE.

PHPWASD$INI

The PHP engine has a set of default configuration parameters and so can be used without specific configuration. This not a tutorial on which changes should be made for any give circumstance, just how to pass those changes into the PHPWASD scripting engine. To change the defaults a configuration file PHP.INI should be provided. The default location of this for VMS PHP and WASD is PHP_ROOT:[000000]PHP.INI. To use a PHP.INI  from a location other than the VMS PHP default define the logical name PHPWASD$INI to locate the file. This logical name can be in any table the scripting process can access (e.g. process, job, system).

PHPWASD$INI2

PHPWASD also has a secondary PHP.INI which contains directives that override those from the primary PHP.INI. This can be useful when maintaining the site-wide PHP configuration in the primary PHP.INI while placing only those directives required to be added or modified for the particular application. To have the PHPWASD engine process this file define the logical name PHPWASD$INI2 to contain the location of the file. This can be defined in any table the scripting process can access (e.g. process, job, system). To suppress use of the primary PHP.INI file and rely entirely on the secondary for configuration define the primary logical name to the NL: device.

$ DEFINE PHPWASD$INI NL:

PHPWASD$INIS

To specify PHP.INI directives directly (and avoid the overhead of file processing) the logical name PHPWASD$INIS can be defined. The format for this string is name="value"[;name="value"], where a semicolon is used to separate directives. Any directive used in this logical overrides the same directive in the primary and secondary PHP.INI. This is an example of such a logical value string and its definition (continued for printed page clarity).

short_open_tag=1 ; expose_php=0 ; include_path="/php/application3/include"

$ DEFINE PHPWASD$INIS "short_open_tag=1 ; expose_php=0 ; include_path=""/php/application3/include"""

It is possible to pass parameters to PHP scripts and applications using the script=param=(name=value) mapping rule. The PHPWASD scripting engine checks for a number of reserved identifiers and will use the contents of those present to perform the indicated function. The primary PHP.INI cannot be supplied via mapping rule due to PHP module startup requirements.

The first example shows the specification of a primary PHP.INI file, the second of a secondary PHP.INI file, and the third the use of a configuration directive string.

set /php/application_a/* script=param=(PHP_INI="php:[application_a]php.ini")

set /php/application_b/* script=param=(PHP_INI2="php:[application_b]php.ini")

# continuation lines used for printed page clarity
set /php/application_c* script=param=(PHP_INIS=\
'short_open_tag=1 ; expose_php=0 ; include_path="/php/application_c/include"')

After configuration the following scripts may be used to confirm the environment is functioning.

• /cgi-bin/php_rules.php
• /cgi-bin/php_info.php   (no PHP or Zend logos?)
• /cgi-bin/php_openvms.php

Script sources:  WASD_ROOT:[SRC.PHP.SCRIPTS]

Performance

The performance of PHPWASD is quite respectable.
This test bench was a Digital Personal WorkStation with 1 CPU and 1536MB running VMS V8.3, HP TCP/IP Services 5.7, and

• WASD 10.3, PHPWASD v1.4.4 and PHP 5.3.28
• CSWS 2.2 and CSWS_PHP-V0502-17-1 (PHP 5.2.17)
• CSWS 2.2 and PHP 5.3.28 modifications^**

^* The (for interest) CGI comparison was enabled using the following configuration:

# WASD_CONFIG_GLOBAL
[DclScriptRunTime]
.PHP $PHP_ROOT:[000000]PHP_CGI.EXE

# WASD_CONFIG_MAP
set /cgi-bin/*.php* script=query=none script=syntax=unix ods=5

^** The CSWS comparisons were between the out-of-the-box HP-AXPVMS-CSWS_PHP-V0502-17-1.PCSI installation (PHP 5.2.17), and with images and extensions updated in accordance to the Mark Berryman kit instructions and using the production PHP.INI.

The PHPWASD.EXE engine interface is only suitable for scripting use. It cannot be used outside of the CGI environment and certainly not from the command line. It is often useful to have a PHP tool that can be used in such a manner and the PHP kit provides one. To access this image assign a symbol (foreign command) in the (SY)LOGIN.COM procedure (assumes WASD_TABLE in process search list).

$ PHP = "$PHP_ROOT:[000000]PHP.EXE"

A practical solution to a WASD site requiring data passback from a PHP script to a wrapping DCL procedure. This extension allows DCL local and global symbols to be assigned, deleted, and values accessed from within PHP.

This extension is supplied in-built with the Mark Berryman PHP engine.

Further information is available in the source code of DCLSYMBOL.C

Problems?

• With the PHPWASD script ... mark.daniel@wasd.vsm.com.au
• The info-WASD mailing list
• Perhaps comp.os.vms

Unfortunately the author of the PHPWASD interface is such a PHP novice he is not in any position to answer queries about PHP "programming" or usage. If there's an obvious behavioural problem with PHPWASD (preferably diagnosed by someone with PHP experience) then he's it though.

Releases

v1.4.5  02-FEB-2014

•  tweak for PHP 5.4.n (future release at this date)

v1.4.4  01-FEB-2014

•  employ Mark Berryman PHP kit (eliminate use of CSWS kit)

•  intial development against 5.3.28

v1.4.3  10-FEB-2011

•  extend PHPWASD$ABSORB_PRE_WRITESAPI to <stderr>

v1.4.2  17-JUL-2010

•  WASD v10.1 ProctorDetect()

•  bugfix; initialise SG(request_info), SG(sapi_headers)

•  bugfix; ImageIdent() for __ia64

v1.4.1  02-JUN-2009

•  The CSWS PHP v2.0 kit (May 2009) session management extension outputs spurious debug(?) data
    which as an interim measure has been suppressed using the PHPWASD$ABSORB_PRE_WRITESAPI logical name

v1.4.0  20-MAY-2009

•  CPQ AXPVMS CSWS_PHP V2.0 (based on PHP v5.2.6)

v1.3.0  29-JAN-2005

•  PHPWASD$WATCH_... logical names and script-embedded "<?php #watch" to activate PHPWASD 'watch' mode

•  SetCrtlFeature ("DECC$FILE_SHARING"),

•  PHPWASD$INI2, PHPWASD$INIS, PHPWASD$NO_TRANSLATE, PHP_INI2, PHP_INIS, PHP_NO_TRANSLATE,

v1.2.0  14-FEB-2004

•  CSWS PHP 1.2 (PHP 4.3.2)

•  minor conditional mods to support IA64

v1.1.0  26-DEC-2002

•  CSWS PHP v1.1

v1.0.0  16-JAN-2002

•  initial

Many thanks to Mark Berryman for his significant efforts in keeping VMS PHP current.

Of course, thanks to the PHP development team!