V5.0 plugin regeneration and synchronization issues
 Technote (troubleshooting)
 
Problem(Abstract)
The Web server plugin configuration file, plugin-cfg.xml, defines URL requests that are transferred from the Web server to an application server. The generated plugin-cfg.xml file is placed in the /config directory of the Application Server install path. Many common WebSphere® Application Server V5.0 plugin problems are resolved through regeneration and synchronization of Web server plug-in files.
 
Resolving the problem
Background:
Key points:
  • If your Web server is located on a remote machine, you must manually copy the plugin-cfg.xml file to the remote Web server machine.
  • This file must be regenerated when server, cluster, HTTP transport, or virtual host alias configurations are changed.

The plugin-cfg.xml file is located in:


$WAS_HOME/config/cells/plugin-cfg.xml

Generating or updating the plugin-cfg.xml file

  • Using the Console
    1. Select Environment > Update Web Server Plugin

    2. Click OK to update the plug-in configuration file.
  • Using command line GenPluginCfg

    $WAS_HOME \bin>GenPluginCfg.sh/bat help

    Usage: GenPluginCfg [[-option.name optionValue]...]

    Examples
    • To generate a plug-in config for all of the clusters in a cell:

      GenPluginCfg.sh/bat -cell.name NetworkDeploymentCell
    • To generate a plug-in configuraion for a single server:

      GenPluginCfg.sh/bat -cell.name NetworkDeploymentCell -node.name myNode -server.name myServerName

      Option
      Value
      Default Value
      -config.root configroot_dir Defaults to environment variable CONFIG_ROOT
      -cell.name cell Defaults to environment variable WAS_
      -node.name node Defaults to environment variable WAS_NODE
      -server.name server Required for single server plug-in generation
      -output.file.name file_name Defaults to plugin-cfg.xml
      -destination.root root Defaults to configroot_dir/cells
      -destination.operating.system windows/unix Operating system of configuration server
      -debug yes/no Defaults to no

  • Using wsadmin

    The Web server plug-in configuration files can also be updated by using wsadmin.

    This example is from a Windows® platform. It invokes the generate operation on the MBean, passing in the installation root directory, configuration root directory, cell name, node name, server name, and output file name. To pass in null as the value of an argument, enter null as given in the example. This is provided for operation that allows null as the value of its argument and processes null differently from an empty string. In this example, both node and server are set to null. The generate operation generates plug-in configuration for all the nodes and servers in the cell. The output file plugin-cfg.xml is created in the configuration root directory:

    1. Identify the Web server plug-in configuration file generator MBean and assign it to the pluginGen variable:

    set pluginGen [$AdminControl completeObjectName type=PluginCfgGenerator,*]

    Example output:

    WebSphere:cell=pongoNetwork,name=PluginCfgGenerator,mbeanIdentifier=PluginCfgGenerator,type=PluginCfgGenerator,node=pongoManager,process=dmgr

    2. Generate the updated plug-in configuration file.

    $AdminControl invoke $pluginGen generate "c:/WebSphere/DeploymentManager c:/WebSphere/DeploymentManager/config mycell plugin-cfg.xml"

    For more information visit the product Information Center.

    In the example above, only four parameters are passed.
    Like CommandLine "GenPluginCfg.sh/bat," we can pass more parameters.

    $AdminControl invoke $pluginGen generate "c:/WebSphere/DeploymentManager c:/WebSphere/DeploymentManager/config myCell myNode myServer plugin-cfg.xml d:/WebServer/myNewDir windows"


    Install Root =>c:/WebSphere/DeploymentManager Configuration Root =>c:/WebSphere/DeploymentManager/config
    Cell Name =>myCell
    Node Name =>myNode
    Server Name =>myServer
    Output File Name =>plugin-cfg.xml
    Destination-root =>d:/WebServer/myNewDir
    Destination-operating-system => Windows or Unix

Questions

How does the generation or update of the plug-in file work?


Depending on your edition of WebSphere (Base, ND, or EE) the regeneration process updates different plugin-cfg.xml files.

In a Base environment, the plugin-cfg.xml that is updated is:

$WAS_HOME_BASE/config/cells/plugin-cfg.xml

In a Cell environment (Deployment Manager with one or more Base nodes) the plugin-cfg.xml that is updated is:

$WAS_HOME_NDconfig/cells/plugin-cfg.xml

The "Update Web Server plug-in" will ONLY update plugin-cfg.xml in the ND Machine in a cell environment. The plugin-cfg.xml files located on the Base nodes are not updated. To update them, a synchronize operation from the ND node is needed to push the updated data to all the Base nodes in the Cell.


What are the differences between Full Resynchronize and Synchronize?
Full Resynchronize
Synchronizes the configuration immediately. Click this button on the Nodes page if automatic configuration synchronization is disabled, or if the synchronization interval is set to a long time, and a configuration change has been made to the cell repository that must be replicated to that node. Clicking this button clears all synchronization optimization settings and performs configuration synchronization anew, so there is no mismatch between node and cell configuration after this operation is performed. This operation might take a while to perform.

Synchronize
Synchronizes the configuration immediately. Click this button on the Nodes page if automatic configuration synchronization is disabled, or if the synchronization interval is set to a long time, and a configuration change has been made to the cell repository that must be replicated to that node. Clicking this button requests that a node synchronization operation be performed using the normal synchronization optimization algorithm. This operation is fast but might not fix problems from manual file edits that occur on the node. It is possible for the node and cell configuration to be out of synchronization after this operation is performed. If problems persist, use Full Resynchronize.

How do I perform a manual synchronization?
A. Stopping and starting the NodeAgent
Stop and start of the node agent will invoke the synchronization operation.
$WAS_HOME_BASE/bin> stopNode.sh/bat

$WAS_HOME_BASE/bin> startNode.sh/bat
B. Using syncNode.sh/bat
$WAS_HOME_BASE/bin> syncNode.sh/bat

Note: Before issuing the syncNode.bat/sh, stop the corresponding node agent. If you do not, the syncNode.bat/sh automatically stops that Node and you see the following warning message:

ADMU0403E: The node agent must be stopped before running syncNode.

C. Using the Console
Use the Full Resynchronize option because the Synchronize option does not update the plugin-cfg.xml file.

In the console under System Administration, go to Nodes, select the check box next to the Base node that you want to synchronize, then click on Full Resynchronize. This copies the plugin-cfg.xml from the ND node to the Base node.

Notes:
  1. If the Web server is installed on the same machine as the Base node, after the Full Resynchronization completes, the Web server is also updated.
  2. If the Web server is remote from the Base node, must FTP or do a manual copy of plugin-cfg.xml file to that machine.
  3. There is a known problem with 5.0 and 5.0.1 with Full Resynchronize; it is not consistent and most of the time it fails to update the Base node's plugin-cfg.xml. This problem occurs on all platforms including cross platforms. To workaround this issue, use options A, B, or D. This issue is fixed in 5.0.2.
D. Using wsadmin
To update the plugin-cfg.xml to the Base nodes, use the following commands. All four of these commands must run in the order listed. If you do not receive similar output or if you receive errors, do not continue the process.

wsadmin>set a [$AdminControl completeObjectName type=ConfigRepository,process=nodeagent,*]

Example output:
WebSphere:platform=common,cell=motherNetwork,version=5.0,name=repository,mbeanIdentifier=repository,type=ConfigRepository,node=mother,process=nodeagent

wsadmin>$AdminControl invoke $a refreshRepositoryEpoch

Example output:
1065581862922

wsadmin>set b [$AdminControl completeObjectName type=NodeSync,*]

Example output:
WebSphere:platform=common,cell=motherNetwork,version=5.0,name=nodeSync,mbeanIdentifier=nodeSync,type=NodeSync,node=mother,process=nodeagent

wsadmin>$AdminControl invoke $b sync

Example output:
true


Important note: There are two cases that might cause problems. The first is when both ND and Base are installed on the same host machine. The second is when ND is installed on one platform (for example, AIX®) and Base is installed on another platform (for example, Linux®). The operating systems can be any variation, the problem will still arise.

This example has Base on Solaris and ND on Windows 2000:

Machine1: Base installation on a Sun Machine
WebSphere Base install root is opt\WebSphere\AppServer
Here, the plugin-cfg.xml is located at opt\WebSphere\AppServer\config\cells\plugin-cfg.xml

Originally this plugin-cfg.xml has the following information for the log, keyring, and stash files:
<LogLogLevel="Error"Name="opt\WebSphere\AppServer\logs\http_plugin.log"/>
<Property name="keyring" value="opt\WebSphere\AppServer\etc\plugin-key.kdb"/>
<Property name="stashfile" value="opt\WebSphere\AppServer\etc\plugin-key.sth"/>

Machine1 also has IBM HTTP Server installed at opt\IBMHTTPServer

The httpd.conf file location is opt\IBMHTTPServer\conf\httpd.conf

This httpd.conf file has following information for plug-in
LoadModule ibm_app_server_http_module"opt\WebSphere\AppServer/bin/mod_ibm_app_server_http.dll"
WebSpherePluginConfig "opt\WebSphere\AppServer/config/cells/plugin-cfg.xml"

Machine2: ND installation on a Windows Machine
WebSphere ND install root is C:\WebSphere\DeploymentManager


Scenario:

The following steps are taken:
a. "addNode" from Base node (Machine 1)
b. re-generate plug-in
c. stop and start nodeagent on the Base node (Machine 1)

On Machine 1, we see the original plugin-cfg.xml file (opt\WebSphere\AppServer\config\cells\plugin-cfg.xml) has been modified and now reflects the following (note that the directories are all Windows based, not UNIX based):

<Log LogLevel="Error" Name="C:\WebSphere\DeploymentManager\logs\http_plugin.log"/>
<Property name="keyring" value="C:\WebSphere\DeploymentManager\etc\plugin-key.kdb"/>
<Property name="stashfile" value="C:\WebSphere\DeploymentManager\etc\plugin-key.sth"/>

This is not correct, but is currently working as designed. The keyring and stashfile files are located only on the Base node and do not exist on the ND node. However, during the synchronization operation the data pushed from the ND machines overrides their locations.

The Web server fails unless the file is manually updated to the original directory paths. There are three ways to workaround this issue.

The synchronization process updates more than just the log, keyring and stashfile entries. If you make a copy of the plugin-cfg.xml file,run synchronization, then copy the original file back, you will not have any of the required updates to the rest of the plugin-cfg.xml file.

Workaround 1:

From Machine 1 (Base and HTTP server) complete the following four steps.

1. Make a backup copy of the plugin-cfg.xml:
copy
opt\WebSphere\AppServer\config\cells\plugin-cfg.xml

to
opt\<MyDirForPlugIn>\plugin-cfg.xml

Note: The MyDirForPlugIn must be located outside of the \WebSphere\ directory path, such as opt\MyDirForPlugIn\plugin-cfg.xml

2. Edit the copied version of the plugin-cfg.xml file to reflect the following changes:
post sync plugin-cfg.xml file
<Log LogLevel="Error" Name="C:\WebSphere\DeploymentManager\logs\http_plugin.log"/>
<Property name="keyring" value="C:\WebSphere\DeploymentManager\etc\plugin-key.kdb"/>
<Property name="stashfile" value="C:\WebSphere\DeploymentManager\etc\plugin-key.sth"/>

edit to reflect the following lines
<Log LogLevel="Error" Name="opt\WebSphere\AppServer\logs\http_plugin.log"/>
<Property name="keyring" value="opt\WebSphere\AppServer\etc\plugin-key.kdb"/>
<Property name="stashfile" value="opt\WebSphere\AppServer\etc\plugin-key.sth"/>

3. Edit following in the HTTP server's httpd.conf, which is located at the Web Server Home\conf directory, to reflect the new location of the plugin-cfg.xml file.
from:
WebSpherePluginConfig "opt\WebSphere\AppServer/config/cells/plugin-cfg.xml"

change to
WebSpherePluginConfig "opt\<MyDirForPlugIn>\plugin-cfg.xml"

4. Re-Start HTTP server to load plugin-cfg.xml from new location
For any changes made to the WebSphere configuration (addNode, installing a new application, creating new server or virtual host, and so forth) you must copy and manually edit the opt\MyDirForPlugIn\plugin-cfg.xml file.

Workaround 2:

From Machine 2 (ND) complete the following two steps.

1. From $WAS_HOME_ND/config/cells directory edit the plugin-cfg.xml file to point to the correct directory structure for the log, keyring and stashfile locations.
from:
<Log LogLevel="Error" Name="C:\WebSphere\DeploymentManager\logs\http_plugin.log"/>
<Property name="keyring" value="C:\WebSphere\DeploymentManager\etc\plugin-key.kdb"/>
<Property name="stashfile" value="C:\WebSphere\DeploymentManager\etc\plugin-key.sth"/>

edit to reflect the following lines
<Log LogLevel="Error" Name="opt\WebSphere\AppServer\logs\http_plugin.log"/>
<Property name="keyring" value="opt\WebSphere\AppServer\etc\plugin-key.kdb"/>
<Property name="stashfile" value="opt\WebSphere\AppServer\etc\plugin-key.sth"/>

2. Do a full sync (see the "How do I perform a manual synchronization?" section above)
This modified "plugin-cfg.xml" from Machine 1 (ND) is replicated to Machine 2 (Base and HTTP server).
1. Do not delete the modified plugin-cfg.xml from Machine 1 because on the next regeneration it creates a new plugin-cfg.xml file that does not contain the location of the log, keyring, and stashfile locations. If you delete the plugin-cfg.xml file from Machine 1, you must perform Workaround 2 again.

2. If you are running 5.0 without any fix packs and you do a manual edit to the plugin-cfg.xml file on Machine 1, it updates Machine 2; however, the manual changes made to Machine 1 are not retained. PQ72596 enables you to do manual changes of the plugin-cfg.xml file that are retained. This fix has been incorporated in 5.0.1 and higher.

Workaround 3:

From node 2 (ND), complete the following. If you have more than one Base node in your cell and the nodes are different operating systems and/or if the installation directories are different, you cannot use this workaround. You can specify only one destination root.
Generate plug-in: From the command line, issue:

$WAS_HOME_ND\bin> GenpluginCfg.bat/sh -destination.root

This changes all the directories in Machine 1 plugin-cfg.xml file to this specified directory.
Example:
GenpluginCfg -destination.root opt\WebSphere\AppServer
Note: opt\WebSphere\AppServer is located on Machine 1.

How do I enable and disable Auto regeneration of the plug-in?
Starting in V5.0 releases, the configurable auto regeneration function is no longer available. This is a function that was deprecated in V3.5 and V4.0.
 
 
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: 5.0.2
Software edition:
Reference #: 1140883
IBM Group: Software Group
Modified date: Apr 7, 2004