Migrating cell configurations to new host machines using the command-line tool
You can migrate cell configurations from a previous version of WebSphere® Application Server that is hosted on one machine to an instance of WebSphere Application Server Version 8.5 that is hosted on a different machine. The source and target host machines do not need to run the same operating system.
Before you begin
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.
Review the migration planning information. See Knowledge Collection: Migration planning for WebSphere Application Server.
This information describes migrating cells to a different machine. For information on migrating cells on the same machine, see Migrating cells using the command line tools.
About this task
This task describes how to migrate each profile in a cell configuration from a previous version of WebSphere Application Server to WebSphere Application Server Version 8.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.
If WebSphere Application Server Version 8.5 is not installed on the source host machine, you must 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 Version 8.5 WASPreUpgrade tool, which you use to create the migration backup directory for the profile.
When the multiple source machines all have the same operating system architectures but different from the target machine, then only one source machine needs to have the target release installed. From that one source machine, the remote migration jar can be created and used on the other source machines.
This procedure assumes that the previous configuration is running and that you are migrating all profiles to a different host machine.
Procedure
- Back up the deployment manager and all old nodes In case of failure during the migration, save the current deployment manager and node configuration to a file that you can use later for recovery purposes.
- Change to the deployment_manager_profile_root/bin directory.
- Run the backupConfig command with the appropriate parameters and
save the current profile configuration to a file. For example:
previous_version_app_server_root\v70dmgr01\bin\ backupConfig.bat \mybackup_old_host\v70dmgr01backupBeforeV85migration.zip -username myuser -password mypass -nostop
previous_version_app_server_root/v70dmgr01/bin/backupConfig.sh /mybackup_old_host/v70dmgr01backupBeforeV85migration.zip -username myuser -password mypass -nostop
where mybackup_old_host is the location where the configuration restore points are stored. - For each node in the configuration, change to the node_profile_root/bin directory.
- Run the backupConfig command with the appropriate parameters and
save the current profile configuration to a file. For example:
previous_version_app_server_root\v70node01\bin\backupConfig.bat \mybackup_old_host\v70node01backupBeforeV85migration.zip -username myuser -password mypass -nostop
previous_version_app_server_root/v70node01 /bin/backupConfig.sh /mybackup_old_host/v70node01rbackupBeforeV85migration.zip -username myuser -password mypass -nostop
- Install WebSphere Application Server
Version 8.5
Install WebSphere Application Server Network Deployment, Base, or Express® Version 8.5 onto each target host in a new directory. For more information, see the documentation about installing an application-serving environment.
- 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 WebSphere Application Server Version 8.5 installed.Note: You must 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.
- 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 you must install WebSphere Application Server Version 8.5 on a system that matches the source profile before creating the remote migration jar. Once you have generated the remote migration jar, it will work on any system which matches the operating system and architecture.
- Create the remote migration .jar.
- In the command prompt, enter: cd $WAS_HOME/bin/migration/bin
- To create the .jar file, run: createRemoteMigrJar.bat(sh) -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
- Prepare the remote system for the WasPreUpgrade command.
- Send the .jar file to the system where your source profile resides.
- Extract the file to a temporary location.
- Cd to the bin directory in the temporary location.
- You 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.
- Identify the operating system and architecture of the source profile.
- Create the target deployment manager profile The target deployment manager profile is a new deployment manager profile that is the target of the migration.Avoid trouble: The Version 8.5 cell and node names must match the cell and node names in the previous configuration. If you create cells and nodes with new cell and node names, then the migration will fail.
- Run the manageprofiles command with the appropriate parameters to
create a deployment manager profile.
For example:
version_8.5_install_root\bin\manageprofiles.bat -create -profileName v70tov85dmgr01 -templatePath app_server_root\profileTemplates\ management -serverType DEPLOYMENT_MANAGER -nodeName currentDmgrNodeName -cellName currentCellName -hostName mydmgrhost.company.com
version_8.5_install_root/bin/manageprofiles.sh -create -profileName v70tov85dmgr01 -templatePath /opt/WebSphereV85/profileTemplates/ management -serverType DEPLOYMENT_MANAGER -nodeName currentDmgrNodeName -cellName currentCellName -hostName mydmgrhost.company.com
- Run the manageprofiles command with the appropriate parameters to
create a deployment manager profile.
- Save the current deployment manager configuration to the migration backup
directory To save the current deployment manager configuration to the migration backup directory, run the WASPreUpgrade command. The WASPreUpgrade command does not change the old configuration.
- Run the WASPreUpgrade command with the
-machineChange true
parameter to save the current deployment manager configuration to a migration backup directory.For example:<path to remote migration jar>\migration\bin\WASPreUpgrade.bat \mybackup_old_host\v70tov85dmgr01 app_server_root -oldProfile 70dmgr01 -machineChange true
<path to remote migration jar>/migration/bin/WASPreUpgrade.sh /mybackup_old_host/v70tov85dmgr01 /opt/WebSphereV70 -oldProfile 70dmgr01 -machineChange true
where mybackup_old_host is the directory to which the profile configuration files are copied in preparation for the migration to the new host.If you are migrating from Version 8.0 to Version 8.5 and your 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 you specify -machineChange true, you must update the job manager URL for all resources (such as other deployment managers or application servers) that are managed by the job manager function of the Version 8.0 deployment manager after the migration. - 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 Version 8.5.
If the command completed successfully, it is not necessary to check the logs for errors or warnings.
- Run the WASPreUpgrade command with the
- 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 WebSphere Application Server migration.
- Use the archive tool of your 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/
- Move the archived file to the target machine.
- 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 to which you are migrating your files.
- Use the archive tool of your choice to create a compressed file of the backup
directory.
- Restore the previous deployment manager configuration
Run the WASPostUpgrade command from the new deployment manager profile bin directory to restore the previous deployment manager configuration that you saved in the migration backup directory. If you use the options shown in the example, all ports are carried forward, and all applications are installed.
- Run the WASPostUpgrade command to restore the saved deployment
manager configuration into the new Version 8.5 deployment
manager profile. For example:
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
version_8.5_install_root/bin/WASPostUpgrade.sh / mybackup_new_host/v70tov85dmgr01 -profileName v70tov85dmgr01 -oldProfile 70dmgr01 -replacePorts TRUE -backupConfig TRUE -scriptCompatibility TRUE -keepDmgrEnabled TRUE -username myuser -password mypass
where mybackup_new_host is the directory from which the source profile configuration files are migrated. - 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 Version 8.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 your deployment manager must be the same as the flag that you use on your 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. You must complete a few more steps before starting the new deployment manager.
- Run the WASPostUpgrade command to restore the saved deployment
manager configuration into the new Version 8.5 deployment
manager profile.
- Save the Version 8.5 migrated deployment manager
configuration to a file To save theVersion 8.5 migrated deployment manager configuration to a file, run the backupConfig command on the Version 8.5 deployment manager.Avoid trouble: If you encounter a node migration failure, you can restore the cell configuration to the point before the failure. You can apply remedial actions and the attempt the node migration again.
- Change to the deployment_manager_profile_root/bin directory
- Run the backupConfig command with the appropriate parameters and
save the Version 8.5 profile configuration to a
file. For example:
version_8.5_profile_root\profiles\v70tov85dmgr01\ bin\backupConfig.bat \mybackup_new_host\v70tov85dmgr01backupMigratedDmgrOnly.zip -username myuser -password mypass
version_8.5_profile_root/profiles/v70tov85dmgr01/bin/backupConfig.sh / mybackup_new_host/v70tov85dmgr01backupMigratedDmgrOnly.zip -username myuser -password mypass
where mybackup_new_host is the location where the configuration restore points are stored.
- Stop and disable the deployment manager on the old host
Ensure that you do not use the deployment manager on the old host.
For more information, see clientUpgrade command.
- Stop the deployment manager on the old host.
- 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_name/serverindex.xml
- New name
- $PROFILE_ROOT/config/cells/cell_name/nodes/deployment_manager_node_name/serverindex.xml_disabled
- Start the Version 8.5 deployment
manager Start the deployment manager on the new host.
- Change to the new Version 8.5 deployment_manager_profile_root/bin directory.
- Run the startManager command.
- While the deployment manager is running, check the SystemOut.log
file for warnings or errors. Note: This topic references one or more of the application server log files. As a recommended alternative, you can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM i systems. You can also use HPEL in conjunction with your native z/OS® logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.Check the warnings to see if they affect any node migration or runtime activities when the Version 8.5 deployment manager is started.
- Ensure that the Version 8.5 deployment manager starts successfully.
- Manually synchronize all nodes You must synchronize the old nodes to the new Version 8.5 deployment manager. Ensure that the Version 8.5 deployment manager on the new host is running. You must log into the machine that contains the old nodes and run the syncNode command.
- Stop the node agent.
- 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 thecom.ibm.ws.scripting.port
value to the new port. - Run the syncNode command from the bin directory. For example:
node_agent_install_root\bin\syncNode.bat myV85DmgrHost.mycompany.com 8879 -username myuser -password mypass
node_agent_install_root/bin/syncNode.sh myV85DmgrHost.mycompany.com 8879 -username myuser -password mypass
- Start the node agent if synchronization is successful.
- Migrate application client installations Migrate client resources to Version 8.5-level resources. If the source WebSphere Application client is Version 6.1, you also must run the WASPreUpgrade and WASPostUpgrade commands to migrate the existing security settings.Avoid trouble: The clientUpgrade command is not supported for cross operating system migrations. This step applies to WebSphere Application client host machines only. On any of your client host machines, you must run the same host migration.
- Identify all client hosts that you must migrate.
- Install the WebSphere Version 8.5 Application client.
- Run the clientUpgrade command on your application client enterprise archive (EAR) files.
- Run the Version 8.5
WASPreUpgrade command to save the Application client security settings to a
migration backup directory. For example:
/opt/AppClientV85/bin/WASPreUpgrade.sh /mybackup_client/v70clientTov85 /opt/AppClientV70
- Run the Version 8.5
WASPostUpgrade command to restore the Application client security settings to the
new Version 8.5 client. For example:
/opt/AppClientV85/bin/WASPostUpgrade.sh /mybackup_client/v6clientToV85
Avoid trouble: The script compatibility flag on your deployment manager must be the same as the flag that you use on your clients.
- Migrate nodes These steps apply to cross-machine migrations only. If you are not completing a cross-machine migration of a node, see the information about migrating nodes in Migrating cells using the command-line tools. Ensure that the Version 8.5 deployment manager is running. For each node that you plan to migrate to Version 8.5, perform the following steps:Avoid trouble: For the migration to be successful, you must use the same source node name and cell name for each node that you migrate to Version 8.5 or later.
- Install WebSphere Application Server Version 8.5.
Install the correct version of WebSphere Application Server Network Deployment, Base, or Express onto each target host. For more information, see the documentation about installing an application-serving environment.
- Create the target node profile. Run the manageprofiles command with
the appropriate parameters to create a new managed profile.
For example:
version_8.5_install_root\bin\manageprofiles.bat -create -profileName node1 -templatePath \opt\ WebSphereV85\profileTemplates\managed -nodeName currentNode1Name -cellName currentCellName -hostName mynode1host.company.com
version_8.5_install_root/bin/manageprofiles.sh -create -profileName node1 -templatePath /opt/WebSphereV85/profileTemplates/managed -nodeName currentNode1Name -cellName currentCellName -hostName mynode1host.company.com
- Use the remote migration .jar file that you created for migrating the deployment
manager to make the WASPreUpgrade command available on the current node
machine. Note: 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.
- Run the WASPreUpgrade command with the
-machineChange true
parameter to save the current node X configuration to a migration backup directory. Choose a new directory for the backup files.For example:<path to remote migration jar>\migration\bin\WASPreUpgrade.bat \mybackup_old_host\v70tov85node1 \opt\WebSphereV70 -oldProfile 70node1 -machineChange true
<path to remote migration jar>/migration/bin/WASPreUpgrade.sh /mybackup_old_host/v70tov85node1 /opt/WebSphereV70 -oldProfile 70node1 -machineChange true
- Check the WASPreUpgrade console output for error and warning
messages. You 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, you do not need to check the log files for error or warning messages.
- Use the archive tool of your 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/
- Move the archived file to the target machine.
- 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. - Stop the application servers on the old node, then stop the node agent on the old node.
- Stop and disable the node on the old host. Ensure that you 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
- Run the WASPostUpgrade command to restore the saved node X
configuration into the new Version 8.5 managed profile.
For example:
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
version_8.5_install_root/bin/WASPostUpgrade.sh / mybackup_new_host/v70tov85node1 -profileName v70tov85node1 -oldProfile 70node1 -replacePorts TRUE -backupConfig TRUE -includeApps TRUE -scriptCompatibility TRUE -username myuser -password mypass
Avoid trouble: The script compatibility flag on your deployment manager must be the same as the flag that you use on your clients. - Check the WASPostUpgrade console output for the following
messages. You 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
Note: If the WASPostUpgrade command fails, you might need to restore the Version 8.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. - Check the Version 8.5 deployment manager
SystemOut.log file for error or warning messages. Note: This topic references one or more of the application server log files. As a recommended alternative, you can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM i systems. You can also use HPEL in conjunction with your native z/OS logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.
- Start the migrated Version 8.5 node X agent.
- Check the Version 8.5 deployment manager and node X SystemOut.log for error or warning messages.
- Optional: Synchronize the cell if the auto synchronization process is not enabled.
- Optional: Start the appropriate application servers on Version 8.5 migrated node X.
- Run the backupConfig command and save the Version 8.5 profile configuration to a file. For example:
version_8.5_profile_root\v70tov85node1\bin\backupConfig.bat \mybackup_new_host\v70tov85node1.zip -username myuser -password mypass -nostop
version_8.5_profile_root/v70tov85node1/bin/backupConfig.sh /mybackup_new_host/v70tov85node1.zip -username myuser -password mypass -nostop
Each time you run the backupConfig command on a specific node, use a new backup file name. - Save the deployment manager configuration using the backupConfig
command.
On the Version 8.5 deployment manager host, change to the deployment_manager_profile_root/bin directory. Run the backupConfig command and save the Version 8.5 profile configuration to a file.For example:
version_8.5_profile_root\v70tov85dmgr01\bin\backupConfig.bat \mybackup_new_host\v70tov85dmgr01backupMigratedDmgrPlusNodeX.zip -username myuser -password mypass
version_8.5_profile_root/v70tov85dmgr01/bin/backupConfig.sh /mybackup_new_host/v70tov85dmgr01backupMigratedDmgrPlusNodeX.zip -username myuser -password mypass
Note: For each node that you migrate, backup the Version 8.5 Deployment Manager configuration to a new backup file. - Repeat the previous steps for additional nodes.
- Install WebSphere Application Server Version 8.5.
- Migrate plug-ins for web servers
The product supports several different web servers, as described in the system requirements. For installation information, see the documentation for your web server type and version.
- Ensure that the Version 8.5 deployment manager is running.
- Update the version of the web server plug-in that is used in the cell.
-
For all application servers in the cell that you want to be served by the web server, create a
new web server definition for web server plug-in.
For more information about creating web server definitions, see Implementing a web server plug-in.
Results
You used the migration tools to migrate the cell configurations from a previous version of WebSphere Application Server to new host machines that run WebSphere Application Server Version 8.5.