Introduction

This guide is designed to help you get started migrating your Web applications and configuration from earlier versions of WebSphere® Application Server to Version 5. While there are excellent guides available that describe the entire process in detail, the tasks involved will be described here at a higher level to give you the big picture on some essentials, including preparation guidelines, important migration options, and a first look at the WebSphere Application Server administrative server, that will help you get your migration started quickly and with confidence.

Back to top

Preparing to migrate

As with all IT projects, a little advance planning can make all the difference. This section highlights some important issues you should consider before beginning your migration. These considerations apply whether you are migrating from either WebSphere Application Server V3.5.x or V4.0.x, unless otherwise noted.

• Apply all required fixes to your current version of WebSphere Application Server.This is important because the XMLConfig program, which is used during the migration process, was updated in WebSphere Application Server, Advanced Edition, Version 4.0. To determine prerequisite fixes for your environment, refer to the WebSphere Application Server InfoCenter for Version 5 (see Resources) and release notes that accompanied the product. Table 1 lists fixes that have been applied to XMLConfig which may be required for your environment. If you are migrating from Version 3.5.x, or if you would like detailed information about migration methodologies and tradeoffs, see the IBM Redbook, Migrating to WebSphere V5.0: An End-to-End Migration Guide.

• Apply all system prerequisites for WebSphere Application Server V5 before you start installing or migrating.
  If it's necessary to upgrade the database software used by your current version of WebSphere Application Server for the administrative repository, do this after the WASPreUpgrade tool has completed successfully. In some cases, an operating system upgrade may also be necessary prior to migrating. (Migrating from a non-prerequisite operating system is covered in an upcoming section.) Table 2 lists operating systems supported by Version 5, and indicates whether or not an operating system upgrade is required. More information is available at the WebSphere Application Server V5 system requirements Web site.

• Do not uninstall your current version of WebSphere Application Server.
  You can, but it's not necessary in order to verify whether the migration was successful. This may be comforting, since it means that your current WebSphere Application Server environment can remain intact and functional, and also that your migration can be implemented in phases, if necessary. This can also be helpful with troubleshooting, because you will still be able to, for example, view parameters and settings from the previous versions. By default, both versions of WebSphere Application Server are not allowed to run simultaneously. It is possible to set your Version 5 configuration so that both versions can run simultaneously, and to have Version 5 applications even coexist with applications running on the previous version of WebSphere Application Server (or with components such as EJBs running on the previous version). For information on configuring for coexistence or interoperability, refer to the WebSphere Application Server InfoCenter for Version 5 (see Resources).
  

• During the migration, run the admin server for the previous version of WebSphere Application Server until WASPreUpgrade has successfully completed.
  For all editions except WebSphere Application Server, Advanced Single Server Edition, Version 4.0.x, the WASPreUpgrade tool must extract all the configuration data from the administrative repository database. The easiest way to do this is to start up the administrative server of the previous version of WebSphere Application Server, bring up the administrative console, then monitor the WASPreUpgrade log. When the log indicates that the command has completed successfully, go to the admin console for the previous version and stop the node. This will close the console and stop the admin server.

Back to top

Installing WebSphere Application Server V5 with migration options

When it comes time to actually install Version 5 with the intention of migrating, you have three basic installation/migration options: Install Panel, Silent and Manual.

• Install Panel
  Migrating through the install panel is perhaps the easiest and most straightforward way to migrate a single system. Make sure that the previous version of WebSphere Application Server is running when you launch the install. The installation program will detect this version and ask you if you want to migrate your applications and/or have them coexist with Version 5. Simply answer the questions and the installation program will take care of the rest. Figure 1 shows a view of the migration panel from the installation wizard.
  Figure 1. Migration panel from the WebSphere Application Server V5 installation wizard
  
  
• Silent
  If you have many identical systems to upgrade then doing a silent install would probably be the preferred method, using a response file to automatically guide the migration. Create your response file based upon the sample response file located in the install directory included with the product. Once your response file is prepared simply launch the install using this command: install -options response_file.

• Manual
  If you have to perform an operating system upgrade, or just want more control over the migration, then a manual migration is the way to go. To run a manual migration, you would perform a standard WebSphere Application Server V5 installation, selecting not to take any of the migration options. After your installation is complete, you can then run the WASPreUpgrade and WASPostUpgrade tools to launch the migration at your own pace.

Back to top

Operating system upgrade as part of a migration

If WebSphere Application Server V5 does not support your current operating system, or if you want to migrate your WebSphere Application Server environment to a different operating system for another reason, you will want to incorporate the steps for upgrading or installing the operating system as part of the migration. To help you understand the sequence of events, here is a list of high level steps you will need to perform:

1. Take note of how the paths are currently defined for your WebSphere Application Server components (database drivers, log files etc). This is important because you will likely want to setup the new operating system with the same structure. If you change any of the file paths under the new operating system, you will need to apply these updates to WebSphere Application Server after you migrate so it can find these files again.
2. Run WASPreUpgrade, which is located in the migration/bin directory of the WebSphere Application Server V5 installation CD. This will create a websphere_backup directory that contains all of the configuration information that you will need later. The command to run WASPreUpgrade looks like this: WASPreUpgrade <backup directory> <current install path> <nodename> .
3. Tar or zip up the websphere_backup directory that WASPreUpgrade created, and use FTP to transfer that file to a temporary storage area on another system. For example: tar -cvf websphere_backup.tar websphere_backup.
4. Perform the operating system upgrade (or install the new operating system, if you're starting from scratch).
5. Install or setup any necessary database drivers. If at all possible, install database drivers into the same directory structure that existed in the previous operating system. If you place any files in a new or different location, be sure to note the new location so you can tell WebSphere Application Server V5 later (in Step 10).
6. Using FTP, transfer the backup directory you created in Step 3 to the new system and expand it. For example: tar -xvf websphere_backup.tar.
7. Install WebSphere Application Server V5. Do not select any migration or coexistence options, because you will be performing a manual migration afetr WebSphere Application Server V5 is installed.
8. Execute WASPostUpgrade pointing it to the websphere_backup directory you just expanded. For example: WASPostUpgrade <backup directory>.
9. Start the default application server, server1, and launch the administrative console.
10. Using the admin console, update any necessary file locations (from Step 5) under Resources.
11. Test all your Web applications to make sure they operate properly in the new environment.

Back to top

Client migration

To migrate your WebSphere Application Server client:

1. On your client machine, point to the directory that contains the image_client.<platform> file on the WebSphere Application Server V5 installation CD.
2. Use the install panels to install the Version 5 client. The client should indicate that an earlier version of the client is installed on your system. Continue the installation. Note that this will overwrite the previous client image.
3. Select either Custom install (to select only the features you need) or Typical (to install everything).
4. On the "HostName and Server Port" dialog, enter the long name and port number of the system that will be the server for this client. For example:
   Hostname: myserver.rchland.ibm.com
   Server Port Number: 900 (4.0.x server) or 2809 (5.0.x server)
   
5. When the installation completes, you will need to update client EAR files. Change to the appropriate directory, then run the appropriate clientUpgrade utility:
   Sun/HP/Linux: /opt/WebSphere/AppClient/bin/clientUpgrade.sh myearfile.ear
   AIX: /usr/WebSphere/AppClient/bin/clientUpgrade.sh myearfile.ear
   Windows: C:\Program Files\WebSphere\AppClient\bin\clientUpgrade.sh myearfile.ear
   
6. Check the clientupgrade.status file (in the EAR file directory) and theWASPostUpgrade.log file for errors. The clientupgrade.status file should not contain any error messages, and should indicate that the client migration was completed successfully. (Both files will contain a warning message MIGr0260W, but this warning can be ignored if the JDBC drivers for the Version 4.0 client EAR are the same as Version 5.)
7. Run the new client. For example:

   /opt/WebSphere/AppClient/bin/launchClient.sh myearfile.ear - CCBootstrapHost=myserver.rchland.ibm.com -CCBootstrapPort=900

   
   

The default bootstrap port is 900 (for Version 4) or 2809 (for Version 5). You may need to specify the correct value. If the application server is running secure, the client should be challenged for a user ID and password when logging in.

Back to top

WASPreUpgrade and WASPostUpgrade

Regardless of the installation/migration method you will be using, it's helpful to understand what the WASPreUpgrade and WASPostUpgrade tools do and how they work.

WASPreUpgrade

WASPreUpgrade creates a backup of your current WebSphere Application Server configuration by saving copies of all WebSphere directories and files needed to run the deployed applications and define the configuration. It then performs an XML export to extract configuration data from the repository database; this is why it is necessary for the administrative server to be running while executing the command. All these files are then saved into the <backup directory> specified by the user. The items that get backed up include:

• configuration directories
• application and properties files
• XML files needed for restoration into the WebSphere Application Server V5 environment.

The default syntax for the command to run WASPreUpgrade is:

WASPreUpgrade <backup directory> <current WebSphere version install path>
<nodename>

However, there are additional parameters available that can be useful. For example:

• -import: Use when migrating from WebSphere Application Server, Advanced Single Server Edition, Version 4.0.x, to specify an .xmi file other than the default server-cfg.xml configuration file.
• -nameServiceHost and -nameServicePort: Use when migrating a configuration that uses a non-default bootstrap port.
• -traceString and -traceFile: Use to obtain traces for troubleshooting errors.

You can also execute the command with no parameters. The options available will display, showing the proper syntax:

<backupDirectoryName>
<currentWebSphereDirectory>
<administrationNodeName>
[-import <xml data file>]
[-nameServiceHost <host name> [ -nameServicePort <port number> ]]
[-traceString <trace spec> [-traceFile <file name>]]

WASPreUpgrade will create a WASPreUpgrade.log.<day and date> file in the backup directory. Review this log file to make sure all the files and directories were successfully copied to the backup directory, and that the entire configuration data was successfully extracted from the repository. While you're in the backup directory, take a look at the websphere_backup.xml to ensure all your configuration data was successfully exported. It's a good idea to familiarize yourself with all the files and directories that are saved by WASPreUpgrade.

WASPostUpgrade

WASPostUpgrade uses the configuration backup created by WASPreUpgrade to recreate the configuration of the previous version of WebSphere Application Server in the Version 5 environment. If migrating from WebSphere Application Server V3.5.x, the configuration information is packaged into .jar, .war, and .ear files for deployment in the WebSphere Application Server V5 J2EE. The .xml file is then used to populate the Version 5 XML administrative repository.

WASPostUpgrade creates logs in the install_root/logs directory. Review these logs to verify that all of the items from the previous version of WebSphere Application Server, such as JDBC drivers, data sources, application servers and all other configuration objects, have been successfully installed in the Version 5 environment. When migrating from Version 3.5.x, you may see some warning messages concerning EJB specifications. EJBs will generally continue to function properly, although they may not meet the newer specifications. You should not see any error messages more severe than the following warnings:

[*Warning] /WSPVTBig3AE.jar(Method:
processClaim(apps.big3ejb.ProcessClaimParams), Class: 
apps.big3ejb.ProcessClaimBean): J2400W: Deprecated use of a 
java.rmi.RemoteException. (EJB 1.1: 6.10.4). 
             
[*Warning] /WSPVTBig3AE.jar(Field: theRootContext, Class: 
apps.big3ejb.ProcessClaimBean): CHKJ2200W: This static field should be final. (EJB 
1.1: 18.1.2)

One big difference you will notice in Version 5 is that repository data is no longer stored in a relational database. Instead, all configuration data is stored under the install_root/config directory in a library of XML files. Although the easiest way to view and manipulate the configuration data is through the Web-based administrative console, it's a good idea to become familiar with the structure of the XML repository. In essence, whenever you modify or create a new object using the admin console, the underlying XML file is modified to reflect that change.

Because WebSphere Application Server V5 no longer relies on a relational database to store configuration data, you may want to doublecheck that environment variables such as class and library paths are set for any databases that your applications need to access.

The default syntax for thecommand to run WASPostUpgrade is:

WASPostUpgrade <backup directory>

Below are optional parameters that can be added to the command:

• -import: Use when migrating from WebSphere Application Server, Advanced Single Server Edition, Version 4.x, using a non-default configuration file. This option can also be useful with Version 3.5.x and other Version 4.0.x editions when using a file other than the default XML file created during the WASPreUpgrade, in cases where, for example, you're migrating just a subset of the previous configuration.
• -cellName: Use to specify the cell name for the program to update. If not specified, the program inspects the configuration for cell names. When one is found, the program uses it, otherwise an error is returned.
• -nodeName: use to specify the node name for the program to update. If not specified, the program inspects the configuration for node names. When one is found, the program uses it, otherwise an error is returned.
• -webModuleAdditionalClasspath: Use when migrating from WebSphere Application Server V3.5.x to specify the path (or the path and file names) of specific directories or files that you do not want copied into the Web Archive (WAR) file. Instead, the program adds the paths and files to the Web Module extension (ibm-web-ext.xmi) additionalClassPath attribute.
• -documentRootLimit: Use when migrating from WebSphere Application Server V3.5.x to specify the number of resource files (such as HTML and JSP pages) to copy from the directory specified in the document-root field in the administrative console for the Web application. If not specified, the default is 300, which means that if there are more than 300 files, some will not be copied over to the new environment.
• -substitute: Use to specify optional arguments passed to the XMLConfig tool. You could use this to specify substitution values for security variables, for example: - substitute "NODE_NAME=admin_node;APP_SERVER=default_server".

You can also execute the command without any parameters, to view the available options, as follows:

<backupDirectoryName> 
[-import <xml data file>] 
[-cellName <cell name>] 
[-nodeName <node name>] 
[-webModuleAdditionalClasspath < classpath > ] 
[-documentRootLimit < number >] 
[-substitute <"key1=value1[;key2=value2;[...]]">] 
[-transportSeed < HTTP transport starting block >] 
[-traceString <trace spec> [-traceFile <file name>]]

Should it be necessary to migrate after federating a node to the Deployment Manager, which is not the typical migration path, you will need to run WASPostUpgrade manually on the Deployment Manager with the -nodeName parameter specifying the Deployment Manager node. Without using this parameter specified, you will get errors similar to the following:

MIGR0122E: Unable to read configuration file 
/opt/WebSphere/DeploymentManager/config/cells/ws-sunfish2Network/nodes/. 
            at 
com.ibm.websphere.migration.postupgrade.TransformBaseConfiguration.reso 
lveDirectory(TransformBaseConfiguration.java:690) 
            at 
com.ibm.websphere.migration.postupgrade.TransformBaseConfiguration.init 
ializeDataModel(TransformBaseConfiguration.java:587) 
            at 
com.ibm.websphere.migration.postupgrade.TransformBaseConfiguration.doIt 
(TransformBaseConfiguration.java:1145) 
            at 
com.ibm.websphere.migration.postupgrade.Restore.doIt(Restore.java:153) 
            at 
com.ibm.websphere.migration.postupgrade.Restore.<init>(Restore.java:93) 
            at 
com.ibm.websphere.migration.postupgrade.WASPostUpgrade.restore(WASPostUpgrade.java:196) 
            at 
com.ibm.websphere.migration.postupgrade.WASPostUpgrade.main(WASPostUpgrade.java:665) 
            at java.lang.reflect.Method.invoke(Native Method) 
            at com.ibm.ws.bootstrap.WSLauncher.main(WSLauncher.java:94) 
com.ibm.websphere.migration.exceptions.WASUpgradeInvalidConfigurationException: 
MIGR0122E: Unable to read configuration file 
/opt/WebSphere/DeploymentManager/config/cells/ws-sunfish2Network/nodes/

Any samples that were installed in the previous version of WebSphere Application Server will not be migrated to Version 5.

Back to top

Starting the WebSphere Application Server V5 environment

If the Default Server has been migrated to Version 5, its attributes will now be in server1. However, some attributes from the prior version, such as log file locations, will not be migrated. Instead, these will default to the Version 5 standard. For example, standard output and error file locations will default to: install_root/logs/ServerName/SystemOut.log and install_root/logs/ServerName/SystemErr.log.

To start the WebSphere Application Server Version 5 environment:

1. Issue the startServer command from the install_root/bin folder, specifying the application server that needs to be started:

   /opt/WebSphere/AppServer50/bin/startServer.sh server1

   
   
2. If your previous version of WebSphere Application Server used server groups or models/clones, you now need to install and migrate to WebSphere Application Server Network Deployment. Server groups and models/clones are now referred to as clusters and cluster members, respectively. Network Deployment can either be installed on the same system as the WebSphere Application Server base product, or it can be installed on its own system. Enterprise Applications that had been installed into the server groups or models will have to be reinstalled after the migration has completed. After installing Network Deployment, you can start the Deployment Manager by issuing the startManager command: /opt/WebSphere/DeploymentManager/bin/startManager.sh.
3. To federate a node to a Version 5 cell (i.e., add a node to the Deployment Manager configuration), issue the addNode command from the node that will be added. For example, if there are two systems, SystemA and SystemB, where SystemA is the Deployment Manager and SystemB is a node that needs to be federated to the Deployment Manger:
   1. Start the Deployment Manager on SystemA by running the startManager command from the install_root/bin directory.
   2. From SystemB, issue this command: install_root/bin/addNode.sh SystemA 8879 -includeApps.
4. It is important from a migration standpoint to specify the -includeApps option for the addNode command. This way, any applications that have been installed on that node will be migrated to the Deployment Manager. Once the nodes have been federated, they will be started. Later, when a node needs to be stopped, it can either be stopped from the Deployment Manager Console or from the command line, by issuing the stopNode command from the install_root/bin directory for that node. Likewise, to stop the Deployment Manager, from the command line run stopManager from the install_root/bin directory, where install_root is the directory where the Deployment Manager has been installed.
5. If you have WebSphere Application Server Enterprise Extensions installed, you will want to install WebSphere Application Server Enterprise Version 5.0. In an environment with WebSphere Application Server Network Deployment, Enterprise will need to be installed on each node as well as the Deployment Manager. If the Deployment Manager is installed on a system with a federated node, Enterprise will still need to be installed twice - once to the Base product and once to the Deployment Manager.

Back to top

Administering the WebSphere Application Server V5 environment

Once your installation is complete, take some time to walk through the administrative console:

1. After installation, the "WebSphere Application Server -- First Steps" window will display.
2. Select Verify Installation. This will verify that the installation process completed successfully, and will also start server1 (the default server in Version 5).
3. Open the adminstrative console using the Windows Start menu, or from a browser using http://localhost:9090/admin/. Before security is enabled, you can use the admin console by entering any user ID (this user ID will only be used to track changes).
4. The admin console will display the following:
   • Menu on left: the main menu, use to administer the environment
   • Menu on top: use to Save changes, modify console Preferences, Logout, get console Help.
   • Display area at bottom: Select Next or Previous to toggle between configuration problems or runtime messages.
5. Become familar with the admin console by viewing the following items:
   • From the main menu, expand Servers => Application Servers, then select the server1 link. Here, you can view and modify the application server properties.
   • From the main menu, expand Applications => Enterprise Applications. Here, you can install a new application, or modify the properties of one already installed.
   • From the main menu, expand Resources => JDBC Providers. Any migrated Data Sources will appear under Data Sources (Version 4).
   • To enable security, expand Security from the main menu. Make any configuration changes or modifications, then select Global Security => Enable Security => Java 2 Security (which will be auto-selected). If necessary, you can deselect Java 2 Security until any appropriate Java 2 Security adjustments have been made to your applications. Java 2 Security protects the local server environment (and other applications) from being corrupted by your application code. Therefore, if Java 2 Security is disabled, it should only be done temporarily.
   • From the main menu, expand Environment. Here, you can make changes to the Virtual Hosts, WebSphere variables, and update the Web server plug-in.
   • From the main menu, expand Troubleshooting to view and modify logs and traces.
   • When enabling security in a WebSphere Application Server Network Deployment environment, be sure to synchronize the nodes when saving the configuration change. Do this by checking Synchronize changes with nodes before selecting Save from the "Save to Master Configuration" dialog. This will force the nodes to pick up the changes at the same time as the manager. After enabling security, the node agents and manager will need to be restarted. When restarting the node agents and node manager, you may need to specify user ID and password, depending on your security configuration.

Back to top

Conclusion

You should now have a good understanding of what your migration options are, how to start the process, and what to expect at a high level. Migration is never much fun, but with careful planning, your transition to Version 5 can be a smooth one. Hopefully, this information will help you complete a successful migration, and avoid potential pitfalls, so you can begin to leverage the many improvements and enhanced functionality of WebSphere Application Server V5 in your Web applications.

Back to top

Acknowledgements

A special thanks to Dana Duffield and Thomas Alcott for reviewing this article.

Resources

• IBM WebSphere Application Server Information Center for Version 4.0.x
  
  
• IBM WebSphere Application Server Information Center for Version 5
  
  
• IBM Redbook: Migrating to WebSphere V5.0: An End-to-End Migration Guide
  
  
• WebSphere Application Server V5 system requirements
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Preparing to migrate
• Installing WebSphere Application Server V5 with migration options
• Operating system upgrade as part of a migration
• Client migration
• WASPreUpgrade and WASPostUpgrade
• Starting the WebSphere Application Server V5 environment
• Administering the WebSphere Application Server V5 environment
• Conclusion
• Acknowledgements
• 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