+

Search Tips   |   Advanced Search

 

Configuration mapping during product-configuration migration

 

Various configurations are mapped during product-configuration migration.

Migration always involves migrating a single profile to another single profile on the same machine or a separate machine. Examples include a WAS Version 6.0.x deployment manager migrating to a V6.1 deployment manager profile and a V6.0.x appserver migrating to a V6.1 standalone appserver profile.

Many migration scenarios are possible. The migration tools map objects and attributes existing in the version from which you are migrating to the corresponding objects and attributes in the V6.1 environment.

Bootstrap port

The migration tools map a non-default value directly into the Version 6.1 environment.

If the -portBlock parameter is specified during the call to WASPostUpgrade, however, a new port value is given to each appserver that is migrated to V6.1.

Command-line parameters

The migration tools convert appropriate command-line parameters to JVM settings in the server process definition. Most settings are mapped directly. Some settings are not migrated because their roles in the WAS V6.1 configuration do not exist, have different meanings, or have different scopes.

For information on how to change the process-definition settings, see Process definition settings. For information on how to change the Java virtual machine settings, see Java virtual machine settings.

Generic server

In WAS V5.1.x, a generic server was an APPLICATION_SERVER fitted to manage external resources. In V6.0.x and later, it has its own type called GENERIC_SERVER. Migration will perform this conversion, but migration cannot accurately migrate the external resources that the generic server references. After migration has completed migrating the generic server settings, you might need to perform additional tasks. If the old resource that the generic server was managing is located under the old WAS installation, perform the following tasks:

  1. Copy any related files to the new installation.

  2. Run any setup required to put the external application back into a valid and working state.

    It is best that you reinstall the resource into the new WAS directory. Whatever you choose to do, the final step is to reset the reference to the new location of the application.

If the old resource that the generic server was managing is not installed under the old WAS installation, nothing further is required.

Java heap size for migrating EAR files

When migrating all WAS V5.x or 6.0.x EAR files to V6.1 using the wsadmin tool, the WASPostUpgrade tool uses the default maximum Java heap size value of 64 MB to install the EAR files. If a Version 5.x or 6.0.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 message: 

java.lang.OutOfMemoryError JVMXE006:OutOfMemoryError

Increase the maximum Java heap size and follow the example below to install the application.

Example of installing the application on WAS V6.1 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}"

Example of installing the application on WAS ND Version 6.1 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 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}"

JMS server

The JMS server was changed in WAS Version 6.0.x from type MESSAGE_BROKER to type APPLICATION_SERVER. Any queues or topics that it owned have been migrated into the default messaging provider, which is based on service integration technologies. In V5.x and earlier, jmsserver was its own MESSAGE_BROKER server in a ND environment; in the base environment, it was contained within APPLICATION_SERVER types.

All JMS resources were left untouched and should work without modification. Further migration of these resources can be performed by running scripts or bats provided by the V6.1 default messaging provider.

For more information on JMS resources, see Learn about messaging resources.

Migration of a V5.x or 6.0.x node to a V6.1 node

You can migrate a WAS V5.x or 6.0.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 V5.x or 6.0.x to V6.1. If you use a different cell name, federated nodes cannot successfully migrate to the ND V6.1 cell.

Migrating a base WAS node that is within a cell to V6.1 also migrates the node agent to Version 6.1. A cell can have some V6.1 nodes and other nodes that are at Version 5.x or 6.0.x levels. See Coexistence support for information on restrictions on using mixed-release cells.

Policy file

WAS V6.1 migrates all the policy files that are installed with V5.x or 6.0.x by merging settings into the V6.1 policy files with the following characteristics:

  • Any comments located in the V6.1 policy file will be preserved. Any comments contained in the V5.x or 6.0.x policy file will not be included in the V6.1 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.1 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 and lib/app directories

Migration copies files from prior version directories into the WebSphere Application Server V6.1 configuration.

Property files

WAS V6.1 migrates all the property files that are installed with V5.x or 6.0.x by merging settings into the V6.1 property files with these exceptions for V5.x files:

  • j2c.properties (migrated into resources.xml files)

  • samples.properties

Migration does not overlay property files.

Resource adapter archives (RARs) referenced by J2C resources

RARs that are referenced by J2C resources are migrated if those RARs are in the old WAS 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. Migrating cluster-level resources: WAS V6.0 introduced the concept of cluster-level resources. These are configured in resourcexxx.xml files under the cluster directories. For example: 

<resources.j2c:J2CResourceAdapter xmi:id="J2CResourceAdapter_1112808424172" 
  name="ims" archivePath="${WAS_INSTALL_ROOT}\installedConnectors\x2.rar">
  ...
</resources.j2c:J2CResourceAdapter>

If you have a cluster-level resource, this resource must be in the same location on each cluster member (node). Using the above example, therefore, each cluster member must have the RAR file installed at location ${WAS_INSTALL_ROOT}\installedConnectors\x2.rar. ${WAS_INSTALL_ROOT} is resolved on each cluster member to get the exact location.

In the migration of a deployment manager, the tools migrate the cluster files on the deployment manager, including the resourcexxx.xml files.

In the migration of a managed node, the tools process each J2C adapter. Files such as RAR files are migrated differently depending on whether you are migrating from V5.x to V6.x or from V6.0.x to V6.1.

  • V5.x to V6.x migration

    Because the profile structure changed in V6.0, migration from V5.x to V6.x copies files such as RAR files from the location set for the WAS_INSTALL_ROOT variable to the location set for the USER_INSTALL_ROOT variable and modifies any paths to reflect these changes.

  • V6.0.x to V6.1 migration

    Migration from V6.0.x to V6.1 copies files such as RAR files from WAS_INSTALL_ROOT to WAS_INSTALL_ROOT and from USER_INSTALL_ROOT to USER_INSTALL_ROOT.

    If you have a RAR file in the WAS_INSTALL_ROOT for V6.0.x, for example, the migration tools do not automatically copy the file from WAS_INSTALL_ROOT to USER_INSTALL_ROOT as they would do in a V5.x to 6.x migration. This maintains the integrity of the cluster-level J2C resources. Limitation: If you hardcoded a path to a RAR file (archivePath="C:/WAS/installedConnectors/x2.rar" for example) in V6.0.x, however, the V6.1 migration tools cannot change the archivePath attribute to reflect this because that would break all of the other cluster members that have not been migrated.

Samples

During the migration of the deployment manager, only WebSphere Application Server V5.x samples for federated nodes are migrated. Equivalent Version 6.1 samples are available for all other V5.x samples and all Version 6.0.x samples.

Security

Java 2 security is enabled by default when you enable security in WebSphere Application Server V6.1. Java 2 security requires you to grant security permissions explicitly.

There are several techniques used to to define different levels of Java 2 security in Version 6.1. One is to create a was.policy file as part of the application to enable all security permissions. The migration tools call the wsadmin command to add an existing was.policy file in the V6.1 properties directory to enterprise applications as they are being migrated. When migrating to WAS V6.1, your choice of whether or not to migrate to support script compatibility results in one of two different outcomes.

  • If you choose to migrate to support script compatibility, your security configuration is brought over to V6.1 without any changes.

    This is the default.

  • If you choose not to migrate to support script compatibility, the security configuration is converted to the default configuration for WebSphere Application Server V6.1. The default security configuration for V6.1 acts almost the same as in the previous versions, but there are some changes.

    For example, existing keyfiles and trustfiles are moved out of the SSLConfig repertoire and new keystore and truststore objects are created.

For more information on migrating your security configurations to V6.1, see Migrating, coexisting, and interoperating – Security considerations.

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 WAS V6.1 installation root.

The migration tools attempt to migrate existing passivation and working directories. Otherwise, appropriate V6.1 defaults are used.

For more information on passivation directories, see EJB container settings. For more information on working directories, see Process definition settings.

In a coexistence scenario, using common directories between versions can create problems.

Transport ports

The migration tools migrate all ports. The tools log a port-conflict warning if a port is already defined in the configuration. You must resolve any port conflicts before you can run servers at the same time. If the -portBlock parameter is specified in the WASPostUpgrade command, a new value is assigned to each transport that is migrated. Choosing -scriptCompatibility="true" or -scriptCompatibility="false" results in two different outcomes for transport ports if you are migrating from WAS V5.x:

  • -scriptCompatibility="true"

    This results in your transport ports being brought over as they are. This is the default.

  • -scriptCompatibility="false"

    This results in the transport ports being converted to the 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.

For more information on the WASPostUpgrade command, see WASPostUpgrade command.

For further information on transport chains and channels, see Transport chains.

You must manually add virtual host alias entries for each port. For more information, see Configure virtual hosts.

Web modules

The specification level of the Java 2 Platform, Enterprise Edition (J2EE) implemented in WAS V6.0.x required 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 Web container no longer default to it but the Web container returns the call as "null." This situation might cause some browsers to display resulting Web container tags incorrectly. To prevent this problem from occurring, migration sets the autoResponseEncoding IBM extension to "true" for Web modules as it migrates enterprise applications.



 

Related tasks


Migrating and coexisting
Migrating product configurations
Task overview: Using enterprise beans in applications