Migration considerations

Considerations for z/OS

• The migration progress usually carries forward the values for user-defined variables or variables that are defined by Application Server. There are some special variables, however, for which the values are not carried forward. These values are:
  • WAS_INSTALL_ROOT
  • USER_INSTALL_ROOT
  • WAS_PRODUCT_ROOT
  • WAS_LIBS_DIR
  • WAS_PROPS_DIR
  • WAS_TEMP_DIR
  • APP_INSTALL_ROOT
  • DRIVER_PATH
  • WAS_INSTALL_LIBRARY
  • JAVA_HOME
  • DEPLOY_TOOL_ROOT
  • CONNECTOR_INSTALL_ROOT
  • TRANLOG_ROOT
  • MQJMS_LIB_ROOT
  • WAS_ETC_DIR
  • WEMPS_USER_ROOT
  • MQ_INSTALL_ROOT
  • WAS_DAEMON_ONLY_ICU_DATA
  • WAS_DAEMON_ONLY_CONFIG_ROOT
  • WAS_DAEMON_primordial_root
  • WAS_DAEMON_daemon_was_env_file
  The values for the these variables are picked up from the profile template when migration creates profiles. If you defined custom values for these variables, they are not maintained in the Application Server release to which you are migrating. These variables are not migrated, because they are Application Server properties that are profile attributes. If you need to override their values with entries that are not the default, you must change the value outside of the product install, profile creation, and migration processes.

  Avoid trouble: Be particularly aware of the APP_INSTALL_ROOT variable. Even if the APP_INSTALL_ROOT had a custom location that you defined, by default the migration process will install applications in the following location:

  ${USER_INSTALL_ROOT}/installedApps

  To have the migration process use an application installation location that is not the default:

  • Specify the location in the Application Install Directory field of zMMT.
  • Select the Migrate applications and use the previous application installation directory option during migration to use the installation path without the need to enter it again. If the installation path for the previous release contains variable references, the Application Server will resolve those variables with the migrated values.
• After you install WebSphere Application Server Version 9.0 on the z/OS operating system, you might want to build a complete WebSphere Application Server Network Deployment cell configuration and verify that it works correctly before you attempt to migrate an existing cell or node.

  This process ensures that your system has all of the necessary prerequisites and supports the new level of the product.

• Before you perform the migration, evaluate the items deprecated in WebSphere Application Server Version 9.0.

  For more information, see Deprecated, stabilized, superseded, and removed features.

• Before you migrate from WebSphere Application Server Version 7.0 or later to Version 9.0, connect the application servant region ID to a keyring and verify that the keyring has the WebSphereCA certificate associated with it. Otherwise, security errors occur if you have global security turned on.
• High availability manager and core group functionality are included in WebSphere Application Server Version 7.0 or later .

  See Core group migration considerations for core-group configuration and topology considerations that might impact your migration from Version 7.0 or later to Version 9.0.

• If you plan on running an Internet Inter-ORB Protocol (IIOP) client that is earlier than Version 6.1 and it will be interacting with a Version 9.0 server on the same logical partition (LPAR), the daemon procedure library for the Version 9.0 daemon must include the earlier release's SBBOLD2 and SBBOLPA libraries in its STEPLIB.
• Migration support requires that both the source and target WebSphere Application Server configurations be on the LPAR.

  Therefore, you cannot migrate an existing configuration to a different z/OS LPAR. You also cannot migrate to or from a non-z/OS operating system using the WebSphere Application Server Version 9.0 migration utilities.

• Migrating cells that span Sysplex environments or operating systems should not present any unique migration issues. You migrate at the node level, and you use the tools provided based on the platform of the node that you are migrating.

  For information on setting up a mixed-platform cell, see the WebSphere for z/OS -- Heterogeneous Cells white paper.

• WebSphere Application Server on the z/OS operating system does not support the WASPreUpgrade, WASPostUpgrade, and manageprofiles command-line tools that are supported by the distributed and i5/OS versions of the product.

  You must generate the migration jobs using the z/OS Migration Management Tool or the zmmt command and then submit them according to the generated instructions.

• The amount of storage that your system requires during migration to Version 9.0 depends on your environment.
  • The size of the file system is provided by the value of the primary allocation in cylinders specified in the z/OS Migration Management Tool or the zmmt command when you generate a migration definition. In addition, this file system is automatically expandable based on the secondary allocation that you specify. The default values provided for these allocations by the migration tools is normally sufficient for the configuration data.
  • The migration backup directory requires a considerable amount of temporary space. The exact amount needed depends on several factors, but 100 cylinders is sufficient in most situations (including tracing if needed). If you are in doubt about the space available for your temporary directory, use the option in the z/OS Migration Management Tool or the zmmt command to move the temporary directory to a custom location with more space and mount your own temporary file system there. Failure to have adequate temporary space can lead to a premature end to the migration process.
• IBM® SDK, Java™ Technology Edition, Version 8 is the default SDK version for WebSphere Application Server Version 9.0. .
  Avoid trouble: Do not enable SDK, Java Technology Edition, Version 8 unless all nodes are migrated to Version 9.0.

  See Migrating API and specifications for more information.

• When migrating a cell with multiple nodes, the applications must remain at lowest Java SDK level until all nodes are migrated.
• The migration articles assume that WebSphere Application Server Version 9.0 is being installed in an environment where it must coexist with previous versions of WebSphere Application Server.
  Consider the following items while planning to enable coexistence:

  • Update prerequisites to the levels required by WebSphere Application Server Version 9.0.

    Previous versions of WebSphere Application Server continue to run at higher prerequisite levels.

  • Review the ports that have been defined to ensure that the WebSphere Application Server Version 9.0 installation does not conflict.

    In particular, note that the default daemon port definition for both versions is the same when installing to coexist with WebSphere Application Server Version 7.0 or later .

    See Default port assignments for default port information.

  See Running coexisting application servers for more information.

• Consider the following information if you are planning to have any mixed-release cells:
  • You can upgrade a portion of the nodes in a cell to WebSphere Application Server Version 9.0 while leaving others at the previous release level. This means that, for a period of time, you might be administering servers that are at the previous release level and servers that are running the newer release in the same cell.

    In this mixed-release environment, some restrictions on what you can do with servers at the previous release level might exist. For details, see Creating application servers. Restrictions on creating clusters and cluster members might also exist. For details, see Creating clusters.

• WebSphere Application Server Version 9.0 migration converts HTTP transports to channel-framework web container transport chains.
  For more information on WebSphere Application Server Version 9.0 transport support, see the information:

  • Configuring transport chains
  • HTTP transport channel settings
  • Transport chains
• Include maintenance considerations when developing your configuration file system strategy.

  If you configure your WebSphere Application Server Network Deployment environment using the default value for the product file system path in the z/OS Migration Management Tool, all the nodes point directly at the mount point of the product file system. This configuration makes rolling maintenance in a nondisruptive way almost impossible. If a cell is configured in this way, applying service to the product file system affects all the nodes at the same time. If multiple cells are configured in this way, applying service to the product file system affects all the cells at the same time.

  You might want to specify what is referred to as an intermediate symbolic link between each node's configuration file system and the actual mount point of the product file system. This strategy is described in the WebSphere Application Server for z/OS V5 - Planning for Test, Production and Maintenance white paper.

  See the Washington Systems Center Sample WebSphere for z/OS ND Configuration white paper for more information about this issue and its relationship to applying maintenance. See the WebSphere for z/OS: Updating an Existing Configuration HFS to Use Intermediate Symbolic Links instructions for information on obtaining and using a utility that you can use to update an existing configuration Hierarchical Hile System (HFS) to use intermediate symbolic links.

• The migration tools create a migration backup directory containing a backup copy of the configuration from the previous version. The space available for this directory must be at least the size of the configuration directory and applications from the previous version plus the size of the batch-job output from the migration.

  Typically, the batch-job output from the migration is very small unless you enable trace. The trace output size varies depending on the parts of migration for which you have enabled trace. The largest trace producer is the WASPostUpgrade phase of migration. You can typically see trace output of approximately 30 MB for this phase.

• WebSphere Application Server Version 9.0 does not support the DB2® for zOS Local JDBC Provider (RRS).

  If you use the DB2 for zOS Local JDBC Provider (RRS) in the Version 7.0 or later configuration that you are going to migrate, you must change your configuration to use the DB2 Universal JDBC Driver Provider before or immediately after you migrate to Version 9.0. The Version 9.0 migration tools do not migrate the provider for you.

  If you use the DB2 for zOS Local JDBC Provider (RRS) in the version to be migrated and do not change your configuration to use the DB2 Universal JDBC Driver Provider before migrating to Version 9.0, the following events occur:

  • When running the migration tools, you receive the following message:

    MIGR0442W: Not migrating DB2 for zOS Local JDBC Provider (RRS) jdbc provider. 
    Manually create a DB2 Universal Driver provider as a replacement. See DB2 
    documentation for further details.

  • After migration, DB2 access is broken and you receive the following runtime message:

    DSRA8213W: JDBC provider, DB2 for zOS Local JDBC Provider (RRS), is no longer 
    supported by WebSphere Application Server. Applications should use DB2 Universal 
    JDBC Driver Provider Type 2.

  If you determine that you must change your configuration to use the DB2 Universal JDBC Driver Provider, you can do so by completing one of the following tasks:

  • Before migrating to Version 9.0, change your Version 7.0 or later configuration to use the DB2 Universal JDBC Driver Provider.

    If you do this, the Version 9.0 migration tools handle the migration to the DB2 Universal JDBC Driver Provider and no post-migration activity id required.

    Perform one of the following actions:

    • Manually change your configuration to use the DB2 Universal JDBC Driver Provider.
    • If you are migrating from Version 7.0 or later, use the JDBC Migration Utility for DB2 on z/OS to migrate from the DB2 for zOS Local JDBC Provider (RRS) to the DB2 Universal JDBC Driver Provider.

      This tool is a script that migrates DB2 for zOS Local JDBC Providers (RRS) to DB2 Universal JDBC Driver Providers one node at a time. A white paper that accompanies the tool explains how to install and configure the DB2 Universal JDBC Driver before running the tool to migrate your configuration.

  • After migrating to Version 9.0, perform one of the following actions:
    • Manually change your configuration to use the DB2 Universal JDBC Driver Provider.
    • Use the JDBC Migration Utility for DB2 on z/OS to migrate from the DB2 for zOS Local JDBC Provider (RRS) to the DB2 Universal JDBC Driver Provider.

      This tool is a script that migrates DB2 for zOS Local JDBC Providers (RRS) to DB2 Universal JDBC Driver Providers one node at a time.

• After you migrate a base application server to WebSphere Application Server Version 9.0 running on the z/OS operating system, the administrative and user applications continue to be defined under the virtual host default_host as they were in the previous release. However, a migrated deployment manager is defined under the virtual host admin_host that was introduced in Version 6.1.
• If you use isolated data repositories—specifically, nonshared data repositories such as transaction logs for SIB and Apache Derby databases—and you migrate from a previous release, your existing databases and transaction logs are saved. If you have mission-critical information that is stored in these local data repositories, you should safely shut down all servers that interact with those repositories before attempting migration. Those servers should remain offline until the migration has been successfully completed or rolled back.

  After the migration is complete or you have rolled back to the previous version, you can restart the servers that interact with these isolated data repositories.

• Before you migrate an Apache Derby database, ensure that any application servers hosting applications that are using the Apache Derby database are closed. Otherwise, the Apache Derby migration fails.
• You should be aware of the following rules related to migrating security domains:
  • If you migrate a deployment manager that has a security domain with a cell-level scope, the migration tools take the following actions:
    • Migration creates a domain in the new configuration called PassThroughToGlobalSecurity if it does not already exist.
    • Migration adds a cluster mapping to the new configuration for all clusters that existed in the old configuration.
      • Clusters that only existed in the Version 9.0 deployment-manager configuration before migration do not have their mappings to PassThroughToGlobalSecurity changed.
        • If mappings for the Version 9.0 clusters exist before migration, they still exist after migration.
        • If no mappings for the Version 9.0 clusters exist before migration, they still do not exist after migration.
      • If a cluster exists in both the previous configuration and the Version 9.0 configuration before migration, the cluster in the new configuration is added to the PassThroughToGlobalSecurity domain and behaves like the cluster in the previous release.
    • Migration adds a bus mapping for any busses that exist in a migrated Version 6.1.x configuration.

      Bus mappings are updated following the same rules as those for cluster mapping.

    • Administrative servers (deployment manager) are not added to the PassThroughToGlobalSecurity domain.
  • If you migrate a federated node that has a security domain with a cell-level scope, the migration tools take the following actions:
    • Migration creates a domain in the new configuration called PassThroughToGlobalSecurity if it does not already exist.
    • Migration adds a server-level mapping to the PassThroughToGlobalSecurity domain for all non-clustered servers in the old node's configuration.
      • Servers on the node that is being migrated that are part of a cluster do not receive entries in the PassThroughToGlobalSecurity domain because this was addressed through a cluster mapping during deployment-manager migration.

        If you have removed that mapping, migration maintains that behavior.

      • Administrative servers (node agents) are not added to the PassThroughToGlobalSecurity domain.

  For more information, see the Security domains in a mixed-version environment section of Multiple security domains.

• If you updated your java.security file in the previous version of WebSphere Application Server, ensure that your updates are located in the migrated java.security file, which is located in V8WAS_HOME/properties/java.security.
• After you use the migration tools to migrate to WebSphere Application Server Version 9.0, you might need to perform some actions that are not performed automatically by the migration tools.
  • Examine any Lightweight Third-Party Authentication (LTPA) security settings that you might have used in WebSphere Application Server Version 7.0 or later, and verify that Version 9.0 security is set appropriately.

    See Lightweight Third Party Authentication for more information.

  • If necessary, create new System Authorization Facility (SAF) profiles before you start your migrated servers on WebSphere Application Server Version 9.0.
    Beginning with Version 6.1, certain security facilities are controlled using SAF profiles.

    • In Version 7.0 or later, the Enabling trusted applications setting is controlled with a SAF security profile instead of an internal WebSphere variable as in previous releases.

      The Enabling trusted applications option, which permits the WebSphere Application Server run time to perform certain privileged operations on behalf of application code, is required for all servers that use the LocalOS registry or SAF authorization.

    • In Version 7.0 or later, the Sync to OS thread allowed feature (which allows an application to access resources using an operating system identity other than the server identity) is controlled with a SAF security profile and the com.ibm.websphere.security.SyncToOSThread variable.

      This implementation allows both the administrator and the system security administrator to determine whether or not the feature is used. This implementation also allows restrictions on which identities the application can assume.

    If you migrate from a previous version of WebSphere Application Server and need these features, you must create the required SAF profiles. If these profiles are not present and correctly set up, a cell using the LocalOS user registry or SAF authorization fails when started on Version 9.0.

    If you use Resource Access Control Facility (RACF®) for your security system, use the following instructions. If you use another SAF-compliant security system, contact the security system vendor for appropriate information.

    • Check your Multiple Virtual Storage (MVS™) system log or use the administrative console to determine whether or not Enable trusted applications is enabled for your server.
      Look for control_region_security_enable_trusted_applications in the startup log. If this value is set to 1, Enabled trusted applications is enabled. If this option is enabled, create the following SAF profile and grant READ access to the application server control region user ID:

      BBO.TRUSTEDAPPS.cell_shortname.cluster_transition_name 

      Use the following RACF commands to complete this action:

      RDEFINE FACILITY
        BBO.TRUSTEDAPPS.cell_shortname.cluster_transition_name 
        UACC(NONE)
      PERMIT FACILITY
        BBO.TRUSTEDAPPS.cell_shortname.cluster_transition_name
        ID(controller_userid) ACCESS(READ)
      SETROPTS RACLIST(FACILITY) REFRESH

      The cluster_name SAF facility profile is replaced by the cluster transition name for unclustered servers. If you want all servers in the cell to have Enabling trusted applications enabled, replace the cluster name with a wild card (*).

      For more information, see System Authorization Facility classes and profiles.

    • Check your Multiple Virtual Storage (MVS) system log or use the administrative console to determine whether or not Sync to OS thread allowed is enabled for your server.
      If this option is enabled, create the following SAF profile and grant either READ or CONTROL access to the application server control region user ID:

      BBO.SYNC.cell_shortname.cluster_transition_name

      The following example contains RACF commands that you might use to complete this action:

      RDEFINE FACILITY 
        BBO.SYNC.cell_shortname.cluster_transition_name
        UACC(NONE) 
      PERMIT FACILITY 
      BBO.SYNC.cell_shortname.cluster_transition_name
        ID(controller_userid) ACCESS(CONTROL)
      SETROPTS RACLIST(FACILITY) REFRESH
      

      The cluster name is replaced by the cluster transition name for unclustered servers. If you want all servers in the cell to have Sync to OS thread allowed enabled, replace the cluster name with a wild card (*).

      Important:

      • Granting the control region READ access to the application server control region user ID restricts the user IDs to which the thread identity can be changed based on SAF SURROGAT profiles.

        If the controller user ID has READ access to the BBO.SYNC profile and the com.ibm.websphere.security.SyncToOSThread variable is set to true, an application might request Sync to the OS Thread. The application might assume the identity of either the caller or a role-related user ID to access resources. In order for the servant to run with a different application ID, however, the servant needs READ access to the SURROGAT profile BBO.SYNC.application_userid.

      • Granting the control region CONTROL access to the application server control region user ID allows the thread identity to be switched to any user ID that requests Sync to OS thread.

        If the controller user ID has CONTROL access to the BBO.SYNC profile and the com.ibm.websphere.security.SyncToOSThread variable is set to true, then an application might request Sync to OS Thread. The application might assume the identity of either the caller or any role-related user ID to access resources. SURROGAT profiles are not checked.

      For more information, see Application Synch to OS Thread Allowed.

  • If you use SAF EJBROLE profiles for role-based authorization, create EJBROLE profiles for the two administrative roles—the deployer and admin security manager roles—that were introduced in Version 6.1.
  • Review your Java Virtual Machine (JVM) settings to verify that you are using a heap size of at least 50 for improved startup performance.

    Read the Java virtual machine settings article in the documentation for more information.

    If you have used a smaller heap size before, you can use the default heap size of 50.

  • Verify the results of the automatic Apache Derby database migration, and manually migrate any Apache Derby databases that are not automatically migrated by the tools.

    Read Migrating Apache Derby databases for more information.

  • If you have multiple node agents on the same logical partition (LPAR), IPC_CONNECTOR_ADDRESS port conflicts might exist after running the migration jobs. Reconfigure the conflicting ports.
  • If you have applications that attempt to send a request to a Session Initiation Protocol (SIP) Uniform Resource Identifier (URI) over Transport Layer Security (TLS), you should be aware of a difference in behavior between WebSphere Application Server Version 6.1 and Version 9.0.

    When a SIP application sends a request to a SIP URI over TLS in Version 6.1, the request URI scheme changes from sip to sips. In Version 9.0, the scheme remains without a change.

    This difference is seen when your applications attempt to send a SIP request in which the request URI contains a sipscheme and a tls transport parameter. For example, if an application in Version 6.1 creates a request with the following request URI:

    sip:alice@atlanta.com;transport=tls

    and sends it to the network, the SIP container changes both the scheme and the transport parameter to produce the following request URI:

    sips:alice@atlanta.com;transport=tcp

    In Version 9.0, the SIP container does not change the scheme.

    If you want to retain the old behavior after migrating the Version 6.1 application server to Version 9.0, change the application code. If the application intends to send a sips URI, it should create the URI that way before requesting to send out the message. With a sips URI, the behavior remains the same as in Version 6.1.