As discussed in Part 1, SOAP Configuration Management (SOMA) is a SOAP-based interface provided by the appliance. These interfaces are language independent, and therefore, can be exposed from any client that supports SOAP/HTTP. There are two such methods for demonstration, cURL-based monitoring and Java-based monitoring. Based on your choice, environment, and other factors, you can use this article to implement various client types. We will explore the installation, configuration, and invocation perspectives on both aspects of monitoring. For details about the concept of SOMA, refer to Part 1 of the series.
cURL based monitoring
cURL is a client side library that you can install on UNIX or Windows®, which is explained in Part 1. You can access the DataPower box via cURL to perform monitoring as well as administrative tasks (see Listing 1 and Listing 2).
Listing 1. Example of a cURL request command with options
curl –k –u user:password –d @myRequestFile.xml https://ipaddress:Port/EndpointURI
Listing 2. Another example of a cURL request command with options
curl –insecure –u user:password –d @myRequestFile.xml https://ipaddress:Port/EndpointURI
Options for the cURL command are:
- insecure or k: This ignores the secure connection (SSL connections without certificate).
- u: This specifies the user and password
- d: This indicates HTTP post data.
- @: This specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device and the port the XML Management is running on.
- Endpoint URI of the current version: service/mgmt/current
You can view or update the port for SOMA (if required) as shown in Figure 1, which you can access by logging in to the default domain on the DataPower appliance (one of the generic approaches).
Figure 1. XML Management Interface configuration
To configure cURL on any machine, you need to install the cURL library. To install cURL, you need a binary package of it that you can download.
Installing binary packages on UNIX
A normal UNIX installation is done in three or four steps (after unpacking the source archive). The sample installation procedure is shown in Listing 3. For more details about the cURL installation options, refer to the product documentation.
Listing 3. Sample install procedure
cd /usr/local/src wget http://curl.haxx.se/download/curl-7.19.0.tar.gz tar zxf curl-7.19.0.tar.gz cd curl-7.19.0 ./configure --prefix=/usr/local --with-ssl=/usr/include/openssl make make install
In Java-based monitoring, create an HTTPS Java client to call SOMA through the XML interface. The configuration of the interface is explained in the next section. Standard request XMLs are used by the Java client to fetch the status of the requested service. The request and response formats are the same for both approaches.
Java client configuration
To configure a Java client, set up a Java HTTPS client to make a call to the SOMA service of the device using its IP address and the port of the XML Management Interface.
Invocation of SOMA using cURL and Java
Different objects of DataPower appliance are monitored by changing the class attribute of the <dp:get-status> element.
For example, to get the system usage status of the box, refer to the <dp:get-status> element with the class SystemUsage in the request message (Listing 4).
Listing 4. GetSystemUsage_Req.xml
<?xml version=\"1.0\" encoding=\"UTF-8\"?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Body> <dp:request xmlns:dp="http://www.datapower.com/schemas/management"> <dp:get-status class="SystemUsage"/> </dp:request> </env:Body> </env:Envelope>
Refer to <dp:get-status> in the response message (Listing 5). It indicates that the operation has performed successfully and the corresponding class elements can be obtained. The example underneath demonstrates the elements, such as Interval, Load, and Worklist of SystemUsage.
Listing 5. Response GetSystemUsage_Resp.xml
<?xml version=\"1.0\" encoding=\"UTF-8\"?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Body> <dp:response xmlns:dp="http://www.datapower.com/schemas/management"> <dp:timestamp>2012-03-02T13:52:02+05:30</dp:timestamp> <dp:status> <SystemUsage xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <Interval>1000</Interval> <Load>47</Load> <WorkList>2</WorkList> </SystemUsage> </dp:status> </dp:response> </env:Body> </env:Envelope>
Invocation using cURL
To get the system usage status of the box, the cURL command invokes the SOMA service using the input request "XML GetSystemUsage_Req.xml" and gets the response from the DataPower device in "GetSystemUsage_Resp.xml" as shown in Listing 6.
Listing 6. Response GetSystemUsage_Resp.xml
curl --insecure --data-binary @GetSystemUsage_Req.xml -u user:password https://10.1.1.1:9550/service/mgmt/current > GetSystemUsage_Resp.xml
Invocation using Java
A Java HTTPS client invokes the SOMA service by sending the input SOAP as a request and gets a response back from the DataPower device. Make sure the client is HTTPS and not HTTP. There is a requisite while developing a HTTPS client and that is to manage the certificate. Listing 7 shows an example of HTTPS. This class is used to invoke the XML Management Interface over HTTPS.
Listing 7. Example of HTTPS
String ip = "127.0.0.1"; // ipaddress of DataPower device int port = 9550; // SOMA port number String user = "admin"; String pass = "password"; HTTPSClient httpsCleintObj = new HTTPSClient(ip, port, user, pass); httpsCleintObj.connect(true); String environmentalSensorsReq = "<env:Envelope"+ "xmlns:env=\"http://schemas.xmlsoap.org/soap/envelope/\"><env:Body><dp:request"+ "xmlns:dp=\"http://www.datapower.com/schemas/management\"><dp:get-status"+ "class=\"EnvironmentalSensors\"/></dp:request></env:Body></env:Envelope>"; String environmentalSensorsResp =httpsCleintObj.sendMessage(environmentalSensorsReq); System.out.println("Response from Datapower device:"+environmentalSensorsResp); httpsCleintObj.releaseConnection();
For a detailed description, see the files that are available in the Download section of the article.
Understanding the request and response structures
The request and response structures are always the same for cURL and Java-based monitoring for any client build up.
One of the basic request types is shown in Listing 8 for the default domain.
Listing 8. Basic request type
<?xml version=\"1.0\" encoding=\"UTF-8\"?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Body> <dp:request xmlns:dp="http://www.datapower.com/schemas/management"> <dp:get-status class="EnvironmentalSensors"/> </dp:request> </env:Body> </env:Envelope>
To get the status of different objects, change the attribute class value in the <dp:get-status> element according to the object class value.
For example, to get the memory status, the input request element has this
‘MemoryStatus’ <dp:get-status class="MemoryStatus".
To get the domain status, the input request element has this class value:
‘DomainStatus’ <dp:get-status class="DomainStatus".
Depending upon the class value used in the request, the response xmls contains the corresponding elements inside the <dp:status> element. These are either a singular or multiple repetitive elements according to your class value. For example, the output for memory usage is singular, whereas the domain status has multiple elements corresponding to the domains that exist in the DataPower appliance.
The output needs to be parsed to fetch the appropriate metrics for further usage according to the monitoring requirements. Listing 9 shows an example of the response for the environment sensors.
Listing 9. Response for the environment sensors
<?xml version="1.0" encoding="UTF-8"?> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Body> <dp:response xmlns:dp="http://www.datapower.com/schemas/management"> <dp:timestamp>2012-03-02T15:01:20+05:30</dp:timestamp> <dp:status> <EnvironmentalSensors xmlns:env="http://www.w3.org/2003/05/soap-envelope"> <systemTemp>0</systemTemp> <cpu1Temp>31</cpu1Temp> <cpu2Temp>30</cpu2Temp> <cpu1rpm>0</cpu1rpm> <cpu2rpm>0</cpu2rpm> <chassis1rpm>0</chassis1rpm> <chassis2rpm>0</chassis2rpm> <chassis3rpm>0</chassis3rpm> <caseopen>no</caseopen> <volt33>3.36</volt33> <volt5>5.08</volt5> <volt12>11.5</volt12> <powersupply>ok</powersupply> <batteryinstalldate>Thu Jan 1 05:29:59 1970 </batteryinstalldate> <checkintrusion>yes</checkintrusion> </EnvironmentalSensors> </dp:status> </dp:response> </env:Body> </env:Envelope>
This article series highlighted the different monitoring approaches for WebSphere DataPower appliances. Part 3, the last in this series, demonstrated the practical usage of the concepts and solution introduced in Part 1 by using the SOMA interface. You learned the high level requirements and complexity involved in using the SOMA interface.
The authors would like to thank Rakesh R. Nair for his review of the article series. Rakesh is a WebSphere DataPower specialist and has led many DataPower-based engagements for worldwide customers.
|Sample Java classes||JavaClient.zip||5KB|
|Sample request XML||GetDomainStatus_Req.zip||1KB|
|Sample response XML||GetDomainStatus_Response.zip||1KB|
- WebSphere DataPower product page
- IBM Tivoli Monitoring suite
- IBM Redbook: XML Management Interface
- cURL library
- developerWorks WebSphere DataPower SOA Appliances resource page