Skip to main content

Alternative Configurations for Microsoft Windows

Important:

InterSystems recommends using the Web Gateway, which is an updated and more feature-rich version of the CSP Gateway. The Web Gateway is compatible with Caché and Ensemble starting with version 2017.1. For more information, read the Web Gateway GuideOpens in a new tab in the latest InterSystems IRIS® documentation.

This section describes how to set up atypical configurations for Microsoft Windows. Everyone should read the first sections to see if they apply to your configuration. Then select one of the configuration options.

These atypical configurations may require some of the following modules. Refer to the sections describing each option to see which are actually required.

  • CSPcms.dll (ISAPI/Native module client to the NSD – if supplied)

  • CSPcgi.exe (Runtime module)

  • nph-CSPcgi.exe (Copy of CSPcgi)

  • CSPcgiSys.exe (Systems Management module)

  • nph-CSPcgiSys.exe (Copy of CSPcgiSys)

  • CSPmsf1.dll (ISAPI filter – if supplied)

These modules are placed in the following common location:

C:\Inetpub\CSPGateway

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

Using the Network Service Daemon (NSD)

When to Use the NSD

Several of the options described in this book use the NSD. There are two situations in which you might choose to use the NSD to separate the CSP Gateway from the web server so that you can manage the CSP Gateway independently of the Web Server. These are:

  • If your web server distributes its load over multiple server processes, an instance of the CSP Gateway is then attached to each web server process.

  • If you have a very large web server installation for which CSP is only a small part; for example, a web server that serves php, static content, .NET, and .ASP applications, as well as CSP applications.

NSD Module Install Locations

If the you use the NSD Module in Microsoft Windows, you install the following two utilities:

  • CSPnsd.exe

  • CSPnsdSv.exe

On an IIS installation, these are installed in this location:

C:\Inetpub\CSPGateway\nsd

On an Apache installation, these are installed in this location:

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

Run the NSD from within its home directory, C:\Inetpub\CSPGateway\nsd. The configuration file (CSP.INI) and Event Log (CSP.LOG) are written in this directory for NSD-based connectivity options.

Operating the NSD

Use the following procedure to start the NSD.

  1. Change to the NSD home directory, such as:

    C:\Inetpub\CSPGateway\nsd

  2. Start the NSD with:

    CSPnsd
    

    The NSD starts as a Windows service (CSPnsd.Sv.exe). Once registered as a service, you can manage the NSD entirely through the Windows Service Manager.

  3. Close down the NSD, by issuing the following command:

    CSPnsd -stop
    

Alternatively, you can enter:

CSPnsd

This shows the status of the NSD’s Windows Service and allows you to perform one of the following actions:

  • Stop the NSD service if it is running.

  • Continue the NSD service if it is paused.

  • Remove the NSD service from the services database.

Alternatively, you can use the Windows Service Manager to manage the NSD. The NSD can be identified in the Service Manager by the description:

Cache Server Pages – Network Service Daemon

All errors are reported in the CSP event log (that is, CSP.log). This file is created and maintained in the install-dir\csp directory. The CSP configuration file CSP.ini also resides in this directory.

Other Startup Options

  1. Display help information.

    CSPnsd -h

  2. Run the NSD interactively in a command window as opposed to as a Windows service. This mode of operation must be used if multiple instances of the NSD are to be run.

    CSPnsd -v

  3. Give permission to others to run the NSD. Administrators of the NSD (CSPnsd) component can give permission to a group or others to start/stop the NSD using CSPnsd —m=s where s is a startup option.

    s can be one of

    • u for the current user (default)

    • g for the current group

    • o for others

    • a for everyone (m=ugo)

    Example: CPSnsd -m=ug gives permissions to the group (the Administrator group) to run the NSD. This command gives the CPSnsd.pid permissions of: -rw-rw–--

    When the command to stop the CSPnsd is issued, it tries to signal the CSPnsd parent process to shut down as before. If this is not possible because the service was started by a different user, a flag is written to the CSPnsd.ini file and the service gracefully closes itself down when it acknowledges this flag. This process takes up to 20 seconds to complete.

Starting NSD on Alternative TCP Port

By default, the NSD listens for incoming requests on TCP port 7038. You can override this by starting the service as follows:

CSPnsd –v [port_no]

Or:

CSPnsd –v -p[port_no]

- where port_no is the TCP port number of your choice.

On startup, the NSD creates the following file:

CSPnsd.ini

Typically, this file contains the following lines:

[SYSTEM]
Ip_Address=127.0.0.1
TCP_Port=7038

In this context, the clients are the CSP modules contained within, or dynamically linked to, the web server and/or the CSP CGI modules invoked by the server. It is, therefore, essential that this file is not deleted or moved. It is also important that the web server processes can read this file. Set the privileges accordingly, bearing in mind the Windows user under which your web server is operating. The NSD clients attempt to find this file in a location contained within the Windows PATH variable. For example:

\Windows

The CSPnsd.ini file must be moved to this location before starting the web server

Clearly, storing the NSD port number in the CSPnsd.ini file is inappropriate for situations in which multiple instances of the NSD are running. For Apache servers, there is a much better mechanism for communicating the TCP port number of the NSD to its clients.

Set the following environment variables in the Apache configuration to indicate the address and port of the target NSD installation. The values specified in these environment variables take precedence over any values found in the CSPnsd.ini file.

CSP_NSD_NAME — This is the IP address of the NSD. Only use this parameter if the NSD is operating on a remote computer.

CSP_NSD_PORT — This is the TCP port of the NSD.

Example 1:

Distribute the load for two Apache virtual hosts (say, 123.123.1.1 and 123.123.1.2) between two independent NSD installations (listening on TCP port 7038 and 7039).

Add the following directives to the Apache configuration (httpd.conf):

<VirtualHost 123.123.1.1>
ServerName 123.123.1.1
SetEnv CSP_NSD_PORT 7038
</VirtualHost>
<VirtualHost 123.123.1.2>
ServerName 123.123.1.2
SetEnv CSP_NSD_PORT 7039
</VirtualHost>
Example 2:

Distribute the load for two CSP applications (say, /csp1 and /csp2) between two independent NSD installations (listening on TCP port 7038 and 7039).

  1. Add the following directives to the Apache configuration (httpd.conf):

    <Location /csp1>
    SetEnv CSP_NSD_PORT 7038
    </Location>
    <Location /csp2>
    SetEnv CSP_NSD_PORT 7039
    </Location>
    
  2. Restart Apache after making changes to its configuration.

In cases where multiple instances of the NSD are running, it is recommended that the separate instances be installed in separate directories, each maintaining its own copy of the configuration and log files (CSP.ini and CSP.log). The CSP Web Gateway Management page for each instance can easily be accessed by using the NSD internal HTTP server. For example:

http://localhost:7038/csp/bin/Systems/Module.cxw

http://localhost:7039/csp/bin/Systems/Module.cxw

Alternative Options for IIS7 or Later

This appendix contains instructions for configuring atypical options for IIS7. To configure one of these options:

  1. Follow the steps in the section Summary of Configuration Steps

  2. Install ISAPI and GCI services, as described in the section Installing the ISAPI and CGI Services

  3. Select one of the following 4 options and follow the directions in that section:

    1. Alternative Option 1: Using the ISAPI Modules (CSPms*.dll)

    2. Alternative Option 2: Using a Native Module with the NSD (CSPcms.dll)

    3. Alternative Option 3: Using an ISAPI Module with the NSD (CSPcms.dll)

    4. Alternative Option 4: Using the CGI Modules with the NSD (nph-CSPcgi*.exe)

Installing the ISAPI and CGI Services

IIS 7 does not, by default, run ISAPI extension, ISAPI filters, or CGI modules. For all the atypical options for IIS7, you must install these services.

Note that, with the ISAPI extensions service installed, all versions of the CSP Gateway that have ever been built (even those shipped with Caché v4) work with IIS 7.

Install these legacy services through the Windows Control Panel.

  1. Open the Windows Control Panel.

  2. Select Programs and Features and select Turn Windows Features on or off.

  3. Navigate to Internet Information Services and expand World Wide Web Services and Application Development Features.

    Select ISAPI Extensions. Also select ISAPI Filters and CGI, if these additional services are required. Select OK

  4. In the Windows Control Panel, open Administrative Tools and Internet Information Services (IIS) Manager.

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

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

  7. In the right panel, select Add Native Module.

  8. In the left panel, expand the top level, expand Web Sites and expand Default Web Site

    [MACHINE_NAME] ([machine_name]\[user_name])
                  Web Sites
                         Default Web Site
    
  9. In the middle panel, double-click Handler Mappings.

  10. In the middle panel, highlight the ISAPI-dll handler.

  11. In the right panel, select Edit Handler Permissions.

  12. Select Execute and select OK. This allows ISAPI extensions to be invoked through direct calls to the name of the ISAPI DLL.

Alternative Option 1: Using the ISAPI Modules (CSPms*.dll)

Use this option if your CSP Gateway DLLs are unable to support the Native Module interface (the Recommended Option). This is the default (and best performing) solution that was supplied for earlier versions of IIS.

IIS 7 does not, by default, run ISAPI extensions, ISAPI filters or CGI modules. This option requires the ISAPI extensions service.

Follow the instructions in the section Installing the ISAPI and CGI Services (If Required) for installing and configuring the ISAPI extensions service.

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 for processing.

Enabling the ISAPI Extensions

DLLs: CSPms.dll and CSPmsSys.dll

Before these extensions can be used they must be registered with IIS as being “Allowed” applications. 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 ISAPI and CGI Restrictions.

  4. In the right panel, select Add.

  5. In the Add ISAPI or CGI Restriction dialogue, enter the following details:

    ISAPI or CGI Path: C:\inetpub\CSPGateway\CSPms.dll

    Description: CSPGatewayRunTime

    Allow extension path to execute: Select

    Select OK

Mapping the CSP File Extensions

Choose one of the following configuration methods:

  1. Serve all content (including static content) from Cache. Map * to the CSP Gateway. Follow the file map procedure in the section “Registering Additional File Types with CSP” in this book.

  2. Serve static content from the web server. Map only files of type .csp, .cls, .zen, .cxw to the CSP Gateway.

If you are serving static files from the web server, map the CSP file extensions to the CSP Gateway ISAPI extensions as follows:

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

  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
    
    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 Script Map.

  5. In the Add Script Map dialogue, enter:

    Request Path: *.csp

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

    Name: CSPGateway_csp

  6. Select Request Restrictions.

    Clear: Invoke handler only if request is mapped to

    Select OK to return to Add Script Map dialogue.

    Select OK.

  7. At this point you may be prompted as follows:

    “Would you like to enable this ISAPI extension? If yes, we add your extension as an “Allowed” entry in the ISAPI and CGI Restrictions list. If the extension already exists we allow it.”

    Select Yes.

    You can later find the list of allowed applications as follows:

    In the left panel, highlight:

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

    In the middle panel, double-click ISAPI and CGI Restrictions.

    If the Gateway ISAPI components are not included in the list of allowed applications then add them (as you would have done for IIS 6):

    You can add text of your own choice in the Description field. For example:

    CSPGatewayManagement for CSPmsSys.dll

    CSPGatewayRunTime for CSPms.dll

  8. Repeat the above process: Use the Add Script Map dialogue to enter the following two mappings:

    Request Path: *.cls

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

    Name: CSPGateway_cls

    Request Path: *.zen

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

    Name: CSPGateway_zen

    Request Path: *.cxw

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

    Name: CSPGatewayManagement

Operating and Managing the Gateway

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

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

http://<ip_address>/csp/bin/CSPmsSys.dll

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 section “CSP Gateway and Security.”

Alternative Option 2: Using a Native Module with the NSD (CSPcms.dll)

IIS 7 does not, by default, run ISAPI extensions, ISAPI filters, or CGI modules. This option requires the CGI modules service for running the Gateway Management module (nph-CSPcgiSys.exe).

Follow the instructions in the section for installing the CGI service, Installing the ISAPI and CGI Services (If Required.

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.

Registering the Runtime Native Module

DLL: CSPcms.dll

Before this module can be used it 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.

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

    Name: CSPcms

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

    Select OK.

  6. 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
    
  7. In the right panel, select Add Native Module.

  8. In the Add Native Module dialogue select CSPcms then select OK.

Enabling the CGI module for Gateway Management

Executable: nph-CSPcgiSys.exe

Before this module can be used it must be registered with IIS as being an Allowed application. This is done in the Internet Information Services (IIS) Manager control panel.

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

  2. In the left panel, highlight:

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

  3. In the middle panel, double-click the ISAPI and CGI Restrictions icon.

  4. In the right panel, select Add.

  5. In the Add ISAPI or CGI Restriction dialogue, enter:

    ISAPI or CGI Path: C:\inetpub\CSPGateway\nph-CSPcgiSys.exe

    Description: CSPGatewayManagement

    Allow extension path to execute: Select

    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 *.

Choose one of the following configuration methods:

  1. Serve all content (including static content) from Cache. Map * to the CSP Gateway. If you are configuring CSP so that the Cache server serves all static files, then follow the file map procedure in the section “Registering Additional File Types with CSP” in this book.

  2. Serve static content from the web server.

    Map only files of type .csp, .cls, .zen, .cxw to the CSP Gateway.

If you are serving static files from the web server, map the CSP file extensions to the CSP Gateway 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   C:\inetpub\CSPGateway\nph-CSPcgiSys.exe
  1. Open the Internet Information Services (IIS) Manager window.

  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
    
    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:

    Request Path: *.csp

    Module: Select CSPcms

    Name: CSPGateway_csp

  6. Select Request Restrictions.

    Clear: Invoke handler only if request is mapped to

    Select OK to return to the Add Module Mappings dialogue.

    Select OK.

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

    Request Path: *.cls

    Module: Select CSPcms

    Name: CSPGateway_cls

    and

    Request Path: *.zen

    Module: Select CSPcms

    Name: CSPGateway_zen

  8. In the left panel, highlight the Default Web Site section:

    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
    
  9. In the middle panel, double-click the Handler Mappings icon.

  10. In the right panel, select Add Script Map.

  11. In the Add Script Map dialogue, enter:

    Request Path: *.cxw

    Executable: C:\inetpub\CSPGateway\nph-CSPcgiSys.exe

    Name: CSPGatewayManagement

  12. Select Request Restrictions.

    clear: Invoke handler only if request is mapped to

    Select OK to return to the Add Script Map dialogue.

    Select OK.

  13. You may be prompted as follows: “Would you like to enable this ISAPI extension? If yes, we add your extension as an “Allowed” entry in the ISAPI and CGI Restrictions list. If the extension already exists we allow it.”

    Select Yes.

    You can later find the list of allowed applications as follows:

    In the left panel, highlight:

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

    In the center panel, double-click the ISAPI and CGI Restrictions icon.

    If the Gateway Management CGI module is not included in the list of allowed applications, add it (as you would have done for IIS 6):

    You can add text of your own choice in the Description field. For example:

    CSPGatewayManagement for nph-CSPcgiSys.exe

Operating and Managing the Gateway

This connectivity option depends on the CSP Gateway’s Network Service Daemon (NSD).

Start the CSP NSD as described in the section, Starting the NSD.

Although CSP pages are served through the higher-performing module (CSPcms.dll), the Gateway’s management suite is accessed through the CGI module dedicated to this purpose (nph-CSPcgiSys.exe).

To access the CSP Gateway’s Systems Management suite, point your browser at one of the following locations:

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

http://<ip_address>/csp-bin/nph-CSPcgiSys

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 section CSP Gateway and Security.

Alternative Option 3: Using an ISAPI Module with the NSD (CSPcms.dll)

Use this option if your CSP Gateway DLLs are unable to support the Native Module interface (Alternative Option 2).

IIS 7 does not, by default, run ISAPI extensions, ISAPI filters or CGI modules. This option requires both the ISAPI extensions and the CGI modules service.

Follow the instructions in the section for installing the CGI service, Installing the ISAPI and CGI Services (If Required.

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 for processing.

Enabling the Runtime ISAPI Extension

DLLs: CSPcms.dll

Before this extension can be used it must be registered with IIS as being “Allowed” applications. 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 ISAPI and CGI Restrictions icon.

  4. In the right panel, select Add.

  5. In the Add ISAPI or CGI Restriction dialogue, enter:

    ISAPI or CGI Path: C:\inetpub\CSPGateway\CSPcms.dll

    Description: CSPGatewayRunTime

    Allow extension path to execute: Select

    Select OK

Enabling the CGI module for Gateway Management

Executable: nph-CSPcgiSys.exe

Before this module can be used it must be registered with IIS as being an “Allowed” application. 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 ISAPI and CGI Restrictions icon.

  4. In the right panel, select Add.

  5. In the Add ISAPI or CGI Restriction dialogue, enter:

    ISAPI or CGI Path: C:\inetpub\CSPGateway\nph-CSPcgiSys.exe

    Description: CSPGatewayManagement

    Allow extension path to execute: Select

    Select OK.

Mapping the CSP File Extensions

Choose one of the following configuration methods:

  1. Serve all content (including static content) from Cache. Map * to the CSP Gateway. If you are configuring CSP so that the Cache server serves all static files, then follow the file map procedure in the section “Registering Additional File Types with CSP” in this book.

  2. Serve static content from the web server.

    Map only files of type .csp, .cls, .zen, .cxw to the CSP Gateway.

If you are serving static files from the web server, map the CSP file extensions to the CSP Gateway Modules as follows:

Extension Binary
*.csp C:\inetpub\CSPGateway\CSPcms.dll
*.cls C:\inetpub\CSPGateway\CSPcms.dll
*.zen C:\inetpub\CSPGateway\CSPcms.dll
*.cxw C:\inetpub\CSPGateway\nph-CSPcgiSys.exe
  1. Open the Internet Information Services (IIS) Manager window.

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

    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
    
    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 Handler Mappings.

  4. In the right panel, select Add Script Map.

  5. In the Add Script Map dialogue, enter:

    Request Path: *.csp

    Executable: C:\inetpub\CSPGateway\CSPcms.dll

    Name: CSPGateway_csp

  6. Select Request Restrictions.

    clear: Invoke handler only if request is mapped to

    Select OK to return to the ‘Add Script Map’ dialogue.

    Select OK.

  7. At this point you may be prompted as follows:

    “Would you like to enable this ISAPI extension? If yes, we add your extension as an “Allowed” entry in the ISAPI and CGI Restrictions list. If the extension already exists we allow it.”

    Select Yes.

    You can later find the list of allowed applications as follows:

    In the left panel, highlight:

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

    In the middle panel, double-click the ISAPI and CGI Restrictions icon.

    If the Gateway ISAPI module is not included in the list of allowed applications then it should be added (as you would have done for IIS 6):

    You can add text of your own choice in the Description field. For example:

    CSPGatewayRunTime for CSPcms.dll

    CSPGatewayManagement for nph-CSPcgiSys.exe

  8. Repeat the above process: Use the Add Script Map dialogue to enter the following two mappings:

    Request Path: *.cls

    Executable: C:\inetpub\CSPGateway\CSPcms.dll

    Name: CSPGateway_cls

    Request Path: *.zen

    Executable: C:\inetpub\CSPGateway\CSPcms.dll

    Name: CSPGateway_zen

    Request Path: *.cxw

    Executable: C:\inetpub\CSPGateway\nph-CSPcgiSys.exe

    Name: CSPGatewayManagement

Operating and Managing the Gateway

This connectivity option depends on the CSP Gateway’s Network Service Daemon (NSD).

  1. Start the CSP NSD as described in the section dedicated to this service.

Although CSP pages are served through the higher-performing ISAPI module (CSPcms.dll), the Gateway’s management suite is accessed through the CGI module dedicated to this purpose (nph-CSPcgiSys.exe).

To access the CSP Gateway’s Systems Management suite, point your browser at one of the following locations:

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

http://<ip_address>/csp-bin/nph-CSPcgiSys

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 section “CSP Gateway and Security.”

Alternative Option 4: Using the CGI Modules with the NSD (nph-CSPcgi*.exe)

In most cases, the all-inclusive Native Module-based solution (the Recommended Option) is the option of choice, and is the implementation that gives the best performance. The CGI/NSD hybrid is useful for cases where it is necessary, for operational reasons, to manage the Gateway independently of the hosting web server. For example, if multiple instances of the web server are to share the same Gateway installation. In option 1 each instance of the core web server process binds to its own instance of the Gateway.

Another factor in choosing this approach might be that the in-house requirements of your web master (or ISP) dictate that all web server extensions are implemented using the CGI protocol.

IIS 7 does not, by default, run ISAPI extensions, ISAPI filters or CGI modules. This option requires the CGI modules service.

Follow the instructions in the section for installing the CGI service, Installing the ISAPI and CGI Services (If Required.

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.

Enabling the CGI Modules

Executables: nph-CSPcgi.exe and nph-CSPmsSys.exe

Before these modules can be used they must be registered with IIS as being “Allowed” applications. 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 ISAPI and CGI Restrictions icon.

  4. In the right panel, select Add.

  5. In the Add ISAPI or CGI Restriction dialogue, enter:

    ISAPI or CGI Path: C:\inetpub\CSPGateway\nph-CSPcgi.exe

    Description: CSPGatewayRunTime

    Allow extension path to execute: Select

    Select OK.

  6. Repeat the above steps for nph-CSPcgiSys.exe, entering the following details in the Restrictions dialogue:

    ISAPI or CGI Path: C:\inetpub\CSPGateway\nph-CSPcgiSys.exe

    Description: CSPGatewayManagement

    Allow extension path to execute: Select

Mapping the CSP File Extensions

Choose one of the following configuration methods:

  1. Serve all content (including static content) from Cache. Map * to the CSP Gateway. If you are configuring CSP so that the Cache server serves all static files, then follow the file map procedure in the section “Registering Additional File Types with CSP” in this book.

  2. Serve static content from the web server.

    Map only files of type .csp, .cls, .zen, .cxw to the CSP Gateway.

If you are serving static files from the web server, map the CSP file extensions to the CSP Gateway CGI Modules as follows:

Extension Binary
*.csp C:\inetpub\CSPGateway\nph-CSPcgi.exe
*.cls C:\inetpub\CSPGateway\nph-CSPcgi.exe
*.zen C:\inetpub\CSPGateway\nph-CSPcgi.exe
*.cxw C:\inetpub\CSPGateway\nph-CSPcgiSys.exe
  1. Open the Internet Information Services (IIS) Manager window.

  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
    
    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 Script Map.

  5. In the Add Script Map dialogue, enter:

    Request Path: *.csp

    Executable: C:\inetpub\CSPGateway\nph-CSPcgi.exe

    Name:CSPGateway_csp

  6. Select Request Restrictions.

    Clear: Invoke handler only if request is mapped to

    Select OK to return to the Add Script Map dialogue.

    Select OK.

  7. At this point you may be prompted as follows: “Would you like to enable this ISAPI extension? If yes, we add your extension as an “Allowed” entry in the ISAPI and CGI Restrictions list. If the extension already exists we allow it.”

    Select Yes.

  8. You can later find the list of allowed applications as follows:

    In the left panel, highlight:

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

    In the middle panel, double-click the ISAPI and CGI Restrictions icon.

    If the Gateway CGI components are not included in the list of allowed applications then add them (as you would have done for IIS 6):

    You can add text of your own choice in the Description field. For example:

    CSPGatewayManagement for nph-CSPcgiSys.exe

    CSPGatewayRunTime for nph-CSPcgi.exe

  9. Repeat the above process: Use the Add Script Map dialogue to enter the following two mappings:

    Request Path: *.cls

    Executable: C:\inetpub\CSPGateway\nph-CSPcgi.exe

    Name: CSPGateway_cls

    Request Path: *.zen

    Executable: C:\inetpub\CSPGateway\nph-CSPcgi.exe

    Name: CSPGateway_zen

    Request Path: *.cxw

    Executable: C:\inetpub\CSPGateway\nph-CSPcgiSys.exe

    Name: CSPGatewayManagement

Operating and Managing the Gateway

This connectivity option depends on the CSP Gateway’s Network Service Daemon (NSD).

  1. Start the CSP NSD as described in the section dedicated to this service.

To access the CSP Gateway’s Systems Management suite, point your browser at one of the following locations:

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

http://<ip_address>/csp-bin/nph-CSPcgiSys

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 section “CSP Gateway and Security”.

Alternative Options for IIS6 or Earlier

Using the ISAPI Filter (CSPmsf1.dll)

You can use this filter with all IIS connectivity options. It can be deployed to provide essential functionality in the following two areas.

Processing WebDAV Requests

The use of the filter is essential if CSP is used to implement WebDAV services.

Many Microsoft WebDAV clients include the Translate: f header in the HTTP request headers sent to the web server with each and every request. IIS, on detecting this header directive, attempts to process the request directly without forwarding it on to any further ISAPI extensions (such as the CSP Gateway) which might otherwise have been called in the absence of this header. This behavior effectively prohibits CSP from processing WebDAV requests.

The Translate: f header is essentially a way of avoiding the overloading of the GET method in the WebDAV protocol. HTTP GET usually means get (that is, run) the page; WebDAV clients expect this method to get the source to the page instead. IIS cannot possibly implement this latter functionality for CSP-based content because the physical content (or source code) is associated with the Caché server and not the web server. Therefore, requests from a Microsoft WebDAV client working to a CSP-based WebDAV server through IIS fail with HTTP Forbidden or File doesn't exist errors.

The filter works around this problem by examining the incoming request stream and translating Translate: f header directives to Translate: g. IIS then passes the request on to the CSP Gateway, if appropriate.

Processing Multiline HTTP Request Headers

IIS does not correctly process header directives that are split over multiple lines. In fact the whole HTTP header block can become badly corrupted.

Recent tests demonstrated that in some cases the affected header block can become corrupted to the extent that it is not possible to always work around the problem in the Gateway code (that is, after the corruption had occurred). See the example below.

The filter corrects this problem by removing carriage-return-linefeeds (CRLs) from individual header directives before IIS has a chance to parse the header block.

Example of the problem: Consider the following request header block.


POST /csp/xds/XDSRequest.csp HTTP/1.1 
Accept: text/html, text/plain, text/xml, image/gif, image/jpeg, */* 
Content-Length: 1787 
certAlias: unknowncert 
SOAPAction: \"" Content-Type: multipart/related; type="text/xml";" \
boundary=--boundary 
421.41176470588235291359.470588235294118-- 
User-Agent: HttpClient/1.4.2 
Mozilla/4.0
Host: localhost 
Connection: keep-alive 

Notice that the content boundary (part of the content-type directive) has been completely misplaced. It has been found that the nature of this corruption is not consistent. The servicing of the request can completely fail depending on the nature of the damage caused and the misparsing that occurs as a result.

Installing the Filter

The filter operates on raw request data and must therefore be installed globally for the whole web server:

  1. Open the Internet Services Manager.

  2. Navigate to Web Sites. Right-click this item and select Properties.

  3. Select the ISAPI Filters tab.

  4. Select Add.

  5. Enter CSP Gateway for the Filter name.

  6. Browse to CSPmsf1.dll for Executable.

  7. Select OK.

  8. Restart the World Wide Web Publishing service from the Windows Services control panel (not the Internet Information Services control panel). Alternatively, restart the computer.

Alternative Option 1: IIS and ISAPI Module with NSD (CSPcms.dll)

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

In most cases, the all-inclusive ISAPI-based solution (the Recommended Option) is the option of choice, and is the implementation that gives the best performance. The ISAPI/NSD hybrid, described here, is useful for cases where it is necessary, for operational reasons, to manage the Gateway independently of the hosting web server; for example, if multiple instances of the web server are to share the same Gateway installation. In the Recommended Option, each instance of the core web server process binds to its own instance of the Gateway.

The Recommended Option provides better performance than the CGI/NSD hybrid described in Option 3. The higher latency that results from the need to start new processes to serve each and every request is avoided in this implementation.

Internet Information Services with ISAPI and NSD

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

Follow the instructions for the Recommended Option with the exception that CSP files should be associated with CSPcms.dll instead of CSPms.dll (steps 7 and 8) and nph-CSPcgiSys.exe instead of CSPmsSys.dll (step 9).

  • Executable: install-dir\csp\bin\CSPcms.dll

  • Extension: csp

  • All Verbs: Select

  • Script engine: Select

  • Check that file exists: Clear

  • Executable: install-dir\csp\bin\CSPcms.dll

  • Extension: cls

  • All Verbs: Select

  • Script engine: Select

  • Check that file exists: Clear

  • Executable: install-dir\csp\bin\CSPcms.dll

  • Extension: zen

  • All Verbs: Select

  • Script engine: Select

  • Check that file exists: Clear

  • Executable: install-dir\csp\bin\nph-CSPcgiSys.exe

  • Extension: cxw

  • All Verbs: Select

  • Script engine: Select

  • Check that file exists: Clear

Refer to the following section for further information relating to version 6 of IIS (shipped with Windows 2003).

Internet Information Services v6 with ISAPI and NSD

If you are running IIS 6, using the ISAPI modules with the NSD, follow the directions in the previous section and also follow these directions:

Follow the instructions for the Recommended Option with the exception that the following executables should be registered as allowed for the CSP Gateway instead of CSPms.dll and CSPmsSys.dll.

  • CSPcms.dll

  • nph-CSPcgi.exe

  • nph-CSPcgiSys.exe

To Prohibit Access to CSP

Mark the following executables as prohibited:

  • CSPcms.dll

  • nph-CSPcgi.exe

  • nph-CSPcgiSys.exe

To Prohibit Access to the CSP Gateway Systems Management Portal

Mark the following executables as prohibited:

  • nph-CSPcgi.exe

  • nph-CSPcgiSys.exe

To Prohibit Access to the CSP Gateway Runtime Module

Mark the following executable as prohibited: CSPcms.dll

Operating and Managing the Gateway with ISAPI and NSD

This connectivity option depends on the CSP Gateway Network Service Daemon (NSD).

  1. Start the CSP NSD as described in “Operating the Network Service Daemon (NSD)”.

  2. Restart Apache after making changes to its configuration file (httpd.conf).

    The order in which you start Apache and the NSD is unimportant.

  3. To access the CSP Gateway Systems Management Portal, point your browser at one of the following locations.

    Although CSP pages are served through the higher-performing module (mod_csp24.so), the CSP Web Gateway Management Page is accessed through the CGI module dedicated to this purpose (nph-CSPcgiSys).

    http://localhost:<port_no>/csp/bin/Systems/Module.cxw
    http://localhost:<port_no>/csp-bin/nph-CSPcgiSys
    

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

Alternative Option 2: IIS and CGI Modules with NSD (nph-CSPcgi.exe)

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

In most cases, the all-inclusive ISAPI-based solution (Option 1) is the option of choice, and is the implementation that gives the best performance. The CGI/NSD hybrid is useful for cases where it is necessary, for operational reasons, to manage the Gateway independently of the hosting web server, for example, if multiple instances of the web server are to share the same Gateway installation. In Option 1, each instance of the core web server process binds to its own instance of the Gateway.

Another factor in choosing this approach might be that the in-house requirements of your web master (or ISP) dictate that all web server extensions are implemented using the CGI protocol.

Internet Information Services with CGI and NSD

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

Follow the instructions for Recommended Option with the exception that CSP files should be associated with nph-CSPcgi.exe instead of CSPms.dll (steps 7 and 8) and nph-CSPcgiSys.exe instead of CSPmsSys.dll (step 9).

  • Executable: install-dir\csp\bin\nph-CSPcgi.exe

  • Extension: csp

  • All Verbs: Select

  • Script engine: Select

  • Check that file exists: Clear

  • Executable: install-dir\csp\bin\nph-CSPcgi.exe

  • Extension: cls

  • All Verbs: Select

  • Script engine: Select

  • Check that file exists: Clear

  • Executable: install-dir\csp\bin\nph-CSPcgi.exe

  • Extension: zen

  • All Verbs: Select

  • Script engine: Select

  • Check that file exists: Clear

  • Executable: install-dir\csp\bin\nph-CSPcgiSys.exe

  • Extension: cxw

  • All Verbs: Select

  • Script engine: Select

  • Check that file exists: Clear

Refer to the following section for further information relating to version 6 of IIS (shipped with Windows 2003).

Internet Information Services v6 with CGI and NSD

If you are running IIS 6, follow the directions in the previous section for all versions of IIS and also follow the directions in this section.

Follow the instructions for Recommended Option IIS 6, except register the following executables as allowed for the CSP Gateway instead of CSPms.dll and CSPmsSys.dll:

  • nph-CSPcgi.exe

  • nph-CSPcgiSys.exe

To Prohibit Access to CSP

Mark the following executables as prohibited:

  • nph-CSPcgi.exe

  • nph-CSPcgiSys.exe

To Prohibit Access to the CSP Gateway Systems Management Module

Mark the following executable as prohibited: nph-CSPcgiSys.exe.

To Prohibit Access to the CSP Gateway Runtime Module

Mark the following executable as prohibited: nph-CSPcgi.exe.

Operating and Managing the Gateway with CGI

This connectivity option depends on the CSP Gateway’s Network Service Daemon (NSD).

  1. Start the CSP NSD as described in “Operating the Network Service Daemon (NSD)”.

  2. Restart Apache after making changes to its configuration (httpd.conf).

    The order in which Apache and the NSD are started is unimportant.

  3. To access the CSP Web Gateway Management page, point your browser at one of the following locations. Although CSP pages are served through the higher-performing module (mod_csp24.so), the CSP Web Gateway Management page is accessed through the CGI module dedicated to this purpose (nph-CSPcgiSys).

    http://localhost:<port_no>/csp/bin/Systems/Module.cxw
    http://localhost:<port_no>/csp-bin/nph-CSPcgiSys
    

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, such as http://localhost:<port_no>/csp/samples/menu.csp

Alternative Options for Windows Apache

This section contains information for installations with Apache web servers on Microsoft Windows. Read the sections that apply to your installation.

Note:

If you are using Apache 2.2 or earlier: If you use the directions in this section, you add text to the end of the httpd.conf file. The text added specifying access control needs to be different for Apache 2.4 or Apache 2.2 (and earlier). If you are using Apache 2.4, use the text shown in this section. If you are using Apache 2.2, replace the following phrases in the httpd.conf sections. Replace Require all denied, with the line Deny from all. Replace Require all granted with the two lines Order allow,deny and Allow from all. If you require more information, see http://httpd.apache.org/docs/2.4/upgrading.htmlOpens in a new tab

Install Locations

The following modules are installed:

  • 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.

Alternative Option 1: Apache and CGI Modules with NSD (nph-CSPcgi.exe)

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

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

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

Add the following section to the end of httpd.conf:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</LocationMatch>
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "c:/cache-install-dir/csp/bin/nph-CSPcgi.exe"
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>
ScriptAlias /csp-bin/ "c:/cache-install-dir/csp/bin/"
ScriptAliasMatch /csp/bin/Systems/Module.cxw "c:/cache-install-dir/csp/bin/nph-CSPcgiSys.exe"
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "c:/cache-install-dir/csp/bin/nph-CSPcgi.exe"
<Directory "c:/cache-install-dir/csp/bin/">
    AllowOverride None
    Options None
    Require all granted
    <FilesMatch "\.(exe)$">
        Allow from all
    </FilesMatch>
</Directory>

The above configuration block relies on the Regular Expressions (regex) processor being available to the Apache environment. Sometimes this is not the case (particularly with Windows 2000 systems) and CSP files are consequently not served (File not found errors are returned). To remedy this situation, associate the (virtual) root location of your CSP applications with the CGI module instead of making the association through the CSP file extensions. For example, your CSP applications are in /csp. To associate the CSP CGI module with files under /csp, replace the following configuration block:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</LocationMatch>
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ 
      "c:/cache-install-dir/csp/bin/nph-CSPcgi.exe"

with

<Location "/csp">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</Location>
ScriptAlias /csp "c:/cache-install-dir/csp/bin/nph-CSPcgi.exe"

These directives work for URLs of the form:

http://localhost:<port_no>/csp/*.csp

Duplicate this configuration block for other root locations. For example, repeat the process for /myapps for URLs of the form:

http://localhost:<port_no>/myapps/*.csp

Another approach to avoiding the regex issue is to use an Action directive in conjunction with a CSP MIME type. However, note that Action is a content filtering technique and, as such, requires that your CSP files are physically present on the web server host even if the Caché server is installed on a separate computer.

To use this approach:

  1. Add a new MIME type to the end of the Apache mime.types file and associate it with the file types representing CSP content, .csp, .cls, and .zen. The mime.types file are in the same directory as the httpd.conf file:

    text/csp                csp cls
    
  2. Add the Action directive to the end of the CGI configuration block in httpd.conf such that it reads:

    Alias /csp/ c:/cache-install-dir/csp/
    <Directory "c:/cache-install-dir/csp">
        AllowOverride None
        Options MultiViews FollowSymLinks ExecCGI
        Require all granted
    <Files CSPnsd.exe>
           Require all denied
        </Files>
    <Files CSP.ini>
           Require all denied
        </Files>
    <Files CSP.log>
           Require all denied
        </Files>
    <Files CSPnsd.ini>
           Require all denied
        </Files>
    <Files CSPnsd.pid>
           Require all denied
        </Files>
        <FilesMatch "\.(log|ini|pid|exe)$">
           Require all denied
        </FilesMatch>
    </Directory>
    ScriptAlias /csp-bin/ "c:/cache-install-dir/csp/bin/"
    <Directory "c:/cache-install-dir/csp/bin/">
        AllowOverride None
        Options None
        Require all granted
    </Directory>
    Action text/csp “/csp-bin/nph-CSPcgi.exe”
    
    

    Finally, note that because CGI is an open standard, the CSP CGI modules work with any web server.

  3. 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 

iIf you need to serve other static files through the CSP Gateway, add mappings for the needed file types so that those files can be loaded. In particular, if you need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js. If you do not do so, the Management Portal will be missing its images.

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> 

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

/csp/ 
csp/samples/menu.csp 
csp/sys/ 
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 

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>

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> 
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

and

text/csp

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/CSPa22.dll
AddType application/x-csp csp cls zen xxx

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 NSD

This connectivity option depends on the CSP Gateway’s Network Service Daemon (NSD).

  1. Start the CSP NSD as described in “Operating the Network Service Daemon”.

  2. Restart Apache after making changes to its configuration (httpd.conf).

    The order in which Apache and the NSD are started is unimportant.

  3. To access the CSP Web Gateway Management page, point your browser at one of the following locations:

    http://localhost:<port_no>/csp/bin/Systems/Module.cxw
    http://localhost:<port_no>/csp-bin/nph-CSPcgiSys
    

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

Alternative Option 2: Apache API Module with NSD (mod_csp.dll)

Note:

This connectivity option is not used as often as the stand-alone API modules described in Option 1, however, it can be used if you need to use the NSD. The CSP module, built as a DLL (mod_csp24.dll – for Apache 2.4), performs better than the CGI-based solution (Option 2). The module is usually named mod_csp2.dll for Apache v2.0.x, and mod_csp22.dll for Apache v2.2.x.

  1. Edit the Apache configuration file httpd.conf. For the standard Apache distribution this file is in:

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

    To invoke CSP for files with the .csp, .cls, and .zen extensions, add the following section to the end of httpd.conf. For Apache v2.4.x, specify mod_csp24.dll. For Apache v2.2.x, specify mod_csp22.dll). For Apache v2.0.x, specify mod_csp2.dll.

    LoadModule csp_module c:/cache-install-dir/csp/bin/mod_csp24.dll
    <LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
                    SetHandler csp-handler
    </LocationMatch>
    Alias /csp/ /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>
            <Files CSPnsd>
                    Require all denied
            </Files>
    </Directory>
    ScriptAlias /csp-bin/ "c:/cache-install-dir/csp/bin/"
    ScriptAliasMatch /csp/bin/Systems/Module.cxw \ 
             "c:/cache-install-dir/csp/bin/nph-CSPcgiSys.exe" 
    ScriptAliasMatch /csp/bin/RunTime/Module.cxw \ 
             "c:/cache-install-dir/csp/bin/nph-CSPcgi.exe"
    <Directory "c:/cache-install-dir/csp/bin/">
            AllowOverride None
            Options None
            Require all granted
    </Directory>
    
    
  2. Optional step, if required: The above configuration block expects that the Regular Expressions (regex) processor is available to the Apache environment. If this is not the case (particularly with Windows 2000 systems), CSP files are not served (File not found errors are returned). To remedy this situation, replace the following configuration block:

    <LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
                    SetHandler csp-handler
    </LocationMatch>
    

    with:

    CSPFiletypes csp cls 
    
  3. Restart Apache after making changes to httpd.conf.

Registering additional file types with CSP

To configure additional file types to be processed by CSP, include the new file extension(s) in the list of usual file extensions (csp,. cls, zen) to be processed by the CGI module. For example, add them to the following line:

ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$  "/cache-install-dir/csp/bin/nph-CSPcgi"

If you need to serve other static files through the CSP Gateway, add mappings for the needed file types so that those files can be loaded. In particular, if you need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js. If you do not do so, the Management Portal will be missing its images.

The following directive can be used to map requests for all files to CSP for a given path.

ScriptAliasMatch ^/csp/*/.* "/cache-install-dir/csp/bin/nph-CSPcgi"

Therefore, a basic configuration block for mapping requests for all files in the /csp path to CSP would be:

ScriptAliasMatch ^/csp/*/.* "/cache-install-dir/csp/bin/nph-CSPcgi"
Directory "/cache-install-dir/csp/bin/">
   AllowOverride None    
   Options None
   Require all granted
</Directory>

Operating and Managing the Gateway with Apache API and NSD

This connectivity option depends on the CSP Gateway’s Network Service Daemon (NSD).

  1. Start the CSP NSD as described in “Operating the Network Service Daemon”.

  2. Restart Apache after making changes to its configuration (httpd.conf).

    The order in which Apache and the NSD are started is unimportant.

  3. To access the CSP Web Gateway Management page, point your browser at one of the following locations.

    Although CSP pages are served through the higher-performing module (mod_csp24.dll), the CSP Web Gateway Management page is accessed through the CGI module dedicated to this purpose (nph-CSPcgiSys.exe).

    http://localhost:<port_no>/csp/bin/Systems/Module.cxw 
    http://localhost:<port_no>/csp-bin/nph-CSPcgiSys.exe
    

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

Locked-down Apache Environments for Microsoft Windows

Occasionally Apache is locked-down such that you cannot easily configure the server to access files outside the Apache file system.

For configurations locked down in this way, the CSP Gateway configurations discussed in previous sections result in HTTP 403 Forbidden error codes being returned when you try to access CSP resources. To work with these secure configurations is to copy the file system under:

\cache-install-dir\csp\

to a location under the Apache root:

C:\Program Files\Apache Group\Apache\

Specify appropriate changes to the paths specified in the Apache configuration.

An alternative approach is to configure the CSP Gateway to work within the pre-configured directories provided by Apache.

  1. Copy CGI modules to: C:\Program Files\Apache Group\Apache\cgi-bin\ as follows:

    copy c:\cache-install-dir\csp\bin\*cgi*.exe C:\Program Files\Apache Group\Apache\cgi-bin\
    
  2. Copy API modules to C:\Program Files\Apache Group\Apache\modules:

    copy c:\cache-install-dir\csp\bin\*.dll C:\Program Files\Apache Group\Apache\modules\
    
  3. Copy static files (and their subdirectories) to locations under C:\Program Files\Apache Group\Apache\htdocs\csp\samples.

    copy c:\cache-install-dir\csp\samples\*.* \
    C:\Program Files\Apache Group\Apache\htdocs\csp\samples\ 
    copy c:\cache-install-dir\csp\broker\*.* \
    C:\Program Files\Apache Group\Apache\htdocs\csp\broker\
    copy c:\cache-install-dir\csp\sys\*.* \
    C:\Program Files\Apache Group\Apache\htdocs\csp\sys\
    
  4. Install the NSD component (if required) in C:\Program Files\Apache Group\Apache\nsd.

Using the pre-configured directories in Apache simplifies the CSP Gateway configuration in httpd.conf. Modified configuration blocks are shown below.

Configuration for Atypical Option 2: CGI Modules with NSD (nph-CSPcgi.exe)

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
AllowOverride None
Options FollowSymLinks ExecCGI
Require all granted
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgiSys.exe"
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgi.exe"
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgi.exe"
         

Configuration for Atypical Option 3: Apache API Module with NSD (mod_csp24.dll)

LoadModule csp_module \
         C:/<cache-install-dir>/Apache Group/Apache/modules/mod_csp24.dll
<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
SetHandler csp-handler
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgiSys.exe"
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgi.exe"

Configuration for Atypical Option 4: ISAPI Modules (CSPms.dll)

Legacy only

AddHandler isapi-isa dll
AddHandler isapi-isa csp
AddHandler isapi-isa cls
AddHandler isapi-isa zen
AddHandler isapi-isa cxw
Alias /csp/bin/Systems/Module.cxw /csp/bin/CSPmsSys.dll

FeedbackOpens in a new tab