vADC Docs

Stingray Status - Using the Control API from a Java Extension

by on ‎03-21-2013 04:49 AM - edited on ‎07-06-2015 02:18 PM by PaulWallace (513 Views)

This article combines two Stingray technologies – Java Extensions and the Control API – and shows you how to query the status of Stingray with a simple, authenticated web request to generate an immediate status report.

 

Introduction

 

Stingray’s admin interface gives you plenty of useful information about the performance and health of Stingray, but sometimes you may want a lighter, quicker way of checking the status. Apache's ServerStatus page is a good model of a report that you can access from within a public website using a privileged URL.

 

This article presents a Java Extension that generates a similar report. The Java Extension is run when a particular URL is requested and appropriate authentication is given; the extension queries Stingray via the SOAP-based Control API and retrieves a range of status information and a list of the recently-processed connections.

 

Before you proceed

 

First, follow the instructions in the article Using Stingray's SOAP Control API with Java to create an appropriate Stingray-API.jar file. Upload this interface file to the Java Extensions catalog in the Stingray admin interface, and ensure that all of the the required dependencies are also installed in the Java catalog.

 

The Java Extension

 

The attached Java Extension source file (ServerStatus.java) is quite long; you can shortcut building it from source by using the attached ServerStatus.jar file and uploading it straight to the Java Extensions catalog in Stingray.

 

Compiling the extension

 

At compilation time, the extension will require the Stingray-API.jar and Apache Axis 1.4 jar files for type checking. For example, if you use the Eclipse IDE, you should add these files as 'External Jars' in the build path.  From the command line:

 

$ javac -cp Stingray-API.jar:zxtm-servlet.jar:servlet.jar:axis-1_4/lib/* ServerStatus.java

 

The extension compiles to several separate class files. You can upload each class file to the JAva catalog, or you can use the 'Export' command (in Eclipse) to create a Java jar file containing the compiled class files from the ServerStatus project. From the command line:

 

$ jar -cvf ServerStatus.jar ServerStatus*.class

 

 

Using the ServerStatus Java Extension

 

The ServerStatus java extension prompts for a username and password; provide the username and password for the 'admin' user in the Stingray Admin Interface.

 

Use the following RuleBuilder request rule to invoke the extension:

 

serverstatusrb.png

 

... or the equivalent TrafficScript rule:

 

$path = http.getPath();  
if( $path == "/serverstatus" ) java.run( "ServerStatus" );  

 

Then, go to http://www.site.com/serverstatus to run the extension:

Screen Shot 2013-03-21 at 11.10.49.png

Security

 

The extension first checks that the HTTP request that has invoked it contains a username and password. If the username and password is missing, the extension returns a '401 Authenticate' message to prompt the caller to provide them. The caller should provide the username and password for the 'admin' user in the Stingray Admin Interface.

 

The extension then attempts to connect to the local Stingray Control API interface using the supplied username/password pair. If the connection fails because the authentication details are invalid, the extension again prompts for a new username and password.

 

Use SSL!

 

When you provide the admin user and password, it’s very advisable to only do so over an SSL-enabled website. You can ensure that the user name and password is never requested by a non-SSL site by modifying the rule as follows:

 

$path = http.getPath();  
if( $path == "/serverstatus" && ssl.isSSL() )  
   java.run( "ServerStatus" );  

 

If necessary, configure a special SSL virtual server in Stingray to host the extension. The extension will return identical results no matter which virtual server it is invoked from.

 

Read more

 

Contributors