Configuration mapping during migration: WAS ND

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 server group node from a V4.0.x environment migrating to a Version 5.x node that you later federate into a deployment manager cell.

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

Bootstrap port

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

For 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 V5.x configuration either do not exist, have different meanings, or have different scopes.

Cluster members

V4.0.x server groups are converted to V5.x 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. Migrated cluster members cannot run until federated into a Network Deployment cell. You can 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 V5.x is server1. All objects previously owned by the DefaultServer of the prior version, are owned by server1 of V5.x after migration.

Enterprise applications for cluster members

Migration does not deploy enterprise applications on cluster members when migrating from V3.5.x or V4.0.x. You must manually deploy these applications on the cluster using scripting or the deployment manager administrative console.

Automated migration of enterprise applications that are installed in a directory other than the default installedApps directory is not feasible in V5.x. Versions 4.0, 5.0, and 5.1 each allow enterprise applications to be installed in a location other than the default installedApps directory. However, for architectural reasons, this property is not migrated from previous versions of WebSphere Application Server to Version 5.0 or V5.1. The migration process instead redeploys the enterprise application to the default installedApps directory in the new version. Enterprise applications that are not installed in the default directory must be reinstalled in their new V5.x environment.

Java database connectivity (JDBC) drivers and data sources

V5.x significantly redefines JDBC and data source objects. The migration tools map V3.5.x and V4.0.x data sources to V5.x data sources, using predecessor settings as input variables. The data source that is used is the WebSphere Application Server V4.0.x data source that uses the ConnectionManager architecture.

Migration after federation

You cannot migrate a previous version configuration to a V5.x Application Server node after the node is federated into a deployment manager cell. The master copy of the configuration no longer resides on the V5.x Application Server node. A master configuration is on the deployment manager node.

You can perform the migration by removing the Application Server node from the cell, migrating, and refederating the node to the cell. As the node is federated, the deployment manager copies the migrated configuration into the master configuration that it maintains for the Application Server node.

Migration of a V5.0.x node to a V5.1.x node

You can migrate a V5.0.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.

Migration tip

Operating platform Tip in Platform-specific tips for installing and migrating
All platforms Avoiding the use of a V5.0.x deployment manager after migrating to V5.1

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

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

Models, clones, and server groups

V3.5.x models and clones and V4.0.x server groups are redefined in V5.x as clusters. Application servers are the only objects supported as models and cluster members in V5.x. This change is a significant difference from V3.5.x, in which many objects can be models and clones. All models and clones relating to Application Servers are mapped to clusters in V5.

Special mapping occurs during the migration of all the other objects that you could previously clone. All clones are treated as simple objects and map as if they are not cluster members. Models that are not Application Server models are ignored and unmapped.

Name bindings

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

For an example, see Migrating to WebSphere V5: An End-to-End Migration Guide, which is available from the Redbooks Web site at http://www.ibm.com/redbooks .

Node name

A V3.5.x and 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 nodes 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 in V5.x. Direct use of the servlet has been deprecated. The PageList servlet is available as part of the servlet extension configuration in the Web archive (WAR) file. All references are updated to the servlet configuration supported in Version 5.

You can also use the to modify the servlet configuration.

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 to correct the error, by moving the usage or extension to your migrated Enterprise archive (EAR) file:

Start the to load the EAR file that generates the error.

Open the Web modules within the EAR file.

Expand the Web module that generates the error.

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

Expand the Servlets. The PageList Extensions option displays.

Add your extension information.

Save the EAR file and redeploy it.

Properties directory, classes directory, and the lib/app directory

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

Property file migration from V3.5.x and V4.0.x

V5.1 migration does migrate property files from V3.5.x and V4.0.x if these files are also present in WebSphere Application Server, V5.1. Specifically, property-file migration includes these files:

converter.properties

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

sas.client.props

TraceSettings.properties

uddi.properties (V4.0,x only)
You must manually convert settings in other property files to the equivalent V5.1 configuration.

Property file migration from V5.0.x to V5.1.x

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

j2c.properties

samples.properties

Migration does not overlay property files.

Samples

No migration of Samples from previous versions is available. Equivalent V5.x Samples are available to use.

Security

Java 2 Security is enabled by default in V5.x. Security enablement might cause some applications to run on V4.0 and not run on Version 5.x. Several techniques are available that you can use to define different levels of Java 2 Security in V5.x. 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 V5.x properties directory to enterprise applications as they migrate. The migration tools perform this task while moving Version 4.0 applications into V5.

Global security that uses Lightweight Third Party Authentication (LTPA) in Versions 3.5.x and 4.0.x is migrated to the base WebSphere Application Server product and to the Network Deployment product. However, although global security was enabled in Versions 3.5.x and 4.0.x, it is disabled during migration to V5.x.

If you add this node later to an IBM WebSphere Application Server Network Deployment, V5.x configuration, you can enable and use the LTPA configuration. Use the administrative console to generate keys for the migrated LTPA mechanism. After generating the keys, you can enable global security.

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

V4.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 Version 5.x administrative console. V4.0.x property values are not migrated to V5.x settings.

The jndi.LDAP.SearchControl.TimeLimit property is equivalent to the Version 5.x Search Timeout setting, which is 300 by default in V5.

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

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

Servlet package name changes

The package that contains the DefaultErrorReporter, SimpleFileServlet, and InvokerServlet servlets has changed for V5.x. In Versions 3.5.x and 4.0.x, the servlets are in the com.ibm.servlet.engine.webapp class. In V5, 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 V5.x installation root. The migration tools attempt to migrate existing passivation and working directories. Otherwise, appropriate V5.x defaults are used.

Using 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.
The default transport type of the servlet engine in V3.5.x is Open servlet engine (OSE). Because V5.x no longer supports OSE transport, the migration tools map these transports to HTTP transports, using the same port assignments.

You must manually add VirtualHost alias entries for each port.

Web modules

The specification level of the Java 2 Platform, Enterprise Edition (J2EE) that V5.x 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 V5.x 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.

V3.5.x to V5.x migration

The migration tools assist in the transition from V3.5.x to Version 5, by migrating system configurations and creating J2EE artifacts, including J2EE security roles mapping. The migration tools create initial J2EE enterprise applications based on V3.5.x configurations. However, because of the significant change in application structures, plan to carefully test and fine tune migrated applications, using development and deployment tools, to determine exactly how the applications function in V5.x.
Analyze the WASPostUpgrade.log file for detailed information about migrated enterprise beans. The J2EE programming model specifies an architecture for how applications are created and deployed. Because applications in V3.5.x do not have the same architecture, the WASPostUpgrade tool recreates applications. It creates all migrated Web resources and enterprise beans in J2EE applications. It maps all enterprise applications from the V3.5.x installation into J2EE applications with the same name, deployed in the same server.

The WASPostUpgrade tool maps Web resources and enterprise beans that are not included in an enterprise application, into a default J2EE application that includes the name of the server. The tool maps Web applications to J2EE WAR files. The tool deploys enterprise beans as EJB 1.1 beans in J2EE JAR files. The tool combines resources in a J2EE EAR file and deploys it in the V5.x configuration. Some differences exist between the EJB 1.0 and EJB 1.1 specifications, but in most cases, EJB 1.0 beans can run successfully as EJB 1.1 beans.

Mapping details for V3.5.x to V5.x migration

data sources.xml
You can use a V3.5.x data sources.xml file to augment data source configuration settings. V3.5.x stores the file in the properties directory. The migration tools migrate an existing data sources.xml file by merging properties in the file into the data source and JDBC driver configuration.

Enterprise applications
The V3.5.x enterprise application entries are optional. The entries group sets of objects together for security definitions. The enterprise bean and Web application portions of the enterprise application point to their respective entries in other portions of the XML file. Processing each enterprise application creates a J2EE application with the same name. The enterprise bean and Web application entries become pointers to the definitions of enterprise beans and Web applications. Entry details help build a J2EE application.

For enterprise bean files, the JAR file definition helps locate the JAR files to redeploy and add to the J2EE application. Document root entries in the Web application help locate the resources used within the Web application, such as HTML pages and JSP pages, which become part of the WAR file within the J2EE application. Class path entries in the Web application help locate servlets and JAR files, which become part of the WAR file within the J2EE application.
V3.5.x. migration to V5.x creates J2EE 1.2 compatible enterprise applications that contain EJB 1.1, Servlet 2.2, and JSP 1.1 level modules. This migration provides the most straight forward compatibility and enables interoperability with previous WebSphere Application Server versions.

Enterprise beans
V3.x supports only the EJB 1.0 Components Specification level. V5.x supports EJB 1.1 and 2.0 components. However, many EJB 1.0 beans can successfully deploy as EJB 1.1 beans. The migration tools redeploy enterprise beans automatically as part of the application migration phase. Check the WASPostUpgrade.log file for deployment details of these enterprise beans. Make any necessary changes and redeploy.

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

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

J2EE security
The security authorization model in V3.5.x is based on the notion of enterprise application and method groups. The cross product of the enterprise application and the method groups is a WebSphere Application Server permission. The J2EE specification includes an authorization model based on roles.

To convert from the WebSphere Application Server permission model in V3.5.x to the role-based authorization model in V5, the migration tools create a one-to-one mapping from a WebSphere Application Server permission to a new role under that application. Therefore, for each enterprise application and each method group in V3.5.x, the migration tools create a role in V5, contained in the J2EE application deployment descriptor. The authorized subjects for each role are contained in an authorization table found in the J2EE application binding.

The J2EE specification includes an authorization model based on roles. WebSphere Application Server interprets the role to mean a set of permissions to access a resource. In the case of an enterprise bean method invocation, the permission to access the method on a particular bean is specified by a method permission. This method permission is associated with one or more roles in the deployment descriptor of the bean JAR file.

In the case of accessing Web resources, the permission to access a Web URI and invoke an HTTP method on that URI is specified in terms of Web resource collections and security constraints in the J2EE specification. The deployment descriptor in the WAR file of the Web application contains the security constraints and Web resource collections.

JSP levels
V5.x runs JSP 1.0 and 1.1 objects as JSP 1.2 objects, which is the only supported level.

Servlet redirector
V5.x does not support the servlet redirector from previous versions. The migration tools ignore these objects.

Servlet package name changes when migrating from V3.5.x to V5.x
If the V3.5.x configuration defines the SimpleFileServlet servlet, this servlet is not migrated. The migration tools set the FileServingEnabled attribute in the ibm-web-ext.xmi Web module file to true.

If the V3.5 configuration defines the InvokerServlet servlet, the servlet is not migrated. The migration tools set the ServeServletsByClassnameEnabled attribute in the ibm-web-ext.xml Web module file to true.

If the V3.5.x configuration defines the DefaultErrorReporter servlet, the servlet is migrated into the web.xml Web module file. Migration uses the new package to set the class name.

Transports
The default transport type of the servlet engine in V3.5.x is Open servlet engine (OSE). Because V5.x no longer supports OSE transport, the migration tools map these transports to HTTP transports, using the same port assignments. You must manually add VirtualHost alias entries for each port.

V4.0.x to V5.x migration

This migration is much less complicated than moving from V3.5.x to V5.x. The V4.0.x configuration is already at the J2EE 1.2 specification level. Although V5.x is at the J2EE 1.3 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 V5.x 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. You 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 V5, 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 V5, 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 V5.x.

J2EE security
You 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.

Secure Sockets Layer (SSL) migration
The following SSLConfig attributes that point to user-defined key files are migrated from WebSphere Application Server Advanced Edition, V4.0.x to V5.x as follows:

V4.0.x settings

<key_file_name>dir_name/WASLDAPKeyring.jks</key_file_name> <trust_file_name>dir_name/WASLDAPKeyring.jks</trust_file_name>
The dir_name variable identifies the original location of the WASLDAPKeyring.jks file.

V5.x settings

keyFileName="dir_name/WASLDAPKeyring.jks" trustFileName="dir_name/WASLDAPKeyring.jks"
The dir_name variable identifies the original location of the WASLDAPKeyring.jks file.

V4.0.x settings

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

V5.x settings

keyFileName="${USER_INSTALL_ROOT}/keys/WASLDAPKeyring.jks" trustFileName="${USER_INSTALL_ROOT}/keys/WASLDAPKeyring.jks"

The migration tools do not copy the key files (for example, .jks, or .kdb) to the corresponding directory in the base WebSphere Application Server product or the Network Deployment product. You must complete the migration of the SSL configuration by copying qualifying key store files to V5.x directories.

If the key-file-name and trust-file-name attributes point to the DummyServerKeyFile.jks file in the WebSphere Application Server Advanced Edition V4.0.x configuration, the key-file-name and trust-file-name attributes are not migrated to V5.x. Instead the V5.x default value of ${USER_INSTALL_ROOT}/etc/DummyServerKeyFile.jks is left unchanged.

Servlet package name changes when migrating from V4.0 to Version 5.x
If the web.xml Web module file for V4.0 defines the SimpleFileServlet servlet, the migration tools update the class name to reflect the V5.x package. The tools also set the FileServing Enabled attribute to true.

If the web.xml file defines the InvokerServlet servlet, the migration tools update the class name to reflect the V5.x package. The tools also set the ServeServletsByClassnameEnabled attribute to true.

If the web.xml file defines the DefaultErrorReporter servlet, the migration tools update the class name to reflect the V5.x package.

V5.0.x to V5.1 migration

Migrating V5.0.x to V5.1 is much less complicated than migrating from V4.0.x or V3.5.x. Both sides of the migration use the same underlying definitions. The task involves mapping configuration files from the V5.0.x to the V5.1 configuration and copying installed applications into the new product. The migration tools support the migration of federated nodes and support the full migration of a Network Deployment node.

Java heap size for migrating EAR files

When migrating all 5.0.x EAR files to V5.1 using the wsadmin tool, the WASPostUpgrade tool uses the default maximum Java heap size value of 64MB to install the EAR files.
If a V5.0.x EAR file fails to install during migration because the Java heap size is not large enough, you see a message similar to the following error:

java.lang.OutOfMemoryError JVMXE006:OutOfMemoryError

Increase the maximum Java heap size. Then use the following information to manually install the EAR file. Assume that the new maximum heap size is represented by number signs (###) in the following example. If the install_app_name.jacl file is in the $WAS50_backup directory created by migration, run the following command from the bin directory of the V5.1 WebSphere Application Server. (The command appears on more than one line for clarity.)

wsadmin -conntype NONE -javaoption -Xmx###m -f $WAS50_backup/install_app_name.jacl

If the install_app_name.jacl file does not exist in the $WAS50_backup directory created by migration, run the following command from the install_root/bin directory of the Version 5.1 base WebSphere Application Server product or the Network Deployment product.

Installing the application on WebSphere Application Server, V5.1

Assume that:

Installation root

C:\WebSphere\AppServer

Number signs (###)

Maximum heap size value

EAR_file_name

The name of the EAR file

app_name

The name of the application.

server

The name of the server on which the EAR file installs

node

The name of the node on which the server is configured

The command appears on more than one line for clarity.

wsadmin -conntype NONE -javaoption -Xmx###m -c "$AdminApp install C:\\WebSphere\\AppServer\\installableApps\\ EAR_file_name {-nodeployejb -appname app_name -server server -node node}"

Installing the application on WebSphere Application Server Network Deployment, V5.1

Assume that:

Installation root

C:\WebSphere\DeploymentManager

Number signs (###)

Maximum heap size value

EAR_file_name

The name of the EAR file

app_name

The name of the application.

cluster_name

The name of the cluster on which the EAR file should be installed

The command appears on more than one line for clarity.

wsadmin -conntype NONE -javaoption -Xmx###m -c "$AdminApp install C:\\WebSphere\\DeploymentManager\\installableApps\\ EAR_file_name> {-nodeployejb -appname app_name -cluster cluster_name}"

No migration of configuration instances from V5.0.x to V5.1

The migration tools do not support the migration of configuration instances from V5.0.x to V5.1

Migrating

Migrating and coexisting
Using enterprise beans in applications

Java 2 security
Process logs