2 Configuring the Plug-In for Oracle HTTP Server

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

Note:

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

You can configure the Oracle WebLogic Server 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:

Section 2.1, "Support Note"
Section 2.2, "Prerequisites for Configuring the Plug-In"
Section 2.3, "Configuring the Plug-In Using Fusion Middleware Control"
Section 2.4, "Configuring the Plug-In Manually"
Section 2.5, "Deprecated Directives for Oracle HTTP Server"
Section 2.6, "Troubleshooting Oracle WebLogic Server Proxy Plug-In Implementations"

2.1 Support Note

The Oracle WebLogic Server Proxy Plug-In for Oracle HTTP Server is now able to front-end WebSocket applications.

2.2 Prerequisites for Configuring the Plug-In

Before you begin configuring the Oracle WebLogic Server 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. Oracle HTTP server and WebLogic Server can be installed either in same domain or in separate domains.
Verify that Fusion Middleware Control has been installed and you can access the Enterprise Manager Console. This is required if you want configure the Oracle WebLogic Server Proxy Plug-In by using the graphical interface provided by Fusion Middleware Control.
To be able to test the configuration, ensure 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 Yes from the WebLogic Plug-In Enabled drop-down list. Yes must be selected if the WebLogic Plug-ins are used with the WebLogic Server. For more information, see Section 2.2.1, "Understanding the WebLogic Plug-In Enabled Parameter."
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.1 Understanding the WebLogic Plug-In Enabled Parameter

The WebLogic Plug-In Enabled drop-down list contains these values:

Yes—Yes must be selected if the WebLogic Plug-ins are used with the WebLogic Server. When set to Yes on the server, it specifies that this server uses the proprietary WL-Proxy-Client-IP header, which is recommended if the server instance will receive requests from a proxy plug-in.

When set to Yes on the cluster, it specifies that the cluster will receive requests from a proxy plug-in or HttpClusterServlet. A call to getRemoteAddr will return the address of the browser client from the proprietary WL-Proxy-Client-IP header, instead of the Web server.
No—Selecting No for the server or cluster disables the weblogic-plugin-enabled parameter (weblogic-plugin-enabled=false) in the config.xml file.
Inherit—When Inherit is selected for WebLogic Plug-In Enabled in the servers page, then the servers will inherit the value selected for WebLogic Plug-In Enabled for the cluster. When Inherit is selected for WebLogic Plug-In Enabled in the clusters page, then the clusters will inherit the value selected for WebLogic Plug-In Enabled for the domain.

2.3 Configuring the Plug-In Using Fusion Middleware Control

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

Ensure you have fulfilled the prerequisites listed in Section 2.2.
Select Administration from the Oracle HTTP Server menu.
Select mod_wl_ohs Configuration from the Administration menu. The mod_wl_ohs Configuration page appears.

Description of the illustration ''mod_wl_ohs.gif''

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.3.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 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.3.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 terminated 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 cannot 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 and 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.

If necessary, add any expression overrides in the Match Expression field.
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.3.2, "Using the AutoFill Function").
4. For the Path Trim field, according to 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, according to 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 must append a File Name, use the DefaultFileName module parameter instead of Path Prepend.
6. Click Add Row again to save the new row
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.
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.3.1 Using the Search Function

By clicking the search icon , 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:

Click the search icon for either WebLogic Cluster or WebLogic Host. The Select WebLogic Cluster/Server dialog box appears.
Select the cluster or server you want to use and click OK.

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

2.3.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 Oracle WebLogic Server Proxy Plug-In Configuration screen by using the AutoFill button. To do so:

Click Add to add a new location,
Type a location name in the Location field.
Click AutoFill.

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

2.4 Configuring the Plug-In Manually

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

Ensure you have fulfilled the prerequisites listed in Section 2.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
Look for the <IfModule weblogic_module> element.
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 Oracle WebLogic Server 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. All of 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 Oracle WebLogic Server 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, one of the following lines also must be added.
```
WLProxySSL ON
WLProxySSLPassThrough ON
```
  (to help determine which of parameter to use, see Section 7.2, "SSL Parameters for Web Server Plug-Ins")
  
  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.
  
  For more information, see "Terminating SSL Requests" in Administering Oracle HTTP 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 Oracle WebLogic Server 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.".
Restart Oracle HTTP Server by using one of the techniques described in "Starting Oracle HTTP Server", in Administering Oracle HTTP Server.

2.5 Deprecated Directives for Oracle HTTP Server

The WebLogic Server plug-in logs for Oracle WebLogic Server 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.6 Troubleshooting Oracle WebLogic Server Proxy Plug-In Implementations

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

Oracle WebLogic Server Session Issues
CONNECTION_REFUSED Errors
NO_RESOURCES Errors

2.6.1 Oracle WebLogic Server Session Issues

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

If the request is routed to a single WebLogic Server instance, the Oracle WebLogic Server 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 WebLogic Server server is marked as bad, and the request is routed to the next available WebLogic Server 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.6.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.6.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 Oracle WebLogic Server Proxy Plug-In. This can be resolved by setting WLSocketTimeoutSecs to a higher value. This allows the Oracle WebLogic Server Proxy Plug-In to wait longer for the connect request to be responded by the WLS server.