Configuration mapping during migration

This topic describes what changes during migration, which always involves migrating a single instance to another single instance on the same machine or a separate machine. An example is a Version 5.x deployment manager migrating to a V6 deployment manager profile, or a V5.x Application Server migrating to a V6 stand-alone Application Server profile.

Many migration scenarios are possible. The V6 migration tools maps objects and attributes to the V6 environment when you restore a configuration from a previous version.

Bootstrap port

Migration maps a default bootstrap NameServer port setting, 900, from V4.0.x Advanced Edition or V5.x to the V6 NameServer default, 2809. The migration tools map a non-default value directly into the V6 environment.

For V4.0.x Advanced Single Server Edition migration, the bootstrap NameServer port maps to the NameServer value of the Application Server defined in the server configuration file.

Command line parameters

The migration tools convert appropriate command line parameters to Java virtual machine (JVM) settings in the server process definition. Most settings are mapped directly. Some settings, such as memory heap sizes, are not migrated because their roles in the V6 configuration either do not exist, have different meanings, or have different scopes.

Cluster members

V4.0.x server groups are converted to V6 clusters. Migration configures cluster members differently than stand-alone servers. When migrating a server group, all servers in the group are assigned to the HTTP transport port number of the server group, regardless of whether or not they each had a unique port number. Therefore, after migration, all the Application Servers in the new cluster use the same HTTP transport port. Use the administrative console to assign unique port numbers, which lets you run the server without federating it.

Default Server

The name of the default server in V6 is server1. All objects previously owned by the DefaultServer of V4.0.x are owned by server1 of V6 after migration.

Enterprise applications for cluster members

Migration does not deploy enterprise applications on cluster members when migrating from V4.0.x. You must manually deploy these applications on the cluster using scripting or the deployment manager administrative console. When migrating from V5.x, the applications are deployed automatically.

GenericServer

Introduced in V5.1.x, a GenericServer was an APPLICATION_SERVER fitted to manage external resources. In V6, it has its own type, called GENERIC_SERVER. Migration will perform this conversion, but migration cannot accurately migrate the external resources that the GenericServer references. After migration has completed migrating the GenericServer settings, we need to perform the following actions:

• If the old resource that the GenericServer was managing is located under the old WAS installation, you have to copy any related files to the new installation of WebSphere Application Server. You must also run any required setup to put the external application back into a valid and working state. IBM recommends instead that you re-install the resource into the new WAS directory. Whichever you choose to do, the final step is that we need to reset the reference to the new location of the application.

• If the old resource that the GenericServer was managing is not installed under the old WAS installation, nothing further is required.

Java DataBase Connectivity (JDBC) drivers and data sources

V6 significantly redefines JDBC and data source objects. The migration tools map V4.0.x data sources to V6 data sources, using predecessor settings as input variables.

jmsserver

jmsserver is changed from type MESSAGE_BROKER to type APPLICATION_SERVER. Any queues or topics that it owned have been migrated into the new WebSphere Platform messaging framework. In previous releases, in an ND environment, jmsserver was its own MESSAGE_BROKER server; in the Base environment it was contained within APPLICATION_SERVER types. All JMS resources are left untouched and should work without modification. Further migration of these resources can be performed by executing scripts/bats provided by WebSphere Platform messaging. For more information on the JMS resources, see messaging resources.

Migration of a V5.x node to a V6 node

We can migrate a V5.x node that belongs to a cell without removing the node from the cell.

Migrate the deployment manager first, before migrating any base nodes in the cell.

Use the same cell name when migrating Network Deployment from V5.x to V6. If you use a different cell name, federated nodes cannot successfully migrate to the Network Deployment V6 cell.

Migrating a base WebSphere Application Server node that is within a cell to V6 also migrates the node agent to V6. A cell can have some V6 nodes and other nodes that are at V5.x levels.

Name bindings

V6 has a new naming structure. All references, such as Enterprise JavaBeans (EJB) references that were valid in previous versions no longer work in V6. However, use the administrative console to add a name binding that maps an old name into the new V6 naming structure. For example, the name of the V5.0.x enterprise bean reference can be both the name of the binding and the Java Naming and Directory Interface (JNDI) name in the V6 name space.

Note: The contents of name spaces from previous versions are not automatically migrated to V6.

Node name

A V4.0.x repository can contain more than one node name and associated children. The WASPostUpgrade tool processes only those objects and children that match the node name of the migrating node. The tool identifies node names in the configuration files that it is migrating and selects any node names in a configuration file that match the long network name or short network name of the migrating machine.

PageList servlet

The configuration of the PageList servlet has changed from V4.0.x. Direct use of the servlet has been deprecated. The PageList servlet is available as part of the servlet extension configuration in the WAR file. All references are updated to the servlet configuration supported in Version 6.

We can also use the Application Server Toolkit (AST) and Rational Web Developer to modify the servlet configuration. See Assembly tools for more information.

If you use or extend the PageList servlet, you might see an error similar to the following example when running a migrated application that uses the servlet

Error 500: No PageList information is configured for servlet 
EmpInfoApp.SearchByDept

Use the Assembly Toolkit to correct the error, by moving the usage or extension to your migrated Enterprise archive (EAR) file:

1. Start the Assembly Toolkit to load the EAR file that generates the error.

2. Open the Web modules within the EAR file.

3. Expand the Web module that generates the error.

4. Open the Web components and find the one that generates the error.

5. Expand the Servlets. The PageList Extensions option displays.

6. Add your extension information.

7. Save the EAR file and redeploy it.

Policy file migration from V5.x to V6

WebSphere Application Server V6 migrates all the policy files that are installed with V5.x by merging settings into the V6 policy files with the following characteristics:

• Any comments located in the V6 policy file will be lost. They are replaced with the comments contained in the V5 policy file.

• Migration will NOT attempt to merge permissions or grants; it is strictly an add-type migration. If the permission or grant is not located in the V6 file, the migration will bring it over.

• Security is a critical component; thus, the migration makes any additions at the end of the original .policy file right after the comment MIGR0372I: Migrated grant permissions follow. This is done to help administrators verify any policy file changes that the migration has made.

Properties directory and the lib/app directory

Migration copies files from prior version directories into the V6 configuration. See the following section for more information.

Property file migration from V4.0.x

V6 migration migrates property files from V4.0.x if these files are also present in WebSphere Application Server, V6. Specifically, property-file migration includes these files:

• converter.properties

• sas.client.props

• encoding.properties (If the "ko" setting is incorrect, no migration occurs.)

• TraceSettings.properties

You must manually convert settings in other property files to the equivalent V6 configuration.

Property file migration from V5.x to V6

WebSphere Application Server V6 migrates all the property files that are installed with V5.x by merging settings into the V6 property files with these exceptions:

• j2c.properties (migrated into resources.xml files)

• samples.properties

Migration does not overlay property files.

Resource Adapter Archive (RAR) referenced by J2C resources

RARs that are referenced by J2C resources are migrated if those RARs are in the old WAS installation. In this case, the RARs are copied over to the corresponding location in the new WebSphere Application Server installation. Relational Resource Adapter RARs will not be migrated.

Samples

During the migration of the deployment manager, V5.x Samples for federated nodes are migrated. Equivalent V6 Samples are available to use for all other V5.x Samples.

Security

Java 2 Security is enabled by default in V6. Security enablement might cause some applications to run on Versions 4.0.x and not run on V6. Several techniques are available that use to define different levels of Java 2 Security in V6. One is to create a was.policy file as part of the application, to enable all security permissions. The migration tools call the wsadmin command to add an existing was.policy file in the V6 properties directory to enterprise applications as they migrate. The migration tools perform this task while moving V4.0.x applications into V6.

Global security that uses LTPA in Version 4.0.x is migrated to the base WAS product and to the Network Deployment product. However, although global security was enabled in V4.0.x, it is disabled during migration to V6 (security is NOT disabled when migrating from V5.x).

The Global security feature that uses localos authentication mechanisms in V4.0.x is migrated to the Network Deployment product. However, although global security was enabled in V4.0.x, it is disabled during migration to V6. The Network Deployment product does not support the authentication mechanism known as SWAM. Migration sets the authentication mechanism in Version 6 to LTPA. Use the administrative console to generate keys for the migrated LTPA. After generating the keys, one can enable global security.

Version 4.0.x introduced properties to support tuning the JNDI search timeout value along with LDAP reuse connection. These two properties are now settings in the Security Center of the V6 administrative console. V4.0.x property values are not migrated to V6 settings.

• The jndi.LDAP.SearchControl.TimeLimit property is equivalent to the Version 6 Search Timeout setting, which is 300 by default in V6.

• The jndi.LDAP.URLContextImplementation property is equivalent to the Version 6 Reuse Connection setting, which is true by default in V6.

Use the V6 administrative console to change these settings to match your V4.0.x property values, if necessary.

Server groups

V4.0.x server groups are redefined in V6 as clusters. Application servers are the only objects supported as cluster members in V6.

Servlet package name changes

The package that contains the DefaultErrorReporter, SimpleFileServlet, and InvokerServlet servlets changed as of V5. In V4.0.x, the servlets are in the com.ibm.servlet.engine.webapp class. In V6, the servlets are in the com.ibm.ws.webcontainer.servlet class.

Stdin, stdout, stderr, passivation, and working directories

The location for these directories is typically within the installation directory of a previous version. The default location for stdin, stdout, and stderr is the logs directory of the V6 installation root. The migration tools attempt to migrate existing passivation and working directories. Otherwise, appropriate V6 defaults are used.

common directories between versions in a coexistence scenario can cause problems.

Transport ports

The migration tools migrate all ports. The tools warn about port conflicts in a log when a port already exists. You must resolve port conflicts before running the servers that are in conflict, at the same time.

Choosing -scriptCompatibility="true" or -scriptCompatibility="false" results in two different outcomes for transport ports:

• -scriptCompatibility="true": This results in your transport ports being brought over as they are (this is the default).

• -scriptCompatibility="false": This results in the transports ports being converted to the new implementation of channels and chains. From an external application usage standpoint, they will still act the same, but they have been moved to the TransportChannelService. For further information on transport chains and channels, see Transport chains.

Web modules

The specification level of the J2EE that V6 implements requires behavior changes in the Web container for setting the content type. If a default servlet writer does not set the content type, not only does the V6 Web container no longer default to it, the Web container returns the call as "null". This situation might cause some browsers to display resulting Web container tags incorrectly. Migration sets the autoResponseEncoding IBM extension to true for Web modules as it migrates enterprise applications. This action prevents the problem.

V4.0.x to V6 migration

The V4.0.x configuration is already at the J2EE 1.2 specification level. Although V6 is at the J2EE 1.4 specification level, J2EE 1.2 objects are supported.

• Enterprise beans

  No redeployment is required when moving EJB 1.1 JAR files from V4.0.

  Specify only one backend data store vendor per JAR file. If enterprise beans use different backend data stores, package them into separate JAR files.

• JMS Resources

  All JMS resources from V4.0 are mapped into generic JMS resources in the V6 configuration. Reconfigure JMS resources that use IBM WebSphere MQ as IBM WebSphere MQ-specific resources. MQ JMS resources have better integration with system management. You do not need to manually define entries in the name space. We can see the backing MQ queue definitions through MQ JMS entries.

• JSP precompiling

  In V4.0.x, the classes generated from JSP pages are in a package based on the directory structure of the WAR file. Any JSP at the top of the context root is in the unnamed package. JSP pages in subdirectories of the root are in packages named after the subdirectories. In V6, the classes generated from JSP pages are all in the org.apache.jsp package. Therefore, the class files are not compatible between versions.

  When migrating an enterprise application from V4.0.x to V6, recompile the JSP pages to regenerate the class files into the correct packages.

  The migration tools provide this support, by using the -preCompileJSPs option of the wsadmin tool during the installation of the application.

  Use the same option to install any V4.0.x enterprise applications that you manually move to V6.

• J2EE security

  We can apply security in two V4.0.x locations to enterprise applications. Information in the repository has precedence over information in the enterprise application bindings. The migration tools migrate information in the repository to the enterprise application.

• SSL migration

  The following SSLConfig attributes that point to user-defined key files are migrated from WAS V4.0.x (AE) or V5.x to V6 as follows:

  V4.0.x or V5.x settings

  <key_file_name>dir_name/WASLDAPKeyring.jks</key_file_name>
  <trust_file_name>dir_name/WASLDAPKeyring.jks</trust_file_name>
  
  

<key_file_name>${WAS_HOME}/keys/WASLDAPKeyring.jks</key_file_name>
<trust_file_name>${WAS_HOME}/keys/WASLDAPKeyring.jks</trust_file_name>