Migrating cells using the command-line tools

You can use the command-line tools to migrate a cell from a previous version of WebSphere® Application Server to Version 9.0.

1. 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.

      /QIBM/UserData/WebSphere/AppServer/V7/ND/profiles/v70dmgr01/bin/backupConfig 
      /mybackupdir/v70dmgr01backupBeforeV90migration.zip 
      -username myuser -password mypass -nostop

   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.

      /QIBM/UserData/WebSphere/AppServer/V7/ND/profiles/v70node01/bin/backupConfig 
      /mybackupdir/v70node01rbackupBeforeV90migration.zip 
      -username myuser -password mypass -nostop

2. Install WebSphere Application Server Version 9.0 onto each target machine in a new directory.

   For more information, see the installation documentation.

3. 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.

   /QIBM/ProdData/WebSphere/AppServer/V9/ND/bin/manageprofiles -create -profileName v90dmgr01 
   -templatePath /QIBM/ProdData/WebSphere/AppServer/V9/ND/profileTemplates/management 
   -serverType DEPLOYMENT_MANAGER -nodeName currentDmgrNodeName -cellName currentCellName 
   -hostName mydmgrhost.company.com

4. 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. For more information, see WASPreUpgrade command.

   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.

      /QIBM/ProdData/WebSphere/AppServer/V9/ND/bin/WASPreUpgrade /mybackup/v70toV90dmgr01 
      /QIBM/UserData/WebSphere/AppServer/V9/ND -oldProfile v70dmgr01

      For transitioning users: In versions prior to Version 9.0, the source instance or profile root directory was specified rather than the installation directory. In Version 9.0, specify the profile name on the -oldProfile parameter.
   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.

5. 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.

      /QIBM/ProdData/WebSphere/AppServer/V9/ND/bin/WASPostUpgrade /mybackup/v70toV90dmgr01 -oldProfile v70dmgr01 
      -profileName v90dmgr01 -resolvePortConflicts incrementCurrent -backupConfig true 
      -includeApps true -keepDmgrEnabled false -username myuser -password mypass

      When you create profiles, only one profile is considered the default profile per 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.

6. 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.

      /QIBM/UserData/WebSphere/AppServer/V9/ND/profiles/myCurrentDmgrProfile/bin/backupConfig.sh 
      /mybackupdir/v70toV90dmgr01backupMigratedDmgrOnly.zip 
      -username myuser -password mypass

7. Start the Version 9.0 deployment manager.

   Ensure that the previous version of the deployment manager is not running.

   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.
   4. Check all of the node's node agent and application server logs for new warnings or errors.
      If automatic synchronization is enabled, allow the node to synchronize, allow the applications to restart, and then check the logs for new warnings or errors.
8. 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 

9. 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.

      /QIBM/ProdData/WebSphere/AppServer/V9/ND/bin/manageprofiles -create 
      -profileName currentNode1Name -templatePath /QIBM/ProdData/WebSphere/AppServer/V9/ND/profileTemplates/managed 
      -nodeName currentNode1Name -cellName tempCellName -hostName mynode1host.company.com

   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.

      /QIBM/ProdData/WebSphere/AppServer/V9/ND/bin/WASPreUpgrade 
      /mybackup/v70toV90node1 /QIBM/UserData/WebSphere/AppServer/V7/ND -oldProfile 70node1

   4. Review warnings or errors in the console output and WASPreUpgrade logs.

      Check the WASPreUpgrade console output for messages such as Failed with errors or Completed with warnings. If the command did not complete successfully, then look in the following logs for errors or warnings.

      • migration_backup_dir/logs/WASPreUpgrade.old_profile.timestamp.log
      • migration_backup_dir/logs/WASPreUpgrade.trace

      If the WASPreUpgrade command completed successfully, then checking the logs for errors or warnings is not necessary.

   5. Stop the node agent.
      If you have Version 7.0 or later nodes running during a migration to Version 9.0, you must stop the node agent on the node that is being migrated. If you do not stop the node agent, you might encounter corruption problems.
   6. Run the WASPostUpgrade command to restore the saved node configuration into the new Version 9.0 managed profile.

      /QIBM/ProdData/WebSphere/AppServer/V9/ND/bin/WASPostUpgrade /mybackup/v70toV90node1 
      -profileName currentNode1Name -oldProfile 70node1 -resolvePortConflicts incrementCurrent 
      -backupConfig true -username myuser -password mypass

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

      Check the WASPostUpgrade console output for Failed with errors or Completed with warnings messages. If the output has either message, 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.

      If the command completed successfully, then checking the logs for errors or warnings is not necessary.

   8. 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.
   9. Start the migrated Version 9.0 node agent.
   10. Check the Version 9.0 deployment manager and node SystemOut.log file for warnings or errors.
   11. Synchronize the cell.
   12. Stop all the application servers on the Version 9.0 migrated node.
   13. Start the appropriate application servers on the Version 9.0 migrated node.
   14. Save the Version 9.0 profile configuration to a file by running the backupConfig command with the appropriate parameters.

       /QIBM/UserData/WebSphere/AppServer/V9/profiles/v70toV90node1/bin/backupConfig 
       /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.

       Note: For each node migrated, back up the Version 9.0 deployment manager configuration to a new backup file.

       /QIBM/UserData/WebSphere/AppServer/V9/profiles/currentDmgrName/bin/backupConfig.sh 
       /mybackupdir/v70toV90dmgr01backupMigratedDmgrPlusNodeX.zip 
       -username myuser -password mypass

10. 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.