17.10. Oracle NSAPI Connector

17.10.1. About the Netscape Server API (NSAPI)

Netscape Server API (NSAPI) is an API provided by Oracle iPlanet Web Server (formerly Netscape Web Server) for implementing extensions to the server. These extensions are known as server plugins. This API is used in nsapi_redirector.so provided by JBoss EAP 6 in Native utilities packages. To configure this connector, refer to Section 17.10.4, “Configure the NSAPI Connector to Balance Client Requests Across Multiple JBoss EAP 6 Servers”.

17.10.2. Configure the NSAPI Connector on Oracle Solaris

Summary

The NSAPI connector is a module that runs within Oracle iPlanet Web Server.

Prerequisites

  • Your server is running Oracle Solaris 10 or greater, on either an Intel 32-bit, an Intel 64-bit, or a SPARC64 architecture.
  • Oracle iPlanet Web Server 7.0.15 or later for Intel architectures, or 7.0.14 or later for SPARC architectures, is installed and configured, aside from the NSAPI connector.
  • JBoss EAP 6 is installed and configured on each server which will serve as a worker. Refer to Section 17.4.8, “Configure JBoss EAP 6 to Accept Requests From External Web Servers”.
  • The JBoss Native Components ZIP package is downloaded from the Customer Service Portal at https://access.redhat.com.

Procedure 17.25. Extract and Setup the NSAPI Connector

  1. Extract the JBoss Native Components package.

    The rest of this procedure assumes that the Native Components package is extracted to the EAP_HOME directory. For the rest of this procedure, the directory /opt/oracle/webserver7/config/ is referred to as IPLANET_CONFIG. If your Oracle iPlanet configuration directory is different, modify the procedure accordingly.
  2. Disable servlet mappings.

    Open the IPLANET_CONFIG/default.web.xml file and locate the section with the heading Built In Server Mappings. Disable the mappings to the following three servlets, by wrapping them in XML comment characters (<!-- and -->).
    • default
    • invoker
    • jsp
    The following example configuration shows the disabled mappings.
    <!-- ============== Built In Servlet Mappings =============== -->
    <!-- The servlet mappings for the built in servlets defined above. -->
    <!-- The mapping for the default servlet -->
    <!--servlet-mapping>
     <servlet-name>default</servlet-name>
     <url-pattern>/</url-pattern>
    </servlet-mapping-->
    <!-- The mapping for the invoker servlet -->
    <!--servlet-mapping>
     <servlet-name>invoker</servlet-name>
     <url-pattern>/servlet/*</url-pattern>
    </servlet-mapping-->
    <!-- The mapping for the JSP servlet -->
    <!--servlet-mapping>
     <servlet-name>jsp</servlet-name>
     <url-pattern>*.jsp</url-pattern>
    </servlet-mapping-->
    Save and exit the file.
  3. Configure the iPlanet Web Server to load the NSAPI connector module.

    Add the following lines to the end of the IPLANET_CONFIG/magnus.conf file, modifying file paths to suit your configuration. These lines define the location of the nsapi_redirector.so module, as well as the workers.properties file, which lists the workers and their properties.
    Init fn="load-modules" funcs="jk_init,jk_service" shlib="EAP_HOME/modules/system/layers/base/native/lib/nsapi_redirector.so" shlib_flags="(global|now)"
    
    Init fn="jk_init" worker_file="IPLANET_CONFIG/connectors/workers.properties" log_level="info" log_file="IPLANET_CONFIG/connectors/nsapi.log" shm_file="IPLANET_CONFIG/connectors/tmp/jk_shm"
    The configuration above is for a 32-bit architecture. If you use 64-bit Solaris, change the string lib/nsapi_redirector.so to lib64/nsapi_redirector.so.
    Save and exit the file.
  4. Configure the NSAPI connector.

    You can configure the NSAPI connector for a basic configuration, with no load balancing, or a load-balancing configuration. Choose one of the following options, after which your configuration will be complete.

17.10.3. Configure the NSAPI Connector to Send Client Requests to JBoss EAP 6

Overview

This task configures the NSAPI connector to redirect client requests to JBoss EAP 6 servers with no load-balancing or fail-over. The redirection is done on a per-deployment (and hence per-URL) basis. For a load-balancing configuration, refer to Section 17.10.4, “Configure the NSAPI Connector to Balance Client Requests Across Multiple JBoss EAP 6 Servers” instead.

Prerequisites

Procedure 17.26. Setup the Basic HTTP Connector

  1. Define the URL paths to redirect to the JBoss EAP 6 servers.

    Note

    In IPLANET_CONFIG/obj.conf, spaces are not allowed at the beginning of a line, except when the line is a continuation of the previous line.
    Edit the IPLANET_CONFIG/obj.conf file. Locate the section which starts with <Object name="default">, and add each URL pattern to match, in the format shown by the example file below. The string jknsapi refers to the HTTP connector which will be defined in the next step. The example shows the use of wildcards for pattern matching.
    <Object name="default">
    [...]
    NameTrans fn="assign-name" from="/status" name="jknsapi"
    NameTrans fn="assign-name" from="/images(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/css(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/nc(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/jmx-console(|/*)" name="jknsapi"
    </Object>
    
  2. Define the worker which serves each path.

    Continue editing the IPLANET_CONFIG/obj.conf file. Add the following directly after the closing tag of the section you have just finished editing: </Object>.
    <Object name="jknsapi">
    ObjectType fn=force-type type=text/plain
    Service fn="jk_service" worker="worker01" path="/status"
    Service fn="jk_service" worker="worker02" path="/nc(/*)"
    Service fn="jk_service" worker="worker01"
    </Object>
    
    The example above redirects requests to the URL path /status to the worker called worker01, and all URL paths beneath /nc/ to the worker called worker02. The third line indicates that all URLs assigned to the jknsapi object which are not matched by the previous lines are served to worker01.
    Save and exit the file.
  3. Define the workers and their attributes.

    Create a file called workers.properties in the IPLANET_CONFIG/connectors/ directory. Paste the following contents into the file, and modify them to suit your environment.
    # An entry that lists all the workers defined
    worker.list=worker01, worker02
    
    # Entries that define the host and port associated with these workers
    worker.worker01.host=127.0.0.1
    worker.worker01.port=8009
    worker.worker01.type=ajp13
    
    worker.worker02.host=127.0.0.100
    worker.worker02.port=8009
    worker.worker02.type=ajp13
    
    The workers.properties file uses the same syntax as Apache mod_jk. For information about which options are available, refer to Section 17.7.5, “Configuration Reference for Apache mod_jk Workers”.
    Save and exit the file.
  4. Restart the iPlanet Web Server.

    Issue the following command to restart the iPlanet Web Server.
    IPLANET_CONFIG/../bin/stopserv
    IPLANET_CONFIG/../bin/startserv
    
Result

iPlanet Web Server now sends client requests to the URLs you have configured to deployments on JBoss EAP 6.

17.10.4. Configure the NSAPI Connector to Balance Client Requests Across Multiple JBoss EAP 6 Servers

Overview

This task configures the NSAPI connector to send client requests to JBoss EAP 6 servers in a load-balancing configuration. To use NSAPI connector as a simple HTTP connector with no load-balancing, see Section 17.10.3, “Configure the NSAPI Connector to Send Client Requests to JBoss EAP 6”.

Procedure 17.27. Configure the Connector for Load-Balancing

  1. Define the URL paths to redirect to the JBoss EAP 6 servers.

    Note

    In IPLANET_CONFIG/obj.conf, spaces are not allowed at the beginning of a line, except when the line is a continuation of the previous line.
    Edit the IPLANET_CONFIG/obj.conf file. Locate the section which starts with <Object name="default">, and add each URL pattern to match, in the format shown by the example file below. The string jknsapi refers to the HTTP connector which will be defined in the next step. The example shows the use of wildcards for pattern matching.
    <Object name="default">
    [...]
    NameTrans fn="assign-name" from="/status" name="jknsapi"
    NameTrans fn="assign-name" from="/images(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/css(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/nc(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/jmx-console(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/jkmanager/*" name="jknsapi"   
    </Object>
    
  2. Define the worker that serves each path.

    Continue editing the IPLANET_CONFIG/obj.conf file. Directly after the closing tag for the section you modified in the previous step (</Object>), add the following new section and modify it to your needs:
    <Object name="jknsapi">
    ObjectType fn=force-type type=text/plain
    Service fn="jk_service" worker="status" path="/jkmanager(/*)"
    Service fn="jk_service" worker="router"
    </Object>
    
    This jksnapi object defines the worker nodes used to serve each path that was mapped to the name="jksnapi" mapping in the default object. Everything except for URLs matching /jkmanager/* is redirected to the worker called router.
  3. Define the workers and their attributes.

    Create a file called workers.properties in IPLANET_CONFIG/connector/. Paste the following contents into the file, and modify them to suit your environment.
    # The advanced router LB worker
    # A list of each worker
    worker.list=router,status
    
    # First JBoss EAP server
    # (worker node) definition.
    # Port 8009 is the standard port for AJP
    #
    
    worker.worker01.port=8009
    worker.worker01.host=127.0.0.1
    worker.worker01.type=ajp13
    worker.worker01.ping_mode=A
    worker.worker01.socket_timeout=10
    worker.worker01.lbfactor=3
    
    # Second JBoss EAP server
    worker.worker02.port=8009
    worker.worker02.host=127.0.0.100
    worker.worker02.type=ajp13
    worker.worker02.ping_mode=A
    worker.worker02.socket_timeout=10
    worker.worker02.lbfactor=1
    
    # Define the load-balancer called "router"
    worker.router.type=lb
    worker.router.balance_workers=worker01,worker02
    
    # Define the status worker
    worker.status.type=status
    
    The workers.properties file uses the same syntax as Apache mod_jk. For information about which options are available, see Section 17.7.5, “Configuration Reference for Apache mod_jk Workers”.
    Save and exit the file.
  4. Restart the iPlanet Web Server 7.0.

    IPLANET_CONFIG/../bin/stopserv
    IPLANET_CONFIG/../bin/startserv
    
Result

The iPlanet Web Server redirects the URL patterns you have configured to your JBoss EAP 6 servers in a load-balancing configuration.