7 Common Configuration Tasks

This chapter describes tasks that are common across all the web servers for configuring the plug-ins provided by Oracle. It contains the following sections:

Configuring IPv6 With Plug-Ins

The version 12c (12.2.1.1.0) plug-ins support IPv6. Specifically, the WebLogicHost and WebLogicCluster configuration parameters (see WebLogicCluster and WebLogicHost) now support IPv6 addresses. For example:

<IfModule mod_weblogic.c>
 WebLogicHost [a:b:c:d:e:f]
 WebLogicPort 7002
 ...
</IfModule>

<IfModule mod_weblogic.c>
 WebLogicCluster [a:b:c:d:e:f]:<port>, [g:h:i:j:k:l]:<port>
 
 ....
</IfModule>

You can also use the IPv6 address mapped host name.

Note:

As of Windows 2008, the DNS server returns the IPv6 address in preference to the IPv4 address. If you are connecting to a Windows 2008 (or later) system using IPv4, the link-local IPv6 address format is tried first, which may result in a noticeable delay and reduced performance. To use the IPv4 address format, configure your system to instead use IP addresses in the configuration files or add the IPv4 addresses to the etc/hosts file.

In addition, you may find that setting the DynamicServerList property to OFF in the mod_wl_ohs.conf/mod_wl.conf/iisproxy.ini file also improves performance with IPv6. When set to OFF, the plug-in ignores the dynamic cluster list used for load balancing requests proxied from the plug-in and uses the static list specified with the WebLogicCluster parameter.

Understanding Connection Errors and Clustering Failover

When the plug-in attempts to connect to WebLogic Server, the plug-in uses several configuration parameters to determine how long to wait for connections to the WebLogic Server host and, after a connection is established, how long the plug-in waits for a response. If the plug-in cannot connect or does not receive a response, the plug-in attempts to connect and send the request to other WebLogic Server instances in the cluster. If the connection fails or there is no response from any WebLogic Server in the cluster, an error message is sent.

Figure 7-1 illustrates how the plug-in handles failover.

This section contains the following information:

Possible Causes of Connection Failures

Failure of the WebLogic Server host to respond to a connection request could indicate the following problems:

Physical problems with the host machine
Network problems
Other server failures

Failure of all WebLogic Server instances to respond could indicate the following problems:

WebLogic Server is not running or is unavailable
A hung server
A database problem
An application-specific failure

Tips for Reducing CONNECTION_REFUSED Errors

Under load, a plug-in may receive CONNECTION_REFUSED errors from a back-end WebLogic Server instance. Follow these tuning tips to reduce CONNECTION_REFUSED errors:

Increase the AcceptBackLog setting in the configuration of your WebLogic Server domain.
Decrease the time wait interval. This setting varies according to the operating system you are using. For example:
- On Windows NT, set the TcpTimedWaitDelay on the proxy and WebLogic Server servers to a lower value. Set the TIME_WAIT interval in Windows NT by editing the registry key under HKEY_LOCAL_MACHINE:
```
SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\TcpTimedWaitDelay 
```
  If this key does not exist you can create it as a DWORD value. The numeric value is the number of seconds to wait and may be set to any value between 30 and 240. If not set, Windows NT defaults to 240 seconds for TIME_WAIT.
- On Windows 2000, lower the value of the TcpTimedWaitDelay by editing the registry key under HKEY_LOCAL_MACHINE:
```
SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
```
- On Solaris, reduce the setting tcp_time_wait_interval to one second (for both the WebLogic Server machine and the Apache machine, if possible):
```
$ndd /dev/tcp
 param name to set - tcp_time_wait_interval
 value=1000
```
Increase the open file descriptor limit on your machine. This limit varies by operating system. Using the limit (.csh) or ulimit (.sh) directives, you can make a script to increase the limit. For example:
```
#!/bin/sh
ulimit -S -n 100
exec httpd
```
On Solaris, increase the values of the following tunables on the WebLogic Server machine:
```
tcp_conn_req_max_q tcp_conn_req_max_q0
```

Failover with a Single, Non-Clustered WebLogic Server

If you run only a single WebLogic Server instance the plug-in only attempts to connect to the server defined with the WebLogicHost parameter. If the attempt fails, an HTTP 503 error message is returned. The 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.

The Dynamic Server List

The WebLogicCluster parameter is required to proxy to a list of back-end servers that are clustered, or to perform load balancing among non-clustered managed server instances.

In the case of proxying to clustered managed servers, when you use the WebLogicCluster parameter to specify a list of WebLogic Servers, the plug-in uses that list as a starting point for load balancing among the members of the cluster. After the first request is routed to one of these servers, a dynamic server list is returned containing an updated list of servers in the cluster.

The updated list adds any new servers in the cluster and deletes any that have been shut down, or are being suspended, or are no longer part of the cluster or that have failed to respond to requests. This feature can be controlled by using DynamicServerList. For example, to disable this feature, set DynamicServerList to OFF.

DynamicServerList ON is a preferred performance tuning parameter. It is useful, for example, if a member of a cluster is temporarily down for maintenance or if administrators decide they want to add another member, and not need to restart the web server.

Note:

If DynamicServerList is set to ON, and the list of backend WebLogic Servers specified in WebLogicCluster is not in a cluster, then the behavior would be undefined.

Failover, Cookies, and HTTP Sessions

When a request contains session information stored in a cookie or in the POST data, or encoded in a URL, the session ID contains a reference to the specific server instance in which the session was originally established (called the primary server). A request containing a cookie attempts to connect to the primary server. If that attempt fails, the plug-in attempts to make a connection to the next available server in the list in a round-robin fashion. That server retrieves the session from the original secondary server and makes itself the new primary server for that same session. See Figure 7-1.

Note:

If the POST data is larger than 64K, the plug-in will not parse the POST data to obtain the session ID. Therefore, if you store the session ID in the POST data, the plug-in cannot route the request to the correct primary or secondary server, resulting in possible loss of session data.

Figure 7-1 Connection Failover

Description of "Figure 7-1 Connection Failover"

In this figure, the Maximum number of retries allowed in the red loop is equal to ConnectTimeoutSecs/ConnectRetrySecs.

Failover Behavior When Using Firewalls and Load Directors

In most configurations, the Oracle WebLogic Server Proxy Plug-In 12c (12.2.1.1.0) for iPlanet Web Server sends a request to the primary instance of a cluster. When that instance is unavailable, the request fails over to the secondary instance. However, in some configurations that use combinations of firewalls and load-directors, any one of the servers (firewall or load-directors) can accept the request and return a successful connection while the primary instance of WebLogic Server is unavailable. After attempting to direct the request to the primary instance of WebLogic Server (which is unavailable), the request is returned to the plug-in as "connection reset."

Requests running through combinations of firewalls (with or without load-directors) are handled by WebLogic Server. In other words, responses of connection reset fail over to a secondary instance of WebLogic Server. Because responses of connection reset fail over in these configurations, servlets must be idempotent. Otherwise duplicate processing of transactions may result.

Tuning Oracle HTTP Server and Apache HTTP Server for High Throughput for WebSocket Upgrade Requests

WebLogic Server 12c (12.2.1.1.0) supports deploying WebSocket applications. Oracle WebLogic Server Proxy Plug-In 12c (12.2.1.1.0) for Oracle HTTP Server 12c (12.2.1.1.0) and Apache HTTP Server 2.2.x and 2.4.x can now handle such WebSocket connection upgrade requests and effectively proxy to WebSocket applications hosted within WebLogic Server 12c (12.2.1.1.0) and later. As a result of adding this support, a new configuration parameter WLMaxWebSocketClients is introduced.

The WLMaxWebSocketClients parameter limits the number of active WebSocket connections at any instant of time. The maximum value you can set for this parameter is 75 percent of ThreadsPerChild (Windows) or 75 percent of MaxRequestWorkers (non-Windows). Hence, to tune your HTTP Server for maximum WebSocket connection upgrade requests, set MaxRequestWorkers/ThreadsPerChild to a value that can accommodate WebSocket connections as well. Also, ensure that WLMaxWebSocketClients is set to 75 percent of MaxRequestWorkers/ThreadsPerChild.

Working with Partitions

By doing some manual configuration, Oracle WebLogic Server Proxy Plug-Ins can front-end Oracle WebLogic Server MT (Multi-Tenency).

This section contains the following information:

Note:

This section describes partitions and multi-tenancy only as far as they apply to Oracle WebLogic Server Proxy Plug-Ins. For more information about Oracle WebLogic Server MT, partitions, and multi-tenancy, see Oracle Fusion Middleware Using WebLogic Server MT.

Adding a Partition

Whenever a partition is added on the Oracle WebLogic Server MT side, you must make corresponding changes to the web server configuration to front the new partition. The details of adding a partition itself is documented by Oracle WebLogic Server MT, (see "Configuring Domain Partitions" in Oracle Fusion Middleware Using WebLogic Server MT).

The following sections describe how to make corresponding changes to web server configuration to front-end a newly added partition in Oracle WebLogic Server MT.

Note:

These sections assume that you have already created one or more domain partitions in Oracle WebLogic Server. For more information on creating domain partitions, see "Configuring Domain Partitions" in Oracle Fusion Middleware Using WebLogic Server MT.

Apache Server and Oracle HTTP Server Configuration Changes

The following is a sample configuration that must be added to the Oracle HTTP Server or Apache plug-in configuration file (httpd.conf) for each new partition being added. The configuration identifies the hostname and port of the partition, the server and the WebLogic cluster it belongs to, and any optional URI that is configured for the partition.

Install and configure the plug-in for Oracle HTTP Server or Apache Server. See Preparing for Configuring the Oracle WebLogic Server Proxy Plug-In or Install the Oracle WebLogic Server Proxy Plug-In for Apache HTTP Server.

Edit the httpd.conf file and add the following section for every new partition:

# For OHS: Uncomment the following line
# LoadModule weblogic_module modules/mod_wl_ohs.so
# For Apache 2.2: Uncomment the following line
# LoadModule weblogic_module modules/mod_wl.so
# For Apache 2.4: Uncomment the following line
LoadModule weblogic_module modules/mod_wl_24.so

<VirtualHost hostname_and_port_of_the_partition>
<IfModule mod_weblogic.c>
ServerName server_URL
WebLogicCluster comma_separated_list_of_WebLogic_clusters
SetHandler weblogic-handler
PathPrepend optional_uri_of_the_partition
</IfModule>
</VirtualHost>

After making the configuration change, you must restart the Apache or Oracle HTTP Server.

Oracle HTTP Server/Apache Plug-in Examples

The following examples provide sample configurations for different use cases.

Example 1: Client may not configure the partition path

Assume there are there are two partitions in the domain:

Host Name of the VirtualTarget1 is www.myCompany1.com and the URI Prefix (partition path) is null as configured in Oracle WebLogic Server.
Host Name of the VirtualTarget2 is www.myCompany2.com and the URI Prefix (partition path) is null as configured in Oracle WebLogic Server.

In this case, you do not need to configure the partition path

LoadModule weblogic_module modules/mod_wl_24.so

<VirtualHost *:8080>
<IfModule mod_weblogic.c>
ServerName www.myCompany1.com
WebLogicCluster wls1:7001,wls2:7001,wls3:7001
SetHandler weblogic-handler
</IfModule>
</VirtualHost>

<VirtualHost *:8080>
<IfModule mod_weblogic.c>
ServerName www.myCompany2.com
WebLogicCluster wls1:7002,wls2:7002,wls3:7002
SetHandler weblogic-handler
</IfModule>
</VirtualHost>

This configuration proxies all of the requests coming to myCompany1.com:8080 or myCompany1.com to the managed servers wls1:7001, wls2:7001 and wls3:7001. Similarly, all of the requests coming to myCompany2.com:8080 or myCompany2.com will be proxied to the managed servers wls1:7002, wls2:7002 and wls3:7002.

Example 2: Client may divide the web site by the partition path

Assume there are there are two partitions in the domain:

Host Name of the VirtualTarget1 is www.foo.com and URI Prefix (partition path) is /myCompany1 as configured in Oracle WebLogic Server.
Host Name of the VirtualTarget2 is www.foo.com and URI Prefix (partition path) is /myCompany2 as configured in Oracle WebLogic Server.

In this case, you do not need to configure the partition path:

<VirtualHost *:8080>
<IfModule mod_weblogic.c>
ServerName server1
WebLogicCluster wls1:7001,wls2:7001,wls3:7001
SetHandler weblogic-handler
</IfModule>
</VirtualHost>

The available urls will be:

www.foo.com:8080/myCompany1

www.foo.com:8080/myCompany2

iPlanet Server Configuration Changes

The following is a sample configuration that must be added to the iPlanet Server plug-in configuration file for each new partition being added.

Install the plug-in for iPlanet Server. See Installing and Configuring the Plug-In for iPlanet.

Edit the magnus.conf file to add the following section:

ServerName server_URL
Init fn="load-modules" shlib="path to the /plugin/mod_wl.so file"

For example:

ServerName www.myCompany.com
Init fn="load-modules" shlib="/scratch/plugin/mod_wl.so"/"

Edit the obj.conf file to add the following section for every new partition:

<Object name="weblogic" ppath="*">
Service ChunkedRequestBufferSize="0" fn="wl-proxy" WebLogicCluster="comma_separated_list_of_WebLogic_clusters" PathPrepend="optional_uri_of_the_partition" SecureProxy="OFF" WLIOTimeoutSecs="10"
</Object>

For example:

<Object name="weblogic" ppath="*">
Service ChunkedRequestBufferSize="0" fn="wl-proxy" WebLogicCluster="wls1:7001,wls2:7001,wls3:7001" PathPrepend="/partition1" SecureProxy="OFF" WLIOTimeoutSecs="10"
</Object>

After making the configuration change, you must restart the iPlanet Server.

IIS Server Configuration Changes

The following is a sample configuration that must be added to the Microsoft IIS plug-in configuration file for each new partition being added.

Install the plug-in for Microsoft IIS Server. See Installing and Configuring the Microsoft IIS 7.5 Plug-In.
Open IIS Manager and create a new Web Site.

Set Host name. For example, set it to www.myCompany.com.
Add the plug-in to the IIS server.

Click Handler Mappings in IIS Manager to set the mappings to the handler for a particular MIME type.

Create a plug-in configuration file:

Create a file named iisproxy.ini with the following content and place it in the directory with the plug-in. Create similar content in the file for every new partition:

WebLogicCluster=comma_separated_list_of_WebLogic_clusters
Debug=ALL
WLLogFile=path to the wlproxy.log file
PathPrepend=optional_uri_of_the_partition
SecureProxy=OFF
WLIOTimeoutSecs=10

For example:

WebLogicCluster=wls1:7001,wls2:7001,wls3:7001
Debug=ALL
WLLogFile=C:/pp_iis_home/myCompany/logs/iis7.0_wlproxy.log
PathPrepend=/partition1
SecureProxy=OFF
WLIOTimeoutSecs=10

After making the configuration change, you must restart the Microsoft IIS Server.

Modifying a Partition and Partition Migration

Partition migration is an Oracle WebLogic Server MT feature. You cannot migrate partitions on the Oracle WebLogic Server Proxy Plug-In side. Once the partition is migrated, the Oracle WebLogic Server Proxy Plug-In configuration must be updated manually to use the new partition information.

For more information on partition migration, see "Exporting and Importing Partitions" in Oracle Fusion Middleware Using WebLogic Server MT.

If you make any changes in the partition on the Oracle WebLogic Server side, you must make corresponding changes in the plug-in configuration. On the Oracle WebLogic Server side you can typically change the VirtualHost parameters (host and port) and the optional URI. In this case, you must edit the ServerName and PathPrepend parameters in the plug-in configuration.

If you add, delete, or migrate managed servers on the Oracle WebLogic Server side, you must also make corresponding changes in the plug-in configuration.

For example, assume you have the following Oracle HTTP Server (or Apache) plug-in configuration:

<VirtualHost *:8080>
<IfModule mod_weblogic.c>
ServerName server1
WebLogicCluster wls1:7001,wls2:7001,wls3:7001
SetHandler weblogic-handler
</IfModule>
</VirtualHost>

If you add managed server wls4 to the partition, Then add wls4 to the WebLogicCluster parameter:

<VirtualHost *:8080>
<IfModule mod_weblogic.c>
ServerName server1
WebLogicCluster wls1:7001,wls2:7001,wls3:7001,wls4:7001
SetHandler weblogic-handler
</IfModule>
</VirtualHost>

If you delete managed server wls1 from the partition, Then delete wls1 from the WebLogicCluster parameter:

<VirtualHost *:8080>
<IfModule mod_weblogic.c>
ServerName server1
WebLogicCluster wls2:7001,wls3:7001,wls4:7001
SetHandler weblogic-handler
</IfModule>
</VirtualHost>

If you migrate managed server wls2 to wls5 then remove wls2 and add wls5 to the WebLogicCluster parameter:

<VirtualHost *:8080>
<IfModule mod_weblogic.c>
ServerName server1
WebLogicCluster wls3:7001,wls4:7001,wls5:7001
SetHandler weblogic-handler
</IfModule>

For information on modifying a partition of the Oracle WebLogic Server side, see "Configuring Domain Partitions," "Configuring Virtual Targets," and "Exporting and Importing Partitions," in Oracle Fusion Middleware Using WebLogic Server MT.

Configuring SSL Between the Web Server and Oracle WebLogic Server

You configure SSL on Oracle WebLogic Server MT in the same way as with Oracle WebLogic Server, however, the partitions that are targeted to the same host name should have same certificate.

Dynamic Discovery of Cluster Changes

The dynamic discovery of cluster changes is a feature of both Oracle WebLogic Server Proxy Plug-In and Oracle WebLogic Server. It is not affected by Multitenancy. This feature can be controlled by the DynamicServerList parameter. For more information, see DynamicServerList.