Migration considerations

Considerations for AIX®, HP-UX, IBM® i, Linux®, Solaris, and Windows operating systems

• Before you perform the migration, evaluate the items deprecated in WebSphere Application Server Version 9.0.

  For more information, see Deprecated, stabilized, superseded, and removed features.

• High-availability manager (HAM) and core-group functionality are included in WebSphere Application Server Version 7.0 or later.

  See Core group migration considerations for core-group configuration and topology considerations that might impact your migration from Version 7.0 or later to Version 9.0.

  Note: In most cases the recommended number of servers in a core group should not exceed 50. You receive a warning message when the migration tools add a server that exceeds the recommended maximum limit.
• The configuration migration tools do not convert applications or make them compatible with a new Java SDK level. Before you migrate to a new Java SDK, use the WebSphere Application Server Migration Toolkit to evaluate your applications for any changes that you might need to make, and test your applications after you make any required updates. See WebSphere Migration Knowledge Collection: Migrating to Liberty.

  See Migrating API and specifications for more information.

• The migration tools create a migration backup directory containing a backup copy of the configuration from the previous version, which is the size of the configuration directory and applications from the previous profile plus the trace files. In addition, your system must have space for the target profile, which after migration will be the same size as the source profile.

  The amount of storage that your system requires for the backup directory depends on your environment as well as on the migration tool that you are using.

  • Location: Backup directories as specified as parameters of the WASPreUpgrade and WASPostUpgrade commands
  • Amount: For an estimate of your storage requirements when using these commands, add the following amounts.
    • Size of the following items for all of the profiles in your previous configuration:
      • profile_root/installableApps directory
      • profile_root/installedApps directory
      • profile_root/config directory
      • profile_root/properties directory
      • Shared libraries referenced in the libraries.xml configuration files
      • Resource adapter archive (RAR) files referenced in the resources.xml configuration files
    • If trace is enabled, allow enough space for the trace files, which depends on the size and complexity of your configuration.
• If you use isolated data repositories—specifically, nonshared data repositories such as transaction logs for SIB and Apache Derby databases—and you migrate from a previous release, your existing databases and transaction logs are saved when the WASPreUpgrade command is run. Any database changes that you make after you run the WASPreUpgrade command are not reflected in the migrated environment.
  • If you have mission-critical information that is stored in these local data repositories, you should safely shut down all servers that interact with those repositories before attempting migration. Those servers should remain offline until the migration has been successfully completed or rolled back.
  • If you make multiple attempts at migration, either because of unexpected rollback or to apply fixes, rerun the WASPreUpgrade command so that any changes to your isolated data repositories are reflected in the migrated environment.
  After the migration is complete or you have rolled back to the previous version, you can restart the servers that interact with these isolated data repositories.
• Do not migrate a node with active servers if the SIB uses the file-store option for one or all of the messaging engines.
  • The WASPreUpgrade command fails with a file-locked exception when you try to copy the file stores on an active application server.
  • The WASPreUpgrade command copies a locked file, which could compromise data consistency.
  A data store for the messaging engine is an option for a hot migration; but if a file store must be used, the servers should not be running.
• If you try to run the WASPreUpgrade command to migrate from Version 6.1 with the node and application server that own the SIB file store still running, you might get an error similar to the following:

  C:\was80A\bin>WASPreUpgrade c:\bkupWAS6.1.0.17June30B C:\was61B 
  MIGR0385I: Starting to save profile AppSrv01. 
  MIGR0215W: The migration function cannot copy the file and open the destination file 
  c:\bkupWAS6.1.0.17June30B\migrated\C_\FSJune19\Log. 
  MIGR0272E: The migration function cannot complete the command. 

  If you then shut down the application server and node, the WASPreUpgrade command completes.
• Before you migrate an Apache Derby database, ensure that any application servers hosting applications that are using the Apache Derby database are closed. Otherwise, the Apache Derby migration fails.
• You should be aware of the following rules related to migrating security domains:
  • If you migrate a deployment manager that has a security domain with a cell-level scope, the migration tools take the following actions:
    • Migration creates a domain in the new configuration called PassThroughToGlobalSecurity if it does not already exist.
    • Migration adds a cluster mapping to the new configuration for all clusters that existed in the old configuration.
      • Clusters that only existed in the Version 9.0 deployment-manager configuration before migration do not have their mappings to PassThroughToGlobalSecurity changed.
        • If mappings for the Version 9.0 clusters exist before migration, they still exist after migration.
        • If no mappings for the Version 9.0 clusters exist before migration, they still do not exist after migration.
      • If a cluster exists in both the previous configuration and the Version 9.0 configuration before migration, the cluster in the new configuration is added to the PassThroughToGlobalSecurity domain and behaves like the cluster in the previous release.
    • Migration adds a bus mapping for any busses that exist in a migrated Version 6.1.x configuration.

      Bus mappings are updated following the same rules as those for cluster mapping.

    • Administrative servers (deployment manager) are not added to the PassThroughToGlobalSecurity domain.
  • If you migrate a federated node that has a security domain with a cell-level scope, the migration tools take the following actions:
    • Migration creates a domain in the new configuration called PassThroughToGlobalSecurity if it does not already exist.
    • Migration adds a server-level mapping to the PassThroughToGlobalSecurity domain for all non-clustered servers in the old node's configuration.
      • Servers on the node that is being migrated that are part of a cluster do not receive entries in the PassThroughToGlobalSecurity domain because this was addressed through a cluster mapping during deployment-manager migration.

        If you have removed that mapping, migration maintains that behavior.

      • Administrative servers (node agents) are not added to the PassThroughToGlobalSecurity domain.

  For more information, see the Security domains in a mixed-version environment section of Multiple security domains.

• The process for disabling credential prompting has changed.

  To disable credential prompting in Version 9.0, configure the ipc.client.props to disable credential prompting before migrating from Version 6.1 to Version 9.0.

• During migration, some of your application metadata might be reset to the default and cause the application to function differently from what you expect.

  If you installed an application in your old environment with Use Metadata From Binaries set to true and during that installation or a future update of the application you made a change to the application's metadata (such as JNDI resource references or database entries for example), the change might be lost when you migrate.

  When Use Metadata From Binaries is set to true, the administrative code only updates the metadata in the binary EAR file. This option is not supported in a mixed cell; therefore, it is automatically turned to false as part of migration. When this happens, the expanded metadata in the configuration directories take precedence over the values in the binary EAR file. This causes the values from the original EAR file installation to take precedence over any updates that you might have made.

  Perform one of the following actions to resolve this issue:

  • Before migrating, update your applications in the old environment and set Use Metadata From Binaries to false. Ensure that the applications are functioning correctly with this new setting, and then run the migration.
  • After migrating, update your applications and correct the metadata as required to allow the applications to function appropriately.
• After you use the migration tools to migrate to WebSphere Application Server Version 9.0, you might need to perform some actions that are not done automatically by the migration tools.
  • Examine any Lightweight Third-Party Authentication (LTPA) security settings that you might have used in WebSphere Application Server Version 7.0 or later, and verify that Version 9.0 security is set appropriately.

    See Lightweight Third Party Authentication for more information.

  • Check the WASPostUpgrade.log file in the logs directory for details about any JavaServer Pages (JSP) objects that the migration tools did not migrate.

    If Version 9.0 does not support a level for which JSP objects are configured, the migration tools recognize the objects in the output and log them.

  • Review your Java™ Virtual Machine (JVM) settings to verify that you are using a heap size of at least 50 for improved startup performance.

    See Java virtual machine settings for more information.

    If you have used a smaller heap size before, you can use the default heap size of 50.

  • Verify the results of the automatic Apache Derby database migration, and manually migrate any Apache Derby databases that are not automatically migrated by the tools.

    See Migrating Apache Derby databases for more information.