Migrating and coexisting

 

Determine whether you have an existing version of WAS installed on the machine where you plan to install your Version 5 product.

If you have a previous version, plan whether to copy the configuration and applications of the previous version to the new version, which is migration. Migration does not uninstall the previous version. The earlier release is still functional. If you run it at the same time as the Version 5 installation, the two versions are coexisting. One can choose to provide non-default port assignments for Version 5 to support coexistence, by selecting the coexistence option during installation.

WAS contains migration tools that provide all migration functionality. The installation wizard can call the migration tools, or you can call them manually at a later time. The migration tools migrate applications and configuration information to the new version, as described in detail in the Migrating and the Configuration mapping during migration topics.

One can also find information about migrating the configuration and applications from a previous version of WAS to Version 5 in the IBM Redbook, Migrating to WebSphere V5.0: An End-to-End Migration Guide, SG24-6910-00. There is a link to the book in the Resources for Learning topic.

In overview, the migration tools perform a fairly routine migration from V4 to V5. For example, J2EE 1.2 enterprise archive files in V4 work in V5 of WAS, which also supports the J2EE 1.3 specification. Similarly, it is not necessary to redeploy enterprise Java bean 1.1 Java archive (JAR) files when moving them from V4 to V5, which also supports EJB 2.0 JAR files.

In overview, the migration from V3.5 to V5 involves significant changes in application structures, development, and deployment. The migration tools assist in this transition by migrating system configurations and creating J2EE artifacts, including mapping previous security settings to J2EE security roles. These security mappings let you access migrated assets during the transition. The migration tools create initial J2EE enterprise applications based on V3.5.x configurations. However, because of the significant changes in the application structures, carefully test and fine tune migrated applications using development and deployment tools.

There are four combinations of migration and coexistence that you can select from the installation wizard or during silent installation:

  • Migrate only
  • Coexist only
  • Migrate and coexist
  • Neither migrate nor coexist

If you neither migrate nor coexist with an earlier version of WAS, you are choosing to ignore the previous installation. One can run only one version at a time because of conflicting default port assignments, although it is possible that both versions might run at the same time without conflict if you use non-default ports in the earlier version. To resolve conflicting port assignments, the coexistence panel lets you manually assign ports for Version 5 to ensure that it can run with an earlier version.

One can specify port assignments for coexistence on the installation wizard coexistence panel, by editing configuration files manually, by wsadmin scripting, or by using the Servers > Application Servers > servername > End Points administrative console page.

WAS products use a different set of default port numbers for coexistence than for the initial installation.

 

Coexistence port definitions

Installation wizard name HTTP Transport Port
Name in base WAS server.xml configuration file HTTPTransport_1 EndPoint_1
Name in Network Deployment server.xml configuration file Not applicable
virtualhosts.xml HostAlias_1
Silent installation response file option name coexistencePanelBean.httpTransportPort
Base WAS, default value 9080
Network Deployment, default value Not applicable
InfoCenter description Port used for request queues between a WAS plug-in for Web servers and a Web container in which the Web modules of an application reside
Port 9085


 

Installation wizard name HTTPS Transport Port
Name in base WAS server.xml configuration file HTTPTransport_2 EndPoint_2
Name in Network Deployment server.xml Not applicable
virtualhosts.xml HostAlias_3
Silent installation response file option name coexistencePanelBean.httpsTransportPort Base WAS, default value 9443
Network Deployment, default value Not applicable
InfoCenter description Port used for request queues between a WAS plug-in for Web servers and a Web container in which the Web modules of an application reside
Port 9444


 

Installation wizard name HTTP Admin Console Port
Name in base WAS server.xml configuration file HTTPTransport_3 EndPoint_3
Name in Network Deployment server.xml HTTPTransport_1 EndPoint_1
virtualhosts.xml HostAlias_4
Silent installation response file option name coexistencePanelBean.adminConsolePort
Silent installation response file option name PME_CoexistenceInformationPanel.adminConsolePort
Default value 9090
InfoCenter description Port used for request queues between a WAS plug-in for Web servers and a Web container in which the Web modules of an application (including the administration console application) reside
Port 9091


 

Installation wizard name HTTPS Admin Console Secure Port
Name in base WAS server.xml configuration file HTTPTransport_4 EndPoint_4
Name in Network Deployment server.xml HTTPTransport_1 EndPoint_2
virtualhosts.xml HostAlias_5
Silent installation response file option name coexistencePanelBean.secureAdminConsolePort
Default value 9043
InfoCenter description Port used for request queues between a WAS plug-in for Web servers and a Web container in which the Web modules of an application (including the administration console application) reside
Port 9044


 

Installation wizard name Bootstrap port
Name in base WAS serverindex.xml configuration file BOOTSTRAP_ADDRESS EndPoint_1
Name in Network Deployment serverindex.xml BOOTSTRAP_ADDRESS EndPoint_2
Silent installation response file option name coexistencePanelBean.bootstrapPort
Base WAS, default value 2809
Network Deployment, default value 9809
InfoCenter description The bootstrap port setting together with the host name forms the initial context for JNDI references.
Port 2810
General Description One can use the connector type and port number parameters of certain commands to identify the bootstrap port number you specify for the RMI connector address in a coexistence scenario. For example, to use the wsadmin command in a coexistence environment, you can specify either of the following commands:

wsadmin.sh -conntype RMI -port portNumber 

wsadmin.sh -conntype SOAP -port portNumber

  1. The default port assignment for the Network Deployment product is 9809. The default port assignment for the base WAS product is 2809. You might want to use a coexistence value for a coexisting Network Deployment product that is more in line with the default value. For example, you might prefer to use a value of 9810.

Alternatively, you can update the wsadmin.properties file located in the $WAS_HOME/properties directory to contain the new port values. If you do this, you need not specify the port parameter when using the wsadmin tool.

The SOAP connection type uses the SOAP connector address port number described next.


 

Installation wizard name SOAP Connector Address
Name in base WAS serverindex.xml configuration file SOAP_CONNECTOR-ADDRESS EndPoint_2
Name in Network Deployment serverindex.xml SOAP_CONNECTOR-ADDRESS EndPoint_4
Silent installation response file option name coexistencePanelBean.soapConnectorAddress Default value 8880
InfoCenter description Port used for the Simple Object Access Protocol (SOAP) connector Port 8881
General Description

One can use the connector type and port number parameters of certain commands to identify the port number you specify for the SOAP connector address in a coexistence scenario. For example, to use the wsadmin command in a coexistence environment, you can specify either of the following commands:

wsadmin.sh -conntype RMI -port portNumber 

wsadmin.sh -conntype SOAP -port portNumber

Alternatively, you can update the wsadmin.properties file located in the $WAS_HOME/properties directory to contain the new port values. If you do this, you need not specify the port parameter when using the wsadmin tool.

The remote method invocation (RMI) connection type uses the bootstrap port number described previously.


 

Installation wizard name DRS client address
Name in serverindex.xml DRS_CLIENT_ADDRESS EndPoint_3
Silent installation response file option name coexistencePanelBean.drsClientAddress
Default value 7873
InfoCenter description Port used to configure the Data Replication Service (DRS), which is a JMS-based message broker system for dynamic caching
Port 7874


 

Installation wizard name JMS server queued address Name in base WAS serverindex.xml configuration file JMSSERVER_QUEUED_ADDRESS EndPoint_4
Name in Network Deployment serverindex.xml Not applicable
Silent installation response file option name coexistencePanelBean.jmsServerQueuedAddress
Default value 5558
InfoCenter description Port used to configure the WebSphere JMS provider topic connection factory settings
Port 5568


 

Installation wizard name JMS server security port
Name in base WAS server.xml configuration file JMSServer_1 Address_3
Name in Network Deployment server.xml Not applicable
Silent installation response file option name coexistencePanelBean.jmsServerSecurityPort
Default value 5557
InfoCenter description Port used in JMS security processing Port 5567


 

Installation wizard name JMS Server Direct Address
Name in base WAS serverindex.xml configuration file JMSSERVER_DIRECT_ADDRESS EndPoint_5
Name in Network Deployment serverindex.xml Not applicable
Silent installation response file option name coexistencePanelBean.jmsServerDirectAddress
Default value 5559 InfoCenter description Port used to configure the WebSphere JMS provider topic connection factory settings
Port 5569


 

Installation wizard name SAS SSL ServerAuth Address
Name in serverindex.xml SAS_SSL_SERVERAUTH_LISTENER_ADDRESS EndPoint_6
Silent installation response file option name coexistencePanelBean.sasSSLServerAuthAddr
Base WAS, default value 0; With security, assign your own non-conflicting value: nnnn
Network Deployment default value 9401 but is not enabled until you enable security
InfoCenter description Port used to listen for requests to use the server
General Description

Note: Assign a coexistence port other than 0, which dynamically takes a free port. You must have a fixed port that clients can use to find the SAS SSL ServerAuth Address. There is no mechanism for clients to use to find a dynamically assigned port.


 

Installation wizard name CSIV2 ServerAuth Listener Address
Name in base WAS serverindex.xml configuration file CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS EndPoint_7
Name in Network Deployment serverindex.xml CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS EndPoint_8
Silent installation response file option name coexistencePanelBean.csivServerAuthListenerAddr
Base WAS, default value 0; With security, assign your own non-conflicting value: nnnn
Network Deployment, default value 9403 but is not enabled until you enable security
InfoCenter description Port used to listen for requests to use the server
General Description

Note: Assign a coexistence port other than 0, which dynamically takes a free port. You must have a fixed port that clients can use to find the CSIV2 ServerAuth Listener Address. There is no mechanism for clients to use to find a dynamically assigned port.


 

Installation wizard name CSIV2 MultiAuth Listener Address
Name in base WAS serverindex.xml configuration file CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS EndPoint_8
Name in Network Deployment serverindex.xml CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS EndPoint_7
Silent installation response file option name coexistencePanelBean.csivMultiAuthListenerAddr
Base WAS, default value 0; With security, assign your own non-conflicting value: nnnn
Network Deployment, default value 9402 but is not enabled until you enable security
InfoCenter description Port used to listen for requests to use the server
Port 0
General Description

Note: Assign a coexistence port other than 0, which dynamically takes a free port. You must have a fixed port that clients can use to find the CSIV2 MultiAuth Listener Address. There is no mechanism for clients to use to find a dynamically assigned port.


 

Installation wizard name ORB Listener Port
Name in base WAS serverindex.xml configuration file Not applicable
Name in Network Deployment serverindex.xml ORB_LISTENER_ADDRESS EndPoint_5
Silent installation response file option name Not applicable - See note.
Base WAS default value Not applicable
Network Deployment default value 9100
InfoCenter description Port used to listen for requests to use the server
Port 9101


 

Network Deployment installation wizard name Cell Discovery Address Base WAS installation wizard name Not applicable
httpd.conf configuration file name IBM HTTP Server Admin Port
Silent installation response file option name coexistencePanelBean.ihsAdminPort
Default value 7277
Description Port used in cell discovery
Port 9989
General Description

Note: Set the Cell discovery address after a silent installation of the Network Deployment product as described in the Configure cells topic.

If you choose to both migrate and coexist, you are selecting two tasks with roughly opposite ends. The goal of migration is to reconstruct your earlier version in a nearly identical V5 environment, including applications, configuration settings, URI descriptors, and Web server context roots. The goal of coexistence is to create an environment that is not in conflict with an earlier version, so far as port settings are concerned. If you select both migration and coexistence, the installation wizard migrates the earlier version configuration and applications. Then the wizard changes port settings to support coexistence with the earlier version, which means that both nodes can start and run at the same time. Migration occurs first. Coexistence processing occurs next and alters the following configuration files to the default settings shown previously:

You must then start servername and use it to change any ports that are in conflict, so that there is no conflict with the earlier version. Then you can run both versions at the same time.

There are two other problems that might occur when you choose both migration and coexistence:

  • One problem is conflicting context roots when attempting to share the same Web server.

    A procedure for configuring a Web server for sharing between WAS versions is described in the InfoCenter for the base WAS product.

  • The other problem occurs if you install WAS Version 5 multiple times on the same z/OS image or sysplex.

Coexistence is described as an optional step below. Migration is also optional. To migrate applications and configurations to V5, follow this procedure:

 

  1. Prepare to migrate or update product prerequisites and corequisites to supported versions.

    IBM WAS supported hardware, software, and APIs

  2. Prepare to use the migration function of the installation wizard, to migrate silently, or to migrate manually.

    • You have the option of letting the installation wizard use the migration tools to migrate an existing WAS earlier version to Version 5 automatically.

      The installation wizard detects a previously installed version, and displays a migration and coexistence panel. One can select either option, both options, or no option.

      1. Start the administrative server of WAS Standard Edition (V3.5.x) or WAS Advanced Edition (V3.5.x or V4.0.x).

        Start the administrative server allows the migration tools to use XMLConfig to export the configuration data repository. It is not necessary that you start the administrative server for WAS Advanced Single Server Edition, V4. The migration tools use the XMI configuration files directly.

      2. Select the migration option and click Next when using the installation wizard. When using the silent installation method, select the appropriate option.

        Enter a fully qualified path for the backup directory, where the migration tools store and read the saved configuration and other files. During migration, the wizard backs up the old version administrative configuration and user data files, but does not uninstall the old version. The wizard automatically configures the new installation with the previous configuration data. It also copies some application data to the newer version.

        The installation wizard uses the WASPreUpgrade migration tool to export the current administrative configuration. After this phase completes, the wizard runs the second phase, which uses the WASPostUpgrade migration tool to convert the backed-up administrative configuration into the new Version 5 configuration. One can stop the administrative server of the earlier version after the migration is complete. You must stop the earlier version server before starting the Version 5 server.

        The installation program prompts you for the following information during migration:

        • Backup directory.

        • Currently installed WAS directory. This directory must differ than the one where you install Version 5.

        • Name of the administrative node of the previous version. The default is the computer name, but both the previous node name and the Version 5 node name must be the same.

          To determine the administrative node name of the previous version, you can do either of these actions:

      3. Plan to complete the migration after the installation and migration are complete.

        Follow these steps to complete the migration:

        1. Stop the administrative server from the earlier version.

        2. Load existing applications into your development environment and fix any known problems.

        3. Start the servers in the new installation.

        4. Deploy the changed applications in a test environment.

        5. Test all applications thoroughly.

        6. Follow normal test procedures as you move the test environment into production.

      The installation wizard backs up the earlier version but does not uninstall it, exports the current configuration, and migrates the configuration to the new installation. If there are errors during the WASPreUpgrade phase, such as the administrative server from the earlier version is not running, the installation wizard does not run the WASPostUpgrade phase. The wizard displays the WASPreUpgrade.log and WASPostUpgrade.log log files if there are errors.

    • Migrate the configuration of a previous version to the Network Deployment product using the installation wizard or during a silent installation.

    • Migrate manually if you prefer a more incremental approach.

    The Migrating topic describes migrating from V4.x (very little to consider) or V3.5.x (several things to consider). It describes differences between V3.5.x and V5 brought about by the full compliance of V5 with Java 2 Platform, Enterprise Edition specifications.

  3. Set up multiple versions of WAS to coexist.

    There must be no run-time conflicts for multiple instances and versions of WAS to run at the same time on the same machine. Potential conflicts can occur in these areas:

    • Prerequisites and corequisites

    • Operating system registration

    • Environmental conflicts

    • File system

    • Port assignments

    1. Run V3.5.x and V5 together.

    2. Run V4.0.x and V5 together.

    3. Install V5 more than once on the same machine.

 

Results

Migration migrates all your resources and applications, but does not migrate entities in your classes directory. As the WAS installation wizard migrates applications to Version 5, it also migrates any applications that use IBM WAS Enterprise Edition, Version 4.0.x. The base migration removes (from the server configuration) those parts of your configuration that are dependent upon the following IBM WAS Enterprise Edition, Version 4.0.x services:

Migration backs up all files in the following directories.

 

For Version 3.5.x

  • bin

  • classes

  • deployableEJBs (Advanced Edition only)

  • deployedEJBs (Advanced Edition only)

  • hosts

  • properties

  • servlets

 

For Version 4.0.x

  • bin

  • classes

  • config (Version 4.0.x Advanced Single Server Edition only)

  • installableApps

  • installedApps

  • installedConnectors (Version 4.x Advanced Edition only)

  • properties

One can coexist with, or migrate the applications and configuration from a previous version of WAS.

 

What to do next

Migration from V4.x to V5 does not require extensive tuning.

Migration from V3.5.x to V5 does require you to examine the migrating applications.

See the Migrating administrative configurations manually topic for a description of fine tuning a migration. Part of the procedure for manual migration includes a description of what to look for after using the migration tools.


Migrating
Creating multiple Version 5 configuration instances
Coexistence support
Port number settings in WAS versions
Installation: Links

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.