Migration configuration mapping

This topic describes how the migration tools map the configuration from the previous release to Version 5 for the basic migration scenario. The basic migration scenario involves migrating a single WebSphere Application Server Version 3.5, Version 4, or Version 5.0.x Express instance to a WebSphere Application Server Version 5 instance located on the same iSeries server.

The migration tools map objects and attributes existing in the version you are migrating from to the corresponding objects and attributes in the Version 5 environment.

• Stdin, stdout, stderr, passivation and working directories
  The location for these directories is typically the logs directory under the WebSphere Application Server instance directory. For example in Version 4 Advanced Edition, the logs directory for the default instance is /QIBM/UserData/WebASAdv4/default/logs. For Version 5, the default location for stdin, stdout, and stderr is still the logs directory located under the WebSphere Application Server instance directory. For example, the logs directory for the default instance is /QIBM/UserData/WebAS5/Base/default/logs. The migration tools attempt to migrate existing passivation and working directories. Otherwise, appropriate Version 5 defaults are used. For more information on passivation directories, see the help topic EJB container settings . For more information on working directories, see the help topic Process definition settings .

  Note: In a coexistence scenario, using common directories between versions can create problems.

• Property files from Version 3.5.x and 4.0.x
  Migration does not process property files from Version 3.5.x and 4.0.x that are located in the properties directory for an instance. You must manually convert settings in these files to the Version 5 equivalent configuration.

• Command line parameters
  The migration tools convert appropriate command line parameters to JVM settings in the server process definition. However some settings, such as memory heap sizes, are not migrated because their role in the Version 5 configuration either does not exist, has different meaning, or has different scope. For information on how to change the process definition settings, see the help topic Process definition . For information on how to change the Java virtual machine settings, see the help topic Java virtual machine .

• Bootstrap port
  If the administrative server for your Version 3.5.x or Version 4 Advanced Edition WebSphere Application Server instance is using port 900 for the bootstrap port, the migration tools map this port to port 2809 for the bootstrap port (also known as the name service port) in the Version 5 instance. Also if the application server name of the Version 3.5.x or Version 4 instance matches the Version 5 instance, the port number remains unchanged from the value of the name service port used when the Version 5 instance was created. If the instance you are migrating from uses a port other than 900 for the bootstrap port, the migration tools use that same port for the bootstrap port of the Version 5 instance. However, if the -portBlock was specified during the call to WASPostUpgrade, a new port value is given to each application server that is migrated to Version 5. The bootstrap port is specified in the admin.properties file located in the properties file WebSphere Application Server Version 3.5.x or Version 4.0.x Advanced Edition instance.
  If you are migrating from Version 4 Advanced Single Server Edition, the bootstrap port is specified in the server configuration file for the application server. The migration tools map the bootstrap port as indicated above for an Advanced Single Server instance.

• Default Server
  The name of the default server in Version 3.5.x and 4.0.x is Default Server. The name of the default server in Version5 is server1. Thus, the Default Server in Version 3.5.x and 4.0.x is migrated to the server1 server in Version 5.

• JDBC drivers and datasources
  The JDBC connection manager from Version 4 is still provided as a configuration option. Using this configuration option enables J2EE 1.2 applications to run unaltered. If you migrate a Version 4 application to Version 5, using the Version 5 migration tools, the application automatically uses the Version 4 connection manager after migration. However, EJB 2.0 modules in J2EE 1.3 applications cannot use the JDBC connection manager from Version 4.

• Name bindings
  There is a new namespace structure in Version 5. Enterprise bean references in Version 5 are incompatible with the references that are expected by application components such as servlets or enterprise beans running in Version 3.5 or Version 4. This only affects topologies where applications running in previous WebSphere Application Releases must access enterprise beans running in Version 5. This does not impact topologies where all application components are running in Version 5.
  The following instructions describe how to externalize the EJB in Version 5 so that a Version 3.5 or Version 4 application component can access it:

  1. Start the Version 5 administrative console.
  2. Navigate to Environment --> Naming --> Name Space Bindings.
  3. Click New.
  4. Specify Ejb for the Binding Type.
  5. Specified SHARED for the Node.
  6. In the Binding Identifier, Name in Name Space, and JNDI Name fields, specify the reference used for enterprise bean in Version 3.5.x or Version 4.0.x.
  7. Click OK.

  8. Save your changes.

• Node name
  A Version 3.5.x or Version 4.0.x administrative repository can contain more than one node name. Each node may have WebSphere Application Server resources associated with it. The migration tools process only the node (and its associated resources) whose node name matches the TCP/IP host name of the iSeries on which the WebSphere Application Server instance resides. The migration tools identify the nodes names in any configuration files it is processing, and migrates only resources that belong to a node whose name matches the long or short host name of the iSeries. The host name of the iSeries can be found under CFGTCP option 12 (CHGTCPDMN).

• PageList servlet
  The configuration of the PageList servlet has changed in Version 5. 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 5.

  You can also use the Application Assembly Tool (AAT) to modify the servlet configuration. If you have used or extended the PageList servlet, you might see an error similar to this when running a migrated application that uses the servlet:

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

  Use the Application Assembly Tool (AAT) to correct the error, by moving the usage or extension to your migrated EAR file:

  1. Start the AAT and load the EAR file that generates the error.
  2. Open Web modules within the EAR file.
  3. Expand the Web module that generated the error.
  4. Open the Web components and find the component that generated the error.
  5. Expand Servlets.
  6. Add your extension information under PageList Extensions.
  7. Save your EAR file and redeploy it.

  For more information on migrating your servlets to Version 5, see Migrate Web applications in the Application Development topic.

• Properties directory, classes directory, and lib/app directory
  Migration does not copy files from these prior version directories into the Version 5 configuration. Property files are not compatible between versions. The classes directory might contain incompatible files. You must migrate these files on an individual basis to move them into the Version 5 configuration.

  If you are migrating to WebSphere Application Server Version 5 or Version 5.0.1, then applications relying on the application extensions classloader or the lib/app directory must manually migrate to WebSphere Application Server Version 5. This does not apply if you are migrating to WebSphere Application Server Version 5.0.2 or later. Follow these steps to manually migrate:

  1. Create the lib/app subdirectory in the Version 5 /QIBM/UserData/WebAS5/Base/instance directory, where instance is the name of your instance. QEJBSVR should be the owner and have *RWX authority to the directory and and files placed in the directory.
  2. Do one of the following tasks:
     • Copy the files from the Version 4 lib/app subdirectory to the Version 5 lib/app subdirectory. Enter these commands from a Qshell command prompt:

       1. mkdir /qibm/userdata/webas5/base/instance/lib

       2. mkdir /qibm/userdata/webas5/base/instance/lib/app

       3. cp /qibm/userdata/webasadv4/instance/lib/app/* 
          /qibm/userdata/webas5/base/instance/lib/app

       4. chown -R QEJBSVR /qibm/userdata/webas5/base/instance/lib

     • Create shared libraries in Version 5 to contain the classes contained in the Version 4 applications extensions directory. For more information, see Administer shared libraries in the Administration topic.

       Note: This is the preferred method, because it is more portable and flexible than using the lib/app subdirectory.

• Samples
  There is no migration of samples from previous versions. There are equivalent Version 5 samples that you can use. The samples are not preinstalled. See Samples Gallery in the Application Development topic for more information on installing and using the samples.

• Security
  If security is enabled for applications in your Version 4 instance, the same applications may not function correctly in the Version 5 environment. This is because Java 2 Security is enabled by default when you enable security in Version 5. Java 2 Security requires you to grant security permissions explicitly. There are several techniques that you can use to define different levels of Java 2 Security in Version 5. 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 Version 5 properties directory to enterprise applications as they are being migrated. The migration tools perform this task while moving Version 4 applications into Version 5.

  Global security that uses LTPA authentication in Versions 3.5.x and 4.0.x is migrated to the base WebSphere Application Server product. However, although global security was enabled in Versions 3.5.x and 4.0.x, it is disabled during and after migration to Version 5. After migration, LTPA keys are generated when security is enabled in the administrative console. Security is left enabled when migrating instances that use the LocalOS authentication mechanism.

  Version 4.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 administrative console. There is no migration of Version 4.x property values to the Version 5 settings.

  • The jndi.LDAP.SearchControl.TimeLimit property is equivalent to the Version 5 Search Timeout setting, which is 300 by default in Version 5.
  • The jndi.LDAP.URLContextImplementation property is equivalent to the Version 5 Reuse Connection setting, which is true by default in Version 5.

  Use the Version 5 administrative console to change these settings to match your Version 4 property values, if necessary.

  For more information on migrating your security configurations to Version 5, see Migrate security configurations from previous releases in the Security topic.

• Servlet package name changes
  The package that contains the DefaultErrorReporter, SimpleFileServlet, and InvokerServlet servlets has changed for Version 5. In Versions 3.5.x and 4.0.x, the servlets are in the com.ibm.servlet.engine.webapp class. In Version 5, the servlets are in the com.ibm.ws.webcontainer.servlet class. For more information, see Migrate Web applications in the Application Development topic.

• Transport ports
  The migration tools migrate all ports. If the -portBlock parameter is specified in the WASPostUpgrade script a new value is assigned to each transport that is migrated. For more information, see The WASPostUpgrade script in the Administration topic. The tools log port conflict warnings if a port is already defined in the configuration. You must resolve port conflicts before running the servers that are in conflict, at the same time. To resolve port conflicts, use the The chgwassvr script.

  The default transport type of the Servlet Engine in Version 3.5.x is Open Servlet Engine (OSE). Because Version 5 no longer supports OSE transport, the migration tools map these transports to Web Container transports, using the same port assignments.

  You must manually add VirtualHost alias entries for each port. For more information, see Configure the virtual host in the Installation topic.

• Web modules
  The Version 5 level of J2EE requires Web container behavior changes in regard to setting content type. If a default servlet writer does not set the content type, not only does the Version 5 Web container no longer default to it, the Web container returns the call as "null". This 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 prevents the problem. For more information on migrating your web applications to Version 5, see Migrate Web applications in the Application Development topic.

• Version 3.5 to Version 5 migration
  The migration tools assist in the transition from Version 3.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 Version 3.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 Version 5.

  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 Version 3.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 Version 3.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 Version 5 configuration. There are some differences 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.

• Version 3.5 to Version 5 mapping details
  Note: See API and Specifications for version 3.5.x to plan your application migration requirements.

  • datasources.xml
    Use a Version 3.5.x datasources.xml file to augment datasource configuration settings. Version 3.5.x stores the file in the properties directory. The migration tools migrate an existing datasources.xml file by merging properties in the file into the datasource and JDBC driver configuration. For more information on migrating your data access applications to Version 5, see Migrate a Version 4 data access application to Version 5 .

  • Enterprise applications
    The Version 3.5.x enterprise application entries are optional; they are most often used to organize 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. Each enterprise application is processed to create a J2EE application with the same name. The enterprise bean and Web application entries are used as pointers to the definitions of enterprise beans and Web applications. The details of these entries are then used to build a J2EE application.

    For enterprise bean files, the JAR file definition is used to find the JAR files to redeploy and add to the J2EE application The Web application document root entries are used to find the resources used within the Web application (HTML, JSP pages, and so forth) These files are copied to the WAR file within the J2EE application. The Web application classpath entries are used to find servlets and JAR files that are copied to the WAR file within the J2EE application.

    Enterprise applications are created during the migration from Version 3.5.x. These are created as J2EE 1.2 compatible enterprise applications and contain EJB 1.1-, Servlet 2.2- and JSP 1.1-level modules. This provides the most straight forward compatibility and enables interoperability with previous WebSphere Application Server versions.

  • Enterprise beans
    Version 3.x supports only the EJB 1.0 Components Specification level. Version 5 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 Version 4. Specify only one backend datastore vendor per JAR file. If there are enterprise beans that use different backends, package them into separate JAR files. For more information on migrating your enterprise beans to Version 5, see Migrate enterprise bean code to the supported specification in the Application development topic.

  • J2EE security
    The security authorization model in version 3.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. J2EE specifies an authorization model based on roles.

    To convert from the WebSphere Application Server permission model in version 3.5.x to the role based authorization model in Version 5, 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 Version 3.5.x, the migration tools create a role in Version 5, 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.

    J2EE specifies 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 in the bean jar file.

    In the case of accessing Web resources, the permission to access a Web URI and invoke a HTTP method on that URI is specified in terms of Web resource collections and security constraints in J2EE. The deployment descriptor of the Web application WAR file contain the security constraints and Web resource collections. For more information on migrating your security configurations to Version 5, see Migrate security configurations from previous releases in the Security topic.

  • JSP levels
    Version 5 runs JSP 1.0 and 1.1 objects as JSP 1.2 objects, which is the only supported level. For more information, see Migrate Web applications in the Application Development topic.

  • Servlet Redirector
    Version 5 does not support the Servlet Redirector from previous versions. The migration tools ignore these objects.

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

    If the Version 3.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 Version 3.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. See Migrate Web applications in the Application Development topic for more information on migrating your servlets to Version 5.

• Version 4 to Version 5 migration
  This migration is much less complicated than moving from Version 3.5.x. The Version 4.0.x configuration is already at the J2EE 1.2 level. Although Version 5 is at the J2EE 1.3 level, J2EE 1.2 objects are supported.

  Note: See API and Specifications for version 4.x to plan your application migration requirements.

  • Enterprise beans
    No redeployment is required when moving EJB 1.1 JAR files from Version 4.0.

    Specify only one backend datastore vendor per JAR file. If there are enterprise beans that use different backends, package them into separate JAR files. See Migrate enterprise bean code to the supported specification in the Application development topic for more information on migrating your enterprise beans to Version 5.

  • JMS Resources
    All JMS resources from Version 4 are mapped into generic JMS resources in the Version 5 configuration. Reconfigure JMS resources that use IBM WebSphere MQ as IBM WebSphere MQ specific resources. MQ JMS resources have better integration with System Management. There is no need to manually define entries in the name space. You can see the backing MQ queue definitions through MQ JMS entries. See Migrate JMS applications to Version 5 for more information on migrating your applications that use JMS to Version 5.

  • JSP precompiling
    In Version 4.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 Version 5, the classes generated from JSP pages are all in the package org.apache.jsp. Therefore, the class files are not compatible between versions.

    When migrating an enterprise application from Version 4.0.x to Version 5, 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 Version 4.0.x enterprise applications that you manually move to Version 5. See Migrate Web applications for more information on migrating your JSP pages to Version 5.

  • J2EE Security
    You can apply security in two Version 4.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 4.0.x to 5 as follows:

    • Version 4 settings:

      <key-file-name>dir_name/WASLDAPKeyring.jks</key-file-name>
      <trust-file-name>dir_name/WASLDAPKeyring.jks</trust-file-name>

      where dir_name is the directory where the WASLDAPKeyring.jks file was placed when it was created.

    • Version 5 settings:

      keyFileName="dir_name/WASLDAPKeyring.jks"   trustFileName="dir_name/WASLDAPKeyring.jks"

      where dir_name is the directory where the WASLDAPKeyring.jks file was placed when it was created.

    Also, the migration tools used by the installation wizard do not copy the key files (for examples, .jks, or .kdb) to the corresponding directory in the base WebSphere Application Server Version 5 product or the Network Deployment product. You must complete migration of the SSL configuration by copying qualifying key store files to Version 5 instance directories and modifying Version 5 SSL configuration data.

    Qualifying key store files are non product key files (i.e. key files you created) or product key files you modified by replacing the product certificates with ones you created or obtained from a commercial certificate authority. Copying product key files from Version 4 to Version 5 instances result in the Version 5 default product key files being overlaid.

    To complete migration of the SSL configuration:

    1. After migration has completed and before enabling security, manually copy qualifying key files to the corresponding directory under each Version 5 base product node and Network Deployment node in the configuration.
    2. Ensure *PUBLIC has *EXCLUDE authority and that the user profile your Version 5 application server runs under (QEJBSVR is the default user profile) has *RWX authority to the copied key files. For .kdb files, grant profile QTMHHTTP *RX authority.
    3. Use the Digital Certificate Manager (DCM) to restash the password if copying a qualifying .kdb file. Follow these steps to restash the password:

       1. Start Digital Certificate Manager.
       2. Click Select a Certificate Store.
       3. Select Other System Certificate Store.
       4. Click Continue.
       5. Enter the Certificate store path and filename.
       6. Enter the Certificate store password.
       7. Click Continue.
       8. In the navigation panel, click Manage Certificate Store.
       9. Select Change password.
       10. Click Continue.
       11. Enter and confirm a new password.
       12. Ensure that Automatic login is selected.
       13. Click Continue.

    4. The WASPostUpgrade tool creates one or more SSL repertoires in the Version 5 instance. The exact number of repertoires depends on how SSL is configured in the Version 4 instance. SSL repertoires must be edited to provide the correct location of the key files. The WASPostUpgrade tool populates the SSL repertoires in Version 5 instances with the Version 4 internal file system pathnames of the key files, hence pointing to the original key files in the Version 4 instances instead of the copies in the Version 5 instances. Ensuring the SSL repertoire information is correct is a required manual step. Incorrect SSL information may cause the server to fail, regardless of whether global security is enabled. Use the administrative console to edit the SSL repertoires.

       1. Login to the administrative console.
       2. Click Security --> SSL.
       3. For each SSL repertoire

          1. Click the repertoire to edit it.
          2. Edit the KeyFileName and TrustFileName fields as needed to point to the appropriate key file for the SSL repertoire. For example, when migrating the server1 instance from WebSphere Application Server Advanced Edition Version 4 to Version 5 in the KeyFileName field change /QIBM/UserData/WebASAdv4/default/etc/DummyServerKeyFile.jks to ${USER_INSTALL_ROOT}/etc/DummyServerKeyFile.jks. The server substitutes /QIBM/UserData/WebAS5/Base/default for ${USER_INSTALL_ROOT} at runtime.
          3. Click OK.

       4. Save the configuration (synchronize nodes for Network Deployment).
       5. Restart the server.

    See Migrate security configurations from previous releases in the Security topic for more information on migrating your security configurations to Version 5.

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

    If the Version 4 web.xml Web module file defines the InvokerServlet servlet, the migration tools update the class name to reflect the Version 5 package. The tools also set the ServeServletsByClassnameEnabled attribute to true.

    If the Version 4 web.xml Web module file defines the DefaultErrorReporter servlet, the migration tools update the class name to reflect the Version 5 package. See Migrate Web applications in the Application development topic for more information on migrating your servlets to Version 5.