Explore SailFin cluster, high availability features using Basic3pcc sample application
The "Basic3pcc" sample demonstrates a simple Third Party Call Control (3pcc) application in SailFin.
This blog describes how to explore out-of-box cluster and high availability features of SailFin using this sample.
First read my previous blog post to get the overall understanding of this sample.
Instructions to deploy Basic3pcc sample to SailFin cluster
- Download the latest SailFin from here. Follow this link to unbundle and configure your SailFin.
- Set the environment variables SF_HOME=<your sailfin installation dir>, HOST_IP_ADDRESS=<your actual ip address, not localhost/127.0.0.1>
- % cd SF_HOME/samples/sipservlet/Basic3pcc
It would point to the sailfin sample 'Basic3pcc' direcotry
- % SF_HOME/lib/ant/bin/ant
It would check your environment variable settings and it would display the available targets for use.
- % SF_HOME/lib/ant/bin/ant setup-cluster
it would setup a SailFin cluster as shown in figure below:
Figure 1. SailFin cluster having 4 instances with instance1 used exclusively as a front-end for this demo.
- % SF_HOME/lib/ant/bin/ant deploy-cluster
It would deploy both 3pccConvergedApp.sar and 3pccRegistrarAndProxy.sar files on SailFin cluster with high-availability-enabled=true.
- [Optional step] % SF_HOME/lib/ant/bin/ant build
Execute this step only if you want to modify this sample and rebuild the sample yourself. If you do this step, you need to redeploy the sample using step (6).
Instructions to execute the Basic3pcc sample application
- Setup your X-Lite softphones using platform specific steps (1) - (4) described in the CallSetup sample application's "Instructions execute the sample application" section by pointing to Telco AS:15060 instead of Telco AS:5060
While configuring make sure that the X-Lite listens on the correct IP address, not on localhost/127.0.0.1. For example, in Linux this can be done by specifying the IP address at Menu > System Settings > Network > Listen on IP.
As mentioned in the instruction, you need to register both Alice's and Bob's X-Lite phones with SailFin. The registration happens as per the figure below:
Figure 2. Registration of SIP phones of Alice and Bob with SailFin cluster
- Now Browse to http://<your-host>:<your-port>/3pcc (eg., http://localhost:18080/3pcc) and login as Alice. Use Alice as the the password.
Note that the sample has pre-provisioned list of users which are Alice, Bob, Adam, Eve (with password same as user name). If you wish to re-provision the users, you can do so by editing SF_HOME/samples/sipservlet/Basic3pcc/userdb.properties file. If you do that then you need to re-build and re-deploy the sample using step (7) & (6) of the above section.
- Once you are logged in, you will see a list of buddies in your web page. Select the radio button against "Bob" and click "Call" button. This will establish a call between you (i.e., Alice) and Bob, as shown in the figure below:
Figure 3. Alice and Bob are talking
Alice's browser will be updated with the call status and call history, as shown in the figure below:
Figure 4. Alice's browser showing the call status and call history
The call establishment between you (i.e., Alice) and Bob is done as per 3pcc, as shown in Figure 4 of my previous blog post
Internal details of how the call establishment between Alice and Bob takes place in the SailFin cluster is described in the figure below:
Figure 5. Internal details of the call establishment between Alice and Bob in the SailFin cluster.
Description of various steps shown in Figure 5:
(1) Alice clicks "Call" Bob@sailfin.org from her browser.
(2) The http request gets routed to instance4.
(3) In instance4, upon receiving the http request, the CallInitiatorServlet (of ConvergedApp) creates INVITE Alice@sailfin.org request and sends it to CLB front-end so that the INVITE request gets forwarded to a different application (RegistrarAndProxyApp in this case).
The reason for forwarding to a different application is because, in real IMS deployments, ConvergedApp is not expected to maintain the location/registration information of the SIP phones, instead registration/location information is maintained by a different application which is RegistrarAndProxyApp in our deployment. So these two need to be separated as different entities.
(4) CLB front-end routes this INVITE request to the correct server instance which has Alice's registration information.
(5) ProxyServlet (of RegistrarAndProxyApp) running in instance4 sends out the INVITE request to Alice's registered location available in Alice's_SipAppSession.
(7) CLB front-end routes this INVITE request to the correct server instance which has Bob's registration information.
(8) ProxyServlet (of RegistrarAndProxyApp) running in instance3 sends out the INVITE request to Bob's registered location available in Bob's_SipAppSession.
Exploring the failover capabilities:
Now, to test the failover, you can stop the instance4 by executing % asadmin stop-instance instance4
After the instance4 is stopped, you can click "Refresh Page" link (as shown in Figure 4) in your web page. Once the page reloads, notice the label at the bottom of the page : "This page is served by SailFin ..." gets changed from instance4 to a different instance. You willl also notice that, all other data i.e., call history, login time are not lost. These data were stored in SipApplicationSession and ConvergedHttpSession respectively, and were replicated, and hence there is no data or session loss when the serving instance was brought down.
The ongoing call between Alice and Bob also gets handled by the different instance when instance4 is brought down. You can check this by clicking "Hang Up" button in Alice's phone. The BYE request sent from Alice's phone gets routed to a different live instance and the ConvergedApp running in that instance will recover/resume Alice's and Bob's SipSessions, and processes the BYE request, and the call gets ended gracefully on both Alice's and Bob's phones.