Configuration mapping during product-configuration migration

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 v7.0 dmgr migrating to a v9.0 dmgr and a v7.0 application server migrating to a v9.0 stand-alone application server.

Many migration scenarios are possible. The migration tools map objects and attributes existing in the version from which we are migrating to the corresponding objects and attributes in the v9.0 environment.

Bootstrap port The migration tools carry the old release value into the v9.0 environment. If the -setPorts parameter is set to generateNew or a port value during the call to WASPostUpgrade, however, the port value is given to each application server that is migrated to v9.0.

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 v9.0 configuration do not exist, have different meanings, or have different scopes. See Process Definition Setting. For information on how to change the JVM settings, see Java virtual machine settings.

Generic server In v7.0 or later, a generic server 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, we might need to perform additional tasks. If the old resource that the generic server was managing is located under the old WAS installation...

Copy any related files to the new installation.
Run any setup required to put the external application back into a valid and working state. It is best to reinstall the resource into the new WAS directory. Whatever we 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 When migrating all WAS v7.0 or later EAR files to v9.0 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 v7.0 or later 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 to install the application.

Example of installing the application on WAS v9.0

Assume that:

Installation root C:\WebSphere\AppServer
EAR_file_name Name of the EAR fileg
app_name Name of the applicationg
server Name of the server on which the EAR file installs
node Name of the node on which the server is configured

Run...
wsadmin -conntype NONE -c "$AdminApp install C:\\WebSphere\\AppServer\\installableApps\\ EAR_file_name {-nodeployejb -appname app_name -server server -node node}"

Example of installing the application on WAS ND v9.0

Assume that:

Installation root C:\WebSphere\ Manager
EAR_file_name Name of the EAR fileg
app_name Name of the applicationg
cluster_name Name of the cluster on which the EAR file should be installed

Run...
wsadmin -conntype NONE -c "$AdminApp install C:\\WebSphere\\ Manager\\installableApps\\ EAR_file_name> {-nodeployejb -appname app_name -cluster cluster_name}"

Migration of a v7.0 or later node to a v9.0 node We can migrate a WAS v7.0 or later node that belongs to a cell without removing the node from the cell. Migrate the dmgr first, before migrating any base nodes in the cell. Use the same cell name when migrating WAS ND from v7.0 or later to v9.0. If we use a different cell name, federated nodes cannot successfully migrate to the WAS ND v9.0 cell.
Migrate a base WAS node that is within a cell to v9.0 also migrates the node agent to v9.0. A cell can have some v9.0 nodes and other nodes that are at v7.0 or later levels.

Policy files WAS v9.0 migrates all the policy files installed with v7.0 or later by merging settings into the v9.0 policy files with the following characteristics:

Any comments located in the v9.0 policy files will be preserved. Any comments contained in the v7.0 or later policy files will not be included in the v9.0 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 v9.0 file, the migration will bring it over.
The migration makes any additions at the end of the original .policy files 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 directories Migration copies files from prior version directories into the WAS v9.0 configuration.

Property files WAS v9.0 migrates all the property files installed with v7.0 or later by merging settings into the v9.0 property files.

RARs referenced by J2C resources RARs 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 WAS installation. Relational Resource Adapter RARs will not be migrated.

Migrate cluster-level resources: WAS Version Cluster-level resources 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>

This resource is in the same location on each cluster member (node). Therefore, each cluster member must have the RAR file installed at...
${WAS_INSTALL_ROOT}\installedConnectors\x2.rar

In the migration of a dmgr, the tools migrate the cluster files on the dmgr, including the resourcexxx.xml files. In the migration of a federated node, the tools process each J2C adapter. Migration from v7.0 to v9.0 copies files such as RAR files from WAS_INSTALL_ROOT to WAS_INSTALL_ROOT and from USER_INSTALL_ROOT to USER_INSTALL_ROOT.

If we have a RAR file in the WAS_INSTALL_ROOT for v7.0, for example, the migration tools do not automatically copy the file from WAS_INSTALL_ROOT to USER_INSTALL_ROOT. This maintains the integrity of the cluster-level J2C resources.
If we hardcoded a path to a RAR file (archivePath="C:/WAS/installedConnectors/x2.rar" for example) in v7.0, however, the v9.0 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 No migration of samples from previous versions is available. There are equivalent WAS v9.0 samples that we can install.

Security Java 2 security is enabled by default when we enable security in WAS v9.0. Java 2 security requires us to grant security permissions explicitly.

There are several techniques that we can use to define different levels of Java 2 security in v9.0. 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 v9.0 properties directory to enterprise applications as they are being migrated.

When migrating to WAS v9.0, our choice of whether or not to migrate to support script compatibility results in one of two different outcomes.

If we choose to migrate to support script compatibility, the security configuration is brought over to v9.0 without any changes.
This is the default.

If we choose not to migrate to support script compatibility, the security configuration is converted to the default configuration for WAS v9.0. The default security configuration for v7.0 or later 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 our security configurations to v9.0, read the "Migrate, coexist, and interoperate - Security considerations" article in the documentation.

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 v9.0 installation root.

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

In a coexistence scenario, using common directories between versions can create problems.
Web modules The specification level of the Java EE implemented in WAS v7.0 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.

Roadmap: Migrating and coexisting application servers
Migrate product configurations
Migration Toolkit on WASdev

Bootstrap port	The migration tools carry the old release value into the v9.0 environment. If the -setPorts parameter is set to generateNew or a port value during the call to WASPostUpgrade, however, the port value is given to each application server that is migrated to v9.0.
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 v9.0 configuration do not exist, have different meanings, or have different scopes. See Process Definition Setting. For information on how to change the JVM settings, see Java virtual machine settings.
Generic server	In v7.0 or later, a generic server 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, we might need to perform additional tasks. If the old resource that the generic server was managing is located under the old WAS installation... Copy any related files to the new installation. Run any setup required to put the external application back into a valid and working state. It is best to reinstall the resource into the new WAS directory. Whatever we 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	When migrating all WAS v7.0 or later EAR files to v9.0 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 v7.0 or later 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 to install the application.

Installation root	C:\WebSphere\AppServer
EAR_file_name	Name of the EAR fileg
app_name	Name of the applicationg
server	Name of the server on which the EAR file installs
node	Name of the node on which the server is configured

Installation root	C:\WebSphere\ Manager
EAR_file_name	Name of the EAR fileg
app_name	Name of the applicationg
cluster_name	Name of the cluster on which the EAR file should be installed

Migration of a v7.0 or later node to a v9.0 node	We can migrate a WAS v7.0 or later node that belongs to a cell without removing the node from the cell. Migrate the dmgr first, before migrating any base nodes in the cell. Use the same cell name when migrating WAS ND from v7.0 or later to v9.0. If we use a different cell name, federated nodes cannot successfully migrate to the WAS ND v9.0 cell. Migrate a base WAS node that is within a cell to v9.0 also migrates the node agent to v9.0. A cell can have some v9.0 nodes and other nodes that are at v7.0 or later levels.
Policy files	WAS v9.0 migrates all the policy files installed with v7.0 or later by merging settings into the v9.0 policy files with the following characteristics: Any comments located in the v9.0 policy files will be preserved. Any comments contained in the v7.0 or later policy files will not be included in the v9.0 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 v9.0 file, the migration will bring it over. The migration makes any additions at the end of the original .policy files 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 directories	Migration copies files from prior version directories into the WAS v9.0 configuration.
Property files	WAS v9.0 migrates all the property files installed with v7.0 or later by merging settings into the v9.0 property files.
RARs referenced by J2C resources	RARs 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 WAS installation. Relational Resource Adapter RARs will not be migrated.
Migrate cluster-level resources:	WAS Version Cluster-level resources 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> This resource is in the same location on each cluster member (node). Therefore, each cluster member must have the RAR file installed at... ${WAS_INSTALL_ROOT}\installedConnectors\x2.rar In the migration of a dmgr, the tools migrate the cluster files on the dmgr, including the resourcexxx.xml files. In the migration of a federated node, the tools process each J2C adapter. Migration from v7.0 to v9.0 copies files such as RAR files from WAS_INSTALL_ROOT to WAS_INSTALL_ROOT and from USER_INSTALL_ROOT to USER_INSTALL_ROOT. If we have a RAR file in the WAS_INSTALL_ROOT for v7.0, for example, the migration tools do not automatically copy the file from WAS_INSTALL_ROOT to USER_INSTALL_ROOT. This maintains the integrity of the cluster-level J2C resources. If we hardcoded a path to a RAR file (archivePath="C:/WAS/installedConnectors/x2.rar" for example) in v7.0, however, the v9.0 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	No migration of samples from previous versions is available. There are equivalent WAS v9.0 samples that we can install.
Security	Java 2 security is enabled by default when we enable security in WAS v9.0. Java 2 security requires us to grant security permissions explicitly. There are several techniques that we can use to define different levels of Java 2 security in v9.0. 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 v9.0 properties directory to enterprise applications as they are being migrated. When migrating to WAS v9.0, our choice of whether or not to migrate to support script compatibility results in one of two different outcomes. If we choose to migrate to support script compatibility, the security configuration is brought over to v9.0 without any changes. This is the default. If we choose not to migrate to support script compatibility, the security configuration is converted to the default configuration for WAS v9.0. The default security configuration for v7.0 or later 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 our security configurations to v9.0, read the "Migrate, coexist, and interoperate - Security considerations" article in the documentation.
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 v9.0 installation root. The migration tools attempt to migrate existing passivation and working directories. Otherwise, appropriate v9.0 defaults are used. In a coexistence scenario, using common directories between versions can create problems.
Web modules	The specification level of the Java EE implemented in WAS v7.0 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.