Configuration mapping during product-configuration migration

Various configurations are mapped during product-configuration migration.

Supported configurations:

This topic is about configuration migration, such as migrating deployment managers and federated nodes in a network deployment environment. The Application Migration Toolkit for WebSphere Application Server provides support for migrating applications from previous versions of WebSphere Application Server to the latest product version. For information about migrating applications, read more about the Migration Toolkit.

Migration always involves migrating a single profile to another single profile on the same machine or a separate machine. Go to the documentation for the WebSphere® Application Server WebSphere Application Server Network Deployment product to learn how the migration tools map models, clones, server groups, clusters, and Lightweight Third Party Authentication (LTPA) security settings.

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 Version 8.5 environment.

Bootstrap port

The migration tools carry the old release value into the Version 8.5 environment.

[AIX Solaris HP-UX Linux Windows] If a value for the -portBlock parameter is specified during the call to WASPostUpgrade, however, the specified port value is given to each application server that is migrated to Version 8.5.

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 are not migrated because their roles in the WebSphere Application Server Version 8.5 configuration do not exist, have different meanings, or have different scopes.

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

Generic server

In Version 6.1 and 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, you might need to perform additional tasks. If the old resource that the generic server was managing is located under the old WebSphere Application Server installation, perform the following tasks:

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 that you reinstall the resource into the new WebSphere Application Server 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 WebSphere Application Server installation, nothing further is required.

Java heap size for migrating EAR files

When migrating all WebSphere Application Server Version 6.1 or later EAR files to Version 8.5 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 6.1 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 WebSphere Application Server Version 8.5:
Assume that:

Installation root

C:\WebSphere\AppServer

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
        -c "$AdminApp install 
               C:\\WebSphere\\AppServer\\installableApps\\
                  EAR_file_name
        {-nodeployejb 
         -appname app_name
         -server server_name 
         -node node_name}"
```

Policy files

WebSphere Application Server Version 8.5 migrates all the policy files that are installed with Version 6.1 or later by merging settings into the Version 8.5 policy files with the following characteristics:

Any comments located in the Version 8.5 policy files will be preserved. Any comments contained in the Version 6.1 or later policy files will not be included in the Version 8.5 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 8.5 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 files immediately 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 WebSphere Application Server Version 8.5 configuration.

Property files

WebSphere Application Server Version 8.5 migrates all the property files that are installed with Version 6.1 or later by merging settings into the Version 8.5 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 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

No migration of samples from previous versions is available. There are equivalent WebSphere Application Server Version 8.5 samples that you can install.

Security

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

[AIX Solaris HP-UX Linux Windows] There are several techniques that you can use to define different levels of Java 2 security in Version 8.5. 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 Version 8.5 properties directory to enterprise applications as they are being migrated.

When migrating to WebSphere Application Server Version 8.5, 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 Version 8.5 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 Version 8.5. The default security configuration for Version 6.1 and 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 your security configurations to Version 8.5, read the Migrating, coexisting, and interoperating – Security considerations topic in the documentation.

Stdin, stdout, stderr, passivation, and working directories

[AIX Solaris HP-UX Linux Windows] 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 WebSphere Application Server Version 8.5 installation root.

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

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

Transport ports

The migration tools migrate all ports. You must resolve any port conflicts before you can run servers at the same time.

Note: If ports are already defined in a configuration being migrated, the migration tools fix the port conflicts in the Version 8.5 configuration and log the changes for your verification.

If you specify the -portBlock parameter in the WASPostUpgrade command, the specified value is assigned to each transport that is migrated.

If you specify true for the -replacePorts parameter in the WASPostUpgrade command, all port values from the old configuration are used in the new configuration. If you specify false for the -replacePorts parameter, the default port definitions in the new profile are not replaced with the values from the old configuration during migration.

For more information on the WASPostUpgrade command, read 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 Configuring virtual hosts.

Web modules

The specification level of the Java Platform, Enterprise Edition (Java EE) implemented in WebSphere Application Server Version 6.1 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.

JVM system properties

If you migrate a Version 6.1 configuration that has feature packs installed, the migration tools might add one or two JVM system properties for each Java server in your configuration, including your administrative servers. Web servers are not affected. The properties are set to indicate to the JVM that the configuration should use a Java annotation scan policy other than the Version 8.5 default scan policy.

If you migrate a Version 6.1 profile that has the Feature Pack for EJB 3.0 installed, the migration tools add the following system property to the JVM definitions for all Java servers defined on that node:
```
com.ibm.websphere.ejb.UseEJB61FEPScanPolicy = true
```
If you migrate a Version 6.1 profile that has the Feature Pack for Web Services installed, the migration tools add the following system property to the JVM definitions for all Java servers defined on that node:
```
com.ibm.websphere.webservices.UseWSFEP61ScanPolicy = true
```
If you migrate a Version 6.1 profile that has both the Feature Pack for EJB 3.0 and the Feature Pack for Web Services installed, the migration tools add both of the system properties to the JVM definitions for all Java servers defined on that node:
```
com.ibm.websphere.ejb.UseEJB61FEPScanPolicy = true
com.ibm.websphere.webservices.UseWSFEP61ScanPolicy = true
```

If these properties are set, the following two changes take place in the default Version 8.5 behavior:

Application installation generates classes based on the annotation scan policy associated with the settings for those two properties.
This means that you can potentially use the following four annotation scan policies:
- Version 8.5 default behavior
- Feature Pack for EJB 3.0 behavior
- Feature Pack for Web Services behavior
- Net behavior from having both the Feature Pack for EJB 3.0 and the Feature Pack for Web Services installed
The servers use the generated annotation classes based on the properties set, resulting in four potential behaviors.

You can change the scan policy behavior by adding or removing the custom JVM system properties from your server.xml files. After changing the properties, you must reinstall or update your applications and then resynchronize the cell to implement the change.