Configuring and Managing WebLogic SIP Server

Upgrading Software and Applications in a Production Environment

Note: The sections that follow provide only general instructions for upgrading WebLogic SIP Server software and deployed applications. Your service pack or new software may contain additional instructions and tools to help you upgrade the software.

The following sections describe how to upgrade production WebLogic SIP Server installations to a new release of the software, and how to upgrade individual SIP applications on a production server installation:

Overview of System and Application Upgrades

Because a typical production WebLogic SIP Server installation uses multiple server instances in both the engine and data tiers, upgrading the WebLogic SIP Server software, or a SIP Servlet deployed to the engine tier, 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 WebLogic SIP Server software, or a deployed SIP application on a production installation. The procedure for either type of upgrade is similar, but each procedure is described in a separate section for clarity.

When upgrading the WebLogic SIP Server software (for example, in response to a Service Pack), or upgrading a SIP Servlet where the Servlet's session data is incompatible with the older version, a new engine tier cluster is created to host newly-upgraded engine tier instances or new versions of SIP Servlets. 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, WebLogic SIP Server automatically forwards requests from one engine tier cluster to the other as necessary to ensure that 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 data tier may also be upgraded, one-by-one. See Upgrading a Deployed Production Application (Compatible Session Data) for more information.

Requirements for Upgrading a Production System

To upgrade a production WebLogic SIP Server installation you require:

Nostage-mode deployments for existing SIP applications. (Nostage-mode deployment enables you to upgrade a deployed SIP Servlet without performing a redeployment operation, as described in Upgrading a Deployed Production Application (Compatible Session Data).)
Cluster-targeted deployments for all SIP applications. All deployed SIP Servlets must be targeted to the engine tier cluster, rather than to individual Managed Server instances within the cluster. Cluster-level targeting is required in order to perform an upgrade of the WebLogic SIP Server software without disrupting existing clients.
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 machine and on each Managed Server machine for installing a copy of the new WebLogic SIP Server software (for server software upgrades only).
Privileges for modifying configuration files on the WebLogic SIP Server Administration Server machine.
Privileges for shutting down and starting up individual Managed Server instances.
Three or more replicas in each partition of the data tier, in order to upgrade the WebLogic SIP Server software to a new version. With fewer than three replicas in each partition, it is not possible to safely upgrade a production data tier deployment as no backup replica would be available during the upgrade procedure.

Warning: 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 WebLogic SIP Server

Follow these steps to upgrade a production installation of WebLogic SIP Server to a newer version of the WebLogic SIP Server software. These instructions upgrade both the SIP Servlet container implementation and the data tier replication and failover implementation included in the sipserver Enterprise Application (EAR).

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 production 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 Container and Data Tier Configuration—Copy the active sipserver.xml configuration file into the new sipserver application 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 Data Tier Servers—Shut down individual data tier servers, restarting them with the new data tier software implementation.

Each procedure is described in the sections that follow.

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 A-1 shows a sample configuration for a cluster having three engine tier server instances; both virtual IP addresses define the same servers.

Figure A-1 Virtual IP Address Configuration for Parallel Clusters

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 WebLogic SIP Server domain to identify the virtual IP addresses that map to each engine tier cluster. WebLogic SIP Server uses this mapping during the upgrade procedure to automatically forward requests to the appropriate "version" of the cluster. This ensures that data tier requests always originate from a compatible version of the WebLogic SIP Server engine tier.

Configure the New Engine Tier Cluster

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

On the Administration Server machine, install the new WebLogic SIP Server software into a new BEA home directory. The steps that follow refer to c:\beanew as the BEA home directory in which the new software was installed. c:\bea refers to the software implementation that is being upgraded.

On the Administration Server machine, copy the new sipserver application directory into a new directory from which it will be deployed. For example:

cp -r c:\beanew\wlss210\samples\domains\telco\sipserver c:\deployments

In the Administration Console, create a new, empty engine tier cluster for hosting the upgraded engine tier servers:

In the left pane, select the Clusters node.

Select Configure a New Cluster...

Enter a name for the new cluster. For example, "NewEngineCluster."

Click Create to create the cluster.

Proceed to Define the Cluster-to-Load Balancer Mapping.

Note: During the upgrade process you need to target the new sipserver Enterprise Application, as well as your own SIP applications, to the newly-created cluster. However, you cannot target applications to an empty cluster. For this reason, targeting applications to the new cluster occurs only after you have added the first engine tier server to the new cluster in Upgrade Engine Tier Servers and Target Applications to the New Cluster.

Define the Cluster-to-Load Balancer Mapping

In this procedure, you manually edit the active sipserver.xml configuration file to define the cluster-loadbalancer-map element. This XML element defines the internal, virtual IP address that is assigned to the older and newer engine tier clusters.

To define the cluster-to-load balancer mapping:

Move to the directory containing the sipserver.xml configuration file for your production domain. For example:

cd c:\bea\user_projects\domains\mydomain\sipserver\config

Open the sipserver.xml file with a text editor:

notepad sipserver.xml

Add a cluster-loadbalancer-map element definition to the end of the configuration file, before the final </sip-server> line. The full definition 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, as well as the cluster name defined in the WebLogic SIP Server domain. Listing 1-1 shows an entry for the sample clusters described earlier.

Listing 1-1 Sample cluster-loadbalancer-map Definition

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

Save your changes to sipserver.xml and exit your text editor.

Duplicate the SIP Servlet Container and Data Tier Configuration

Before upgrading individual engine tier servers, you must ensure that the SIP Servlet container configuration and data tier configuration in the new engine tier cluster matches your current production configuration. To duplicate the container configuration, copy your production sipserver.xml and datatier.xml configuration files on top of the files in the new sipserver application. For example:

cp c:\bea\user_projects\domains\mydomain\sipserver\config\sipserver.xml c:\deployments\sipserver\config

cp c:\bea\user_projects\domains\mydomain\sipserver\config\datatier.xml c:\deployments\sipserver\config

The sipserver.xml file in both the old and the new sipserver application should now be identical; only the implementation classes for each application are different. As engine tier servers are restarted in the new engine tier cluster in the next procedure, they will have the same SIP container 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:

Expand the Servers tab in the left pane.

Select the name of the server you want to upgrade.

Select the Control->Start/Stop tab in the right pane.

Select Graceful shutdown of this server...

Select Yes to perform the shutdown.

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

Expand the Clusters tab in the left pane.

Select the name of the active engine tier cluster.

Select the Configuration->Servers tab in the right pane.

Select the name of the stopped server in the Chosen column, and use the arrow to move it to the Available column.

Click Apply.

Next, expand the Clusters tab and select the newly-created engine tier cluster ("NewEngineCluster").

Select the Configuration->Servers tab in the right pane.

Select the name of the stopped server in the Available column, and use the arrow to move it to the Chosen column.

Click Apply.

After adding the first engine tier server to the new cluster, you can now target the sipserver Enterprise Application and your own SIP applications to the new cluster.

Note: Perform this step only once, after adding the first engine tier server to the new cluster:

In the left pane, select the Deployments->Applications node.

Select Deploy a new Application...

Using the links in the Location field, select the new sipserver application directory on the Administration Server machine (for example, c:\deployments\sipserver).

Click Target Application.

Select the name of the new engine tier cluster ("NewEngineCluster"). Also ensure that All servers in the Cluster is selected.

Click Continue.

Select the option, I will make the application accessible from the following location.

Click Deploy.

Repeat this step to deploy all of your production SIP applications to the new cluster. Both the new and old engine tier clusters should be configured similarly, except that the new cluster hosts the new sipserver application while the existing cluster hosts the older sipserver application.

Restart the stopped managed server to bring it up in the new engine tier cluster:

Access the machine on which the stopped engine tier server runs (for example, use a remote desktop on Windows, or secure shell (SSH) on Linux).

Use the available Managed Server start script (startManagedWebLogic.cmd or startManagedWebLogic.sh) to boot the Managed Server. For example:

startManagedWebLogic.cmd engine-server1 t3://adminhost:7001

In the Administration Console, 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 (the new sipserver application deployment) and are hosting your production SIP Servlets with the same SIP Servlet container settings as your old configuration. Data tier servers can now be upgraded using the instructions in Upgrade Data Tier Servers.

Upgrade Data Tier Servers

Warning: Your data tier must have three active replicas (three server instances) in each partition in order to upgrade the servers in a production environment. With only two replicas in each partition, a failure of the active replica during the upgrade process will result in the irrecoverable loss of call state data. With only one replica in each partition, the upgrade cannot be initiated without losing call state data.

The procedure for upgrading server instances in the data tier is similar to the procedure for upgrading servers in the engine tier, except that:

No SIP applications are targeted to the newly-created data tier cluster.
No cluster-to-load balancer map is necessary for the parallel data tier cluster.

Apart from these differences, the process for upgrading a data tier cluster involves creating a new cluster for hosting upgraded server instances, targeting the new sipserver application to the new cluster, and restarting individual server instances in the new cluster. While upgrading individual data tier servers, care must be taken to ensure that each partition always contains an two active replicas in each partition to protect against hardware or software failures during the upgrade.

To upgrade data tier servers to a new WebLogic SIP Server implementation:

First perform all previous procedures to upgrade the engine tier servers in your domain. See Upgrading to a New Version of WebLogic SIP Server.

In the Administration Console, create a new, empty data tier cluster for hosting the upgraded data tier servers:

In the left pane, select the Clusters node.

Select Configure a New Cluster...

Enter a name for the new cluster. For example, "NewDataCluster."

Click Create to create the cluster.

Select a running data tier server that you want to upgrade:

Expand the Servers tab in the left pane.

Select the name of the server you want to upgrade.

Warning: Do not shut down a data tier server instance in a partition unless two additional servers in the same partition are available, and both are in the ONLINE state. See Monitoring and Troubleshooting Data Tier Servers for information about determining the state of data tier servers.

Select the Control->Start/Stop tab in the right pane.

Select Graceful shutdown of this server...

Select Yes to perform the shutdown.

The server remains active while engine tier instances are still accessing the server, but no new connection requests are accepted. After all existing connections have ended, the server shuts down. Other replicas in the same data tier partition process engine tier requests for call state data during the shutdown procedure.

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 data tier cluster:

Expand the Clusters tab in the left pane.

Select the name of the active data tier cluster.

Select the Configuration->Servers tab in the right pane.

Select the name of the stopped server in the Chosen column, and use the arrow to move it to the Available column.

Click Apply.

Next, expand the Clusters tab and select the newly-created data tier cluster ("NewDataCluster").

Select the Configuration->Servers tab in the right pane.

Select the name of the stopped server in the Available column, and use the arrow to move it to the Chosen column.

Click Apply.

After adding the first data tier server to the new cluster, target the new sipserver Enterprise Application to the cluster:

Note: Perform this step only once, after adding the first data tier server to the new cluster:

In the left pane, select the Deployments->Applications node.

Select Deploy a new Application...

Using the links in the Location field, select the new sipserver application directory on the Administration Server machine (for example, c:\deployments\sipserver).

Click Target Application.

Select the name of the new data tier cluster ("NewDataCluster"). Also ensure that All servers in the Cluster is selected.

Click Continue.

Select the option, I will make the application accessible from the following location.

Click Deploy.

Restart the stopped managed server to bring it up in the new data tier cluster:

Access the machine on which the stopped data tier server runs (for example, use a remote desktop on Windows, or secure shell (SSH) on Linux).

Use the available Managed Server start script (startManagedWebLogic.cmd or startManagedWebLogic.sh) to boot the Managed Server. For example:

startManagedWebLogic.cmd data-server1 t3://adminhost:7001

In the Administration Console, select the Servers node and verify that the Managed Server has started.

Repeat these steps to upgrade the remaining data tier servers.

After all data tier servers have been upgraded, delete the original data tier cluster:

Select the Clusters node in the left pane.

Select the trash can icon next to the name of the older cluster in the cluster table.

Select Yes to delete the cluster definition.

Finally, delete the original engine tier cluster:

Select the Clusters node in the left pane.

Select the trash can icon next to the name of the older cluster in the cluster table.

Select Yes to delete the cluster definition.

At this point, all running Managed Servers are using the new WebLogic SIP Server data tier implementation (the new sipserver application deployment) and serving call state data to upgraded servers in the Engine Tier.

Upgrading a Deployed Production Application (Compatible Session Data)

This section describes how to upgrade a deployed SIP Servlet to a new version of the same SIP Servlet in a production environment. The instructions that follow assume that the session data used by the new Servlet version is compatible with the older Servlet version. If the session data is incompatible, see Upgrading a Deployed Production Application (Incompatible Session Data) instead.

Warning: In order to upgrade a SIP Servlet using the procedure below, the session state information stored by the new version of the Servlet must be compatible with the older version of the Servlet. If the older and newer Servlets use incompatible session information, you must follow the instructions in Upgrading a Deployed Production Application (Incompatible Session Data) instead.

To upgrade an individual SIP Servlet to a new version:

On the Administration Server machine, make a backup copy of the source files used to deploy the older SIP Servlet version. You may need the older files if you decide to revert to the previously-deployed application. For example:

cd c:\deployments

mkdir myServlet_backup

cp -r myServlet\* myServlet_backup

Replace the current deployment source files with the updated version of the deployment files. For example, if the file list for the new version of the Servlet is the same as the old:

cp -r myNewServlet\* myServlet

If files have been deleted from the old servlet version, delete the original deployment files before copying over the new files: rm -r myServlet\* cp -r myNewServlet\* myServlet
At this point, the source files for the already-deployed SIP Servlet should represent the upgraded Servlet implementation. The currently-active SIP Servlet deployed to the engine tier uses the older version of the implementation.

To deploy the new source files and make the upgraded Servlet implementation active, use the Administration Console to gracefully shutdown a single Managed Server instance in the engine tier, and then restart the same server.

After the server has started and joined the cluster, repeat the previous step for an additional server in the engine tier. Repeat this process until each server in the engine tier has been restarted.

For nostage-mode deployments, the final two steps have the effect of deploying the SIP Servlet using the updated source files.

Warning: It is important that the updated application files are deployed by gracefully shutting down and then restarting individual servers, rather than by simply redeploying the running application. Redeploying an application immediately unloads the application's implementation classes and replaces them with the newer classes. This makes the application unavailable during redeployment and may result in dropped client connections; never redeploy a running application in a production system.

Upgrading a Deployed Production Application (Incompatible Session Data)

This section describes how to upgrade a deployed SIP Servlet to a new version when the session data used by the new Servlet is compatible with the older version. The upgrade procedure is similar to the procedure described in Upgrading to a New Version of WebLogic SIP Server, except that the SIP Servlet container (sipserver application) is not upgraded.

The steps for performing this type of upgrade are divided into these 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 the new version of the SIP Servlet.

Define the Cluster-to-Load Balancer Mapping—Modify the SIP Servlet container configuration to indicate the virtual IP address of each engine tier cluster.

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

Each procedure is described in the sections that follow.

Configure the Load Balancer

Figure A-2 Virtual IP Address Configuration for Parallel Clusters

Virtual IP Address Configuration for Parallel Clusters

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

Configure the New Engine Tier Cluster

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

On the Administration Server machine, copy the new sipserver application directory into a new directory from which it will be deployed. For example:

cp -r c:\beanew\wlss210\samples\domains\telco\sipserver c:\deployments

In the Administration Console, create a new, empty engine tier cluster for hosting the upgraded engine tier servers:

In the left pane, select the Clusters node.

Select Configure a New Cluster...

Enter a name for the new cluster. For example, "NewEngineCluster."

Click Create to create the cluster.

Proceed to Define the Cluster-to-Load Balancer Mapping.

Note: During the upgrade process you need to target your new SIP applications to the newly-created cluster. However, you cannot target applications to an empty cluster. For this reason, targeting applications to the new cluster occurs only after you have added the first engine tier server to the new cluster in Migrate Engine Tier Servers and Target Applications to the New Cluster.

Define the Cluster-to-Load Balancer Mapping

To define the cluster-to-load balancer mapping:

Move to the directory containing the sipserver.xml configuration file for your production domain. For example:

cd c:\bea\user_projects\domains\mydomain\sipserver\config

Open the sipserver.xml file with a text editor:

notepad sipserver.xml

Add a cluster-loadbalancer-map element definition to the end of the configuration file, before the final </sip-server> line. The full definition 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, as well as the cluster name defined in the WebLogic SIP Server domain. Listing 1-1 an entry for the sample clusters described earlier.

Listing 1-2 Sample cluster-loadbalancer-map Definition

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

Save your changes to sipserver.xml and exit your text editor.

Migrate Engine Tier Servers and Target Applications to the New Cluster

To deploy the new version of the SIP Servlet, you gracefully shut each server down, change its cluster membership, and then restart it in the new cluster. Because you target the newer versions of your production applications to the new cluster, restarting server instances in the new cluster deploys the latest application versions. Follow these steps:

Access the Administration Console for your production domain.

Select a running engine tier server that you want to upgrade:

Expand the Servers tab in the left pane.

Select the name of the server you want to upgrade.

Select the Control->Start/Stop tab in the right pane.

Select Graceful shutdown of this server...

Select Yes to perform the shutdown.

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 using the older version of the SIP Servlet, and the WebLogic SIP Servlet implementation automatically forwards requests to the appropriate cluster (using the cluster-to-load balancer map) so that each engine tier accesses the correct version of the application's session data.

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:

Expand the Clusters tab in the left pane.

Select the name of the active engine tier cluster.

Select the Configuration->Servers tab in the right pane.

Select the name of the stopped server in the Chosen column, and use the arrow to move it to the Available column.

Click Apply.

Next, expand the Clusters tab and select the newly-created engine tier cluster ("NewEngineCluster").

Select the Configuration->Servers tab in the right pane.

Select the name of the stopped server in the Available column, and use the arrow to move it to the Chosen column.

Click Apply.

After adding the first engine tier server to the new cluster, you can now target the new SIP applications to the new cluster.

Note: Perform this step only once, after adding the first engine tier server to the new cluster:

In the left pane, select the Deployments->Applications node.

Select Deploy a new Application...

Using the links in the Location field, select the new version of an application on the Administration Server machine.

Click Target Application.

Select the name of the new engine tier cluster ("NewEngineCluster"). Also ensure that All servers in the Cluster is selected.

Click Continue.

Select the option, I will make the application accessible from the following location.

Click Deploy.

Repeat this step to deploy all of your newer SIP applications to the new cluster. Both the new and old engine tier clusters should be configured similarly, except that the new cluster hosts the newer applications while the existing cluster hosts the older applications.

Restart the stopped managed server to bring it up in the new engine tier cluster:

Access the machine on which the stopped engine tier server runs (for example, use a remote desktop on Windows, or secure shell (SSH) on Linux).

Use the available Managed Server start script (startManagedWebLogic.cmd or startManagedWebLogic.sh) to boot the Managed Server. For example:

startManagedWebLogic.cmd engine-server1 t3://adminhost:7001

In the Administration Console, select the Servers node and verify that the Managed Server has started.

Repeat these steps to upgrade the remaining engine tier servers.

After all engine tier servers have been upgraded, delete the original engine tier cluster:

Select the Clusters node in the left pane.

Select the trash can icon next to the name of the older cluster in the cluster table.

Select Yes to delete the cluster definition.

At this point, all running Managed Servers are using the new version of the SIP Servlet.