Configuration mapping during migration

Various configurations are mapped during migration.

Migration involves the copying of your configuration from a previous release of a WebSphere Application Server product into a new release.

Many migration scenarios are possible. The Version 6.0.x migration tools map objects and attributes to the Version 6.0.x environment when you restore a configuration from a previous version.

Bootstrap port

Migration maps a default bootstrap NameServer port setting, 900, from Version 5.x to the Version 6.0.x NameServer default, 2809. The migration tools map a non-default value directly into the Version 6.0.x environment.

Command-line parameters

The migration tools convert appropriate command-line parameters to Java virtual machine (JVM) settings in the server process definition. Most settings are mapped directly. Some settings, such as memory heap sizes, are not migrated because their roles in the Version 6.0.x configuration either do not exist, have different meanings, or have different scopes.

GenericServer
Introduced in Version 5.1.x, a GenericServer was an APPLICATION_SERVER fitted to manage external resources. In Version 6.0.x, it has its own type, called GENERIC_SERVER. Migration will perform this conversion, but migration cannot accurately migrate the external resources that the GenericServer references. After migration has completed migrating the GenericServer settings, you need to perform the following actions:
  • If the old resource that the GenericServer was managing is located under the old WebSphere Application Server installation, you have to copy any related files to the new installation of WebSphere Application Server. You must also run any required setup to put the external application back into a valid and working state. IBM recommends instead that you re-install the resource into the new WebSphere Application Server directory. Whichever you choose to do, the final step is that you need to reset the reference to the new location of the application.
  • If the old resource that the GenericServer was managing is not installed under the old WebSphere Application Server installation, nothing further is required.
Migration of a Version 5.x node to a Version 6.0.x node

You can migrate a Version 5.x node that belongs to a cell without removing the node from the cell.

Migrate the deployment manager first, before migrating any base nodes in the cell.

Use the same cell name when migrating Network Deployment from Version 5.x to Version 6.0.x. If you use a different cell name, federated nodes cannot successfully migrate to the Network Deployment Version 6.0.x cell.

Migrating a base WebSphere Application Server node that is within a cell to Version 6.0.x also migrates the node agent to Version 6.0.x. A cell can have some Version 6.0.x nodes and other nodes that are at Version 5.x levels.

Name bindings
Version 6.0.x has a new naming structure. All references, such as enterprise Java bean references that were valid in previous versions no longer work in Version 6.0.x. However, you can use the administrative console to add a name binding that maps an old name into the new Version 6.0.x naming structure. For example, the name of the Version 5.0.x enterprise bean reference can be both the name of the binding and the Java Naming and Directory Interface (JNDI) name in the Version 6.0.x name space.
Note: The contents of name spaces from previous versions are not automatically migrated to Version 6.0.x.
Policy file migration from Version 5.x to Version 6.0.x
WebSphere Application Server Version 6.0.x migrates all the policy files that are installed with Version 5.x by merging settings into the Version 6.0.x policy files with the following characteristics:
  • Any comments located in the Version 6.0.x policy file will be lost. They are replaced with the comments contained in the Version 5.x policy file.
  • Migration will NOT attempt to merge permissions or grants; it is strictly an add-type migration. If the permission or grant is not located in the Version 6.0.x file, the migration will bring it over.
  • Security is a critical component; thus, the migration makes any additions at the end of the original .policy file right after the comment MIGR0372I: Migrated grant permissions follow. This is done to help administrators verify any policy file changes that the migration has made.
Properties directory and the lib/app directory

Migration copies files from prior version directories into the Version 6.0.x configuration. See the following section for more information.

Property file migration from Version 5.x to Version 6.0.x
WebSphere Application Server Version 6.0.x migrates all the property files that are installed with Version 5.x by merging settings into the Version 6.0.x property files with these exceptions:
  • j2c.properties (migrated into resources.xml files)
  • samples.properties
Migration does not overlay property files.
Resource Adapter Archive (RAR) referenced by J2C resources

RARs that are referenced by J2C resources are migrated if those RARs are in the old WebSphere Application Server installation. In this case, the RARs are copied over to the corresponding location in the new WebSphere Application Server installation. Relational Resource Adapter RARs will not be migrated.

Samples

During the migration of the deployment manager Version 5.x samples for federated nodes are migrated. Equivalent Version 6.0.x samples are available to use for all other Version 5.x samples.

Servlet package name change

The package that contains the DefaultErrorReporter servlet changed as of Version 5. In Version 6.0.x, the servlet is in the com.ibm.ws.webcontainer.servlet class. Direct use of the DefaultErrorReporter servlet has been deprecated.

InvokerServlet and SimpleFileServlet servlets
The InvokerServlet and SimpleFileServlet servlets are internal servlets that have not been public since WebSphere Application Server Version 3.5. If you referenced these servlets in any version after Version 3.5 through the web.xml file, you should remove these entries from the web.xml file and use the ibm-web-ext.xmi file to enable or disable these servlets using serveServletsByClassnameEnabled and fileServingEnabled. See the following example:
<?xml version="1.0" encoding="UTF-8"?>
<webappext:WebAppExtension xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"  
xmlns:webappext="webappext.xmi" xmlns:webapplication="webapplication.xmi"  
xmlns:commonext.localtran="commonext.localtran.xmi"  
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmi:id="WebApp_ID_Ext" reloadInterval="3" reloadingEnabled="true" 
fileServingEnabled="false" directoryBrowsingEnabled="false" 
serveServletsByClassnameEnabled="true" preCompileJSPs="false" 
autoRequestEncoding="false" autoResponseEncoding="false">
  <defaultErrorPage xsi:nil="true"/>
  <additionalClassPath xsi:nil="true"/>
  <webApp href="WEB-INF/web.xml#WebApp_ID"/>
  <extendedServlets xmi:id="ServletExtension_1">
    <extendedServlet href="WEB-INF/web.xml#Servlet_1"/>
  </extendedServlets>
  <extendedServlets xmi:id="ServletExtension_2">
    <markupLanguages xmi:id="MarkupLanguage_1" name="HTML" mimeType="text/html" 
    errorPage="Page_1" defaultPage="Page_2">
      <pages xmi:id="Page_2" name="Hello.page" uri="/HelloHTML.jsp"/>
      <pages xmi:id="Page_1" name="Error.page" uri="/HelloHTMLError.jsp"/>
    </markupLanguages>
    <markupLanguages xmi:id="MarkupLanguage_2" name="VXML" mimeType="text/x-vxml" 
    errorPage="Page_3" defaultPage="Page_4">
      <pages xmi:id="Page_4" name="Hello.page" uri="/HelloVXML.jsp"/>
      <pages xmi:id="Page_3" name="Error.page" uri="/HelloVXMLError.jsp"/>
    </markupLanguages>
    <markupLanguages xmi:id="MarkupLanguage_3" name="WML" mimeType="vnd.wap.wml" 
    errorPage="Page_5" defaultPage="Page_6">
      <pages xmi:id="Page_6" name="Hello.page" uri="/HelloWML.jsp"/>
      <pages xmi:id="Page_5" name="Error.page" uri="/HelloWMLError.jsp"/>
    </markupLanguages>
    <extendedServlet href="WEB-INF/web.xml#Servlet_2"/>
  </extendedServlets>
  <extendedServlets xmi:id="ServletExtension_3">
    <extendedServlet href="WEB-INF/web.xml#Servlet_3"/>
    <localTransaction xmi:id="LocalTransaction_1" unresolvedAction="Rollback"/>
  </extendedServlets>
</webappext:WebAppExtension>
Stdin, stdout, stderr, passivation, and working directories

The location for these directories is typically within the installation directory of a previous version. The default location for stdin, stdout, and stderr is the logs directory of the Version 6.0.x installation root. The migration tools attempt to migrate existing passivation and working directories. Otherwise, appropriate Version 6.0.x defaults are used.

Using common directories between versions in a coexistence scenario can cause problems.

Transport ports

The migration tools migrate all ports. The tools warn about port conflicts in a log when a port already exists. You must resolve port conflicts before running the servers that are in conflict, at the same time.

Choosing -scriptCompatibility="true" or -scriptCompatibility="false" results in two different outcomes for transport ports:
  • -scriptCompatibility="true": This results in your transport ports being brought over as they are (this is the default).
  • -scriptCompatibility="false": This results in the transports ports being converted to the new implementation of channels and chains. From an external application usage standpoint, they will still act the same, but they have been moved to the TransportChannelService.
Web modules

The specification level of the Java 2 Platform, Enterprise Edition (J2EE) that Version 6.0.x implements requires behavior changes in the Web container for setting the content type. If a default servlet writer does not set the content type, not only does the Version 6.0.x Web container no longer default to it, the Web container returns the call as "null". This situation might cause some browsers to display resulting Web container tags incorrectly. Migration sets the autoResponseEncoding IBM extension to true for Web modules as it migrates enterprise applications. This action prevents the problem.

Version 5.x to Version 6.0.x migration

Migrating from Version 5.x to Version 6.0.x is much less complicated than previous migrations. Both versions use the same underlying definitions. The task involves mapping configuration files from the Version 5.x to the Version 6.0.x configuration and copying installed applications into the new product. The migration tools support the migration of federated nodes and support the full migration of a Network Deployment node.

Java heap size for migrating EAR files
If a Version 5.x EAR file fails to install during migration because the Java heap size is not large enough, you see a message similar to the following error:
java.lang.OutOfMemoryError JVMXE006:OutOfMemoryError 

Increase the maximum Java heap size and follow the instructions below to install the application:

Installing the application on WebSphere Application Server Version 6.0.x

Assume that:
Installation root
C:\WebSphere\AppServer
Number signs (###)
Maximum heap size value
EAR_file_name
Name of the EAR file
app_name
Name of the application
server_name
Name of the server on which the EAR file installs
node_name
Name of the node on which the server is configured
The command is displayed on more than one line for clarity.
wsadmin -conntype NONE
        -javaoption 
        -Xmx###m 
        -c "$AdminApp install 
               C:\\WebSphere\\AppServer\\installableApps\\
                  EAR_file_name
        {-nodeployejb 
         -appname app_name
         -server server_name 
         -node node_name}"

Installing the application on WebSphere Application Server Network Deployment Version 6.0.x

Assume that:
Installation root
C:\WebSphere\DeploymentManager
Number signs (###)
Maximum heap size value
EAR_file_name
Name of the EAR file
app_name
Name of the application
cluster_name
Name of the cluster on which the EAR file should be installed
The command is displayed on more than one line for clarity.
wsadmin -conntype NONE
        -javaoption 
        -Xmx###m 
        -c "$AdminApp install 
            C:\\WebSphere\\DeploymentManager\\installableApps\\
                   EAR_file_name> 
        {-nodeployejb 
         -appname app_name 
         -cluster cluster_name}"



Related tasks
Migrating product configurations
Migrating and coexisting
Concept topic    

Terms of Use | Feedback

Last updated: Aug 29, 2010 8:25:23 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=vela&product=was-nd-zos&topic=cins_migconf
File name: cins_migconf.html