This chapter describes how to upgrade Oracle Communications Services Gatekeeper from versions 5.0, 5.0.0.1, and 5.1 to version 6.0. Upgrades are supported on the Linux, Solaris, and Windows operating systems.
For more information about supported operating systems, see "Services Gatekeeper System Requirements".
During the upgrade process, each server in the domain, one at a time, is stopped, upgraded to the new version, and then re-started. This process upgrades the WebLogic Server and the Services Gatekeeper core services, but leaves all communication services unchanged.
After all servers have been upgraded, the communication services in use need to be upgraded. You do this by using in-production redeployment, which is a WebLogic Server feature that enables the communication services to be upgraded without any traffic interruption.
After the upgrade, the security identity of Services Gatekeeper is the same as it was before the upgrade.
The high-level workflow is:
Gracefully shut down each Services Gatekeeper server.
Upgrade each server. See "Upgrading Servers" for details.
Deploy new Services Gatekeeper applications.
Verify that new traffic is processed.
You should always upgrade the servers in this order:
Administration server
First Access Tier server
First Network Tier server
Second Access Tier server
Second Network Tier server
Oracle strongly recommends that you back up configuration data prior to the upgrade. See ”Managing, Backing Up, and Restoring Services Gatekeeper” in Services Gatekeeper System Administrator's Guide for more information.
The following restrictions apply when upgrading Services Gatekeeper:
Do not make configuration changes during the upgrade process until all of the servers in the cluster have been upgraded. This is especially important for new configuration options. Services Gatekeeper servers ignore settings that are not understood, and the local configuration file may not be updated properly.
During the upgrade, the location of the old Services Gatekeeper installation and the location of the new Services Gatekeeper installation must be in two different directories.
In addition to the placeholders described in "Placeholders Used in this Guide", Table 11-1 describes the directories and values that are specific to upgrading.
Table 11-1 Upgrade-Specific Placeholders
| Placeholder | Description |
|---|---|
|
new_Middleware_home |
The new Middleware home directory is the directory under which you install Services Gatekeeper 6.0. Middleware home is the repository for common files that are used by Oracle Communications service delivery products such as Services Gatekeeper, WebLogic Server, and Java Development Kit. |
|
new_Services_Gatekeeper_home |
The directory in which the new version of the Services Gatekeeper software is installed. By default, this is new_Middleware_home/ocsg. |
|
old_version |
The two-digit version number, without periods, of the existing Services Gatekeeper version to be upgraded. For example, 51 represents version 5.1. |
|
new_version |
The two-digit version number, without periods, of the new Services Gatekeeper version to which you are upgrading. For example, 60 represents version 6.0. |
|
new_Domain_home |
The directory in which you create the new Services Gatekeeper domain. By default, this is a subdirectory of the old_Middleware_home/user_projects/domains directory. |
To upgrade a server, perform the following on each machine that hosts your Administration Server, Access Tier server, and Network Tier server:
If your old version of Services Gatekeeper includes Services Gatekeeper Reports, undeploy your Services Gatekeeper Reports application EAR file (edr_to_analytic.ear), which is located in the new_Middleware_home/ocsg/applications directory.
For more information about using the Administration Console to undeploy applications, see ”Deploying and Undeploying Communication Services and Plug-ins” in Services Gatekeeper System Administrator's Guide.
Stop the server gracefully so that all processing requests are completed before the shutdown begins.
For information about how to stop a server by using the Administration Console, see ”Starting, Stopping, and Administering Servers” in Services Gatekeeper System Administrator's Guide.
Note:
In high-volume traffic situations, you may encounter an excessively long shutdown period. Set a Graceful Shutdown Timeout or enable the Ignore Sessions During Shutdown option to remedy that behavior.For information about controlling graceful shutdowns, see the section about controlling graceful shutdowns in Oracle WebLogic Server Administration Console Online Help at
http://docs.oracle.com/cd/E24329_01/apirefs.1211/e24401/taskhelp/startstop/ControlGracefulShutdowns.html
Install JDK 1.7.0_55 or higher on your system and set the JAVA_HOME environment variable.
Download the JDK from the Java page on the Oracle Technology Network website at:
Install the new version of Services Gatekeeper in the new_Middleware_home directory. Do not configure a domain.
During the upgrade, the location of the old installation and the location of the new installation must be in two different directories.
See "Installing Services Gatekeeper" for details.
If you are upgrading Reports, perform the tasks described in "Upgrading Services Gatekeeper Reports".
(Administration server only) Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory.
(Administration server only) Unzip the migration.zip archive into the upgrade directory.
The migration subdirectory is created.
(Administration server only) Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade/migration/old_version directory.
(Administration server only) Change the permissions for the old_version directory:
chmod +x oldversion
(Administration server only) At a command prompt, enter one of the following:
On Solaris and Linux:
sh runConfigurationMigration.sh DatabaseType DatabaseHost DatabasePort DatabaseName DatabaseUsername DatabasePassword
On Windows:
runConfigurationMigration.bat DatabaseType DatabaseHost DatabasePort DatabaseName DatabaseUsername DatabasePassword
where:
DatabaseType is either Oracle or MySQL.
DatabaseHost is the host name of the database server.
DatabasePort is the port number through which the database host listens.
DatabaseName is the name of the database or service hosting the Services Gatekeeper data.
DatabaseUsername is the user name that will access the Services Gatekeeper database.
DatabasePassword is the password for the database user.
Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory, and open the undeploy.py file in a text editor.
Edit the following parameters:
AdminServerListenAddress: The IP address of the Administration Server.
AdminServerListenPort: The listen port of the Administration Server.
adminName: The main administrator user name.
adminPassword: The main administrator password.
serverName: The name of the server that is hosting the Administration Server.
Save and close the file.
Ensure that the Administration Server is running.
For more information, see ”Starting and Stopping Servers” in Services Gatekeeper System Administrator's Guide.
From the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory, enter the following at the command line:
sh new_Middlware_home/wlserver/common/bin/wlst.sh undeploy.py
Shut down all Administration Servers, Access Tier servers, and Network Tier servers.
For more information, see ”Starting and Stopping Servers” in Services Gatekeeper System Administrator's Guide.
To upgrade the Administration Server, perform the following on the system hosting your Administration Server:
Ensure that you are using the correct version of the JDK and that the JAVA_HOME environment variable is set correctly.
Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory, and open the build.properties file in a text editor.
Edit the following parameters:
server.name: The name of the Administration Server.
adminurl: The address of the Administration Server using the following format:
URIscheme://IPaddress:Port
For example:
t3://10.111.22.33:7001
username: The main administrator user name.
password: The main administrator password.
admin.host: The name of the server that is hosting the Administration Server.
admin.port: The listen port of the Administration Server.
production.mode: Set this to true for production systems and to false for demonstration systems.
domain51.home: The directory in which your old Services Gatekeeper domain resides.
domain51.name: The name of your old Services Gatekeeper domain.
bea51.home: The old_Middleware_home directory.
wlsold.home: The directory in which old Services Gatekeeper release installed WebLogic Server.
bea60.home: The new_Middleware_home directory.
wlsnew.home: The directory in which Services Gatekeeper 6.0 installed WebLogic Server.
ocsg.home: The directory in which Services Gatekeeper 6.0 is installed.
Save and close the build.properties file.
At a command prompt, enter the following:
ant upgrade
Restart the Administration Server.
To upgrade the Access Tier, perform the following on the Access Tier server:
Note:
If your Access Tier server and Administration Server are installed in the same location, skip this step.Set the necessary environment variables.
Windows: Run the script new_Middleware_home\wlserver\common\bin\commEnv.cmd
Solaris and Linux: Source the script new_Middleware_home/wlserver/common/bin/commEnv.sh
Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory and open the build.properties file in a text editor.
Edit the following parameters:
server.name: The name of the Administration Server.
adminurl: The address of the Administration Server using the following format:
URIscheme://IPaddress:Port
For example:
t3://10.111.22.33:7001
username: The main administrator user name.
password: The main administrator password.
admin.host: The name of the server that is hosting the Administration Server.
admin.port: The listen port of the Administration Server.
production.mode: Set this to true for production systems and to false for demonstration systems.
domain51.home: The directory in which the Services Gatekeeper 5.1 domain resides (old_Domain_home).
domain51.name: The name of your Services Gatekeeper 5.1 domain.
bea51.home: The old_Middleware_home directory.
wlsold.home: The directory in which Services Gatekeeper 5.1 installed WebLogic Server.
bea60.home: The new_Middleware_home directory.
wlsnew.home: The directory in which Services Gatekeeper 6.0 installed WebLogic Server.
ocsg.home: The directory in which Services Gatekeeper 6.0 is installed.
Save and close the build.properties file.
At a command prompt, enter the following:
ant upgrade
Restart the Access Tier server.
To upgrade the Network Tier, perform the following on the Network Tier server:
Note:
If your Network Tier and Administration Server are installed in the same location, skip this step.Set the necessary environment variables.
Windows: Run the script new_Middleware_home\wlserver\common\bin\commEnv.cmd
Solaris and Linux: Source the script new_Middleware_home/wlserver/common/bin/commEnv.sh
Go to the new_Middleware_home/wlserver/common/templates/scripts/upgrade directory and open the build.properties file in a text editor.
Edit the following parameters:
server.name: The name of the Administration Server.
adminurl: The address of the Administration Server using the following format:
URIscheme://IPaddress:Port
For example:
t3://10.111.22.33:7001
username: The main administrator user name.
password: The main administrator password.
admin.host: The name of the server that is hosting the Administration Server.
admin.port: The listen port of the Administration Server.
production.mode: Set this to true for production systems and to false for demonstration systems.
domain51.home: The directory in which the Services Gatekeeper 5.1 domain resides (old_Domain_home).
domain51.name: The name of your Services Gatekeeper 5.1 domain.
bea51.home: The old_Middleware_home directory.
wlsold.home: The directory in which Services Gatekeeper 5.1 installed WebLogic Server.
bea60.home: The new_Middleware_home directory.
wlsnew.home: The directory in which Services Gatekeeper 6.0 installed WebLogic Server.
ocsg.home: The directory in which Services Gatekeeper 6.0 is installed.
Save and close the build.properties file.
At a command prompt, enter the following:
ant upgrade
Restart the Network Tier server.
Redeploy the rest.jar application, which is located in the new_Middleware_home/ocsg/applications directory.
Stop the Administration Server.
Go to the old_domain_home/config directory and open the config.xml file in a text editor.
Set the <source-path> parameter to new_Middleware_home/ocsg/applications/rest.jar. For example:
<library>
<name>rest-core#1.0@1.0.0.0</name>
<target>WLNG_NT_Cluster,WLNG_AT_Cluster</target>
<module-type xsi:nil="true"></module-type>
<source-path>${OCSG6.0_Home}/ocsg/applications/rest.jar</source-path>
<security-dd-model>DDOnly</security-dd-model>
</library>
Save and close the config.xml file.
(Complete steps 25 through 29 if you use Node Manager) Open the new_Middleware_home/wlserver/server/bin/startNodeManager.sh file in a text editor.
Add this line to the JAVA_OPTIONS:
JAVA_OPTIONS="${JAVA_OPTIONS} -Djava.security.egd=file:/dev/./urandom"
Copy the old_Middleware_home/welserver_10.3/common/nodemanager directory to new_Middleware_home/oracle_common/common.
Delete all files in the new new_Middleware_home/oracle_common/common/nodemanager directory except nodemanager.domains and nodemanager.properties.
Start Node Manager on all servers by running this script:
new_Middleware_home/wlserver/server/bin/startNodeManager.sh
Restart your servers in the following order: Administration Server, then first Access Tier server, then second Access Tier server, then first Network Tier server, and then second Network Tier server.
Redeploy the pubsub-1.0.war application, which is located in the Middleware_home/wlserver/common/deployable-libraries/ directory.
Stop the Administration Server.
Go to the old_domain_home/config directory and open the config.xml file in a text editor.
Replace the following text:
<library>
<name>pubsub#1.0@1.7.0.0</name>
<target>WLNG_AT_Cluster</target>
<module-type>war</module-type>
<source-path>${OCSG5.1_HOME}/wlserver_10.3/common/deployable-libraries/pubsub-1.0.war</source-path>
<security-dd-model>DDOnly</security-dd-model>
</library>
with this text:
<library>
<name>pubsub#1.0@3.0.0.0</name>
<target>WLNG_AT_Cluster</target>
<module-type>war</module-type>
<source-path>${OCSG6.0_HOME}/wlserver/common/deployable-libraries/pubsub-1.0.war</source-path>
<security-dd-model>DDOnly</security-dd-model>
<staging-mode xsi:nil="true"></staging-mode>
<plan-staging-mode xsi:nil="true"></plan-staging-mode>
<cache-in-app-directory>false</cache-in-app-directory>
</library>
Save and close the config.xml file.
Restart your Administration Server, then your first Access Tier server, and then your second Access Tier server.
Follow the procedure in "Deploying New Services Gatekeeper Applications".
After upgrading, you must undeploy all deprecated applications and redeploy the new Services Gatekeeper applications. You do this by using the hitless upgrade procedure. For more information about hitless upgrades, see the following:
”Upgrading and Redeploying Communication Services and Service Interceptors” in Services Gatekeeper System Administrator's Guide
”Redeploying Applications in a Production Environment” in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.
To deploy the new Services Gatekeeper applications:
Undeploy the following deprecated application EAR files:
wlng_nt_oauth2.ear
wlng_nt_portal.ear
Deploy the new Portal Server, Parlay, and XQoS application EARs files, which are located in the new_Middleware_home/ocsg/applications directory:
wlng_nt_oauth2.ear
wlng_at_qos_px40.ear
wlng_at_rest_portal_service.ear
oracle.sdp.daf.externalaction-6.0.0.0.jar (must be named ”DafExternalActions” when deployed)
wlng_nt_portal.ear
daf-multitier-at.ear (for cluster implementations only)
daf-multitier-nt.ear (for cluster implementations only)
daf.war (for standalone implementations only)
Redeploy the Services Gatekeeper 6.0 communication services application EAR files, which are located in the new_Middleware_home/ocsg/applications/ directory:
wlng_nt_qos.ear
wlng_nt_session.ear
wlng_nt_call_notification_px21.ear
wlng_nt_multimedia_messaging_px21.ear
wlng_nt_presence_px21.ear
wlng_nt_sms_px21.ear
wlng_nt_terminal_location_px21.ear
wlng_nt_device_capabilities_px30.ear
wlng_nt_terminal_status_px21.ear
wlng_nt_third_party_call_px21.ear
wlng_nt_subscriber_profile_ews.ear
wlng_nt_push_message_ews.ear
wlng_nt_multimedia_messaging_mm7.ear
wlng_nt_native_smpp_sms.ear
wlng_nt_payment_px30.ear
wlng_nt_address_list_px30.ear
wlng_nt_acr_px21.ear
wlng_at_portal_service.ear
wlng_at_acr_parlay_rest.ear
wlng_at_address_list_px30.ear
wlng_at_addresslist_parlay_rest.ear
wlng_at_oauth2.ear
wlng_at_session.ear
wlng_at_callable_policy.ear
wlng_at_call_notification_px21.ear
wlng_at_multimedia_messaging_px21.ear
wlng_at_presence_px21.ear
wlng_at_sms_px21.ear
wlng_at_terminal_location_px21.ear
wlng_at_device_capabilities_px30.ear
wlng_at_terminal_status_px21.ear
wlng_at_third_party_call_px21.ear
wlng_at_subscriber_profile_ews.ear
wlng_at_push_message_ews.ear
wlng_at_multimedia_messaging_mm7.ear
wlng_at_payment_px30.ear
interceptors.ear
xparam_interceptors.ear
wlng_at_payment_parlay_rest.ear
wlng_at_sms_parlay_rest.ear
wlng_at_terminallocation_parlay_rest.ear
wlng_at_multimedia_messaging_parlay_rest.ear
wlng_prm.ear
wlng_nt_native_ucp_sms.ear
wlng_at_qos_rest.ear
Redeploy the new Reports application EAR file, which is located in the new_Middleware_home/ocsg/applications directory.
edr_to_analytic.ear
Reconfigure your Services Gatekeeper Reports.
For more information, see ”Managing StatisticService” in Services Gatekeeper System Administrator's Guide.
The general process for removing the old Services Gatekeeper files after upgrading includes:
Making a backup copy of the old Services Gatekeeper middleware_home directory and its subdirectories
Removing the contents of the old middleware_home directory except for the domain_home directories if you locate them under middleware_home. You can safely remove everything under the old middleware_home except for the domain_home and its subdirectories. If your domain_home is not under middleware_home you can safely just remove everything in middelware_home.
Starting the new Services Gatekeeper servers to ensure that they work correctly.
Then you can remove the backup copy of the old Services Gatekeeper implementation.
You upgrade Services Gatekeeper Reports by upgrading the reports database schema and then deploying the new repository and catalog files.
To upgrade Services Gatekeeper Reports:
Go to the Middleware_home/wlserver/common/templates/scripts/upgrade directory.
Unzip the analytics_migration.zip archive into the upgrade directory.
The analytics_migration directory is created.
Go to the Middleware_home/wlserver/common/templates/scripts/upgrade/analytics_migration directory.
At a command prompt, enter one of the following:
On Solaris and Linux:
sh runConfigurationMigration.sh DatabaseHost DatabasePort DatabaseName DatabaseUsername DatabasePassword
On Windows:
runConfigurationMigration.bat DatabaseHost DatabasePort DatabaseName DatabaseUsername DatabasePassword
where:
DatabaseHost is the host name of the database server to be used for reports data.
DatabasePort is the port number through which the reports database host listens.
DatabaseName is the name of the database or service hosting the reports data.
DatabaseUsername is the user name that will access the reports database.
DatabasePassword is the password for the database user.
Your reports database schema is now upgraded.
Start the Oracle Business Intelligence Administration Tool.
For more information about starting and using the Oracle Business Intelligence Administration Tool, see "About the Oracle BI Administration Tool" in Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.
In the Oracle Business Intelligence Administration Tool, open the Middleware_home/ocsg/ext/analytics/edr.rpd file.
Modify the repository file's orcl and blockInit database connection, user name, and password properties to reference your database.
For instructions about configuring RPD files, including changing the password and setting database connection information, see ”Importing Metadata and Working with Data Sources” in Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition.
Transfer the edr.rpd file to the machine hosting your Oracle Business Intelligence installation.
Copy the catalog.zip archive from the Middleware_home/wlserver/common/templates/scripts/upgrade/analytics_migration directory to the machine hosting your Oracle Business Intelligence installation.
Unzip the catalog.zip archive into the Oracle_instance/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obips1/catalog/edr6 directory.
Redeploy the repository file and catalog file:
Login to the Fusion Middleware Control Console.
In the Navigator, click Farm_bifoundation_domain, expand Business Intelligence, and then expand coreapplication.
Click the Deployment tab and then click the Repository tab.
Specify the repository file (edr.rpd) location and password.
Specify the catalog location as Oracle_instance/bifoundation/OracleBIPresentationServicesComponent/coreapplication_obips1/catalog/edr6.
Click Activate Changes.
Click Restart.
For more information, see ”Using Fusion Middleware Control to Upload a Repository and Set the Oracle BI Presentation Catalog Location” in Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.
This section provides remedies for common problems that occur after a Services Gatekeeper upgrade.
New versions of Services Gatekeeper may upgrade the Oracle Coherence version. Because of that, sometimes the upgraded server cannot join servers running the earlier version because of the version mismatch. To fix this issue:
Edit the script new_Middleware_home/wlserver/common/templates/scripts/upgrade/configCoherence.py and update the following variables:
ADMIN_USER_NAME: The WebLogic administrator user name.
ADMIN_PASSWORD: The WebLogic administrator password.
ADMIN_URL: The WebLogic administration console URL.
FIRST_TIME: Set this to true if this is the first Network Tier server you are upgrading; false otherwise.
Run the script using the following command:
# . ../../../bin/wlst.sh configCoherence.py
Sometimes an upgraded Services Gatekeeper has a different OAuth 2.0 EBJ home instance from other Network Tier servers and is not be able to join the cluster. To fix this issue:
Start the Network Tier server's Administration Console:
http://server_address:port/console
Note:
The default Administration Console port is 7001.In the Change Center panel, click Lock & Edit.
In the Domain Structure panel, select your Services Gatekeeper domain and then select Deployments.
In the Summary of Deployments pane, select wlng_nt_outh2 and then select the Targets tab.
Select wlng_nt_oauth2, and click Change Targets.
Under Clusters, select Part of the cluster, and deselect the server that cannot join the cluster. Click Yes.
In the Change Center, click Activate Changes.
Restart the other Network Tier servers in the cluster.
Following the same procedure above, reset the wlng_nt_oauth2 targets to All servers in the cluster, and click Yes.
Restart the server that could not rejoin its cluster.