Pulse Secure vADC

Looking for Installation and User Guides for Pulse vADC? User documentation is no longer included in the software download package with Pulse vTM, so the documentation can now be found on the Pulse Techpubs pages  

Pulse Virtual Traffic Manager contains a GeoIP database that maps IP addresses to location - longitude and latitude, city, county and country.  The GeoIP database is used by the Global Load Balancing capability to estimate distances between remote users and local datacenters, and it is accessible using the geo.* TrafficScript and Java functions.  

Stingray’s SOAP Control API  is published as a collection of WSDL files.  If you want to access the API from Java (for example, in a Java Extension), you will need to create an interface library. This interface library will expose a collection of Java classes and methods that correspond to the methods and structures in Stingray's WSDL specification.   Creating Stingray-API.jar   We'll create a Java archive called Stingray-API.jar to contain the interface library.   This example uses the WSDL-to-Java converter in the Apache axis project (version 1.4) to build the interface library. This process is a little involved; you can download a pre-build Stingray-API.jar from the attachments instead and skip to the 'Using the Interface Library' section.   Get the source and application files   Download the Stingray WSDL files from the Stingray Admin Interface (Help -> Manuals):     Download Apache Axis 1.4 from http://archive.apache.org/dist/ws/axis/1_4/; you'll need the axis-bin package.  Note that the Stingray WSDL files use RPC/encoded, so that are better supported by the legacy Axis 1.4 rather than Apache Axis2.   Download JavaMail from http://www.oracle.com/technetwork/java/javamail/index.html (this article used version 1.4.7).   Unzip these three archives in your working directory, giving you 3 subdirectories - wsdl, axis-1_4 and javamail-1.4.7.   The process assumes that you’ve downloaded and installed the Java JDK and added it to your path.   Build the Stingray-API.jar library   On Windows   Run the WSDL2Java application in Apache axis directory to process each wsdl file and create the Java source files:   C:\> for %F in (wsdl\*.wsdl) do java –cp ;axis-1_4\lib\*;javamail-1.4.7\lib\* org.apache.axis.wsdl.WSDL2Java %F This will create a subdirectory called 'com' containing the source files for the interface library.   Compile these into class files in an obj directory:   C:\> mkdir obj C:\> javac –d obj -cp ;axis-1_4\lib\* com\zeus\soap\zxtm\_1_0\*.java C:\> javac –d obj -cp ;axis-1_4\lib\* com\zeus\soap\zxtm\_1_1\*.java C:\> javac –d obj -cp ;axis-1_4\lib\* com\zeus\soap\zxtm\_1_2\*.java   Create the Stingray-API.jar file from the compiled class files:   C:\> cd obj C:\> jar cf Stingray-API.jar com\zeus   On Linux/Unix/MacOSX   Follow the instructions above, but use the following commands:   $ for F in wsdl/*.wsdl ; do java -cp axis-1_4/lib/*:javamail-1.4.7/lib/* org.apache.axis.wsdl.WSDL2Java $F ; done $ mkdir obj $ javac -d obj -cp :axis-1_4/lib/* com/zeus/soap/zxtm/*/*.java $ cd obj $ jar cf Stingray-API.jar com/zeus   Build the Javadoc documentation   $ mkdir javadoc $ javadoc -d javadoc -classpath :axis-1_4/lib/*:javamail-1.4.7/lib/* -subpackages com.zeus.soap.zxtm   The resulting javadoc package is attached.   Using the Stingray-API.jar interface library   From an application   When you create an application that uses Stingray's Control API, you will need to add Stingray-API.jar to your CLASSPATH. The Stingray-API.jar file has a large number of dependencies; it depends on jar files from the Apache Axis 1.4, Javamail and JavaBeans Activation Framework (JAF) packages. Install these jar package files in your third-party Java library location, such as /usr/share/java.   For an example of a simple application that uses the Stingray-API.jar interface library, check out Tech Tip: Using the SOAP Control API with Java.   From a Java Extension   If you create a Java Extension that uses Stingray's Control API, the easiest way to manage the Stingray-API.jar file and its dependencies is to upload them via the Stingray Admin Interface. The following jar files from the Axis, Javamail and JAF packages will also be required to use Stingray-API.jar:   axis-1_4/lib/axis-ant.jar axis-1_4/lib/axis.jar axis-1_4/lib/commons-discovery-0.2.jar axis-1_4/lib/commons-logging-1.0.4.jar axis-1_4/lib/jaxrpc.jar axis-1_4/lib/saaj.jar axis-1_4/lib/wsdl4j-1.5.1.jar javamail-1.4.7/mail.jar jaf-1.1.1/activation.jar   Stingray-API.jar and dependencies uploaded to the Stingray Admin Interface   Note that axis.jar is listed in the 'Java Extensions' list; this is because it happens to contain a classes that inherit from GenericServlet.   For an example of a Java Extension that uses the Stingray-API.jar library, check out the article Stingray Status - Using the Control API from a Java Extension

The Stingray Configuration Guide document (see Product Documentation) lists all of the tunables that are used to configure Stingray.  Take care if you modify any of these tunables directly, because this will bypass the extensive validation stages in the UI, and refer to Riverbed support if you have any questions.   You can also use the undocumented UI page ‘KeyInfo’ to list all of the tunables that are used to configure Stingray.   https://stingray-host:9090/apps/zxtm/index.fcgi?section=KeyInfo

The following code uses Stingray's Control API to list all the running virtual servers on a cluster. The code is written in Ruby.   listVS.rb    Running the example   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 #!/usr/bin/ruby     require 'http-access2'   require 'soap/rpc/driver'     # Fix these for your admin server, password etc   url  = 'https://10.100.1.31:9090/soap'   user = 'admin'   pass = 'admin'     client = SOAP::RPC: p river.new( url, 'http://soap.zeus.com/zxtm/1.0/VirtualServer/' )   client.add_method( 'getVirtualServerNames' )   client.add_method( 'getEnabled' , 'names' )     client.options[ 'protocol.http.ssl_config.verify_mode' ] = OpenSSL: SSL::VERIFY_NONE   client.options[ 'protocol.http.basic_auth' ] << [ url, user, pass ]       vservers = client.getVirtualServerNames   enabled = client.getEnabled( vservers )     vservers. length . times do |i|       if enabled          puts vservers       end   end   Run the Ruby script as follows:   $ listVS.rb Main website Mail servers Test site   Notes   As well as Ruby 1.8, you will need to install the http-access2 and openssl Ruby packages in order for the HTTPS Basic Authentication used by Stingray's SOAP server to functions correctly.   Read more   Collected Tech Tips: SOAP Control API examples

The following code uses Stingray's Control API to list all the running virtual servers on a cluster. The code is written in Python.   listVS.py #!/usr/bin/python import SOAPpy conn = SOAPpy.WSDL.Proxy("VirtualServer.wsdl") names = conn.getVirtualServerNames() enabled = conn.getEnabled(names) for i in range(0,len(names)): if ( enabled ): print names   Running the example   This code was tested with Python 2.3.5 and version 0.11.5 of the SOAP.py library. Earlier versions of the SOAP.py library (0.8.4) could not correctly parse the WSDL file.   Run the Python script as follows:   $ listVS.py Main website Mail servers Test site   Notes   By default, most SOAP implementations read the location of the SOAP server from the WSDL file (located in ZEUSHOME/zxtm/etc/wsdl. However, for security reasons, the location of the Stingray Admin Server (including the required administrator username and password) is not embedded in the Stingray WSDL files. Most SOAP toolkits allow you to override the location specified in the WSDL file, but Python's SOAP.py module does not. Before you run this example, edit your WSDL files. Look for the soap:address node at the very end of each WSDL file and edit appropriately: <service name="VirtualServer"> <port name="VirtualServerPort" binding="zeusns:VirtualServerBinding"> <soap:address location="https://username:[email protected]:9090/soap" /> </port> </service>   Alternatively, you can programmatically control the endpoints as follows: endpoint_uri = "https://username:[email protected]:9090/soap" conn = SOAPpy.WSDL.Proxy("VirtualServer.wsdl") for method in conn.methods.keys(): conn.methods[method].location = endpoint_uri   Read more Collected Tech Tips: SOAP Control API examples

The following code uses Stingray's Control API to list all the running virtual servers on a cluster. The code is written in PHP 5.   listVS.php #!/usr/bin/php5 <? $conn = new SoapClient( "VirtualServer.wsdl", array( 'login' => "username", 'password' => "password" )); $names = $conn->getVirtualServerNames(); $enabled = $conn->getEnabled( $names ); for ($i=0; $i < count( $names ); $i++) { if ( $enabled[$i] ) print "$names[$i]\n"; } ?> Running the example   Run the PHP script as follows   $ ./listVS.php Main website Mail servers Test site   Notes You may need to enable the SOAP extensions in your php.ini file. Like Python, the PHP Soap toolkit expects to find the location of the SOAP server in the WSDL file, and does not provide any means to override it. However, you can specify the login details from your application, so these do not need to be embedded in the WSDL: <service name="VirtualServer"> <port name="VirtualServerPort" binding="zeusns:VirtualServerBinding"> <soap:address location="https://host:9090/soap" /> </port> </service>   Read more Collected Tech Tips: SOAP Control API examples

The following code uses Stingray's Control API to list all the running virtual servers on a cluster. The code is written in Perl, using the SOAP::Lite module:   listVS.pl #!/usr/bin/perl -w use SOAP::Lite 0.60; # This is the url of the Stingray admin server my $admin_server = 'https://usernameSmiley [email protected]:9090'; my $conn = SOAP::Lite -> uri('http://soap.zeus.com/zxtm/1.0/VirtualServer/') -> proxy("$admin_server/soap"); # Get a list of virtual servers my $res = $conn->getVirtualServerNames(); my @names = @{$res->result}; # Establish which are enabled $res = $conn->getEnabled( \@names ); my @enabled = @{$res->result}; # Print those which are enabled for( my $i = 0; $i <= $#names; $i++ ) { if( $enabled[$i] ) { print "$names[$i]\n"; } } Running the Example   $ ./listVS.pl Main website Mail servers Test site   Notes   To run this example, you will need Perl, SOAP::Lite and IO::Socket::SSL. On Debian-based systems, you may install the packages libsoap-lite-perl and libio-socket-ssl-perl. On RedHat based systems, you'll need the perl-SOAP-Lite and perl-IO-Socket-SSL rpms.   Perl's SOAP::Lite module does not use the WSDL file to perform any type checking, so calling errors will be detected at runtime. The SSL layer is happy to accept self-signed certificates.   Read more   Collected Tech Tips: SOAP Control API examples

The following code uses Stingray's Control API to list all the running virtual servers on a cluster. The code is written in C#.   listVS.cs using System; using System.Net; using System.IO; using System.Security.Cryptography.X509Certificates; public class AllowSelfSignedCerts : IcertificatePolicy { public bool CheckValidationResult( ServicePoint sp, X509Certificate cert, WebRequest request, int problem ) { return true; } } public class listVS { public static void Main( string [] args ) { System.Net.ServicePointManager.CertificatePolicy = new AllowSelfSignedCerts(); string url= "https://host:9090/soap"; string username = "username"; string password = "password"; try { Stingray.VirtualServer p = new Stingray.VirtualServer(); p.Url = url; p.Credentials = new NetworkCredential( username, password ); string[] names = p.getVirtualServerNames(); bool[] enabled = p.getEnabled( names ); for ( int i = 0; i < names.Length; i++ ) { if( enabled ) { Console.WriteLine( "{0}", names ); } } } catch ( Exception e ) { Console.WriteLine( "{0}", e ); } } } Running the example This code works with the .NET 1.1 SDK and with Mono (use the most recent Mono build available from http://www.mono-project.com/). Using .Net 1.1, compile and run this example as follows:   C:\> wsdl -o:VirtualServer.cs -n:Stingray VirtualServer.wsdl C:\> csc /out:listVS.exe VirtualServer.cs listVS.cs C:\> listVS.exe Main website Mail servers Test site   With Mono, compile and run as follows:   $ wsdl -o:VirtualServer.cs -n:Stingray VirtualServer.wsdl $ mcs /out:listVS.exe /r:System.Web.Services VirtualServer.cs listVS.cs $ ./listVS.exe Main website Mail servers Test site   The WSDL interface specifications for the Stingray Control API are located in ZEUSHOME/zxtm/etc/wsdl/.   Notes   Note the use of the IcertificatePolicy derived class to override the default certificate checking method. This allows the application to accept the Stingray's Admin Server's self-signed certificate.   Read more   Collected Tech Tips: SOAP Control API examples

The following code uses Stingray's Control API to list all the running virtual servers on a cluster. The code is written in Java and uses the Stingray-API.jar library described in this article: Java Interface Library.   listVS.java   Make sure to edit the endpoint address (https://username:[email protected]:9090/soap) so that the username, password and host match the admin interface for your Stingray. import com.zeus.soap.zxtm._1_0.*; import java.security.Security; import java.security.KeyStore; import java.security.Provider; import java.security.cert.X509Certificate; import javax.net.ssl.ManagerFactoryParameters; import javax.net.ssl.TrustManager; import javax.net.ssl.TrustManagerFactorySpi; import javax.net.ssl.X509TrustManager; public class listVS { public static void main( String[] args ) { // Install the all-trusting trust manager Security.addProvider( new MyProvider() ); Security.setProperty( "ssl.TrustManagerFactory.algorithm", "TrustAllCertificates"); try { VirtualServerLocator vsl = new VirtualServerLocator(); vsl.setVirtualServerPortEndpointAddress( "https://username:[email protected]:9090/soap" ); VirtualServerPort vsp = vsl.getVirtualServerPort(); String[] vsnames = vsp.getVirtualServerNames(); boolean[] vsenabled = vsp.getEnabled( vsnames ); for( int i = 0; i < vsnames.length; i++ ){ if( vsenabled ){ System.out.println( vsnames ); } } } catch (Exception e) { System.out.println( e.toString() ); } } /* The following code disables certificate checking. * Use the Security.addProvider and Security.setProperty * calls to enable it */ public static class MyProvider extends Provider { public MyProvider() { super( "MyProvider", 1.0, "Trust certificates" ); put( "TrustManagerFactory.TrustAllCertificates", MyTrustManagerFactory.class.getName() ); } protected static class MyTrustManagerFactory extends TrustManagerFactorySpi { public MyTrustManagerFactory() {} protected void engineInit( KeyStore keystore ) {} protected void engineInit( ManagerFactoryParameters mgrparams ) {} protected TrustManager[] engineGetTrustManagers() { return new TrustManager[] { new MyX509TrustManager() }; } } protected static class MyX509TrustManager implements X509TrustManager { public void checkClientTrusted( X509Certificate[] chain, String authType) {} public void checkServerTrusted( X509Certificate[] chain, String authType) {} public X509Certificate[] getAcceptedIssuers() { return null; } } } }   Running the example   To build and run the code, you'll first need to do the following:   Download axis 1.4 from Index of /dist/ws/axis/1_4. You can unzip the axis-bin package in your working directory, or you can install the jar files permanently (e.g. in the JAVAHOME/jre/lib/ext/ directory).   Download the JavaMail library; either unzip the package in your working directory, or install the mail.jar file to the JAVAHOME/jre/lib/ext/ directory.  This package provides class implementations that, though not required, will avoid warning about missing classes   Compile and run the example as follows:   $ javac -cp Stingray-API.jar:axis-1_4/lib/* listVS.java $ jar -cvfe listVS.jar listVS listVS*.class $ java -cp Stingray-API.jar:axis-1_4/lib/*:javamail-1.4.7/lib/*:listVS.jar listVS Main website Mail servers Test site   If you install the Stingray-API, Apache Axis 1.2 and JavaMail libraries in your system classpath, then you don't need to reference them explicity when you build and run this example.   Notes   The bulk of this code disables client certificate checking. Details of the code and surrounding infrastructure are at http://java.sun.com/j2se/1.5.0/docs/guide/security/jsse/JSSERefGuide.html.   Read more   Collected Tech Tips: SOAP Control API examples

The following code uses Stingray's RESTful API to enable or disabled a specific Virtual Server.   The code is written in Ruby.  This program checks to see if the Virtual Server "test vs" is enabled and if it is, it disables it and if it is disabled, it enables it.  A GET is done to retrieve the configuration data for the Virtual Server and the "enabled" value in the "basic" properties section is checked.  This is a boolean value, so if it is true it is set to false and if it is false it is set to true. The changed data is then sent to the server using a PUT.   startstopvs.rb   require 'rest_client' require 'base64' require 'json' vs = "test vs" # Because there is a space in the virtual serve name it must be escaped url = 'https://stingray.example.com:9070/api/tm/1.0/config/active/vservers/' + URI.escape(vs) auth = 'Basic ' + Base64.encode64('admin:admin') begin # Get the config data for the virtual server response = RestClient.get(url, {:authorization => auth}) # Decode the json response. The result will be a hash vsConfig = JSON.parse(response.body) if vsConfig['properties']['basic']['enabled'] # the virtual server is enabled, disable it. We only need to send the data that we # are changing so create a new hash with just this data. newVSConfig = {'properties' => {'basic' => {'enabled' => false}}} puts "#{vs} is enabled. Disable it." else # the virtual server is disabled, enable it newVSConfig = {'properties' => {'basic' => {'enabled' => true}}} puts "#{vs} is disabled. Enable it." end # PUT the new data response = RestClient.put(url, JSON.generate(newVSConfig), {:content_type => :json, :authorization => auth}) rescue => e puts "Error: URL=#{url} Error: #{e.message}" end   Running the example   This code was tested with Ruby 1.9.3 and version 1.6.7 of the rest-client module.   Run the Ruby script as follows:   $ startstopvs.rb test vs is enabled. Disable it.   Notes  This program it is sending only the 'enabled' value to the server by creating a new  hash just this value in the 'basic' properties section.  Alternatively, the entire Virtual Server configuration could have been returned to the server with just the enabled value changed.  Sending just the data that has changed reduces the chances of overwriting another user's changes if multiple programs are concurrently accessing the RESTful API.     Read More REST API Guide in the Product Documentation Feature Brief: Traffic Manager's RESTful Control API Tech Tip: Using the RESTful Control API with Ruby Collected Tech Tips: Using the RESTful Control API  

The following code uses Stingray's RESTful API to list all the pools defined on a cluster. The code is written in Ruby. This example has more extensive comments then the following examples and most of these are applicable to all the examples. This program does a single GET request for the list of pools and then loops through that list, each element of which is a hash, and then outputs the pool name.   listpools.rb   require 'rest_client' require 'base64' require 'json' puts "Pools:\n\n" # Set the URL url = 'https://stingray.example.com:9070/api/tm/1.0/config/active/pools' # Setup the basic authorization header with the encoded Userid and Password. # These need to match a UserId and Password for a Stingray user auth = 'Basic ' + Base64.encode64('admin:admin') begin # Do the HTTP GET to get the lists of pools response = RestClient.get(url, {:authorization => auth}) data = JSON.parse(response.body) # Deserialize the JSON response into a hash pools = data['children'] pools.each do |pool| puts pool['name'] end rescue => e # We weren't able to connect to the Stingray or there was a problem with the request. # The most likely reasons for this are: # - the hostname of the Stingray instance is incorrect # - this client doesn't have network access to the Stingray instance or port 9070 # - the RESTful API is disabled # - the RESTful API is using using a different port # - the URL is incorrect puts "Error getting pool list: URL=#{url} Error: #{e.message}" end   Running the example   This code was tested with Ruby 1.9.3 and version 1.6.7 of the rest-client module.   Run the Ruby script as follows:   $ listpools.rb Pools:   Pool1 Pool2   Read More REST API Guide in the Product Documentation Feature Brief: Traffic Manager's RESTful Control API Tech Tip: Using the RESTful Control API with Ruby Collected Tech Tips: Using the RESTful Control API  

The following code uses Stingray's RESTful API to list all the pools defined for a cluster and for each pool it lists the nodes defined for that pool, including draining and disabled nodes. The code is written in Ruby. This example builds on the previous listpools.rb example.  This program does a GET request for the list of pool and then while looping through the list of pools, a GET is done for each pool to retrieve the configuration parameters for that pool.   listpoolnodes.rb   require 'rest_client' require 'base64' require 'json' puts "Pools:\n\n" url = 'https://stingray.example.com:9070/api/tm/1.0/config/active/pools' auth = 'Basic ' + Base64.encode64('admin:admin') begin # Do the HTTP GET to get the lists of pools response = RestClient.get(url, {:authorization => auth}) data = JSON.parse(response.body) pools = data['children'] pools.each do |pool| poolName = pool['name'] begin # Do the HTTP GET to get the properties of a pool response = RestClient.get(url + '/' + URI.escape(poolName), {:authorization => auth}) poolConfig = JSON.parse(response.body) # Since we are getting the properties for a pool we expect the first element to be 'properties'. # The value of the key 'properties' will be a hash containing property sections. All the properties # that this program cares about are in the 'basic' section. 'nodes' is the array of all active or # draining nodes in this pool. 'draining' the array of all draining nodes in this pool. 'disabled' # is the array of all disabled nodes in this pool. nodes = poolConfig['properties']['basic']['nodes'] draining = poolConfig['properties']['basic']['draining'] disabled = poolConfig['properties']['basic']['disabled'] puts "Pool: #{poolName}" print " Node: " nodes.each do |node| print node + ' ' end puts if draining.length > 0 print " Draining: " draining.each do |node| print node + ' ' end puts end if disabled.length > 0 print " Disabled: " disabled.each do |node| print node + ' ' end puts end puts rescue => e puts "Error getting pool data&colon; URL=#{url + '/' + URI.escape(poolName)} Error: #{e.message}" end end rescue => e puts "Error getting pool list: URL=#{url} Error: #{e.message}" end   Running the example   This code was tested with Ruby 1.9.3 and version 1.6.7 of the rest-client module.   Run the Ruby script as follows:   $ listpoolnodes.rb Pools:   Pool1     Nodes:  192.168.1.100 192.168.1.101     Draining:  192.168.1.101     Disabled:  192.168.1.102   Pool2     Nodes:  192.168.1.103 192.168.1.104   Read More REST API Guide in the Product Documentation Feature Brief: Traffic Manager's RESTful Control API Tech Tip: Using the RESTful Control API with Ruby Collected Tech Tips: Using the RESTful Control API  

The following code uses Stingray's RESTful API to delete a pool.  The code is written in Ruby.  This program deletes the "rbtest" pool created by the addpool.rb example.  To delete a resource you do a HTTP DELETE on the URI for the resource.  If the delete is successful a 204 HTTP status code will be returned.   deletepool.rb   require 'rest_client' require 'base64' require 'json' poolName = 'rbtest' url = 'https://stingray.example.com:9070/api/tm/1.0/config/active/pools/' + poolName auth = 'Basic ' + Base64.encode64('admin:admin') begin # Try to delete the pool. If it exists and is deleted we will get a 204. If it doesn't # exist we will get a 404, which will causue a resource.not_found exception response = RestClient.delete(url, {:authorization => auth}) if response.code == 204 puts "Pool #{poolName} deleted" else puts "Bad status code #{response.code} when deleting pool" end rescue => e # If a 404 is returned then e.response will be a json object, otherwise it may not be if defined?(e.response) error = JSON.parse(e.response) if error['error_id'] == 'resource.not_found' puts "Pool #{poolName} not found" else puts "Error: URL=#{url} Error: #{e.message}" end else puts "Error: URL=#{url} Error: #{e.message}" end end   Running the example   This code was tested with Ruby 1.9.3 and version 1.6.7 of the rest-client module.   Run the Ruby script as follows:   $ delelepool.rb Pool rbtest deleted   Read More REST API Guide in the Product Documentation Feature Brief: Traffic Manager's RESTful Control API Tech Tip: Using the RESTful Control API with Ruby Collected Tech Tips: Using the RESTful Control API  

The following code uses Stingray's RESTful API to add a pool.   The code is written in Ruby. This program creates a new pool, "rbtest", first doing a GET to make sure the pool doesn't already exist, and if the pool doesn't exist, the pool is created by doing a PUT with just the minimum data need to create a pool.  In this case the program creates a properties hash with just one node.  All other values will get default values when Stingray creates the pool.   addpool.rb   require 'rest_client' require 'base64' require 'json' poolName = 'rbtest' poolConfig = {'properties' => {'basic' => {'nodes' => ['192.168.168.135:80']}}} url = 'https://stingray.example.com:9070/api/tm/1.0/config/active/pools/' + poolName auth = 'Basic ' + Base64.encode64('admin:admin') begin # First see if the pool already exists. If it does exist, a 404 will returned # which will causue a resource.not_found exception response = RestClient.get(url, {:authorization => auth}) puts "Pool #{poolName} already exists" rescue => e # If a 404 is returned then e.response will be a json object, otherwise it may not be if defined?(e.response) error = JSON.parse(e.response) if error['error_id'] == 'resource.not_found' begin # PUT the new data response = RestClient.put(url, JSON.generate(poolConfig), {:content_type => :json, :authorization => auth}) if response.code == 201 # When creating a new resource we expect to get a 201 puts "Pool #{poolName} added" else puts "Bad status code #{response.code} when adding pool" end rescue => e puts "Error: URL=#{url} Error: #{e.message}" end else puts "Error: URL=#{url} Error: #{e.message}" end else puts "Error: URL=#{url} Error: #{e.message}" end end   Running the example   This code was tested with Ruby 1.9.3 and version 1.6.7 of the rest-client module.   Run the Ruby script as follows:   $ addpool.py Pool rbtest added   Notes The only difference between doing a PUT to change a resource and a PUT to add a resource is the HTTP status code returned.  When changing a resource 200 is the expected status code and when adding a resource, 201 is the expected status code.      Read More REST API Guide in the Product Documentation Feature Brief: Traffic Manager's RESTful Control API Tech Tip: Using the RESTful Control API with Ruby Collected Tech Tips: Using the RESTful Control API  

The following code uses Stingray's RESTful API to a file to the extra directory.   The code is written in Ruby.  This program adds the file 'validserialnumbers' to the extra directory and if the file already exists it will be overwrite it.  If this is not the desired behavior, code can be added to to check for the existence of the file as was done in the addpool example.   addextrafile.rb   require 'rest_client' require 'base64' require 'json' fileName = 'validserialnumbers' url = 'https://stingray.example.com:9070/api/tm/1.0/config/active/extra/' + fileName auth = 'Basic ' + Base64.encode64('admin:admin') validSerialNumbers = < 'application/octet-stream', :authorization => auth}) # If the file already exists, it will be replaced with this version and 204 will be returned # otherwise 201 will be returned. if response.code == 201 || response.code == 204 puts "File #{fileName} added" else puts "Bad status code #{response.code} when adding file #{fileName}" end rescue => e puts "Error: URL=#{url} Error: #{e.message}" end   Running the example   This code was tested with Ruby 1.9.3 and version 1.6.7 of the rest-client module.   Run the Ruby script as follows:   $ addextrafile.rb File added   Notes Since this is a file and not a configuration resource, JSON will not be used and the MIME type will be "application/octet-stream".  Another difference when dealing with files is how Stingray handles adding a file that already exists.  If the file already exists, Stingray will overwrite the it and return a HTTP status code of 204.  If the file doesn't already exist, the HTTP status code will be a 201.      Read More REST API Guide in the Product Documentation Feature Brief: Traffic Manager's RESTful Control API Tech Tip: Using the RESTful Control API with Ruby Collected Tech Tips: Using the RESTful Control API  

This article explains how to use Stingray's REST Control API using the excellent rest-client Ruby module.   You can install rest-client with gem: Windows: gem install rest-client Linux: sudo gem install rest-client   Resources   The REST API gives you access to the Stingray Configuration, presented in the form of resources.  The format of the data exchanged using the Stingray RESTful API will depend on the type of resource being accessed:   Data for Configuration Resources, such as Virtual Servers and Pools are exchanged in JSON format using the MIME type of “application/json”, so when getting data on a resource with a GET request the data will be returned in JSON format and must be deserialized or decoded into a Ruby data structure.  When adding or changing a resource with a PUT request the data must be serialized or encoded from a Ruby data structure into JSON format. Files, such as rules and those in the extra directory are exchanged in raw format using the MIME type of “application/octet-stream”.   Working with JSON and Ruby   The json module provides functions for JSON serializing and deserializing.  If this is not already installed on your system it can be installed with gem: Windows: gem install json Linux: sudo gem install json To take a Ruby data structure and serialize it into JSON format use JSON.generate() and to deserialize a JSON formatted string into a Ruby data structure use JSON.parse().   Working with a RESTful API and Ruby   To make the programming easier, the program examples that follow utilize the rest-client package as the REST client. There are methods for GET, PUT and DELETE and each must include an authorization header, replacing <userid>, <password>, <url> and <data> with the appropriate values: auth = 'Basic ' + Base64.encode64('<useid>:<password>') response = RestClient.get(<url>, {:authorization => auth}) response = RestClient.put(<url>, JSON.generate(<data>), {:content_type => :json, :authorization => auth}) response = RestClient.delete(<url>, {:authorization => auth}) The URL for Stingray RESTful API will be of the form:   https://<STM hostname or IP>:9070/api/tm/1.0/config/active/   followed by a resource type or a resource type and resource, so for example to get a list of all the pools from the Stingray instance, stingray.example.com, it would be:   https://stingray.example.com:9070/api/tm/1.0/config/active/pools   And to get the configuration information for the pool, “testpool” the URL would be:   https://stingray.example.com:9070/api/tm/1.0/config/active/pools/testpool     Data Structures   JSON responses from a GET or PUT are deserialized into a Ruby dictionary that always contains one element.   The key to this element will be:   'children' for lists of resources.  The value will be a Ruby array with each element in the array being a dictionary with the key, 'name', set to the name of the resource and the key, 'href', set to the URI of the resource. 'properties' for configuration resources.  The value will be a hash with each key value pair being a section of properties with the key being set to the name of the section and the value being a hash containing the configuration values as key/value pairs.  Configuration values can be scalars or arrays or hashes.   Please see Feature Brief: Traffic Manager's RESTful Control API for examples of these data structures and something like the Chrome REST Console can be used to see what the actual data looks like.   Read More REST API Guide in the Product Documentation Feature Brief: Traffic Manager's RESTful Control API Collected Tech Tips: Using the RESTful Control API  

The following code uses Stingray's RESTful API to enable or disabled a specific Virtual Server.   The code is written in TrafficScript.  This rule checks to see if the Virtual Server "test vs" is enabled and if it is, it disables it and if it is disabled, it enables it.  A GET is done to retrieve the configuration data for the Virtual Server and the "enabled" value in the "basic" properties section is checked.  This is a boolean value, so if it is true it is set to false and if it is false it is set to true. The changed data is then sent to the server using a PUT.  Subroutines in stmrestclient are used to do the actual RESTful API calls.  stmrestclient is attached to the article Tech Tip: Using the RESTful Control API with TrafficScript - Overview.   stmrest_startstopvs ################################################################################ # stmrest_startstopvs # # This rule toggles the enabled status of virtual server "test vs". # # To run this rule add it as a request rule to an HTTP Virtual Server and in a # browser enter the path /rest/startstopvs. # # It uses the subroutines in stmrestclient ################################################################################ import stmrestclient; if (http.getPath() != "/rest/startstopvs") break; $vs = "test vs"; $resource = "vservers/" . string.escape($vs); $accept = "json"; $html = "<br><b>Toggle the status of Virtual Server " . $vs . "</b><br><br>"; $response = stmrestclient.stmRestGet($resource, $accept); if ($response["rc"] == 1) { $vsConfig = $response["data"]; if ($vsConfig["properties"]["basic"]["enabled"]) { $vsConfig["properties"]["basic"]["enabled"] = false; } else { $vsConfig["properties"]["basic"]["enabled"] = true; } $response = stmrestclient.stmRestPut($resource, $accept, $vsConfig); if ($response["rc"] == 1) { if ($vsConfig["properties"]["basic"]["enabled"]) { $html = $html . $vs . " is Disabled. Enable it"; } else { $html = $html . $vs . " is Enabled. Disable it."; } } else { $html = $html . "There was an error updating the virtul server configuration for " . $vs . ": " . $response["info"]; } } else { if ($response["status"] == 404) { $html = $html . "Virtual Server " . $vs . " not found"; } else { $html = $html . "There was an error getting the virtul server configuration for " . $vs . ": " . $response["info"]; } } http.sendResponse("200 OK", "text/html", $html, "");   Running the example This rule should be added as a request rule to a Virtual Server and run with the URL:   http://<hostname>/rest/startstopvs test vs is enabled. Disable it.   Notes This rule it is sending only the "enabled" value to the server by creating a new hash with just this value in the "basic" properties section.  Alternatively, the entire Virtual Server configuration could have been returned to the server with just the "enabled" value changed.  Sending just the data that has changed reduces the chances of overwriting another user's changes if multiple programs are concurrently accessing the RESTful API.     Read More REST API Guide in the Product Documentation Tech Tip: Using the RESTful Control API with TrafficScript - Overview Feature Brief: Traffic Manager's RESTful Control API Collected Tech Tips: Using the RESTful Control API  

This article discusses how to use Stingray's RESTful Control API with TrafficScript, Stingray's scripting language.  The RESTful API can be accessed in a TrafficScript rule using the http.request.get(), http.request.put() and http.request.delete() functions, but to make programming easier I have taken advantage of the support in TrafficScript for subroutine libraries to create a TrafficScript REST client that contains subroutines that be can be used by TrafficScript rules and that abstract many of the RESTful API programming details.   Resources   The RESTful API gives you access to the Stingray Configuration, presented in the form of resources.  The format of the data exchanged using the Stingray RESTful API will depend on the type of resource being accessed:   Data for Configuration Resources, such as Virtual Servers and Pools are exchanged in JSON format using the MIME type “application/json”, so when getting data on a resource with a GET request the data will be returned in JSON format and must be deserialized or decoded into a TrafficScript data structure.  When adding or changing a resource with a PUT request the data must be serialized or encoded from a TrafficScript data structure into JSON format. Files, such as rules and those in the extra directory are exchanged in raw format using the MIME type “application/octet-stream”.   Working with JSON and TrafficScript   TrafficScript provides functions for JSON serializing and deserializing.  To take a TrafficScript data structure and serialize it into JSON format, use json.serialize() and to deserialize a JSON formatted string into a TrafficScript structure, use json.deserialize().   Working with the RESTful API and TrafficScript   To make the programming easier, the program examples that follow utilize the stmrestclient REST client. To use stmrestclient in a TrafficScript rule you include it with the import statement:   import stmrestclient;   The hostname of the STM to access, the base URI path and the userid and password are defined in stmrestclient and can be changed there if needed.  The default is for the hostname to be the same as the STM on which the rule is running and the userid and password are both "admin".  There are three subroutines for use in rules:   stmRestGet(resourcepath, type) stmRestPut(resourcepath, type, data) stmRestDelete(resourcepath)   resourcepath identifies the part of the URI path to the resource that needs to be added to the base URI path.  The base URI path is "/api/tm/1.0/config/active/". So for example, to get a list of pools, resourcepath would be set to "pools" or to work with the pool "testpool", resourcepath would be set to "pools/testpool", resulting in a URI path of "/api/tm/1.0/config/active/pools" and "/api/tm/1.0/config/active/pools/testpool" respectively.   type identifies the format of the data and should be set to "json", "file" or "any".  These will be translated to “application/json”, “application/octet-stream” and “application/json, application/octet-stream” respectively.   data should be a TrafficScript hash for configurations resources or a string for files.   Each subroutine returns the following hash:   rc: Return code.  1=OK, 0=Error info: "OK" if OK, and an error message if there was an error data: The data from the response.  A hash containing one element, "children" for lists or "properties" for configuration data. For files it is the file. content-type: The Content-Type header of the response, either “application/json” or “application/octet-stream” status: The HTTP response code   Data Structures   Responses that return a JSON formatted string will be deseriailized by the stmrestclient subroutines into a hash that always contains one element. The key to this element will be:   "children" for lists of resources.  The value will be an array with each element in the array being a hash with the key, "name", set to the name of the resource and the key, "href", set to the URI of the resource. "properties" for configuration resources.  The value will be a hash with each key value pair being a section of properties with the key being set to the name of the section and the value being a hash containing the configuration values as key/value pairs.  Configuration values can be scalars, arrays or hashes.   Please see Feature Brief: Traffic Manager's RESTful Control API for examples of these data structures and tools such as the Chrome REST Console can be used to see what the actual data looks like.   Example   The following rule will get a list of all pools and create a webpage listing them:   import stmrestclient; $html = "Pools: \n"; $response = stmrestclient.stmRestclient("pools", "json"); if ($response["rc"]) { $pools = $response["data"]["children"]; foreach ($pool in $pools) { $html = $html . $pool["name"] . " "; } } else { $html = $html . "There was an error getting the pool list: " . $response['info']; } http.sendResponse("200 OK", "text/html", $html, "");   stmrestclient   The TrafficScript code for the STM REST client, stmrestclient, has been attached to this article.   Read More   REST API Guide in the Product Documentation Feature Brief: Traffic Manager's RESTful Control API Collected Tech Tips: Using the RESTful Control API  

The following code uses Stingray's RESTful API to list all the pools defined for a cluster. The code is written in TrafficScript. This example has more extensive comments then the other examples and most of these are applicable to all the examples. This rule does a single GET request for the list of pools and then loops through that list, each element of which is a hash, and outputs the pool name to a web page. A subroutine in stmrestclient is used to do the actual RESTful API call.  stmrestclient is attached to the article Tech Tip: Using the RESTful Control API with TrafficScript - Overview.   stmrest_listpools   ################################################################################ # stmrest_listpools # # This rule gets the lists of pools and creates a webpage to display the list. # # To run this rule add it as a request rule to an HTTP Virtual Server and in a # browser enter the path /rest/listpools. # # It uses the subroutines in stmrestclient ################################################################################ import stmrestclient; # Only run the rule for the path /rest/listpools if (http.getPath() != "/rest/listpools") break; $resource = "pools"; # The configuration resource $accept = "json"; # The format of the response $html = "<b>Pools:</b><br><br>\n"; # Do the HTTP GET to get the lists of pools $response = stmrestclient.stmRestGet($resource, $accept); if ($response["rc"] == 1) { # Since we are getting a list of pools we expect the first element to be 'children' $pools = $response["data"]["children"]; # The value for the key 'children' will be a hash containing an array for each pool # with the key, 'name', set to the name of the pool and the key, 'href', set to the # URL of the pool foreach ($pool in $pools) { $html = $html . $pool["name"] . "<br>"; } } else { # Either the attempt to connect to the Stingray REST API failed, or the request had an # error. $response['info'] should provide some information. If The connection attempt # failed, the most likely reasons for this are that the port, username or password for # the Stingray REST API are incorrect, or the REST API is disabled. The above request # should not have an error, but the most common reason for a GET error is that the # incorrect resource is specified. $html = $html . "There was an error getting the pool list: " . $response['info']; } http.sendResponse("200 OK", "text/html", $html, "");   Running the example This rule should be added as a request rule to a Virtual Server and run with the URL:   http://<hostname>/rest/listpools   Pools: Pool1 Pool2     Read More   REST API Guide in the Product Documentation Tech Tip: Using the RESTful Control API with TrafficScript - Overview Feature Brief: Traffic Manager's RESTful Control API Collected Tech Tips: Using the RESTful Control API