This chapter describes how to use the Reconfiguration Wizard to reconfigure WebLogic Server domains that were created using any WebLogic Server 10.3.1 or greater release or WebLogic Server 12.1.1.
When you use the Reconfiguration Wizard to reconfigure a WebLogic Server domain, the following items are automatically updated, depending on the applications in the domain:
WLS core infrastructure
Domain version
Note:
The Reconfiguration Wizard does not update any of your own applications that are included in the domain. For information about how to upgrade your own applications, see Appendix A, "WebLogic Server 12.1.2 Compatibility with Previous Releases."
This chapter contains the following sections:
Refer to the following two sections prior to beginning the upgrade process.
If a domain was created prior to WebLogic Server 10.3.0, you must first upgrade to WebLogic Server 10.3.6. After upgrading to WebLogic Server 10.3.6, run the Domain Upgrade Wizard to upgrade the domain.
For information about upgrading to WebLogic Server 10.3.6 and running the Domain Upgrade Wizard, see Upgrade Guide for Oracle WebLogic Server 10.3.6 at the following URL:
Prior to running the Reconfiguration Wizard to reconfigure a domain on a UNIX or Linux operating system, if you have not already done so, set the CONFIG_JVM_ARGS environment variable to the following value to use the operating system's random number generator:
-Djava.security.egd=file:/dev/./urandom
This decreases the amount of time it takes for the Reconfiguration Wizard to reconfigure a domain.
Prior to running the Reconfiguration Wizard, make a backup copy of the domain directory. For example, copy C:\domains\mydomain to C:\domains\mydomain_backup.
Prior to updating the domain on each remote Managed Server, make a backup copy of the domain directory on each remote machine.
If domain reconfiguration fails for any reason, you must copy all files and directories from the backup directory into the original domain directory to ensure that the domain is returned entirely to its original state prior to reconfiguration.
You can reconfigure a WebLogic domain:
In graphical mode, by running the Fusion Middleware Reconfiguration Wizard, or
From the command line using WebLogic Scripting Tool.
When you reconfigure a domain:
The domain version number in the config.xml file for the domain is updated to the Administration Server's installed WebLogic Server version major and minor version number (for example, 12.1.2.0).
Reconfiguration templates for all installed Oracle products are automatically selected and applied to the domain. These templates define any reconfiguration tasks that are required to make the WebLogic domain compatible with the current WebLogic Server version.
Start scripts are updated.
You must manually complete the Node Manager configuration to use the existing Node Manager configuration for the domain.
Note:
If you want the Node Manager for the domain to be a per-domain type rather than host-based, Oracle recommends that you use the Configuration Wizard or WLST to create a new domain instead of reconfiguring the existing domain. For information about Node Manager types, see "Configuring Java Node Manager" in Administering Node Manager for Oracle WebLogic Server.
Note the following items when reconfiguring a domain:
After reconfiguring the domain on the Administration Server, you must port the reconfigured domain to all remote Managed Servers in the domain. For more information, see Updating a Managed Server Domain on a Remote Machine.
After reconfiguring a domain using either WLST or the Reconfiguration Wizard, you must take additional steps to complete the Node Manager configuration. See Completing the Node Manager Configuration.
To reconfigure a WebLogic domain by using the Reconfiguration Wizard in graphical mode, start the wizard as follows. You can start the Reconfiguration Wizard only from a DOS command prompt window or UNIX shell.
Caution:
Once the domain reconfiguration process starts, it is irreversible. Prior to running the Reconfiguration Wizard, ensure that you have backed up the domain as described in Backing Up the Domain. If an error or other interruption occurs while running the Reconfiguration Wizard, you must restore the domain by copying the files and directories from the backup location to the original domain directory. This is the only way to ensure that the domain has been returned to its original state prior to reconfiguration.
Note:
In situations where you cannot run the Reconfiguration Wizard in GUI mode, Oracle recommends that you use a WLST script to reconfigure your domain. For more information, see Reconfiguring a WebLogic Domain Using WebLogic Scripting Tool.
To start the Reconfiguration Wizard in graphical mode from a Windows command prompt or on UNIX systems:
Log in to the system on which the domain resides.
Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX).
Go to the following directory:
On Windows: ORACLE_HOME\oracle_common\common\bin
On UNIX: ORACLE_HOME/oracle_common/common/bin
where ORACLE_HOME is your Oracle home directory.
Execute the following command:
On Windows: reconfig.cmd
On UNIX: sh reconfig.sh
Note:
When you run the reconfig.cmd or reconfig.sh command, the following error message might be displayed to indicate that the default cache directory is not valid:
*sys-package-mgr*: can't create package cache dir
You can change the cache directory by including the -Dpython.cachedir=valid_directory option in the command.
The Select Domain screen is displayed.
The Reconfiguration Wizard displays a sequence of screens, in the order listed in Table 3-1. For more information on each screen, refer to the related section in Chapter 5, "Reconfiguration Wizard Screens," or click the link in the Screen column.
Notes:
Depending on the applications in your domain and other factors, additional configuration screens may also be displayed in addition to the screens shown in the following table. For information on these screens, click the Help button on the screen or refer to Chapter 5.
If the Advanced Configuration screen is displayed during reconfiguration, do not select any options to skip all advanced configuration. If necessary, you can use WLST, the Configuration Wizard or the Administration Console at a later time to perform advanced configuration such as adding additional servers and clusters or changing deployment targeting.
Table 3-1 Reconfiguring an Existing WebLogic Domain
| Screen | When Does This Screen Appear? | Perform the Following Action |
|---|---|---|
|
Always |
Enter the full path to the domain directory or click Browse to navigate to and select the domain directory. Click Next to continue. |
|
|
Always |
Shows the progress of the application of reconfiguration templates. When the process completes, click Next to continue. |
|
|
Always |
Domain mode cannot be changed. Select the JDK to use in the domain or click Browse to navigate to the JDK you want to use. Click Next to continue. |
|
|
Additional domain configuration screens may appear at this point |
Additional screens depend on the domain configuration |
Click the Help button on the screen or refer to Chapter 5, which describes all of the screens in the order in which they are displayed. |
|
Always |
Select the check box for each category (if any) for which you want to perform advanced configuration tasks The available check boxes depend on the domain configuration. Click Next to continue. |
|
|
Additional domain configuration screens may appear at this point |
Additional screens depend on the Advanced Configuration options you selected |
Click the Help button on the screen or refer to Chapter 5, which describes all of the screens in the order in which they are displayed. |
|
Always |
Review the configuration. Click the Back button to change the configuration or click the Reconfig button to complete the domain reconfiguration process. |
|
|
Always |
Shows the final status of the reconfiguration process. Click Finish to exit the Configuration Wizard. |
This section describes how to reconfigure a domain using WebLogic Scripting Tool (WLST) in offline mode, using the readDomainForUpgrade command.
Caution:
Once the domain reconfiguration process starts, it is irreversible. Prior to running using WLST to reconfigure the domain, ensure that you have backed up the domain as described in Backing Up the Domain. If an error or other interruption occurs during reconfiguration, you must restore the domain by copying the files and directories from the backup location to the original domain directory. This is the only way to ensure that the domain has been returned to its original state prior to reconfiguration.
The following example script shows how to reconfigure a domain called my_domain using WLST offline.
After reconfiguring your domains, perform the following steps to complete the Node Manager configuration:
Note:
The following steps describe how to configure Node Manager to run as it did in your previous installation, using one Node Manager to control all of your domains.
In the new WebLogic Server installation, create the nodemanager directory in ORACLE_HOME/oracle_common/common.
Copy the nodemanager.properties and nodemanager.domains files from the WL_HOME/common/nodemanager directory of your previous WebLogic Server installation to the directory you created in Step 1.
If your previous installation includes an nm_data.properties, SerializedSystemIni.data, or security/SerializedSystemIni.dat file, copy it to the directory you created in Step 1. If copying SerializedSystemIni.dat, you must create a security directory under the nodemanager directory and store the file there.
Make the following edits to the nodemanager.properties file, where ORACLE_HOME is the Oracle home directory for your WebLogic Server 12.1.2 installation:
Update DomainsFile to point to ORACLE_HOME/oracle_common/common/nodemanager/nodemanager.domains file.
If the file contains a javaHome property setting, remove it as it is not needed.
Update JavaHome to point to the jre directory for the JDK that you are using for WebLogic Server 12.1.2.
Update NodeManagerHome to point to ORACLE_HOME/oracle_common/common/nodemanager.
Update LogFile to point to ORACLE_HOME/oracle_common/common/nodemanager/nodemanager.log
If you are using your own security certificates, verify that the location of those certificates is correct in nodemanager.properties. You may have to update the path if you moved the certificates to another location.
If you were using the WebLogic Server demo certificate in your previous installation, you must run CertGen to create a demo keystore for this installation:
Run setWLSEnv:
cd WL_HOME/server/bin
. ./setWLSEnv.sh (UNIX)
setWLSEnv.cmd (Windows)
Note:
On UNIX operating systems, the setWLSEnv.sh command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.
Change to the ORACLE_HOME/oracle_common/common/nodemanager/ directory and create a security directory if it does not already exist.
Change to the security directory and enter the following command:
java utils.CertGen -certfile democert -keyfile demokey -keyfilepass DemoIdentityPassPhrase
Enter the following command to generate the DemoIdentity.jks file:
java utils.ImportPrivateKey -certfile democert.pem -keyfile demokey.pem -keyfilepass DemoIdentityPassPhrase -keystore DemoIdentity.jks -storepass DemoIdentityKeyStorePassPhrase -alias demoidentity
From the ORACLE_HOME/wlserver/server/bin directory, run startNodeManager.cmd (Windows) or startNodeManager.sh (UNIX).
Verify that you can start servers using Node Manager. For more information, see "Using Node Manager to Control Servers" in Administering Node Manager for Oracle WebLogic Server. To ensure that your permgen settings are adequate for starting the servers, you can use any one of the following methods:
Start the Managed Servers using the startManagedWebLogic script.
Set the StartScriptEnabled value in nodemanager.properties to true, which causes the StartManagedWebLogic script to be invoked when starting Managed Servers.
Set permgen space as described in Setting permgen space.
Use a setUserOverrides script to specify permgen settings for server startup. For more information, see "Customizing Domain Wide Server Parameters" in Administering Server Startup and Shutdown for Oracle WebLogic Server.
If your WebLogic domain contains multiple Managed Servers, and each Managed Server domain directory is located on a remote machine on which the Administration Server does not reside, you can use either of the following methods to update the domain on the remote machine:
Run the pack -managed=true command to generate the domain template JAR, move the JAR to the remote machine, and then use unpack on the remote machine to create the Managed Server domain. For more information, see Creating Templates and Domains Using the Pack and Unpack Commands.
Use the WLST writeTemplate command in online mode. When you execute the writeTemplate command while connected to the Administration Server from a remote machine, it dynamically packs the domain on the Administration Server into a template JAR file and transfers the template JAR to the specified directory.
The following sample WLST script demonstrates how to use writeTemplate to create or update a Managed Server domain on a remote machine. Run the script on each remote machine in the domain. This script:
logs in to the Administration Server
packs the Administration Server domain into a JAR file and writes it to the specified template directory on the remote machine.
disconnects from the Administration Server
reads the template JAR
creates the domain on the remote machine
import os
wlsHome = os.getenv('WL_HOME')
mwHome = os.path.join(wlsHome, '..')
#Substitute the administrator user name and password values below as needed
connect('adminuser','adminpassword','admin_server_url')
#Create the path on the local machine where the template will be stored,
#The specified template JAR should not already exist. The timeout value
#specifies the number of milliseconds to elapse before the connection between
#the Administration Server and remote machine times out (default is 120000).
templatePath = '/user_templates/myTemplate.jar'
timeout = '180000'
#get the packed template from the Administration Server
writeTemplate(templatePath, timeout)
#disconnect from online WLST connection to the Administration Server
disconnect()
#read the template that was downloaded from the Administration Server
readTemplate(templatePath)
#specify the domain directory where the domain needs to be created
domainPath = 'domains/myDomain')
#create the domain
writeDomain(domainPath)
Please note the following important information about the upgrade process:
It is not necessary for WebLogic Server applications to be undeployed. In most cases, WebLogic Server applications can be run without modifications in the new WebLogic Server 12.1.2 application environment. Review the compatibility information in Appendix A, "WebLogic Server 12.1.2 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.
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 Developing JTA Applications for Oracle WebLogic Server.
All contents of the domain directory on the target computer are updated during this process.
You must upgrade the domain on every computer in the application environment.
The reconfiguration wizard does not upgrade your own applications that may exist in the domain during a WebLogic domain upgrade.
Domains that contain resources for WebLogic Liquid Data, or AquaLogic Data Services Platform cannot be upgraded to WebLogic Server 12.1.2.
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:
<Apr 12, 2009 6:42:06 PM EDT> <INFO> <Upgrade> <BEA-800000> <An invalid path, 'C:\bea\wlserver_10.3\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 12.1.2 on a Solaris computer (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 fails with a JVM error.
After you upgrade the application environment, it may be necessary to perform the following tasks:
Not all of these steps are required for all situations. Review the sections to determine which, if any, of these steps are appropriate for your environment. In addition, you should review the compatibility issues in Appendix A, "WebLogic Server 12.1.2 Compatibility with Previous Releases," to determine if any of the compatibility issues apply to your environment].
To complete the upgrade of your application environment to 12.1.2, it might be necessary to re-apply any customizations to startup scripts. The following sections describe how to customize the default startup scripts as well as any custom startup scripts.
The Reconfiguration Wizard does not carry forward any customizations that have been made to the default startup scripts, such as the setting of the JAVA_OPTIONS environment variable. After the upgrade process is complete, you must customize the default scripts again.
If you are upgrading your domain to 12.1.2 and you want to continue using PointBase, you must add the PointBase JAR files to the beginning of the CLASSPATH environment variable definition. To do so, update the set CLASSPATH statement in your setDomainEnv files.
Note:
WebLogic Server 12.1.2 supports PointBase 5.7; however, the use of any version of PointBase with WebLogic Server 10.3.3 or later requires a PointBase license, available at http://www.pointbase.com.
If you have created custom startup scripts, you must update them manually, as follows:
Set the JDK version to the JDK that you are using with WebLogic Server.
Update the CLASSPATH variable, as follows:
Add WebLogic Server 12.1.2 classes to the beginning of the variable.
Remove all unused pre-10.3 WebLogic classes.
To continue using PointBase, include the PointBase database JARs at the beginning of the CLASSPATH environment variable definition.
For more information about upgrading a domain that uses an evaluation database, see Upgrading a Domain that Uses an Evaluation Database.
Verify the file permissions, as follows:
If you backed up the domain directory as part of the upgrade, you must make your backup files secure because they might contain confidential information.
During the upgrade process, file permissions are not preserved. If nondefault file permissions are set on files, they must 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 or modify the permissions on files created during the upgrade process.
When you start the Administration Server, verify that the remote server start options, such as JAVA_HOME, BEA_HOME, and CLASSPATH, reference the WebLogic Server 12.1.2 installation on the target Managed Server. This can be accomplished using the Administration Console, as described in "Configure startup arguments for Managed Servers" in Oracle WebLogic Server Administration Console Online Help.
Note:
If the remote server startup options are not set correctly, when attempting to start a Managed Server using Node Manager, messages similar to the following may be written to the log file. Because these messages may be sent recursively, they may eventually consume all space available on the drive.
No config.xml was found. Would you like the server to create a default configuration and boot? (y/n): java.io.IOException: The handle is invalid
Execute standard procedures for quality assurance and performance tuning before promoting an application environment to production. You should test the execution of your applications (including external client applications) in your test application environment. If your applications use APIs that have been deprecated or removed, then you may encounter warnings or exceptions at run time. If you do, you can make any required modifications before promoting your applications to production.
When all test criteria have been met, you can promote the application environment to production, as outlined in your upgrade plan (defined previously in Step 4: Create an Upgrade Plan).
When the new 12.1.2 application environment is deployed into production, you can start redirecting requests to the new environment from the existing environment. Gradually, you can bring the existing environment to a safe state for shutdown. This might be accomplished using a load balancer, for example.
As of WebLogic 10.3.3, the evaluation database that is available from the installation program is changed from PointBase to Derby. The evaluation database is provided for use by the sample applications and code examples and may be used as a demonstration database. If you are upgrading an examples or demonstration domain that was originally based on PointBase, you have the option to continue using PointBase in the domain.
To continue using PointBase as the database for a domain being upgraded to WebLogic 12.1.2, complete the following steps:
When installing WebLogic Server 12.1.2, as described in Prepare to Upgrade, you must use the full installer. The full installer does not preserve the PointBase installation from the previous WebLogic Server installation.
Complete the steps described in Upgrade Your Application Environment, and Completing Post-Upgrade Tasks.
The domain's configuration settings for PointBase are preserved.
Obtain a PointBase license, available from http://www.pointbase.com.
Restore your PointBase installation. PointBase is installed in the WL_HOME/common/eval/pointbase directory.
Add the PointBase database JARs at the beginning of the CLASSPATH environment variable definition.