CSP Gateway Configuration Guide
Web Servers for OpenVMS
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

If you are running Caché on OpenVMS, you can use web servers from Apache or HP. The HP Secure Web Server (SWS) is, in fact, based on the Apache server; the main difference is that the modules for supporting secure SSL-based communication are included in the prebuilt HP product.

The supported version of Secure Web Server is as follows:
The configuration procedures described here are based on the standard layout and configuration for the Apache and SWS servers operating under OpenVMS.
Apache is usually installed in the directory represented by:
APACHE$COMMON
Note:
Note for OpenVMS Clusters
All of the web server's files reside under its root directories pointed to by the APACHE$ROOT logical name. During installation, file protection is set to (S:RWED, O:RWED, G, W). During configuration, all files are set to be owned by the APACHE$WWW account. The APACHE$ROOT logical name is used for the examples in this section. For multi-server clustered environments it may be more appropriate to use the APACHE$COMMON logical name since this defines cluster-wide files in APACHE$ROOT. For single-server installations, these two OpenVMS logicals are equivalent.
The name APACHE$ROOT is a OpenVMS search logical representing APACHE$SPECIFIC and APACHE$COMMON. The essential support files for the CSP Gateway (CSPNSD) are not stored in APACHE$SPECIFIC. Therefore, the CSPNSD component will not start in APACHE$SPECIFIC:[CSPGW.BIN] or APACHE$ROOT:[CSPGW.BIN]
The CSPNSD component must be installed started in APACHE$COMMON:[CSPGW.BIN].
Installation on OpenVMS (All Connectivity Options)
First follow the directions in this section, then follow the directions in either Recommended Option: OpenVMS and Apache API Module with NSD (MOD_CSP.EXE) or Alternative Option 1: OpenVMS and CGI Modules with NSD (CSPCGI.EXE).
Install the CSP Gateway components in the Apache directory tree (unlike either Windows or UNIX® described previously in the this book). The privileges of the OpenVMS user account under which Apache runs (usually APACHE$WWW) are usually very restrictive. Including the Gateway components within the Apache directory tree avoids the need to assign additional privileges to Apache (or reduce the level of protection defined for the Caché directory tree).
Install the CSP Gateway components and the CSP static files as follows:
  1. NSD Module
    The default location for this image is:
    The NSD should be run from within this directory (its home directory). The configuration file (CSP.INI) and Event Log (CSP.LOG) are written in this directory.
  2. Apache module (for recommended option in Recommended Option: OpenVMS and Apache API with NSD (MOD_CSP.EXE))
    The default location for these images is:
    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.
  3. HyperEvents Components
    The default location for these files is:
  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:
  5. Miscellaneous static resources used by the Caché Management Portal
    A number of static web resources (such as image files) are required by the System .Management Portal. The default location for these files is:
    If you are performing a manual installation and the files listed above are contained within the Caché directory tree, they can be conveniently copied to their final destination using the following command:
    Note:
    Note for OpenVMS Clusters If SWS/Apache is operating in a clustered environment then the directory APACHE$SPECIFIC:[CSP] must be created for all cluster nodes.
Recommended Option: OpenVMS and Apache API with NSD (MOD_CSP.EXE)
If the CSP module is supplied with your distribution as an OpenVMS shareable image (MOD_CSP.EXE), this provides a better-performing solution than the CGI-based solution described elsewhere. Use shareable image MOD_CSP22.EXE for SWS 2.2 /Apache Version 2.0.63 and later.
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.
The web server configuration file (HTTPD.CONF) is found in the following directory:
APACHE$COMMON:[CONF]
Add the following section to the end of HTTPD.CONF.
LoadModule csp_module /apache$common/csp/bin/mod_csp22.exe
CSPFileTypes csp cls zen
<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None 
    Options FollowSymLinks ExecCGI
    Order allow,deny 
    Allow from all
</LocationMatch>
Alias /csp/ /apache$common/csp/
<Directory "/apache$common/csp"> 
    AllowOverride None 
    Options MultiViews FollowSymLinks ExecCGI 
    Order allow,deny 
    Allow from all 
    <FilesMatch "\.(log|ini|pid|exe)$"> 
        Deny from all 
    </FilesMatch>
</Directory>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/apache$common/csp/bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/apache$common/csp/bin/nph-CSPcgi"
ScriptAlias /csp-bin/ "/apache$common/csp/bin/"
<Directory "/apache$common/csp/bin/">
    AllowOverride None 
    Options None 
    Order allow,deny 
    Allow from all
</Directory>
Restart SWS/Apache after making these changes to the configuration file.
Registering Additional File Types with CSP
Apache API modules always recognize the following reserved file extensions:
.csp .cls .zen .cxw 
You may have other files that you want to send to CSP for processing. For example, if you need to serve other static files through the CSP Gateway or need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, and .js.
You can configure Apache to recognize what files to pass on to CSP in any of the following ways:
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
</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 /apache$common/csp/bin/mod_csp22.exe
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 OpenVMS 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 (NSD).
  2. Restart SWS/Apache after making changes to its configuration file (HTTPD.CONF).
    The order in which SWS/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_CSP*.EXE), the CSP Web Gateway Management page is accessed through the CGI module dedicated to this purpose (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 OpenVMS
The requirement that the CSP components be installed within the Apache directory structure for this server has been discussed in previous sections. Occasionally it is necessary to install the CSP Gateway components in the appropriate pre-configured Apache directories in order to avoid HTTP 403 Forbidden error codes being returned on attempting to access CSP resources. If this is the case for your installation then proceed as follows:
  1. Copy CGI modules to: APACHE$COMMON:[cgi-bin]
  2. Copy API modules to: APACHE$COMMON:[modules]
  3. Copy static files and subdirectories in these directories to locations under: APACHE$COMMON:[htdocs]
  4. The NSD component can be installed in: APACHE$COMMON:[CSPGW.BIN]
Using the preconfigured directories in Apache simplifies the CSP Gateway configuration in HTTPD.CONF. Modified configuration blocks are shown below.
Configuration for the Recommended Option: Dynamic Apache API Module with NSD (mod_csp.exe)
LoadModule csp_module /apache$common/modules/mod_csp.exe
CSPFiletypes csp cls
<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None 
    Options FollowSymLinks ExecCGI
    Order allow,deny 
    Allow from all
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/apache$common/cgi-bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/apache$common/cgi-bin/nph-CSPcgi"
Configuration for Alternative Option 1: CGI Modules with NSD (nph-CSPcgi.exe)
<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Order allow,deny
    Allow from all
</LocationMatch>
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "/apache$common/cgi-bin/nph-CSPcgi"
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/apache$common/cgi-bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/apache$common/cgi-bin/nph-CSPcgi"
Operating the Network Service Daemon (NSD)
Use the following procedure to start the NSD:
  1. Change to the NSD's home directory:
  2. Start the NSD as a background process:
If this process starts successfully, the NSD's startup banner is written to the file: CSPNSD.LOG.
Use the following procedure to stop the NSD:
  1. Change to the NSD's home directory:
  2. Stop the NSD using the command:
This command closes down the NSD in an orderly manner – it gracefully terminates all open connections to Caché and releases all its system resources before terminating. Do not use a plain stop command to terminate the NSD.
All errors are reported in the Event Log (CSP.LOG). OpenVMS System Errors are reported in CSPNSD.LOG. These files are created and maintained in the NSD’s home directory. The configuration file CSP.INI also resides in this directory.
Starting the NSD on Alternative TCP port
By default, the NSD listens for incoming requests on TCP port 7038. You can override this by creating and specifying alternative parameters in the CSPNSD.INI file. The format of this file is as follows and must be installed in the NSDs home directory.
[SYSTEM]
Ip_Address=127.0.0.1
TCP_Port=7038
It is necessary to communicate the value of the following parameters to the Apache modules so that they know how to access the NSD. To do this, set the following environment variables in the Apache configuration to indicate the address and port of the target NSD installation.
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.
If you want to run multiple instances of the NSD, you must install separate instances in separate directories, each maintaining its own copy of the configuration and log files (CSPNSD.INI, CSP.INI and CSP.LOG). The CSP Web Gateway Management page for each instance can easily be accessed by using the NSD’s internal HTTP server. For example:
http://localhost:7038/csp/bin/Systems/Module.cxw
http://localhost:7039/csp/bin/Systems/Module.cxw