Installing and Configuring the CSP Gateway

Installing and Configuringthe CSP Gateway

Version 5.201 September 2006

InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Installing and Configuring the CSP GatewayCaché Version 5.2 01 September 2006 Copyright © 2006 InterSystems Corporation.All rights reserved.

This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information fromthe following sources: Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium atwww.w3c.org. The primary document development tools were special-purpose XML-processing applications builtby InterSystems using Caché and Java.

The Caché product and its logos are registered trademarks of InterSystems Corporation.

The Ensemble product and its logos are registered trademarks of InterSystems Corporation.

The InterSystems name and logo are trademarks of InterSystems Corporation.

This document contains trade secret and confidential information which is the property of InterSystems Corporation,One Memorial Drive, Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operationand maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any otherpurpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system ortranslated into any human or computer language, in any form, by any means, in whole or in part, without the expressprior written consent of InterSystems Corporation.

The copying, use and disposition of this document and the software programs described herein is prohibited exceptto the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation coveringsuch programs and related documentation. InterSystems Corporation makes no representations and warrantiesconcerning such software programs other than those set forth in such standard software license agreement(s). Inaddition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use ofsuch software programs is limited in the manner set forth in such standard software license agreement(s).

THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BYINTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTERSOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARELICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLEUPON REQUEST.

InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves theright, in its sole discretion and without notice, to make substitutions and modifications in the products and practicesdescribed in this document.

Caché, InterSystems Caché, Caché SQL, Caché ObjectScript, Caché Object, Ensemble, InterSystems Ensemble,Ensemble Object, and Ensemble Production are trademarks of InterSystems Corporation. All other brand or productnames used herein are trademarks or registered trademarks of their respective companies or organizations.

For Support questions about any InterSystems products, contact:

InterSystems Worldwide Customer Support+1 617 621-0700Tel:+1 617 374-9391Fax:[email protected]:

Table of Contents

1 Introduction ..................................................................................................................... 1

2 Web Servers for Microsoft Windows ............................................................................. 52.1 Microsoft Peer Web Server (PWS) and Internet Information Services (IIS) ........... 6

2.1.1 Installation ...................................................................................................... 62.1.2 Option 1: Using the ISAPI Modules (CSPms*.dll) ........................................ 72.1.3 Option 2: Using an ISAPI Module with the NSD (CSPcms.dll) .................. 122.1.4 Option 3: Using the CGI Modules with the NSD (nph-CSPcgi*.exe) ......... 15

2.2 Netscape, iPlanet, and Sun Web Servers ................................................................ 172.2.1 Installation .................................................................................................... 182.2.2 Option 1: Using the NSAPI Modules (CSPn3*.dll) ..................................... 192.2.3 Option 2: Using an ISAPI Module with the NSD (CSPcn3.dll) .................. 21

2.3 Apache Servers ....................................................................................................... 232.3.1 Installation (All Connectivity Options) ........................................................ 232.3.2 Option 1: Using the Apache API Modules (CSPa*.dll) ............................... 252.3.3 Option 2: Using the CGI Modules with the NSD (nph-CSPcgi*.exe) ......... 262.3.4 Option 3: Using an Apache API Module with the NSD (mod_csp*.dll) ..... 292.3.5 Option 4: Using the ISAPI Modules (CSPms*.dll) ...................................... 31

2.4 Operating the Network Service Daemon (NSD) .................................................... 33

3 Web Servers for UNIX, LINUX, and Mac OS X ........................................................ 353.1 Netscape, iPlanet, and Sun Web Servers ................................................................ 35

3.1.1 Installation .................................................................................................... 363.1.2 Option 1: Using the NSAPI Modules (CSPn3*.so) ..................................... 383.1.3 Option 2: Using a NSAPI Module with the NSD (CSPcn3.so) ................... 40

3.2 Apache Servers ....................................................................................................... 413.2.1 Installation (All Connectivity Options) ........................................................ 423.2.2 Option 1: Using a Dynamic Apache API Module with the NSD (mod_csp*.so)................................................................................................................................ 433.2.3 Option 2: Using the CGI Modules with the NSD (nph-CSPcgi*) ............... 473.2.4 Option 3: Using a Built-in Apache API Module with the NSD (mod_csp.c) ....5 0

3.3 Operating the Network Service Daemon (NSD) .................................................... 55

4 General Web Server Configuration Issues .................................................................. 57

Installing and Configuring the CSP Gateway iii

4.1 A Note on the CGI Modules Supplied ................................................................... 574.2 Security Issues in Accessing the Gateway’s Systems Management ..................... 584.3 Making a CSP Page the Default Page (or ‘Homepage’) for the Web Server ......... 59

4.3.1 Peer Web Server ........................................................................................... 604.3.2 Internet Information Services ....................................................................... 604.3.3 Netscape, iPlanet, and Sun Web Servers ...................................................... 61

4.4 Apache Servers ....................................................................................................... 62

iv Installing and Configuring the CSP Gateway

1Introduction

This document describes the procedures for configuring the CSP Gateway to work with allthe Web servers that Caché supports. The CSP Gateway is responsible for providing thecommunications layer between the hosting Web server and Caché.

In most cases, the automatic installation procedures supplied with the Caché distributionsprovide a working system without the need to manually follow the instructions in this docu-ment. However, for cases where atypical Web server architectures are encountered or foradvanced users who wish to get the best out of their environments, this document containsall the necessary installation and configuration information:

Web ServersOperating System

Microsoft — Internet Information Services (IIS), including PeerWeb Server

Microsoft Windows

Sun — Netscape, iPlanet, Sun ONE, and Sun Java System

Apache

Sun — Netscape, iPlanet, Sun ONE, and Sun Java SystemUNIX

Apache

High performance connectivity solutions are supplied with CSP for Microsoft,Netscape/iPlanet/Sun and the Apache Web servers. Connectivity to Caché through theCommon Gateway Interface (CGI) is available for all supported Operating Systems and, assuch, can potentially offer support for Web servers not explicitly mentioned in this guide.

The Microsoft and Netscape/iPlanet/Sun line of Web servers both support a multithreadedAPI which allows extensions, in the form of dynamically bound libraries, to be made to the

Installing and Configuring the CSP Gateway 1

Web server’s core functionality. Current versions of the CSP Gateway make full use of theseAPIs in order to bring high-performance Web connectivity to the Caché system. The Windowsversion of Apache also operates in an exclusively multithreaded mode and, as such, can alsotake advantage of the CSP Gateway implemented as a dynamically bound library.

The UNIX version of Apache are architecturally different from the Microsoft andNetscape/iPlanet/Sun Web servers in that they are not inherently multithreaded servers and,as such, do not support the multithreaded style of API. In order to support these versions ofApache (and similarly designed Web servers) the multithreaded CSP Gateway is implementedas a stand-alone executable that runs independently of the Web server as a daemon process.This stand-alone implementation of the CSP Gateway is known as the Network ServiceDamon (NSD). The Web server communicates with the NSD through small dedicated modulesthat work to the hosting Web server’s proprietary API or through the standard CommonGateway Interface (CGI). The Apache Web server does publish a proprietary API in additionto supporting extensions implemented as CGI modules.

You can add extra functionality to Apache by means of user-defined modules (compiled Cprograms). In fact, a large part of Apache's core functionality is implemented as a set ofmodules. You can add modules to Apache by one of two methods. First, the source to themodule can be compiled directly into the Apache core. This option arguably offers the bestperformance but, unfortunately, involves reconfiguring and rebuilding the Web server. Thesource code to a ‘CSP module’ is provided for this purpose. As an alternative to building themodule source directly into the Apache core, later versions of Apache (1.3 onwards) supportextensions implemented as dynamically linked libraries. This facility allows you to takeadvantage of the high performance of Apache modules without the need to physically buildthe module into the core of Apache. The CSP module can be built as a Windows ‘DynamicLink Library’ (DLL) and as a UNIX ‘Dynamic Shared Object’ (DSO). UNIX Shared Objectsare conceptually similar to a Windows Dynamic Link Library (DLL) and are linked at runtime. The overhead involved in linking to a library at run time is very low on modern operatingsystems and it is recommended that this option be chosen over the built-in approach. Pre-built versions of the CSP module are available for most supported Operating Systems.

In addition to the connectivity options described above, there is also a high-performance CGI-based solution. This is for Apache installations for which a pre-built module is not availableand users do not wish to either build the module themselves from source or build it directlyinto the Apache core.

Both the CSP module and the CGI executables are small functional blocks designed to com-municate exclusively with the NSD. In this context, the NSD is responsible for providing theCSP Gateway’s core functionality and persistent connections to Caché. The CSP moduleoffers better performance than the CGI-based equivalent. The CSP module is attached directly

2 Installing and Configuring the CSP Gateway

Introduction

to the hosting Apache processes whereas the CGI module must be started in its own process.For small systems, the performance difference between the CSP module and CGI executablemay not be that noticeable. However, the difference becomes more marked as the load onthe system increases and the overhead of starting and managing the extra number of processesthat are required by the CGI-based connectivity model becomes apparent.


Introduction

2Web Servers for MicrosoftWindows

This section describes Web Servers from Microsoft, Sun and Apache. The original NetscapeWeb servers (Enterprise and FastTrack), which were, until fairly recently, marketed underthe name of ‘iPlanet’, are now developed and marketed by Sun as the ‘Sun ONE’ suite ofservers. At the time of writing, Sun had renamed these servers again and the Sun ONE Webserver is now known as the “Sun Java System Web Server.”

All Microsoft Web servers can be extended by means of a high-performance API. TheInternet Server Application Programming Interface (ISAPI) allows us to extend the Webserver through ‘ISAPI extensions’ implemented as Windows DLLs.

Netscape/iPlanet/Sun Web servers can also be extended by means of a high-performanceAPI. The Netscape Application Programming Interface (NSAPI) allows us to extend the Webserver through modules implemented as Windows DLLs.

Several connectivity options are available for Apache. The CGI-based solution is arguablythe easiest option to install and configure. The Apache Group also provides support forextensions implemented as dynamically linked modules (DLLs) and a means through whichISAPI extensions, developed for Microsoft’s Web servers, can be utilized.


2.1 Microsoft Peer Web Server (PWS) andInternet Information Services (IIS)

PWS is essentially a lightweight version of IIS. As a general rule, PWS is supplied withMicrosoft’s client-oriented Operating Systems (such as Windows 95/98/NT WorkStation/Me)and IIS is supplied with the server-oriented Operating Systems (such as Windows NTServer/2000/2003). Windows XP, though predominantly a client-oriented Operating System,includes the IIS server.

This guide is based on the various CSP/Gateway Web server components being installed inthe following file system:

C:\cachesys\csp\

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

2.1.1 Installation

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

1. NSD Module (if required)

• CSPnsd.exe

• CSPnsdSv.exe

The default location for these modules is C:\cachesys\csp.

The NSD should be run from within its home directory (above). The configuration file(CSP.INI) and Event Log (CSP.LOG) are written in this directory for NSD-based connec-tivity options.

2. ISAPI and CGI Modules

• CSPms.dll (Run-time module)

• CSPmsSys.dll (Systems-management module)

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

• CSPcgi.exe (Run-time module)

• nph-CSPcgi.exe (A copy of CSPcgi)


Web Servers for Microsoft Windows

• CSPcgiSys.exe (Systems-Management module)

• nph-CSPcgiSys.exe (A copy of CSPcgiSys)

Note that not all of the modules listed above are required for all connectivity options.Refer to the sections describing each option to see which are actually required.

The default location for these modules is C:\cachesys\csp\bin.

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

3. HyperEvents Components

• CSPBroker.js

• CSPBBroker.class

• CSPBroker.jar

• CSPxmlhttp.js

The default location for these files is C:\cachesys\csp\broker.

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

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

The Web server should be configured such that it recognizes CSP requests (files of type .cspand .cls) and passes them to the CSP Gateway for processing.

2.1.2.1 Peer Web Server

1. Add the following two key values to the Windows registry, in the HKEY_LOCAL_MACHINE(HKLM) set of keys. These keys instruct PWS to pass requests for CSP files to the CSPGateway for processing.

REGEDIT4

[HKLM\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\Script Map]".csp"="C:\\cachesys\\csp\\bin\\CSPms.dll"

REGEDIT4

[HKLM\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\Script Map]".cls"="C:\\cachesys\\csp\\bin\\CSPms.dll"


Microsoft Peer Web Server (PWS) and Internet Information Services (IIS)

2. Open the Internet Service Manager window.

3. Double-click on the WWW Service to bring up the WWW Service Properties window.

4. Click on the Directories tab.

5. Click the Add button and enter the following Virtual Directory.

• Directory: c:\cachesys\csp

• Virtual Directory: Check

• Alias: /csp

• Access: Check Read and Execute

6. Save and Apply all changes and restart the computer.

2.1.2.2 Internet Information Services

1. Open the Internet Services Manager window.

2. In the left-hand window, navigate to the Default Web Site.

3. Right-click on the Default Web Site. Select Properties from the menu to bring up theDefault Web Site Properties window.

4. Click on the Home Directory tab.

5. Click the Configuration button to bring up the Application Configuration window.

6. Click on the App Mappings tab.

7. Click the Add button to bring up the Add/Edit Application Extension window and add thefollowing record:

• Executable: c:\cachesys\csp\bin\CSPms.dll

• Extension: csp

• All Verbs: Check

• Script engine: Check

• Check that file exists: UnCheck

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

• Executable: c:\cachesys\csp\bin\CSPms.dll

• Extension: cls






9. Return to the Internet Information Services window and navigate to the Default Web Site.

10. Right-click on the Default Web Site and select New -> Virtual Directory from the menusto bring up the Virtual Directory Creation window. Add the following record:

• Alias: csp

• Directory: c:\cachesys\csp

• Execute Permissions: Check

11. Save and Apply all changes and restart the computer.

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

2.1.2.3 Internet Information Services Version 6

This version of IIS is the Web server shipped with Windows Server 2003 (Formerly knownas Windows .net Server 2003). In configuring CSP to work with this server, the CSP GatewayISAPI DLLs (CSPms.dll and CSPmsSys.dll) must be registered as ‘allowed’ Web serviceextensions.


2. In the left-hand window, navigate to the Web Service Extensions. This displays a list ofcurrently configured extensions (or applications) in the right-hand panel.

3. Right-click on the Web Services Extensions. Select Add a new Web service extensionfrom the menu to bring up the New Web Service Extension window.

4. Type in CSP Gateway for the Extension name field.

5. Click the Add button to bring up the Add File dialog. Add CSPms.dll (including the fullphysical path to this DLL. Repeat the process for CSPmsSys.dll.

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

7. Finally click the OK button to file the Web Service Extension.



Note that there is an option to allow users access to all ISAPI extensions: Allow All unknownISAPI extensions. Enabling this option automatically enable access to the CSP Gateway’sISAPI modules. However, in the interests of security it recommended that the proceduresoutlined above are followed and that additional access is only granted to the CSP Gatewaymodules.

It is a common mistake to register the Gateway’s modules, which are ISAPI extensions, asISAPI filters. This error should be avoided as it totally prohibit the use of CSP.

The following additional operations can be later performed on registered Web ServiceExtensions.

To Prohibit Access to CSP

Use this procedure to temporarily disable access to the CSP Gateway and, by implication,all CSP-based resources.


2. In the left-hand window, navigate to the Web Service Extensions. You will see a list ofcurrently configured extensions (or applications) in the right-hand panel.

3. In the right-hand window right-click on CSP Gateway and select Prohibit. Access to theCSP Gateway is now prohibited.

Reactivating the CSP Gateway is the reverse procedure to that shown above – in the last step,select Allow.

To Prohibit Access to the CSP Gateway’s Systems Management Module

Use this procedure to disable access to the CSP Gateway’s Systems Management suite. Doingthis will prevent the possibility of unauthorized users gaining access the Systems ManagementSuite for an operational system. It is a quick and straightforward procedure for systemadministrators to re-enable access for a future period of time in order for configuration changesto be made to the Gateway.


2. In the left-hand window, navigate to the Web Service Extensions. You will see a list ofcurrently configured extensions (or applications) in the right-hand panel.

3. In the right-hand window double-click on CSP Gateway to bring up the Web Service

Extension Properties window.

4. Click on the Required Files tab.

5. Click on CSPmsSys.dll to highlight (or select) this file.



6. Click on the Prohibit button to the right followed by the Apply button and finally the OK

button located at the bottom of the dialog.

Reactivating the CSP Gateway Systems Management module is the reverse procedure to thatshown above – at this last stage click on the Allow button.

Of course, the above procedure can also be used to prevent end-users from gaining access toCSP resources while significant changes are being made to the Gateway’s configuration. Inthis case, the Gateway’s run-time module (CSPms.dll) should be marked as Prohibited insteadof the Systems Management module (CSPmsSys.dll).

2.1.2.4 Security Settings

For many Windows installations (particularly Windows 2000 and later), the default privilegesassigned to the Web server (PWS or IIS) are not sufficient to allow the CSP Gateway to readfrom 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 Gateway’s files, orgrant the Web server 'Administrator' privileges.

File-access privileges can be modified through Windows Explorer. Alternatively, you canuse the following two commands:

cacls c:\cachesys\csp\bin\CSP.ini /E /G IUSR_xxx:Fcacls c:\cachesys\csp\bin\CSP.log /E /G IUSR_xxx:F

Where 'IUSR_xxx' is the Web server’s user authority. The 'xxx' component is usually thecomputer name. You can find the specific name in the Internet Service Manager by navigatingto the Authentication methods dialog as follows:



3. Right-click on the Default Web Site

. Select Properties from the menu to bring up the Default Web Site Properties window.

4. Click on the Directory Security tab.

5. Click on the Edit button under the Anonymous access and authentication control panel.This displays the User Name in the Authentication methods dialog.

Before invoking the ‘cacls’ command, it is necessary to create the files that you are applyingit to, if they don’t already exist. Use the ‘copy con’ command (in a Windows CommandPrompt window or ‘DOS box’) to create empty files:



Copy con c:\cachesys\csp\bin\CSP.ini^Z

Copy con c:\cachesys\csp\bin\CSP.log^Z

Each individual command line is terminated with ‘carriage return’. ‘^Z’ refers to ‘Control-Z’.

Example:

Use the following commands to adjust the CSP Gateway’s configuration and log file accessrights for a computer named BOSTON:

cacls c:\cachesys\csp\bin\CSP.ini /E /G IUSR_BOSTON:Fcacls c:\cachesys\csp\bin\CSP.log /E /G IUSR_BOSTON:F

2.1.2.5 Operating and Managing the Gateway

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

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

If you see an unauthorized user error message, refer to the security notes.

The CSP engine is automatically invoked for requested files containing the .csp and .clsextension. For example:

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

2.1.3 Option 2: Using an ISAPI Module with the NSD (CSPcms.dll)

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

This 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 everyrequest is avoided in this implementation.


Follow the instructions for Option 1 with the exception that the registry settings shouldassociate CSP files with CSPcms.dll instead of CSPms.dll.



REGEDIT4

[HKLM\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\Script Map]".csp"="C:\\cachesys\\csp\\bin\\CSPcms.dll"

REGEDIT4

[HKLM\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\Script Map]".cls"="C:\\cachesys\\csp\\bin\\CSPcms.dll"


Follow the instructions for Option 1 with the exception that CSP files should be associatedwith CSPcms.dll instead of CSPms.dll (steps 7 and 8).

• Executable: c:\cachesys\csp\bin\CSPcms.dll

• Extension: csp




• Executable: c:\cachesys\csp\bin\CSPcms.dll

• Extension: cls






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

• CSPcms.dll

• nph-CSPcgi.exe

• nph-CSPcgiSys.exe




Mark the following executables as prohibited:

• CSPcms.dll

• nph-CSPcgi.exe




• nph-CSPcgi.exe


To Prohibit Access to the CSP Gateway’s Run-Time Module

Mark the following executable as prohibited: CSPcms.dll


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

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

• Apache must be (re)started after making changes to its configuration (httpd.conf).

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

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

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

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






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

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

Another factor in choosing this approach might be that the in-house requirements of yourWeb master (or ISP) dictate that all Web server extensions are implemented using the CGIprotocol.


Follow the instructions for Option 1 with the exception that the registry settings shouldassociate CSP files with nph-CSPcgi.exe instead of CSPms.dll.

REGEDIT4

[HKLM\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\Script Map]".csp"="C:\\cachesys\\csp\\bin\\nph-CSPcgi.exe"

REGEDIT4

[HKLM\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\Script Map]".cls"="C:\\cachesys\\csp\\bin\\nph-CSPcgi.exe"


Follow the instructions for Option 1 with the exception that CSP files should be associatedwith nph-CSPcgi.exe instead of CSPms.dll (steps 7 and 8).

• Executable: c:\cachesys\csp\bin\nph-CSPcgi.exe

• Extension: csp




• Executable: c:\cachesys\csp\bin\nph-CSPcgi.exe



• Extension: cls






Follow the instructions for Option 1 with the exception that the following executables shouldbe registered as allowed for the CSP Gateway instead of CSPms.dll and CSPmsSys.dll:

• nph-CSPcgi.exe




• nph-CSPcgi.exe



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

To Prohibit Access to the CSP Gateway’s Runtime Module

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














2.2 Netscape, iPlanet, and Sun Web Servers

This section covers the configuration and operational procedures for running CSP throughthe original Netscape Web servers (Enterprise and FastTrack). The modern versions of theseservers were, until fairly recently, marketed under the name of iPlanet, but are now developedand marketed by Sun as the Sun ONE suite of servers. At the time of writing, Sun had furtherrenamed these servers and the Sun ONE Web server is now known as the Sun Java SystemWeb Server.

Traditionally, these Netscape-based servers are produced in two forms: FastTrack andEnterprise. The FastTrack server is a lightweight version of the Enterprise-grade server withlimited functionality and is usually supplied free of charge. The installation and configurationprocedure (with respect to CSP) is the same for both grades of server.


C:\cachesys\csp\

It is assumed that the Web server is installed under:

C:\Netscape\SuiteSpot\

For the sake of brevity, the ‘Netscape’ product name is used throughout in the followingdiscussion. However, be aware of the various name changes that have occurred in this productline. For example, the iPlanet server, though essentially the same product as NetscapeEnterprise, is installed under:

C:\iPlanet\SuiteSpot\

The later versions supplied by Sun are installed under:

C:\Sun\WebServer\


Netscape, iPlanet, and Sun Web Servers

Individual instances of the Netscape server are installed under directories of the form:

C:\Netscape\SuiteSpot\https-<server_name>\

or

C:\Netscape\SuiteSpot\httpd-<server_name>\

Where server_name is the logical name assigned to the hosting computer.


The documentation root directory for these servers is usually:

C:\Netscape\SuiteSpot\docs\

2.2.1 Installation



• CSPnsd.exe

• CSPnsdSv.exe

The default location for these modules is:

C:\cachesys\csp


2. NSAPI and CGI Modules

• CSPn3.dll (Run-time module)

• CSPn3Sys.dll (Systems-management module)

• CSPcn3.dll (NSAPI client to the NSD – if supplied)









C:\cachesys\csp\bin



• CSPBroker.js


• CSPBroker.jar

• CSPxmlhttp.js

The default location for these files is:

C:\cachesys\csp\broker


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

2.2.2 Option 1: Using the NSAPI Modules (CSPn3*.dll)

The Web server should be configured such that it recognizes CSP requests (files of type .cspand .cls) and passes them to the CSP Gateway for processing.

The Web server configuration files (magnus.conf and obj.conf) are in the following directory:

C:\Netscape\SuiteSpot\https-<server_name>\config\

Directives to load the NSAPI modules and instructions for recognizing and processing CSPfiles must be added to the Web server configuration.



2.2.2.1 The Directives

Directives for Loading the NSAPI Modules

The ‘Init’ directive instructs the Web server to load NSAPI modules. Depending on whichversion of the Web server you have, these directives should be added to either the coremagnus.conf file or the objects obj.conf configuration file. The Netscape Web servers andearly iPlanet servers use the obj.conf for holding ‘Init’ directives, whereas later iPlanet andSun servers use the magnus.conf file. In order to determine which of these two configurationfiles you should use, examine both to see where the Web server’s core ‘Init’ directives areheld. These core configuration directives are always present, an example of which is as follows:

Init fn=load-types mime-types=mime.types

Having located the block of core ‘Init’ directives, add the following section before this block:

Init fn=load-modules shlib=C:/cachesys/csp/bin/CSPn3.dll \ funcs=csp_term,csp_init,csp_reqInit fn=csp_init shlib="C:/cachesys/csp/bin/CSPn3.dll"Init fn=load-modules shlib= C:/cachesys/csp/bin/CSPn3Sys.dll \ funcs=csp_term_sys,csp_init_sys,csp_req_sysInit fn=csp_init_sys shlib="C:/cachesys/csp/bin/CSPn3Sys.dll"

Note that ‘Init’ directives are made up of a single line. Due to the limitations of space, thelines shown above are wrapped before the function declarations (funcs).

Directives for Locating Static Components

CSP includes a number of ‘static’ files that are served by the Web server. For example, theJava/JavaScript files used to implement hyperevents and the image used in the CSP samples.These files are detailed in sections 3 and 4 of the installation section respectively.

The Web server needs to know the location of these files relative to the virtual CSP documen-tation root directory.

Find the ‘default’ directives section of obj.conf:

<Object name="default">

Add the following two lines in the ‘default’ section – that is, after the line shown above.

NameTrans fn="pfx2dir" from="/csp/samples" dir="c:/cachesys/csp/samples"NameTrans fn="pfx2dir" from="/csp/broker" dir="c:/cachesys/csp/broker"

Directives for Recognizing and Processing CSP Requests

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



<Object ppath="*/*.csp">Service method=(GET|HEAD|POST) fn=csp_req</Object><Object ppath="*/*.cls">Service method=(GET|HEAD|POST) fn=csp_req</Object><Object ppath="*/CSPn3Sys.dll">Service method=(GET|HEAD|POST) fn=csp_req_sys</Object><Object ppath="*/CSPn3.dll">Service method=(GET|HEAD|POST) fn=csp_req</Object>


The Web server must be restarted after making changes to its configuration files (magnus.conf

and obj.conf).

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

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




2.2.3 Option 2: Using an ISAPI Module with the NSD (CSPcn3.dll)

In most cases, the all-inclusive NSAPI-based solution (Option 1) is the option of choice, andis the implementation that gives the best performance. The NSAPI/NSD hybrid is useful forcases where it is necessary, for operational reasons, to manage the Gateway independentlyof the hosting Web server. For example, if multiple instances of the Web server are to sharethe same Gateway installation. In option 1 each instance of the core Web server process bindsto its own instance of the Gateway.

The configuration procedure is very similar to that described for Option 1. The essential dif-ferences are highlighted below.

Locate the block of core ‘Init’ directives for your Web server as described for Option 1. Theseare in either magnus.conf or obj.conf. Add the following section before the core ‘Init’ block:

Init fn=load-modules shlib=C:/cachesys/csp/bin/CSPcn3.dll \ funcs=cspc_term,cspc_init,cspc_reqInit fn=cspc_init shlib="C:/cachesys/csp/bin/CSPcn3.dll"




2.2.3.1 Directives

Directives for Locating Static Components and the CGI Modules



Add the following lines in the ‘default’ section – that is, after the line shown above.

NameTrans fn="pfx2dir" from="/csp/samples" dir="c:/cachesys/csp/samples"NameTrans fn="pfx2dir" from="/csp/broker" dir="c:/cachesys/csp/broker"

NameTrans fn="pfx2dir" from="/csp-bin" \ dir="c:/cachesys/csp/bin" name="cgi"



<Object ppath="*/*.csp">Service method=(GET|HEAD|POST) fn=csp_req</Object><Object ppath="*/*.cls">Service method=(GET|HEAD|POST) fn=csp_req</Object>














2.3 Apache Servers

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

Pre-built kits are available for Windows which are, generally, a few builds behind the latestApache build. The complete source code to Apache is available for download together withclear instructions for building the server. To build Apache under Windows, you must havethe Microsoft C compiler (Visual C++) version 5.0 (or later).


C:\cachesys\csp\


C:\Program Files\Apache Group\Apache\


Choose one connectivity method from the following sections. The CGI-based approach isthe easiest to get started with. On the other hand, the solutions based on dynamically linkedmodules perform better. It should be noted that the ISAPI-based solution requires the Apacheserver to be rebuilt with a modified version of the ISAPI module (mod_isapi.c).

2.3.1 Installation (All Connectivity Options)



• CSPnsd.exe

• CSPnsdSv.exe


C:\cachesys\csp



Apache Servers

http://www.apache.org

2. CGI and other dynamically linked Modules

Note: The Apache Server API changed significantly between versions 1.3.x and 2.x.Consequently there are separate binaries for each server as shown below.

Common files:





Apache Version 1.3.x:

• mod_csp.dll (Apache ‘built-in’ module as a DLL – if supplied)

• CSPap.dll (Run-time module – if supplied)

• CSPapSys.dll (Gateway Systems Management module – if supplied)

Apache Version 2.x:

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

• CSPa2.dll (Run-time module – if supplied)

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

The default location for these binaries is:

C:\cachesys\csp\bin


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


• CSPBroker.js


• CSPBroker.jar



• CSPxmlhttp.js


C:\cachesys\csp\broker



C:\cachesys\csp\samples

2.3.2 Option 1: Using the Apache API Modules (CSPa*.dll)

This connectivity option is relatively new and offers the best performance as well as beingthe easiest to configure. It is not necessary to start the NSD in order to use this option. Apacheunder Windows is entirely multithreaded and its modules persist in memory from the timeApache is started. These two essential characteristics make it possible to implement theGateway’s functionality as a set of stand-alone modules.

The modules CSPap.dll (Run-time) and CSPapSys.dll (Gateway systems management) aredynamically linked modules that are designed to work the same way as the correspondingMicrosoft ISAPI DLLs. Use modules CSPa2.dll (Run-time) and CSPa2Sys.dll for ApacheVersion 2.x.

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

The Web server configuration file (httpd.conf) are in the following directory:

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

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


Apache Servers

LoadModule cspsys_module_sa c:/cachesys/csp/bin/CSPapSys.dllLoadModule csp_module_sa c:/cachesys/csp/bin/CSPap.dll<Location "/csp/bin/Systems/">SetHandler cspsys-handler-sa</Location><Location "/csp/bin/RunTime/">SetHandler csp-handler-sa</Location>AddHandler csp-handler-sa csp clsAlias /csp/ c:/cachesys/csp/<Directory "c:/cachesys/csp"> AllowOverride None Options MultiViews FollowSymLinks ExecCGI Order allow,deny Allow from all <FilesMatch "\.(log|ini|pid|exe)$"> Deny from all </FilesMatch></Directory>

If you are using Apache Version 2.x then you should specify CSPa2.dll (instead of CSPap.dll)and CSPa2Sys.dll (instead of CSPapSys.dll) in the configuration block shown above.



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

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




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

You should configure the Web server such that it recognizes CSP requests (files of type .cspand .cls) and passes them to the CSP gateway for processing.

The Web server configuration file (httpd.conf) are in the following directory:





<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$"> AllowOverride None Options FollowSymLinks ExecCGI Order allow,deny Allow from all</LocationMatch>ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ \ "c:/cachesys/csp/bin/nph-CSPcgi.exe"Alias /csp/ c:/cachesys/csp/<Directory "c:/cachesys/csp"> AllowOverride None Options MultiViews FollowSymLinks ExecCGI Order allow,deny Allow from all <FilesMatch "\.(log|ini|pid|exe)$"> Deny from all </FilesMatch></Directory>ScriptAlias /csp-bin/ "c:/cachesys/csp/bin/"<Directory "c:/cachesys/csp/bin/"> AllowOverride None Options None Order allow,deny Allow from all <FilesMatch "\.(exe)$"> Allow from all </FilesMatch></Directory>

The above configuration block relies on the Regular Expressions (regex) processor beingavailable to the Apache environment. Sometimes this is not the case (particularly with Win-dows 2000 systems) and CSP files are consequently not served (‘File not found’ errors willbe returned). To remedy this situation, you can associate the (virtual) root location of yourCSP applications with the CGI module instead of making the association through the CSPfile extensions. For example, let’s say your CSP applications are contained under location‘/csp’. To associate the CSP CGI module with files under ‘/csp’, replace the following con-figuration blocks:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$"> AllowOverride None Options FollowSymLinks ExecCGI Order allow,deny Allow from all</LocationMatch>ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "c:/cachesys/csp/bin/nph-CSPcgi.exe"

with

<Location "/csp"> AllowOverride None Options FollowSymLinks ExecCGI Order allow,deny Allow from all</Location>ScriptAlias /csp "c:/cachesys/csp/bin/nph-CSPcgi.exe"

These directives work for URLs of the form:


Apache Servers

http://<ip_address>/csp/*.csp

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

http://<ip_address>/myapps/*.csp

Another approach to avoiding the ‘regex’ issue is to use an ‘Action’ directive in conjunctionwith a CSP MIME type. However, it should be noted that ‘Action’ is essentially a contentfiltering technique and, as such, requires that your CSP files are physically present on theWeb server host even if the Caché server is installed on a separate computer. If you wish touse this approach, first add a new MIME type to the end of the Apache mime.types file andassociate it with file types representing CSP content. The mime.types file are in the samedirectory as the httpd.conf file.

text/csp csp cls

Now, add the ‘Action’ directive to the end of the CGI configuration block in httpd.conf suchthat it reads:

Alias /csp/ c:/cachesys/csp/<Directory "c:/cachesys/csp"> AllowOverride None Options MultiViews FollowSymLinks ExecCGI Order allow,deny Allow from all<Files CSPnsd.exe> Deny from all </Files><Files CSP.ini> Deny from all </Files><Files CSP.log> Deny from all </Files><Files CSPnsd.ini> Deny from all </Files><Files CSPnsd.pid> Deny from all </Files> <FilesMatch "\.(log|ini|pid|exe)$"> Deny from all </FilesMatch></Directory>ScriptAlias /csp-bin/ "c:/cachesys/csp/bin/"<Directory "c:/cachesys/csp/bin/"> AllowOverride None Options None Order allow,deny Allow from all</Directory>Action text/csp “/csp-bin/nph-CSPcgi.exe”

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













2.3.4 Option 3: Using an Apache API Module with the NSD(mod_csp*.dll)

Note: This connectivity option is largely superseded by the stand-alone API modulesdescribed in Option 1.

If the CSP module is supplied with your distribution as a DLL (mod_csp.dll), this provides abetter-performing solution than the CGI-based solution previously described. Use modulemod_csp2.dll for Apache Version 2.x.

Edit the Apache configuration file ‘httpd.conf’. For the standard Apache distribution this fileis in:


Assuming that you wish to invoke the CSP engine for requested files containing the extension.csp and .cls, add the following section to the end of ‘httpd.conf’:


Apache Servers

LoadModule csp_module c:/cachesys/csp/bin/mod_csp.dll<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$"> SetHandler csp-handler</LocationMatch>Alias /csp/ /cachesys/csp/<Directory "c:/cachesys/csp"> AllowOverride None Options MultiViews FollowSymLinks ExecCGI Order allow,deny Allow from all <FilesMatch "\.(log|ini|pid|exe)$"> Deny from all </FilesMatch> <Files CSPnsd> Deny from all </Files></Directory>ScriptAlias /csp-bin/ "c:/cachesys/csp/bin/"<Directory "c:/cachesys/csp/bin/"> AllowOverride None Options None Order allow,deny Allow from all</Directory>

Of course, if you are using Apache Version 2.x then you should specify mod_csp2.dll (insteadof mod_csp.dll) in the configuration block shown above.

The above configuration block relies on the Regular Expressions (regex) processor beingavailable to the Apache environment. Sometimes this is not the case (particularly with Win-dows 2000 systems) and CSP files are consequently not served (‘File not found’ errors arereturned). To remedy this situation, replace the following configuration block:

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

with:

AddHandler csp-handler csp cls






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




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




2.3.5 Option 4: Using the ISAPI Modules (CSPms*.dll)

This connectivity option is superseded by the stand-alone API modules described in Option1 and should not be used. It is documented here as a reference for legacy systems that haveused it in the past.

The Apache Group provide a module that attempts to emulate Microsoft’s ISAPI interface.If Apache is configured to use this module then ISAPI extensions may be run. However, thereare significant differences between the Apache Group’s ISAPI interface and Microsoft’soriginal. The most troublesome feature of the Apache ISAPI module is that it unloads itsISAPI extensions (DLLs) after servicing each and every request. This behavior is unacceptablefor CSP because the CSP Gateway relies on its ISAPI DLLs remaining in memory in orderfor it to manage a persistent pool of connections to Caché.

The modified ISAPI module supplied with CSP allows the CSP Gateway’s ISAPI extensionsto remain loaded between requests. The modifications only affect the Gateway’s ISAPI DLLs;all other ISAPI DLLs are subject to the original Apache Group’s functionality.

2.3.5.1 Rebuilding the Apache Executable

1. Upgrade the Apache ISAPI module (mod_isapi.c)

Overwrite the Apache Group’s ISAPI module with the version contained in the CSPdistribution:

C:\Program Files\Apache Group\Apache\src\os\win32\mod_isapi.c

2. Rebuild the Apache executable

In order to perform this step you need version 5.0 (or later) of the Microsoft C Compiler(Microsoft Visual C++).

Change to the following directory:

C:\Program Files\Apache Group\Apache\src\os\win32\mod_isapi.c


Apache Servers

Build Apache:

nmake /f Makefile.nt installr INSTDIR=d:\progra~1\apache~1\apache

You can safely ignore the many innocuous warning messages that the build process dis-plays.

3. Run-time configuration

Edit the Apache configuration file ‘httpd.conf’. For the standard Apache distribution thisfile is in:


Assuming that you wish to invoke the CSP engine for requested files containing theextension .csp and .cls, add the following section to the end of ‘httpd.conf’:

AddHandler isapi-isa dllAddHandler isapi-isa cspAddHandler isapi-isa clsAlias /csp/ /cachesys/csp/<Directory "c:/cachesys/csp"> AllowOverride None Options MultiViews FollowSymLinks ExecCGI Order allow,deny Allow from all <FilesMatch "\.(log|ini|pid|exe)$"> Deny from all </FilesMatch></Directory>



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






2.4 Operating the Network Service Daemon(NSD)

Use the following procedure to start the NSD:

1. Change to the NSD's home directory:

C:\cachesys\csp

2. Start the NSD:

CSPnsd

Under Windows 95, this service runs interactively in the command window. For otherversions of Windows the NSD starts as a Windows service (CSPnsd.Sv.exe). Once reg-istered as a service, you can manage the NSD entirely through the Windows ServiceManager.

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

• Windows 95:

Type Control-C in the NSD’s command Window.

• Other Windows Systems:

CSPnsd -stop

Alternatively, you can enter:

CSPnsd

This shows the status of the NSD’s Windows Service and allows you to perform one of thefollowing 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 canbe identified in the Service Manager by the description:

Cache Server Pages – Network Service Daemon


Operating the Network Service Daemon (NSD)

All errors are reported in the CSP event log (that is, ‘CSP.log’). This file is created andmaintained in the ‘C:\cachesys\csp’ directory. The CSP configuration file ‘CSP.ini’ alsoresides in this directory.

The NSD also creates the following file:

C:\cachesys\csp\CSPnsd.ini

This file is extremely important because it tells the ‘clients’ how to communicate with theNSD. In this context, the ‘clients’ are the CSP module linked to Apache and the CSP CGImodules invoked by Apache. It is, therefore, essential that this file is not deleted or moved.It is also important that the Apache processes can read this file. Set the privileges accordingly,bearing in mind the Windows user under which your Apache server is operating.



3Web Servers for UNIX, LINUX, andMac OS X

Web Servers from Sun and Apache are described in this section. The original Netscape Webservers (Enterprise and FastTrack), which were, until fairly recently, marketed under thename of ‘iPlanet’, are now developed and marketed by Sun.

Netscape/iPlanet/Sun Web servers can also be extended by means of a high-performanceAPI. The Netscape Application Programming Interface (NSAPI) allows us to extend the Webserver through modules implemented as UNIX Shared Objects (or Shared Libraries).

Several connectivity options are available for Apache. The CGI-based solution is arguablythe easiest option to install and configure. The Apache Group also provide support forextensions implemented as dynamically linked modules (DSOs). Extensions, written asApache modules, can be built directly into the Apache core. However, this latter optionrequires that Apache be rebuilt.

3.1 Netscape, iPlanet, and Sun Web Servers

This section covers the configuration and operational procedures for running CSP throughthe original Netscape Web servers (Enterprise and FastTrack). The modern versions of theseservers were, until fairly recently, marketed under the name of iPlanet, but are now developedand marketed by Sun as the Sun ONE suite of servers. At the time of writing, Sun had furtherrenamed these servers and the Sun ONE Web server is now known as the Sun Java SystemWeb Server.


Traditionally, these Netscape-based servers are produced in two forms: FastTrack andEnterprise. The FastTrack server is a lightweight version of the Enterprise-grade server withlimited functionality and is usually supplied free of charge. The installation and configurationprocedure (with respect to CSP) is the same for both grades of server.

This guide is based on the various CSP Web server components being installed in the followingfile system:

/usr/cachesys/csp/


/usr/netscape/suitespot/ (or /opt/netscape/suitespot/)

For the sake of brevity, the ‘Netscape’ product name is used throughout in the followingdiscussion. However, be aware of the various name changes that have occurred in this productline. For example, the iPlanet server, though essentially the same product as NetscapeEnterprise, is usually installed under:

/usr/iplanet/ (or /opt/iplanet/)

The later versions supplied by Sun are installed under:

/usr/SUNWwbsvr/ (or /opt/SUNWwbsvr/)

Individual instances of the Netscape server are installed under directories of the form:

/usr/netscape/suitespot/https-<server_name>/

or

/usr/netscape/suitespot/httpd-<server_name>/

Where ‘server_name’ is the logical name assigned to the hosting computer.


The documentation root directory for these servers is usually:

/usr/netscape/suitespot/docs/

3.1.1 Installation




Web Servers for UNIX, LINUX, and Mac OS X

CSPnsd

The default location for this module is:

/usr/cachesys/csp


2. NSAPI and CGI Modules

• CSPn3.so (Run-time module)

• CSPn3Sys.so (Systems-management module)

• CSPcn3.so (NSAPI client to the NSD – if supplied)







/usr/cachesys/csp/bin

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


• CSPBroker.js


• CSPBroker.jar

• CSPxmlhttp.js


/usr/cachesys/csp/broker





/usr/cachesys/csp/samples

3.1.2 Option 1: Using the NSAPI Modules (CSPn3*.so)

You should configure the Web server such that it recognizes CSP requests (files of type .cspand .cls) and pass them to the CSP gateway for processing.

The Web server configuration files (magnus.conf and obj.conf) are in the following directory:

/usr/netscape/suitespot/https-<server_name>/config/

You need to add directives to load the NSAPI modules and instructions for recognizing andprocessing CSP files to the Web server configuration.

3.1.2.1 Directives

Directives for Loading the NSAPI Modules

The ‘Init’ directive instructs the Web server to load NSAPI modules. Depending on whichversion of the Web server you have, these directives should be added to either the coremagnus.conf file or the objects obj.conf configuration file. The Netscape Web servers andearly iPlanet servers use the obj.conf for holding ‘Init’ directives, whereas later iPlanet andSun servers use the magnus.conf file. In order to determine which of these two configurationfiles you should use, examine both to see where the Web server’s core ‘Init’ directives areheld. These core configuration directives are always present, an example of which is as follows:

Init fn=load-types mime-types=mime.types

Having located the block of core ‘Init’ directives, add the following section before this block:

Init fn=load-modules shlib=/usr/cachesys/csp/bin/CSPn3.so \ funcs=csp_term,csp_init,csp_reqInit fn=csp_init shlib=”/usr/cachesys/csp/bin/CSPn3.so”Init fn=load-modules shlib=/usr/cachesys/csp/bin/CSPn3Sys.so \ funcs=csp_term_sys,csp_init_sys,csp_req_sysInit fn=csp_init_sys “shlib=/usr/cachesys/csp/bin/CSPn3Sys.so”




Directives for Locating Static Components

CSP includes a number of ‘static’ files that are served by the Web server. For example, theJava/JavaScript files used to implement hyperevents and the image used in the CSP samples.These files are detailed in sections 2 and 3 of the installation section respectively.

The Web server needs to know the location of these files relative to the virtual CSP documen-tation root directory.



Add the following two lines in the ‘default’ section – that is, after the line shown above.

NameTrans fn="pfx2dir" from="/csp/samples" \ dir="/usr/cachesys/csp/samples"NameTrans fn="pfx2dir" from="/csp/broker" \ dir="/usr/cachesys/csp/broker"



<Object ppath="*/*.csp">Service method=(GET|HEAD|POST) fn=csp_req</Object><Object ppath="*/*.cls">Service method=(GET|HEAD|POST) fn=csp_req</Object><Object ppath="*/CSPn3Sys.so">Service method=(GET|HEAD|POST) fn=csp_req_sys</Object><Object ppath="*/CSPn3.so">Service method=(GET|HEAD|POST) fn=csp_req</Object>


The Web server must be restarted after making changes to its configuration files (magnus.conf

and obj.conf).


http://<ip_address>/csp/bin/CSPn3Sys.so






3.1.3 Option 2: Using a NSAPI Module with the NSD (CSPcn3.so)

In most cases, the all-inclusive NSAPI-based solution (Option 1) is the option of choice, andis the implementation that gives the best performance. The NSAPI/NSD hybrid is useful forcases where it is necessary, for operational reasons, to manage the Gateway independentlyof the hosting Web server. For example, if multiple instances of the Web server are to sharethe same Gateway installation. In option 1, each instance of the core Web server processbinds to its own instance of the Gateway.

The configuration procedure is very similar to that described for Option 1. The essential dif-ferences are highlighted below.

Locate the block of core ‘Init’ directives for your Web server as described for Option 1. Theseare found in either magnus.conf or obj.conf. Add the following section before the core ‘Init’block:

Init fn=load-modules shlib=/usr/cachesys/csp/bin/CSPcn3.so \ funcs=cspc_term,cspc_init,cspc_reqInit fn=cspc_init shlib="/usr/cachesys/csp/bin/CSPcn3.so"


3.1.3.1 Directives

Directives for Locating Static Components and the CGI Modules



Add the following lines in the ‘default’ section – that is, after the line shown above.

NameTrans fn="pfx2dir" from="/csp/samples" \ dir="/usr/cachesys/csp/samples"NameTrans fn="pfx2dir" from="/csp/broker" \ dir="/usr/cachesys/csp/broker"

NameTrans fn="pfx2dir" from="/csp-bin" \ dir="/usr/cachesys/csp/bin" name="cgi"



<Object ppath="*/*.csp">Service method=(GET|HEAD|POST) fn=csp_req</Object><Object ppath="*/*.cls">Service method=(GET|HEAD|POST) fn=csp_req</Object>














3.2 Apache Servers

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

Pre-built kits are available for some UNIX systems which are, generally, a few builds behindthe latest version. The complete source code to Apache is available for download togetherwith clear instructions for building the Apache server. The freely available GNU C compiler(gcc) can be obtained for this purpose, though the Apache build procedure attempts to usethe indigenous C compiler.

Many systems are shipped with Apache pre-installed, configured and ready to go. Most dis-tributions of Linux include Apache. IBM distribute Apache with their UNIX offering — AIX.

This guide is based on the various CSP Web server components being installed in the followingfile system:

/usr/cachesys/csp/



Apache Servers

http://www.apache.org

/usr/apache/


Choose one connectivity method from the following sections. The CGI-based approach isthe easiest to get started with. On the other hand, the solutions based on dynamically linkedor built-in modules perform better.

3.2.1 Installation (All Connectivity Options)


1. NSD Module

CSPnsd

The default location for this module is:

/usr/cachesys/csp

The NSD should be run from within its home directory (above). The configuration file(CSP.INI) and Event Log (CSP.LOG) are written in this directory.

2. CGI and other dynamically-linked Modules

• CSPcgi (Run-time module)

• nph-CSPcgi (A copy of CSPcgi)

• CSPcgiSys (Systems-Management module)

• nph-CSPcgiSys (A copy of CSPcgiSys)

• mod_csp.so (Apache Version 1.3.x — Apache module as a DSO, if supplied)

• mod_csp2.so (Apache Version 2.x, Apache module as a DSO, if supplied)

The default location for these binaries is:


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


• CSPBroker.js




• CSPBroker.jar

• CSPxmlhttp.js


/usr/cachesys/csp/broker



/usr/cachesys/csp/samples

3.2.2 Option 1: Using a Dynamic Apache API Module with the NSD(mod_csp*.so)

If the CSP module is supplied with your distribution as a pre-built shared object (mod_csp.so

or mod_csp2.so), then proceed to the section on configuration. To build the shared objectfrom the supplied source file ‘mod_csp.c’ choose Method 1 or Method 2 below. Method 1 ispreferred.

Use module mod_csp2.so for Apache Version 2.x.

Before embarking on this configuration process, be sure to check that your build of Apacheincludes the built-in module for managing shared objects (mod_so). To perform this check,run the following command (this list the modules currently available within Apache):

httpd -l

The Shared Object module (mod_so) should appear in the list of modules displayed.

A typical module listing (with mod_so included) is shown below:


Apache Servers

Compiled in modules: core.c mod_access.c mod_auth.c mod_include.c mod_log_config.c mod_env.c mod_setenvif.c prefork.c http_core.c mod_mime.c mod_status.c mod_autoindex.c mod_asis.c mod_cgi.c mod_negotiation.c mod_dir.c mod_imap.c mod_actions.c mod_userdir.c mod_alias.c mod_so.c

If mod_so is not included in the list for your Apache installation, refer to your Apache docu-mentation and follow the procedure for rebuilding Apache to include this module.

Be sure to read the following instructions regarding the creation of shared objects in conjunc-tion with the specific documentation contained within your Apache distribution. Note thatthe instructions given here assume that the root directory for the Apache installation is‘apache’. In practice, this directory name usually has the Apache version number appendedto it.

The module source file supplied (mod_csp.c) is fully compliant with both Apache v1.3.x andApache v2.x.

3.2.2.1 Method 1: Building the CSP Module as a Shared Object Using the ‘apxs’(APache eXtenSion) Tool

apxs –c mod_csp.c

All being well, this builds the shared library ‘mod_csp.so’.

In order to be consistent with the instructions in this document you may want to rename thismodule as mod_csp2.so for Apache Version 2.x. Alternatively, mod_csp2.so may be builtdirectly as follows:

apxs –c –o mod_csp2.so mod_csp.c

Install the shared-object produced binary in the following directory:




3.2.2.2 Method 2: Building the CSP Module as a Shared Object Manually

Install the module source file ‘mod_csp.c’ in the following directory:

/usr/apache/src/modules/extra

Return to the ‘src’ directory:

/usr/apache/src

Edit the file: ‘Configuration’.

Near the end of this file you should find the line:

# AddModule modules/example/mod_example.o

After this line, add the following line:

ShareModule modules/extra/mod_csp.so

Configure the build process using the following command:

./Configure

Build the shared object using the following command:

make

This should produce the shared object ‘mod_csp.so’ in directory:

/usr/apache/src/modules/extra

In order to be consistent with the instructions in this document you may want to rename thismodule as mod_csp2.so for Apache Version 2.x.

Copy mod_csp.so (or mod_csp2.so) to:


3.2.2.3 Run-time Configuration

Edit the Apache configuration file httpd.conf. For the standard Apache distribution, this fileis in:

/usr/apache/conf

For Red Hat Linux, the run-time version of httpd.conf is in:

/etc/httpd/conf


Apache Servers


LoadModule csp_module /usr/cachesys/csp/bin/mod_csp.so<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$"> SetHandler csp-handler</LocationMatch>Alias /csp/ /usr/cachesys/csp/<Directory "/usr/cachesys/csp"> AllowOverride None Options MultiViews FollowSymLinks ExecCGI Order allow,deny Allow from all <FilesMatch "\.(log|ini|pid|exe)$"> Deny from all </FilesMatch> <Files CSPnsd> Deny from all </Files></Directory>ScriptAlias /csp-bin/ "/usr/cachesys/csp/bin/"<Directory "/usr/cachesys/csp/bin/"> AllowOverride None Options None Order allow,deny Allow from all</Directory>

Of course, if you are using Apache Version 2.x then you should specify mod_csp2.so (insteadof mod_csp.so) in the configuration block shown above.

The above configuration block relies on the Regular Expressions (regex) processor beingavailable to the Apache environment. Sometimes this is not the case and CSP files are conse-quently not served (‘File not found’ errors are returned). To remedy this situation, replacethe following configuration block:


with:

AddHandler csp-handler csp cls

Operating and Managing the Gateway













3.2.3 Option 2: Using the CGI Modules with the NSD (nph-CSPcgi*)

The Web server should be configured such that it recognizes CSP requests (files of type .cspand .cls) and pass them to the CSP gateway for processing.

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

/usr/apache/conf

For Red Hat Linux, the run-time version of ‘httpd.conf’ is found in:

/etc/httpd/conf



Apache Servers

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$"> AllowOverride None Options FollowSymLinks ExecCGI Order allow,deny Allow from all</LocationMatch>ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ \ "/usr/cachesys/csp/bin/nph-CSPcgi"Alias /csp/ /usr/cachesys/csp/<Directory "/usr/cachesys/csp"> AllowOverride None Options MultiViews FollowSymLinks ExecCGI Order allow,deny Allow from all <FilesMatch "\.(log|ini|pid|exe)$"> Deny from all </FilesMatch> <Files CSPnsd> Deny from all </Files></Directory>ScriptAlias /csp-bin/ "/usr/cachesys/csp/bin/"<Directory "/usr/cachesys/csp/bin/"> AllowOverride None Options None Order allow,deny Allow from all</Directory>

The above configuration block relies on the Regular Expressions (regex) processor beingavailable to the Apache environment. Sometimes this is not the case and CSP files are conse-quently not served (‘File not found’ errors are returned). To remedy this situation you canassociate the (virtual) root location of your CSP applications with the CGI module insteadof making the association through the CSP file extensions. For example, let’s say your CSPapplications are contained under location ‘/csp’. To associate the CSP CGI module with filesunder ‘/csp’, replace the following configuration blocks:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$"> AllowOverride None Options FollowSymLinks ExecCGI Order allow,deny Allow from all</LocationMatch>ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ \ "/usr/cachesys/csp/bin/nph-CSPcgi"

with:

<Location "/csp"> AllowOverride None Options FollowSymLinks ExecCGI Order allow,deny Allow from all</LocationMatch>ScriptAlias /csp "/usr/cachesys/csp/bin/nph-CSPcgi"

These directives work for URLs of the form:

http://<ip_address>/csp/*.csp



Duplicate the configuration block for other root Locations. For example, repeat the processfor ‘/myapps’ for URLs of the form:

http://<ip_address>/myapps/*.csp

Another approach to avoiding the ‘regex’ issue is to use an ‘Action’ directive in conjunctionwith a CSP MIME type. However, it should be noted that ‘Action’ is essentially a contentfiltering technique and, as such, requires that your CSP files are physically present on theWeb server host even if the Caché server is installed on a separate computer. If you wish touse this approach, first add a new MIME type to the end of the Apache mime.types file andassociate it with file types representing CSP content. The mime.types file are found in thesame directory as the httpd.conf file.

text/csp csp cls

Now, add the ‘Action’ directive to the end of the CGI configuration block in httpd.conf suchthat it reads:

Alias /csp/ /usr/cachesys/csp/<Directory "/usr/cachesys/csp"> AllowOverride None Options MultiViews FollowSymLinks ExecCGI Order allow,deny Allow from all<Files CSPnsd> Deny from all </Files><Files CSP.ini> Deny from all </Files><Files CSP.log> Deny from all </Files><Files CSPnsd.ini> Deny from all </Files><Files CSPnsd.pid> Deny from all </Files></Directory>ScriptAlias /csp-bin/ "/usr/cachesys/csp/bin/"<Directory "/usr/cachesys/csp/bin/"> AllowOverride None Options None Order allow,deny Allow from all</Directory>Action text/csp “/csp-bin/nph-CSPcgi”

Finally, note that because CGI is an open standard, The CSP CGI modules work with anyWeb server.


Apache Servers











3.2.4 Option 3: Using a Built-in Apache API Module with the NSD(mod_csp.c)

Be sure to read these instructions in conjunction with the specific documentation containedwithin your Apache distribution. Note that the instructions given here assume that the rootdirectory for the Apache installation is ‘apache’. In practice, this directory name usually hasthe apache version number appended to it.

3.2.4.1 Adding the CSP Module Source Code to the Apache Source Directory

The code for user-defined modules resides under the following directory:

/usr/apache/src/modules

Create the following directory for the CSP module:

/usr/apache/src/modules/csp

While in the ‘/usr/apache/src/modules’ directory type

mkdir csp

Copy the source for the CSP module (mod_csp.c) into this directory. You should now have:

/usr/apache/src/modules/csp/mod_csp.c



3.2.4.2 Creating a ‘Makefile’ for the CSP Module

The next task is to create a ‘Makefile’. The Makefile contains instructions on how the CSPmodule should be compiled and linked. Apache always provides an example module – makea copy of the example’s Makefile and modify it for CSP.

Make sure you are in the ‘csp’ directory:

/usr/apache/src/modules/csp

Copy the example Makefile by typing:

cp ../example/Makefile* ./

Depending on the version of Apache you have, one of the following files will be in the ‘CSP’directory:

• Makefile — Apache 1.2.x series.

• Makefile.tmpl — Makefile template, Apache 1.3.x series.

Edit whichever file you have and replace all references to ‘mod_example’ with ‘mod_csp’.

3.2.4.3 Configuring the Apache Build Process to Recognize the CSP Module

1. Return to the ‘src’ directory:

/usr/apache/src

2. Edit the file: ‘Configuration’.

• For Apache 1.2.x:


# Module example_module modules/example/mod_example.o


Module CSP_module modules/csp/mod_csp.o

• For Apache 1.3.x:


# AddModule modules/example/mod_example.o


AddModule modules/csp/mod_csp.o


Apache Servers

3.2.4.4 Run the ‘Configure’ Script to Build the Main ‘Makefile’

We can now configure the build process. Make sure you are in the ‘src’ directory:

/usr/apache/src

Enter the following command:

./Configure

3.2.4.5 Before Building Apache – A Special Note for Users of Red Hat Linux

Red Hat Linux is distributed with a pre-built version of Apache. If you install Apache as partof the Linux installation procedure, Apache is automatically started when Linux is booted.The layout of the run-time file system for this pre-built version is slightly different to thatwhich is prescribed as the default layout in the Apache source code. In order to account forthis, the following change should be made to the Apache C header file ‘httpd.h’:

For Apache 1.2.x:

/usr/apache/src/httpd.h

For Apache 1.3.x:

/usr/apache/src/include/httpd.h

The Web server root (HTTPD_ROOT) is one of the first items defined in this file. For RedHat Linux this symbol should be defined as follows:

#define HTTPD_ROOT “/etc/httpd”

3.2.4.6 Build the Apache Executable

Next, build the Apache executable. Make sure you are in the ‘src’ directory:

/usr/apache/src

Enter the following command:

make

This should produce a new Web server executable (httpd) with the CSP module’s functionalitybuilt-in.

Run the following command to check that the CSP module has been successfully includedin the Apache core (this command lists all modules currently built into Apache):

./httpd -l



For example:

Compiled in modules: core.c mod_access.c mod_auth.c mod_include.c mod_log_config.c mod_env.c mod_setenvif.c prefork.c http_core.c mod_mime.c mod_status.c mod_autoindex.c mod_asis.c mod_cgi.c mod_negotiation.c mod_dir.c mod_imap.c mod_actions.c mod_userdir.c mod_alias.c mod_csp.c

The httpd executable is created in the ‘src’ directory. For normal operation, copy this to the‘apache’ directory (and run it there).

For Red Hat Linux, the executable ‘httpd’ should be copied to:

/usr/sbin

Be sure to backup the existing copy first.

3.2.4.7 Run-time Configuration

Edit the Apache configuration file ‘httpd.conf’. For the standard Apache distribution this fileis in:

/usr/apache/conf

For Red Hat Linux, the run-time version of ‘httpd.conf’ is in:

/etc/httpd/conf



Apache Servers

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$"> SetHandler csp-handler</LocationMatch>Alias /csp/ /usr/cachesys/csp/<Directory "/usr/cachesys/csp"> AllowOverride None Options MultiViews FollowSymLinks ExecCGI Order allow,deny Allow from all <FilesMatch "\.(log|ini|pid|exe)$"> Deny from all </FilesMatch> <Files CSPnsd> Deny from all </Files></Directory>ScriptAlias /csp-bin/ "/usr/cachesys/csp/bin/"<Directory "/usr/cachesys/csp/bin/"> AllowOverride None Options None Order allow,deny Allow from all</Directory>

The above configuration block relies on the Regular Expressions (regex) processor beingavailable to the Apache environment. Sometimes this is not the case and CSP files are conse-quently not served (‘File not found’ errors are returned). To remedy this situation, replacethe following configuration block:


with:

AddHandler csp-handler

Note that all requests to Apache are serviced by a set of modules invoked in a pre-definedsequence. The CSP module is one of the first modules invoked, provided its definition wasadded near the end of the 'Configuration' file as suggested.






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








3.3 Operating the Network Service Daemon(NSD)

First, change to the following directory:

/usr/cachesys/csp

Use the following command to start the NSD:

./CSPnsd

Before retiring to the background, the NSD displays a banner indicating its running configu-ration. It shows the TCP port number dedicated to this service, which is, by default, portnumber 7038. You can override this by starting the service as follows:

./CSPnsd <port_no>

where port_no is the TCP port number of your choice.

You can suppress all startup messages for this command using the ‘-s’ qualifier. For example,if you wish to ‘silently’ start the NSD from a script invoked when the system is booted use:

/usr/cachesys/csp/CSPnsd –s [port_no]

Use the following command to close down the NSD:

./CSPnsd -stop

Alternatively:

kill –TERM `cat /usr/cachesys/csp/CSPnsd.pid`


Operating the Network Service Daemon (NSD)

These commands close down the NSD in an orderly manner – it gracefully terminates allopen connections to Caché and releases all its system resources before terminating. Do notuse the ‘kill –9’ command to terminate the NSD.

All errors are reported in the Event Log (‘CSP.log’). This file is created and maintained inthe ‘/usr/cachesys/csp’ directory. The configuration file ‘CSP.ini’ also resides in this directory.

The NSD also creates the following file:

/usr/cachesys/csp/CSPnsd.ini

This file is extremely important because it tells the ‘clients’ how to communicate with theNSD. In this context, the ‘clients’ are the CSP module contained within, or dynamicallylinked to, Apache and the CSP CGI modules invoked by Apache. It is, therefore, essentialthat this file is not deleted or moved. It is also important that the Apache processes can readthis file. Set the privileges accordingly, bearing in mind the UNIX user under which yourApache server is operating.



4General Web Server ConfigurationIssues

4.1 A Note on the CGI Modules Supplied

Typically, most CSP installations take advantage of the high-performing proprietary APIsthat are supported by the hosting Web server. However, some connectivity options involvethe use of small CGI executable, at least, for the purpose of running the CSP Gateway’ssystems management suite. The notes in this section apply to all Operating System and WebServer combinations.

Note that two series of CGI modules are supplied – those prefixed with ‘nph-‘ and those thatare not. These modules are, in fact, the same, irrespective of whether or not they have the‘nph-‘ prefix. The ‘nph’ prefix is the CGI convention for instructing the Web server not toparse the HTTP headers (that is, non-parsed-headers). The Web server simply forwards yourheaders on to the browser. In the context of a URL, the ‘nph-‘ prefix must always be expressedin lower-case.

CSP and CSP-based applications usually assume the responsibility for sending a full HTTPheader. Under CGI, the first line of the header (the request status line) has traditionally beenthe responsibility of the server-side of the CGI interface. Some Web servers are strict aboutthis – Apache is one such example. Apache expects the first header line sent by your applica-tion to be the ‘Content-type’ line and not the request status line (such as HTTP/1.1 200 OK)– it returns an error if it parses the header and doesn’t detect a ‘Content-type’ line first. Usingthe ‘nph’ version of the CGI module alleviates this problem. Not all Web servers are so strict


about this convention. For example, Microsoft’s Web servers do not object to receiving a fullHTTP header from a CGI executable not prefixed with ‘nph’ (for example: CSPcgi.exe).

4.2 Security Issues in Accessing the Gateway’sSystems Management

By default, only clients local to the Gateway’s hosting computer are allowed access to theSystems Management suite. For example:

http://localhost/csp/bin/CSPmsSys.dll

or:

http://127.0.0.1/csp/bin/CSPmsSys.dll

This effectively means that the browser through which the administration forms are accessedmust be running on the same machine as the Web server and CSP Gateway.

You can add additional clients to the list of authorized administrators by adding the client IPaddresses to the System_Manager parameter in CSP.ini. This parameter is held in the SYSTEMsection. For example:

[SYSTEM]System_Manager=190.8.7.6,190.8.7.5,190.8.7.4

This parameter represents a comma (or ‘+’) separated list of clients (by IP address) who mayaccess the Gateway's system management and configuration forms. The directive shownabove would grant access to three remote clients in addition to the default local access.

For new Gateway installations, for which there is no local browser available, it is necessaryto manually create this configuration setting.

The System_Manager parameter is equivalent to the Systems Manager Machines settingwhich is found under the default parameters section of the Gateway’s management suite.

Gateway Build 662.698 (and higher) allows wildcard and numeric ranges to be specified inthe entries for the Systems Manager Machines parameter.

For example:

[SYSTEM]System_Manager=190.8.7.4-6


General Web Server Configuration Issues

This indicates that the last part of the IP address can take the value of a number between 4and 6 inclusive. In other words, it is a more convenient way of writing:

[SYSTEM]System_Manager=190.8.7.6,190.8.7.5,190.8.7.4

Wildcards can also be used. For example:

[SYSTEM]System_Manager=190.8.7.*

The following directive grants access to all clients:

[SYSTEM]System_Manager=*.*.*.*

However, it is not recommended that such a directive be used on operational systems.

It should be recognized that there are shortcomings in using this scheme as a way of protectingthe Gateway's management suite.

• This scheme is not able to provide strong security. For the purpose of checking Webclients, the IP address of a client is obtained from the CGI environment variableREMOTE_ADDR. Client IP addresses can be spoofed.

• The use of a proxy between the client and the Web server/gateway installation effectivelytranslates all client IP addresses to that of the proxy. In this scenario you would have toeither specify the proxy's IP address as a Gateway Systems Manager (which wouldeffectively grant access to all Web users coming in through the proxy) or, preferably,enable the designated systems managers to bypass the proxy layer altogether.

The IP-based scheme, while useful as a first line of defense, should not be relied upon as thesole means through which access to the Gateway management suite is controlled – certainlynot for CSP installations that are available over the Internet. For production systems it isrecommended that the hosting Web server's configuration controls access to the Gateway'ssystems management modules.

4.3 Making a CSP Page the Default Page (or‘Homepage’) for the Web Server

This section describes the configuration changes that are necessary to allow a CSP page tobe served as the Web server’s default page (or homepage). As an example, the procedure for


Making a CSP Page the Default Page (or ‘Homepage’) for the Web Server

making the CSP samples menu (/csp/samples/menu.csp) the server’s default page is outlined.The Web server’s default page is accessed via:

http://<web_server>/

When a CSP page is served in this way it should be noted that embedded URLs must bespecified in full. If relative URLs are used for embedded hyperlinks, the browser interpretsthese as relative to the documentation root directory and not the CSP root. For example, takingour samples menu as the homepage, the URL to, say, the inspector option should be:

http://<web_server>/csp/samples/inspector.csp

If relative URLs are used, then the browser incorrectly interprets this link as:

http://<web_server>/inspector.csp

4.3.1 Peer Web Server

1. Open the Internet Service Manager window.

2. Double-click on the WWW Service to bring up the WWW Service Properties window.

3. Click on the Directories tab.

4. Replace the Default Document with /csp/samples/menu.csp.

5. Ensure that the Enable Default Document checkbox is ticked.

6. Save and Apply all changes.

7. The new default page (/csp/samples/menu.csp) must physically exist relative to the Webserver’s documentation root directory. It is only necessary to create an empty file. Forexample, if your document’s root is c:\inetpub\wwwroot proceed as follows:

cd c:\inetpub\wwwrootmd cspcd cspmd samplescd samplescopy con menu.csp^Z

4.3.2 Internet Information Services





3. Right-click on the Default Web Site. Select Properties from the menu to bring up theDefault Web Site Properties window.

4. Click on the Directory tab.

5. Click the Add button to bring up the Add Default Document Name window.

6. Enter the document name (/csp/samples/menu.csp) for the Default Document Name win-dow.

7. Click on the OK button.

8. Ensure that the Enable Default Document checkbox is ticked.

9. In the Directories tab, use the arrow keys to move the new default document (/csp/sam-ples/menu.csp ) to the top of the list.

10. Click Apply and OK to save and activate all changes.

11. The new default page (/csp/samples/menu.csp) must physically exist relative to the Webserver’s documentation root directory. It is only necessary to create an empty file. Forexample, if your document’s root is c:\inetpub\wwwroot proceed as follows:

cd c:\inetpub\wwwrootmd cspcd cspmd samplescd samplescopy con menu.csp^Z

4.3.3 Netscape, iPlanet, and Sun Web Servers

The procedure described in this section is only available with Gateway build 663.763 (andlater).

The following directive specifies the homepage for a Netscape server in the default sectionof obj.conf:

NameTrans fn="home-page" path="/csp/samples/menu.csp"

This directive, however, does not result in the CSP form menu.csp becoming the home pagefor the server. The reason for this is that the server does not update the environment variablesrelating to the page requested before transferring control to the CSP Gateway. The Gatewaysees the incoming request as a request for / instead of /csp/samples/menu.csp. Netscape-basedservers expect NSAPI extensions to accept the responsibility for recognizing this scenarioand update the variables identifying the page requested and its path accordingly. You canwork around this behavior as follows:


Making a CSP Page the Default Page (or ‘Homepage’) for the Web Server

• Define the CSP homepage in the default section of obj.conf:

NameTrans fn="home-page" path="/csp/samples/menu.csp"

• The section that describes the mapping between CSP files and the Gateway modules mustbe modified to include the home-page-path directive as follows:

<Object ppath="*/*.[Cc][Ss][Pp]">Service method=(GET|HEAD|POST) fn=csp_req \home-page-path="/usr/cachesys/csp/samples" </Object> <Object ppath="*/*.[Cc][Ll][Ss]">Service method=(GET|HEAD|POST) fn=csp_req \home-page-path="/usr/cachesys/csp/samples" </Object> <Object ppath="*/CSPn3Sys.so">Service method=(GET|HEAD|POST) fn=csp_req_sys</Object> <Object ppath="*/CSPn3.so">Service method=(GET|HEAD|POST) fn=csp_req</Object>

It is not entirely necessary to specify the path to the home page in the home-page-path propertywithin the Service directive, but if you do, it results in the PATH_TRANSLATED environmentvariable taking the value that it would have done had /csp/samples/menu.csp been requesteddirectly. In other words, PATH_TRANSLATED for the home-page (/) is returned as:

/cachesys/csp/samples/inspector.csp

instead of:

/csp/samples/inspector.csp

4.4 Apache Servers

Find the DirectoryIndex directive in the Apache configuration file. For example:

DirectoryIndex index.html index.html.var

Add the new default page for the Web server at the head of the list:

DirectoryIndex /csp/samples/menu.csp index.html index.html.var



Installing and Configuring the CSP Gateway

Documents

Transcript of Installing and Configuring the CSP Gateway