Web Server Plug-in Coexistence
 Technote (troubleshooting)
 
Problem(Abstract)
You can configure your web server to route requests to both WebSphere® Application Server versions 4.0, 5.0 and 6.0. By loading the plug-in for both versions and merging the plug-cfg.xml files, a single web server can handle requests for both application servers. This document outlines the considerations and limitations for a plug-in coexistence configuration.
 
Cause
You want to configure a single web server to route requests to both a V4.0 application server and a V5.0 application server.
 
Resolving the problem
Statement of Support
IBM supports V4.0.2-4.0.7 and V5.0-5.0.2 plug-in coexistence configurations when the Cumulative plug-in fix for V5.0 dated Sep 3, 2003 or later is installed.

Minimum recommended web server versions for V4.0 and V5.0 plug-in coexistence:
  • IHS 2.0.42.2
  • IHS 1.3.26.2 (IBM recommends IHS 2.0.42.2 instead of IHS 1.3.26.2, whenever possible)
  • iPlanet 6.0.4
  • Domino 5.0.9a
  • Domino 6.0.2
  • IIS 4 on Windows NT
  • Covalent Apache
  • IIS 5 on Windows 2000
  • Covalent Enterprise Ready Server 2.3.2
For more information on prerequisites, review this Web site:

http://www-3.ibm.com/software/webservers/appserv/doc/latest/prereq.html

There are some differences between the V4.0 and V5.0 plug-ins that need to be addressed before the merging the two plugin-cfg.xml files.

Features that are present in the V4.0 plug-in, but not in the V5.0 plug-in:
VHostMatchingCompat flag - this parameter sets how the VirtualHost matching algorithm in the plug-in works. In V4.0 the VirtualHost matching can be done against the port number that the request was received on, or against the port number that is parsed from the host header. In V5.0 the VirtualHost matching is done only against the port number that is parsed from the host header. This behavior complies with the HTTP 1.1 spec. This flag is supported only in V4.0 and not applicable in V5.0. There is a plan to support this flag in a future V5.0 Cumulative plug-in fix.

AppServerPortPreference flag - this configuration option allows you to choose what port number the Application server uses in building URIs for a sendRedirect. In V4.0 it can be the port number from the host header of the http request coming in, or the port number that the web server received the request on. In V5.0 it is only the port number from the host header of the http request coming in, which fully complies with the HTTP 1.1 spec. This flag is supported only in V4.0 and not applicable in V5.0. There is a plan to support this flag in a future V5.0 Cumulative plug-in fix.

Features that were added to the V5.0 plug-in compared to the V4.0 plug-in:
ESI Cache element - Edge Server Includes processor

ServerCluster element - this is a new element that replaced ServerGroup element which was used in WebSphere 4.0 plug-in

There are several other minor differences between the V4.0 and V5.0 plug-ins, but to list them all would go beyond the scope of this document. For more information about V4.0 and V5.0 plug-ins, visit the WebSphere Infocenter Web site at:

http://www-3.ibm.com/software/webservers/appserv/infocenter.html

Decide whether you will use the same domain name or separate domain names for the V4.0 instance and the V5.0 instance

This is probably the most important step before you configure the V4.0 and V5.0 plug-in for coexistence. It is not required, but IBM recommends that you configure a separate domain name in the web server for each instance of WebSphere Application Server. If this is not possible, or if it does not fit your business need, both instances can be configured with the same domain name to access both V4.0 and V5.0 applications, but some additional configuration steps may be needed.

Example Assumptions:

All of the plug-in examples provided in this document assume the use of IBM HTTP Server 2.0 (IHS 2.0) web server. This approach should be applicable to any web server that is supported with the V4.0 and V5.0 plug-ins.

For the sake of simplicity, the examples below will use myApp40 which is a WebModule of the Enterprise Application deployed in V4.0 with a ContextRoot myApp40. The myApp50 is a WebModule of the Enterprise Application deployed in V5.0 with a ContextRoot myApp50. V4.0 is installed on the server "slovakia" and V5.0 on the server "slavic".

Example #1: Each instance of WebSphere will be accessed thru its own domain name in the web server.

Configure two IP Based VirtualHosts in IHS (httpd.conf), each with its unique IP address, such as:

Listen 80

<VirtualHost 10.10.10.1:80>
ServerName mysite40.com
DocumentRoot /www/docs/mysite40
ErrorLog logs/mysite40-error.log
CustomLog logs/mysite40-access.log common
</VirtualHost>

<VirtualHost 10.10.10.2:80>
ServerName mysite50.com
DocumentRoot /www/docs/mysite50
ErrorLog logs/mysite50-error.log
CustomLog logs/mysite50-access.log common
</VirtualHost>

or if you prefer NameBased VirtualHosting (there are some restrictions for SSL VirtualHosts in IBM HTTP Server):

Listen 80
NameVirtualHost 10.10.10.1

<VirtualHost 10.10.10.1:80>
ServerName mysite40.com
DocumentRoot /www/docs/mysite40
ErrorLog logs/mysite40-error.log
CustomLog logs/mysite40-access.log common
</VirtualHost>

<VirtualHost 10.10.10.1:80>
ServerName mysite50.com
DocumentRoot /www/docs/mysite50
ErrorLog logs/mysite50-error.log
CustomLog logs/mysite50-access.log common
</VirtualHost>

Configure VirtualHostsGroup in V4.0 and V5.0 with corresponding aliases, such as:

a) In V4.0 configure VirtualHost_myApp40 VirtualHostGroup
www.mysite40.com:80
10.10.10.1:80

b) In V5.0 configure VirtualHost_myApp50 VirtualHostGroup
www.mysite50.com:80
10.10.10.2:80

In the case of using NameBased VirtualHosts in IHS, do not add the IP address alias in any VirtualHostGroup. Unexpected results may occur since both VirtualHosts have the same IP address.

Example #2: Both instances of WebSphere have the same domain name in the web server

When serving a request, the plug-in searches for the best match of both VirtualHost and URI mappings. In this case the VirtualHost is common to both the V4.0 and V5.0 environments, so the URI mapping must be unique. Any overlap can cause unexpected results.

Configure IP Based VirtualHost in IHS, such as:

Listen 80

<VirtualHost 10.10.10.1:80>
ServerName mysite.com
DocumentRoot /www/docs/mysite
ErrorLog logs/mysite-error.log
CustomLog logs/mysite-access.log common
</VirtualHost>

Configure VirtualHostsGroup in WebSphere 4.0 & 5.0 with corresponding aliases, such as:

a) In V4.0 configure VirtualHost_myApp40 VirtualHostGroup
www.mysite.com:80
10.10.10.1:80

b) In V5.0 configure VirtualHost_myApp50 VirtualHostGroup
VirtualHost_myApp50 with only one alias:
www.mysite.com:80
10.10.10.1:80

Merging the V4.0 and V5.0 plugin-cfg.xml configuration files

1. Config tag is the root element in the plugin-cfg.xml. There should be only one Config element in the merged file.

2. Copy the Log element from any of the two files to be merged and modify the Name if required.

3. Copy all the VirtualHostGroup from both the files. VirtualHostGroup name must be unique.

4. When serving a request, the plug-in searches for all the possible matches of VirtualHost and URI mappings. Each combination receives a score. The VirtualHost and URI mapping combination with the highest score will be selected for routing the request to the appropriate ServerGroup or Cluster defined in Route element.

5. Copy all ServerCluster and ServerGroup elements from both plug-in configuration files. They must be unique. Normally, they are unique since there is a host name included as well.

6. ServerName must be unique across all Clusters and ServerGroups. From V5.0.1 and up, host/node name is included in the ServerName. If you are using V5.0 or if you have clones configured within V4.0, then you may have to append the host name to the ServerName, to make it unique.

7. In the Transport element, the properties "keyring" and "stashfile" must use the same location for all the application servers in the merged file.

8. Copy all the URIGroup Elements from both nodes. They must be unique. Normally these will be unique as there is a server cluster name in V5.0 and hostname in V4.0 included in it.

9. Copy all the Route elements and apply all changes that you made to the names of VirtualHostGroup, ServerCluster, and URIGroups.

10. After creating the new plugin-cfg.xml file, make sure that the web server configuration file points to the new file.

Examples of merged plugin-cfg.xml files from V4.0 and V5.0

Taking into consideration best practices and instructions mentioned above, here is an example of the merged plug-in configuration file.

V4.0 plugin-cfg.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>

<Config>

<Log LogLevel="Error" Name="C:\ WebSphere\AppServer\logs\native.log"/>

<VirtualHostGroup Name="default_host">
<VirtualHost Name="www.mySite40:80"/>
<VirtualHost Name="10.10.10.1:80"/>
</VirtualHostGroup>

<ServerGroup Name="slovakia/Default Server”>
<Server Name="Default Server">
<Transport Hostname="slovakia" Port="9080" Protocol="http"/>
</Transport>
</Server>
</ServerGroup>

<UriGroup Name="slovakia_sampleApp/default_app_URIs">
<Uri AffinityCookie="JSESSIONID" Name="/MyApp40/snoop/*"/>
</UriGroup>

<Route ServerGroup=" slovakia/Default Server"
UriGroup="slovakia_sampleApp/default_app_URIs" VirtualHostGroup="default_host"/>

</Config>


V5.0 plugin-cfg.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>

<Config>

<Log LogLevel="Error" Name="C:\WebSpherePluginLogs\http_plugin.log"/>

<Property Name="ESIEnable" Value="false"/>
<Property Name="ESIMaxCacheSize" Value="1024"/>
<Property Name="ESIInvalidationMonitor" Value="false"/>

<VirtualHostGroup Name="default_host">
<VirtualHost Name="www.mySite50.com:80"/>
<VirtualHost Name="10.10.10.2:80"/>
</VirtualHostGroup>

<ServerCluster CloneSeparatorChange="false"
LoadBalance="Round Robin" Name="server1_slavic_Cluster">
<Server Name="server1_slavic_Cluster>
<Transport Hostname="slavic" Port="9080" Protocol="http"/>
</Transport>
</Server>
<PrimaryServers>
<Server Name="slavic_server1"/>
</PrimaryServers>
</ServerCluster>

<ServerCluster CloneSeparatorChange="false"
LoadBalance="Round Robin" Name="dmgr_slavicManager_Cluster">
<Server Name="slavicManager_dmgr">
<PrimaryServers>
<Server Name="slavicManager_dmgr"/>
</PrimaryServers>
</ServerCluster>

<UriGroup Name="default_host_server1_slavic_Cluster_URIs">
<Uri AffinityCookie="JSESSIONID"
AffinityURLIdentifier="jsessionid" Name="myApp50/snoop/*"/>
</UriGroup>

<Route ServerCluster="server1_slavic_Cluster"
UriGroup="default_host_server1_slavic_Cluster_URIs" VirtualHostGroup="default_host"/>

</Config>

Example #1 of a merged plugin-cfg.xml (V4.0 and V5.0 use separate domain names)

<?xml version="1.0" encoding="ISO-8859-1"?>

<Config>

<Log LogLevel="Error" Name="C:\WebSpherePluginLogs\http_plugin.log"/>

<Property Name="ESIEnable" Value="false"/>
<Property Name="ESIMaxCacheSize" Value="1024"/>
<Property Name="ESIInvalidationMonitor" Value="false"/>

<VirtualHostGroup Name="myApp50">
<VirtualHost Name="www.mySite50.com:80"/>
<VirtualHost Name="10.10.10.2:80"/>
</VirtualHostGroup>

<VirtualHostGroup Name="myApp40">
<VirtualHost Name="www.mySite40.com:80"/>
<VirtualHost Name="10.10.10.1:80"/>
</VirtualHostGroup>

<ServerCluster CloneSeparatorChange="false"
LoadBalance="Round Robin" Name="server1_slavic_Cluster">
<Server Name="server1_slavic_Cluster>
<Transport Hostname="slavic" Port="9080" Protocol="http"/>
</Transport>
</Server>
<PrimaryServers>
<Server Name="slavic_server1"/>
</PrimaryServers>
</ServerCluster>

<ServerCluster CloneSeparatorChange="false"
LoadBalance="Round Robin" Name="dmgr_slavicManager_Cluster">
<Server Name="slavicManager_dmgr">
<PrimaryServers>
<Server Name="slavicManager_dmgr"/>
</PrimaryServers>
</ServerCluster>

<ServerGroup Name="slovakia/Default Server”>
<Server Name="Default Server">
<Transport Hostname="slovakia" Port="9080" Protocol="http"/>
</Server>
</ServerGroup>

<UriGroup Name="myApp50_server1_slavic_Cluster_URIs">
<Uri AffinityCookie="JSESSIONID"
AffinityURLIdentifier="jsessionid" Name="myApp50/snoop/*"/>
</UriGroup>

<UriGroup Name="slovakia_sampleApp/default_app_URIs">
<Uri AffinityCookie="JSESSIONID" Name="/MyApp40/snoop/*"/>
</UriGroup>

<Route ServerCluster="server1_slavic_Cluster"
UriGroup="myApp50_server1_slavic_Cluster_URIs" VirtualHostGroup="myApp50"/>

<Route ServerGroup=" slovakia/Default Server"
UriGroup="slovakia_sampleApp/default_app_URIs" VirtualHostGroup="myApp40"/>

</Config>

Example #2 of a merged plugin-cfg.xml (V4.0 and V5.0 use common domain name)

The merged file is very similar to the one above, the only difference is that there isn't any need to configure two VirtualHostGroups.

For Example:

<VirtualHostGroup Name="myApp40_50">
<VirtualHost Name="www.mySite.com"/>
<VirtualHost Name="10.10.10.1:80"/>
</VirtualHostGroup>

Conclusion

This document should be used as a guideline for configuring V4.0 and V5.0 plug-in coexistence using a common web server. This document does not address the use of secure socket layers (SSL) transports. If SSL is required between the plug-in and the application server, then the "keyring" and "stashfile" properties must use the same files and location for all instances.
 
 
Cross Reference information
Segment Product Component Platform Version Edition
Application Servers Runtimes for Java Technology Java SDK
 
 


Document Information


Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server > Plug-in
Operating system(s): Windows
Software version: 6.0
Software edition:
Reference #: 1113774
IBM Group: Software Group
Modified date: Nov 25, 2003