CSP Gateway Configuration Guide
Web Servers for UNIX®, Linux, and Mac OS X
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Web Servers from Apache and Sun are described in this section.

Several connectivity options are available for Apache. The Apache Group provides support for extensions implemented as dynamically linked modules (DSOs). Extensions, written as Apache modules, can be built directly into the Apache core. This is the recommended option. Other, atypical, configuration options are in the appendix Alternative Configurations for UNIX®, Linux, and Mac OS X
Sun web servers can be extended using a high-performance API. You can use the Netscape Application Programming Interface (NSAPI) to extend the web server through modules implemented as UNIX® Shared Objects (or Shared Libraries).
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 some UNIX® systems which are, generally, a few builds behind the latest version. The complete source code to Apache is available for download together with 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 use the indigenous C compiler.
Many systems are shipped with Apache pre-installed, configured and ready to go. Most distributions of Linux include Apache. IBM distributes Apache with their UNIX® implementation: AIX®.
Note:
The build of apache that IBM supplies with AIX is not compatible with the recommended Apache API modules. Follow the instructions in the appendix Building Apache for IBM AIX to build a compatible version of Apache on AIX. The configurations using NSD do not require this step. For more information, see the appendix Alternative Configurations for UNIX®, Linux, and Mac OS X.
This guide refers to the directory that CSP Gateway components are installed in as:
/opt/cspgateway/csp/
This guide refers to the directory that Apache is installed in as the following; your Apache install directory may be different.
/usr/apache/
If the layout is different on your system, be sure to amend the configuration directives described in the following sections, as appropriate.
This section describes the recommended option for installing the CSP Gateway.
  1. Everyone should follow the directions in the section Install Locations with Apache Servers on UNIX (All Options).
  2. Then follow the directions in the section Recommended Option: Apache API Module without NSD (CSPa.so). Or, if you are using an atypical option, see the appendix Alternative Configurations for UNIX, Linux, and Mac OS.
Install Locations Apache UNIX®, Linux, Mac OS (Recommended Option)
This section describes directory locations for CSP Gateway files and CSP static files.
  1. Dynamically-linked modules:
    In order to avoid disrupting existing Gateway installations on upgrading Caché, the installation procedures place these modules in the following common location. This location is not related to a particular Caché instance.
    /opt/cspgateway/bin
    The original location (/cache-install-dir/csp/bin) is used to hold the Gateway components required for serving the Management Portal for the specific instance of Caché.
    The modules with Sys appended access the CSP Web Gateway Management page. The runtime modules (that is, those without Sys) have no access to the CSP Web Gateway Management pages.
  2. HyperEvents Components
    The default location for these files is:
    /cache-install-dir/csp/broker
  3. Miscellaneous static resources used by the CSP Samples
    A number of static web resources (such as image files) are required by the CSP Samples. The default location for these files is:
    /cache-install-dir/csp/samples
  4. Miscellaneous static resources used by the Caché Management Portal.
    A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is:
    /cache-install-dir/csp/sys
Requirements for using Apache API Modules (Recommended Option and Alternative Option 1)
Before following instructions for either Recommended Option and Alternative Option 1, check that your build of Apache includes the built-in module for managing shared objects (mod_so). To perform this check, run the following command which lists the modules currently available within Apache:
httpd -l
The shared object module (mod_so) should appear in the list of modules displayed. The following shows a typical module listing (with mod_so included):
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 documentation and follow the procedure for rebuilding Apache to include this module.
Recommended Option: Apache API Module without NSD (CSPa24.so)
This option is used in the configuration of the Private Web Server in the Management Portal.
This connectivity option offers the best performance as well as being the easiest to configure.
Before using this option you should bear in mind that Apache v2.x..x is partially multithreaded, implemented as a hybrid multi-process and multithreaded server. In practice, this means that there is one instance of the CSP Gateway per Apache child process. This is not a problem in itself but this architecture makes it difficult to control the number of connections to Caché (and Caché processes) used by the Gateway since each instance of the Gateway independently manages its own pool of Caché connections.
State-aware connectivity (preserve mode 1) should not be used with these modules.
The modules CSPa24.so (Runtime) and CSPa24Sys.so (Gateway systems management) are dynamically linked modules (DSOs).
Configure the web server to recognize CSP requests (files of type .csp, .cls, and .zen) and pass them to the CSP Gateway module for processing.
The web server configuration file (httpd.conf) is in the following directory:
/usr/apache/conf
For Red Hat Linux, the runtime version of httpd.conf is found in:
/etc/httpd/conf
For Suse, the runtime version of httpd.conf is found in:
/etc/apache2/conf
  1. Apache 2.4.x: Add the section below to the end of httpd.conf.
    LoadModule csp_module_sa /opt/cspgateway/bin/CSPa24.so
    CSPModulePath /opt/cspgateway/bin/
    <Location "/csp/bin/Systems/">
    SetHandler cspsys-handler-sa
    </Location>
    <Location "/csp/bin/RunTime/">
    SetHandler csp-handler-sa
    </Location>
    CSPFileTypes csp cls zen cxw 
    Alias /csp/ /opt/cspgateway/csp/
    <Directory "/opt/cspgateway/csp">
             AllowOverride None
             Options MultiViews FollowSymLinks ExecCGI
             Require all granted
             <FilesMatch "\.(log|ini|pid|exe)$">
             Require all denied 
             </FilesMatch>
    </Directory>
    Apache 2.2.x: Add the section below to the end of httpd.conf.
    LoadModule csp_module_sa /opt/cspgateway/bin/CSPa22.so
    CSPModulePath /opt/cspgateway/bin/
    <Location "/csp/bin/Systems/">
    SetHandler cspsys-handler-sa
    </Location>
    <Location "/csp/bin/RunTime/">
    SetHandler csp-handler-sa
    </Location>
    CSPFileTypes csp cls zen cxw 
    Alias /csp/ /opt/cspgateway/csp/
    <Directory "/opt/cspgateway/csp">
             AllowOverride None
             Options MultiViews FollowSymLinks ExecCGI
             Order allow,deny
             Allow from all
             <FilesMatch "\.(log|ini|pid|exe)$">
             Deny from all
             </FilesMatch>
    </Directory>
    Apache 2.0.x: Add the section above using CSPa2.dll to the end of httpd.conf
  2. Restart Apache after making changes to httpd.conf.
Registering Additional File Types with CSP
Apache API modules always recognize the following reserved file extensions:
.csp .cls .zen .cxw 
You may have other files that you want to send to CSP for processing. For example, if you need to serve other static files through the CSP Gateway or need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js.
You can configure Apache to recognize what files to pass on to CSP in any of the following ways:
By CSPlocation directive
Use the CSP directive to request that all files within a certain location be processed by CSP. The following requests that all files and directories under the /csp path be processed by CSP.
<Location /csp>
   CSP On 
   SetHandler csp-handler-sa
</Location> 
For example, all the following would be sent to CSP for processing:
/csp/ 
csp/samples/menu.csp 
csp/sys/ 
By file extension — CSPFileTypes directive
The CSPFileTypes directive works for requests for files that have extensions (such /csp/menu.csp). It does not work for requests for files that do not have file extensions (such as/csp/menu).
This parameter is processed by the Gateway’s Apache modules and can be globally defined at the server definition level (in httpd.conf) or restricted within the definition for a location or directory block.
By file type: The following directive requests that files of type xxx and yyy be processed by CSP.
CSPFileTypes xxx yyy 
By location: The following requests that files of type xxx and yyy be processed by CSP but only for locations under /csp (including subdirectories, such as /csp/samples and so on).
<Location /csp/> 
   CSPFileTypes xxx yyy
</Location>
Using the wildcard character, the following requests that all files under path /csp (and /csp/samples and so on) be processed by CSP.
<Location /csp/> 
   CSPFileTypes * 
</Location> 
By MIME type
In addition to recognizing the file extensions listed above, CSP can also recognize files for the following MIME types:
application/x-csp
and
text/csp
For example, to add the file extension xxx to the list of files processed by CSP, use:
LoadModule csp_module_sa /opt/cspgateway/bin/CSPa22.so
AddType application/x-csp csp cls zen xxx
One of the problems with using MIME types to associate types of file with CSP is that Apache checks to ensure that the path to the resource (that is, the hosting directory) physically exists, and returns a file not found error if it does not. It does not, however, check to ensure that the file requested physically exists – which is appropriate for resources served by CSP since they are served by Caché and are virtual as far as the web server is concerned. The “By MIME type” approach is therefore only suitable for cases where the application’s path structure can be replicated on the web server.
Operating and Managing the Gateway with Apache API
To access the CSP Web Gateway Management page, point your browser to:
http://localhost:<port_no>/csp/bin/Systems/Module.cxw
Notice the use of the cxw file extension. This extension prevents Apache attempting to load and run these DLLs through the Apache Group ISAPI interface. Also, remember that URL paths and files names are case-sensitive under Apache.
If you see an Unauthorized User error message, refer to the section on security considerations.
The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:
http://localhost:<port_no>/csp/samples/menu.csp
If you see an Unauthorized User error message, refer to the section on security considerations.
Sun Web Servers
This section covers the configuration and operational procedures for running CSP through the Sun Web Server. This guide is based on the CSP web server components being installed in the following file system:
/cache-install-dir/csp/
It is assumed that the web server is installed under:
/usr/SUNWwbsvr/   (or /opt/SUNWwbsvr/)
Individual instances of the Sun server are installed under directories of the form:
/usr/SUNWwbsvr/https-<server_name>/
or
/usr/SUNWwbsvr/httpd-<server_name>/
Where server_name is the logical name assigned to the hosting computer.
If the layout is different on your system, be sure to amend the configuration directives described in the following sections, as appropriate.
The documentation root directory for these servers is usually:
/usr/SUNWwbsvr/docs/
Install Locations for Sun Web Servers (Recommended Option)
Install the CSP Gateway components and the CSP static files as follows:
  1. NSAPI and CGI Modules
    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:
    /opt/cspgateway/bin
    The configuration file (CSP.INI) and Event Log (CSP.LOG) are written in this directory for non-NSD based connectivity options.
  2. HyperEvents Components
    The default location for these files is:
    /cache-install-dir/csp/broker
  3. Miscellaneous static resources used by the CSP Samples
    A number of static web resources (such as image files) are required by the CSP Samples. The default location for these files is:
    /cache-install-dir/csp/samples
  4. Miscellaneous static resources used by the Caché Management Portal.
    A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is:
    /cache-install-dir/csp/sys
Recommended Option: NSAPI Modules (CSPn3.so)
Configure the web server to recognize CSP requests (files of type .csp, .cls, and .zen) 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/SUNWwbsvr/https-<server_name>/config/
You need to add directives to load the NSAPI modules and instructions for recognizing and processing CSP files to the web server configuration.
Directives
Follow the direction in each of the directive subsections below.
Directives for Loading NSAPI Modules
The Init directive instructs the web server to load NSAPI modules. These directives should be added to the core magnus.conf file. These core configuration directives are always present, an example of which is as follows:
Init fn=load-types mime-types=mime.types
Locate the block of core Init directives and add the following section before this block:
Init fn=load-modules shlib=/opt/cspgateway/bin/CSPn3.so \
     funcs=csp_term,csp_init,csp_req
Init fn=csp_init shlib=”/opt/cspgateway/bin/CSPn3.so”
Note that Init directives are made up of a single line. Due to the limitations of space, the lines 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, the Java/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 documentation root directory.
Find the default directives section of obj.conf:
<Object name="default">
Add the following line in the default section – that is, after the line shown above.
NameTrans fn="pfx2dir" from="/csp/samples" dir="/cache-install-dir/csp/samples"
NameTrans fn="pfx2dir" from="/csp/broker" dir="/cache-install-dir/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="*/*.zen">
Service method=(GET|HEAD|POST) fn=csp_req
</Object>
<Object ppath="*/CSPn3Sys.so">
Service method=(GET|HEAD|POST) fn=csp_req
</Object>
<Object ppath="*/CSPn3.so">
Service method=(GET|HEAD|POST) fn=csp_req
</Object>
<Object ppath="*/Systems/Module.cxw">
Service method=(GET|HEAD|POST) fn=csp_req
</Object>
<Object ppath="*/RunTime/Module.cxw"> 
Service method=(GET|HEAD|POST) fn=csp_req
 </Object>
Registering additional file types with CSP
Configuring additional file types to be processed by CSP is simply a question of replicating, for the new file extension(s), the configuration block created (at the end of obj.conf) for the usual file extensions (csp,cls, zen).
If you need to serve other static files through the CSP Gateway or need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js.
To map requests for all files to CSP for a given path, set up a wildcard entry for that path. For example:
<Object ppath="/csp/*.*">
Service method=(GET|HEAD|POST) fn=csp_req
</Object>
It is not necessary to add any further configuration block to this section. In addition to this modification make sure that any configuration directives previously used to alias your paths to physical locations on the web server are removed. In other words, the following lines (or similar) should not be added to the obj.conf file:
NameTrans fn="pfx2dir" from="/csp/samples" dir="/cache-install-dir/csp/samples"
NameTrans fn="pfx2dir" from="/csp/broker" dir="/cache-install-dir/csp/broker"
Operating and Managing the Gateway with Sun NSAPI
The web server must be restarted after making changes to its configuration files (magnus.conf and obj.conf).
To access the CSP Web Gateway Management page, point your browser at one of the following locations:
http://localhost:<port_no>/csp/bin/Systems/Module.cxw 
http://localhost:<port_no>/csp/bin/CSPn3Sys.so
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
Nginx Web Servers
Nginx is an Open Source product and the source code can be downloaded free of charge from:
http://nginx.org/
Some prebuilt kits are available for Linux which are, generally, a few builds behind the latest Nginx build. However, given that extensions must be compiled into the Nginx core, it is necessary to build the web server locally from the source code in order to include support for CSP.
This guide assumes that CSP/Gateway web server components are installed under the following directory:
/opt/cspgateway/bin/
It assumes that Caché, if installed locally, is under:
/opt/cachesys/
It assumes that the web server is installed under:
/opt/nginx/
If the layout is different on your system, be sure to amend the various configuration directives described in the following sections, as appropriate.
Installation
The CSP Gateway components and the CSP static files should be installed as follows:
  1. Dynamically linked Universal CSP Gateway Modules
    The default location for these binaries is:
    The configuration file (CSP.INI) and Event Log (CSP.LOG) are written in this directory.
    The modules with Sys appended are special modules for accessing the CSP systems management suite. The run-time modules (that is, those without Sys) have no access to the systems management forms.
  2. HyperEvents Components
    The default location for these files is:
    If these files are to be served as static components directly by the web server they should be copied to the following location:
  3. Miscellaneous static resources used by the CSP Samples
    A number of static web resources (such as image files) are required by the CSP Samples. The default location for these files is:
    Copy these to the following location if they are to be served directly by the web server:
  4. Miscellaneous static resources used by the Caché SMP
    A number of static web resources (such as image files) are required by the SMP. The default location for these files is:
    Copy these to the following location if they are to be served directly by the web server:
    See the section Static Files in Using CSP for more information.
Building the Nginx Web Server for CSP
Most of the CSP Gateway functionality is provided by the Universal Modules (CSPx[Sys].so). For CSP access, Nginx can be built and configured to communicate with these Universal Modules through a small compiled-in module:
ngx_http_csp_module_sa.c
The build instructions given here are based on the official documentation for building Nginx under UNIX systems:
http://nginx.org/en/docs/configure.html
The Nginx documentation stipulates that the following third party add-ons are also required:
However, it is possible to create a fully functional server without these components, provided the final installation doesn’t require the functionality that would otherwise be provided by them.
A typical configuration script for building Nginx, including all optional modules listed above, is as follows:
./configure --prefix=/opt/nginx --with-http_ssl_module
This results in a default Nginx build installed under: /opt/nginx
The build process can be modified to exclude optional modules:
Procedure for building Nginx for CSP
  1. Unpack the source distribution under a location of your choice. For example:
    After unpacking, if you specify /opt/, the source code distribution is under:
  2. Create a directory for the CSP extension:
  3. Copy the module source code (ngx_http_csp_module_sa.c and cspapi.h) to the directory created above.
  4. In that same directory, create a configuration file called config. This file should contain the following lines:
    ngx_addon_name=ngx_http_csp_module_sa
    HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module_sa"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module_sa.c"
    CORE_LIBS="$CORE_LIBS -ldl"
  5. Working in /opt/nginx-n.n.n/, configure the Nginx build environment:
    ./configure --prefix=/opt/nginx \
    --with-http_ssl_module \
    --add-module=/opt/nginx-n.n.n/csp
    Alternatively, without the optional functionality provided by OpenSSL, ZLIB and PCRE:
     ./configure --prefix=/opt/nginx \
    --without-http_rewrite_module \
    --without-http_gzip_module \
    --add-module=/opt/nginx-n.n.n/csp
    Note the final line containing the instructions to include the CSP module.
  6. Compile Nginx:
    make
  7. Install Nginx:
    make install
    If successful, you should find the complete server installation under:
Using the Universal CSP Gateway Modules (CSPx*.so)
The Universal Modules CSPx.so (Run-time) and CSPxSys.so (Gateway systems management) are dynamically linked modules that are designed to be loaded by a CSP-enabled Nginx installation.
The web server should be configured such that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the CSP Gateway module for processing
The web server configuration file (nginx.conf) is found in the following directory:
/opt/nginx/conf
The following configuration directives are provided for the CSP extension:
Place the following directive within the http configuration block:
CSPModulePath /opt/cspgateway/bin/;
This directive enables Nginx to find the Universal Gateway Modules (CSPx[Sys].so) and the associated configuration (CSP.ini).
Nginx can now be configured to pass all requests for a certain path to CSP or just certain file types.
Using the Universal CSP Gateway Modules (CSPx*.dll)
The Universal Modules CSPx.dll (Run-time) and CSPxSys.dll (Gateway systems management) are dynamically linked modules that are designed to be loaded by a CSP-enabled Nginx installation.
The web server should be configured such that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the CSP Gateway module for processing
The web server configuration file (nginx.conf) is found in the following directory:
C:\nginx\conf
The following configuration directives are provided for the CSP extension:
For Windows, the thread stack size must be increased to 2MB. To do this, add the following directive to the top of the Nginx configuration file (before the http section):
thread_stack_size 2000000;
Place the following directive within the http configuration block:
CSPModulePath C:/cachesys/csp/bin/;
This directive enables Nginx to find the Universal Gateway Modules (CSPx[Sys].dll) and the associated configuration (CSP.ini).
Nginx can now be configured to pass all requests for a certain path to CSP or just certain file types.
Enabling CSP for a Particular Path
Place the following section within the appropriate server configuration block:
location /csp {
CSP On;
Registering Specific File Types with CSP
Place the following section within the appropriate server configuration block:
location /csp {
CSPFileTypes  csp cls zen cxw;
Starting and Stopping Nginx
First, ensure that Nginx has read/write permissions to the location holding the Universal Gateway Modules (/opt/cspgateway/bin/). This is the location where the Gateway configuration and Event Log files are maintained (CSP.ini and CSP.log).
To start Nginx:
/opt/nginx/sbin/nginx
To stop Nginx:
/opt/nginx/sbin/nginx –s stop
Operating and Managing the Gateway
To access the CSP Gateway’s systems management suite, point your browser:
http://<ip_address>/csp/bin/Systems/Module.cxw
Notice the use of the cxw file extension.
The CSP engine is automatically invoked for requested files containing the .csp, .cls, or .zen extensions. For example:
http://<ip_address>/csp/samples/menu.csp
If you see an Unauthorized User error message, refer to the section on security considerations in this book.
Building Nginx to Work with the CSP NSD Component
Nginx can be built to work with the CSP Gateway’s Network Service Daemon component (CSPnsd[Sv].exe), as opposed to the Universal Modules (CSPx[Sys].dll). To do this, modify the build and configuration procedure as follows:
The usual reason for preferring to use the NSD component is to obtain full and reliable support for CSP state-aware mode (Preserve mode). However, in order to get the best results with Nginx, it is recommended that applications should be entirely state-less.