Skip to main content
Previous sectionNext section

Web Servers for Microsoft Windows

This section describes how to manually configure Web Servers from Microsoft and Apache on systems running Windows.

When you install Caché, you can select the option to configure your web server to work with CSP. This is what most customers do. If you do not choose this option during Caché installation, you can run the Caché installation again and select to install only the CSP Gateway components. If you do not select to configure your web server during the Caché installation, you can configure your web server manually to work with CSP. To configure your web server manually on a system running Windows, use the instructions in this chapter.

This chapter describes the most common configuration for each of the webservers, IIS 7 (and later versions), IIS 6, Apache. Other, atypical, configuration options are described in the Appendix, Alternative Configurations for Microsoft Windows.

  • If you are using an IIS web server, follow the directions in this chapter for your configuration. First follow the steps in the section “Microsoft IIS All Versions” Then follow the section that is applicable, either “Microsoft IIS 7 ” or “Microsoft IIS 6 ”.

  • If you are using an Apache web server, following the directions in this chapter to configure Apache using Native Modules, extensions implemented as dynamically-linked modules (DLLs) and a means through which ISAPI extensions, a high-performance API, the Internet Server Application Programming Interface (ISAPI), developed for Microsoft’s web servers, can be utilized.

Microsoft IIS All Versions

If you are using IIS as your web server, follow the steps in this section.

Summary of Configuration

Follow these steps to configure your web server for IIS, all versions.

  1. Set permissions for the Gateway components. For details, see the section “Setting Permissions for the Gateway Components”.

  2. Configure the CSP application path. For details, see the section “Configuring the CSP Application Path”.

  3. Enable URLs with /bin.

    For details, see the section “Enabling URLs with /bin”.

  4. Turn to the section for your webserver. If you are using IIS 7 or later, see the section “Microsoft IIS 7”. If you are using IIS 6, see the section “Microsoft IIS 6”. Or, if you have an atypical configuration, see the appendix Alternative Configurations for Microsoft Windows.

Setting Permissions for the Gateway Components

Regardless of which CSP Gateway configuration option you choose, you need to assign appropriate permissions to web resources held outside the standard IIS documents root (for example, C:\inetpub\wwwroot).

IIS 7 does not, by default, allow the user of a web application to access anything outside the scope of the pre-configured documents root unless you assign Read & Execute and Write permissions for those external resources to the following user or groups:

[machine_name]\IIS_IUSRS

And:

[machine_name]\Users

It should be noted that IIS_IUSRS represents the user (group) under which IIS worker processes operate. It essentially replaces the more familiar IUSR_[machine_name] user group found in earlier versions of IIS. Applications controlled through IIS (such as the CSP Gateway) operate with the level of privilege assigned to IIS_IUSRS.

For CSP, resources external the web server's root usually include the following:

Gateway binary components:

C:\inetpub\CSPGateway

Static file components:

\cache-install-dir\CSP\

Permissions can be manually assigned to these folders via Windows Explorer as follows:

  1. Right select the folder name and select Properties.

  2. Select the Security tab.

  3. Select Edit.

  4. Select Add.

  5. In the Enter the object names to text box enter:

    [machine_name]\IIS_IUSRS

  6. Select Check Names and OK.

  7. Select [machine_name]\IIS_IUSRS in the Group or Usernames window, then:

  8. Assign Read & Execute and Write permissions in the Permissions window.

  9. Select Apply and OK.

  10. Repeat the above process for the [machine_name]\Users user group.

As with previous versions of IIS, full read and write permissions for the Gateway configuration and event log files (CSP.ini and CSP.log) should be assigned to the IIS user group. For example, at the Windows command prompt, enter:

cacls CSP.ini /E /G IIS_IUSRS:F

cacls CSP.log /E /G IIS_IUSRS:F

Of course, this can also be done via Windows Explorer.

Configuring the CSP Application Path

This section describes the procedure for configuring the CSP application path (such as /csp) for IIS. These procedures are common to all CSP Gateway configuration options for IIS.

As with previous version, IIS is configured in the Internet Information Services (IIS) Manager control panel. Subdirectories configured under the documents root can either be classed as Virtual or Applications. Virtual subdirectories (or aliases) are mapped to physical equivalents (windows directories). The same applies to subdirectories classed as Applications except that, in addition to defining the physical equivalent, you can associate the application with a particular application pool (the default of which is DefaultAppPool).

Since CSP applications are served through the CSP Gateway, the hosting subdirectories (such as/csp) should be configured as Applications.

In a default CSP configuration, the /csp application path is mapped to the physical location install-dir\CSP. All the static files are located under this root (\csp\broker…).

  1. Open the Internet Information Services (IIS) Manager.

  2. In the left panel, expand the top level to reveal the Web Sites section, then the Default Web Site section. Highlight the Default Web Site section:

    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
    Copy code to clipboard
  3. In the right panel, select View Applications.

  4. Again in the right panel select Add Application.

  5. In the Add Application dialogue, enter:

    Alias: csp

    Physical path: install-dir\CSP\

  6. Select OK.

If you are using a CSP Gateway solution based on an atypical option, set up an application called /bin under the /csp application. Map this to the physical directory holding the Gateway binaries. For example:

Map application /csp/bin to C:\inetpub\CSPGateway

Enabling URLs with /bin

If you installed the CSP Gateway using the Cache installer, this step was done automatically for you. If you are installing the CSP Gateway manually, you need to do this step. (See this external web site for more details and alternative ways to accomplish this http://weblogs.asp.net/owscott/archive/2008/03/05/iis7-blocks-viewing-access-to-files-in-bin-and-other-asp-net-folders.aspx.) To enable URLs that contain /bin, add the following location tag to your applicationHost.config file:

<location path="sitename.com/subfolder/bin/debug">
    <system.webServer>
        <security>
           <requestFiltering>
              <hiddenSegments>
                 <remove segment="bin" />                    
               </hiddenSegments>
           </requestFiltering>
        </security>
     </system.webServer>
 </location>
Copy code to clipboard

Restarting IIS

This section describes what happens when IIS is restarted via the various control panels:

Most configuration changes can be made in real-time to an active IIS installation. However, the Internet Information Services (IIS) Manager control panel provides stop, start, and restart options. These are useful for the refreshing the web server configuration but does not result in an active Gateway installation being reinitialized (the Gateway DLLs are not reloaded).

As with previous versions of IIS, if you want to force IIS to restart, so that the Gateway modules are reloaded, then you have to restart the World Wide Web Publishing service via the main Windows Services control panel.

Troubleshooting

This section describes problems that commonly occur in configuring third-party modules (both Native and ISAPI) to work with IIS.

The most common problem likely to be encountered is that, after reconfiguring, requests to IIS fail with the following error:

Service Unavailable

HTTP Error 503. The service is unavailable.

This usually indicates that the default Application Pool has terminated.

  1. Open the Internet Information Services (IIS) Manager window.

  2. In the left panel expand the top level to reveal the Application Pools section.

    [MACHINE_NAME] ([machine_name]\[user_name])

    Appliation Pools

  3. Check that the Default Application Pool (DefaultAppPool), or whatever application pool your server is configured to use, is marked with a Status of Started.

  4. Restart the application pool if necessary (using the options in the right panel).

  5. If problems persist, look for clues in the main Windows Event Log: the Applications section. In particular, check for the following error message:

    Failed to find the RegisterModule entrypoint in the module DLL C:\inetpub\CSPGateway\CSPms.dll. The data is the error.

    This, for example, indicates that the version of Gateway DLLs that you are using do not implement the Native Modules interface. Either obtain later DLLs from InterSystems or configure the Gateway to work through the conventional ISAPI interface.

As with all software, restarting often clears transient problems: To completely restart IIS, restart the World Wide Web Publishing service via the main Windows Services control panel.

Do not use the Add Wildcard Script Map utility to map file extensions. If you do, you may see this error: The specified module required by the handler is not in the modules list. If you are adding a script map handler mapping, the IsapModule or the CgModule must in the modules list. Instead use Add Module Mapping for * to map file extensions using a wildcard.

If URLs with /bin in them are not working, see the section “Manual Step for Enabling URLs with /bin

Microsoft IIS 7 or Later

In this build, the Microsoft ISAPI extensions (CSPms.dll, CSPmsSys.dll and CSPcms.dll) have been adapted such that they can work directly to the Native Modules interface in IIS 7. This is the web server supplied with Windows Vista and Windows Server 2008.

The Gateway modules that we supply can work with the Native Modules in IIS 7. They can also be used with ISAPI extensions. There are additional configuration options for customers who are using the NSD. This section describes how to configure your IIS 7 web server to work with the Native Modules. The appendix Alternative Configurations for Microsoft Windows contains information on configuring IIS 7 for other configurations.

Install Locations for IIS 7

Install the CSP Gateway components and the CSP static files as follows:

  1. The default location for the Native Modules

    • CSPms.dll (Runtime module)

    • CSPmsSys.dll (Systems Management module)

    The default location for these modules is:

    C:\Inetpub\CSPGateway

    The configuration file (CSP.INI) and Event Log (CSP.LOG) are written in this directory for non NSD-based connectivity options.

  2. HyperEvents Components

    • CSPBroker.js

    • CSPxmlhttp.js

    The default location for these files is:

    C:\cache-install-dir\csp\broker

  3. Miscellaneous static resources used by the CSP Samples

    A number of static web resources (such as image files) are required by the CSP Samples. The default location for these files is:

    C:\cache-install-dir\csp\samples

  4. Miscellaneous static resources used by the Management Portal (Caché v5.1 and later)

    A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is:

    C:\cache-install-dir\csp\sys

Recommended Option: Using Native Modules (CSPms*.dll)

This is the recommended and most-used configuration option. It uses the new Native Modules interface supplied with IIS 7. This option provides the best performance.

For other configuration options using ISAPI or NSD, see the appendix Alternative Configuration Options for Microsoft Windows.

Register the Native Modules and configure the web server so that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the CSP Gateway for processing. Include any additional files that might be required for your installation (such as, for example, special CSP resources needed for DeepSee).

Registering the Native Modules

DLLs: CSPms.dll and CSPmsSys.dll

Before these modules can be used they must be registered with IIS. This is done in the Internet Information Services (IIS) Manager control panel.

  1. Open the Internet Information Services (IIS) Manager window.

  2. In the left panel, highlight: [MACHINE_NAME] ([machine_name]\[user_name])

  3. In the middle panel, double-click the Modules icon.

  4. In the right panel, select Add Native Module (or Configure Native Modules).The precise wording depends on the build of IIS in use.

  5. Select Register and enter the following in the Register Native Module dialogue:

    Name: CSPms

    Path: C:\inetpub\CSPGateway\CSPms.dll

    Select OK.

  6. In the left panel, expand the top level and expand Web Sites, and Default Web Site. Highlight Default Web Site:

    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
    Copy code to clipboard
  7. In the right panel, select Add Native Module.

  8. Select CSPms and select OK.

Mapping the CSP File Extensions

Note:

Do NOT use Add Wildcard Script Mapping utility for this file extension mapping process; it will give you an error! Instead, use the utility called Add Module Mapping for *.

Map the CSP file extensions to the CSP Gateway Native Modules as follows:

Extension Native Module Binary
*.csp CSPms C:\inetpub\CSPGateway\CSPms.dll
*.cls CSPms C:\inetpub\CSPGateway\CSPms.dll
*.zen CSPms C:\inetpub\CSPGateway\CSPms.dll
*.cxw CSPms C:\inetpub\CSPGateway\CSPms.dll
  1. Open the Internet Information Services (IIS) Manager window.

  2. In the left panel, expand the top level and expand Web Sites, then the Default Web Site section. Highlight Default Web Site:

    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
    Copy code to clipboard
    Note:

    This activates CSP for the whole web site. To restrict the use of CSP to specific virtual sub-directories (such as /csp/) focus control on the appropriate subdirectory (under Default Web Site) before creating the mappings. Repeat the process for each virtual subdirectory from which CSP content is to be served.

  3. In the middle panel, double-click the Handler Mappings icon.

  4. In the right panel, select Add Module Mapping.

  5. In the Add Module Mappings dialogue, enter the following details:

    Request Path: *.csp

    Module: (select CSPms from the dropdown)

    Name:CSPGateway_csp

  6. Select Request Restrictions and ensure that the box is not checked next to Invoke handler only if request is mapped to.

  7. Select OK to return to the Add Module Mappings dialogue and select OK again.

  8. Repeat the above process to add the following Module Mappings:

    Request Path: *.cls

    Module: (select CSPms from the list)

    Name:CSPGateway_cls

    Request Path: *.zen

    Module: (select CSPms from the list)

    Name:CSPGateway_zen

    Request Path: *.cxw

    Module: (select CSPms from the list)

    Name: CSPGatewayManagement

Registering Additional File Types with CSP

To configure additional file types to be processed by CSP, replicate the configuration created for the usual file extensions (that is,.csp,. .cls, .zen) for the new file extension(s).

If you need to serve other static files through the CSP Gateway or need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js.

To map requests for all files to CSP for a given path, set up the following wildcard entry for that path:

Extension Native Module Binary
* CSPms C:\inetpub\CSPGateway\CSPms.dll

Operating and Managing the Gateway

To access the CSP Gateway’s systems management suite, point your browser at the following location:

http://<ip_address>/csp/bin/Systems/Module.cxw

The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:

http://<ip_address>/csp/samples/menu.csp

If you see an unauthorized user error message, refer to the security notes in the section “CSP Gateway and Security”.

Configuring IIS to Return SOAP Fault Details

A Caché web service that encounters an error may return an HTTP 500 error without the associated SOAP fault details. By default, IIS returns extended error information only to local clients. However, you can modify this behavior in the <httpErrors> element within the configuration file web.config. To do so, add the following section to instruct IIS to dispatch detailed error information to all clients.

<configuration>
    <system.webServer>
       <httpErrors errorMode="Detailed" />
    </system.webServer>
</configuration>
Copy code to clipboard

Use caution with this approach as sensitive information about the hosting environment may be revealed to clients. An alternative approach that avoids the security concerns of using errorMode="Detailed” is to instead use the existingResponse="PassThrough" directive.

<configuration>
    <system.webServer>
       <httpErrors existingResponse="PassThrough" />
    </system.webServer>
</configuration>
Copy code to clipboard

Restart IIS after making changes to the configuration.

You can make these changes manually to the IIS web.config file. Or, for a better, less error prone, approach, use the Configuration Editor built into the IIS Manager.

  1. In the IIS Manager, from the Connections panel on the left, select the path which corresponds to the web service. For example: Default Web Site, then csp.

  2. In the middle panel, under the section heading Management at the bottom, double-click on Configuration Editor.

  3. In the Configuration Editor dropdown at the top labeled Section, expand system.webServer and click httpErrors.

  4. Click on the value next to existingResponse and use the dropdown to view the options. Select PassThrough.

  5. In the Actions pane on the right, click Apply.

  6. Restart IIS after making changes to the configuration.

Further information about error handling in IIS can be found at:

http://www.iis.net/configreference/system.webserver/httperrors

Microsoft IIS 6 or Earlier

IIS is supplied with the server-oriented Windows Operating Systems (such as Windows NT Server/2000/2003). Windows XP Professional, though predominantly a client-oriented Operating System, also includes the IIS server. A web server is not supplied with Windows XP Home edition.

This book assumes that the CSP Gateway components are installed in the following directory:

C:\Inetpub\CSPGateway

If your CSP Gateway web server components are installed in a different directory, amend the directions in the following sections, as appropriate.

Install Locations for IIS 6

Install the CSP Gateway components and the CSP static files as follows:

  1. The default location for the Native Modules:

    • CSPms.dll (Runtime module)

    • CSPmsSys.dll (Systems Management module)

    is:

    C:\Inetpub\CSPGateway

    The configuration file (CSP.INI) and Event Log (CSP.LOG) are written in this directory for non NSD-based connectivity options.

  2. HyperEvents Components

    • CSPBroker.js

    • CSPxmlhttp.js(Caché version 5.1 and later)

    The default location for these files is:

    C:\cache-install-dir\csp\broker

  3. Miscellaneous static resources used by the CSP Samples

    A number of static web resources (such as image files) are required by the CSP Samples. The default location for these files is:

    C:\cache-install-dir\csp\samples

  4. Miscellaneous static resources used by the Management Portal (Caché v5.1 and later)

    A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is:

    C:\cache-install-dir\csp\sys

Recommended Option: IIS and ISAPI Modules (CSPms.dll)

If you are using the ISAPI modules with the IIS web server, follow the directions in this section:

Configure the web server so that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the CSP Gateway for processing.

Internet Information Services with ISAPI

If you are running any version of IIS using the ISAPI modules, follow these directions:

  1. Open the Internet Services Manager, which in most versions of Windows is in Administrative Tools.

  2. Expand the Web Sites folder and navigate to Default Web Site.

  3. Right-click Default Web Site and select Properties.

  4. Select the Home Directory tab.

  5. Select Configuration.

  6. Select the Mappings tab.

  7. Select Add to display the Add/Edit Application Extension Mapping dialog box and add the following record:

    • Executable: \Inetpub\CSPGateway\CSPms.dll

    • Extension: csp

    • Verbs: Select All Verbs

    • Script engine check box: Select

    • Check that file exists check box: Clear

  8. Repeat the above process to add the following record:

    • Executable: \Inetpub\CSPGateway\CSPms.dll

    • Extension: cls

    • Verbs: Select All Verbs

    • Script engine check box: Select

    • Check that file exists check box: Clear

  9. Repeat the above process to add the following record:

    • Executable: \Inetpub\CSPGateway\CSPms.dll

    • Extension: zen

    • Verbs: Select All Verbs

    • Script engine check box: Select

    • Check that file exists check box: Clear

  10. Repeat the above process to add the following record:

    • Executable: \Inetpub\CSPGateway\CSPms.dll

    • Extension: cxw

    • Verbs: Select All Verbs

    • Script engine check box: Select

    • Check that file exists check box: Clear

  11. Return to Internet Information Services and navigate to Default Web Site again.

  12. Right-click Default Web Site, point to New and then select Virtual Directory. Create a virtual directory using the following information:

    • Alias: csp

    • Directory: install-dir\csp

    • Access Permissions: Select the Execute check box

  13. Select Save and restart IIS to apply your changes.

Internet Information Services v6 with ISAPI

If you are running IIS 6, follow the directions in the previous section and also the directions in this section:

This version of IIS is shipped with Windows Server 2003. To configure CSP to work with this server, register the CSP Gateway ISAPI DLLs (CSPms.dll and CSPmsSys.dll) as allowed Web service extensions.

Important:

It is a common mistake to register the Gateway’s modules, which are ISAPI extensions, as ISAPI filters. If you register the modules as ISAPI filters, CSP does not work.

  1. Open the Internet Services Manager.

  2. Navigate to Web Service Extensions. This displays a list of currently configured extensions (or applications) in the right-hand panel.

  3. Right-click Web Services Extensions and select Add a new Web service extension.

  4. Enter CSP Gateway for the Extension name field.

  5. Select Add.

  6. Add CSPms.dll (including the full physical path to this DLL). Repeat the process for CSPmsSys.dll (Gateway builds 999 and earlier).

  7. Select the Set extension status to Allowed check box.

  8. Select OK.

Note that there is an option to allow users access to all ISAPI extensions: Allow All unknown ISAPI extensions. Enabling this option automatically enables access to the CSP Gateway’s ISAPI modules. However, to maintain security it recommended that you follow the procedure above and grant additional access only to the CSP Gateway modules.

Later, you can perform the following additional operations on registered Web Service Extensions. IIS 6 lets you turn off aspects of access to CSP.

To Prohibit Access to CSP Web Gateway Management Page

Use this procedure to disable access to the CSP Web Gateway Management page available from the Management Portal. Doing this prevents the possibility of unauthorized users gaining access the CSP Web Gateway Management page for an operational system. It is a quick and straightforward procedure for system administrators to re-enable access for a future period of time in order for configuration changes to be made to the Gateway.

  1. Open the Internet Services Manager .

  2. Navigate to Web Service Extensions to display a list of currently configured extensions (or applications) in the right-hand panel.

  3. In the right-hand window, double-click CSP Gateway to display the Web Service Extension Properties window.

  4. Select the Required Files tab.

  5. Select CSPmsSys.dll to select this file.

  6. Select Prohibit; select Apply; select OK.

You can also use this procedure to prevent end-users from gaining access to CSP resources while significant changes are being made to the Gateway configuration. In this case, the Gateway runtime module (CSPms.dll) should be marked as Prohibited instead of the Systems Management module (CSPmsSys.dll).

To reactivate the CSP Gateway Systems Management module, at the last step, select Allow instead of Prohibit.

Security Settings with ISAPI

For many Windows installations (particularly Windows 2000 and later), the default privileges assigned to the IIS web server are not sufficient to allow the CSP Gateway to read from and/or write to its configuration and log files (CSP.ini and CSP.log respectively).

You must, therefore, assign the web server read/write privileges to the CSP Gateway files, or grant the web server Administrator privileges. If you fail to do this, you may not be able to save your configuration changes through the CSP Web Gateway Management page.

File-access privileges can be modified through Windows Explorer. Alternatively, you can use the following two commands at the command prompt. Note that the CSP.ini and CSP.log files are in the same directory as the Gateway binaries that the web server is configured to use. With ISAPI, this is typically Inetpub.

cacls c:\Inetpub\CSPGateway\CSP.ini /E /G IUSR_xxx:F
cacls c:\Inetpub\CSPGateway\CSP.log /E /G IUSR_xxx:F
Copy code to clipboard

Where IUSR_xxx is the web server’s user authority and the xxx component is usually the computer name (see the numbered procedure below to find the correct name).

The files that you are running the cacls command on must already exist. If they do not, use the copy con command (in a Windows Command Prompt window or DOS box) to create empty files:

Copy con c:\Inetpub\CSPGateway\CSP.ini
^Z
Copy con c:\Inetpub\CSPGateway\CSP.log
^Z
Copy code to clipboard

Each individual command line is terminated with carriage return. ^Z refers to Ctrl-Z, which ends the copy command.

Example: Use the following commands to adjust the CSP Gateway configuration and log file access rights for a computer named BOSTON:

cacls c:\Inetpub\CSPGateway\CSP.ini /E /G IUSR_BOSTON:F
cacls c:\Inetpub\CSPGateway\CSP.log /E /G IUSR_BOSTON:F
Copy code to clipboard

You can find the specific name to use in the Internet Service Manager by navigating to the Authentication methods dialog as follows:

  1. Open the Internet Services Manager.

  2. Navigate to Default Web Site.

  3. Right-click Default Web Site and select Properties

  4. Select the Directory Security tab.

  5. Select Edit under the Anonymous access and authentication control panel. This displays the Username in the Authentication methods dialog box.

Registering Additional File Types with CSP

To configure additional file types to be processed by CSP, replicate the configuration created for the usual file extensions (that is,.csp, .cls, .zen) for the new file extension(s).

If you need to serve other static files through the CSP Gateway or need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js.

To map requests for all files to CSP for a given path, set up the following wildcard entry for that path:

Executable: c:\cache-install-dir\csp\bin\CSPms.dll
Extension: .* (dot asterisk)
All Verbs: Check
Script engine: Check
Check that file exists: UnCheck

If the above does not work for your operating system, do the following:

  1. Open the Internet Services Manager.

  2. Navigate to Default Web Site, right-click and select Properties.

  3. Select the Home Directory tab and select Configuration.

  4. Under Mappings tab, insert an asterisk.

  5. For Executable, select CSPms.dll and uncheck the Verify that file exists.

Operating and Managing the Gateway with ISAPI

To access the CSP Web Gateway Management page, enter one of the following URLs in your browser:

http://localhost:<port_no>/csp/bin/Systems/Module.cxw
http://localhost:<port_no>/csp/bin/CSPmsSys.dll.
Copy code to clipboard

If you see an Unauthorized User error message, refer to the section on “security considerations”.

The CSP engine is automatically invoked for requested files with names that end in .csp or .cls. For example:

http://localhost:<port_no>/csp/samples/menu.csp
Copy code to clipboard

Apache Servers

Apache is supplied by the Apache Group and can be downloaded free of charge from:http://www.apache.org.

The complete source code to Apache is available from Apache for download together with clear instructions for building the server. To build Apache under Windows, you must have the Microsoft C compiler (Visual C++) version 5.0 (or later). Instead of building the server yourself, you can instead download prebuilt kits for Windows. The prebuilt kits are, generally, a few builds behind the latest Apache source code.

This guide assumes that the CSP Gateway components are installed in the following directory:

C:\Program Files\Apache Group\Apache\CSPGateway

It is assumed that the web server is installed under:

C:\Program Files\Apache Group\Apache\

If the layout is different on your system, amend the configuration directives in the following sections, as appropriate.

First follow the directions in the section “Install Locations with Apache Servers (All Options)”, then follow the directions in the section “Recommended Option: Apache API Modules (CSPa.dll) ”section that follows or, if you are installing an atypical configuration, see the appendix Alternative Configurations for Microsoft Windows.

Install Locations with Apache Servers (All Options)

All users of the Apache server should follow the directions in this section.

Install the CSP Gateway components and the CSP static files as follows:

  1. CGI and other dynamically-linked modules:

    The common files for all Apache versions are:

    • CSPcgi.exe (Runtime module)

    • nph-CSPcgi.exe (Copy of CSPcgi)

    • CSPcgiSys.exe (Systems-Management module)

    • nph-CSPcgiSys.exe (Copy of CSPcgiSys)

    Note:

    There are separate binaries for each version of the Apache server as shown below.

    Apache Version 2.4.x

    • mod_csp24.dll (Apache built-in momod_dule as a DLL, if supplied)

    • CSPa24.dll (Runtime module, if supplied)

    • CSPa24Sys.dll (Gateway Systems Management module, if supplied)

    Apache Version 2.2.x

    • mod_csp22.dll (Apache built-in momod_dule as a DLL, if supplied)

    • CSPa22.dll (Runtime module, if supplied)

    • CSPa22Sys.dll (Gateway Systems Management module, if supplied)

    Apache Version 2.0.x:

    • mod_csp2.dll (Apache built-in module as a DLL, if supplied)

    • CSPa2.dll (Runtime module, if supplied)

    • CSPa2Sys.dll (Gateway Systems Management module, if supplied)

    The default location for these binaries is:

    C:\Program Files\Apache Group\Apache\CSPGateway\bin

    The original location (install-dir\csp\bin) is used to hold the Gateway components required for serving the Management Portal for the specific instance of Caché.

    The configuration file (CSP.INI) and Event Log (CSP.LOG) are written in this directory for non NSD-based connectivity options.

    The modules with Sys appended are special modules for accessing the CSP Web Gateway Management page. The runtime modules (that is, those without Sys) have no access to the systems management forms.

  2. HyperEvents Components

    • CSPBroker.js

    • CSPxmlhttp.js

    The default location for these files is:

    C:\cache-install-dir\csp\broker

  3. Miscellaneous static resources used by the CSP Samples

    A number of static web resources (such as image files) are required by the CSP Samples. The default location for these files is:

    C:\cache-install-dir\csp\samples

  4. Miscellaneous static resources used by the Management Portal

    A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is:

    C:\cache-install-dir\csp\sys

Recommended Option: Apache API Modules (CSPa24.dll)

This is the option that is used by the Private Web Server that serves the Management Portal.

This connectivity option is relatively new and offers the best performance as well as being the easiest to configure. Apache under Windows is entirely multithreaded and its modules persist in memory from the time Apache is started. These two essential characteristics make it possible to implement the Gateway’s functionality as a set of stand-alone modules.

If you are installing an atypical configuration, see the appendix Alternative Configurations for Microsoft Windows

The modules CSPap24.dll (Runtime) and CSPapSys24.dll (Gateway systems management) are dynamically-linked modules that are designed to work the same way as the corresponding Microsoft ISAPI DLLs. These modules are named according to their Apache version:

  • Apache 2.4.x: Use modules CSPa24.dll and CSPa24Sys.dll.

  • Apache 2.2.x: Use modules CSPa22.dll and CSPa22Sys.dll.

  • Apache 2.0.x: Use modules CSPa2.dll (Runtime) and CSPa2Sys.dll

Configure the web server so that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the CSP Gateway module for processing.

The web server configuration file (httpd.conf) is in the following directory:

C:\Program Files\Apache Group\Apache\conf

  1. Apache 2.4.x: Add the section below to the end of httpd.conf.

    LoadModule csp_module_sa c:/cache-install-dir/csp/bin/CSPa24.dll 
    <Location "/csp/bin/Systems/"> 
    SetHandler csp-handler-sa 
    </Location> 
    <Location "/csp/bin/RunTime/"> 
    SetHandler csp-handler-sa 
    </Location> 
    CSPFileTypes csp cls zen cxw 
    Alias /csp/ c:/cache-install-dir/csp/ 
    <Directory "c:/cache-install-dir/csp"> 
        AllowOverride None 
        Options MultiViews FollowSymLinks ExecCGI 
        Require all granted
        <FilesMatch "\.(log|ini|pid|exe)$"> 
        Require all denied 
        </FilesMatch>
    </Directory> 
    Copy code to clipboard

    Apache 2.2.x: Add the section below to the end of httpd.conf

    LoadModule csp_module_sa c:/cache-install-dir/csp/bin/CSPa22.dll 
    <Location "/csp/bin/Systems/"> 
    SetHandler csp-handler-sa 
    </Location> 
    <Location "/csp/bin/RunTime/"> 
    SetHandler csp-handler-sa 
    </Location> 
    CSPFileTypes csp cls zen cxw 
    Alias /csp/ c:/cache-install-dir/csp/ 
    <Directory "c:/cache-install-dir/csp"> 
        AllowOverride None 
        Options MultiViews FollowSymLinks ExecCGI 
        Order allow,deny
                  Allow from all
        <FilesMatch "\.(log|ini|pid|exe)$"> 
        Deny from all
        </FilesMatch>
    </Directory> 
    Copy code to clipboard

    Apache 2.0.x: Add the section above using CSPa2.dll to the end of httpd.conf

  2. Restart Apache after making changes to httpd.conf.

Registering Additional File Types with CSP

Apache API modules always recognize the following reserved file extensions:

.csp .cls .zen .cxw 
Copy code to clipboard

You may have other files that you want to send to CSP for processing. For example, if you need to serve other static files through the CSP Gateway or need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js.

You can configure Apache to recognize what files to pass on to CSP in any of the following ways:

  • By CSP location directive

  • By file extension—CSPFileTypes directive

  • By MIME type

By CSPlocation directive

Use the CSP directive to request that all files within a certain location be processed by CSP. The following requests that all files and directories under the /csp path be processed by CSP.

<Location /csp>
   CSP On 
   SetHandler csp-handler-sa
</Location> 
Copy code to clipboard

For example, all the following would be sent to CSP for processing:

/csp/ 
csp/samples/menu.csp 
csp/sys/ 
Copy code to clipboard
By file extension — CSPFileTypes directive

The CSPFileTypes directive works for requests for files that have extensions (such /csp/menu.csp). It does not work for requests for files that do not have file extensions (such as/csp/menu).

This parameter is processed by the Gateway’s Apache modules and can be globally defined at the server definition level (in httpd.conf) or restricted within the definition for a location or directory block.

By file type: The following directive requests that files of type xxx and yyy be processed by CSP.

CSPFileTypes xxx yyy 
Copy code to clipboard

By location: The following requests that files of type xxx and yyy be processed by CSP but only for locations under /csp (including subdirectories, such as /csp/samples and so on).

<Location /csp/> 
   CSPFileTypes xxx yyy
</Location>
Copy code to clipboard

Using the wildcard character, the following requests that all files under path /csp (and /csp/samples and so on) be processed by CSP.

<Location /csp/> 
   CSPFileTypes * 
</Location> 
Copy code to clipboard
By MIME type

In addition to recognizing the file extensions listed above, CSP can also recognize files for the following MIME types:

application/x-csp
Copy code to clipboard

and

text/csp
Copy code to clipboard

For example, to add the file extension xxx to the list of files processed by CSP, use:

LoadModule csp_module_sa /cache-install-dir/csp/bin/CSPa24.dll
AddType application/x-csp csp cls zen xxx
Copy code to clipboard

One of the problems with using MIME types to associate types of file with CSP is that Apache checks to ensure that the path to the resource (that is, the hosting directory) physically exists, and returns a file not found error if it does not. It does not, however, check to ensure that the file requested physically exists – which is appropriate for resources served by CSP since they are served by Caché and are virtual as far as the web server is concerned. The “By MIME type” approach is therefore only suitable for cases where the application’s path structure can be replicated on the web server.

Operating and Managing the Gateway with Apache API

To access the CSP Gateway’s CSP Web Gateway Management page, point your browser at:

http://localhost:<port_no>/csp/bin/Systems/Module.cxw
Copy code to clipboard

Notice the use of the cxw file extension. This extension prevents Apache attempting to load and run these DLLs through the Apache Group ISAPI interface. Also, remember that URL paths and files names are case-sensitive under Apache.

If you see an Unauthorized User error message, refer to the section on “security considerations”.

The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:

http://localhost:<port_no>/csp/samples/menu.csp
Copy code to clipboard

Nginx Servers

Nginx is an Open Source product. The source code can be downloaded free of charge from:

http://nginx.org/

Some prebuilt kits are available for Windows which are, generally, a few builds behind the latest Nginx build. However, given that extensions must be compiled into the Nginx core, it is necessary to build the web server locally from the source code in order to include support for CSP.

This guide is based on CSP/Gateway web server components being installed under the following file system:

C:\cachesys\csp\

It is assumed that the web server is installed under:

C:\nginx\

If the layout is different on your system, be sure to amend the configuration directives described in the following sections, as appropriate.

Installation

The CSP Gateway components and the CSP static files should be installed as follows:

  1. Dynamically linked Universal CSP Gateway Modules

    • CSPx.dll (Run-time module)

    • CSPxSys.dll (Gateway Systems Management module)

    The default location for these binaries is:

    C:\cachesys\csp\bin

    The configuration file (CSP.INI) and Event Log (CSP.LOG) are written in this directory.

    The modules with Sys appended are special modules for accessing the CSP systems management suite. The run-time modules (that is, those without Sys) have no access to the systems management forms.

  2. HyperEvents Components

    • CSPBroker.js

    • CSPxmlhttp.js

    The default location for these files is:

    C:\cachesys\csp\broker

    If these files are to be served as static components directly by the web server they should be copied to the following location:

    C:\nginx\html\csp\broker

  3. Miscellaneous static resources used by the CSP Samples

    A number of static web resources (such as image files) are required by the CSP Samples. The default location for these files is:

    C:\cachesys\csp\samples

    Copy these to the following location if they are to be served directly by the web server:

    C:\nginx\html\csp\samples

  4. Miscellaneous static resources used by the Caché SMP

    A number of static web resources (such as image files) are required by the SMP. The default location for these files is:

    C:\cachesys\csp\sys

    Copy these to the following location if they are to be served directly by the web server:

    C:\nginx\html\csp\sys

    See the section Static Files in Using CSP for more information.

Building the Nginx web server for CSP

Most of the CSP Gateway functionality is provided by the Universal Modules (CSPx[Sys].dll). For CSP access, Nginx can be built and configured to communicate with these Universal Modules through a small compiled-in module:

ngx_http_csp_module_sa.c

Prerequisites for building Nginx:

The build instructions given here are based on the official documentation for building Nginx under Windows:

http://nginx.org/en/docs/howto_build_on_win32.html

The Nginx documentation stipulates that the following third party add-ons are also required:

However, it is possible to create a fully functional server without these components, provided the final installation doesn’t require the functionality that would otherwise be provided by them.

The default configuration script for building Nginx, including all optional modules listed above, is as follows:

auto/configure --with-cc=cl --builddir=objs --prefix= \
--conf-path=conf/nginx.conf --pid-path=logs/nginx.pid \
--http-log-path=logs/access.log --error-log-path=logs/error.log \
--sbin-path=nginx.exe \
--http-client-body-temp-path=temp/client_body_temp \
--http-proxy-temp-path=temp/proxy_temp \
--http-fastcgi-temp-path=temp/fastcgi_temp \
--with-cc-opt=-DFD_SETSIZE=1024 --with-pcre=objs/lib/pcre-8.32 \
--with-zlib=objs/lib/zlib-1.2.7 \
--with-openssl=objs/lib/openssl-1.0.1e \
--with-select_module --with-http_ssl_module --with-ipv6
Copy code to clipboard

The build process can be modified to exclude optional modules:

  • OpenSSL - Remove SSL/TLS capability:

    Remove directive: --with-http_ssl_module

  • Zlib - Remove GZIP capability:

    Add directive: --without-http_gzip_module

  • PCRE - Remove HTTP rewrite capability:

    Add directive: --without-http_rewrite_module

Procedure for building Nginx for CSP

  1. Working in a MSYS shell, create the working directory structure suggested in the Nginx documentation:

    /opt/

  2. Working in /opt, check-out the Nginx source code using the following command:

    hg clone http://hg.nginx.org/nginx
    Copy code to clipboard

    This places the Nginx source code under: /opt/nginx/

  3. Create a directory for the CSP extension:

    /opt/nginx/objs/lib/csp/

  4. Copy the module source code (ngx_http_csp_module_sa.c and cspapi.h) to the directory created in the previous step.

  5. In the same directory, create a configuration file called config. This file should contain the following lines:

    ngx_addon_name=ngx_http_csp_module_sa
    HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module_sa"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module_sa.c"
    Copy code to clipboard
  6. Working in /opt/nginx/, configure the Nginx build environment:

    auto/configure --with-cc=cl --builddir=objs --prefix= \
    --conf-path=conf/nginx.conf --pid-path=logs/nginx.pid \
    --http-log-path=logs/access.log --error-log-path=logs/error.log \
    --sbin-path=nginx.exe \
    --http-client-body-temp-path=temp/client_body_temp \
    --http-proxy-temp-path=temp/proxy_temp \
    --http-fastcgi-temp-path=temp/fastcgi_temp \
    --with-cc-opt=-DFD_SETSIZE=1024 --without-http_rewrite_module \
    --without-http_gzip_module \
    --with-select_module --with-ipv6 \
    --add-module=objs/lib/csp
    Copy code to clipboard

    Note the final line containing the instructions to include the CSP module.

  7. Compile Nginx:

    nmake -f objs/Makefile
    Copy code to clipboard

    If successful, you should find the server (nginx.exe) in: /opt/nginx/objs/

  8. Install Nginx:

    The easiest way to do this is to first download and install a pre-built version of Nginx for Windows to obtain the directory structure (usually under C:\nginx\) then replace the nginx.exe file in that installation with the one created locally.

    The typical directory structure for an operational Nginx installation is as follows:

    Directory of C:\nginx
    
    03/07/2013  09:09    <DIR>          .
    03/07/2013  09:09    <DIR>          ..
    26/06/2013  10:14    <DIR>          conf
    26/06/2013  10:14    <DIR>          contrib
    10/05/2014  12:53    <DIR>          csp
    26/06/2013  10:14    <DIR>          docs
    26/06/2013  10:14    <DIR>          html
    10/05/2014  15:57    <DIR>          logs
    04/07/2013  15:52           715,264 nginx.exe
    26/06/2013  10:17    <DIR>          scgi_temp
    26/06/2013  10:17    <DIR>          temp
    26/06/2013  10:17    <DIR>          uwsgi_temp
    Copy code to clipboard

    Replace the copy of nginx.exe in this directory with the version created by the build procedure.

Using the Universal CSP Gateway Modules (CSPx*.dll)

The Universal Modules CSPx.dll (Run-time) and CSPxSys.dll (Gateway systems management) are dynamically linked modules that are designed to be loaded by a CSP-enabled Nginx installation.

The web server should be configured such that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the CSP Gateway module for processing

The web server configuration file (nginx.conf) is found in the following directory:

C:\nginx\conf

The following configuration directives are provided for the CSP extension:

  • CSPModulePath

    http section: Path to the Universal Gateway Modules

  • CSP

    server section: Enable CSP for an entire path

  • CSPFileTypes

    server section: Enable CSP for specific file types

For Windows, the thread stack size must be increased to 2MB. To do this, add the following directive to the top of the Nginx configuration file (before the http section):

thread_stack_size 2000000;
Copy code to clipboard

Place the following directive within the http configuration block:

CSPModulePath C:/cachesys/csp/bin/;
Copy code to clipboard

This directive enables Nginx to find the Universal Gateway Modules (CSPx[Sys].dll) and the associated configuration (CSP.ini).

Nginx can now be configured to pass all requests for a certain path to CSP or just certain file types.

Enabling CSP for a Particular Path

Place the following section within the appropriate server configuration block:

location /csp {
CSP On;
}
Copy code to clipboard

Registering Specific File Types with CSP

Place the following section within the appropriate server configuration block:

location /csp {
CSPFileTypes  csp cls zen cxw;
}
Copy code to clipboard

Starting and Stopping Nginx

First, ensure that Nginx has read/write permissions to the location holding the Universal Gateway Modules (C:/cachesys/csp/bin/). This is the location where the Gateway configuration and Event Log files will be maintained (CSP.ini and CSP.log).

To start Nginx:

C:\nginx\nginx
Copy code to clipboard

To stop Nginx:

C:\nginx\nginx –s stop
Copy code to clipboard

Operating and Managing the Gateway

To access the CSP Gateway’s systems management suite, point your browser:

http://<ip_address>/csp/bin/Systems/Module.cxw
Copy code to clipboard

Notice the use of the cxw file extension.

The CSP engine is automatically invoked for requested files containing the .csp, .cls, or .zen extensions. For example:

http://<ip_address>/csp/samples/menu.csp
Copy code to clipboard

If you see an Unauthorized User error message, refer to the section on security considerations in this book.

Building Nginx to Work with the CSP NSD Component

Nginx can be built to work with the CSP Gateway’s Network Service Daemon component (CSPnsd[Sv].exe), as opposed to the Universal Modules (CSPx[Sys].dll). To do this, modify the build and configuration procedure as follows:

  • Build Nginx with source code module ngx_http_csp_module.c instead of ngx_http_csp_module_sa.c

  • The configuration file for CSP (/opt/nginx/objs/lib/csp/config) should read as follows:

    ngx_addon_name=ngx_http_csp_module
    HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module.c"
    Copy code to clipboard
  • Remove the CSPModulePath directive from the Nginx configuration.

  • Start the NSD component.

The usual reason for preferring to use the NSD component is to obtain full and reliable support for CSP state-aware mode (Preserve mode). However, in order to get the best results with Nginx, it is recommended that applications should be entirely state-less.