Migration configuration mapping

This topic describes how the migration tools map the configuration from the previous release to Version 6.0 for the basic migration scenario. The basic migration scenario involves migrating a single WebSphere Application Server Version 4, Version 5.0.x, Version 5.1.x, Version 5.0.x Express, or Version 5.1.x Express instance to a WebSphere Application Server Version 6.0 profile 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 6.0 environment.

• Stdin, stdout, stderr, passivation and working directories
  The location for these directories is typically the logs directory under the WebSphere Application Server profile directory. For example in Version 4 Advanced Edition, the logs directory for the default instance is /QIBM/UserData/WebASAdv4/default/logs. For Version 6.0, the default location for stdin, stdout, and stderr is still the logs directory located under the WebSphere Application Server profile directory. For example, the logs directory for the default profile is /QIBM/UserData/WebSphere/AppServer/V6/Base/profiles/default/logs.

  The migration tools attempt to migrate existing passivation and working directories. Otherwise, appropriate Version 6.0 defaults are used. For more information on passivation directories, see the topic EJB container settings. For more information on working directories, see the topic Process definition settings.

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

• Property files from Version 4.0.x
  Migration does migrate property files from Version 4.0.x if they are also present in Version 6.0. Specifically, property file migration includes the following files:
  • converter.properties
  • encoding.properties
  • sas.client.properties
  • TraceSettings.properties

  You must manually convert settings in other property files to the Version 6.0 equivalent property file settings.

• Property files from Version 5.x and Version 5.x Express
  Migration migrates all property files that are installed with Version 6.0 by merging settings into the Version 5.x property files. Migration does not overlay property files.

• 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 6.0 configuration either does not exist, has different meaning, or has different scope. For information on how to change the process definition settings, see the topic Process definition. For information on how to change the Java virtual machine settings, see the topic Java virtual machine.

• Bootstrap port
  If the administrative server for your 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 6.0 profile. Also if the application server name of the Version 4 instance matches the Version 6.0 profile, the port number remains unchanged from the value of the name service port used when the Version 6.0 profile 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 6.0 profile. 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 6.0. The bootstrap port is specified in the admin.properties file located in the properties file WebSphere Application Server 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 4.0.x is Default Server. The name of the default server in Version 6.0 is server1. Thus, the Default Server in Version 4.0.x is migrated to the server1 server in Version 6.0.

• JDBC drivers and datasources
  The JDBC connection manager from Version 4 is still provided as a configuration option in Version 6.0. Using this configuration option enables Version 4.0.x J2EE 1.2 applications to run unaltered. If you migrate a Version 4.0.x application to Version 6.0 using the Version 6.0 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. EJB 2.0 modules are migrated to use the Version 6.0 JDBC connection manager.

• Name bindings
  When migrating from Version 4.0.x, there is a new namespace structure in Version 6.0. Enterprise bean references in Version 6.0 are incompatible with the references that are expected by application components such as servlets or enterprise beans running in Version 4. This only affects topologies where applications running in previous WebSphere Application Releases must access enterprise beans running in Version 6.0. This does not impact topologies where all application components are running in Version 6.0.
  The following instructions describe how to externalize the EJB in Version 6.0 so that a Version 4 application component can access it:
  1. Start the Version 6.0 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 4.0.x.
  7. Click OK.

  8. Save your changes.

• Node name
  A 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 6.0. 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.0.

  You can also use the Assembly Toolkit (ATK) 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 Assembly Toolkit (ATK) to correct the error, by moving the usage or extension to your migrated EAR file:

  1. Start the ATK, 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. The PageList Extensions appear.
  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 6.0, see Web applications: WebSphere Application Server.

• Properties directory, classes directory, and lib/app directory
  Migration does copy files from prior version directories into the Version 6.0 configuration. See Property files from Version 4.0.x and Property files from Version 5.x and Version 5.x Express for more information on how the contents of the properties directory are migrated.

• Samples
  There is no migration of samples from previous versions. There are equivalent Version 6.0 samples that you can use. The samples are not preinstalled. See Samples and applications 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 6.0 environment. This is because Java 2 Security is enabled by default when you enable security in Version 6.0. 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 6.0. 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 6.0 properties directory to enterprise applications as they are being migrated. The migration tools perform this task while moving Version 4 applications into Version 6.0.

  Global security that uses LTPA authentication in Version 4.0.x is migrated to the base WebSphere Application Server product. However, although global security was enabled in Version 4.0.x, it is disabled during and after migration to Version 6.0. 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 6.0 administrative console. There is no migration of Version 4.x property values to the Version 6.0 settings.

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

  Use the Version 6.0 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 6.0, see Migrate security configurations from previous releases.

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

• 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. 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.

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

• Web modules
  The Version 6.0 level of J2EE requires Web container behavior changes in regard to setting content type if you are migrating from Version 4.0.x. If a default servlet writer does not set the content type, not only does the Version 6.0 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 6.0, see Web applications: WebSphere Application Server.

• Migration of Version 4.0.x nodes to a Version 6.0 node after federation
  You cannot migrate a Version 4.0.x instance to a Version 6.0 profile after the 6.0 application server node has been federated into a deployment manager cell. The master copy of the configuration no longer resides on the Version 6.0 application node. There is a master configuration on the deployment manager cell. You can perform the migration by removing the 6.0 application server node from the cell, migrating, refederating the node into the cell. As the node is federated, the deployment manager copies the migrated configuration that it maintains for the application server node.

• Migration of Version 5.x nodes to a Version 6.0 node after federation
  You can migrate a Version 5.x node that belongs to a cell without removing the Version 6.0 node from the cell. Migrate the deployment manager first before migrating any base nodes in the cell. After migrating the deployment manager node, do not use the Version 5.x deployment manager node. Migrating a base Version 5.x node that is within a Version 6.0 cell also migrates the node agent to Version 6.0. A cell can have some Version 6.0 nodes and other nodes that are at Version 5.x levels.

• Version 4 to Version 6.0 migration
  The Version 4.0.x configuration is already at the J2EE 1.2 level. Although Version 6.0 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 for more information on migrating your enterprise beans to Version 6.0.

  • JMS Resources
    All JMS resources from Version 4 are mapped into generic JMS resources in the Version 6.0 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. All JMS resources from Version 5.x are mapped into the same JMS provider in Version 6.0. No manual configuration is required. See Migrating from version 5 embedded messaging for more information on migrating your applications that use JMS to Version 6.0.

  • 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 6.0, 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 6.0, 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 6.0. See Web applications: WebSphere Application Server for more information on migrating your JSP pages to Version 6.0.

  • 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 6.0 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 6.0 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 6.0 product or the Network Deployment product. You must complete migration of the SSL configuration by copying qualifying key store files to Version 6.0 profile directories and modifying Version 6.0 SSL configuration data.

    Qualifying key store files are non product key files (for example, 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 6.0 profiles result in the Version 6.0 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 6.0 base product node and Network Deployment node in the configuration.
    2. Ensure *PUBLIC has *EXCLUDE authority and that the user profile your Version 6.0 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 6.0 profile. 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 6.0 profiles 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 6.0 profiles. 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 6.0 in the KeyFileName field change /QIBM/UserData/WebASAdv4/default/etc/DummyServerKeyFile.jks to profile_root/etc/DummyServerKeyFile.jks.
          3. Click OK.
       4. Save the configuration (synchronize nodes for Network Deployment).
       5. Restart the server.

    See Migrate security configurations from previous releases for more information on migrating your security configurations to Version 6.0.

  • Servlet package name changes when migrating from Version 4 to Version 6.0
    If the Version 4 web.xml Web module file defines the SimpleFileServlet servlet, the migration tools update the class name to reflect the Version 6.0 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 6.0 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 6.0 package. See Web applications: WebSphere Application Server for more information on migrating your servlets to Version 6.0.