You can clone 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 9.0 that is hosted on a different machine. The source
and target host machines do not need to run the same operating system.
Restriction: Remote 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 to
a different host. 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.
For resources to help you plan and perform your migration, see Knowledge Collection: Migration planning for WebSphere Application Server.
For videos about migrating cells to
a different machine, see the WebSphere Administration - Migrating cells
REMOTELY 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 a variety of
migration failures.
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 9.0 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.
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.
If WebSphere Application Server
Version 9.0 is not installed on the source host machine, you
must generate a remote migration Java archive (JAR or .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 9.0
WASPreUpgrade tool, which you use to create the migration backup directory for
the profile.
The
WASPreUpgrade command must be run from the target
WebSphere Application Server release. The source machine will not have the new
version of the
WASPreUpgrade command. You must do one of the following actions:
- OPTION 1: Install the target product version on the source machine.
- OPTION 2: Create the remote migration JAR file. The JAR file has the
WASPreUpgrade command and files that are needed to support its running, including
Java, collected from the target installation.
After you have the remote migration JAR file, you can run it on the source machine.
Note:
OPTION 2 is easier as a full install is not needed. After the archive is created, it can be used
for many source machines. However, if the target and source machines are on different operating
system architectures, then OPTION 1 is required because the remote migration archive is operating
system architecture specific.
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, you can create the remote migration JAR and use it 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.
For transitioning users: WebSphere Virtual Enterprise and Intelligent Management previously required separate migration
tools but are now migrated as part of the standard migration procedures.
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 deployment manager profile configuration to a file.
-
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 node profile configuration to a file.
previous_version_app_server_root\v70node01\bin\backupConfig.bat
\mybackup_old_host\v70node01backupBeforeV90migration.zip
-username myuser -password mypass -nostop
previous_version_app_server_root/v70node01
/bin/backupConfig.sh /mybackup_old_host/v70node01rbackupBeforeV90migration.zip
-username myuser -password mypass -nostop
-
Install WebSphere Application Server Network Deployment
Version 9.0 onto each target host in a new directory.
For more information, see the installation documentation.
-
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 9.0 installed.
Avoid trouble:
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 runs only on this architecture.
If the operating system or architecture differs between the source and
target systems, you can create the remote migration JAR file without specifying the
-includeJava option. Set the JAVA_HOME environment variable to
a compatible Java™ version 7 or later installation on the
source system prior to running the WASPreUpgrade command. If you want to use the
-includeJava option, you must create the remote migration JAR file on the same
operating system and architecture as you installed the source.
-
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 9.0 on a system that matches the source profile before
creating the remote migration JAR. After you generate the remote migration JAR, it will work on any
system which matches the operating system and architecture.
-
Create the remote migration JAR file.
- At a command prompt, change to the migration bin
directory.
cd $WAS_HOME/bin/migration/bin
- To create the .jar file, run the createRemoteMigrJar
command.
createRemoteMigrJar.bat(sh) -targetDir <dir_for_the_remote_migration_jar>
This
creates the
WAS_V90_OS.arch_RemoteMigrSupport.jar
file. For example, WAS_V90_windows.amd64_RemoteMigrSupport.jar.
-
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.
- Change directories 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.
-
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 9.0 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 fails.
To create a deployment manager profile, run the
manageprofiles command with the appropriate parameters.
version_9_install_root\bin\manageprofiles.bat
-create -profileName v70toV90dmgr01
-templatePath app_server_root\profileTemplates\management
-serverType DEPLOYMENT_MANAGER -nodeName currentDmgrNodeName
-cellName currentCellName -hostName mydmgrhost.company.com
version_9_install_root/bin/manageprofiles.sh
-create -profileName v70toV90dmgr01
-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.
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.
If you are migrating from Version 8.0 to Version 9.0 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. If the output
has either message, then check the following log files for any warnings or errors:
- mybackup_old_host/v70toV90dmgr01/logs/WASPreMigrationSummary.log
- mybackup_old_host/v70toV90dmgr01/logs/WASPreUpgrade.timestamp.log
- mybackup_old_host/v70toV90dmgr01/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 9.0.
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 WebSphere Application Server migration.
-
Use an archive tool to create a compressed file of the backup directory.
cd /mybackup_old_host
/opt/WebSphereV70/java/bin/jar -cf v70toV90dmgr01.jar v70toV90dmgr01/
-
Move the archived file to the target machine.
-
Create a directory on the target machine and extract the archived file to the new
directory.
Replace mybackup_new_host with the directory to which you are migrating your
files.
mkdir /mybackup_new_host
cd /mybackup_new_host
/opt/WebSphereV90/java/bin/jar -xf v70toV90dmgr01.jar
-
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 9.0 deployment manager
profile.
-
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 following log files for any warnings or errors:
- mybackup_new_host/v70toV90dmgr01/logs/WASPostMigrationSummary.log
- mybackup_new_host/v70toV90dmgr01/logs/WASPostUpgrade.target
profile name.timestamp.log
- mybackup_new_host/v70toV90dmgr01/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 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.
If the command completed successfully, it is not necessary to check the logs for errors or
warnings.
Avoid trouble: 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.
-
Save the Version 9.0 migrated deployment manager
configuration to a file by running the backupConfig command on the Version 9.0 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 9.0 profile configuration to a file.
- Optional:
Stop and disable the deployment manager on the old host.
-
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 9.0 deployment manager on the new
host.
-
Change to the new Version 9.0
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 9.0 deployment manager is started.
-
Ensure that the Version 9.0 deployment manager starts
successfully.
- Optional:
Manually synchronize the old nodes to the new Version 9.0
deployment manager.
Ensure that the Version 9.0 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 the
com.ibm.ws.scripting.port
value to the new port.
-
Run the syncNode command from the bin directory.
node_agent_install_root\bin\syncNode.bat myV90DmgrHost.mycompany.com 8879 -username myuser -password mypass
node_agent_install_root/bin/syncNode.sh myV90DmgrHost.mycompany.com 8879 -username myuser -password mypass
-
Start the node agent if synchronization is successful.
-
Migrate application client installations.
If the source WebSphere application client is Version
7.0, you also must run the WASPreUpgrade and WASPostUpgrade
commands to migrate the existing security settings.
-
Identify all client hosts that you must migrate.
-
Install the WebSphere
Version 9.0 application client.
-
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_client/v70clientToV90 /opt/AppClientV70
-
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_client/v70clientToV90
-
Migrate nodes.
Important: 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 9.0 deployment manager is running. For each node that you
plan to migrate to
Version 9.0, perform the following
steps.
Avoid trouble: For the migration to be successful, you must use the
same source node name but a different temporary cell name for each node that you migrate to Version 9.0 or later.
-
Install WebSphere Application Server
Version 9.0 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.
version_9_install_root\bin\manageprofiles.bat
-create -profileName node1
-templatePath \opt\WebSphereV90\profileTemplates\managed
-nodeName currentNode1Name -cellName tempCellName
-hostName mynode1host.company.com
version_9_install_root/bin/manageprofiles.sh
-create -profileName node1
-templatePath /opt/WebSphereV90/profileTemplates/managed
-nodeName currentNode1Name -cellName tempCellName
-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
configuration to a migration backup directory. Choose a new directory for the backup files.
<path to remote migration jar>\migration\bin\WASPreUpgrade.bat
\mybackup_old_host\v70toV90node1
\opt\WebSphereV70 -oldProfile 70node1 -machineChange true
<path to remote migration jar>/migration/bin/WASPreUpgrade.sh
/mybackup_old_host/v70toV90node1
/opt/WebSphereV70 -oldProfile 70node1 -machineChange true
-
Check the WASPreUpgrade console output for error and warning messages.
You might find messages such as
Failed with errors or
Completed with
warnings. Also, look in the following log files for error or warning messages:
- myback_old_host/v70toV90node1/logs/WASPreMigrationSummary.log
- myback_old_host/v70toV90node1/logs/WASPreUpgrade.timestamp.log
- myback_old_host/v70toV90node1/logs/WASPreUpgrade.trace
If the WASPreUpgrade command is successful, you do not need to check the
log files for error or warning messages.
-
Use an archive tool to create a compressed file of the backup directory that was created by the
WASPreUpgrade command.
cd /mybackup_old_host
/opt/WebSphereV70/java/bin/jar -cf v70toV90node1.jar v70toV90node1/
-
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 the following example, replace mybackup_new_host with the directory from
which the profile configuration files are migrated.
mkdir /mybackup_new_host
cd /mybackup_new_host
/opt/WebSphereV90/java/bin/jar -xf v70toV90dmgr01.jar
- Run the WASPostUpgrade command to restore the saved node
configuration into the new Version 9.0 managed profile.
-
Check the WASPostUpgrade console output for messages.
You might find the
Failed with errors or
Completed with warnings
messages. Also, look in the following log files for errors or warning messages:
- mybackup_new_host/v70toV90node1/logs/WASPostMigrationSummary.log
- mybackup_new_host/v70toV90node1/logs/WASPostUpgrade.target_profile_name.timestamp.log
- mybackup_new_host/v70toV90node1/logs/WASPostUpgrade.target_profile_name.trace
Note: If the WASPostUpgrade command fails, you might need to restore the Version 9.0 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 has been migrated. The node cannot be
migrated again until the deployment manager has been 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.
-
Check the Version 9.0 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 9.0 node agent.
-
Check the Version 9.0 deployment manager and node
SystemOut.log for error or warning messages.
- Optional:
Synchronize the cell if the auto-synchronization process is not enabled.
-
Start the appropriate application servers on Version 9.0
migrated node.
-
Run the backupConfig command and save the Version 9.0 profile configuration to a file.
version_9_profile_root\v70toV90node1\bin\backupConfig.bat
\mybackup_new_host\v70toV90node1.zip -username myuser
-password mypass -nostop
version_9_profile_root/v70toV90node1/bin/backupConfig.sh
/mybackup_new_host/v70toV90node1.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 9.0 deployment manager host, change to the
deployment_manager_profile_root/bin directory. Run the
backupConfig command and save the Version 9.0 profile configuration to a file.
-
Repeat the previous steps for additional nodes.
-
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 9.0 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.
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 9.0.