13 Upgrading Production WebRTC Session Controller Software

This chapter provides general instructions for upgrading Oracle Communications WebRTC Session Controller software to a new Service Pack release. The service pack may contain additional tools or instructions for performing the upgrade which may supersede the information in this chapter. Refer to those instructions if they are available.

Overview of System Upgrades

Because a typical production WebRTC Session Controller installation uses multiple server instances, upgrading the WebRTC Session Controller software requires that you follow very specific practices. These practices ensure that:

Existing clients of deployed SIP Servlets are not interrupted or lost during the upgrade procedure.
The upgrade procedure can be "rolled back" to a previous state if any problems occur.

The sections that follow describe how to use a configured load balancer to perform a "live" upgrade of the WebRTC Session Controller software on a production installation.

When upgrading the WebRTC Session Controller software (for example, in response to a Service Pack), a new engine tier cluster is created to host newly-upgraded engine tier instances. One-by-one, servers in the engine tier are shut-down, upgraded, and then restarted in the new target cluster. While servers are being upgraded, WebRTC Session Controller automatically forwards requests from one engine tier cluster to the other as necessary to ensure that SIP data tier requests are always initiated by a compatible engine tier server. After all servers have been upgraded, the older cluster is removed and no longer used. After upgrading the engine tier cluster, servers in the SIP data tier may also be upgraded, one-by-one.

Requirements for Upgrading a Production System

To upgrade a production WebRTC Session Controller installation you need:

A compatible load balancer product and administrator privileges for reconfiguring the load balancer virtual IP addresses and pools.
Adequate disk space on the Administration Server system and on each Managed Server system for installing a copy of the new WebRTC Session Controller software.
Privileges for modifying configuration files on the WebRTC Session Controller Administration Server system.
Privileges for shutting down and starting up individual Managed Server instances.
Three or more replicas in each partition of the SIP data tier, to upgrade the WebRTC Session Controller software to a new version. With fewer than three replicas in each partition, it is not possible to safely upgrade a production SIP data tier deployment as no backup replica would be available during the upgrade procedure.

Caution:
Before modifying any production installation, thoroughly test your proposed changes in a controlled, "stage" environment to ensure software compatibility and verify expected behavior.

Upgrading to a New Version of WebRTC Session Controller

Follow these steps to upgrade a production installation of WebRTC Session Controller to a newer Service Pack version of the WebRTC Session Controller software. These instructions upgrade both the SIP Servlet container implementation and the SIP data tier replication and failover implementation.

The steps for performing a software upgrade are divided into several high-level procedures:

Configure the Load Balancer: Define a new, internal Virtual IP address for the new engine tier cluster you will configure.
Configure the New Engine Tier Cluster: Create and configure a new, empty engine tier cluster that will host upgraded engine tier servers and your converged applications.
Define the Cluster-to-Load Balancer Mapping: Modify the SIP Servlet container configuration to indicate the virtual IP address of each engine tier cluster.
Duplicate the SIP Servlet Configuration: Copy the active sipserver.xml configuration file to duplicate your production container configuration.
Upgrade Engine Tier Servers and Target Applications to the New Cluster: Shut down individual engine tier server instances, restarting them in the new engine tier cluster.
Upgrade SIP Data Tier Servers: Shut down individual SIP data tier servers, restarting them with the new SIP data tier software implementation.

The sections that follow describe each procedure.

Configure the Load Balancer

Begin the software upgrade procedure by defining a new internal virtual IP address for the new engine tier cluster you will create in "Configure the New Engine Tier Cluster". The individual server IP addresses (the pool definition) for the new virtual IP address should be identical to the pool definition of your currently-active engine tier cluster. Figure 13-1 shows a sample configuration for a cluster having three engine tier server instances; both virtual IP addresses define the same servers.

Figure 13-1 Virtual IP Address Configuration for Parallel Clusters

Description of "Figure 13-1 Virtual IP Address Configuration for Parallel Clusters"

See your load balancer documentation for more information about defining virtual IP addresses.

In the next section, you will configure the WebRTC Session Controller domain to identify the virtual IP addresses that map to each engine tier cluster. WebRTC Session Controller uses this mapping during the upgrade procedure to automatically forward requests to the appropriate "version" of the cluster. This ensures that SIP data tier requests always originate from a compatible version of the WebRTC Session Controller engine tier.

Configure the New Engine Tier Cluster

Follow these steps to create an Engine Tier cluster to host upgraded containers, and to configure both clusters in preparation for a software upgrade:

On the Administration Server system, install the new WebRTC Session Controller software into a new ORACLE_HOME\Middleware home directory. The steps that follow refer to c:\Oraclenew as the home directory in which the new software was installed. c:\Oracle refers to the software implementation that is being upgraded.
Log in to the Administration Console for the active WebRTC Session Controller domain.
In the Administration Console, create an empty engine tier cluster for hosting the upgraded engine tier servers:
1. In the left pane, select the Environment node, and then select the Clusters node.
2. Click New to configure a new cluster.
3. Enter a name for the new cluster.
4. Select Unicast or Multicast for the Messaging Mode.
5. Enter a Unicast Broadcast Channel, or Multicast Address and Multicast Port number for the cluster.
6. Click OK to create the cluster.
Proceed to "Define the Cluster-to-Load Balancer Mapping".

Define the Cluster-to-Load Balancer Mapping

In this procedure, you configure the cluster-to-load balancer mapping to define the internal, virtual IP address that is assigned to the older and newer engine tier clusters.

To define the cluster-to-load balancer mapping:

Log in to the Administration Console for the active WebRTC Session Controller domain.
In the Administration Console, create a load balancer map entry for the new cluster you created:
1. In the left pane, select the SipServer node.
2. Select Configuration, then select the Loadbalancer Map tab.
3. Click New to create a mapping.
4. Enter the Cluster Name and SIP URI of the new cluster you created in Configure the New Engine Tier Cluster.
5. Click Finish to create the new mapping.
Repeat Step 2 to enter a mapping for the older cluster. For example, create an entry for "EngineCluster" and "sip:172.17.0.1:5060".

You must include a mapping for both the older and the newer engine tier cluster. A mapping consists of the internal virtual IP address of the cluster configured on the load balancer and the cluster name defined in the WebRTC Session Controller domain. Example 13-1 shows an entry in the sipserver.xml file for the sample clusters described earlier.

Example 13-1 Sample cluster-loadbalancer-map Definition

<sip-server>
... 
  <cluster-loadbalancer-map>
      <cluster-name>EngineCluster</cluster-name>
      <sip-uri>sip:172.17.0.1:5060</sip-uri>
   </cluster-loadbalancer-map>
   <cluster-loadbalancer-map>
      <cluster-name>NewEngineCluster</cluster-name>
      <sip-uri>sip:172.17.0.2:5060</sip-uri>
   </cluster-loadbalancer-map>
</sip-server>

Duplicate the SIP Servlet and WebRTC Session Controller Configurations

Before upgrading individual engine tier servers, you must ensure that the SIP Servlet container configuration, SIP data tier configuration, and the WebRTC Session Controller configuration in the new engine tier cluster matches your current production configuration.

To duplicate the SIP Servlet container configuration, copy your production sipserver.xml configuration file to the new installation. For example:

cp c:\Oracle\Middleware\user_projects\domains\mydomain\config\custom\*.xml c:\Oraclenew\Middleware\user_projects\domains\mydomain\config\custom

To duplicate the WebRTC Session Controller configuration, copy your production configuration files to the new installation. For example:

cp c:\Oracle\Middleware\user_projects\domains\mydomain\config\wsc\*.xml c:\Oraclenew\Middleware\user_projects\domains\mydomain\config

As engine tier servers are restarted in the new engine tier cluster in the next procedure, they will have the same configuration but will use the new container implementation.

Upgrade Engine Tier Servers and Target Applications to the New Cluster

To upgrade individual engine tier servers, you gracefully shut each server down, change its cluster membership, and then restart it. Follow these steps:

Access the Administration Console for your production domain.
Select the first running engine tier server that you want to upgrade:
1. Select Environment, then select the Servers tab in the left pane.
2. Select the Control tab in the right pane.
3. Select the name of the server you want to upgrade.
Select Shutdown, then select When work completes from the table.

The server remains active while clients are still accessing the server, but no new connection requests are accepted. After all existing client connections have ended or timed out, the server shuts down. Other server instances in the engine tier process client requests during the shutdown procedure.
Select Environment, then select the Servers tab in the left pane and verify that the Managed Server has shut down.
Change the stopped server's cluster membership so that it is a member of the new engine tier cluster:
1. Expand the Environment node, and the select the Clusters tab in the left pane.
2. Select the name of the active engine tier cluster.
3. Select Configuration, and then select the Servers tab in the right pane.
4. Select the check box next to the name of the stopped server, and click Remove.
5. Click Yes to remove the server from the cluster.
6. Next, expand the Environment node, then select the Clusters tab and select the newly-created engine tier cluster ("NewEngineCluster").
7. Select Configuration, then select the Servers tab in the right pane.
8. Click Add to add a new server.
9. Select the name of the stopped server from the drop-down list.
10. Click Finish.
Restart the stopped managed server to bring it up in the new engine tier cluster:
1. Access the system on which the stopped engine tier server runs (for example, use a remote desktop on Windows, or secure shell (SSH) on Linux).
2. Use the available Managed Server start script (startManagedWebLogic.cmd or startManagedWebLogic.sh) to start the Managed Server. For example:
```
startManagedWebLogic.cmd engine-server1 t3://adminhost:7001
```
In the Administration Console, select Environment, then select the Servers node and verify that the Managed Server has started.
Repeat these steps to upgrade the remaining engine tier servers.

At this point, all running Managed Servers are using the new SIP Container implementation and are hosting your production SIP Servlets with the same SIP Servlet container settings as your old configuration.

Applying Software Patches and Updates

Oracle may occasionally release software patches and updates to address known bugs and limitations in the WebRTC Session Controller software. To update WebRTC Session Controller, you apply patches using the Oracle OPatch utility.

See "Patching with OPatch" in Oracle Fusion Middleware Documentation for more information on how to update your WebRTC Session Controller installation.