Overview This article illustrates how you can create a custom 'program' action that is triggered when a selection of events is raised.  The action will seek to take the appropriate debugging or remedial action to address the problem associated with each event. Candidate actions If a node fails, we will capture network traffic to and from that node If a node begins to underperform, we will obtain process information from that node If the number of file descriptors gets too low, we will generate a report of file descriptor usage If the Traffic Manager encounters a FATAL problem, we will generate a technical support report To help us create and debug the event handler, we'll first create a very simple debugging action.  Go to the System -> Alerting -> Manage Actions page. Create a Program Action named 'Debug Problem', and configure it to call /bin/echo: Creating the Action To help us create and debug the event handler, we'll first create a very simple debugging action.  Go to the System -> Alerting -> Manage Actions page. Create a Program Action named 'Debug Problem', and configure it to call /bin/echo: The program (/bin/echo) is passed two parameters by default: the name of the event type that triggered the action and information about the specific event reported within that event type. This will suffice for now - we will add more arguments later when we have finished writing the program. Creating an event type   Next, we create a set of events (an 'event type') that will trigger the action:   Go to System -> Alerting -> Manage Event Types and create a new event type called 'Problems to Debug'. You will be presented with a list of all the events that Traffic Manager can catch in a tree structure. Select the following events:   Nodes -> General Events -> Serious Errors -> Node has failed SLM Classes -> Information Messages -> Node information when SLM is non-conforming General -> Warnings -> Running out of free file descriptors General -> ZXTM Software -> Internal software error   Save the event type by clicking 'Update' Linking the event type to the action   The next step is to configure Traffic Manager to trigger the action when one of the events in our event type occurs.   Go to the System -> Alerting page and select the 'Problems to Debug' event type from the drop-down box at the bottom of the page. The event type will appear in the list of mappings alongside a drop-down box containing a list of all the actions that have been configured. Select the 'Debug Problem' action from the list.     It would also be useful to receive a notification that some debug output has been produced, so select 'E-Mail' from the list of actions as well. Click 'Update' to save the changes and then, if you haven't already done so, configure the E-Mail action to use your mail server and e-mail address.   Writing the Program   Currently the 'Debug Problem' action will not do anything useful when it is triggered, so we need to write a program for it to run.  The code for this program is attached to this article.   The program examines the event information it receives and, for certain events, performs some debugging actions. The program determines which event it is handling by matching the primary tag (as presented in the 'Event Type' configuration list). When a node fails... The Perl program looks for the 'nodefail' tag, then extracts the name of the node and its port from the message.   if( $message =~ /\tnodefail\t/ ) { my( $node, $port ) = ( $1, $2 ) if $message =~ /\tnodes\/(\S+):(\d+)\t/; }   It then starts capturing traffic going between Traffic Manager and that node to see if there are any clues as to what is causing the failure. The node might, for example, be ignoring invalid requests from a particular client, thus causing the passive monitoring feature of Traffic Manager to mark it as failed. `tcpdump -c 1000 -n -s 0 -i any -w $diagnostic_file host $node`;   The captured traffic is then sent to a different machine so it can be analysed.   `scp $diagnostic_file $scpuser\@$scpdest`;   The program uses scp to send the information, which usually requires a password to be entered to access the remote machine. Because scp is being invoked by the program there is no opportunity to enter a password. To get around this problem, you can configure scp to contact a particular remote machine without requiring a password. Alternatively, if no location is passed to the program, it will just write the files to a specific location on the Traffic Manager machine so you can access them manually.   When Traffic Manager encounters a problem...   If there is a problem with Traffic Manager, the program will create a technical support report that you can send to the support team should you need further assistance with the problem. Information about the specific problem that occurred in the software will be sent in the notification e-mail that we configured earlier.   `$ENV{ZEUSHOME}/zxtm/bin/support-report $diagnostic_file`; When the number of free file descriptors is running low... If Traffic Manager detects that it is running low on free file descriptors, the program will obtain information about current memory usage, disk usage, active connections and file descriptor settings.   `ulimit -a >> $diagnostic_file`; `vmstat -s >> $diagnostic_file`; `df -h >> $diagnostic_file`; `netstat -an >> $diagnostic_file`;   By examining this information, you should be able to determine why the system is running low on file descriptors. Often it is because the maximum number of file descriptors (as reported by ulimit) is too low, though it could also be caused by the system running out of memory or disk space or there simply being an abnormally high number of active connections. When a Service Level Monitoring class fails... Finally, if SLM fails the program is triggered with the 'slmnodeinfo' event that identifies which nodes contributed to the SLM failure. In this case, the program will log on to the nodes in question and obtain information about the running processes to see what is going wrong. To do this it uses rsh, which means that you need to have the appropriate permissions configured in the '.rhosts' files on each node to allow the machine running Traffic Manager to access them without a password.   `rsh -l $rshuser $node "ps -eo pid,ppid,rss,vsize,pcpu,pmem,cmd -ww --sort=-pcpu" >> $diagnostic_file`; `rsh -l $rshuser $node "vmstat -s" >> $diagnostic_file`; Testing the program The program also looks out for a 'testaction' event, which is reported when you use the 'Update and Test' button on the action page. We will use this later to make sure the program is working correctly and copies the debug output to the correct location.   Adding the Program to Traffic Manager   We can now configure the 'Debug Problem' action to use the correct program. Upload the program to Traffic Manager's Action Programs catalog (in the 'Extra Files' section.)     Go to System -> Alerting -> Manage Actions, and edit the Debug Problem action; change the program from 'Custom...' to the program you just uploaded.   You will have noticed that the program takes several arguments beyond just the event information. These arguments include the location to which files should be sent and the scp and rsh usernames to use when connecting to remote machines. You can use the 'Argument Descriptions' section of the page to configure the action to supply these arguments. After expanding the Argument Descriptions section, enter 'rshuser' into the name box and 'Username used to log on to failing nodes' in the description box. Click update and then add the remaining arguments - scpuser and scpdest - in the same way.   The arguments will appear in the 'Additional Settings' section where you can configure them with the appropriate values for your system. Click 'Update' to save the configuration and scroll down to the Additional Settings section again. The command that will be executed when the action is triggered is shown at the bottom of this section:       It would also be helpful to enable 'Verbose' mode on the action at this point so any problems that occur are reported in the Event Log.   If you want to test the program out, click 'Update and Test' from the Debug Problem action's page and you should find a file called 'test-event.txt' in the location you put in the 'scpdest' parameter. If not then double check that you can use scp to copy files from the Traffic Manager machine to that location without requiring any user interaction.   If you did get the file then when any of the events in the 'Debug Problems' event type occur you will receive some additional debugging information! ... View more

Array types in TrafficScript   Arrays store a collection of values indexed by an integer value - essentially they are a numbered list of TrafficScript variables:   $chickens = [ "nugget", "emily", "henrietta", "chelsea" ];   Array indexes start at 0, representing the first item in the list, and extend up to the size of the array - so the last index will be the number of items in the array, less one. Arrays can store any value in any index, including other arrays.   Arrays can be created by specifying a list of values separated by commas and surrounded by [ ] characters. Alternatively you can create an array of a specific size that is filled with a default value by using the array.create() function:   $array = [ 1, 2, 3 ]; # An array of size 3, containing the numbers 1, 2 and 3 $array = array.create( 10, "foo" ); # An array of size 10, each element is the string "foo"   To look up a value in an array, specify the array variable that contains the value you want to look up, followed by the index of the value enclosed in [ ] characters:   $array = [ 1, 2, 3 ]; $value = $array[0]; # $value will be set to 1 (indexes start at 0)   Similarly, to insert a value into an existing array, specify the array and the index into which you want to insert the value, followed by an '=' and the value you want to insert:   $array = [ 1, 2, 3 ]; $array[1] = "hello"; # the number 2 will be replaced by the string "hello"   You cannot insert into an index that does not exist - if you do, a warning will be printed in the Event Log and the array will remain unchanged:   $array = [ 1, 2, 3 ]; $array[3] = "Goodbye"; # This will print a warning and the array will be unchanged   Arrays can be expanded by adding new values to the end using the array.push() function, and they can also be shrunk by removing values from the end with the array.pop() function:   $array = [ 1, 2, 3 ]; array.push( $array, "Goodbye" ); $value = $array[3]; # $value will be set to "Goodbye" $value2 = array.pop( $array ); # $value2 will also be set to "Goodbye" $array[3] = "Au revoir"; # This will print a warning because 'pop' # shrunk the array back to 3 values   Hashes in TrafficScript   Hashes are very similar to arrays, however they are indexed by a string value rather than an integer value. Unlike arrays, you do not have to ensure that a particular index already exists before looking it up or before inserting a value into it.   Hashes are created by listing pairs of 'keys' (the string index of a value) and their values, separated by =>:   # Create a new hash $hash = [ "name" => "Andy", "occupation" => "Engineer", "height" => 5.11 ];   To look up a value in a hash, you specify the key that indexes the value you want after the hash variable, enclosed in [ ] characters:   $height = $hash["height"]; # $height will now be 5.11   You can add any key/value pair to the hash at any time, it does not need to exist in the hash before you add it:   # You can add a new key/value pair at any time $hash["drink"] = "Tea";   Arrays and hashes can contain any TrafficScript data type, including other arrays and hashes. You can index into multiple levels of arrays and hashes by adding additional indexes to the lookup:   # You can add the hash to another hash! $employees["andy"] = $hash; # You can then perform multiple lookups to get the values you want $occupation_andy = $employees["andy"]["occupation"];   To remove a value from the hash you can use the hash.delete() function:   hash.delete( $hash, "height" ); # the height/5.11 pair will now # be removed from the hash   Enumeration   The foreach loop is the easiest way to iterate over an array or hash and perform some actions with each value it contains:   foreach( $var in $array ) { ... # $var will be set to each element of $array in turn }   For example, the http.listHeaderNames() function returns an array containing the name of each header supplied by an HTTP request. If you want to log all the headers in a request then the foreach loop comes in very handy:   # Log all of the header names and values $headers = http.listHeaderNames(); foreach( $header in $headers ) { log.info($header . "=" . http.getHeader($header)); }   If you want to show the headers in alphabetical order, you can apply the array.sort() function to the array in the foreach loop:   foreach( $header in array.sort( $headers ) ) { ... }   Iterating over the values of a hash can be done in a similar way when using the hash.keys() function. This function returns an array containing all the keys in the hash with which there are associated values. You can then use the foreach loop to iterate over these keys and look them up in the hash.   You can therefore use the new http.getHeaders() function as an alternative way to print out all the headers in an HTTP request. The function returns a hash mapping all the header names in the request to their values. To print them all you could write:   $headers = http.getHeaders(); foreach( $header in hash.keys( $headers ) ) { log.info( $header . "=" . $headers[$header] ); }   The output will be the same as that from the previous http.listHeaderNames() example, except that the order in which the headers are printed might differ. The order of the keys returned by hash.keys() is not guaranteed.   Read more   Collected Tech Tips: TrafficScript examples ... View more

Augmenting the Web with Stingray Traffic Manager (04/05/2010) This article illustrates how you can use Stingray Traffic Manager to personalize and enhance the websites you visit. Augmented browsing allows you to get the content you want presented to you in the way that you want - a feature that is becoming increasingly rare as more and more data becomes available on the Internet. By using Stingray Traffic Manager to augment websites you can see the effects in any browser without having to install extra plugins. Even better - all this can be achieved with a free development licensed version of Stingray Traffic Manager! Although you would traditionally expect to find Stingray Traffic Manager deployed in front of a series of web servers, making sure that everything runs smoothly for the users accessing a website, it can be used in many other scenarios involving network traffic. Many of these applications don't require the traffic manager to process large volumes of traffic and so are perfectly suited for use with a development license that is restricted only by the number of requests that can be processed every second. This article explores one such application: using TrafficScript to personalize and augment websites. Augmented Browsing The basic principle of augmented browsing is that a website generates and delivers content to you, which is then examined and rewritten using rules that you specify, before being given to the browser to render. Perhaps the most well known example of augmented browsing technology is <a href="http://www.greasespot.net/" target="_blank">*Greasemonkey*</a> . Greasemonkey is a fantastic tool for post-processing websites, however it is not available in all browsers and requires an extension to be installed in others. There are also some inconsistencies when running the same scripts under different browsers. Using Stingray Traffic Manager to augment websites offers a browser-independent solution that doesn't require any add-ons and can be used by anyone accessing the web through your traffic manager. Some of the possible uses for augmented browsing include: Altering the style of a website - for example changing the colors, or highlighting certain parts of the website. Enhancing existing content, such as expanding shortened URLs, or adding links to related information. Adding new content - for example adding buttons to social networking sites that perform multiple operations, such as accepting or rejecting all invitations. Filtering out unwanted parts of a website, such as adverts, comments, videos, or explicit words. Configuring Stingray Traffic Manager First of all, you'll need a copy of the traffic manager! If you don't already have one, you can obtain a copy of it along with a free developer license <a href="http://www.zeus.com/downloads/developers/" target="_blank">*here*</a> . Then next step is to configure the traffic manager to proxy your web requests - as follows: Creating a Service When you have the traffic manager up and running, create a new virtual server by going to Services > Virtual Servers. In theCreate a new virtual server section, enter a name, such as 'HTTP Proxy', set the protocol to HTTP, the port to 8080 (this port is typically used by HTTP proxies) and the default traffic pool to 'discard'. You will now have a service that, when started, will receive requests on port 8080 and discard them. Not very useful! Instead you need to tell the service to send all requests to their target URLs. This will be done using TrafficScript, but first the traffic manager will need to know how to handle the requests that are being sent out - for example, how long it should wait for responses. Creating a Pool To provide these settings you will need to create a pool. To do this, go to Services > Pools and in the Create a new Pool section, enter 'HTTP Proxy Pool' for the name and enter any valid hostname and port for the nodes, such as 'localhost:5678', as no requests will actually be sent there. Leave the monitor field set to 'No Monitor'. The default pool settings will suffice for now, so no further changes are necessary. Proxying Requests TrafficScript can now be used to forward the incoming requests to the correct location. Create a new TrafficScript rule for the HTTP Proxy service you created earlier by going to Services > Virtual Servers > HTTP Proxy > Rules and clicking Manage Rules in Catalog under Request Rules. In the Create a new rule section, enter 'Forward Proxy' as the name and select 'Use TrafficScript Language', then click 'Create Rule' (leave the 'associate with virtual server' check box ticked). This will create a new rule and associate it with your HTTP Proxy service. The service is going to be receiving requests from your browser that look like this: GET <a title="http://www.zeus.com/about/index.html" href="http://www.zeus.com/about/index.html" target=_blank>*http://www.zeus.com/about/index.html*</a> HTTP/1.1 What it needs to do to operate as an HTTP proxy is to discover the hostname from the URL (in this case, <a title="www.zeus.com" href="http://www.zeus.com/" target=_blank>*www.zeus.com*</a> ) and forward the request there with the protocol and hostname removed from the Request-URI and the hostname added as a Hostheader field as follows: GET /about/index.html HTTP/1.1 Host: <a title="www.zeus.com" href="http://www.zeus.com/" target=_blank>*www.zeus.com*</a> The following code will achieve that - just copy and paste it into the rule and click 'Update': $url = http.getRawURL(); if( string.startsWith( $url, "/" ) ) { # Not a typical request to a proxy - get the destination # from the Host header instead $host = http.getHostHeader(); } else if( string.startsWith( $url, "http://" ) || string.startsWith( $url, "https://" ) ) { # A typical request to a proxy - strip off the protocol # and the path so we just have the hostname $host = string.substring( $url, string.find( $url, "://" ) + 3, string.length( $url ) - 1 ); $host = string.substring( $host, 0, string.find( $host, "/" ) - 1 ); # Set the host header to be the hostname http.setHeader( "Host", $host ); } # Find out to which port we should be sending the request $port = 80; if( string.regexmatch( $host, "^(.*):( d+)$" ) ) { $host = $1; $port = $2; } # Strip off the protocol and hostname from the Request-URI http.setPath( http.getPath() ); # Forward the request pool.use( "HTTP Proxy Pool", $host, $port ); The rule simply grabs the hostname (either from the Request-URI as discussed above, or from the Host header if it doesn't exist), sets the Request-URI to be just the path portion of the incoming URL and then forwards the request to the destination host and port using the settings specified in the 'HTTP Proxy Pool' pool you created earlier. Configuring the Virtual Server There are a few additional settings needed to make this service forward requests properly. In Services > Virtual Servers > HTTP Proxy > Connection Management expand the HTTP-Specific Settings section and set add_cluster_ip to No. Under Cookie Settings set cookie!domain to 'Rewrite the domain to the host header of the request'. Under Location Header settings setlocation!rewrite to 'Nothing'. These settings are useful only when sending requests to internal servers. Streaming Responses You're almost done setting things up now! The final task is to make sure that responses are streamed back efficiently to the browser. If the contents of the responses are going to be modified then the body data of the response must be read. By default, the traffic manager will read in the entire body of the response before making any modifications to it so your browser won't be able to start rendering the content immediately. To remedy this, you can use the HTTP streaming feature of TrafficScript to modify data as it arrives and immediately stream it to the browser. Create a response rule for your service by going to Services > Virtual Servers > HTTP Proxy > Rules and clicking Manage Rules in Catalog under Response Rules. Under Create a new rule enter the name 'Proxy Response' and select 'Use TrafficScript Language' again. Paste the following code into the rule and save it: if( string.startswith( http.getResponseHeader( "Content-Type" ), "text/html" ) ) { # Start streaming all HTML responses http.stream.startResponse( http.getResponseCode(), http.getResponseHeader( "Content-Type" ) ); while( 1 ) { # Get the next line of data $data = http.stream.readResponse( 4096, "\n" ); # See if we've reached the end of the response if( $data == "" ) { break; } # ... Here is where we will make modifications to the response ... # Write the data to the client http.stream.writeResponse( $data ); } # Stop streaming the response http.stream.finishResponse(); } This rule will stream data to the browser as it is received, but will also allow you to make modifications to it, line-by-line, as it arrives. Finally, start up the service by going to the front page of the traffic manager and clicking the play button next to the HTTP Proxy service. Now you're all set to use the traffic manager as a proxy! Configuring your Browser to use the Proxy In your browser's advanced settings, enter the traffic manager's hostname and port 8080 (or whichever port you chose to run the service on) as the HTTP proxy settings and start browsing the web. If everything worked then you should be able to browse the web as normal - but you will also see some activity in the status applet within the traffic manager's user interface. If something has gone wrong then double check that the rules match those presented above, and that all the necessary settings have been changed - and feel free to leave a comment! ... View more

Customized Load-Balancing with Stingray (07/03/2009) Choosing the right load-balancing algorithm can often be difficult as every web application behaves differently. Stingray offers a wide variety of built-in load-balancing algorithms to overcome this problem, but if none of these suit your needs then you can just design your own! This article shows you how. Introduction Typically, an application server will start to slow down when it becomes overloaded. Its response times will increase and it will not be able to handle as many connections. Stingray can easily detect these problems and start directing traffic away from that server. Stingray's 'Fastest Response Time' and 'Least Connections' algorithms are two examples that will accomplish exactly this task. Sometimes, though, there will be a particular application that just doesn't let on when it is busy. It will soldier on with impeccable response times right up until the server crashes from the excessive load. None of Stingray's built-in load balancing algorithms would be able to detect this problem until the server has actually crashed. Customized Load-Balancing This is an ideal situation to use a custom load-balancing algorithm that can gather whatever information it likes and use that to influence where Stingray will send its requests. In this case, we would like to use the server's CPU utilization so we can tell Stingray to back off sending requests to a particular server when its resources are running low. The algorithm would therefore be effective regardless of how quickly the server is responding to requests. To create a customized load-balancing algorithm, you can use the Weighted Round Robin algorithm for your pool and then use Stingray’s SOAP API to alter the weighting of each node in that pool depending on how busy it is. You can gather information from the nodes and make SOAP calls from a program running on the same machine as your Stingray, or on another machine on the network that can access both the SOAP API of your Stingray and the all nodes in the pool that you want to load balance. The following is a general outline of what such a program should do: Get a list of the nodes in the pool being load-balanced Gather data from each node in the list Process the data to work out which nodes should receive the most traffic Set the weighting of each node in the pool accordingly Wait for a few seconds, then repeat An Example This is the source code of a simple Perl program that will find out how busy the CPU of each node in the pool is and use that information to determine what the node's priority should be: <a href="http://blogs.riverbed.com/files/monitornodes.pl.txt" target=_blank>*Perl source code*</a> (save as monitorNodes.pl and make it executable) The program takes as arguments the location of the SXTM's SOAP interface (this will be the same as the location you browse to when accessing the Administration Server), the username and password used to access the SOAP interface and the name of the pool to which you want to apply the custom load-balancing algorithm. ./monitorNodes.pl myzxtm:9090 admin admin MyPool The program has several internal parameters that you can change to customize how requests will be distributed: Metric: This is the command that will be executed on each node to obtain the information used to determine the nodes' priorities. The command used in this case is: vmstat 5 This command returns information about the resources being used by a system, such as how much memory is available and how active the CPU is, once every 5 seconds. You can increase or decrease the frequency of the reports if your CPU utilization is likely to change more slowly or more rapidly. We just want to find out how busy the CPU is, but vmstat reports a lot of additional information around this. To extract the information we need, there are additional functions specified in the main body of the code that pull out the relevant information from the output returned by vmstat and ensure it is within a reasonable range. If you want to use a different metric, you can modify this code to extract the relevant data from the output generated by your command. Ceiling: This number indicates the point at which the node should be given the minimum priority. In this example we use 80 so that when the CPU is 80% utilized it will be assigned the minimum possible priority relative to the other nodes in the pool. This will give the server a bit of leeway to recover once it starts to become overloaded. If the ceiling parameter is set to 0 then the program will assign priorities based on how heavily the server is loaded relative to the other nodes in the pool. This is useful if there is no upper limit to the metric being reported (for example, if it were to report the current number of requests being served). Granularity: This parameter effectively defines how often the priorities should be updated. If set to 100, then nodes will be assigned priorities between 1 and 100, so if the idle CPU time on a node changes by about 1% then the priority of that node will be changed. In this example, we set the granularity to 10, so only large changes in the idle time result in the program making a SOAP call to Stingray. When executed, the program will check the pool you specified, get a list of the nodes, obtain the CPU utilization for each of the nodes, calculate the priorities of each node based on that information and then send a command to Stingray to update the weights of the nodes accordingly! It will continue to monitor the CPU usage of the nodes and will update the weightings once every 5 seconds. SSH Commands Note that the program uses SSH to run the commands that obtain the CPU utilization for each node. You will have to enter the password for each node every time you start the program unless you configure SSH to allow you to log on without a password. A quick search for 'passwordless ssh' provides plenty of information on how to do this. Alternatively, if you would prefer not to perform the commands using SSH, you could modify the program to listen for information from the nodes on an internet socket. You would then need to run separate programs on each of the nodes that send the desired information to this socket. Once the program has information from all the nodes it can calculate the priorities as before. ... View more

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. Introduction 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="https://community.brocade.com/t5/Articles/Introducing-Event-Handling-in-Stingray-Traffic-Manager-5-1-12-08/m-p/23250/highlight/true#M81" 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="http://www.textanywhere.net/" 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 Overview 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. Arguments 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: INFO: vservers/Olympus vsstart 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="https://support.riverbed.com/docs/stingray/trafficmanager.htm" 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 = "10.100.25.25"; exit if system ( "ifconfig -a | grep $token > /dev/null" ); } Replace the '10.100.25.25' 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. ... View more