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

Introduction

ZXTM’s secure, web-based admin interface gives you plenty of useful information about the performance and status of ZXTM, 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 ZXTM 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 Accessing the Control API from Java to create an appropriate ZXTM-API.jar file. Upload this interface file to the Java Extensions catalog in the ZXTM admin interface, and ensure that the required dependencies are also installed in the ZXTM system.

The Java Extension

The Java Extension is quite long; you can shortcut building it from source by downloading a pre-compiled ServerStatus.jar file and uploading it straight to the Java Extensions catalog in ZXTM.

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

Compiling the extension

If you want to compile (or modify) the extension, take note of the following points:

• At compilation time, the extension will require the ZXTM-API.jar file for type checking. For example, if you use the Eclipse IDE, you should add the ZXTM-API.jar file as an 'External Jar' in the build path.
• The extension will compile to several separate class files. You can upload each class file to the ZXTM 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.

Using the ServerStatus Java Extension

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:

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 ZXTM Admin Interface.

The extension then attempts to connect to the local ZXTM’s 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 ZXTM to host the extension. The extension will return identical results no matter which virtual server it is invoked from.

Owen Garrett [Zeus Dev Team] 25 September 2008