2 Configuring the WebLogic Proxy Plug-In for Oracle HTTP Server

This chapter describes how to configure the WebLogic Proxy Plug-In (mod_wl_ohs), which is the plug-in for proxying requests from Oracle HTTP Server to Oracle WebLogic server. The WebLogic Proxy Plug-In is included in the Oracle HTTP Server 12.1.2 installation. You need not download and install it separately.

Note:

The WebLogic Proxy Plug-In provides features that are identical to those of the plug-in for Apache HTTP Server.

You can configure the WebLogic Proxy Plug-In either by using Fusion Middleware Control or by editing the mod_wl_ohs.conf configuration file manually.

This chapter contains the following topics:

2.1 Prerequisites for Configuring the WebLogic Proxy Plug-In

Before you begin configuring the WebLogic Proxy Plug-In, do the following:

  • Ensure that Oracle WebLogic Server has been installed, a domain has been created, and you can access the Oracle WebLogic Server administration console.

  • Verify that Fusion Middleware Control has been installed and you can access the Enterprise Manager Console. This is required if you want configure the WebLogic Proxy Plug-In by using the graphical interface provided by Fusion Middleware Control.

  • To be able to test the configuration, make sure that the required Java applications are deployed to Oracle WebLogic Server—either to a single managed server or to a cluster—and are accessible.

  • If the version of the Oracle WebLogic Server instances in the back end is 10.3.4 (or later releases), you must set the WebLogic Plug-In Enabled parameter.

    1. Log in to the Oracle WebLogic Server administration console.

    2. In the Domain Structure pane, expand the Environment node.

      • If the server instances to which you want to proxy requests from Oracle HTTP Server are in a cluster, select Clusters.

      • Otherwise, select Servers.

    3. Select the server or cluster to which you want to proxy requests from Oracle HTTP Server.

      The Configuration: General tab is displayed.

    4. Scroll down to the Advanced section, expand it, and select the WebLogic Plug-In Enabled checkbox.

    5. If you selected Servers in step 2, repeat steps 3 and 4 for the other servers to which you want to proxy requests from Oracle HTTP Servers.

    6. Click Save.

    For the change to take effect, you must restart the server instances.

2.2 Configuring the WebLogic Proxy Plug-In Using Fusion Middleware Control

To configure the mod_wl_ohs module using Fusion Middleware Control, do the following:

  1. Make sure that you have fulfilled the prerequisites listed in Section 2.1.

  2. Select Administration from the Oracle HTTP Server menu.

  3. Select mod_wl_ohs Configuration from the Administration menu. The mod_wl_ohs Configuration page appears.

    Description of mod_wl_ohs.gif follows
    Description of the illustration mod_wl_ohs.gif

  4. Specify the configuration settings as described in the following table:

    Field Description
    WebLogic Cluster List of Oracle WebLogic Servers that can be used for load balancing. The server or cluster list is a list of host:port entries. If a mixed set of clusters and single servers is specified, the dynamic list returned for this parameter will return only the clustered servers.

    If you are not sure if the correct cluster, you can click the search icon to see a list of all associated clusters. For more information, see Section 2.2.1, "Using the Search Function".

    The module does a simple round-robin between all available servers. The server list specified in this property is a starting point for the dynamic server list that the server and module maintain. Oracle WebLogic Server and the module work together to update the server list automatically with new, failed, and recovered cluster members.You can disable the use of the dynamic cluster list by disabling the Dynamic Server List ON field. The module directs HTTP requests containing a cookie, URL-encoded session, or a session stored in the POST data to the server in the cluster that originally created the cookie.

    Note: WebLogic Cluster and WebLogic Host are mutually-exclusive fields; you should only specify one. If you provide a value for both fields, WebLogic Cluster takes precedence.

    WebLogic Host Oracle WebLogic Server host (or virtual host name as defined in Oracle WebLogic Server) to which HTTP requests should be forwarded. If you are using a WebLogic cluster, use the WebLogic Cluster parameter instead of WebLogic Host.

    If you are not sure if the correct server, you can click the search icon to see a list of all associated clusters. For more information, see Section 2.2.1, "Using the Search Function".

    Note: WebLogic Host and WebLogic Cluster are mutually-exclusive fields; you should only specify on. If you provide a value for both fields, WebLogic Cluster takes precedence.

    WebLogic Port Port at which the Oracle WebLogic Server host is listening for connection requests from the module (or from other servers). (If you are using SSL between the module and Oracle WebLogic Server, set this parameter to the SSL listen port.)
    Dynamic Server List ON | OFF When set to OFF, the module ignores the dynamic cluster list used for load balancing requests proxied from the module and only uses the static list specified with the WebLogic Cluster parameter. Normally this parameter should be set to ON.

    There are some implications for setting this parameter to OFF:

    • If one or more servers in the static list fails, the module could waste time trying to connect to a dead server, resulting in decreased performance.

    • If you add a new server to the cluster, the module cannot proxy requests to the new server unless you redefine this parameter. Oracle WebLogic Server automatically adds new servers to the dynamic server list when they become part of the cluster.

    Error Page You can create your own error page to appear when your Web server is unable to forward requests to Oracle WebLogic Server.
    WebLogic Temp Directory Specifies the location of the _wl_proxy directory for post data files.
    Exclude Path or MIME Type This parameter allows you exclude certain requests from proxying.

    This parameter can be defined locally at the Location tag level as well as globally. When the property is defined locally, it does not override the global property but defines a union of the two parameters.

    Match Expressions This region is used to specify any Expression overrides. For example, if you were proxying by MIME type, you might enter:
    *.jsp WebLogicHost=myHost|paramName=value
    

    You can define a new parameter for Match Expression by using the following syntax:

    *.jsp PathPrepend=/test PathTrim=/foo
    
    Location This table is used to specify any location overrides. See step 6, below.

  5. If necessary, add any expression overrides in the Match Expression field.

  6. If necessary, add any location overrides in the Location table. To do so:

    1. Click Add Row to create a new row.

    2. Enter the base URI for which the associated directives become effective.

    3. Complete the WebLogic Cluster, WebLogic Host, and WebLogic Port fields. You can automatically complete these fields by clicking AutoFill (see Section 2.2.2, "Using the AutoFill Function").

    4. For the Path Trim field, as per the RFC specification, generic syntax for URL is:

      [PROTOCOL]://[HOSTNAME]:{PORT}/{PATH}/{FILENAME};{PATH_PARAMS}/{QUERY_STRING}...
      

      Path Trim specifies the string trimmed by the module from the {PATH}/{FILENAME} portion of the original URL, before the request is forwarded to WebLogic Server. For example, if the URL:

      http://myWeb.server.com/weblogic/foo
      

      is passed to the module for parsing and if Path Trim has been set to strip off /weblogic before handing the URL to WebLogic Server, the URL forwarded to WebLogic Server is:

      http://myWeb.server.com:7002/foo
      

      Note:

      If you are converting an existing third-party server to proxy requests to WebLogic Server using the module for the first time, you must change application paths to /foo to include weblogic/foo. You can use Path Trim and Path Prepend in combination to change this path
    5. For the Path Prepend field, as per the RFC specification, generic syntax for URL is:

      [PROTOCOL]://[HOSTNAME]:{PORT}/{PATH}/{FILENAME};{PATH_PARAMS}/{QUERY_STRING}...
      

      Path Prepend specifies the path that the module prepends to the {PATH} portion of the original URL, after Path Trim is trimmed and before the request is forwarded to WebLogic Server.

      Note:

      If you need to append File Name, use the DefaultFileName module parameter instead of Path Prepend.
    6. Click Add Row again to save the new row

  7. If the settings are correct, click Apply to apply the changes. If the settings are incorrect or you decide to not apply the changes, click Revert to return to the original settings.

  8. Restart Oracle HTTP Server by selecting Control from the Oracle HTTP Server menu, and then selecting Start Up.

The mod_wl_ohs module configuration is saved and shown on the mod_wl_ohs Configuration page.

2.2.1 Using the Search Function

By clicking the search icon Magnifying glass, you can see a list of clusters or servers available to the selected Oracle HTTP Server instance. To use the search function, do the following:

  1. Click the search icon for either WebLogic Cluster or WebLogic Host. The Select WebLogic Cluster/Server dialog box appears.

  2. Select the cluster or server you want to use and click OK.

The selected cluster or server name appears in the appropriate field.

2.2.2 Using the AutoFill Function

You can easily add valid WebLogic Server and endpoint locations for a specified Base UIRL to the Locations table on the WebLogic Proxy Plug-In Configuration screen by using the AutoFill button. To do so:

  1. Click Add to add a new location,

  2. Type a location name in the Location field.

  3. Click AutoFill.

Data for any location of the same name will be updated and any new locations will be added to the table.

2.3 Configuring the WebLogic Proxy Plug-In Manually

You can configure the WebLogic Proxy Plug-In manually by specifying directives in the mod_wl_ohs.conf file.

  1. Make sure that you have fulfilled the prerequisites listed in Section 2.1.

  2. Open the mod_wl_ohs.conf file, which is located in the following directory, in a text editor:

    DOMAIN_HOME/config/fmwconfig/components/OHS/instances/componentName

  3. Look for the <IfModule weblogic_module> element.

  4. Add directives within the <IfModule weblogic_module> element in the configuration file, as follows:

    Note:

    Oracle recommends that you specify directives within the predefined <IfModule weblogic_module> element.

    If you specify directives outside the predefined <IfModule weblogic_module> element, or in additional <IfModule weblogic_module> elements, or in configuration files other than mod_wl_ohs.conf, the WebLogic Proxy Plug-In might work, but the configuration state of the module, as displayed in Fusion Middleware Control, could be inconsistent with the directives specified in the mod_wl_ohs.conf configuration file.

    • To forward requests to an application running on a single Oracle WebLogic Server instance, specify the details of that destination server within a <location> element.

      Syntax:

      <IfModule weblogic_module>
      <Location path>
      WLSRequest On
      WebLogicHost host
      WeblogicPort port
      </Location>
      </IfModule>
      

      Example:

      With the following configuration, requests for the /myapp1 URI received at the Oracle HTTP Server listen port will be forwarded to /myapp1 on the Oracle WebLogic Server with the listen port localhost:7001

      <IfModule weblogic_module>
      <Location /myapp1>
      WLSRequest On
      WebLogicHost localhost
      WeblogicPort 7001
      </Location>
      </IfModule>
      
    • To forward requests to an application running on a cluster of Oracle WebLogic Server instances, specify the details of that destination cluster within a new <location> element.

      Syntax:

      <IfModule weblogic_module>
      <Location path>
      WLSRequest On
      WebLogicCluster host:port,host:port,...
      </Location>
      </IfModule>
      

      Example:

      With the following configuration, requests for the /myapp2 URI received at the Oracle HTTP Server listen port will be forwarded to /myapp2 the Oracle WebLogic Server cluster containing the managed servers with the listen ports localhost:8002 and localhost:8003.

      <IfModule weblogic_module>
      <Location /myapp2>
      WLSRequest On
      WebLogicCluster localhost:8002,localhost:8003
      </Location>
      </IfModule>
      
    • To configure multiple destinations—say, an application running on a single Oracle WebLogic Server instance and another application running on a cluster—you must specify each destination in a distinct <location> child element. Note that all the <location> child elements should be at the same level within the <IfModule weblogic_module> element, as shown in the following syntax:

      <IfModule weblogic_module>
      #For an application running on a single server instance
      <Location path1>
      WLSRequest On
      WebLogicHost host
      WeblogicPort port
      </Location>
      
      #For an application running on a cluster
      <Location path2>
      WLSRequest On
      WebLogicCluster host:port,host:port,...
      </Location>
      
      </IfModule>
      
    • To configure the WebLogic Proxy Plug-In so that it can link to managed servers, for example to enable a high availability deployment of Oracle HTTP Server, edit mod_wl_ohs.conf as follows:

      <IfModule mod_weblogic.c>
            WebLogicCluster apphost1.mycompany.com:7050, apphost2.mycompany.com:7050
            MatchExpression *.jsp
       </IfModule>
        
      <Location /weblogic>
        WLSRequest On
        WebLogicCluster apphost1.mycompany.com:7050,apphost2.com:7050
        DefaultFileName index.jsp
      </Location>
      

      Note:

      If you are using SSL termination and routing requests to WebLogic, the following additional configuration is required.

      In the WebLogic console, WebLogic Plugin Enabled must be set to true, either at the domain, cluster or Managed Server level.

      In the Location block which directs requests to the WebLogic managed servers, the following lines also need to be added.

      WLProxySSL ON
      WLProxySSLPassThrough ON
      

      For example:

      <Location /weblogic>
        WLSRequest On
        WebLogicCluster apphost1.mycompany.com:7050,apphost2.com:7050
        WLProxySSL On
        WLProxySSLPassThrough ON
        DefaultFileName index.jsp
      </Location>
      

      After enabling the WebLogic plugin, restart the Administration Server.

      These examples show two different ways of routing requests to Oracle WebLogic managed servers:

      • The <ifModule> block sends any requests ending in *.jsp to the WebLogic Managed Server cluster located on Apphost1 and Apphost2.

      • The <Location> block sends any requests with URLs prefixed by /weblogic to the WebLogic Managed Server cluster located on Apphost1 and Apphost2.

    • For information about configuring the WebLogic Proxy Plug-In to support one-way and two-way SSL between Oracle HTTP Server and Oracle WebLogic Server, see Use SSL with Plug-Ins.

    For information about the other directives that you can specify in the mod_wl_ohs.conf file, see Chapter 7, "Parameters for Web Server Plug-Ins.".

  5. Restart Oracle HTTP Server by using one of the techniques described in "Starting Oracle HTTP Server", in Administering Oracle HTTP Server.

2.4 Deprecated Directives for Oracle HTTP Server

The WebLogic Server plug-in logs for WebLogic Proxy Plug-In are now part of the Web Server error log mechanism. References are prefixed with weblogic: to easily identify them; for example:

[Fri Dec 27 12:09:14 2013] [debug] ap_proxy.cpp(143): [client 192.168.1.123]
weblogic: INFO: SSL is configured, referer:@ https://example.com/app/fileUploadAction.do

The directives WLLogFile and Debug are deprecated. If the configuration still uses any of these directives, the following note will appear in the console log file:

The WLLogFile directive is ignored. The web server log file is used instead. The Debug directive is ignored. The web server log level is used instead.

To enable plug-in logs:

  • If OraLogMode is set to ODL-text, set OraLogSeverity to TRACE:32. The logs appear in the directory OraLogDir (instance-name.log). This is the default.

  • If OraLogMode is set to apache, set LogLevel to debug. The directive ErrorLog points to the file where the errors are logged.

For more details on Managing Oracle HTTP Server Logs, See "Managing Oracle HTTP Server Logs".

2.5 Troubleshooting WebLogic Proxy Plug-In Implementations

This section describes common problems that you might encounter when using the WebLogic Proxy Plug-In and explains how to solve them. It includes the following topics:

2.5.1 WLS Session Issues

The WebLogic Proxy Plug-In routes the requests to backend WLS server/cluster. WLS maintains sessions so that subsequent requests from the same client are routed to the same WLS server. However, due to various reasons, if the WebLogic Proxy Plug-In is unable to communicate with the WLS server:

  • If the request is routed to a single WebLogic Server instance, the WebLogic Proxy Plug-In continues trying to connect to that same WebLogic Server instance for the maximum number of retries as specified by the ratio of ConnectTimeoutSecs and ConnectRetrySecs. If all attempts fail, an HTTP 503 error message is returned back to the client.

  • If the request is routed to WebLogic Cluster, then the current WLS server is marked as bad, and the request is routed to the next available WLS server. If all attempts fail, an HTTP 503 error message is returned back to the client.

In addition to sending a HTTP 503 error message, the following is displayed as a response in the HTTP client:

Failure of Web Server bridge:
No backend server available for connection: timed out after xx seconds or idempotent set to OFF or method not idempotent.

2.5.2 CONNECTION_REFUSED Errors

Occasionally, under stress conditions, few requests might fail with the following error logged in the error log file.

weblogic: Trying GET /uri at backend host 'xx.xx.xx.xx/port; got exception 'CONNECTION_REFUSED [os error=xxx, line xxxx of URL.cpp]: apr_socket_connect call failed with error=xxx, host=xx.xx.xx.xx, port=xxxx'

As mentioned in Section 6.4.2, "Tips for reducing Connection_Refused Errors", WLS server might have reached the maximum allowed backlog connections.

To resolve, follow the steps mentioned in Section 6.4.2, "Tips for reducing Connection_Refused Errors".

2.5.3 NO_RESOURCES Errors

Occasionally, under stress conditions, few requests might fail with the following error logged in the error log file.

weblogic: *******Exception type [NO_RESOURCES] (apr_socket_connect call failed with error=70007, host=xx.xx.xx.xx, port=xxxx) raised at line xxxx of URL.cpp

This usually occurs if WLS server is too busy to respond to the connect request from the WebLogic Proxy Plug-In. This can be resolved by setting WLSocketTimeoutSecs to a higher value. This allows the WebLogic Proxy Plug-In to wait longer for the connect request to be responded by the WLS server.