Previous     Contents     Index     Next     
iPlanet Application Server Administrator's Guide



Chapter 7   Configuring the Web Connector Plug-In


This chapter describes the Web Connector Plug-in which sends users' requests to applications residing on iPlanet Application Server.

The following topics are included in this chapter:



About the Web Connector Plug-In

The Web Connector Plug-in is installed on your web server at the time you install iPlanet Application Server.

If you install iPlanet Application Server on the same machine where a web server is installed, the Web Connector Plug-in is simultaneously installed and the web server configured automatically.

If you install iPlanet Application Server on a machine where a web server is not installed, you must manually install the Web Connector Plug-in on that web server machine. For more information about manually installing the web connector, see the Installation Guide.

You can configure the following Web Connector Plug-in functions:


Table 7-1    Configurable Web Connector Plug-in Functions

Connector functionality

Description

More information

Web server request logging  

Mapping web server request components to database fields and adding HTTP variables to the log.  

 

Cookie and hidden field security  

Enable or disable cookies and hidden fields during web server to iPlanet Application Server communication.  

 

CGI flag for CGI request processing  

Set a flag to process requests in CGI mode when that is necessary.  

 

The plug-in port number  

Reconfigure the port number used by the plug-in.  

 

Configuring HTTP variables as input for application components  

Determine which HTTP variables can be accessed by application components.  

 



Manually Configuring a Web Server


When you install iPlanet Application Server, your web server is automatically configured for the Web Connector Plug-in, meaning that all the necessary directories and settings on the web server are updated. However, there may be occasions, when, after you've installed the Web Connector Plug-in, you must manually re-configure the web server. This procedure is recommended only if you are having problems with the connection between iPlanet Application Server and your web server.

The following steps explain how to manually configure a web server to use the Web Connector Plug-in, whether your web server resides on the same or a different machine than where iPlanet Application Server is installed.

If you perform only step one of the following procedure (enabling CGI), the Web Connector Plug-in will run as a CGI script. If you perform the entire procedure, the Web Connector Plug-in will run as a plug-in, which is more efficient since a plug-in is faster than a CGI script.

You must be logged in as the same administrator user who installed the web server.

The following topics are described in this section:


Configuring iPlanet Web Server

To reconfigure an iPlanet Web Server, perform the following steps:

  1. Enable CGI, if it is not already enabled:

    1. On Windows, from the Start menu, select iPlanet Web Server> Administer Web Servers.

    2. Enter the administrator ID and password, and click OK.

    3. On the iPlanet Server Selector screen, choose the web server instance you want to configure from the drop-down list and click Manage.

    4. Click Programs, from the menu toolbar.

    5. On the CGI directory screen under URL prefix, type cgi-bin.

    6. Under CGI directory, enter the cgi-bin path.

    For iPlanet Web Server 4.1, Windows:

       <drive letter>:\Netscape\Server4\docs\cgi-bin

    For iPlanet Web Server 4.1, Solaris:

       <iWSInstallDir>/docs/cgi-bin

    Now you are ready to configure the Web Connector Plug-in.

  2. Edit the file obj.conf (till iWS 4.1) or magnus.conf (from iWS 6.0 onwards) in the web server configuration directory.

    For iWS4.1, the file obj.conf will hold all the changes. For iWS6.0 and above, the file magnus.conf will also be modified.

    For iPlanet Web Server 4.1, Windows, modify the file obj.conf in the following path:

       drive letter:\Netscape\Server4\https-machinename\config

    For iPlanet Web Server 4.1, Solaris, modify the file obj.conf in the following path:

       iWSInstallDir/https-machinename/config

    Make a copy of the file before modifying it. At the end of the Init section of the obj.conf file, add the following as two lines:

    • Windows:

            Init fn="load-modules"
               funcs=nas_name_trans,gxrequest,gxlog,gxinit,gxredirect,
               gxhtmlrequest shlib="<path to iAS bin dir>\gxnsapi6.dll>

            Init fn="gxinit"

    • Solaris:

            Init fn="load-modules"
               funcs=nas_name_trans,gxrequest,gxlog,gxinit,gxredirect,
               gxhtmlrequest shlib="libgxnsapi6.so"

            Init fn="gxinit" LateInit=yes

    Specify the following for shlib, iPlanet Enterprise Web Server 4.1:

    • Windows:

            <iASInstallDir>\bin\gxnsapi6.dll

    • Solaris:

            <iASInstallDir>/gxlib/libgxnsapi6.so

The following changes need to be made to the obj.conf file (for all versions of iPlanet Web Server).

  1. In the Object name=default section, just after type=text/plain section, add the following line:

       Service fn="gxredirect" fnname="imagemap" method="(GET|HEAD)"

  2. In the Object name=cgi section(s), insert the following line immediately before the line Service fn="send-cgi":

       Service fn="gxrequest"

    And then insert the following line immediately after the line Service fn="send-cgi":

       AddLog fn="gxlog"

  3. Make a copy of the current version of the file obj.conf and the file magnus.conf and copy them to the back up version (so that the backup is consistent with the current version) in the following directory:

    For Windows:

       drive letter:\iPlanet\SuiteSpot\https-machinename\conf_bk

    For Solaris:

       iPlanet install directory/https-machinename/conf_bk

  4. Solaris only: Modify the web server's start and stop scripts as follows:

    In the start script:

    Set GX_ROOTDIR to the directory in which iPlanet Application Server is installed. For example:

       GX_ROOTDIR=iASInstallDir; export GX_ROOTDIR

  5. Restart the web server.


Configuring Apache Web Server

Apache Web Server 1.3.19 is supported in the iPlanet Application Server 6.5 release. To use the Apache Web server with the iPlanet Application Server's Web Connector Plug-in, a few manual configuration steps have to be performed.

You must install and configure the Apache Web Server on the machine on which the Web Connector Plug-in is installed.

Note To use the Apache Web Server, you must select either the iPlanet Web Server or Microsoft Internet Information Server (on Windows only) during the application server installation. After installing the iPlanet Application Server, install and configure the Apache Web Server.



To Install Apache Web Server on Solaris

  1. Download the Apache web server 1.3.19 source files from the Apache Web site at www.apache.org and unpack the tar.gz file.


    Note
    • ar should be in your PATH.

    • The owner/group of iPlanet Application Server and Apache should be the same. By default, Apache runs as nobody:nobody.

      If you need to change the owner/group of iPlanet Application Server files say, to nobody:nobody, then type the following command:

      chown -R nobody:nobody <iASInstallDirectory/ias/>

    • Apache recommends that the Web server not be run as root. For more information, see the Apache Web site.

      To run as root, set the shell variable EXTRA_CFLAGS to -DBIG_SECURITY_HOLE, before compiling.

    • If you are using an older version of GNU binutils (2.7 or earlier), pass the option -export-dynamic to the GNU linker.

      Without this option, the runtime linker will not be able to resolve certain Apache symbols referred in the plugin and the web server will crash when you start it.


  2. Go to the root directory where the source files are saved and run:

    ./configure --prefix=<Installation_Directory>
    --enable-module=so --with-port=<PortNo.>
    make
    make install


    Note
    • enable-module=so is mandatory

    • The port number value is optional, as it is set to 80, by default.


    The Apache control script is called apachectl and is available in the bin directory of the installation.

    To start the script, type:

    apachectl start

    To stop, type

    apachectl stop


To Configure Apache Web Server on Solaris

  1. Add the shell variables GX_ROOTDIR, LD_LIBRARY_PATH and LD_PRELOAD to the apachectl script:

    Code Example 7-1   

    # Additions for the iPlanet Application Server
    #
    GX_ROOTDIR=<iASInstallDir>/ias
    export GX_ROOTDIR
    LD_LIBRARY_PATH=${GX_ROOTDIR}/gxlib:$LD_LIBRARY_PATH
    export LD_LIBRARY_PATH
    LD_PRELOAD=${GX_ROOTDIR}/gxlib/libiasdl.so
    export LD_PRELOAD
    #


    Note
    • Replace <iASInstallDir> with the installation directory of iPlanet Application Server.

    • Replace <ApacheInstallDir> with the installation directory of Apache web server.

    • The lines with LD_PRELOAD are required only for Solaris 2.6.


  2. Add the following lines at the end of <ApacheInstallDir>/conf/httpd.conf

    Code Example 7-2   
    # Additions for the iPlanet Application Server

    #

    LoadModule nas_module <iASInstallDir>/ias/gxlib/libiASApachePlugin.so

    AddModule iASApacheInterface.cpp

    <Location "/">

    SetHandler ias-handler

  3. Copy the <iASInstallDir>/ias/GXApp and <iASInstallDir>/ias/ias-samples directories to the <apacheInstallDir>/htdocs/ directory.

    The minimum, maximum and the starting number of Web servers can be controlled by the following keys in conf/httpd.conf. These are the default values provided by Apache:

    MinSpareServers 5

    MaxSpareServers 10

    StartServers 5

    All the web servers write to the same log file.

  4. Modify the iPlanet Application Server registry using kregedit, as given in "Configuring iPlanet Application Server Registry".


Installing Apache on Windows

Download and install the binaries for Apache 1.3.19 from the Apache Web site at www.apache.org. For more information on installing Apache on Windows, follow instructions on the Apache Web site.


To Configure Apache Web Server on Windows

  1. Add the path of the Apache executable in the system variable PATH.

  2. Add the path of iASApachePlugin.dll (the Web Connector Plug-in) to the system variable PATH.

    The path will be <iASInstallDir>/ias/bin.


    Note
    • Replace <iASInstallDir> with the installation directory of iPlanet Application Server.


  3. Add the following lines at the end of <ApacheInstallDir>/conf/httpd.conf

Code Example 7-3   
#Additions for the iPlanet Application Server
#
LoadModule nas_module <iASInstallDir>/ias/bin/iASApachePlugin.dll
AddModule iASApacheInterface.cpp
<Location "/">
SetHandler ias-handler
</Location>

  1. Copy the <iASInstallDir>/ias/GXApp and <iASInstallDir>/ias/ias-samples directories to the <ApacheInstallDir>/htdocs/ directory.

  2. Modify the iPlanet Application Server registry using kregedit, as given in "Configuring iPlanet Application Server Registry"".


Configuring iPlanet Application Server Registry

After installation, use kregedit to modify the following keys in the iPlanet Application Server registry.

  1. Set SOFTWARE/iPlanet/Application Server/6.5/CCS0/HTTPAPI/HTTPPort to the listening port of the Apache web server.

  2. Set SOFTWARE/iPlanet/Application Server/6.5/CCS0/HTTPAPI/PATH and SOFTWARE/iPlanet/Application Server/6.5/deployment/LogicalName/WWW_DOCROOT to the document root directory.

  3. Append the document root directory, <Apache_Installation_Directory>/htdocs, to SOFTWARE/iPlanet/Application Server/6.5/CCS0/TEMPLATE/PATH, separated by semi colons.


Configuring Microsoft Internet Information Server

Keep in mind the following information when reconfiguring Microsoft IIS:

  • Rename the gxisapi.dll library to gx.dll and leave it in the cgi-bin directory of the IIS wwwroot (inetput/wwwroot/cgi-bin/).

  • Configure the ISAPI filter file, gx.dll, in the following registry entry:

       My Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services

       \W3SVC\Parameters\

    A string key, Filter DLLs, should be added under Parameters, with the following value:

    <drive letter>:\inetpub\wwwroot\cgi-bin\gx.dll

  • The Webconnector Plugin will throw exceptions if it doesn't have permission to write to the Windows registry.

    Follow these instructions to enable the Plugin to modify the registry:

    1. Open the Windows registry editor.

    2. Go to \\HKEY_LOCAL_MACHINE\SOFTWARE\iPLANET\Application Server\6.5\CCSO\HTTPAPI.

    3. From the menu options, open the Permission Definition key.

    4. Change the permission from Special Access to Full Control.

    5. Enable the changes for the subkeys.

    6. Click Apply Changes to commit the modifications.



Configuring the Web Connector Plug-in for Web Server Logging

Web server requests are divided into components. Each component is represented by an HTTP variable. HTTP variables are standardized across all web servers, so the configurations you make with regard to their use are web- server independent.

This section describes the following topics:


Mapping HTTP Variables to Database Fields

To enable logging of a particular component of a web server request, you must map HTTP variables to specific database fields to ensure that web server requests are properly logged. Mapping HTTP variables to database fields is done in the Web Connector Plug-in on the web server machine. The web server machine may or may not be the same machine where you installed iPlanet Application Server.

To map HTTP variables to database fields, perform the following steps:

  1. Open the iPlanet Registry Editor by typing kregedit at the command line.

    The editor tool opens and displays the keys and values that apply to iPlanet Application Server. If the web server and iPlanet Application Server are installed on separate machines, the editor opens and displays the keys and values that apply to the Web Connector Plug-in.

  2. Open the following key:

       SOFTWARE\iPlanet\Application Server\6.5\CCS0\HTTPLOG\INPUTVARS

    Each value under this key represents an HTTP variable and the database field to which the variable is mapped.

    The ID of the value is the HTTP variable. The string value is the database field.

    The HTTP variable is in ALL CAPS, such as HTTP_REFERER, and the database field is exactly as it appears in the database table.

  3. Double-click the HTTP variable you want to map to a database field.

    The String editor dialog box appears.

  4. Enter the database field name as the value data and click OK.

  5. Leave any HTTP variables you do not want to log blank.

  6. Close the editor.

See your web server documentation for an explanation of the HTTP variables.

Use the iPlanet Registry Editor to modify the Web Connector Plug-in.


Adding HTTP Variables to the Log

You can also modify the list of available HTTP variables, adding variables to the list to expand your logging options.

To add HTTP variables to the log, perform the following steps:

  1. Open the iPlanet Registry Editor by typing kregedit at the command line.

    The editor opens and displays the keys and values that apply to iPlanet Application Server. If the web server and iPlanet Application Server are installed on separate machines, the editor opens and displays the keys and values that apply to the Web Connector Plug-in.

  2. Open the following key:

       SOFTWARE\iPlanet\Application Server\6.5\CCS0\HTTPLOG\INPUTVARS

    Each value under this key represents an HTTP variable and the database field to which the variable is mapped.

    The ID of the value is the HTTP variable. The string value is the database field.

    The HTTP variable is in ALL CAPS, such as HTTP_REFERER, and the database field is exactly how it appears in the database table.

  3. Add a new String value with the new HTTP variable name.

  4. Click OK.

  5. Repeat steps 3 through 5 for each new HTTP variable.

  6. Close the editor.

See your web server documentation for a list and an explanation of all available HTTP variables.



Configuring Cookie and Hidden Field Usage


iPlanet Application Server is designed to work with web browsers in all modes of cookie and hidden-field security. There are three configurations you can set for the Web Connector Plug-in to support the various security modes. These configurations are described in the following table:


Table 7-2    Configurations to Support Security Modes

Cookie setting

Description

0  

Cookies and hidden fields are passed back to the requesting web browser. This is the default setting.  

1  

Only hidden fields are passed back to the requesting web browser.  

2  

Only cookies are passed back to the requesting web browser.  

To configure cookie and hidden field usage, perform the following steps:

  1. Open the iPlanet Registry Editor by typing kregedit at the command line.

    The editor tool opens and displays the keys and values that apply to iPlanet Application Server. If the web server and iPlanet Application Server are installed on separate machines, the registry editor opens and displays the keys and values that apply to the Web Connector Plug-in.

  2. Open the following key:

       SOFTWARE\iPlanet\Application Server\6.5\CCSO\HTTPAPI

  3. Double-click the NoCookie DWORD value.

    The DWORD editor dialog box appears.

  4. To disable cookies being passed to the web browser, change the value data to 1.

  5. To disable hidden fields being passed to the web browser, change the value data to 2.

  6. To enable both cookie and hidden fields, change the value data to 0.

  7. When finished, close the editor.



Configuring URL Rewriting

iPlanet Application Server provides the user the choice of either using implicit URL rewriting (the default method), or explicit URL rewriting.

By default, implicit URL rewriting is enabled. To enable explicit URL rewriting, use kregedit to modify the default=implicit key in the iPlanet Application Server registry path:

SOFTWARE/iPlanet/Application Server/6.0/CCS0/HTTPAPI/URLRewrite

To enable explicit URL rewriting, change the value default=implicit to default=explicit.

Implicit URL rewriting is performed by the WebConnector Plugin and does not require any changes to the code by the developer. To enable Explicit URL Rewriting, which is performed by the Web container, developers have to modify the Servlet or JSP code to make explicit calls to encodeURL and encodeRedirectURL.

For more information on URL Rewriting, see iPlanet Application Server Developer's Guide.



Configuring a CGI Flag for CGI Requests


Some requests must be processed in CGI mode. You can set a flag in the Web Connector Plug-in to identify those requests.

To configure a CGI flag for CGI requests, perform the following steps:

  1. Open the iPlanet Registry Editor by typing kregedit at the command line.

    The editor opens and displays the keys and values that apply to iPlanet Application Server. If the web server and iPlanet Application Server are installed on separate machines, the editor opens and displays the keys and values that apply to the Web Connector Plug-in.

  2. Open the following key:

       SOFTWARE\iPlanet\Application Server\6.5\CCSO\HTTPAPI

  3. Double-click the AgentToken String value.

    The String Editor dialog box appears.

  4. For the value data, enter the flag that marks requests for CGI mode processing.

  5. Click OK.

  6. Close the editor.



Changing the Web Connector Port Number

In certain configurations, the web connector port number might conflict with another software package. You can reconfigure the connector port number to resolve this conflict.

To change the Web Connector Plug-in port number, perform the following steps:

  1. Open the iPlanet Registry Editor. by typing kregedit at the command line.

    The editor opens and displays the keys and values that apply to iPlanet Application Server. If the web server and iPlanet Application Server are installed on separate machines, the editor opens and displays the keys and values that apply to the Web Connector Plug-in.

  2. Open the following key:

       SOFTWARE\iPlanet\Application Server\6.5\CCSO\HTTPAPI

  3. Double-click the ListenPort DWORD value and change the value data to an available port number.

  4. Click OK.

  5. Close the editor.



Specifying HTTP Variables for Input to Application Components

HTTP variables can be passed as part of the application request to application components like Enterprise Java Beans (EJBs). This allows the developer to determine certain information about the request and use that information when processing the request.

For example, the application might look at the HTTP_REFERER variable to determine where the request is coming from. This information might be used to present a more individualized greeting screen, or to keep statistics about where requests originate.

You edit entries in the registry to manage the HTTP variables. You can enable and disable them as desired. By default, iPlanet Web Server provides the following HTTP variables:

HTTPS

HTTP_USER_DEFINED

AUTH_USER

HTTPS_KEYSIZE

CLIENT_CERT

HTTPS_SECRETKEYSIZE

CONTENT_LENGTH

PATH_INFO

CONTENT_TYPE

PATH_TRANSLATED

HOST

QUERY

HTTP_ACCEPT

QUERY_STRING

HTTP_ACCEPT_CHARSET

REMOTE_ADDR

HTTP_ACCEPT_ENCODING

REMOTE_HOST

HTTP_ACCEPT_LANGUAGE

REMOTE_IDENT

HTTP_AUTHORIZATION

REMOTE_USER

HTTP_CONNECTION

REQUEST_METHOD

HTTP_COOKIE

SCRIPT_NAME

HTTP_HOST

SERVER_PORT

HTTP_IF_MODIFIED_SINCE

SERVER_PROTOCOL

HTTP_REFERER

SERVER_SOFTWARE

HTTP_USER_AGENT

SERVER_URL

To specify HTTP variables for input to application components, perform the following steps:

  1. Open the iPlanet Registry Editor by typing kregedit at the command line.

    The editor opens and displays the keys and values that apply to iPlanet Application Server. If the web server and iPlanet Application Server are installed on separate machines, the editor opens and displays the keys and values that apply to the Web Connector Plug-in.

  2. Open the appropriate key:

    • For iPlanet web servers, open the following key:

            SOFTWARE\iPlanet\Application
            Server\6.5\CCSO\HTTPAPI\INPUTNSAPI

    • For Microsoft web servers, open the following key:

            SOFTWARE\iPlanet\Application
            Server\6.5\CCSO\HTTPAPI\INPUTISAPI

    • For Apache web servers, open the following key:

            SOFTWARE\iPlanet\Application
            Server\6.5\CCSO\HTTPAPI\INPUTAPACHE

    Each value name shown represents an HTTP variable. The value determines whether the HTTP variable is passed to iPlanet Application Server with the application request. If the name's value is non-zero, the HTTP variable is passed to the iPlanet Application Server machine with the application request.

    The name is created in ALL CAPS, such as HTTP_REFERER.

  3. Add a name that is the HTTP variable name.

  4. Double-click the new HTTP variable (name) and enter the one of the following as the value:

    • Enter a 0 to disable the HTTP variable.

    • Enter a 1 to enable the HTTP variable.


      Note You can disable any of the default HTTP variables by adding the HTTP variable name and then setting the key name value to 0. For example, you could add ENTITY_HEADER and set its value to 1 and then add HTTP_REFERER (a HTTP variable provided by default) and set its value to 0 to disable it.


  5. Click OK.

  6. Repeat steps 4 through 6 for each HTTP variable you want to add/enable/disable.

  7. Close the editor. You need to restart the Web Server for the changes to take effect.


Previous     Contents     Index     Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated March 06, 2002