Introduction

This article is to help you get started migrating from IBM WebSphere Application Server Version 5.0.x, 5.1.x or 6.0.x to WebSphere Application Server Version 6.1. This article presents a high level overview of the WebSphere Application Server V6.1 migration tools and their usage, plus a summary of some special considerations that will apply when migrating from specific versions, for both single server and a managed cell. For detailed information on any of the steps in the migration process, refer to the WebSphere Application Server V6.1 Information Center.

Terminology used in this document

Before beginning, here are definitions for terms that are used in this document:

Back to top

Migration support across WebSphere Application Server

The basics of the migration support and tooling are the same across all the operating systems supported by WebSphere Application Server V6.1. The root of this tooling is described in Run the command line tools. However, there are differences in what interfaces are available for each operating system, as well as some characteristics that are unique to some operating systems. Following is a high level overview of this support:

z/OS

Migrating WebSphere Application Server for z/OS to V6.1 involves customizing a set of batch jobs and then running those jobs to migrate a node. Customization is accomplished using a set of ISPF dialogs. Each node in a cell will have its own customized jobs; a cell is migrated node by node, starting with the Deployment Manager node.

Using the ISPF dialogs is the only interface to the migration support on z/OS. The unique characteristics of the z/OS operating system, as well as the migration steps for z/OS, are covered in the white paper, Migrating to WebSphere Application Server for z/OS Version 6.1. This white paper, along with information in the WebSphere Application Server V6.1 Information Center, do an excellent job of describing the migration support for z/OS. We will not duplicate that information in this article.

i5/OS

Migrating WebSphere Application Server for i5/OS to V6.1 involves evoking the tools is described in the Run command line tools section. Using these command line tools is the only interface to the migration support on i5/OS. You can use this article to guide your i5/OS migration, but keep in mind that the support described in the Migration wizard section is not available for i5/OS.

Distributed platforms

Distributed platforms essentially includes all the operating systems that are supported by WebSphere Application Server, other than z/OS and i5/OS. See the List of supported software for WebSphere Application Server V6.1 for a complete list of these operating systems and their system requirements. These operating systems are supported by either using the command line tools or the Migration wizard.

Back to top

1. Prepare to migrate

This section covers important issues yo uneed to review prior to attempting a migration from a previous version of WebSphere Application Server to V6.1. Unless otherwise specified, all points discussed here apply when migrating from either V5 or V6.

1. Confirm prerequisite software levels. Review the List of supported software for WebSphere Application Server V6.1 for minimum version and fix level requirements for your operating system and associated software. If your existing WebSphere Application Server V5 or V6 installation is on an operating system version that does not meet V6.1 prerequisites (such as AIX® 5.1 or Sun™ Solaris™ 8), then an operating system upgrade will be required before you can install WebSphere Application Server V6.1 on that system.

2. Gather information. Before starting the migration procedure using the command line tools, it is important to track down the names of all nodes in the V5 or V6 cell, in addition to the cell name. These values are used when creating V6.1 profiles for each node in the cell. Profiles will be discussed more in the next section.

3. Backup your environment. Backup your WebSphere Application Server environments before attempting any migration. This is especially critical if you will be performing an incremental cell upgrade. You can use the backup tool to save the current environment; to learn more about this, review articles related to the backupConfig utility in either V5 or v6 Information Center (see Resources.

4. Leave your previous version of WebSphere Application Server intact. This point cannot be stressed enough: Do not uninstall your existing WebSphere Application Server V5 or V6 configuration, leave it as is. WebSphere Application Server V6.1 will co-exist safely with these previous versions -- assuming that only one version of WebSphere Application Server is running at any given moment. Besides being required for the first step of migration, having the previous version of WebSphere Application Server intact also enables you to rollback your environment to the previous version, if desired or necessary.

Back to top

2. Install WebSphere Application Server V6.1

The installation process for V6.1 has changed from the process used in V5. One important change is that migration has been decoupled from the installer. As mentioned earlier, a Migration wizard (for distributed operating systems only) will guide you through the migration after you have installed V6.1. If you previously used the Silent option to install and migrate to a previous version, you can still install silently, after which you will need to use the migration command line tools manually.

New in V6 and V6.1 is the concept of profiles, which are independent instances of the WebSphere Application Server configuration and application file sets. In essence, profiles enable multiple configurations of V6.1 with only one copy of the WebSphere Application Server core binary files. Profiles offer an improvement over V5 instances, and V6.1 has new tooling that can be used to create and manage these profiles.

You will use the FirstSteps tool to access the Profile Management tool, shown in Figure 1.

In WebSphere Application Server Network Deployment V6.1 (hereafter referred to as Network Deployment), there are three types of profiles available:

• Deployment manager
• Custom
• Application server.

Only the application server profile is available in the other editions of WebSphere Application Server V6.1. Figure 1 shows the Network Deployment Profile Management tool, from which you can select from four predefined profile layouts, called environments.

A profile does not need to exist prior to running the Migration wizard. However, if you plan to use the migration command line tools, then you will need to create profiles for your environment.

When creating a profile for migrating from a previous release, certain values must match between the previous version and the new version. Specifically, when migrating a deployment manager to V6.1, the cell name value of the V6.1 profile must match the cell name from V5 or V6; when migrating to a V6.1 federated node, the node name of the V6.1 profile must match the node name from the previous version’s federated node, and so on. For nodes that are not part of a cell, such as a standalone system, there are no such naming requirements for the V6.1 profile. If you use the Migration wizard or the z/OS customization jobs to create your profile and to migrate, then these values are filled in for you.

For a Network Deployment migration, profiles must be migrated in this specific sequence:

1. Deployment Manager profile. This profile must be migrated first whenever a cell is being migrated. The V6.1 migrated Deployment Manager profile can manage all V5 and V6.0.2.x nodes in the cell. WebSphere Application Server V6.1 restricts the migrated deployment manager by only letting it manage V5 nodes that were in the cell prior to migration. Specifically, V5 nodes cannot be federated into a V6.1 deployment manager -- but V6.0.2.x nodes can be added to a V6.1 deployment manager. For V5 users, the Deployment Manager profile is analogous to the WebSphere Application Server Network Deployment V5 and deployment manager installations. Each cell must have exactly one deployment manager.

2. Custom profile. This profile is ideal for a federated node migration. There are no default applications or application servers created for this profile. Each node of the previous release can be migrated to exactly one Custom profile. If you have large V5 or V6 cells, the nodes can be migrated one at a time. The nodes will be members of the V6.1 cell and can, at any time, be migrated to V6.1 nodes.

3. Application server profile. This profile is analogous to a single node installation in V5. The profile is created with an application server called server1, plus several default applications.

Back to top

3. Perform the migration

The next steps you will perform will depend on the migration method you have chosen. You will either:

1. Run the Migration wizard, or
2. Run the command line tools.

3a. Run the Migration wizard

The Migration wizard is new and improved for V6.1 and replaces the migration panels that were a part of the Application Server Installer for V5. The Migration wizard is not available for i5/OS or z/OS platforms. The Migration wizard is found on the FirstSteps panel. To run the Migration wizard:

1. Launch FirstSteps from the profile directory, if one exists; for example: C:\WebSphere\AppServer\profiles\default\. On Windows®, you can launch FirstSteps from either the profile directory’s firststeps folder or from the Start Menu.

2. After FirstSteps is launched, select Migration wizard to begin the migration provcess (Figure 2).

   
   
   Figure 2. First steps panel
   
   
   

3. After the Welcome panel displays, select the prior version of WebSphere Application Server you want to migrate from a list of detected versions (Figure 3). It is important that you make sure the location of the previous version is correct by verifying the location displayed in the Installation root directory of the previous version field. If the previous version you want to migrate is not detected by the wizard, use this field to specify its location after first checking Specify the installation location if your existing product is not listed.

   
   
   Figure 3. Detected versions of WebSphere Application Server
   
   
   

4. Select which profile in the previous version you want to migrate (Figure 4). For V5, you will typically migrate the defaultinstance; however, if you created more than one instance, you can select any one of your other V5 instances. For V6, you can select which profile you want to migrate, but remember that the deployment manager must always be migrated before the federated nodes.

   
   
   Figure 4. Source profile selection panel
   
   
   

5. If you have defined one or more profile, such as a V6.1 deployment manager and a V6.1 node profile on the same system, you must select the profile to be used as your target profile (Figure 5). If you have not already created a V6.1 profile, the Migration wizard can create one for you if you select <Create new profile>.

   
   
   Figure 5. Target profile selection panel
   
   
   

6. If you have the Migration wizard create a profile, the panel shown in Figure 6 will display. The Migration wizard will populate the required fields with appropriate values; for example, if you are migrating a deployment manager, then the wizard will determine the cell name from your source WebSphere Application Server, and so on.

   
   
   Figure 6. Profile creation panel
   
   
   

7. The migration tools use a backup directory to migrate your previous version of WebSphere Application Server to V6.1. Specify where the backup directory is located, or, if it does not already exist, where it should be created (Figure 7).

   
   
   Figure 7. Migration backup directory panel
   
   
   

8. Figures 8 and 9 show the panels for application migration settings. These panels are new in the V6.1 Migration wizard and enable it to use new parameters in the WASPostUpgrade command. On these panels, you can select whether you want to migrate and install the applications, or if you want to have scripts created so you can migrate the applications at a later time. You can also select the location where you want to have the applications installed.

   
   
   Figure 8. Application install migration settings panel
   
   
   

9. On the next panel (Figure 9), you can change the location where applications will be installed. By default, migrating will install applications into the config directory of WebSphere Application Server V6.1. If you have your applications installed outside of the WebSphere directory tree structure, you can select the option to Keep the same application directories as the previous version. Alternatively, you can also enter a new or different directory in which to install your applications. If the application installation directory location is not important to you, then accept the default.

   
   
   Figure 9. Application directory migration settings panel
   
   
   

10. By default, the V5 or V6 deployment manager is disabled during the migration process, but if you have a critical need, you can opt to Do not disable the deployment manager of the previous version (Figure 10). This lets you use the deployment manager for your previous version while the migration is in progress. However, this is an unsupported configuration and so this option must be used with extreme caution. The previous deployment manager is stopped and disabled to prevent multiple deployment managers from working on the same managed nodes. Should you not disable the previous deployment manager, you are responsible for later disabling -- and not using -- the previous deployment manager before the new deployment manager is started.

    
    
    Figure 10. Deployment manager disablement panel
    
    
    

11. Specify the port values you wish to use on the Port value assignment panel (Figure 11). You can select to use the port values from the source installation (default), in which case the V6.1 WebContainer ports will be removed prior to migration, thus avoiding any conflicts with the WebContainer port being migrated forward. You can also select a block of ports to be used for all ports created during the migration process.

    
    
    Figure 11. Port value assignment panel
    
    
    

12. Indicate whether you want migration to support script compatibility on the panel shown in Figure 12. Check Migrate to support script compatibility if, for example, you have scripts or programs that are used to create or modify your configuration definitions. If you leave this option unchecked, the migration tooling will, for example, create V6.1 channels rather than transports. More information on the convertScriptCompatibility command is provided in the next section.

    
    
    Figure 12. Script compatibility panel
    
    
    

13. The Migration summary panel (Figure 13) is the last panel that displays before we execute any commands. Confirm your selections here or go back and make any necessary changes.

    
    
    Figure 13. Migration summary panel
    
    
    

14. If you had selected to <Create new profile>, then you will see a panel similar to the one in Figure 14. As long as profile creation completes successfully, then the migration will continue. If there is a problem while creating a profile, then the wizard will end.

    
    
    Figure 14. Profile creation output panel
    
    
    

15. Select Next on the Migration summary panel (or on the Profile creation output panel) to execute the migration. The WASPreUpgrade command will be executed, followed by the WASPostUpgrade command. These commands essentially perform the migration, and will be discussed in the next section.

16. After WASPreUpgrade and WASPostUpgrade have executed, the Migration status panel (Figure 15) displays, providing a summary status of the output from the migration commands.

    
    
    Figure 15. Migration status panel
    
    
    

3b. Run the command line tools

The WASPreUpgrade and WASPostUpgrade commands can be used to manually migrate your previous version of WebSphere Application Server to V6.1. The Migration wizard calls these tools as part of the automated migration process. These commands should always be called from the V6.1 profile directory, not the V5 or V6 directory, since the commands have changed with each release. The commands can also be found in the bin folder of the V6.1 profile, but if you choose to use these commands, you will need to specify which V6.1 profile the command should run against.

1. WASPreUpgrade

   The WASPreUpgrade command creates a backup of all pertinent V5 and V6 WebSphere Application Server configuration information. The contents of the backup are specific to the version and configuration setup.

   The syntax of WASPreUpgrade command is:

   WASPreUpgrade backupDirectory currentWebSphereDirectory [-traceString trace_spec [-traceFile file_name]]

   
   

   Only the first two parameters are required. An example of what you could run for V5 could be:

   C:\IBM\WebSphere\AppServer61\profiles\default\bin\WASPreUpgrade.bat C:\IBM\WebSphere\Backupv5Config C:\IBM\WebSphere\AppServer5

   
   

   The final two lines of the WASPreUpgrade output, if successful, will be:

   MIGR0303I: The existing WebSphere Application Server environment is saved. MIGR0420I: The first step of migration completed successfully.

   
   

   Refer to the WebSphere Application Server V6 Information Center for details on using the WASPreUpgrade command, or run the WASPreUpgrade command without any parameters to display the command’s syntax. To diagnose a migration problem, see WASPreUpgrade logs.

2. WASPostUpgrade

   The WASPostUpgrade command takes the backup created by WASPreUpgrade and uses it to move the previous configuration up to V6.

   The syntax for WASPostUpgrade is:

   WASPostUpgrade backupDirectory [-oldProfile profile_name] [-profileName profile_name] [-scriptCompatibility true | false] [-portBlock port_starting_number] [-backupConfig true | false] [-replacePorts true | false] [-includeApps true | false | script] [-keepAppDirectory true | false] [-appInstallDirectory user_specified_directory] [-traceString trace_spec [-traceFile file_name]]

   
   

   Only the first parameter is required. An example of what you could run could be:

   C:\IBM\WebSphere\AppServer61\profiles\default\bin\WASPostUpgrade.bat C:\IBM\WebSphere\Backupv5Config

   
   

   When there is more than one V6.1 profile, use the –profileName parameter to specify which profile should be updated. This is especially important when you run this command from the main WebSphere Application Server directory, as opposed to the profile directory. (That is, for example, from C:\IBM\WebSphere\AppServer61\bin verses C:\IBM\WebSphere\AppServer61\profiles\default\bin.) If the command is run from the main WebSphere Application Server directory and the –profileName parameter is not used, the command will use the default profile, which is not necessarily the profile whose name is “default”.

   The WASPostUpgrade command can end with warnings and still be successful, so review the log files to see why there was a warning, and if any additional action is necessary. The final output from the WASPostUpgrade command should be either:

   MIGR0259I: The migration has successfully completed.

   
   

   or

   MIGR0271W: Migration completed successfully, with one or more warnings.

   
   

   The WASPostUpgrade tool creates a backup of the V6.1 environment prior to making any changes, and will attempt to rollback any changes if an error such as the following occurs:

   MIGR0272E: The migration function cannot complete the command.

   
   

   Refer to the WebSphere Application Server V6.1 Information Center for details on using the WASPostUpgrade command, or run the WASPostUpgrade command without any parameters to display the command’s syntax. To diagnose a migration problem, see WASPostUpgrade logs.

3. convertScriptCompatibility

   The convertScriptCompatibility command converts the V6.1 configuration from a mode in which script compatibility is supported to a mode in which script compatibility is not to be supported. Script compatibility mode occurs by either running WASPostUpgrade with -scriptCompatibility true, or by taking the default value.

   The syntax for convertScriptCompatibility is:

   convertScriptCompatibility [-help] [-backupConfig true | false] [-profileName profile_name] [-nodeName node_name [-serverName server_name]] [-traceString trace_spec [-traceFile file_name]]

   
   

   There are no required parameters. An example of what you could run:

   C:\IBM\WebSphere\AppServer61\profiles\default\bin\convertScriptCompatibility.bat

   
   

   When there is more than one V6.1 profile, use the –profileName parameter to specify which profile should be updated. This is especially important when you run this command from the main WebSphere Application Server directory, as opposed to the profile directory. (That is, for example, from C:\IBM\WebSphere\AppServer61\bin verses C:\IBM\WebSphere\AppServer61\profiles\default\bin.) If the command is run from the main WebSphere Application Server directory and the –profileName parameter is not used, the command will use the default profile, which is not necessarily the profile whose name is “default”.

   Special consideration should be noted when attempting to run this conversion against a federated node. The command should be run against the dmgr profile specifying the federated node you want to convert using the -nodeName parameter. After you have run convertScriptCompatibility, you will be required to manually sync with the federated node you just converted in order to download those changes to the node.

   If successful, convertScriptCompatibility will end with the following message:

   MIGR0259I: The migration has successfully completed.

   
   

   The convertScriptCompatibility tool creates a backup of the V6.1 environment prior to making any changes, and will attempt to rollback any changes if an error such as the following occurs:

   MIGR0272E: The migration function cannot complete the command.

   
   

   Refer to the WebSphere Application Server V6.1 Information Center for details on using convertScriptCompatibility, or run the convertScriptCompatibility command specifying -help to display the command’s syntax. To diagnose a migration problem, see convertScriptCompatibility logs.

Back to top

4. Review the log files

Whether you are performing a manual migration or migrating through the wizard, it’s always a good idea to review the log files for any errors or warnings that might require some kind of action. Trace files will be generated by default on all platforms except z/OS; however, these files are solely for use by IBM Support personnel, if required.

WASPreUpgrade logs

The following log files are created when the WASPreUpgrade command is run manually:

<backupDirectory>/WASPreUpgrade.<Date-Time>.log

When migrating through the Migration wizard, these log and trace files are created:

<backupDirectory>/WASPreUpgrade.<Date-Time>.log
<backupDirectory>/logs/preMigrationOutput.log
<backupDirectory>/logs/WASPreMigrationLog.log

WASPostUpgrade logs

The following log files are created when the WASPostUpgrade command is run manually:

<profileDirectory>/logs/WASPostUpgrade.<Date-Time>.log
<profileDirectory>/logs/<cloudscapeDBName><Log|Debug><Date-Time>.log

When migrating through the Migration wizard, these log and trace files are created:

<profileDirectory>/logs/WASPostUpgrade.<Date-Time>.log
<backupDirectory>/logs/postMigrationOutput.log
<backupDirectory>/logs/WASPostMigration.log
<backupDirectory>/logs/<cloudscapeDBName><Log|Debug><Date-Time>.log

convertScriptCompatibility logs

The following log file is created when the convertScriptCompatibility command is run manually:

<profileDirectory>/logs/convertScriptCompatibility.<Date-Time>.log

Back to top

Conclusion

This overview should give you enough familiarity with the migration tools in WebSphere Application Server Version V6.1, and their usage and options, to give you an idea of how to begin the migration process. Although the process is largely automated and relatively straightforward, this article also included some special considerations when migrating from a single server or from a managed cell. We hope you find this information useful, wish you well with your migration, and hope you enjoy using the new and improved WebSphere Application Server V6.1.

Resources

• WebSphere Application Server system requirements
  
  
• List of supported software for WebSphere Application Server V6.1
  
  
• WebSphere Application Server Information Centers (all versions)
  
  
• Migrating to WebSphere Application Server for z/OS Version 6.1
  
  
• WebSphere Application Server V6 Migration Guide
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Migration support across WebSphere Application Server
• 1. Prepare to migrate
• 2. Install WebSphere Application Server V6.1
• 3. Perform the migration
• 4. Review the log files
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers