- 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
- CLOUDSCAPE_JDBC_DRIVER_PATH
- 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 honor a an application install 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 honor the install path without the need to enter it again. If the
install path for the previous release contains variable references,
Application Server will resolve those variables with the migrated
values.
- After you install WebSphere Application Server Version 8.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 8.0.
For more information,
read the "Deprecated and removed features" article in the information
center.
- Before you migrate from WebSphere Application Server Version 6.x to Version 8.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
6.0 and later.
Read the "Core group migration considerations" article
in the information center for core-group configuration and topology
considerations that might impact your migration from Version 6.x to Version 8.0.
- If you are migrating from WebSphere Application Server Version 6.0.1
to Version 8.0 and security
is enabled for Version 6.0.1, you must upgrade to service level 6.0.2.12
or later before migrating to Version 8.0.
If security is
not enabled for WebSphere Application Server Version
6.0.1, this requirement does not apply and there is no specific service-level
requirement for the migration.
- If you are migrating from WebSphere Application Server Version 6.0.2.x
to Version 8.0 and your configuration
uses XA connections, you must have Version 6.0.2.9 or later before
migrating.
- 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.0 server on the same
logical partition (LPAR), the daemon procedure library for the Version 8.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 systems 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.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, read 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.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.
- 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.
Read 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.0 is being installed
in an environment where it must coexist with prior levels 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.0.
Prior levels
of WebSphere Application Server continue
to run aWebSphere Application Servert the
higher prerequisite levels.
- Review the ports that have been defined to ensure that the WebSphere Application Server Version 8.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
6.x.
Read the "Default port assignments" article in the information
center for default port information.
Read 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.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,
read the "Creating application servers" article in the information
center. Restrictions on creating clusters and cluster members might
also exist. For details, read the "Creating clusters" article in the
information center.
- A WebSphere Application Server Version 8.0 WebSphere Application Server, Network Deployment cell can contain
mixed releases of Version 6.x nodes; however, there is no mixed-node
management support for Version 6.0.1.x.
The
Version 8.0 migration tools still
migrate these nodes during deployment-manager migration; however,
these tools issue a warning message that the nodes cannot be managed
by the
Version 8.0 deployment
manager. You can then perform one of the following actions based on
your needs.
- Upgrade all Version 6.0.1.x nodes to at least Version 6.0.2. This
upgrade allows them to be administered by a Version 8.0 deployment manager.
- Migrate these nodes to Version 8.0.
- During migration, Version 8.0 cluster
information is distributed throughout the cell. Version 6.0.x nodes
that are not at Version 6.0.2.11 or later fail to read this information
and the cluster function might fail. Therefore, upgrade all Version
6.0.x nodes that will be contained in or interoperating with a Version 8.0 cell to Version 6.0.2.11
or later before migrating your deployment managers to Version 8.0.
- WebSphere Application Server Version 8.0 migration converts
HTTP transports to channel-framework web container transport chains.
For
more information on
WebSphere Application Server Version 8.0 transport support,
read the following articles in the information center:
- 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.
Read
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. Read 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.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 6.x 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.0. The Version 8.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 8.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:
- After you migrate a base application server to WebSphere Application Server Version 8.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 IBM Cloudscape
or 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.
Read the "Security domains in a mixed-version environment"
section of the "Multiple security domains" article in the information
center.
- Modifications to the java.security file are lost during migration.
If you've updated your java.security file in the previous version
of WebSphere Application Server, the new version will not have your
updates. For example, if you modified your provider list to use FIPS
or Hardware crypto, your migrated cell will not use these providers,
and therefore will not use FIPS or Hardware Crypto. To migrate your
modified java.security file, use the following steps:
- Before migrating, copy the java.security file from the old WAS_HOME/java/lib/security to
a temporary directory.
- Migrate WebSphere Application Server to Version 8.0.
- Compare the old java.security file with the new Version 8.0 java.security
file that is located in V8WAS_HOME/properties/java.security.
- Update V8WAS_HOME/properties/java.security with
changes to the provider list from the old java.security file.
- Repeat this procedure for each installation of WebSphere Application
Server.
- After you use the migration tools to migrate to WebSphere Application Server Version 8.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 6.x, and
verify that Version 8.0 security
is set appropriately.
Read the "Lightweight Third Party Authentication"
article in the information center for more information.
- If necessary, create new System Authorization Facility (SAF) profiles
before you start your migrated servers on WebSphere Application Server Version 8.
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.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, read the "System Authorization Facility
classes and profiles" article in the information center.
- 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, read the "Application Synch to
OS Thread Allowed" article in the information center.
- 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 IBM Cloudscape or Apache Derby databases for
more information.
- WebSphere Application Server Version 8.0 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.
- During cell migrations to Version 8.0, the Version 6.0.x
server user ID is not migrated or mapped to the Version 8.0 Primary administrative
user name field as shown in the administrative console at Security >
Global security > user_account_repository >
Configure. The server user identity value is transferred, and
the proper user ID from the Version 6.0.x cell is migrated along with
a password.
The primary administrative user name is required when
defining Lightweight Directory Access Protocol (LDAP) as the security
repository in Version 8.0.
The Primary
administrative user name field and server user identity value
are used by the product when you use administrative scripts (wsadmin)
to update the configuration. Version 6.0.x and earlier versions of
the product store a valid username-and-password pair in the authenticating
registry inside the local product configuration files. Beginning with
Version 6.1, an administrative user ID can be set but the authentication
information is not stored in the local product configuration files
(thereby improving security).
If you migrate from an older release
of the product to Version 6.1 or later, the old model is still used
in order to maintain backward compatibility and to allow the mixed
cell to function properly. When you are ready to upgrade to the new
model, which requires that all nodes in the cell be at Version 6.1.x
or later, you can perform the following actions:
- Input a Primary administrative user name that represents a valid
user identity in the authentication authority (user registry).
- Change the server user identity value from Server identity
that is stored in the repository to Automatically generated
server identity.
If you are still using a mixed cell in Version 8.0 that contains Version
6.0.x nodes, you must continue to use the old model or the older nodes
will not be able to communicate with the new nodes. You should not
make any changes to the security settings in the mixed cell. If editing
the user registry becomes necessary in a mixed cell that is not ready
to be upgraded to the new model, however, select a valid user identity
in the authentication authority (user registry) and put that value
into the Primary administrative user name field but do not change
the value of the server user identity. On all platforms, it is important
to select a user ID that is valid for the scripting tools (wsadmin).
- 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.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
8.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 "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.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 8.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.