Clone migrating cells using the command-line tools

You can use command-line tools to migrate a cell from a previous version of WebSphere® Application Server to Version 9.0. A clone migration sets the -clone optional parameter to true in a WASPostUpgrade migration command, which enables you to continue to use a source profile after you migrate it to a Version 9.0 environment.

Restriction: Clone migration from IBM® i or z/OS is not supported.

Before you begin

This topic is about profile configuration clone migration, specifically clone migrating cells on the same host.

To clone migrate cells to a different host, see Clone migrating cells to new host machines using the command-line tools.
For a standard cell migration without profile cloning, see Migrating cells using the command-line tools.
To migrate cells to a different host without profile cloning, see Migrating cells to new host machines using the command-line tool.
To migrate your applications to the latest version, use the WebSphere Application Server Migration Toolkit.

For resources to help you plan and perform your migration, see Knowledge Collection: Migration planning for WebSphere Application Server.

Multimedia For videos about migrating cells, see the WebSphere Administration - Migrating cells using the command-line tools videos in the WebSphere Migration - Using the CMD line playlist. The steps in this topic are for a clone migration. The videos mention clone migration steps. To do a clone migration, set the -clone optional parameter to true in a WASPostUpgrade migration command.

Avoid trouble: Ensure that your setting for the maximum number of open files is 10000 or greater. If the number of open files is too low, this can cause various migration failures.

About this task

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. This procedure assumes that the previous configuration is running.

To migrate a cell configuration, you run WASPreUpgrade, WASPostUpgrade, manageprofiles, and other migration commands that are described in Using the migration tools. You can specify individual parameters on migration commands, or specify the -properties file_name.properties parameter to input a properties file.

For transitioning users: The following products previously required separate migration tools but are now migrated as part of the standard migration procedures:

WebSphere Extended Deployment Compute Grid or Feature Pack for Modern Batch
WebSphere Virtual Enterprise or Intelligent Management

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 by using the backupConfig command.
1. Change to the deployment_manager_profile_root/bin directory.
2. Run the backupConfig command with the appropriate parameters and save the current deployment manager profile configuration to a file.
```
/opt/WebSphereV70/profiles/v70dmgr01/bin/backupConfig.sh 
/mybackupdir/v70dmgr01backupBeforeV90migration.zip 
-username myuser -password mypass -nostop
```
  Tip: Windows users can revise the examples in this topic to run on a Windows computer. For example, to run the backupConfig command, use backupConfig or backupConfig.bat for the command. Change the file paths as needed for your environment. Windows command lines typically support a forward slash (/) in file paths as well as a backslash (\).
```
previous_version_app_server_root\v70dmgr01\bin\backupConfig.bat 
\mybackup_old_host\v70dmgr01backupBeforeV90migration.zip 
-username myuser -password mypass -nostop
```
  Replace mybackup_old_host with the location of your configuration backup.
3. For each node in the configuration, change to the node_profile_root/bin directory.
4. Run the backupConfig command with the appropriate parameters, and save the current node profile configuration to a file.
```
/opt/WebSphereV70/profiles/v70node01/bin/backupConfig.sh 
/mybackupdir/v70node01backupBeforeV90migration.zip 
-username myuser -password mypass -nostop
```
Install WebSphere Application Server Version 9.0 onto each target machine in a new directory.

For more information, see the installation documentation.

Create the target deployment manager profile by running the manageprofiles command with the appropriate parameters.

The target deployment manager profile is a new deployment manager profile that will be the target of the migration.

/opt/WebSphereV90/bin/manageprofiles.sh -create -profileName v90dmgr01 
-templatePath /opt/WebSphereV90/profileTemplates/management -serverType DEPLOYMENT_MANAGER 
-nodeName currentDmgrNodeName -cellName currentCellName -hostName mydmgrhost.company.com

Save the current deployment manager configuration to the migration backup directory by running the WASPreUpgrade command from the new deployment manager profile bin directory.

The WASPreUpgrade command does not change the Version 7.0 or later configuration.

Note: If you are migrating from Version 8.0 or later to Version 9.0 and your profile is a deployment manager, the Version 8.0 profile is stopped when you run the WASPreUpgrade command. 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.
1. Run the WASPreUpgrade command, specifying the migration backup directory, the Version 7.0 or later installation root directory, and the deployment manager profile name.
```
/opt/WebSphereV90/bin/WASPreUpgrade.sh /mybackup/v70toV90dmgr01 /opt/WebSphereV70 
-oldProfile v70dmgr01 -keepDmgrEnabled true -username myuser -password mypass
```
  For a same release migration, add -allowSameRelease true.
2. 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. If the output has either message, then check the WASPreUpgrade.old_Profile.timestamp.log and WASPreUpgrade.trace log files for any warnings or errors.
  
  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 9.0.
  
  If the command completed successfully, it is not necessary to check the logs for errors or warnings.
Restore the previous deployment manager configuration that you saved in the migration backup directory by running the WASPostUpgrade command.

If you use the options that are shown in the following example, all ports are carried forward, the old deployment manager is shut down and disabled, and all applications are installed. For more information, see WASPostUpgrade command.
1. Run the WASPostUpgrade command with the -clone parameter set to true.
```
/opt/WebSphereV90/bin/WASPostUpgrade.sh /mybackup/v70toV90dmgr01 
-oldProfile v70dmgr01 -profileName v90dmgr01 
-clone true -setPorts generateNew 
-username myuser -password mypass
```
  The -clone true parameter enables you to continue to use the old profile after it is migrated. If you specify a clone migration for the deployment manager, you must also clone all of its federated nodes. Specifying a clone migration automatically sets -keepDmgrEnabled to true.
  
  When you create profiles, only one profile is considered the default profile for an installation.
  
  You can identify the default profiles by looking in the profileRegistry.xml file in the WAS_HOME/properties directory. The source profileRegistry.xml is copied to the migration backup directory as part of the WASPreUpgrade command.
  
  Avoid trouble: Always specify the -oldProfile and -profileName parameters when you run the WASPostUpgrade command.
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. If the output has either message, then check the migration_backup_dir/logs/WASPostUpgrade.target_profile_name.timestamp.log and migration_backup_dir/logs/WASPostUpgrade.target_profile_name.trace log files for any warnings or errors. 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 9.0.
  
  If the configuration was migrated correctly but any applications were not installed, you can run the WASMigrationAppInstaller command to install only the applications that were not migrated. For more information, see WASMigrationAppInstaller command.
  
  If the command completed successfully, it is not necessary to check the logs for errors or warnings.
Back up the Version 9.0 deployment manager configuration to a file by running the backupConfig command on the Version 9.0 deployment manager.

Avoid trouble: This is an important step in the cell migration plan. If there are any node migration failures, you can restore the cell configuration to the point before the failure, apply remedial actions, and attempt the node migration again.
1. Change to the deployment_manager_profile_root/bin directory
2. Run the backupConfig command with the appropriate parameters.
```
/opt/WebSphereV90/profiles/v70toV90dmgr01/bin/backupConfig.sh 
/mybackupdir/v70toV90dmgr01backupMigratedDmgrOnly.zip 
-username myuser -password mypass
```
Start the Version 9.0 deployment manager.
1. Change to the new Version 9.0 deployment manager profile bin directory.
2. Run the startManager command.
3. 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.
For Compute Grid or Feature Pack for Modern Batch, verify that the job scheduler was migrated correctly and that you can dispatch jobs to the previous version servers that host your batch applications.
To verify the job scheduler migration, after the deployment manager restarts, access the job management console through a web browser.
To verify that the previous version servers that host your batch applications work correctly:
1. Verify that the batch applications on the migrated server or cluster are started. Examine the server or cluster logs for any errors.
2. Verify that you can dispatch batch jobs to the migrated server by submitting a job from the migrated job scheduler server. You can submit the job by using the Job Management Console, the WSGrid utility, the EJB interface, or the web services interface.
Migrate application client installations.

Migrate client resources to Version 9.0-level resources.
1. Install the WebSphere Version 9.0 application client.
  
  For more information, see the installation documentation.
2. Run the Version 9.0 WASPreUpgrade command to save the application client security settings to a migration backup directory.
```
/opt/AppClientV90/bin/WASPreUpgrade.sh /mybackup/v70clientToV90 /opt/AppClientV70
```
3. Run the Version 9.0 WASPostUpgrade command to restore the application client security settings to the new Version 9.0 client.
```
/opt/AppClientV90/bin/WASPostUpgrade.sh /mybackup/v70clientToV90
```
Migrate nodes.

Use the migration tools to migrate the previous versions of the nodes in the configuration to Version 9.0. Perform the following procedure for each node that you plan to migrate to Version 9.0.

Avoid trouble: You must use the same source node name but a different temporary cell name for each node that you migrate to Version 9.0.
1. Ensure that the Version 9.0 deployment manager is running.
2. Create the target node profile. Run the manageprofiles command with the appropriate parameters to create a new managed profile.
```
/opt/WebSphereV90/manageprofiles.sh -create -profileName node1 
-templatePath /opt/WebSphereV90/profileTemplates/managed -nodeName currentNode1Name 
-cellName tempCellName -hostName mynode1host.company.com
```
  Avoid trouble: The Version 9.0 -nodeName value must match the node name in the previous configuration. If the Version 9.0 deployment manager -nodeName value is different, the migration will fail.
3. Run the WASPreUpgrade command to save the current node configuration information to a migration backup directory. Specify a new directory for the backup files, the installation root directory, and the node profile.
```
/opt/WebSphereV90/bin/WASPreUpgrade.sh /mybackup/v70toV90node1 /opt/WebSphereV70 
-oldProfile 70node1
```
4. Review warnings or errors in the console output and WASPreUpgrade logs.
  Check the WASPreUpgrade console output for the Failed with errors or Completed with warnings messages. If the WASPreUpgrade command did not complete successfully, then look in the following logs for warnings or errors.
  - migration_backup_dir/logs/WASPreUpgrade.old_profile.timestamp.log
  - migration_backup_dir/logs/WASPreUpgrade.trace
5. Run the WASPostUpgrade command to restore the saved node configuration into the new Version 9.0 managed profile.
  Set the -clone parameter to true. Also, specify the -newDmgrHostname parameter, and at least one of the -newDmgrSoapPort or -newDmgrRmiPort parameters, filling in the appropriate values. Do not clone federated nodes unless the deployment manager was also cloned.
```
/opt/WebSphereV90/bin/WASPostUpgrade.sh /mybackup/v70toV90node1 
-profileName node1 -oldProfile 70node1 -username myuser -password mypass
-clone true -newDmgrHostname myV90DmgrHost.mycompany.com 
-newDmgrSoapPort 8879 -setPorts generateNew
```
6. Review warnings or errors in the console output and WASPostUpgrade logs.
  Check the WASPostUpgrade console output for the Failed with errors or Completed with warnings messages. If the command did not complete successfully, then look in the following logs for errors or warnings.
  - migration_backup_dir/logs/WASPostUpgrade.target_profile.timestamp.log
  - migration_backup_dir/logs/WASPostUpgrade.target_profile.trace
  Note: If the WASPostUpgrade command fails, you might have to restore the Version 9.0 deployment manager from the backupConfig file. If the WASPostUpgrade processing ran the syncNode command, the deployment manager is aware that the node was migrated. The node cannot be migrated again until the deployment manager is restored to the state before the node migration.
  
  If the configuration was migrated correctly but any applications were not installed, you can run the WASMigrationAppInstaller command to install only the applications that were not migrated. For more information, see WASMigrationAppInstaller command.
7. Check the Version 9.0 deployment manager 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.
8. Start the migrated Version 9.0 node agent.
```
/opt/WebSphereV90/profiles/v70toV90node1/bin/startNode.sh -profileName currentNode1Name
```
9. Check the Version 9.0 deployment manager and node SystemOut.log file for warnings or errors.
10. Synchronize the cell.
11. Stop all the application servers on the Version 9.0 migrated node.
12. Start the appropriate application servers on the Version 9.0 migrated node.
13. For Compute Grid or Feature Pack for Modern Batch, verify that the job scheduler was migrated correctly and that you can dispatch jobs to the migrated servers that host your batch applications.
  To verify the job scheduler migration, after the migrated application servers or clusters restart, access the job management console through a web browser.
  To verify that the Version 9.0 servers that host your batch applications work correctly:
  1. Verify that the batch applications on the migrated server or cluster are started. Examine the server or cluster logs for any errors.
  2. Verify that you can dispatch batch jobs to the migrated server by submitting a job from the migrated job scheduler server. You can submit the job by using the Job Management Console, the WSGrid utility, the EJB interface, or the web services interface.
14. Save the Version 9.0 profile configuration to a file by running the backupConfig command with the appropriate parameters.
```
/opt/WebSphereV90/profiles/v70toV90node1/bin/backupConfig.sh 
/mybackupdir/v70toV90node1.zip -username myuser 
-password mypass -nostop
```
  Each time that you run the backupConfig command, use a new backup file name.
15. Save the deployment manager configuration to a file by running the backupConfig command with the appropriate parameters.
  Before you run the command, change to the deployment_manager_profile_root/bin directory on the Version 9.0 deployment manager host.
  Tips:
  - For each node migrated, back up the Version 9.0 deployment manager configuration to a new backup file.
  - If you are migrating a node to a different host, refer to the information about migrating nodes in Clone migrating cells to new host machines using the command-line tools.
```
/opt/WebSphereV90/profiles/v70toV90dmgr01/bin/backupConfig.sh 
/mybackupdir/v70toV90dmgr01backupMigratedDmgrPlusNodeX.zip 
-username myuser -password mypass
```
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.
1. Ensure that the Version 9.0 deployment manager is running.
2. Update the version of the web server plug-in that is used in the cell.
3. 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 migrated from a previous version to WebSphere Application Server Version 9.0 using the migration tools.