Before you begin the process of migrating to WebSphere® Application Server Version 8.5, there are some considerations
of which you need to be aware.
Supported configurations: This
article is about configuration migration, such as migrating deployment
managers and federated nodes in a network deployment environment.
The Application Migration Toolkit for WebSphere Application Server
provides support for migrating applications from previous versions
of WebSphere Application Server to the latest product version. For
information about migrating applications, read more about the Application
Migration Toolkit.
sptcfg
Considerations for z/OS
Consider the following before migrating
Application Server 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
gotcha
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 8.5 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 8.5.
For more information,
see Deprecated, stabilized, superseded, and removed features.
- Before you migrate from WebSphere Application Server Version 6.1 or
above to Version 8.5, 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
6.1 and later.
See Core group migration considerations for core-group configuration and topology considerations that might
impact your migration from Version 6.1 or above to Version 8.5.
- 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 8.5 server on the same
logical partition (LPAR), the daemon procedure library for the Version 8.5 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 8.5 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 8.5 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.
- Before you migrate to Java Standard Edition (SE) Development Kit (JDK) 6 from JDK 5 or JDK
1.4 , review your applications for necessary changes based on the
Sun Microsystems Java specification. IBM® WebSphere SDK Java Technology Edition Version 6.0 is installed by default
with WebSphere Application Server Version 8.5. Optionally, you
can use the Installation Manager to install IBM WebSphere SDK Java Technology Edition
Version 7.0.
Avoid trouble: Do not enable SDK Java Technology Edition Version 7.0 unless all
nodes are migrated to
Version 8.5.
gotcha
See Migrating API and specifications for more information.
- When migrating a cell with multiple nodes, the applications must
remain at lowest JDK level until all nodes are migrated.
- The migration articles assume that WebSphere Application Server Version 8.5 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 8.5.
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 8.5 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
6.1 or above.
See Default port assignments for
default port information.
See Running multiple application server versions 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 8.5 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 8.5 migration converts
HTTP transports to channel-framework web container transport chains.
For more information on
WebSphere Application Server Version 8.5 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 8.5 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 6.1 or above 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 8.5. The Version 8.5 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 8.5, 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:
- After you migrate a base application server to WebSphere Application Server Version 8.5 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:
- 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.
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 8.5, 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 6.1 or
above, and verify that Version 8.5 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 8.5.
Beginning with
Version 6.1, certain security facilities are controlled using SAF
profiles.
- In Version 6.1 and 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 6.1 and 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 8.5.
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 information center 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.
- WebSphere Application Server Version 8.5 does not include
the WebSphere Connect
JDBC driver for SQL Server. The WebSphereConnectJDBCDriverConversion
tool is provided to convert data sources from the WebSphere Connect JDBC driver to the DataDirect
Connect JDBC driver or the Microsoft SQL Server JDBC driver.
Read Migrating from the WebSphere Connect JDBC driver 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 8.5.
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 8.5, 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
"sip" scheme 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 8.5, 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 8.5, 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.