3 Reconfiguring WebLogic Domains

You can use the Reconfiguration Wizard to upgrade any WebLogic domain that was created with Oracle WebLogic Server 10.3.1 or later, or from Oracle WebLogic Server 12.1.1 or later.

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 applications that are included in the domain. For information about how to upgrade your applications, see WebLogic Server 14.1.1.0.0 Compatibility with Previous Releases.

Learn how to use the Reconfiguration Wizard to reconfigure WebLogic Server domains.

Before You Begin

Before you run the Reconfiguration Wizard, make sure the domain is upgraded to version WebLogic Server 10.3.6, if necessary. You then perform additional tasks, such as configuring the CONFIG_JVM_ARGS environment variable, backing up the domain, and choosing the Node Manager configuration that you want to use with the upgraded domain.

Upgrading Domains Created Prior to WebLogic Server 10.3.0

Domains created with WebLogic Server versions 10.3.0 and later can be upgraded directly to version 14.1.1.0.0. However, if your domain was created prior to WebLogic Server 10.3.0, you must first upgrade it to WebLogic Server 10.3.6.

After upgrading to WebLogic Server 10.3.6, run the Domain Upgrade Wizard to upgrade the domain.

To upgrade to WebLogic Server 10.3.6 and run the Domain Upgrade Wizard, see Upgrade Guide for Oracle WebLogic Server 10.3.6 at the following URL:

http://docs.oracle.com/cd/E23943_01/web.1111/e13754/toc.htm

Setting CONFIG_JVM_ARGS on UNIX and Linux Systems

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.

Backing Up the 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.

Determining Node Manager Upgrade Procedure

Prior to WebLogic Server 12.1.2, a default Node Manager configuration was provided by WebLogic Server using a default startup script and a default Node Manager home location. By default, any new domains that were created on that machine were associated with the Node Manager in the default Node Manager location. This is commonly referred to as a per host Node Manager.

Starting WebLogic Server 12.1.2, a Node Manager default configuration is a per domain Node Manager configuration. That is, the Node Manager configuration is specific to a given domain. This configuration allows multiple domains on a given machine to have different Node Manager configurations. See Default Node Manager Configuration in Administering Node Manager for Oracle WebLogic Server.

Table 3-1 shows the supported Node Manager upgrade paths when upgrading WebLogic Server from version 12.1.1 or earlier to the current version, or when upgrading from version 12.1.2 or later to the current version. Per host in this context means any Node Manager configuration that is outside of your per domain Node Manager configurations.

Table 3-1 Supported Node Manager Upgrade Paths

Node Manager Upgrade Paths From WebLogic Server 12.1.1 or earlier From WebLogic Server 12.1.2 or later

Per domain to per domain

Not available

Supported

Per domain to per host

Not available

Not supported

Per host to per domain

Supported

Supported

Per host to per host

Manual configuration

Manual configuration

Table 3-2 shows the Node Manager upgrade details for each supported upgrade path.

Table 3-2 Node Manager Upgrade Details

Per Domain to Per Domain Per Host to Per Domain Per Host to Per Host

This is an automatic upgrade for all WebLogic Server 12.1.2 or later releases that are already configured for per domain Node Manager. The environment is updated to standard settings and can be customized later.

The upgrade is automatic whether you are using the Reconfiguration Wizard or WLST to upgrade the domain.

In this case, the Reconfiguration Wizard provides a Node Manager screen during domain reconfiguration. Use this screen to select the Node Manager configuration to use for the reconfigured domain. The resulting configuration depends on the combination of options that you select for Node Manager Type and Node Manager Configuration.

You can also use WLST to upgrade the domain and Node Manager configuration as desired. See Reconfiguring a WebLogic Domain Using WebLogic Scripting Tool.

If multiple per domain Node Managers run on the same machine, see Configuring Multiple Per Domain Node Managers on the Same Machine.

Click the Help button on the screen on the Fusion Middleware Reconfiguration Wizard window to see the Reconfiguration Wizard Context-Sensitve Help.

Node Manager configuration must be completed manually as described in Completing the Node Manager Configuration.

If only some 11g domains are upgraded to 14c, you would need to configure a second Node Manager for the 14c domains. Before starting the reconfiguration process, see Running Two Per Host Node Managers on the Same Machine. After domain reconfiguration, complete the Node Manager configuration as described in Completing the Node Manager Configuration (Two Per Host Node Managers).

Configuring Multiple Per Domain Node Managers on the Same Machine

If you have multiple domains on the same machine using a Per Domain Node Manager configuration, when running the Reconfiguration Wizard, do the following:

  • If you are upgrading an 11g domain, the Node Manager screen appears. Select either Per Domain Default Location or Per Domain Custom Location.

  • On the Advanced Configuration screen, select Managed Servers, Clusters, and Coherence to reconfigure the existing machines for the 14c Node Manager.

  • No changes are needed on the Managed Servers and Clusters screens. When the Machines screen appears, ensure that you use a unique Node Manager port for each domain. For example, if you have three per domain Node Managers running on the machine, use port 5556 for Domain 1, port 5557 for Domain 2, and port 5558 for Domain 3.

    Click the Help button on the screen on the Fusion Middleware Reconfiguration Wizard window to see the Reconfiguration Wizard Context-Sensitve Help .

Running Two Per Host Node Managers on the Same Machine

If all the following items apply to your upgrade scenario, extra steps are needed during the reconfiguration process to create a second Node Manager for the 14c domains:

  • You want to upgrade only some of your 11g or 12c domains to 14c.

  • You want to continue using a per host Node Manager for the 14c domains.

  • Both 11g/12c and 14c per host Node Managers are running on the same machine.

When running the Reconfiguration Wizard:

  • On the Node Manager screen, select Manual Node Manager Setup. This option keeps the Node Manager configuration as a per host Node Manager for the 14c domain being upgraded.

  • On the Advanced Configuration screen, select Managed Servers, Clusters, and Coherence to reconfigure the existing machines for the 14c Node Manager. In addition, select Deployments and Services to check machine assignments for your deployments and services.

  • No changes are needed on the Managed Servers and Clusters screens. When the Machines screen appears, change the name of each machine to something other than the name that is being used for the 11g or 12c domains. In addition, enter a Node Manager port number that is different than the Node Manager port number that is being used for the 11g or 12c Node Manager. Use the same port number for each 14c machine in this domain.

  • Verify that your deployments and services are assigned to the new machine names.

Reconfiguring a WebLogic Domain

Oracle provides a choice of two tools for reconfiguring a WebLogic domain: the graphical Fusion Middleware Reconfiguration Wizard or the WebLogic Scripting Tool (WLST).

Caution:

Once the domain reconfiguration process starts, it is irreversible. Before using the Reconfiguration Wizard or WLST to upgrade 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 the reconfiguration process, you must restore the domain by copying the files and directories from the backup location to the original domain directory. This workaround is the only way to ensure that the domain has been returned to its original state before reconfiguration.

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, 14.1.1.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.

  • After reconfiguring the domain on the Administration Server, you must port the reconfigured domain to all remote Managed Servers in the domain. See Updating a Managed Server Domain on a Remote Machine.

  • After reconfiguring a domain to a per host Node Manager by using either WLST or the Reconfiguration Wizard, you must take additional steps to complete the Node Manager configuration. See Completing the Node Manager Configuration and Completing the Node Manager Configuration (Two Per Host Node Managers).

Reconfiguring a WebLogic Domain in Graphical Mode

To reconfigure a domain using the Reconfiguration Wizard, you first launch it from a DOS command prompt or UNIX shell, and then provide the required upgrade details in a sequence of screens that are displayed.

Note:

If you cannot run the Reconfiguration Wizard in GUI mode, Oracle recommends that you use a WLST script to reconfigure your domain. 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:

  1. Log in to the system on which the domain resides.
  2. Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX).
  3. Go to the following directory, where ORACLE_HOME is your Oracle home directory:

    On Windows: ORACLE_HOME\oracle_common\common\bin

    On UNIX: ORACLE_HOME/oracle_common/common/bin

  4. Run the following commands:

    On Windows: reconfig.cmd

    On UNIX: sh reconfig.sh

    Note:

    When you run the reconfig.cmd or reconfig.sh command, the following error message appears if 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.

    To create a log file of the Reconfiguration Wizard session, include the -log=reconfig.log -log_priority=debug parameter in the command. You can specify any file name for the log file, such as config_today.log. The log file is stored in the logs directory of the Oracle Home directory. Other valid values for log_priority are OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, and ALL.

    The Select Domain screen appears.

The Reconfiguration Wizard displays a sequence of screens in the order listed in Table 3-3.

Note:

Depending on the applications in your domain and other factors, extra configuration screens appear in addition to the screens shown in the following table. For information on these screens, click the Help button on the screen.

If the Advanced Configuration screen appears during the reconfiguration process, do not select any options to skip all advanced configuration. If necessary, you can use WLST, the Configuration Wizard, or the WebLogic Server Administration Console later to perform advanced configuration such as adding more servers and clusters or changing deployment targeting.

Table 3-3 Reconfiguring an Existing WebLogic Domain

Screen When Does This Screen Appear? Perform the Following Action

Select Domain

Always

Enter the full path to the domain directory or click Browse to navigate to and select the domain directory.

Click Next to continue.

Reconfiguration Setup Progress

Always

Shows the progress of the application of reconfiguration templates.

When the process completes, click Next to continue.

Reconfiguration Summary

Always

Displays the information about the reconfiguration process for all the reconfigured templates.

Click Next to continue.

Domain Mode and JDK

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 Reconfiguration Wizard Screens, which describes all the screens in the order in which they are displayed.

Advanced Configuration

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.

Configuration Summary

Always

Review the configuration.

Click the Back button to change the configuration or click the Reconfig button to complete the domain reconfiguration process.

Reconfiguration Success

Always

Shows the final status of the reconfiguration process.

Click Finish to exit the Configuration Wizard.

Reconfiguring a WebLogic Domain Using WebLogic Scripting Tool

To reconfigure a domain using WLST, you use the readDomainForUpgrade command. You can also use this command to migrate an existing per host Node Manager configuration to a per domain configuration.

Note:

If the original domain is using a per domain Node Manager configuration, Node Manager is upgraded automatically and no additional steps are needed.

If the original domain is using a per host Node Manager, and you want to continue using that configuration, you must manually reconfigure Node Manager as described in Completing the Node Manager Configuration.

Example 3-1 shows how to reconfigure a domain called my_domain using WLST offline.

Example 3-2 shows how to migrate an existing per host Node Manager configuration to a per domain configuration located in DOMAIN_HOME/nodemanager.

Example 3-3 shows how to migrate an existing per host configuration located in /Oracle/Middleware/oracle_common/common/nodemanager to a per domain configuration located in /Oracle/Middleware/custom/nodemanager.

For information about available Node Manager options for the setOption command, see setOption in WLST Command Reference for WebLogic Server. For information about available Node Manager WLST commands, see Node Manager Commands in WLST Command Reference for WebLogic Server.

Example 3-1 Reconfiguring a WebLogic Domain

# Open the domain for upgrade.
wls:/offline> readDomainForUpgrade('c:/domains/my_domain')

# Save the updated domain.
wls:/offline/my_domain> updateDomain()

# Close the domain.
wls:/offline/my_domain> closeDomain()

If your existing domain is using a per host Node Manager and you want to move to a per domain Node Manager configuration, you have several options:

  • Create a per domain configuration in the default location (DOMAIN_HOME/nodemanager) by migrating an existing per host configuration.

  • Create a per domain configuration in the default location (DOMAIN_HOME/nodemanager) with a new configuration based on Oracle-recommended defaults.

  • Create a per domain configuration in a custom location by migrating an existing per host configuration.

  • Create a per domain configuration in a custom location with a new configuration based on Oracle-recommended defaults.

Example 3-2 Creating a New Node Manager Configuration in the Default Location

#Read domain for reconfiguration
readDomainForUpgrade('domains/mydomain')
 
#Set Node Manager username and password.
cd('/')
cd('SecurityConfiguration/mydomain')
cmo.setNodeManagerUsername('username')
cmo.setNodeManagerPasswordEncrypted('password')
 
#Browse Node Manager properties
cd('/')
cd('NMProperties')
 
# Create per domain Node Manager with new default configuration. Existing
# Node Manager properties will not be migrated in this case.
setOption('NodeManagerType','PerDomainNodeManager')
setOption('NodeManagerUpgradeType','New')
 
# Update the domain to commit the changes.
updateDomain()

Example 3-3 Migrating an Existing Configuration to a Custom Location

#Read domain for reconfiguration
readDomainForUpgrade('/domains/mydomain')
 
#Set Node Manager username and password.
cd('/')
cd('SecurityConfiguration/mydomain')
cmo.setNodeManagerUsername('username')
cmo.setNodeManagerPasswordEncrypted('password')
 
#Browse node manager properties
cd('/')
cd('NMProperties')
 
# Create custom location Node Manager, migrating an existing Node Manager
# configuration with default values for Oracle-recommended default properties.
setOption('NodeManagerType','CustomLocationNodeManager')
setOption('NodeManagerHome','/Oracle/Middleware/custom/nodemanager/')
setOption('NodeManagerUpgradeType','Migrate')
setOption('OldNodeManagerHome','/Oracle/Middleware/Oracle_Home/oracle_common/
common/nodemanager')
setOption('NodeManagerUpgradeOverwriteDefault','true')
 
# Update the domain to commit the changes.
updateDomain()

Completing the Node Manager Configuration

If the domain you reconfigured was using a per host Node Manager configuration and you want to continue using a per host Node Manager for the domain, you must complete a set of configuration tasks for Node Manager.

  1. In the new WebLogic Server installation, create the nodemanager directory in ORACLE_HOME/oracle_common/common.

  2. 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.

  3. 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.

  4. Make the following edits to the nodemanager.properties file, where ORACLE_HOME is the Oracle home directory for your WebLogic Server installation:

    • Update DomainsFile to point to ORACLE_HOME/oracle_common/common/nodemanager/nodemanager.domains file.

    • Update JavaHome to point to the jre directory for the JDK that you are using for WebLogic Server. If the file also contains a javaHome property setting (lower-case j), remove it as it is not needed.

    • Update NodeManagerHome to point to ORACLE_HOME/oracle_common/common/nodemanager.

    • Update LogFile to point to ORACLE_HOME/oracle_common/common/nodemanager/nodemanager.log.

  5. 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:

    1. 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.

    2. Change to the ORACLE_HOME/oracle_common/common/nodemanager/ directory and create a security directory if it does not exist.

    3. Change to the security directory and enter the following command:

      java utils.CertGen -certfile democert -keyfile demokey -keyfilepass DemoIdentityPassPhrase

    4. Tto generate the DemoIdentity.jks file, enter the following command:

      java utils.ImportPrivateKey -certfile democert.pem -keyfile demokey.pem -keyfilepass DemoIdentityPassPhrase -keystore DemoIdentity.jks -storepass DemoIdentityKeyStorePassPhrase -alias demoidentity

  6. From the ORACLE_HOME/wlserver/server/bin directory, run startNodeManager.cmd (Windows) or startNodeManager.sh (UNIX).

  7. Verify that you can start servers using Node Manager. 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. See Customizing Domain Wide Server Parameters in Administering Server Startup and Shutdown for Oracle WebLogic Server.

Completing the Node Manager Configuration (Two Per Host Node Managers)

If the domain you reconfigured was using a per host Node Manager configuration, you can continue using a per host Node Manager for the 14c domain on a machine that already has a per host Node Manager for 11g or 12c domains.

Complete the following steps on each machine in the domain:

Note:

Prior to performing the steps in this section, ensure that you have unpacked the domain to each remote machine in the domain. Include the -nodemanager_type=ManualNodeManagerSetup and -overwrite_domain=true parameters in the command. For example:

./unpack.sh -domain=domain_home -template=template_jar -nodemanager_type=ManualNodeManagerSetup -overwrite_domain=true
  1. In the new WebLogic Server installation, create the nodemanager directory in ORACLE_HOME/oracle_common/common.

  2. Copy the nodemanager.domains and nodemanager.properties files from the WL_HOME/common/nodemanager directory of your previous WebLogic Server installation to the directory you created in Step 1. If any 11g or 12c domains are listed in the nodemanager.domains file, delete or comment out those lines.

  3. Edit the nodemanager.properties file as appropriate on each machine. In particular:

    • Verify that the SecureListener is set to true if using an SSL Node Manager, or is set to false if using a Plain Node Manager.

    • Change DomainsFile to point to ORACLE_HOME/oracle_common/common/nodemanager/nodemanager.domains.

    • Change PropertiesVersion to 14.1.1.0.0.

    • Change NodeManagerHome to ORACLE_HOME/oracle_common/common/nodemanager.

    • Change JavaHome to point to the jre directory for the Java installation that you are using for WebLogic Server 14.1.1.0.0.

    • Remove the javaHome line as it is not needed in 14c.

    • Change ListenPort to the value you specified on the Machines screen of the Configuration Wizard.

    • Change LogFile to the desired location and file name. The recommended value is ORACLE_HOME/oracle_common/common/nodemanager/nodemanager.log.

  4. If you are using your own security certificates, verify that the location of those certificates is correct in nodemanager.properties. If you moved the certificates to another location, you have to update the path.

    If you used the WebLogic Server demo certificate in your previous installation, you must run CertGen to create a demo keystore for this installation:

    1. 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.

    2. Change to the ORACLE_HOME/oracle_common/common/nodemanager/ directory and create a security directory if it does not exist.

    3. Change to the security directory and enter the following command:

      java utils.CertGen -certfile democert -keyfile demokey -keyfilepass DemoIdentityPassPhrase

    4. To generate the DemoIdentity.jks file, enter the following command:

      java utils.ImportPrivateKey -certfile democert.pem -keyfile demokey.pem -keyfilepass DemoIdentityPassPhrase -keystore DemoIdentity.jks -storepass DemoIdentityKeyStorePassPhrase -alias demoidentity

  5. From the ORACLE_HOME/wlserver/server/bin directory, start Node Manager.

  6. If the Administration Server is running, restart the Administration Server.

  7. Verify that you can start servers using Node Manager. 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. See Customizing Domain Wide Server Parameters in Administering Server Startup and Shutdown for Oracle WebLogic Server.

Updating a Managed Server Domain on a Remote Machine

If your WebLogic domain contains multiple Managed Servers, and each Managed Server domain directory is located on a machine that is remote to the Administration Server host machine, you can use one of two methods to update the domain on the remote machine.

  • Use the pack command to generate the domain template JAR. Ensure that you include the -managed=true argument in the pack command. Move the JAR to the remote machine and then use the unpack command on the remote machine to create the Managed Server domain. 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 does the following tasks:

    • 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)

Important Notes About the Domain Upgrade Process

Bear in mind several key notes about the domain upgrade process, such as whether it is necessary to undeploy WebLogic Server applications, the minimum set of files that must exist in the domain directory, and more.

  • It is not always necessary to undeploy WebLogic Server applications. Usually, WebLogic Server applications can run without modifications in the new WebLogic Server 14.1.1.0.0 application environment. Review the compatibility information in WebLogic Server 14.1.1.0.0 Compatibility with Previous Releases to determine whether any features changes affect the applications in your environment. If APIs that have been deprecated or removed are used in the application, then you might 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. 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 14.1.1.0.0.

  • When you upgrade a domain on a remote Managed Server, a message similar to the following may appear 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'.>
    

    You can ignore this message.

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

    . ${WL_HOME}/common/bin/commEnv.sh

    Otherwise, the server start fails with a JVM error.

Completing Post-Upgrade Tasks

After you upgrade the application environment, it may be necessary to perform tasks such re-applying customizations to startup scripts, verifying file permissions and remote server startup options, and more.

This section includes the following topics:

Not all 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 WebLogic Server 14.1.1.0.0 Compatibility with Previous Releases to determine if any of the compatibility issues apply to your environment.

Re-apply Customizations to Startup Scripts

To complete the upgrade of your application environment to 14.1.1.0.0, 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.

Default 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 14.1.1.0.0 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 14.1.1.0.0 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.

Custom Startup Scripts

To update custom startup scripts:

  • Set the JDK version to the JDK that you are using with WebLogic Server.

  • Update the CLASSPATH variable, as follows:

    • Add WebLogic Server 14.1.1.0.0 classes to the beginning of the variable.

    • Remove all unused WebLogic classes prior to version 10.3.

    • To continue using PointBase, include the PointBase database JARs at the beginning of the CLASSPATH environment variable definition.

      To know about upgrading a domain that uses an evaluation database, see Upgrading a Domain that Uses an Evaluation Database.

Verify File Permissions

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.

Verify Remote Server Startup Options

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 installation on the target Managed Server. This can be accomplished using the WebLogic Server 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 

Recreating the Windows Node Manager Service

On Windows systems, if you were running Node Manager as a Windows service for your domain, you must reconfigure it if you want to continue using it.

For information about how to configure the Node Manager service for Windows, see Default Node Manager Configuration in Administering Node Manager for Oracle WebLogic Server.

Optionally, you can remove the Node Manager service from your installation by running uninstallNodeMgrSrv.cmd. See Default Node Manager Configuration in Administering Node Manager for Oracle WebLogic Server.

Promote the Application Environment to Production

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 14.1.1.0.0 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.

Enabling Edition-based Redefinition for Standalone WebLogic Server Installations (Optional)

Edition-based redefinition (EBR) provides standalone Oracle WebLogic Server users with online upgrade support with uninterrupted availability.

If you want to perform a zero downtime upgrade when upgrading to a future standalone release of Oracle WebLogic Server, you must perform the following tasks after installing and configuring the WebLogic domain.

Note:

For information about using EBR to perform an online application upgrade, see Using EBR to Upgrade an Application.

Before you begin, review the following prerequisites and pertinent information:

  • Oracle database is the only EBR-supported database.
  • In order to EBR-enable Weblogic Server for zero downtime upgrades, you must use the following database tables for storing system schemas: diagnostic logs, timers, leasing tables, servlet sessions, persistent stores, WAN persistent stores, LLR tables, and batch data tables.
  • The steps in this guide apply to Oracle WebLogic Server standalone installations.
  • In cases where the Oracle WebLogic Server administrator is not able to perform privileged database operations, a database administrator must execute SQL statements or provide an environment for the Oracle WebLogic Server administrator to use.
  • The Oracle WebLogic Server administrator or database administrator must create all editions.
  • Enabling EBR requires downtime during the initial setup, but once the environment is EBR-enabled, additional downtime is unlikely.
Stop the WebLogic Server Domain

Before you begin EBR-enabling your environment, you must first stop the WebLogic Server domain.

See Starting and Stopping Servers in Administering Server Startup and Shutdown for Oracle WebLogic Server.
Create an Edition-enabled User and the Edition

Create an edition-enabled user before creating the edition on the database.

The WebLogic Server administrator or the database administrator must complete the following:
  1. Connect to SQL*Plus and execute the following commands to create an edition-enabled user:
    $ sqlplus <sysdba-connection-string>
    SQL> CREATE USER <username> identified by <password>
    SQL> ALTER USER <username> ENABLE EDITIONS;
  2. While still connected to SQL*Plus, execute the following commands to create the edition:
    SQL> CREATE EDITION sample_ed;
    SQL> GRANT USE ON sample_ed TO <username>;
  3. If the edition-enabled user is going to rename tables and create views, then the following permissions must be granted:
    GRANT CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE VIEW, CREATE PROCEDURE, CREATE TRIGGER TO <username>;
Run the WebLogic Services Upgrade Scripts

Use SQL*Plus to run the packaged EBR scripts from the WebLogic Services directory. These scripts upgrade the existing WebLogic Server system tables in the database from non-EBR to EBR-enabled.

Use SQL*Plus to connect and execute the following commands to upgrade the existing WebLogic Server database tables. Make sure that you are connecting with the edition-enabled user. Note that the scripts are located in multiple directores and are part of the WebLogic Server standalone installation.
  1. Connect to SQL*Plus and run the following scripts to create the tables.
    $ sqlplus <user-connection-string>
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/oracle_ebr/upgrade_js_ddl.sql -- rename/cover WEBLOGIC_TIMERS
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/diagnostics/oracle_ebr/upgrade_wls_events_ddl.sql -- rename/cover VIEW WLS_EVENTS
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/diagnostics/oracle_ebr/upgrade_wls_hvst_ddl.sql -- rename/cover WLS_HVST
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/oracle_ebr/upgrade_lstbs.sql -- rename/cover ACTIVE
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/batch/oracle_ebr/upgrade_checkpoint_data_ddl.sql -- rename/cover CHECKPOINTDATA
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/batch/oracle_ebr/upgrade_execution_instance_data_ddl.sql -- rename/cover EXECUTIONINSTANCEDATA
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/batch/oracle_ebr/upgrade_job_instance_data_ddl.sql -- rename/cover JOBINSTANCEDATA
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/batch/oracle_ebr/upgrade_job_status_ddl.sql -- rename/cover JOBSTATUS
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/batch/oracle_ebr/upgrade_step_execution_instance_data_ddl.sql -- rename/cover STEPEXECUTIONINSTANCEDATA
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/batch/oracle_ebr/upgrade_step_status_ddl.sql -- rename/cover STEPSTATUS
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/servletsess/oracle_ebr/upgrade.sql -- rename/cover WL_SERVLET_SESSIONS
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/wanpersist/oracle_ebr/upgrade.sql -- rename/cover WLS_WAN_PERSISTENCE_TABLE
    
  2. Verify that all of the tables have been EBR-enabled before continuing to the next step.
Run the Create Table Scripts

Use SQL*Plus to run the packaged EBR scripts from the WebLogic Services directory. These scripts will create the required tables and EBR-enable them automatically.

The WebLogic Server administrator or the database administrator must run the scripts. If you created these tables in a previous release, run the scripts again to ensure you have the latest changes. The scripts will rename the exisiting tables, or, if needed, create new tables with an underscore, and then create the editioning views.
  1. Connect to SQL*Plus and execute the following commands to create the tables. Note that the scripts are located in multiple directores.
    Make sure that you are connecting as the edition-enabled user.

    $ sqlplus <user-connection-string> 
    SQL> ALTER SESSION SET EDITION = sample_ed;
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/oracle_ebr/crejstbs.sql -- creates WEBLOGIC_TIMERS
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/oracle_ebr/crelstbs.sql -- creates ACTIVE
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/batch/oracle_ebr/jbatch.sql -- creates JOBINSTANCEDATA, EXECUTIONINSTANCEDATA, STEPEXECUTIONINSTANCEDATA, JOBSTATUS, STEPSTATUS, CHECKPOINTDATA
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/diagnostics/oracle_ebr/wls_events_ddl.sql -- creates WLS_EVENTS
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/diagnostics/oracle_ebr/wls_hvst_ddl.sql -- creates WLS_HVST
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/servletsess/oracle_ebr/create.sql -- creates WL_SERVLET_SESSIONS
    SQL> @<WLS_HOME>/oracle_common/common/sql/wlsservices/wanpersist/oracle_ebr/create.sql -- creates WLS_WAN_PERSISTENCE_TABLE
    
  2. Verify that all of the tables have been created before continuing to the next step.
Set the New Edition as the Default

Once you have verified that all of the tables have been created and the new edition is working as expected, set it as the default edition.

  1. The WLS administrator or DBA will then make the new edition the default.
    SQL> ALTER DATABASE DEFAULT EDITION = sample_ed;
  2. If the data source is to specify the edition explicitly, then use WLST to set it.
    $ wlst
    wlst> readDomain('/path/to/domain')
    wlst> cd('/JDBCSystemResource/my-ds/JdbcResource/my-ds/JDBCDriverParams/NO_NAME_0/Properties/NO_NAME_0/Property/oracle.jdbc.editionName')
    wlst> cmo.setValue('SAMPLE_ED')
    wlst> updateDomain()
Restart the WebLogic Server Domain

After you have created the system tables, restart the WebLogic domain.

See Starting and Stopping Servers in Administering Server Startup and Shutdown for Oracle WebLogic Server.

Upgrading a Domain that Uses an Evaluation Database

The evaluation database is provided for use by the sample applications and code examples and may be used as a demonstration database. As of WebLogic 10.3.3, the evaluation database that is available from the installation program is changed from PointBase to Derby.

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 Server 14.1.1.0.0, complete the following steps:

  1. When installing WebLogic Server 14.1.1.0.0 as described in Prepare for the Upgrade, you must use the full installer. The full installer does not preserve the PointBase installation from the previous WebLogic Server installation.
  2. Complete the steps described in Upgrade Your Application Environment and Completing Post-Upgrade Tasks.

    The domain's configuration settings for PointBase are preserved.

  3. Obtain a PointBase license, available from http://www.pointbase.com.
  4. Restore your PointBase installation. PointBase is installed in the WL_HOME/common/eval/pointbase directory.
  5. Add the PointBase database JARs at the beginning of the CLASSPATH environment variable definition.