- 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 have installed WebSphere Application Server for z/OS
Version 6.1, you might want to build a complete deployment cell configuration
and make sure that it works properly before you attempt to migrate
an existing cell or node.
This ensures that your system has all
of the necessary prerequisites and supports the new level of WebSphere
Application Server.
- Before you migrate from WebSphere Application Server Version 5.x
to Version 6.1, the application servant region ID should be connected
to a keyring and the keyring should have the WebSphereCA certificate
associated with it. Otherwise, you will see security errors if you
have Administrative Security turned on.
- Be sure to load the WebSphere Application Server Version 6.1 product
modules into the link pack area (LPA) and Link List on the system
where the migration must occur (that is, your existing WebSphere Application
Server Version 6.0.x or Version 5.1 system). On this same system you
can then restore the original configuration HFS of the "older" system
and build the WebSphere Application Server Version 6.1 configuration
zFS. Then you can run the appropriate migration job (BBOWMG1B, BOWMG2B,
BBOWMG3B, and so on.).
If the WebSphere Application Server Version
6.1 product modules are not loaded into LPA and Link List prior to
running the migration job, the job will not complete successfully.
- High availability manager and core group functionality are included
in WebSphere Application Server Version 6.0 and later.
- WebSphere Application Server Version 6.1 does not provide support
for migrating a WebSphere Application Server Version 5.x configuration
that contains an internal JMS provider.
The JMS applications must
be manually installed and reconfigured after migration to use the
WebSphere Application Server Version 6.1 JMS provider.
- If you are migrating from WebSphere Application Server for z/OS
Version 6.0.1 to Version 6.1 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 6.1.
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 for z/OS
Version 6.0.2.x to Version 6.1 and your configuration uses XA connections,
you must have Version 6.0.2.9 or later before migrating.
- If you are currently running your WebSphere Application Server
for z/OS Version 5.0.x node using STEPLIB, you must verify that profile_root/bin/setupCmdLine.sh contains
the STEPLIB of the load libraries.
Some Version 5.0.x nodes might
not contain the installation-generated STEPLIB statement. In these
instances, you must add the STEPLIB manually to the "OS/390)" section
of the
setupCMDLine.sh file before running the
migration utilities. Here is an example from a
setupCMDLine.sh file
in a properly configured system:
STEPLIB=BOSS.VICOM.W000020.SBBOLPA:$STEPLIB
STEPLIB=BOSS.VICOM.W000020.SBBOLD2:$STEPLIB
STEPLIB=BOSS.VICOM.W000020.SBBOLOAD:$STEPLIB
export STEPLIB
- If you plan on running a IIOP client that is earlier than Version
6.1 and it will be interacting with a Version 6.1 server on the same
LPAR, then the daemon procedure library for the Version 6.1 daemon
will need to include the earlier release's SBBOLD2 and SBBOLPA libraries
in its STEPLIB.
- Migration support requires that both the source and target WebSphere
Application Server for z/OS systems are on the same 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 6.1 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.
- WebSphere Application Server for z/OS 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 Customization Dialog or
z/OS Migration Management Tool and then submit them according to the
generated instructions.
- Before you migrate to JDK 5 (introduced in WebSphere Application
Server Version 6.1) from JDK 1.4 (introduced in Version 5.1) or JDK
1.3 (supported in Version 5.0.x) , review your applications for necessary
changes based on the Sun Microsystems Java specification.
See API and specification migration,
- When migrating a cell with multiple nodes, the applications must
remain at lowest JDK level until all nodes are migrated.
- The Web server plug-in configuration file (plugin-cfg.xml)
generated after successful migration from Version 5.x to Version 6.x
is topology centric—that is, it includes all the applications within
a cell. You cannot manage this cell-wide plug-in configuration file
from the administrative console until you have manually configured
it.
See Migrating Web server configurations,
- The migration articles assume that WebSphere Application Server
Version 6.1 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 6.1.
Prior levels of WebSphere Application Server
will continue to run at the higher prerequisite levels.
- Set up WebSphere Application Server for z/OS Version 6.1 to eliminate
potential LPA conflicts with a prior Version 5.x or 6.0.x installation.
WebSphere
Application Server Version 5.x, 6.0.x, and 6.1 require the placement
of some code into LPA (SBBOLPA). In addition, additional product code
(SBBOLOAD) should be placed into LPA for performance reasons. Because
of naming conflicts, however, more than one version of product code
can not be in LPA at the same time.
- Review the ports that have been defined to ensure that the WebSphere
Application Server Version 6.1 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 5.x or 6.0.x.
See Coexisting.
- Consider the following 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 6.1 while leaving others at the older release
level. This means that, for a period of time, you might be administering
servers that are at the current release and servers that are running
the newer release in the same cell.
Note that in this mixed-release
environment, there might be some restrictions on what you can do with
servers at the older release level. There might also be restrictions
on creating clusters and cluster members.
- WebSphere Application Server Version 5.0.x cannot coexist with
Version 6.0.x or Version 6.1 in the same cell on the same system image
(LPAR).
If you have multiple WebSphere Application Server Version
5.0.x nodes, including the deployment manager, on the same LPAR, all
nodes must be migrated to WebSphere Application Server Version 6.1
at the same time. All nodes must be migrated sequentially before starting
any WebSphere Application Server Version 6.1 node in the LPAR.
- A WebSphere Application Server Version 6.1 deployment cell can
contain mixed releases of Version 5.x or 6.0.x nodes, but there is
no mixed-node management support for Version 6.0.1.x.
The Version
6.1 migration tools still migrate these nodes during deployment-manager
migration, but they issue a warning message that the nodes cannot
be managed by the Version 6.1 deployment manager. You can then do
one of the following based on your needs.
- Upgrade all Version 6.0.1.x nodes to at least Version 6.0.2. This
will allow them to be administered by a Version 6.1 deployment manager.
- Immediately migrate these nodes to Version 6.1.
- During migration,
Version 6.1 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 6.1 cell to Version 6.0.2.11 or later before migrating
your deployment managers to Version 6.1.
- WebSphere Application Server Version 6.1 migration converts HTTP
transports to channel-framework Web container transport chains.
- Include maintenance considerations when developing your configuration
file system strategy.
If you configure your Network Deployment environment
using the default value for the product file system path in the Customization
Dialog, it will result in all the nodes pointing directly at the mount
point of the product file system. This makes rolling maintenance in
a nondisruptive manner 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; and 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 would allow you to update an
existing configuration 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 should be at least the size of
the previous version's configuration directory and applications plus
the size of the batch-job output from the migration.
Normally, 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 around 30 MB for this phase.
- Migrating to Version 6.1 might increase the Java virtual machine
(JVM) heap sizes for your servers on z/OS. The following heap sizes
are required in Version 6.1:
- Control region minheap must be at least 48 MB, and maxheap must
be no less than 256 MB.
- Servant minheap must be at least 256 MB, and maxheap must be no
less than 512 MB.
If your JVM heap sizes in the version that you are migrating
are lower than these required values, the migration process increases
them to the Version 6.1 minimum values.
- WebSphere Application Server Version 6.1 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 5.x or 6.0.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 6.1. The Version 6.1 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 6.1, the following events will
occur:
- When running the migration tools, you will 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 will be broken and you will 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 performing
one of the following tasks:
- After you migrate a base application server to WebSphere Application
Server for z/OS Version 6.1, 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.
- The WebSphere Application Server File System Owner user ID is
included in Websphere Application Server Version 6.1 and later. This
user ID has a default value of WSOWNER. In earlier versions of the
product, the configuration file system is owned by the WebSphere Application
Server Administrator user ID, which has a default value of WSADMIN.
- Before you migrate a Cloudscape database, ensure that any application
servers hosting applications that are using the Cloudscape database
are shut down. Otherwise, the Cloudscape migration will fail.
- After you use the migration tools to migrate to WebSphere Application
Server Version 6.1, you might need to do some things that are not
done automatically by the migration tools.
- Examine any Lightweight Third Party Authentication
(LTPA) security settings that you might have used in WebSphere Application
Server Version 5.x or 6.0.x, and make sure that Version 6.1 security
is set appropriately.
- If necessary, create new System Authorization Facility (SAF) profiles
before your migrated servers are started on WebSphere Application
Server for z/OS Version 6.1.
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 for z/OS runtime
to perform certain privileged operations on behalf of application
code, is required for all WebSphere Application Server for z/OS servers
that use the LocalOS registry or SAF authorization.
- In Version 6.1 and later, the Sync to OS Thread 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 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 should create the required SAF
profiles. If these profiles are not present and properly set up, a
cell using the LocalOS user registry or SAF authorization will fail
when brought up on Version 6.1.
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 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 it is set to 1, Enabled Trusted Applications is
enabled. If it 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 accomplish this:
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 (*).
- Check your MVS system log or use the administrative console to
determine whether or not Sync to OS Thread Allowed is enabled for
your server.
If it 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 accomplish
this:
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 (*).
Notes:
- 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.
- If you use SAF EJBROLE profiles for role-based authorization,
create EJBROLE profiles for the two administrative roles—the deployer
and adminsecuritymanager roles—that were introduced in Version 6.1.
- Review your Java virtual machine settings to verify that you are
using a heap size of at least 50 for improved startup performance.
If
you have used a smaller heap size in the past, you can use the default
heap size of 50.
- Verify the results of the automatic Cloudscape database migration,
and manually migrate any Cloudscape databases that are not automatically
migrated by the tools.
See Migrating Cloudscape databases.