Previous     Contents     Index     DocHome     Next     
iPlanet Application Server Admintration 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 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 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 functions:


Table 7-1    Configurable Web Connector 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 will run as a CGI script. If you perform the entire procedure, the web connector 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.

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

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

    1. From the Start menu, go to the iPlanet program group and choose Administer iPlanet 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 box and click Manage.

    4. On the main menu bar across the top of the page, click Programs.

    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 NT:

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

    For iPlanet Web Server 4.1, Unix:

       iASInstallDir/docs/cgi-bin

    Now you are ready to configure the web connector plug-in.

  2. Edit the obj.conf file in the web server configuration directory.

    For iPlanet Web Server 4.1, Windows NT:

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

    For iPlanet Web Server 4.1, Unix:

       iASInstallDir/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 NT:

            Init fn="load-modules"
               funcs=ias_name_trans,gxrequest,gxlog,gxinit,gxredirect,
               gxhtmlrequest shlib="path to iAS bin dir/example:
               gxnsapi351.dll      "

            Init fn="gxinit"

    • Unix:

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

            Init fn="gxinit"

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

    • Windows NT:

            iASInstallDir\bin\gxnsapi351.dll

    • Unix:

            iASInstallDir/gxlib/libgxnsapi30.so

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

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

  4. 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"

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

    For Windows NT:

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

    For Unix:

       iPlanet install directory/https-machinename/conf_bk

  6. Unix 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

  1. Restart the web server.


Reconfiguring the 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:

       c:\inetpub\wwwroot\cgi-bin\gx.dll



Configuring the Web Connector 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.


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.0\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.0\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.0\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 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.0\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 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.0\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.0\CCSO\HTTPAPI\INPUTNSAPI

    • For Microsoft web servers, open the following key:

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

    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.


Previous     Contents     Index     DocHome     Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated February 06, 2001