Upgrading WebLogic Application Environments

Upgrading a WebLogic Domain

If you have created a WebLogic domain that is compatible with WebLogic Server 6.1, 7.0, or 8.1, you can use the WebLogic Upgrade Wizard to upgrade the domain for a WebLogic Server 9.1 application environment.

The following sections describe how to use the WebLogic Upgrade Wizard for this purpose:

What Happens During a WebLogic Domain Upgrade?

During a WebLogic domain upgrade, you specify the domain that you wish to upgrade and respond to a set of prompts. The WebLogic Upgrade Wizard performs the following tasks:

Optionally, the wizard backs up the original domain directory.

If a backup is requested, the wizard backs up the domain directory only, and it does not preserve file permissions. BEA recommends that you back up the domain, any external applications, and application database resources in a separate process, as described in Step 2: Back Up the Application Environment.

Note: Backup files created by the wizard need to be protected by the user as they may contain confidential information.

Recreates scripts, such as startup and shutdown scripts, and renames any original scripts as orig-scriptname.bak, where orig-scriptname specifies the original script name and extension.

Note: The wizard does not copy any customizations in the original startup scripts to the new scripts. For example, if you specified a non-default value for the JAVA_OPTIONS environment variable in the original script, the specified value will not be preserved in the new script.

Restructures the original domain, creating a new directory structure and moving domain components to new locations.

During the restructuring, if a required directory already exists, the wizard simply keeps that directory and maintains the files and subdirectories that reside in it.
Existing server log files are copied to the servers/server_name/logs/pre-90-logs directory in the domain, where server_name specifies the name of the server.
To review changes to the domain directory structure, see WebLogic Domain Directory Structure Enhancements.

Upgrades the persisted configuration information stored in the configuration file (config.xml) to the config directory.

If the wizard encounters duplicate resources when upgrading the configuration file (config.xml), a message is logged in the progress window. In this case, the last resource definition encountered is used during the conversion.

Upgrades persisted data, such as JMS file stores, JMS JDBC stores, and transaction stores.

Note: If JMS JDBC stores are used in the domain, see Step 5: Set Up the Environment.

After the JMS JDBC stores are upgraded, the original JMS JDBC stores are not deleted. You should take this fact into account when performing capacity planning. You can delete the original JMS JDBC store tables once the upgrade is successful. Original JMS JDBC store tables are named PrefixNameJMSSTORE and PrefixNameJMSSTATE, where PrefixName is the value of the Prefix Name attribute for the JMS JDBC store.
If you do not want to upgrade persisted JMS messages, you can delete the JMS file store or JMS JDBC store tables before running the upgrade. When you do so, only JMS messages are lost; the configuration is not changed. For information about managing JDBC store tables, see "Managing JDBC Store Tables" in Configuring WebLogic Server Environments at http://download.oracle.com/docs/cd/E13222_01/wls/docs91/config_wls/store.html#managing_jdbc_store_tables.
The wizard does not upgrade a JMS JDBC or file store if it detects that an upgrade has already been performed. If you need to perform multiple upgrades of a domain in which the same persistent stores are use (for example, in a test scenario), you must revert the data in the JMS store each time you repeat the upgrade process, as follows:

For a JMS JDBC store, the upgrade process creates a new table named PrefixNameWLSTORE, where PrefixName is the value of the Prefix Name attribute for the JMS JDBC store. Before re-running the upgrade process on a domain that uses the JMS JDBC store is used, remove or clear this table.
If you need to re-run the upgrade, make sure you first restore the backed up version of the JMS file store.

Saves the configuration.

Note: When upgrading remote Managed Servers, the wizard does not persist the configuration information.

Reports any issues with the domain upgrade that require further consideration.

Important Notes About the Domain Upgrade Process

Please note the following important notes about the upgrade process:

At a minimum, the domain directory must contain the following files:

config.xml
Security-related files, including SerializedSystemIni.dat, DefaultAuthenticatorInit.ldift, DefaultAuthorizerInit.ldift, and DefaultRoleMapperInit.ldift

If the security-related files are not available, the server fails to start and an authentication error message is logged.

Any transaction log (.tlog) files that reside in the domain. For more information, see "Transaction Log Files" in Programming WebLogic JTA at http://download.oracle.com/docs/cd/E13222_01/wls/docs91/jta/trxcon.html#tlog.

All contents of the domain directory on the target machine are updated during this process.
You must upgrade the domain on every machine in the application environment.
When upgrading a WebLogic Server 6.1 domain, please note the following:

The WL_HOME\config directory must contain only one domain. If it contains more than one domain, the upgrade will fail.
When a domain contains single-module applications (.war, .jar) and an application.xml file is not defined for the domain, make sure that the pathname for the application does not include URL for the module. For example, if the path is specified as c:\bea\wlserver6.1\config\petstore\applications\tour.war, the tour.war filename must be removed before you start the upgrade. Otherwise, the upgrade process returns an error indicating that the path is invalid.

If an error is encountered during the upgrade process and the application module is not deployed, the module is autodeployed as long as the server is running in development mode. Otherwise, you need to deploy the application module using the WebLogic administration tools.

The wizard does not upgrade applications during a WebLogic domain upgrade. In most cases, WebLogic Server applications can be run without modifications in the new WebLogic Server 9.1 application environment. Review the compatibility information in Compatibility with Previous Releases to determine whether any features changes affect the applications in your environment. Note that if APIs that have been deprecated or removed are used in the application, then you may encounter warnings or exceptions at run time.
As of 9.0, the .wlnotdelete directory is no longer used in the WebLogic Server environment.
During the upgrade process, file permissions are not preserved. All non-default file permissions need to be verified and reset.
On a UNIX system, ownership and permissions for any new files created during the upgrade process are assigned to the user performing the upgrade. For example, if the upgrade is performed by root, then root is assigned ownership of any new files. As a result, any user who subsequently wants to update these files in the domain must have root privileges. You may want to review and/or modify the permissions on files created during the upgrade process.
In WebLogic Server 9.1, you may need to specify a username and password when starting the server. As a result, you may notice the following behavioral changes:

In 6.1, the username defaulted to system, and you were required to specify a password only.
When upgrading the WebLogic product samples that were installed automatically for WebLogic Server 7.0 releases (located in WL_HOME\samples\server\config), you may notice a change in behavior when starting the Administration Server in the upgraded 9.1 domain. With 9.1, you are prompted for a username and password. With 7.0, the username and password are passed as a command-line argument to the startServer command, as follows:

-Dweblogic.management.username=weblogic -Dweblogic.management.password=weblogic

When you upgrade a domain on a remote Managed Server, a message similar to the following may be displayed to indicate that the referenced application path does not reside on the system:

<Aug 1, 2005 6:42:06 PM EDT> <INFO> <Upgrade> <BEA-800000> <An invalid
path, 'C:\bea\weblogic81\user_projects\mydomain\medrecEar.ear', was
specified for application, 'medrecEar'.>

This message can be ignored.

If you upgraded the Avitek Medical Records application from 8.1 to 9.1 on a Solaris machine (only), before starting the server, you must edit the setDomainEnv.sh file to remove -Xverify:none from the start command by setting JAVA_OPTIONS="" after the following line:

. ${WL_HOME}/common/bin/commEnv.sh
Otherwise, the server start will fail with a JVM error.

Upgrading a Domain

The wizard supports the following upgrade modes:

Graphical—For upgrading a domain interactively, using the graphical user interface.
Silent—For upgrading a domain silently, by specifying upgrade requirements in a file.

Note: You can also use implicit mode, to upgrade a domain automatically when the Administration Server is started. For more information, see Upgrading a Domain at Administration Server Startup (Implicit Mode).

You must upgrade the domains on every machine in the domain. For information about preparing remote managed server domain directories, see Step 4: Prepare the Remote Managed Server Domain Directories.

The following sections provide instructions for both modes:

Upgrading a Domain in Graphical Mode

The following sections describe how to upgrade a WebLogic domain using the WebLogic Upgrade Wizard in graphical mode:

Note: The console from which you are running the Upgrade Wizard in graphical mode must support a Java-based GUI. If you attempt to start the Upgrade Wizard in graphical mode on a system that cannot support a graphical display, the invocation fails and an error message is displayed.

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade a Domain

To start the WebLogic Upgrade Wizard in graphical mode and upgrade a WebLogic domain on a Windows platform, choose the Domain Upgrade Wizard option from the BEA program group in the Windows Start Menu:

Start —> Programs —> BEA Products—> Tools —> Domain Upgrade Wizard

Note: You can only use this option if you do not have to customize the environment to specify JDBC driver classes, as described in step 3 of Step 5: Set Up the Environment.

To start the WebLogic Upgrade Wizard in graphical mode and upgrade a WebLogic domain from a Windows command prompt or on a UNIX platform:

Note: Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade and reviewed the important notes described in Important Notes About the Domain Upgrade Process.

Verify that the WebLogic domain is not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 5: Set Up the Environment.

At the command prompt, enter the following command:

java weblogic.Upgrade [-type domain] [-out file]
Two arguments are optional: -type and -out. Include these arguments if you want to override the default values for the following:

The type of upgrade to be performed. If you do not specify a type with the -type option, a domain upgrade is performed.
The output file in which all standard output (stdout) and error messages are written. If you do not specify a file with the -out option, such messages are written to the command window, and a summary of messages is displayed at the end of the upgrade process.

The -out argument is optional. It allows you to designate a file in which you want all standard output (stdout) and error messages to be written. By default, these messages are written to the command window and a summary of them is displayed at the end of the upgrade process.
After you run the command, the WebLogic Upgrade Wizard opens, as shown in the following figure.

If JMS JDBC stores are used in the domain, you should start the corresponding databases.

Click Next to proceed to the next window.

Procedure for Upgrading a WebLogic Domain

The following table summarizes the steps in the procedure to upgrade a domain using the WebLogic Upgrade Wizard.

Table 5-1 Procedure for Upgrading a WebLogic Domain

In this step ...	You ...
Select WebLogic Version	Select the WebLogic version of the domain that you are upgrading, as shown in the following example. Note: When upgrading a WebLogic Server 6.1 domain, the `WL_HOME\config` directory must contain only one domain. If it contains more than one domain, the upgrade will fail. Click Next to proceed to the next window.
Select a Domain to Upgrade	Select the directory that contains the WebLogic domain to be upgraded by navigating the local directory hierarchy, as shown in the following example. Note: When upgrading a WebLogic Server 6.1 domain, you should select the directory that contains the `config` directory. For example, if your domain resides in `c:/bea/user_projects/config/mydomain`, you should select `c:/bea/user_projects` as the directory of the WebLogic domain. If you select another directory, such as `c:/bea/user_projects/config/mydomain`, you will get unexpected results. Click Next to proceed to the next window.
Inspect Domain	Review progress of the wizard as it inspects the domain. Progress messages are displayed in the window, as shown in the following example. If you attempt to upgrade a domain in which custom security providers are used, without first upgrading those security providers, an error message is displayed and the wizard exits. The error message appears as follows. If you receive this error message, upgrade the customer security providers, as described in Upgrading a Security Provider, and start the domain upgrade procedure again. Once the inspection is complete (and if no error is encountered), the wizard advances to the next window automatically.
Select Administration Server	Select a server to function as the Administration Server in the new domain, as shown in the following example. Note: If there is only one server defined in the domain, this window is skipped. Click Next to proceed to the next window.
Enter Node Manager Credentials	Enter the username and password (and password confirmation) for Node Manager authorization, as shown in the following example. For WebLogic Server 9.1, Node Manager requires user and password credentials to be specified for each domain. By default, the username and password are set to `weblogic`. If you do not use Node Manager, leave the default values unchanged. Click Next to proceed to the next window.
Select Upgrade Options	Select one or more of the following upgrade options: Back up current domain (recommended)—If selected, the wizard backs up the original domain directory and stores it in a zip file. This option is selected by default. Note: The wizard backs up the domain directory only and does not preserve file permissions. BEA recommends that you back up the domain and any external application and application database resources in a separate process, as described in Step 2: Back Up the Application Environment. Add log files to backup zip—If selected, log files will be included in the backup zip file. The number and size of log files can be large and you may want to disable this option to exclude them from the backup file. By default, log files are included in the backup file. Do not set backwards compatibility flags—As of WebLogic Server 9.0, some previously supported behavior has changed to comply with J2EE 1.4. By default, the wizard sets flags to enable the previous behavior in the new domain. If you select this option, these flags are not set for backward compatibility. For more information about the backward compatibility flags, see Backward Compatibility Flags. Click Next to proceed to the next window.
Directory Selection Analysis and Optional Tasks	Review progress as the wizard processes the domain information and options provided. Progress messages are displayed in the window, as shown in the following example. Once processing is complete, the wizard advances automatically to the next window.
Domain Backup	Review progress of the wizard as it prepares to back up the domain. Progress messages are displayed in the window, as shown in the following example. Note: Messages that are not relevant to this step are shaded in the following illustration. Once the preparation is complete, the wizard advances automatically to the next window.
Select Directory for Domain Backup	Note: If you did not select the Back up current domain upgrade option, as described in Select Upgrade Options, skip to Restructure Domain Directory. In this window, set values for the following: Backup directory—Navigate the local hierarchy and select the directory in which you want to save the backup zip file. By default, the original domain directory is used. Backup filename—Enter the name of the backup file in the text box. The default filename is `weblogic-domain-backup-domain.zip`, where `domain` specifies the name of the domain. The following example shows how these values are set. Click Next to proceed to the next window.
Backup Domain	Review progress as the wizard backs up the domain. A progress bar displays the percentage of the backup process that is complete, and progress messages are displayed in the window, as shown in the following example. Note: Messages that are not relevant to this step are shaded in the following illustration. Note: Backup files created by the wizard need to be protected by the user as they may contain confidential information. Once the backup process is complete, the wizard advances automatically to the next window.
Restructure Domain Directory	Review progress as the wizard restructures the domain directory. Progress messages are displayed in the window, as shown in the following example. Once the restructuring process is complete, the wizard advances automatically to the next window.
Upgrade Configuration Settings	Review progress as the wizard upgrades the configuration settings. Progress messages are displayed in the window, as shown in the following example. Note: Messages that are not relevant to this step are shaded in the following illustration. The configuration information is not persisted until a later step. Once the configuration upgrade is complete, the wizard advances automatically to the next window.
Upgrade Persisted Messages and Transaction Log Formats	Review progress as the wizard upgrades the persisted messages (JMS file and JDBC stores) and transaction (JTA) logs that exist in the domain. A progress bar displays the percentage complete and progress messages are displayed in the window, as shown in the following example. Once the persisted message and transaction log upgrade process is complete, the wizard advances to the next window automatically.
Finalize Domain Upgrade	Review progress of the wizard as it saves the upgraded configuration and deletes any temporary files that were created during the upgrade process. Progress messages are displayed in the window. Note: When upgrading remote Managed Servers, the wizard does not persist the configuration information. For example: Note: Messages that are not relevant to this step are shaded in the following illustration. Once this process is complete, click Next to proceed to the next window.
Upgrade Complete	Review the results of the upgrade, including any important messages that require further consideration, as shown in the following example. Click Done to close the WebLogic Upgrade Wizard.

Upgrading a Domain in Silent Mode

In some circumstances, for example, when the domain resides on a remote machine, it is not practical to use the WebLogic Upgrade Wizard in graphical mode. In such situations, you can use the wizard in silent mode to upgrade the WebLogic domain.

Note: Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade.

To start the WebLogic Upgrade Wizard in silent mode and upgrade a WebLogic domain:

Verify that the WebLogic domain is not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 5: Set Up the Environment.

(Optional) Create an XML script to define the upgrade requirements. For more information, see Silent Upgrade XML Script Reference.

Navigate to the directory that contains WebLogic domain that you want to upgrade. For example:

cd c:\bea\user_projects\domains\domain
where domain specifies the name of the domain.

At a command prompt, enter the following command:

java weblogic.Upgrade -mode silent -type domain [-responses xmlfile] [-out file]

Two arguments are optional: -responses and -out. Include these arguments if you want to override the default values for the following:

The location of an XML file that defines the upgrade requirements. If you do not specify a file with the -responses option, the wizard uses the default values during the upgrade process. For more information about the format of the XML file and the default values, see Silent Upgrade XML Script Reference.
The output file in which all standard output (stdout) and error messages are written. If you do not specify a file with the -out argument, these messages are written to the command window.