W*API Plug-In/Apple CGI Operation in a WebTen Virtual Host Environment

WebTen may be configured with one or more "virtual" hosts in addition to the main host. A virtual host or "vhost" may be ip-based (having a unique Internet address) or name-based (based on the name in the HTTP/1.1 protocol "Host" header in a HTTP request). A name-based vhost's name will resolve (via DNS) to an IP address associated with the main host while an ip-based vhost's name will resolve to an IP address that does not overlap with any of the main host's DNS addresses. For purposes of this discussion, name-based and ip-based vhosts are identical.

Each vhost will likely have its web site folder rooted in a unique place in the Macintosh Hierarchical File System or the WebTen Fast File System. A W*API Plug-in/CGI that processes a URL request from WebTen must assume that the document root folder will change for every request received. A plug-in/CGI that assumes a static document root folder or treats the folder containing the WebTen application as the document root folder will not function properly in a virtual host environment.

Plug-ins should always use the W*API parameters piURLFileRef (the Mac FSSpec for the requested file), piServerDirectoryPath (a colon separated full path to the vhost's document tree), and piPluginDirFSSpec (the Mac FSSpec for the plug-in folder) when processing URL's and plug-in related configuration files under WebTen.

The CGI Sdoc Apple Event

The W*API CGI specification lacks an Apple Event parameter to indicate the document root or website folder for a request made on a virtual server. Under WebTen, an event parameter DIRE has been added to the sdoc Apple event sent by the server to the CGI. The DIRE parameter is an FSSpec to the document root of the vhost handling the request.

For seamless operation in a WebTen virtual host environment while remaining compatible with WebSTAR, the CGI should use the DIRE FSSpec if present in the sdoc event in constructing the path to the file being requested.

In addition, a DocR event has been added to WebTen application event suite that, given a server name (typeChar) in the direct parameter, will return an FSSpec to the server's document root folder. The DocR event may be sent to WebTen outside of a connection request context to obtain information about a vhost's document folder.

Some older Macintosh CGI's may not tolerate the presence of the extra parameter in the sdoc AppleEvent. To support these CGI's, WebTen has a per-virtual-host configuration option, ACGIEventExtensions, to disable the inclusion of DIRE in the AppleEvent.

W*API Limitations on Server Parameters

The W*API 1.1 specification allows for reading and writing server global settings. Under WebTen, most global server settings can be applied on a per-vhost basis. This allows, for example, each vhost to maintain its own log file, default MIME type, or connection statistics. Unfortunately, except during actual connection processing, there is no way for the server to determine for which vhost the plug-in WSAPI_Set/GetParameter request applies. Under W*API 1.1, WebTen necessarily must treat parameter requests outside of a connection thread as requests on the main or "default" server.

As a matter of policy, WebTen limits what global parameters a plug-in/CGI can set over what is allowed by the W*API specification. Further, WebTen only permits setting of global parameters during initialization and idle processing. The effect is twofold:

  1. Global parameters may only be set for the default server.
  2. Vhost parameters are available for reading only during connection processing.

Similarly, WebTen Apple event suite events are processed only in the context of the default server. Except as noted above, vhost parameters are not available to a CGI using AppleEvents outside of a connection request.

Page last updated 12/28/1999