Migrate cell configurations to new host machines

Overview

This article is about migrating deployment managers and federated nodes in a network deployment environment. The Application Migration Toolkit for WAS supports migrating applications from previous versions of WAS to the latest product version.

These steps apply to cross-machine migrations only. If we are not completing a cross-machine migration of a node, see the information about migrating nodes

Before starting, Review the migration planning information.

This task describes how to migrate each profile in a cell configuration from a previous version of WAS to WAS v8.5 hosted on a different machine. The cell configuration consists of a deployment manager with one or more nodes, a web server, and an application client. All ports are migrated forward into the new configuration. The source and target host machines do not need to run the same operating system.

If WAS v8.5 is not installed on the source host machine, generate a remote migration .jar file on the target host machine that matches the operating system of the source machine. The remote migration .jar file provides the source host with the v8.5 WASPreUpgrade tool, which you use to create the migration backup directory for the profile.

This procedure assumes that the previous configuration is running and that you are migrating all profiles to a different host machine.

Ensure the setting for the maximum number of open files is 10000 or greater. If the number of open files is too low, this can cause a variety of migration failures.

Migrate cell configurations

1. Back up the deployment manager and all old nodes

   In case of failure during the migration, we save the current deployment manager and node configuration to a file that can be used later for recovery purposes.

   1. Change to the deployment_manager_profile_root/bin directory.

   2. Save the current profile configuration to a file. For example:
      cd previous_version_app_server_root\v70dmgr01\bin\
      backupConfig.bat c:\tmp\v70dmgr01backupBeforeV85migration.zip -username myuser -password mypass -nostop

   3. For each node in the configuration, save the current profile configuration to a file...
      cd previous_version_app_server_root\v70node01\bin\
      • backupConfig.bat c:\tmp\v70node01backupBeforeV85migration.zip -username myuser -password mypass -nostop

2. Install WAS ND, Base, or Express v8.5 onto each target host in a new directory.

3. Create the remote migration .jar file

   This .jar file contains the files necessary to run the WASPreUpgrade command on a system which does not have WAS v8.5 installed.

   Avoid trouble: Create the remote migration .jar file on the same operating system and architecture as you installed the source. Because the archive that is generated contains operating system specific code, it only executes on this architecture.

   1. Identify the operating system and architecture of the source profile.

      If the operating system and architecture of the source profile is different from the operation system or the architecture of the target profile, then install WAS v8.5 on a system that matches the source profile before creating the remote migration jar. Once we have generated the remote migration jar, it will work on any system which matches the operating system and architecture.

   2. Create the remote migration .jar.
      cd $WAS_HOME/bin/migration/bin
      createRemoteMigrJar.bat -targetDir <dir for the remote migration jar>

      This creates the following file:

      WAS_V85_OS.arch_RemoteMigrSupport.zip

      For example:

      WAS_V85_windows.x86_RemoteMigrSupport.zip

   3. Prepare the remote system for the WasPreUpgrade command.

      1. Send the .jar file to the system where the source profile resides.

      2. Extract the file to a temporary location.

      3. Cd to the bin directory in the temporary location.

      4. We are now ready to run the WASPreUpgrade command against the source profile. However, do not issue this command until you are told to do so in a later step.

4. Create the target dmgr profile The target dmgr profile is a new dmgr profile that is the target of the migration.

   The v8.5 cell and node names must match the cell and node names in the previous configuration. If we create cells and nodes with new cell and node names, then the migration will fail.

5. Create a dmgr profile...
   cd version_8.5_install_root\bin\
   manageprofiles.bat -create -profileName v70tov85dmgr01 -templatePath \opt\WebSphereV85\profileTemplates\ management -serverType DEPLOYMENT_MANAGER -nodeName currentDmgrNodeName -cellName currentCellName -hostName mydmgrhost.company.com

6. Save the current deployment manager configuration to the migration backup directory
   cd <path to remote migration jar>\migration\bin\
   • WASPreUpgrade.bat c:\tmp\v70tov85dmgr01 \opt\WebSphereV70 -oldProfile 70dmgr01 -machineChange true

   If we are migrating from Version 8.0 to v8.5 and the profile is a deployment manager, Version 8.0 profile is stopped when WASPreUpgrade runs. The deployment manager is only started before WASPreUpgrade completes if you provide -keepDmgrEnabled true on the command line or specify the corresponding option in the Migration wizard.

   Avoid trouble: If we specify -machineChange true, you must update the job manager URL for all resources (such as other deployment managers or application servers) managed by the job manager function of the Version 8.0 deployment manager after the migration.

7. Review warnings or errors in the console output and WASPreUpgrade logs. After the WASPreUpgrade command is complete, check the console output for Failed with errors or Completed with warnings messages. Then, check the following log files for any warnings or errors:

   • mybackup_old_host/v70tov85dmgr01/logs/WASPreMigrationSummary.log

   • mybackup_old_host/v70tov85dmgr01/logs/WASPreUpgrade.timestamp.log

   • mybackup_old_host/v70tov85dmgr01/logs/WASPreUpgrade.trace

   If there are errors, fix the errors and run the WASPreUpgrade command again. Check whether the warnings affect any other migration or runtime activities on v8.5.

   If the command completed successfully, it is not necessary to check the logs for errors or warnings.

Archive the backup directory created by the WASPreUpgrade command

Avoid trouble: Do not use the Windows archive tool because it is not compatible with a WAS migration.

1. Use the archive tool of the choice to create a compressed file of the backup directory. For example:
   cd /mybackup_old_host
   /opt/WebSphereV70/java/bin/jar -cf v70tov85dmgr01.jar v70tov85dmgr01/

2. Move the archived file to the target machine.

3. Create a directory on the target machine and extract the archived file to the new directory...
   mkdir /mybackup_new_host
   cd /mybackup_new_host
   /opt/WebSphereV85/java/bin/jar -xf v70tov85dmgr01.jar

   where mybackup_new_host is the directory to which we are migrating the files.

Restore the previous deployment manager configuration

All ports are carried forward, and all applications are installed.

1. Restore the saved deployment manager configuration into the new v8.5 dmgr profile. For example:
   cd version_8.5_install_root\bin\
   • WASPostUpgrade.bat \ mybackup_new_host\v70tov85dmgr01 -profileName v70tov85dmgr01 -oldProfile 70dmgr01 -replacePorts TRUE -backupConfig TRUE -scriptCompatibility TRUE -keepDmgrEnabled TRUE -username myuser -password mypass

2. Review warnings or errors in the console output and WASPostUpgrade logs.

   After the WASPostUpgrade command is complete, check the console output for Failed with errors or Completed with warnings messages. Then, check the following log files for any warnings or errors:

   • mybackup_new_host/v70tov85dmgr01/logs/WASPostMigrationSummary.log
   • mybackup_new_host/v70tov85dmgr01/logs/WASPostUpgrade.target profile name.timestamp.log
   • mybackup_new_host/v70tov85dmgr01/logs/WASPostUpgrade.target profile name.trace

   If there are errors, fix the errors and run the WASPostUpgrade command again. Check whether the warnings affect any other migration or runtime activities on v8.5.

   If the command completed successfully, it is not necessary to check the logs for errors or warnings.

Avoid trouble:

• The script compatibility flag on the deployment manager must be the same as the flag that you use on the clients. Save the value of the script compatibility flag for later use.

• After the WASPostUpgrade command completes successfully, do not start the new deployment manager. Complete a few more steps before starting the new deployment manager.

Save the v8.5 migrated deployment manager configuration to a file To save thev8.5 migrated deployment manager configuration to a file, run the backupConfig command on the v8.5 deployment manager.

Avoid trouble: If we encounter a node migration failure, we can restore the cell configuration to the point before the failure. We can apply remedial actions and the attempt the node migration again.

cd version_8.5_profile_root\profiles\v70tov85dmgr01\bin\
• backupConfig.bat \mybackup_new_host\v70tov85dmgr01backupMigratedDmgrOnly.zip -username myuser -password mypass

Stop and disable the deployment manager on the old host

Ensure that we do not use the deployment manager on the old host.

1. Stop the deployment manager on the old host.

2. Disable the deployment manager on the old host. To disable this deployment manager, you must rename the associated serverindex.xml file as indicated in the following information:

   Old name

   $PROFILE_ROOT/config/cells/cell_name/nodes/deployment_manager_node/serverindex.xml

   New name

   $PROFILE_ROOT/config/cells/cell_name/nodes/deployment_manager_node/serverindex.xml_disabled

Start the v8.5 deployment manager Start the deployment manager on the new host.

1. Change to the new v8.5 deployment_manager_profile_root/bin directory.

2. Run the startManager command.

3. While the deployment manager is running, check the SystemOut.log file for warnings or errors.

   Check the warnings to see if they affect any node migration or runtime activities when the v8.5 deployment manager is started.

4. Ensure that the v8.5 deployment manager starts successfully.

Manually synchronize all nodes We must synchronize the old nodes to the new v8.5 deployment manager. Ensure that the v8.5 deployment manager on the new host is running. We must log into the machine containing the old nodes and run the syncNode command.

1. Stop the node agent.

2. Obtain the deployment manager host and port number and update the node_agent_profile_root/properties/wsadmin.properties file. Change the com.ibm.ws.scripting.host value to the new host. Change the com.ibm.ws.scripting.port value to the new port.

3. Run the syncNode command...
   node_agent_install_root\bin\syncNode.bat myV85DmgrHost.mycompany.com 8879 -username myuser -password mypass

4. Start the node agent if synchronization is successful.

Migrate plug-ins for web servers

1. Ensure that the v8.5 deployment manager is running.

2. Upgrade the version of the web server plug-in used in the cell.

3. See the supporting information that is applicable to the web server type and version.

Migrate application client installations Migrate client resources to v8.5-level resources. If the source WebSphere Application client is Version 6.1, we also must run the WASPreUpgrade and WASPostUpgrade commands to migrate the existing security settings.

The clientUpgrade command is not supported for cross operating system migrations. This step applies to WebSphere Application client host machines only. On any of the client host machines, you must run the same host migration.

1. Identify all client hosts that migrate.

2. Install the WebSphere v8.5 Application client.

3. Run the clientUpgrade command on the application client EAR files.

4. Save the Application client security settings to a migration backup directory. For example:
   cd /opt/AppClientV85/bin/
   WASPreUpgrade.sh /mybackup_client/v70clientTov85 /opt/AppClientV70

5. Restore the Application client security settings to the new v8.5 client. For example:
   cd /opt/AppClientV85/bin/
   • WASPostUpgrade.sh /mybackup_client/v6clientToV85

   The script compatibility flag on the deployment manager must be the same as the flag that you use on the clients.

Migrate nodes

These steps apply to cross-machine migrations only. If we are not completing a cross-machine migration of a node, see the information about migrating nodes in Migrate cells using the command-line tools. Ensure that the v8.5 deployment manager is running. For each node to migrate to v8.5, perform the following steps:

For the migration to be successful, use the same source node name and cell name for each node that you migrate to v8.5 or later.

1. Install WAS v8.5.

   Install the correct version of WAS Network Deployment, Base, or Express onto each target host.

2. Create the target node profile.
   cd version_8.5_install_root\bin\
   • manageprofiles.bat -create -profileName node1 -templatePath \opt\ WebSphereV85\profileTemplates\managed -nodeName currentNode1Name -cellName currentCellName -hostName mynode1host.company.com

3. Use the remote migration .jar file created for migrating the deployment manager to make the WASPreUpgrade command available on the current node machine.

   This step needs be done only if the source node and deployment manager are not on the same machine, and this step can be done only if the machine architecture is the same. For more information, see step 3 of this scenario, Create the remote migration .jar file.

4. Save the current node X configuration to a migration backup directory.

   Choose a new directory for the backup files.

   cd <path to remote migration jar>\migration\bin\
   • WASPreUpgrade.bat \mybackup_old_host\v70tov85node1 \opt\WebSphereV70 -oldProfile 70node1 -machineChange true

5. Check the WASPreUpgrade console output for error and warning messages.

   We might find the following messages: "Failed with errors" or "Completed with warnings". Also, look in the following log files for error or warning messages:

   • myback_old_host/v70tov85node1/logs/WASPreMigrationSummary.log
   • myback_old_host/v70tov85node1/logs/WASPreUpgrade.<timestamp >.log
   • myback_old_host/v70tov85node1/logs/WASPreUpgrade.trace

   If the WASPreUpgrade command is successful, we do not need to check the log files for error or warning messages.

6. Use the archive tool of the choice to create a compressed file of the backup directory that was created by the WASPreUpgrade command. For example:
   cd /mybackup_old_host /opt/WebSphereV70/java/bin/jar -cf v70tov85node1.jar v70tov85node1/

7. Move the archived file to the target machine.

8. Create a directory on the target machine and extract the archived file to the new directory. For example:
   mkdir /mybackup_new_host
   cd /mybackup_new_host
   /opt/WebSphereV85/java/bin/jar -xf v70tov85dmgr01.jar

   ...where mybackup_new_host is the directory from which the profile configuration files are migrated.

9. Stop the application servers on the old node, then stop the node agent on the old node.

10. Stop and disable the node on the old host.

    Ensure that we do not use the node on the old host. To disable the node, you must rename the associated serverindex.xml file as indicated in the following information:

    Old name

    $PROFILE_ROOT/config/cells/cell_name/nodes/node_X/serverindex.xml

    New name

    $PROFILE_ROOT/config/cells/cell_name/nodes/node_X/serverindex.xml_disabled

11. Restore the saved node X configuration into the new v8.5 managed profile. For example:
    cd version_8.5_install_root\bin\
    • WASPostUpgrade.bat \ mybackup_new_host\v70tov85node1 -profileName v70tov85node1 -oldProfile 70node1 -replacePorts TRUE -backupConfig TRUE -includeApps TRUE -scriptCompatibility TRUE -username myuser -password mypass

    The script compatibility flag on the deployment manager must be the same as the flag that you use on the clients.

12. Check the WASPostUpgrade console output for the following messages. We might find the following messages: "Failed with errors" or "Completed with warnings". Also, look in the following log files for errors or warning messages:
    • mybackup_new_host/v70tov85node1/logs/WASPostMigrationSummary.log
    • mybackup_new_host/v70tov85node1/logs/WASPostUpgrade. <target profile>.< timestamp >.log
    • mybackup_new_host/v70tov85node1/logs/WASPostUpgrade.< target profile name >.trace

    If the WASPostUpgrade command fails, we might need to restore the v8.5 deployment manager from the backup configuration file. If the WASPostUpgrade command processing ran the syncNode command, then the deployment manager is aware that the node X has been migrated. The node X cannot be migrated again until the deployment manager has been restored to the state before the node X migration.

13. Check the v8.5 deployment manager SystemOut.log file for error or warning messages.

14. Start the migrated v8.5 node X agent.

15. Check the v8.5 deployment manager and node X SystemOut.log for error or warning messages.

16. Optional: Synchronize the cell if the auto synchronization process is not enabled.

17. Optional: Start the appropriate application servers on v8.5 migrated node X.

18. Save the v8.5 profile configuration to a file...
    cd version_8.5_profile_root\v70tov85node1\bin\
    • backupConfig.bat \mybackup_new_host\v70tov85node1.zip -username myuser -password mypass -nostop

19. Save the deployment manager configuration using the backupConfig command. On the v8.5 deployment manager host, change to the deployment_manager_profile_root/bin directory.

    Save the v8.5 profile configuration to a file...

    cd version_8.5_profile_root\v70tov85dmgr01\bin\
    • backupConfig.bat \mybackup_new_host\v70tov85dmgr01backupMigratedDmgrPlusNodeX.zip -username myuser -password mypass

    For each node that you migrate, backup the v8.5 Deployment Manager configuration to a new backup file.

20. Repeat the previous steps for additional nodes.

Results

You used the migration tools to migrate the cell configurations from a previous version of WAS to new host machines that run WAS v8.5.