Apache for Windows Manual Configuration

Web Connection supports Apache 2.0 and 2.2 (and later) in full featured ISAPI mode. Prior versions are supported only with the somewhat limited CGI mode and this is not recommended. You'll want to use the ISAPI mode for best performance and the ability to run Web Connection in COM mode.

Web Connection provides a custom Apache ISAPI module (mod_webconnection_isapi.so and mod_webconnection_isapi_20.so) that can be found in the \scripts directory of your Web Connection installation. There are two versions: The default 2.2 compatible version and a 2.0 specific version (mod_webconnection_isapi_20.so). The Web Connection console will pick the right module based on the version of Apache installed. If you manually install make sure you pick the correct version of these module files for copying into the Apache Modules directory.

This custom Apache provides the following:

Basic Authentication against Windows User accounts
Path fix ups to match IIS pathing formats

Please note that if you plan on using Apache, you should be familiar with Apache Configuration and security. It is your responsibility to lock down Apache server and your application and provide common customization features. The Web Connection installer only provides basic hook ups for Apache operation of Web Connection.

Automatic Configuration

The process of configuration is integrated into Web Connection's Configuration utilities so if you Create a new Project or use the Configure your Server Console applications they automatically configure your Apache server for the application. To do this simply choose Apache as your Web Server on the first page of each of the Wizards.

The Wizards will handle the following:

Copy the mod_webconnection_isapi.so to the Modules directory
Create a Web directory under Apache's htdocs folder creating a standard Web Connection Web setup
Set configuration settings in httpd.conf:
Load mod_webconnection_isapi.so
Set up virtual directory
Add a script handler for each mapped extension and Web Connection.dll
Configure a ScriptAlias for non-file script extensions URLs

All of this automatic and we recommend that you take advantage of this functionality using the Console application both for first time configuration (New Project Wizard) and for server configuration (Configure your Server Wizard).

Manual Configuration

Manual configuration of Apache is accomplished by:

Copying the Web Connection Apache ISAPI module
Create a virtual directory for your Web files
Copying the Web Connection DLL
Modifying the httpd.conf file by
Mapping the Web Connection Apache Module
Creating a 'Virtual' Alias Directory
Setting scripting options on this directory
Setting up any script map extensions

Copying the Web Connection Apache Module
The Web Connection module is found in the /scripts directory of the Web Connection installation. You should always copy this directory with your application to the server so the scripts directory is available to copy the files from within it to the server. To copy the file:

COPY FILE "<webconectionInstallFolder>\scripts\mod_webconnection_isapi.so" TO;
               "<ApacheRoot>\modules\mod_webconnection_isapi.so"

If you're using a version of Apache prior to 2.2 use:

COPY FILE "<webconectionInstallFolder>\scripts\mod_webconnection_isapi_20.so" TO;
               "<ApacheRoot>\modules\mod_webconnection_isapi.so"

MSVCR7.DLL Required
Apache doesn't ship with recent Microsoft CRT runtimes, so you have to copy MSVCR7.DLL from the Web Connection install root, into your Windows directory if it's not already there (servers often won't have it). Automatic configuration copies this file automatically if not present, manual configuration requires you to do it.

Create an Apache virtual directory
Typically virtual directories are created underneath the Apache\htdocs directory. This Web path will hold all of your Web related files - HTML files, images, script pages etc.

Into this directory you should copy the standard Web Connection related project files which are stored under <wcInstall>\HTML which is the Web template for the project.

Copying the Web Connection DLL
The most important file for the Web installation is the Web Connection ISAPI DLL (wc.dll). If you copied from a template this file will already be there otherwise you can find it here:

COPY FILE TO "<webconnectionInstallFolder\scripts\wc.*" TO ;
                    "<WebDirectory>\BIN\wc.*"

This copies both wc.dll and wc.ini configuration file. wc.ini holds Web Connection configuration information in an INI file format and you'll need to confgure this file to match the settings in your server file. Specifically make sure you set the path (which is the temp file path for file based messaging) and the Template which needs to match the settings configured in your Web Connection server (<yourapp>.ini)

;*** THIS DIRECTORY MUST HAVE READ AND WRITE ACCESS FOR THE
Path=d:\temp\wcapache\

;*** Message File Template (1st 3 letters)
;*** Default is "wc_"          Only needed if using a different template
Template=WC_

Modifying httpd.conf
Apache configuration is handled through the httpd.conf file which lives in the /conf folder of the Apache Configuration. Web Connection adds a few entries to this file. There are a couple of global settings and a host of settings specific to each virtual directory/application that you configure.

At the bottom of the file add the following:

#*** WEB CONNECTION MODULE CONFIGURATION
LoadModule webconnection_isapi_module modules/mod_webconnection_isapi.so
#*** END WEB CONNECTION MODULE CONFIGURATION

#*** WEB CONNECTION VIRTUAL - wconnect

#*** WEB CONNECTION SCRIPT ALIAS
ScriptAliasMatch (?i)^/wconnect/.*\.(wc|wcs|wcsx|wwsoap|wwd|blog|pho|wwr)$ "C:\Program Files\Apache2.0\Apache2\htdocs\wconnect\wc.dll"
#*** END WEB CONNECTION SCRIPT ALIAS

Alias /wconnect/ "C:/Program Files/Apache2.0/Apache2/htdocs/wconnect/"

<directory "C:/Program Files/Apache2.0/Apache2/htdocs/wconnect/">
DirectoryIndex default.htm
Options ExecCGI
# AddHandler isapi-handler dll
AddHandler webconnection-isapi-handler dll
#*** WEB CONNECTION VIRTUAL SCRIPT MAPS
AddType application/webconnection-scriptmap .wc .wcs .wcsx .wwsoap .wwd .blog .pho .wwr
Action application/webconnection-scriptmap "/wconnect/wc.dll"
#*** END WEB CONNECTION VIRTUAL SCRIPT MAPS
</directory>
#*** END WEB CONNECTION VIRTUAL - wconnect


#*** WEB CONNECTION VIRTUAL - wwthreads

#*** WEB CONNECTION SCRIPT ALIAS
ScriptAliasMatch (?i)^/wwthreads/.*\.(wwt|wc)$ "C:\Program Files\Apache2.0\Apache2\htdocs\wconnect\wc.dll"
#*** END WEB CONNECTION SCRIPT ALIAS

Alias /wwthreads/ "C:/Program Files/Apache2.0/Apache2/htdocs/wwthreads/"

<directory "C:/Program Files/Apache2.0/Apache2/htdocs/wwthreads/">
DirectoryIndex default.htm
Options ExecCGI
# AddHandler isapi-handler dll
AddHandler webconnection-isapi-handler dll
#*** WEB CONNECTION VIRTUAL SCRIPT MAPS
AddType application/webconnection-scriptmap .wwt .wc
Action application/webconnection-scriptmap "/wwthreads/wc.dll"
#*** END WEB CONNECTION VIRTUAL SCRIPT MAPS
</directory>
#*** END WEB CONNECTION VIRTUAL - wwthreads

The comment lines (#) are optional but recommended as they are placeholders for the Web Connection configuration routines that allow you to update the settings using the Wizards or programmatic tools to configure the server. If you add the comments for auto-configuration make sure the comment lines are EXACTLY as above (ie. cut and paste!).

The key features are:

LoadModule loads the Web Connection Apache module. This is a global setting and should only be specified once in the file.

ScriptAliasMatch is used to deal with script mapping. It routes any custom extension you'd like to configure to the Web Connection ISAPI DLL. NOTE: it's crucial that this directive is declared before the Alias for the virtual is defined - otherwise you will get File Not Found errors on any requests that access non-file backed 'scripts'.

Alias creates a Virtual directory. It maps a logical/virtual path to a physical path.

The <directory> tag contains configuration settings for the specific directory on disk. It specifies the default document(s), and that this directory supports dynamic script operation (ExecCGI). It also sets up the Web Connection ISAPI DLL as a script handler for any files that map to the extensions specified in the AddType command. Action then maps the type specified to the Web Connection ISAPI DLL as the script handler. These script handlers are actually not required if you use a ScriptAliasMatch as above, but they are left in here in case ScriptAliasMatch is missing or misconfigured - AddType will catch any scriptmapped requests that have a backing file.

Programmatically setting Configuration Settings

In addition to manual configuration you can also programmatically configure Apache. You can use the wwWebServer Class to perform these tasks:

DO WCONNECT
SET CLASSLIB TO WebServer ADDITIVE

oWeb = CREATEOBJECT("wwWebServer")
oWeb.cServerType = "APACHE"

*** Create a virtual directory 
oWeb.CreateVirtual("WebDemo","d:\westwind\webdemo")
oWeb.CreateScriptMap(".wp","d:\westwind\webdemo\bin\wc.dll","WebDemo")
oWeb.CreateScriptMap(".wpp","d:\westwind\webdemo\bin\wc.dll","WebDemo")

*** Edit the .Config file
lcConfigFile = oWeb.GetWebRoot() + "conf\httpd.conf"
GoUrl(lcConfigFile)   && Opens in Notepad for editing

Using wwApacheRequest instead of wwRequest

Let's move on to the Web Connection FoxPro configuration of the server. Again this step is automatically performed for you when you create your project with the New Project wizard and choose Apache as your Web server.

Apache returns some server variables slightly differently than IIS does and so a special subclass of the wwRequest class called wwApacheRequest is used to handle these differences. IIS returns some platform specific server variables that are not returned by Apache - but most of these are truly platform specific and rarely used so this should not be a problem.

The wwApacheRequest class handles path fixup for requests by explicitly checking paths and trying to automatically fix up the physical path to match the true physical path of a given script.

To use the wwApacheRequest class you can simply assign the cRequestClass in the your main wwServer class which is contained in <yourApp>Main.prg. The following code demonstrates:

DEFINE CLASS WebdemoServer AS WWC_SERVER OLEPUBLIC

cRequestClass='wwApacheRequest'
...

Alternately you can also override this globally using the following flag in your WCONNECT_OVERRIDE.H file:

#UNDEFINE WWC_REQUEST
#DEFINE WWC_REQUEST wwApacheRequest

The former is a little less intrusive and isolates the change to the current application, while the latter can be easier if you need to do this with multiple applications as the flag is global to all Web Connection applications.

Set the CallCoInitialize flag in wc.ini
Starting with Version 4.50 Web Connetion no longer calls CoInitialize by default on COM requests by default. This fixed a number of issues with IIS as IIS had some issues with multiple calls to CoInitialize and potential mismatched CoUninitialize calls. IIS automatically calls CoInitialize for each thread, so there's no need to do it again.

Apache however does not do this, so we need to tell the Web Connection ISAPI dll to explicitly to call CoInitialize/CoUninitialize. To do so we set the CallCoInitialize flag in the wc.ini file:

[Automation Servers]
;*** Severloading - 0 - Normal  1 - Round Robin
ServerLoading=1

;*** KeepAlive  0 - Normal  1 - Force extra COM reference to keep alive
KeepAlive=1

Server1=webDemo.webDemoServer
;Server2=webDemo.webDemoServer

;*** Determines whether CoInitialize for COM objects
;*** Set this option to 1 only if your servers do not
;*** load and given an error message to the effect 
;*** that COM is not initialized. Should only be needed
;*** on ancient or non-Microsoft Web Servers.
CallCoInitialize=1

Your wc.ini file is found in the same directory as wc.dll which will be your Web virtual directory usually in the BIN path.

Configuring Apache Security for Web Connection

Apache does not support application driven Basic Authentication so Web Connection's default mechanism for accessing admin links and the like won't work. Your only choice to work around this limitation is to configure Apache for directory security and create script files for admin operations in a separate, protected directory.

To work around these issues and provide the basic security for locking down administration functions in the Web Connection DLL, the Web Connection Apache ISAPI Module provides Windows based Basic Authentication. When using the custom module, programmatic Basic Authentication works just like it does in IIS by authenticating against Windows User accounts rather than using Apache's password files.

This lets you set security in the wc.ini configuration file:

;*** Account for Admin tasks    REQUIRED FOR ADMIN TASKS
;***       NT User Account   -  The specified user must log in
;***       Any               -  Any logged in user
;***                         -  Blank - no Authentication
AdminAccount=Any

Apache Security Note
Web Connection will override security with the custom behavior only if Apache has not provided its own security implementation. If you lock down directories and Apache can authenticate users prior to hitting the Web Connection module, the Apache authentication takes precendence. To avoid confusion in this scenario you should avoid using Basic Authentication outside of programmatic use within your Web Connection applications. Instead choose Digest or other custom security scheme for directory based rights in Apache - this will avoid any conflicts.

Check with your Apache Administrator for more information on setting up Web Server authentication for requests.