Skip to main content

Alternative Configurations for UNIX®, Linux, and Mac OS X

Important:

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

This section describes how to configure atypical options for UNIX, Linux, and Mac OS.

Using the NSD on UNIX®, Linux, Mac OS X

When to Use the NSD

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

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

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

NSD Module Install Locations

The NSD Module, if required, is CSPnsd.

The default location for this module is:

/opt/cspgateway/bin

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 connectivity options.

Operating the NSD

To run the NSD:

  1. Change to the following directory:

    /opt/cspgateway/csp

  2. Enter the following command to start the NSD:

    ./CSPnsd

Before retiring to the background, the NSD displays a banner indicating its running configuration. It shows the TCP port number dedicated to this service, which is, by default, port number 7038.

You can suppress all startup messages for this command using the -s qualifier. For example, to start the NSD from a script invoked at system boot, use:

/opt/cspgateway/csp/CSPnsd –s

Other common startup options:

  • Display help information.

    ./CSPnsd -h

  • Pause the operation of the NSD. This command sends a stop signal (SIGSTOP) to the NSD process.

    ./CSPnsd -pause

  • Continue the operation of the NSD (after a pause). This command sends a continue signal (SIGCONT) to the NSD process.

    ./CSPnsd -cont

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

    s can be one of

    • u for the current user (default)

    • g for the current group

    • o for others

    • a for everyone (m=ugo)

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

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

To close down the NSD, enter:

./CSPnsd -stop

Alternatively:

kill –TERM `cat /opt/cspgateway/csp/CSPnsd.pid`

These commands close 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 the kill –9 command to terminate the NSD.

All errors are reported in the Event Log (CSP.log). This file is created and maintained in the NSD home directory (such as /opt/cspgateway/csp). 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 starting the service as follows, where port_no is the TCP port number of your choice.

./CSPnsd [port_no]

Or:

./CSPnsd -p=[port_no]

On startup, the NSD creates the following file:

/opt/cspgateway/csp/CSPnsd.ini

Typically, this file contains the following lines:

[SYSTEM]
Ip_Address=127.0.0.1
TCP_Port=7038

In this context, the clients are the CSP module contained within, or dynamically linked to, the web server and/or the CSP CGI modules invoked by the server. It is, therefore, essential that this file is not deleted or moved. It is also important that the web server processes can read this file. Set the privileges accordingly, bearing in mind the UNIX® username under which your web server is operating. The NSD clients attempt to find this file in the following locations:

/cache-install-dir/csp

/opt/cspgateway/csp

/etc

If the NSD is operating in a different directory, you have to move the CSPnsd.ini file to one of the locations listed.

Storing the NSD port number in the CSPnsd.ini file is inappropriate for situations in which multiple instances of the NSD are running. For Apache servers there is a much better mechanism for communicating the TCP port number of the NSD to its clients. Set the following environment variables in the Apache configuration to indicate the address and port of the target NSD installation.

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.

The values specified in these environment variables take precedence over any values found in the CSPnsd.ini file.

Example 1:

To distribute the load for two Apache virtual hosts (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:

To distribute the load for two CSP applications (/csp1 and /csp2) between two independent NSD installations (listening on TCP port 7038 and 7039), 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>

Restart Apache after making changes to its configuration.

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

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

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

Spreading the Load over Multiple NSD Processes

By default, the NSD operates in a two-process mode of operation (one parent and one child worker).

However, there are limits to the number of threads that a single UNIX® process can start. If the concurrent load of the CSP application is resulting in requests queuing for available threads, consider raising the number of processes used by the NSD.

./CSPnsd –c=[no_processes]

- where no_processes is the number of child (or worker) processes to start.

It should be noted that there are even advantages in setting the number of child processes to one.

./CSPnsd –c=1

Under these circumstances, the NSD actually start two processes: a parent and one child worker process. The presence of the parent processes when using the ‘–c’ directive improves the resilience of the NSD because if a fault develops in one of the worker processes the parent can replace the process. For the single, multithreaded architecture, the NSD cannot always recover from serious internal error conditions.

State-aware connectivity (preserve mode 1) should not be used in cases where the number of worker processes exceeds one.

Granting Administrator Rights to the NSD

Administrators of the NSD (CSPnsd) component can have some control over the user (or group) permitted to start/stop this service.

In the default scenario, the CSPnsd master process ID (PID) file (CSPnsd) is created such that only the user who started the service can subsequently close it down.

Administrators can now choose, for example, to allow all users belonging to the current UNIX group to manage the service. This is the group to which the administrating user belongs.

NSD start-up option: [-m=s]
     Define the user(s) permitted to manage this service
          where 's' is:
               'u' for the current user (the default),
               'g' for the current group,
               'o' for others,
               'a' for everyone (m=ugo),

Example:

./CSPnsd -m=ug

This allows the current user and all others in the current user's group to manage the NSD.

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

Atypical Options for Apache for UNIX®, Linux, Mac OS

This section contains the following subsections. Read the first section for all atypical options. Then follow the directions in the option that applies to your installation.

  1. Installing with Apache Servers on UNIX®, Linux, and Mac OS (All Alternative Options)

  2. Alternative Option 1: Apache API Module with NSD (mod_csp24.so)

  3. Alternative Option 2: CGI Modules with NSD (nph-CSPcgi)

  4. Alternative Option 3: Built-in Apache API Module with NSD (mod_csp.c)

Install Locations Apache on UNIX®, Linux, Mac OS (All Alternative Options)

This section describes directory locations for CSP Gateway files and CSP static files.

  1. The NSD module is:

    CSPnsd
    

    The default location of this module is:

    /opt/cspgateway/csp
    

    The NSD should be run from within its home directory /opt/cspgateway/csp. The configuration file, CSP.INI, and the event log, CSP.LOG, are written in this directory.

    In order to avoid disrupting existing Gateway installations on upgrading Caché, the installation places the following modules in the common location /usr/cspgateway/nsd. This location is not related to a particular Caché instance.

  2. CGI and other dynamically-linked modules:

    • CSPcgi (Runtime module)

    • nph-CSPcgi (Copy of CSPcgi)

    • CSPcgiSys (Systems-Management module)

    • nph-CSPcgiSys (Copy of CSPcgiSys)

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

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

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

    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.

    /usr/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.

  3. The default location for the HyperEvents components:

    • CSPBroker.js

    • CSPxmlhttp.js

    and miscellaneous static resources (such as image files) are required by the CSP Samples and the Management Portal is:

    \cache-install-dir\csp\broker

Requirements for using Apache API Modules (Recommended Option and Alternative Option 1)

Before following instructions for either the recommended option (“Recommended Option: NSAPI Modules (CSPn3.so)”) or atypical option 1 (“Alternative Option 1: Apache API Module with NSD (mod_csp24.so)”, 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.

Atypical Option 1: Apache API Module with NSD (mod_csp24.so)

If the CSP module is supplied with your distribution as a pre-built shared object (mod_csp22.so or mod_csp2.so), then proceed to the section on configuration. To build the shared object from the supplied source file mod_csp.c choose Method 1 or Method 2 below. Method 1 is preferred.

Use module mod_csp24.so for Apache Version 2.4.x, mod_csp22.so for Apache Version 2.2.x, and mod_csp2.so for Apache Version 2.0.x.

Be sure to read the following instructions regarding the creation of shared objects in conjunction with the specific documentation contained within your Apache distribution. Note that the 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 appended to it.

The module source file supplied (mod_csp.c) is fully compliant with both Apache v2.2.x and Apache V2.0.x.

Method 1: Building the CSP Module as Shared Object with apxs (APache eXtenSion) Tool

The following command builds and installs the shared library, mod_csp24.so, in the Apache /modules directory using the Apache extension tool, apxs. It also adds a directive to load the module to the Apache configuration file /conf/httpd.conf.

apxs -I -a –c mod_csp.c

This module mod_csp22.so for Apache Version 2.02.x and mod_csp2.so for Apache Version 2.0.x.

Alternatively, mod_csp24.so may be built directly as follows:

apxs –c –o mod_csp2.so mod_csp.c

Install the shared-object produced binary in the following directory: /opt/cspgateway/bin.

Method 2: Building the CSP Module as Shared Object Manually

Perform the following steps to manually build the CSP module as a shared object:

  1. Install the module source file mod_csp.c in the following directory: /usr/apache/src/modules/extra

  2. Return to the /usr/apache/src directory and edit the Configuration file. Near the end of this file, locate the following line:

    # AddModule modules/example/mod_example.o
    

    After this line, add the following line:

    ShareModule modules/extra/mod_csp24.so
    
  3. Configure the build process using the following command:

    ./Configure
    
  4. Build the shared object using the following command:

    make
    
  5. To produce shared object mod_csp.so in /usr/apache/src/modules/extra

Note:

For further information about the apxs tool, refer to the Apache documentation at http://httpd.apache.org/docs/2.0/programs/apxs.htmlOpens in a new tab.

Method 2 Examples

This section documents the compiler and linker commands you can use to build the Apache module on a range of popular UNIX® systems.

  • DEC UNIX® 5 (DEC Compiler)

    cc -c -DOSF1 -std1 -pthread -DIS_64 -ieee_with_inexact \
     –I/usr/apache/include mod_csp.c -o mod_csp.o
    ld -all -shared -expect_unresolved "*" -taso mod_csp.o \
    -o mod_csp24.so
    
  • FreeBSD (GNU Compiler)

    cc -c -DFREEBSD –I/usr/apache/include -o mod_csp.o mod_csp.c
    ld -G -o mod_csp.so mod_csp24.o
    
  • Linux: (GNU Compiler)

  • Apache v2.0.x

    cc -c -fpic -DLINUX –I/usr/apache/include -o mod_csp.o mod_csp.c 
    ld -G -lrt -ldl -o mod_csp.so mod_csp.o
    
  • Apache v24.x

    cc -c -fpic -DLINUX=2 -D_REENTRANT -D_GNU_SOURCE -D_LARGEFILE64_SOURCE –I/usr/apache/include mod_csp.c -o mod_csp24.o
    ld -G mod_csp24.o -lrt -ldl -o mod_csp24.so
    
  • Mac OS X: (Mac OS X Compiler)

    –I/usr/apache/include mod_csp.c -o mod_csp.o
    gcc -c -fPIC -fno-common -DMACOSX -DDARWIN gcc -bundle -flat_namespace -undefined suppress mod_csp.o -o mod_csp24.so
    
  • IBM AIX® (IBM Compiler)

    xlc_r -c -DAIX -DAIX5 -I/usr/apache/include mod_csp.c -o mod_csp.o
    xlc_r -G -H512 -T512 -bM:SRE mod_csp.o -berok -bexpall -bnoentry -lm -lc -o mod_csp24.so
    
  • IBM AIX®: 64-bit (IBM Compiler)

    OBJECT_MODE=64
    export OBJECT_MODE
    xlc_r -c -DAIX -DAIX5 -I/usr/apache/include mod_csp.c -o mod_csp.o
    xlc_r -G -H512 -T512 -bM:SRE mod_csp.o -berok -bexpall -bnoentry -lm -lc -o mod_csp24.so
    

Copy mod_csp24.so to: /opt/cspgateway/bin.

Runtime Configuration

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

/usr/apache/conf

For Red Hat Linux, the runtime version of httpd.conf is in:

/etc/httpd/conf

Assuming that you wish to invoke the CSP engine for requested files that contain a .csp, .cls, or .zen extension, add the following section to the end of httpd.conf. Of course, if you are using Apache Version 2.0.x, specify mod_csp2.so in the configuration block below. If you are using Apache Version 2.2.x, specify mod_csp22.so.

The below configuration block relies on the Regular Expressions (regex) processor being available to the Apache environment. Sometimes this is not the case and CSP files are consequently not served (File not found errors are returned). To remedy this situation, replace the following lines in the configuration block:

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

with:

CSPFiletypes csp-handler csp cls
LoadModule csp_module /opt/cspgateway/bin/mod_csp.so
<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
                SetHandler csp-handler
</LocationMatch>
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>
        <Files CSPnsd>
                Require all denied
        </Files>
</Directory>
ScriptAlias /csp-bin/ "/opt/cspgateway/bin/"
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/opt/cspgateway/bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/opt/cspgateway/bin/nph-CSPcgi"
<Directory "/opt/cspgateway/bin/">
        AllowOverride None
        Options None
        Require all granted
</Directory>

Restart Apache after making changes to httpd.conf.

Pooling Connections Between the Apache Module and the NSD

This facility is available only in build 7 (and later) of the Apache module: mod_csp. This is supplied with the Caché v2008.2 distributions.

The enhancement described in this section concerns connection pooling in the Apache module: mod_csp[n].so/dll. As discussed previously, this module is designed to implement the lines of communication between the Web Server environment and the Gateway NSD component (CSPnsd).

Previous versions of the Apache module implemented an HTTP v1.0 style of communication between the Web Server and Gateway. This mode of operation was necessary because, prior to the enhancements made in later versions of the CSP Gateway, CSP responses were generally dispatched to the client without including any form of size notification. Therefore, the “connection close” event was the sole means of terminating a response. However, as with other HTTP v1.0 based applications, the following problems become apparent at times of peak usage:

  1. The overhead of creating a new TCP connection to serve each request.

  2. Production systems would inevitably experience a build-up of connections spending an unacceptable length of time in the “TIME_WAIT”state at times of peak usage.

The problems listed above can be solved by maintaining a pool of persistent TCP connections between the module and NSD. On the sever side (i.e. NSD), a pool of threads is maintained alongside the persistent connections (connection-oriented thread pooling).

It is anticipated that these enhancements result in a marked improvement in performance for Apache/UNIX® installations. The best improvements are seen with Apache v2 (and later) because this server is a multithreaded/multiprocess hybrid and it is possible to anticipate a single instance of mod_csp being able to maintain a large pool of persistent TCP connections to the server. However, the same optimizations should also improve the performance of the Apache Group’s earlier single-threaded/multiprocess servers (v1.3 and earlier).

Controlling Connection Pooling

The size of the connection pool can be controlled by the following Apache configuration parameter (specified in http.conf):

CSPMaxPooledNSDConnections <no> 

In the absence of this parameter, a default value of 32 is used internally – which is effectively:

CSPMaxPooledNSDConnections 32 

To switch-off connection pooling, set this parameter to zero:

CSPMaxPooledNSDConnections 0 

If, for any reason, it becomes necessary to use the legacy (asymmetric) mode of operation (whereby the Gateway notifies the end of response transmission by closing the connection on its side), set this parameter to minus 1:

CSPMaxPooledNSDConnections -1
Operating and Managing the Gateway with Apache API and NSD

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

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

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

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

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

    http://localhost:<port_no>/csp-bin/nph-CSPcgiSys
    

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

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

http://localhost:<port_no>/csp/samples/menu.csp

Registering Additional File Types with CSP

Apache API modules always recognize the following reserved file extensions:

.csp .cls .zen .cxw 

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

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

  • By CSP location directive

  • By file extension – CSPFileTypes directive

  • By MIME type

By CSPlocation directive

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

<Location /csp>
   CSP On 
   SetHandler csp-handler-sa
</Location> 

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

/csp/ 
csp/samples/menu.csp 
csp/sys/ 
By file extension – CSPFileTypes directive

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

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

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

CSPFileTypes xxx yyy 

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

<Location /csp/> 
   CSPFileTypes xxx yyy
</Location>

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

<Location /csp/> 
   CSPFileTypes * 
</Location> 
By MIME type

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

application/x-csp

and

text/csp

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

LoadModule csp_module_sa /opt/cspgateway/csp/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.

Alternative Option 2: CGI Modules with NSD (nph-CSPcgi)

The web server should be configured such that it recognizes CSP requests (files of type .csp, .cls, and .zen) 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 runtime version of httpd.conf is found in:

/etc/httpd/conf

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

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/opt/cspgateway/bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/opt/cspgateway/bin/nph-CSPcgi"
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "/opt/cspgateway/bin/nph-CSPcgi"
Alias /csp/ instance-installation-directory
<Directory "instance-installation-directory">
    AllowOverride None
    Options MultiViews FollowSymLinks ExecCGI
   Require all granted
    <FilesMatch "\.(log|ini|pid|exe)$">
       Require all denied
    </FilesMatch>
    <Files CSPnsd>
       Require all denied
    </Files>
</Directory>
ScriptAlias /csp-bin/ "/opt/cspgateway/bin/"
<Directory "/opt/cspgateway/bin/">
    AllowOverride None
    Options None
    Require all granted
</Directory>

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

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</LocationMatch>
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "/opt/cspgateway/bin/nph-CSPcgi"

with:

<Location "/csp">
    AllowOverride None
    Options FollowSymLinks ExecCGI
   Require all granted
</Location>
ScriptAlias /csp "/opt/cspgateway
/bin/nph-CSPcgi"

These directives work for URLs of the form:

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

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

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

Another approach to avoiding the regex issue is to use an Action directive in conjunction with a CSP MIME type. However, it should be noted that Action is essentially a content filtering technique and, as such, requires that your CSP files are physically present on the web server host even if the Caché server is installed on a separate computer. If you wish to use this approach, first add a new MIME type to the end of the Apache mime.types file and associate it with file types representing CSP content. The mime.types file are found in the same 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 such that it reads:

Alias /csp/ /opt/cspgateway/csp/
<Directory "/opt/cspgateway/csp">
    AllowOverride None
    Options MultiViews FollowSymLinks ExecCGI
    Require all granted
<Files CSPnsd>
       Require all denied
    </Files>
<Files CSP.ini>
       Require all denied
    </Files>
<Files CSP.log>
       Require all denied
    </Files>
<Files CSPnsd.ini>
       Require all denied
    </Files>
<Files CSPnsd.pid>
       Require all denied
    </Files>
</Directory>
ScriptAlias /csp-bin/ "/opt/cspgateway/bin/"
<Directory "/opt/cspgateway/bin/">
    AllowOverride None
    Options None
    Require all granted
</Directory>
Action text/csp “/csp-bin/nph-CSPcgi”

Restart Apache after making changes to httpd.conf.

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

Registering Additional File Types with CSP

Apache API modules always recognize the following reserved file extensions:

.csp .cls .zen .cxw 

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

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

  • By CSP location directive

  • By file extension – CSPFileTypes directive

  • By MIME type

By CSPlocation directive

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

<Location /csp>
   CSP On 
   SetHandler csp-handler-sa
</Location> 

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

/csp/ 
csp/samples/menu.csp 
csp/sys/ 
By the 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/csp/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 CGI and NSD

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

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

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

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

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

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

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

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

http://localhost:<port_no>/csp/samples/menu.csp

Alternative Option 3: Built-in Apache API Module with NSD (mod_csp.c)

Before embarking on setting up this more complicated option you should bear in mind that, for most modern UNIX® systems, the performance advantage in static linking over linking the module at runtime as a shared object (option 1) is minimal (if anything at all).

Be sure to read these instructions in conjunction with the specific documentation contained within your Apache distribution.

Build Apache to Include CSP Module Source Code

Refer to the Apache documentation for this step.

http://httpd.apache.org/Opens in a new tab

Check the Apache Binary Produced

Run the following command to check that the CSP module has been successfully included in 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

Runtime Configuration

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

/usr/apache/conf

For Red Hat Linux, the runtime version of httpd.conf is in:

/etc/httpd/conf

Assuming that you wish to invoke the CSP engine for requested files that contain a .csp, .cls, or .zen extension, add the following section to the end of httpd.conf:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
                SetHandler csp-handler
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/opt/cspgateway/bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/opt/cspgateway/bin/nph-CSPcgi"
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>
        <Files CSPnsd>
                Require all denied
        </Files>
</Directory>
ScriptAlias /csp-bin/ "/opt/cspgateway/bin/"
<Directory "/opt/cspgateway/bin/">
        AllowOverride None
        Options None
        Require all granted
</Directory>

The above configuration block relies on the Regular Expressions (regex) processor being available to the Apache environment. Sometimes this is not the case and CSP files are consequently not served (File not founderrors are returned). To remedy this situation, replace the following configuration block:

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

with:

CSPFiletypes

Note that all requests to Apache are serviced by a set of modules invoked in a predefined sequence. The CSP module is one of the first modules invoked, provided its definition was added near the end of the Configuration file as suggested.

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 

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

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

  • By CSP location directive

  • By file extension

  • By CSPFileTypes directive

  • By MIME type

By CSPlocation directive

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

<Location /csp>
   CSP On 
   SetHandler csp-handler-sa
</Location> 

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

/csp/ 
csp/samples/menu.csp 
csp/sys/ 
By file extension

Traditionally, Apache has been configured to invoke CSP on the basis of the requested file’s extension. For example, the following configuration block (from httpd.conf) tells Apache to allow CSP to process requests for files of type *.csp, *.cls, *.zen, and *.cxw:

LoadModule csp_module_sa /opt/cspgateway/csp/bin/CSPa22.so
AddHandler csp-handler-sa csp cls zen cxw

This method works well in Apache v1.3.x, but may no longer work in Apache v2.0.x (and later).

By the 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/csp/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 and NSD

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

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

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

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

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

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

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

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

http://localhost:<port_no>/csp/samples/menu.csp

Locked-down Apache for UNIX®, Linux, and Mac OS X

Occasionally Apache is locked-down so that you cannot easily configure the server to access files outside the Apache file system. For example, this is the case for Security Enhanced Linux (SELinux).

For configurations locked down in this way, the CSP Gateway configurations discussed in previous sections results in HTTP 403 Forbidden error codes being returned on attempting to access CSP resources. The simplest way to work with these secure configurations is to copy the file system under:

/opt/cspgateway/csp

to a location under the Apache root:

/usr/apache/csp

Having done this, the appropriate changes to the paths specified in the Apache configuration must be made.

An alternative approach (and the one that should be used if the method suggested above fails) is to configure the CSP Gateway to work within the directories supplied by Apache.

  1. Copy CGI modules to: /usr/apache/cgi-bin/

    cp /opt/cspgateway/bin/*cgi* /usr/apache/cgi-bin/
    
  2. Copy API modules to: /usr/apache/modules/

    cp /opt/cspgateway/bin/*.so /usr/apache/modules/
    
  3. Copy static files (and subdirectories in these directories) to locations under: /usr/apache/htdocs/

    cp /cache-install-dir/csp/samples/* /usr/apache/htdocs/csp/samples/
    cp /cache-install-dir/csp/broker/* /usr/apache/htdocs/csp/broker
    cp /cache-install-dir/csp/sys/* /usr/apache/htdocs/csp/sys
    
  4. Install the NSD component (if required) in: /usr/apache/nsd/

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

Recommended Option: Apache API Modules (CSPa24.so)

LoadModule cspsys_module_sa /usr/apache/modules/CSPap24.so
CSPSYSModulePath /usr/apache/modules/
<Location "/csp/bin/Systems/">
    SetHandler cspsys-handler-sa
</Location>
<Location "/csp/bin/RunTime/">
    SetHandler csp-handler-sa
</Location>
CSPFiletypes csp cls zen cxw

Atypical Option 1: Apache API Module with NSD (mod_csp.so)

LoadModule csp_module /usr/apache/modules/mod_csp.so
<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
SetHandler csp-handler
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/usr/apache/cgi-bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/usr/apache/cgi-bin/nph-CSPcgi"

Atypical Option 2: CGI Modules with NSD (nph-CSPcgi)

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

Atypical Option 3: Built-in Apache API Module with NSD (mod_csp.c)

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
SetHandler csp-handler
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/apache/cgi-bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/usr/apache/cgi-bin/nph-CSPcgi"

Alternative Option for Sun Web Servers

There is only one atypical option for a Sun web server, the NSAPI module with the NSD.

Install Locations for Sun (Alternative Option)

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

  1. The NSD module is:

    CSPnsd
    

    The default location of the NSD module is:

    /opt/cspgateway/csp
    

    The NSD should be run from within its home directory /opt/cspgateway/csp. The configuration file, CSP.INI, and the event log, CSP.LOG, are written in this directory.

    In order to avoid disrupting existing Gateway installations on upgrading Caché, the installation places the following modules in the common location /usr/cspgateway/nsd. This location is not related to a particular Caché instance.

  2. NSAPI and CGI Modules

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

    • CSPcgi.exe (Runtime module)

    • nph-CSPcgi.exe (Copy of CSPcgi)

    • CSPcgiSys.exe (Systems-Management module)

    • nph-CSPcgiSys.exe (Copy of CSPcgiSys)

    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.

  3. The default location for the HyperEvents components:

    • CSPBroker.js

    • CSPxmlhttp.js

    and miscellaneous static resources (such as image files) are required by the CSP Samples and the Management Portal is:

    \cache-install-dir\csp\broker

Alternative Option 1: NSAPI Module with NSD (CSPcn3.so)

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

This configuration procedure is very similar to that described for the recommended option, “Recommended Option: NSAPI Modules (CSPn3.so)”. The essential differences are highlighted below.

Locate the block of core Init directives for your web server as described for the Recommended Option. These are found in either magnus.conf or obj.conf. Add the following section before the core Init block:

Init fn=load-modules shlib=/cache-install-dir/csp/bin/CSPcn3.so funcs=cspc_term,cspc_init,cspc_req
Init fn=cspc_init shlib="/cache-install-dir/csp/bin/CSPcn3.so"

Directives

Directives for Locating Static Components and the CGI Modules

Find the default directives section of obj.conf:

<Object name="default">

Add the following lines 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"

NameTrans fn="pfx2dir" from="/csp-bin" dir="/cache-install-dir/csp/bin" name="cgi"

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>

Operating and Managing the Gateway with NSAPI 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 the web server after making changes to its configuration files (magnus.conf and obj.conf).

    The order in which the web server 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 (CSPcn2.so), the CSP Web Gateway Management page is accessed through the CGI module dedicated to this purpose (nph-CSPcgiSys).

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

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

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

http://localhost:<port_no>/csp/samples/menu.csp

Troubleshooting

If you are getting I/O errors when connecting via HTTPS to an Apache mod_ssl server with Microsoft Internet Explorer, you might try the following. This is an occasional issue caused by Apache introduced in an attempt to work around problems caused by earlier versions of IE. The following lines are in the SSL/TLS configuration for apache:

BrowserMatch ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0

Remove the last \ and the line downgrade-1.0 force-response-1.0 and restart Apache. This prevents a downgrade of the HTTP headers from HTTP1.1 to HTTP1.0 to get around some issues that earlier versions of IE had with HTTP1.1. This may solve your issue.

FeedbackOpens in a new tab