Showing results for 
Search instead for 
Did you mean: 

Receiving SMS Alerts from Stingray Traffic Manager (01/07/2009)

Not applicable

Receiving SMS Alerts from Stingray Traffic Manager (01/07/2009)

Be alerted at the earliest opportunity to a problem with your websites. This article describes how the new Event Handling feature of Stingray Traffic Manager 5.1 can be used to send a text message to your mobile phone when something critical happens to your services.


Stingray Traffic Manager introduces a new feature in version 5.1 called Event Handling. It allows you to map a selection of events, for example a node failing or a license key expiring, to certain actions, such as sending an e-mail or executing a program. This article describes how you can use a program action to configure Stingray Traffic Manager to send you SMS text messages when a particular events occurs. If you are unfamiliar with event handling in Stingray Traffic Manager 5.1 then you might want to read the article

<a href="" target="_self">*Introducing Event Handling in Stingray Traffic Manager 5.1*</a>

before continuing.

Before you proceed

Before configuring Stingray Traffic Manager you will need an SMS gateway. An SMS gateway converts any messages it receives into mobile network traffic, allowing you to send text messages without a mobile phone.

In this article we use a service provided by

<a href="" target="_blank">*TextAnywhere*</a>

, but there are many alternatives to this. The TextAnywhere service provides several interfaces for sending messages, including a Web Services (SOAP) interface, a HTTP and HTTPS interface and an SNMP interface. Stingray Traffic Manager could use any one of these interfaces to contact the gateway, but for the purposes of this example we shall use the HTTP interface.

A Perl program will be used to generate the request that is sent to the gateway as this provides us with maximum control over the content of the messages. After writing the Perl program, we will configure Stingray Traffic Manager to execute it when certain events occur.

The Perl Program


The program will use the httpclient program included with Stingray Traffic Manager 5.1 to create an HTTP POST request and send it to the gateway. The HTTP request will contain all the information the gateway needs to send a text message to the correct phone or phones. A POST request is used in preference to a GET request because sensitive data such as user names and passwords required by the gateway can be encrypted in the body data of the request rather than being contained in its URL.

Source code

The source code of the perl program is available *here *and in the attachment section.


The program takes in two compulsory arguments – a comma-separated list of telephone numbers and the message to send. These values will be provided by Stingray Traffic Manager when it executes the program, along with the optional argument +eventtype+ that specifies what actually triggered the program to be run. There is also an optional +debug+ argument that we will use to test the program.

After checking that all the necessary arguments have been supplied, the program converts the supplied phone numbers into the correct format for the gateway to read. If no country code is specified, it will add a UK country code. $destinations[$i] =~ s/^0/$country_code/;

Creating the message content

Next, the message content is created. The content is derived from the event information passed in to the program by ZXTM as the final argument. This information will most likely contain tab characters, which many mobile phones cannot display, so it needs some modification to make it more mobile-friendly.

The program removes the tabs from the message and adds line breaks and spaces to make the information more readable on a mobile device. It also removes the name of the event for clarity, and adds the value of the eventtype argument that ZXTM gave us (this will be configured to be "SMS Events" later in the article). If ZXTM supplies the following message that indicates the virtual server called Olympus was started:

INFO vservers/Olympus vsstart Virtual server started on port 80

You would receive a text message like this:

SMS Events:




Virtual server started on port 80

Once the message has been formatted, all the information the SMS gateway needs is collected together.

In addition to the list of phone numbers and the message body, the TextAnywhere gateway requires a client ID and password to identify who is sending the message. It also takes a couple of parameters (Client_Ref and Billing_Ref) used to keep track of the messages that you have sent – these can be set to whatever you want.

The Reply_Type parameter is set to 0 because we are not interested in receiving replies to the text messages we send. TheOriginator parameter is what appears in the 'Sender' field on the recipient's phone - this is set to 'Stingray'.

my %params = ( Client_ID => "AB1234567",
Client_Pass => "password",
Client_Ref => "my_company",
Billing_Ref => "zxtm",
Connection => $debug ? 1 : 2,
Originator => "Stingray",
OType => 1,
DestinationEx => $destination,
Body => "$message",
SMS_Type => 0,
Reply_Type => 0

The final parameter that it important to us is the connection parameter. This determines whether the SMS gateway will actually send a text message or just simulate it.

If the debug argument was passed to the Perl program, then we set a value of 1 here, meaning the gateway will not actually send a text message, but will still send back a response indicating whether all the other information was correct or not. A value of 2 will send the message for real.

To send the HTTP request, the Perl program makes use of the httpclient program that is included with Stingray Traffic Manager. The program is invoked in POST mode and is passed the body data of the request – a URL-encoded list of all the parameters we need to send to the gateway. The httpclient program then sends the request off to the gateway:

open FH, "echo '$body' | $httpclient -m POST $url |"

If the gateway received the message successfully, we get a 200 OK response back. In the body data of this response will be a list of all the phone numbers we asked the message to be sent to and a return code indicating whether the message was successfully sent to that number. The program examines this response and reports any messages that failed to send.

Configuring Stingray Traffic Manager

Now you can configure Stingray Traffic Manager to use this program.

First of all, you need to import it into Stingray Traffic Manager . To do this, go to the Catalogs → Extra Files section of the UI. Here you will find several categories of extra files you can upload. The program will be executed by an Action, so go to the Action Programs page and click the 'Browse...' button in the Upload Program section. Select the Perl program from your computer and click 'Upload'.

The next step is to create an Action to use this program. You can access the Actions page using the link at the bottom of the Action Programs page, or you can get to it through System → Alerting → Manage Actions. Create a new action called Send SMSand set the type of the action to be Program.

On the new page that appears, set 'Verbose' to Yes so that any errors in the Perl program that might occur get printed to the Event Log. In the Additional Settings section, choose the program you just uploaded to ZXTM from the drop-down box. Expand the Argument Descriptions section and enter 'destination' into the 'Name' box and 'A comma-separated list of phone numbers to which messages should be sent' into the 'Description' box. Click 'Update' at the bottom of the page.

You should now see an additional piece of information on the page showing exactly what command will be run by this action. It is missing the 'debug' parameter mentioned earlier, so add this to the argument descriptions section and click 'Update' again. Now all that is missing are the values for the destination and debug arguments. Set debug to '1' for now and destination to your mobile phone number and click 'Update'.


Testing the action

At this point you can test the action to make sure it works correctly. Click the 'Update and Test' button and then view the Event Log. You should see “Action Send SMS: Action triggered by test event.” followed by the output of the program, which, if all was successful, should be “(phone number): SMS Sent”.

If any errors were reported then you can try running the Perl program manually using the command shown on the Send SMS action's page and debug any problems from there. If you try testing the action with debug set to 0 you should receive an SMS message to your mobile phone containing the text "Test settings for action 'Send SMS'".

Creating an event type

The final stage in the process is to select what events you would like to receive a text message for. To do this you create an event type.

Go to the System → Alerting → Manage Event Types page. On this page, create a new event type called SMS Events. After creating the event type, you are presented with a list of all the events that you can be notified about. Pick the events that you would like to receive an SMS notification for – in our example we choose the following:

License Keys → Warnings → License key expires within 4 days

Pools → General Events → Serious Errors → Pool has no back-end nodes responding

SLM Classes → Serious Errors → SLM has fallen below serious threshold

SSL Hardware → Serious Errors → SSL hardware support failed

Save your Event Type and go to the System → Alerting page. This is where you link event types and actions - telling ZXTM what you would like to happen when certain events occur. Select the SMS Events event type you just created from the drop-down box on the left and then, in the new drop-down box that appears in the Actions column, select the Send SMS action you created earlier. Finally, click 'Update' to save the mapping.


Now when any of the events you selected in your event type occur you will receive a text message! Depending on what features your chosen SMS gateway provides, you could take this example much further than we have – for example, you could allow recipients to reply to the message and use this reply, in conjunction with Stingray’s SOAP interface, to modify Stingray Traffic Manager's configuration.

If you have multiple Stingray Traffic Managers ...

If you have a cluster of Stingray Traffic Manager machines, you might find that you receive an SMS message from each one in the cluster when one of your selected events occurs. This happens because some events, such as a node failing, are be reported by every machine in a cluster. Each machine will also have access to the Perl program because it is replicated across your cluster when you upload it to Stingray Traffic Manager.

To get around this problem, you can add some additional logic to the Perl program that will ensure only one Stingray Traffic Manager will send a text message for certain events. To do this, you could use the notion of a token.

A text message can only be sent by a Stingray Traffic Manager machine if that machine has the token. Only one machine can have the token at any one time. The token can be implemented very easily using a Traffic IP Address.

Create a local Traffic IP that every machine in your cluster can raise on the Services → Traffic IP Groups page. If the Stingray Traffic Manager that currently has the Traffic IP address goes down then another, functioning Stingray Traffic Manager will pick it up again straight away.


To incorporate this into the program that sends the text message, you can simply run ifconfig and see if the Traffic IP Address you created is currently raised on this machine. If it is, send the message, if not, then quit.

Of course, this should only be done for messages that every Stingray Traffic Manager will send - events raised by TrafficScript functions, for example, will only occur on the machine that is handling that particular connection. In the example event type we created called 'SMS Events', the only event that would be reported on all the Stingray Traffic Managers is 'Pool has no back-end nodes responding'.

The reference documentation

<a href="" target="_blank">*Events in Stingray Traffic Manager*</a>

provides a description of how to identify the event that triggers the program to be run. In this case, the 'Pool has no back-end nodes responding' event can be identified by the 'pooldied' tag. Adding the following code to the top of the sendsms Perl program, just after the $message variable has been filled in, will stop that message getting reported multiple times:

  • if( $message =~ /\tpooldied\t/ ) {
  • # Don't send text messages for events that are reported on all
  • # functioning ZXTM machines if we don't have the Traffic IP
  • # 'token'.
  • my $token = "";
  • exit if system ( "ifconfig -a | grep $token > /dev/null" );
  • }

Replace the '' IP address with the IP address you are using as your token. There are many possible solutions to this problem - the one presented here is very simple but could be improved upon if you desire more robust duplicate message detection.