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.
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.
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 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.
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
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
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:
... 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:
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.
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.